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.