README.rst
1.. SPDX-License-Identifier: GPL-3.0-or-later
2
3.. _mod-hints:
4
5Static hints
6============
7
8This is a module providing static hints for forward records (A/AAAA) and reverse records (PTR).
9The records can be loaded from ``/etc/hosts``-like files and/or added directly.
10
11You can also use the module to change the root hints; they are used as a safety belt or if the root NS
12drops out of cache.
13
14.. tip::
15
16 For blocking large lists of domains please use :func:`policy.rpz`
17 instead of creating huge list of domains with IP address *0.0.0.0*.
18
19Examples
20--------
21
22.. code-block:: lua
23
24 -- Load hints after iterator (so hints take precedence before caches)
25 modules = { 'hints > iterate' }
26 -- Add a custom hosts file
27 hints.add_hosts('hosts.custom')
28 -- Override the root hints
29 hints.root({
30 ['j.root-servers.net.'] = { '2001:503:c27::2:30', '192.58.128.30' }
31 })
32 -- Add a custom hint
33 hints['foo.bar'] = '127.0.0.1'
34
35.. note:: The :ref:`policy <mod-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.
36 That can be worked around e.g. by explicit :any:`policy.PASS` action.
37
38Properties
39----------
40
41.. function:: hints.config([path])
42
43 :param string path: path to hosts-like file, default: no file
44 :return: ``{ result: bool }``
45
46 Clear any configured hints, and optionally load a hosts-like file as in ``hints.add_hosts(path)``.
47 (Root hints are not touched.)
48
49.. function:: hints.add_hosts([path])
50
51 :param string path: path to hosts-like file, default: ``/etc/hosts``
52
53 Add hints from a host-like file.
54
55.. function:: hints.get(hostname)
56
57 :param string hostname: i.e. ``"localhost"``
58 :return: ``{ result: [address1, address2, ...] }``
59
60 Return list of address record matching given name.
61 If no hostname is specified, all hints are returned in the table format used by ``hints.root()``.
62
63.. function:: hints.set(pair)
64
65 :param string pair: ``hostname address`` i.e. ``"localhost 127.0.0.1"``
66 :return: ``{ result: bool }``
67
68 Add a hostname--address pair hint.
69
70 .. note::
71
72 If multiple addresses have been added for a name (in separate ``hints.set()`` commands),
73 all are returned in a forward query.
74 If multiple names have been added to an address, the last one defined is returned
75 in a corresponding PTR query.
76
77.. function:: hints.del(pair)
78
79 :param string pair: ``hostname address`` i.e. ``"localhost 127.0.0.1"``, or just ``hostname``
80 :return: ``{ result: bool }``
81
82 Remove a hostname - address pair hint. If address is omitted, all addresses for the given name are deleted.
83
84.. function:: hints.root_file(path)
85
86 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.
87
88.. function:: hints.root(root_hints)
89
90 :param table root_hints: new set of root hints i.e. ``{['name'] = 'addr', ...}``
91 :return: ``{ ['a.root-servers.net.'] = { '1.2.3.4', '5.6.7.8', ...}, ... }``
92
93 Replace current root hints and return the current table of root hints.
94
95 .. tip:: If no parameters are passed, it only returns current root hints set without changing anything.
96
97 Example:
98
99 .. code-block:: lua
100
101 > hints.root({
102 ['l.root-servers.net.'] = '199.7.83.42',
103 ['m.root-servers.net.'] = '202.12.27.33'
104 })
105 [l.root-servers.net.] => {
106 [1] => 199.7.83.42
107 }
108 [m.root-servers.net.] => {
109 [1] => 202.12.27.33
110 }
111
112 .. 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.
113
114.. function:: hints.use_nodata(toggle)
115
116 :param bool toggle: true if enabling NODATA synthesis, false if disabling
117 :return: ``{ result: bool }``
118
119 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).
120
121.. function:: hints.ttl([new_ttl])
122
123 :param int new_ttl: new TTL to set (optional)
124 :return: the TTL setting
125
126 This function allows to read and write the TTL value used for records generated by the hints module.
127
128