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