1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
.. SPDX-License-Identifier: GPL-3.0-or-later
.. _mod-hints:
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 :func:`policy.rpz`
instead of creating huge list of domains with IP address *0.0.0.0*.
Examples
--------
.. code-block:: lua
-- 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 :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.
That can be worked around e.g. by explicit :any:`policy.PASS` action.
Properties
----------
.. function:: hints.config([path])
:param string path: path to hosts-like file, default: no file
:return: ``{ result: bool }``
Clear any configured hints, and optionally load a hosts-like file as in ``hints.add_hosts(path)``.
(Root hints are not touched.)
.. function:: hints.add_hosts([path])
:param string path: path to hosts-like file, default: ``/etc/hosts``
Add hints from a host-like file.
.. function:: hints.get(hostname)
:param string hostname: i.e. ``"localhost"``
:return: ``{ 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()``.
.. function:: hints.set(pair)
:param string pair: ``hostname address`` i.e. ``"localhost 127.0.0.1"``
:return: ``{ 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.
.. function:: hints.del(pair)
:param string pair: ``hostname address`` i.e. ``"localhost 127.0.0.1"``, or just ``hostname``
:return: ``{ result: bool }``
Remove a hostname - address pair hint. If address is omitted, all addresses for the given name are deleted.
.. function:: 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.
.. function:: hints.root(root_hints)
:param table root_hints: new set of root hints i.e. ``{['name'] = 'addr', ...}``
:return: ``{ ['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:
.. code-block:: lua
> 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.
.. function:: hints.use_nodata(toggle)
:param bool toggle: true if enabling NODATA synthesis, false if disabling
:return: ``{ 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).
.. function:: hints.ttl([new_ttl])
:param int new_ttl: new TTL to set (optional)
:return: the TTL setting
This function allows to read and write the TTL value used for records generated by the hints module.
|
