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 fallback addresses for the root servers.
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, so your hints might get surprisingly shadowed by even default policies.
That most often happens for RFC 6761 Section 6 names, e.g.
localhost
and test
or with PTR
records in private address ranges.
To unblock the required names, you may use an explicit policy.PASS
action.
policy.add(policy.suffix(policy.PASS, {todname('1.168.192.in-addr.arpa')}))
This .PASS
workaround isn’t ideal. To improve some cases,
we recommend to move these .PASS
lines to the end of your rule list.
The point is that applying any non-chain action
(e.g. forwarding actions or .PASS
itself)
stops processing any later policy rules for that request (including the default block-rules).
You probably don’t want this .PASS
to shadow any other rules you might have;
and on the other hand, if any other non-chain rule triggers,
additional .PASS
would not change anything even if it were somehow force-executed.
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.
These root hints are only used as fallback when addresses of
NS .
aren’t available, e.g. when cache is completely clear.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 }
- 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).
The setting is (now) per-entry, so you want to set it before any address-name pairs.
- 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.
The setting is (now) per-entry, so you want to set it before any address-name pairs.