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 justhostname
- 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.