# Static hints

This is a module providing static hints for forward records (A/AAAA) and reverse records (PTR). The records can be loaded from `/etc/hosts`-like files and/or added directly.

You can also use the module to change fallback addresses for the root servers.

Tip

For blocking large lists of domains please use `policy.rpz()` instead of creating huge list of domains with IP address 0.0.0.0.

## Examples

    -- Load hints after iterator (so hints take precedence before caches)
    modules = { 'hints > iterate' }
    -- Add a custom hosts file
    hints.add_hosts('hosts.custom')
    -- Override the root hints
    hints.root({
      ['j.root-servers.net.'] = { '2001:503:c27::2:30', '192.58.128.30' }
    })
    -- Add a custom hint
    hints['foo.bar'] = '127.0.0.1'

Note

The policy module applies before hints, so your hints might get surprisingly shadowed by even default policies.

That most often happens for RFC 6761 Section 6 names, e.g. `localhost` and `test` or with `PTR` records in private address ranges. To unblock the required names, you may use an explicit `policy.PASS` action.

    policy.add(policy.suffix(policy.PASS, {todname('1.168.192.in-addr.arpa')}))

This `.PASS` workaround isn’t ideal. To improve some cases, we recommend to move these `.PASS` lines to the end of your rule list. The point is that applying any non-chain action (e.g. forwarding actions or `.PASS` itself) stops processing any later policy rules for that request (including the default block-rules). You probably don’t want this `.PASS` to shadow any other rules you might have; and on the other hand, if any other non-chain rule triggers, additional `.PASS` would not change anything even if it were somehow force-executed.

## Properties

hints.config([path])
  Parameters:

    path (string) – path to hosts-like file, default: no file

  Returns:

    `{ result: bool }`

  Clear any configured hints, and optionally load a hosts-like file as in `hints.add_hosts(path)`. (Root hints are not touched.)

hints.add_hosts([path])
  Parameters:

    path (string) – path to hosts-like file, default: `/etc/hosts`

  Add hints from a host-like file.

hints.get(hostname)
  Parameters:

    hostname (string) – i.e. `"localhost"`

  Returns:

    `{ result: [address1, address2, ...] }`

  Return list of address record matching given name. If no hostname is specified, all hints are returned in the table format used by `hints.root()`.

hints.set(pair)
  Parameters:

    pair (string) – `hostname address` i.e. `"localhost 127.0.0.1"`

  Returns:

    `{ result: bool }`

  Add a hostname–address pair hint.

  Note

  If multiple addresses have been added for a name (in separate `hints.set()` commands), all are returned in a forward query. If multiple names have been added to an address, the last one defined is returned in a corresponding PTR query.

hints.del(pair)
  Parameters:

    pair (string) – `hostname address` i.e. `"localhost 127.0.0.1"`, or just `hostname`

  Returns:

    `{ result: bool }`

  Remove a hostname - address pair hint. If address is omitted, all addresses for the given name are deleted.

hints.root_file(path)

  Replace current root hints from a zonefile. If the path is omitted, the compiled-in path is used, i.e. the root hints are reset to the default.

hints.root(root_hints)
  Parameters:

    root_hints (table) – new set of root hints i.e. `{['name'] = 'addr', ...}`

  Returns:

    `{ ['a.root-servers.net.'] = { '1.2.3.4', '5.6.7.8', ...}, ... }`

  Replace current root hints and return the current table of root hints.

  These root hints are only used as fallback when addresses of `NS .` aren’t available, e.g. when cache is completely clear.

  Tip

  If no parameters are passed, it only returns current root hints set without changing anything.

  Example:

      > hints.root({
        ['l.root-servers.net.'] = '199.7.83.42',
        ['m.root-servers.net.'] = '202.12.27.33'
      })
      [l.root-servers.net.] => {
        [1] => 199.7.83.42
      }
      [m.root-servers.net.] => {
        [1] => 202.12.27.33
      }

hints.use_nodata(toggle)
  Parameters:

    toggle (bool) – true if enabling NODATA synthesis, false if disabling

  Returns:

    `{ result: bool }`

  If set to true (the default), NODATA will be synthesised for matching hint name, but mismatching type (e.g. AAAA query when only A hint exists).

hints.ttl([new_ttl])
  Parameters:

    new_ttl (int) – new TTL to set (optional)

  Returns:

    the TTL setting

  This function allows to read and write the TTL value used for records generated by the hints module.