From: Vladimír Čunát Date: Thu, 23 Dec 2021 10:11:12 +0000 (+0100) Subject: hints docs: better explain shadowing by policies X-Git-Tag: v5.5.0~20^2 X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=3e4974e540236b284db02b01792e09434c11e5ff;p=thirdparty%2Fknot-resolver.git hints docs: better explain shadowing by policies --- diff --git a/modules/hints/README.rst b/modules/hints/README.rst index 65bebaa16..97d24ddc6 100644 --- a/modules/hints/README.rst +++ b/modules/hints/README.rst @@ -32,8 +32,26 @@ Examples -- Add a custom hint hints['foo.bar'] = '127.0.0.1' -.. note:: The :ref:`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. +.. 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 ----------