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

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.