.. 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 ` 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 ` (e.g. :ref:`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 ---------- .. 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.