Mention pdns.DROP is old in all places relevant and add refs to make the callback...

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 91b0d1bf5c00456971fc8ae0f9bde0ad0ef4c78d..a2c3655113a57768816d7a9d916dcb54b268737d 100644 (file)
--- 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 1fe3ba3f3c90474ae2fadbcc27748eb7b0c16068..75c428b0769e4bcf97d3bb71ee6e6de4ffb08342 100644 (file)
--- 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 9851323dc29a5dfe4441a79ff246818ac077a981..e90c467732fa655235cb4764efc60c19989e0966 100644 (file)
--- 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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^