From 3e4974e540236b284db02b01792e09434c11e5ff Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20=C4=8Cun=C3=A1t?= Date: Thu, 23 Dec 2021 11:11:12 +0100 Subject: [PATCH] hints docs: better explain shadowing by policies --- modules/hints/README.rst | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) 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 ---------- -- 2.47.2