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.

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.