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 the root hints; they are used as a safety belt or if the root NS drops out of cache.

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, meaning e.g. that hints for special names (RFC 6761#section-6) like localhost or test will get shadowed by policy rules by default. That can be worked around e.g. by explicit policy.PASS action.

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.

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
}

Tip

A good rule of thumb is to select only a few fastest root hints. The server learns RTT and NS quality over time, and thus tries all servers available. You can help it by preselecting the candidates.

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.