From: Charles-Henri Bruyand <charles-henri.bruyand@open-xchange.com>
Date: Mon, 19 Mar 2018 10:16:30 +0000 (+0100)
Subject: improve documentation of addLuaAction and addLuaResponseAction
X-Git-Tag: dnsdist-1.3.0~46^2~5
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=fbd6b779245b32f6db02a85ac0e6430ec2477737;p=thirdparty%2Fpdns.git

improve documentation of addLuaAction and addLuaResponseAction
---

diff --git a/pdns/dnsdistdist/docs/reference/constants.rst b/pdns/dnsdistdist/docs/reference/constants.rst
index 38b994d8cc..5adcdd1e8f 100644
--- a/pdns/dnsdistdist/docs/reference/constants.rst
+++ b/pdns/dnsdistdist/docs/reference/constants.rst
@@ -73,7 +73,7 @@ DNS Section
 DNSAction
 ---------
 
-These constants represent an Action that can be returned from the functions invoked by :func:`addLuaAction` and :func:`addLuaResponseAction`.
+These constants represent an Action that can be returned from the functions invoked by :func:`addLuaAction`.
 
  * ``DNSAction.Allow``: let the query pass, skipping other rules
  * ``DNSAction.Delay``: delay the response for the specified milliseconds (UDP-only), continue to the next rule
@@ -83,4 +83,21 @@ These constants represent an Action that can be returned from the functions invo
  * ``DNSAction.Nxdomain``: return a response with a NXDomain rcode
  * ``DNSAction.Pool``: use the specified pool to forward this query
  * ``DNSAction.Refused``: return a response with a Refused rcode
+ * ``DNSAction.ServFail``: return a response with a ServFail rcode
  * ``DNSAction.Spoof``: spoof the response using the supplied IPv4 (A), IPv6 (AAAA) or string (CNAME) value
+ * ``DNSAction.Truncate``: truncate the response
+
+
+.. _DNSResponseAction:
+
+DNSResponseAction
+-----------------
+
+These constants represent an Action that can be returned from the functions invoked by :func:`addLuaResponseAction`.
+
+ * ``DNSResponseAction.Allow``: let the query pass, skipping other rules
+ * ``DNSResponseAction.Delay``: delay the response for the specified milliseconds (UDP-only), continue to the next rule
+ * ``DNSResponseAction.Drop``: drop the query
+ * ``DNSResponseAction.HeaderModify``: indicate that the query has been turned into a response
+ * ``DNSResponseAction.None``: continue to the next rule
+ * ``DNSResponseAction.ServFail``: return a response with a ServFail rcode
diff --git a/pdns/dnsdistdist/docs/rules-actions.rst b/pdns/dnsdistdist/docs/rules-actions.rst
index 33da71a9e3..d05f0b6009 100644
--- a/pdns/dnsdistdist/docs/rules-actions.rst
+++ b/pdns/dnsdistdist/docs/rules-actions.rst
@@ -150,7 +150,9 @@ Rule Generators
 
   Invoke a Lua function that accepts a :class:`DNSQuestion`.
   This function works similar to using :func:`LuaAction`.
-  The ``function`` should return a :ref:`DNSAction`. If the Lua code fails, ServFail is returned.
+  The ``function`` should return both a :ref:`DNSAction` and its argument `rule`. The `rule` is used as an argument
+  of the following :ref:`DNSAction`: `DNSAction.Spoof`, `DNSAction.Pool` and `DNSAction.Delay`. As of version `1.3.0`, you can
+  ommit the argument. For earlier releases, simply return an empty string. If the Lua code fails, ServFail is returned.
 
   :param DNSRule: match queries based on this rule
   :param string function: the name of a Lua function
@@ -160,6 +162,20 @@ Rule Generators
 
   * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
 
+  ::
+
+    function luarule(dq)
+      if(dq.qtype==35) -- NAPTR
+      then
+        return DNSAction.Pool, "abuse" -- send to abuse pool
+      else
+        return DNSAction.None, ""      -- no action
+        -- return DNSAction.None       -- as of dnsdist version 1.3.0
+      end
+    end
+
+    addLuaAction(AllRule(), luarule)
+
 .. function:: addLuaResponseAction(DNSrule, function [, options])
 
   .. versionchanged:: 1.3.0
@@ -167,7 +183,9 @@ Rule Generators
 
   Invoke a Lua function that accepts a :class:`DNSResponse`.
   This function works similar to using :func:`LuaResponseAction`.
-  The ``function`` should return a :ref:`DNSResponseAction`. If the Lua code fails, ServFail is returned.
+  The ``function`` should return both a :ref:`DNSResponseAction` and its argument `rule`. The `rule` is used as an argument
+  of the `DNSResponseAction.Delay`. As of version `1.3.0`, you can ommit the argument (see :func:`addLuaAction`). For earlier
+  releases, simply return an empty string. If the Lua code fails, ServFail is returned.
 
   :param DNSRule: match queries based on this rule
   :param string function: the name of a Lua function