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.
- path (string) – path to hosts-like file, default:
-
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()
.- hostname (string) – i.e.
-
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.- pair (string) –
-
hints.del
(pair)¶ Parameters: - pair (string) –
hostname address
i.e."localhost 127.0.0.1"
, or justhostname
Returns: { result: bool }
Remove a hostname - address pair hint. If address is omitted, all addresses for the given name are deleted.
- pair (string) –
-
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.
- root_hints (table) – new set of root hints i.e.
-
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.