summaryrefslogtreecommitdiffstats
path: root/modules/hints/README.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--modules/hints/README.rst145
1 files changed, 145 insertions, 0 deletions
diff --git a/modules/hints/README.rst b/modules/hints/README.rst
new file mode 100644
index 0000000..97d24dd
--- /dev/null
+++ b/modules/hints/README.rst
@@ -0,0 +1,145 @@
+.. 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,
+ 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 :any:`policy.PASS` action.
+
+ .. code-block:: lua
+
+ 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 :ref:`non-chain action <mod-policy-actions>`
+ (e.g. :ref:`forwarding actions <forwarding>` 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
+----------
+
+.. 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.
+