From: Otto Moerbeek Date: Fri, 4 Feb 2022 08:30:56 +0000 (+0100) Subject: Mention pdns.DROP is old in all places relevant and add refs to make the callback... X-Git-Tag: auth-4.7.0-alpha1~20^2~4 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=9e4411009ea77c2e141fc98ca232b95f4dbcb3fe;p=thirdparty%2Fpdns.git Mention pdns.DROP is old in all places relevant and add refs to make the callback semantics section easier to find. Also add upgrade note. --- diff --git a/pdns/recursordist/docs/lua-scripting/dq.rst b/pdns/recursordist/docs/lua-scripting/dq.rst index 91b0d1bf5c..a2c3655113 100644 --- a/pdns/recursordist/docs/lua-scripting/dq.rst +++ b/pdns/recursordist/docs/lua-scripting/dq.rst @@ -39,8 +39,8 @@ The DNSQuestion object contains at least the following fields: .. attribute:: DNSQuestion.rcode - current DNS Result Code, which can be overridden, including to several magical values - The rcode can be set to ``pdns.DROP`` to drop the query. + current DNS Result Code, which can be overridden, including to several magical values. + Before 4.4.0, the rcode can be set to ``pdns.DROP`` to drop the query, for later versions refer to :ref:`hooksemantics`. Other statuses are normal DNS return codes, like ``pdns.NOERROR``, ``pdns.NXDOMAIN`` etc. .. attribute:: DNSQuestion.isTcp diff --git a/pdns/recursordist/docs/lua-scripting/hooks.rst b/pdns/recursordist/docs/lua-scripting/hooks.rst index 1fe3ba3f3c..75c428b076 100644 --- a/pdns/recursordist/docs/lua-scripting/hooks.rst +++ b/pdns/recursordist/docs/lua-scripting/hooks.rst @@ -211,13 +211,15 @@ Interception Functions :param :class:`PolicyEvent` event: The event to handle -Semantics -^^^^^^^^^ -The `ipfilter` and `preresolve` must return ``true`` if they have taken over the query and wish that the nameserver should not proceed with its regular query-processing. + .. _hooksemantics: + +Callback Semantics +^^^^^^^^^^^^^^^^^^ +The :func:`ipfilter` and :func:`preresolve` callbacks must return ``true`` if they have taken over the query and wish that the nameserver should not proceed with processing. When a function returns ``false``, the nameserver will process the query normally until a new function is called. If a function has taken over a request, it should set an rcode (usually 0), and specify a table with records to be put in the answer section of a packet. -An interesting rcode is NXDOMAIN (3, or ``pdns.NXDOMAIN``), which specifies the non-existence of a domain. +An interesting rcode is `NXDOMAIN` (3, or ``pdns.NXDOMAIN``), which specifies the non-existence of a domain. The :func:`ipfilter` and :func:`preoutquery` hooks are different, in that :func:`ipfilter` can only return a true of false value, and that :func:`preoutquery` can also set rcode -3 to signify that the whole query should be terminated. @@ -241,8 +243,8 @@ A minimal sample script: **Warning**: Please do NOT use the above sample script in production! Responsible NXDomain redirection requires more attention to detail. -Useful 'rcodes' include 0 for "no error" and ``pdns.NXDOMAIN`` for "NXDOMAIN". Before 4.4.0, ``pdns.DROP`` can also be used to drop the question without any further processing. -Such a drop is accounted in the 'policy-drops' metric. +Useful ``rcodes`` include 0 or ``pdns.NOERROR`` for no error and ``pdns.NXDOMAIN`` for ``NXDOMAIN``. Before 4.4.0, ``pdns.DROP`` can also be used to drop the question without any further processing. +Such a drop is accounted in the ``policy-drops`` metric. Starting with recursor 4.4.0, the method to drop a request is to set the ``dq.appliedPolicy.policyKind`` to the value ``pdns.policykinds.Drop``. @@ -257,7 +259,7 @@ Starting with recursor 4.4.0, the method to drop a request is to set the ``dq.ap return false end -**Note**: to drop a query from ``preresolve``, set ``policyKind`` and return false, to indicate the Recursor should process the Drop action. +**Note**: to drop a query set ``policyKind`` and return ``false``, to indicate the Recursor should process the ``Drop`` action. DNS64 ----- diff --git a/pdns/recursordist/docs/upgrade.rst b/pdns/recursordist/docs/upgrade.rst index 9851323dc2..e90c467732 100644 --- a/pdns/recursordist/docs/upgrade.rst +++ b/pdns/recursordist/docs/upgrade.rst @@ -114,6 +114,10 @@ To conform better to the standard, RPZ processing has been modified. This has consequences for the points in the resolving process where matches are checked and callbacks are called. See :ref:`rpz` for details. Additionally a new type of callback has been introduced: :func:`policyEventFilter`. +Dropping queries from Lua callbacks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The method to drop a query from a Lua callback has been changed. +Previously, you could set `rcode` to `pdns.DROP`. See :ref:`hooksemantics` for the new method. Parsing of unknown record types ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^