dnsdist: Document that `add*DynBlocks()` methods are legacy ones

(cherry picked from commit a53e079749c0472c0187c4e7f5ac57408165786d)

diff --git a/pdns/dnsdistdist/docs/advanced/ebpf.rst b/pdns/dnsdistdist/docs/advanced/ebpf.rst
index 6d8f9c2a20d8f51e63d1e065aa9c7ed82e736996..e50dfbf47258e91fe3ed2fc487189a42e770bde9 100644 (file)
--- a/pdns/dnsdistdist/docs/advanced/ebpf.rst
+++ b/pdns/dnsdistdist/docs/advanced/ebpf.rst
@@ -59,8 +59,27 @@ Finally, it's also possible to attach it to specific binds at runtime::
   > bd = getBind(0)
   > bd:attachFilter(bpf)
 
-:program:`dnsdist` also supports adding dynamic, expiring blocks to a BPF filter::
+:program:`dnsdist` also supports adding dynamic, expiring blocks to a BPF filter:
 
+.. code-block:: lua
+
+  bpf = newBPFFilter({ipv4MaxItems=1024, ipv6MaxItems=1024, qnamesMaxItems=1024})
+  setDefaultBPFFilter(bpf)
+  local dbr = dynBlockRulesGroup()
+  dbr:setQueryRate(20, 10, "Exceeded query rate", 60)
+
+  function maintenance()
+    dbr:apply()
+  end
+
+This will dynamically block all hosts that exceeded 20 queries/s as measured over the past 10 seconds, and the dynamic block will last for 60 seconds.
+
+Since 1.6.0, the default BPF filter set via :func:`setDefaultBPFFilter` will automatically get used when a "drop" dynamic block is inserted via a :ref:`DynBlockRulesGroup`, which provides a better way to combine dynamic blocks with eBPF filtering.
+Before that, it was possible to use the :func:`addBPFFilterDynBlocks` method instead:
+
+.. code-block:: lua
+
+  -- this is a legacy method, please see above for DNSdist >= 1.6.0
   bpf = newBPFFilter({ipv4MaxItems=1024, ipv6MaxItems=1024, qnamesMaxItems=1024})
   setDefaultBPFFilter(bpf)
   dbpf = newDynBPFFilter(bpf)
@@ -69,16 +88,12 @@ Finally, it's also possible to attach it to specific binds at runtime::
           dbpf:purgeExpired()
   end
 
-This will dynamically block all hosts that exceeded 20 queries/s as measured over the past 10 seconds, and the dynamic block will last for 60 seconds.
-
 The dynamic eBPF blocks and the number of queries they blocked can be seen in the web interface and retrieved from the API. Note however that eBPF dynamic objects need to be registered before they appear in the web interface or the API, using the :func:`registerDynBPFFilter` function::
 
   registerDynBPFFilter(dbpf)
 
 They can be unregistered at a later point using the :func:`unregisterDynBPFFilter` function.
 
-Since 1.6.0, the default BPF filter set via :func:`setDefaultBPFFilter` will automatically get used when a "drop" dynamic block is inserted via a :ref:`DynBlockRulesGroup`, which provides a better way to combine dynamic blocks with eBPF filtering.
-
 Requirements
 ------------
 

diff --git a/pdns/dnsdistdist/docs/guides/dynblocks.rst b/pdns/dnsdistdist/docs/guides/dynblocks.rst
index a8958283c0b0f885a2453ebda582258f74702aec..c987b0c69f5b538f23c9f9a7c6b8dfe90e973c1c 100644 (file)
--- a/pdns/dnsdistdist/docs/guides/dynblocks.rst
+++ b/pdns/dnsdistdist/docs/guides/dynblocks.rst
@@ -11,14 +11,28 @@ To set dynamic rules, based on recent traffic, define a function called :func:`m
 It will get called every second, and from this function you can set rules to block traffic based on statistics.
 More exactly, the thread handling the :func:`maintenance` function will sleep for one second between each invocation, so if the function takes several seconds to complete it will not be invoked exactly every second.
 
-As an example::
+As an example:
+
+.. code-block:: lua
+
+  local dbr = dynBlockRulesGroup()
+  dbr:setQueryRate(20, 10, "Exceeded query rate", 60)
 
   function maintenance()
-      addDynBlocks(exceedQRate(20, 10), "Exceeded query rate", 60)
+    dbr:apply()
   end
 
 This will dynamically block all hosts that exceeded 20 queries/s as measured over the past 10 seconds, and the dynamic block will last for 60 seconds.
 
+:ref:`DynBlockRulesGroup` is a very efficient way of processing dynamic blocks that was introduced in 1.3.0. Before that, it was possible to use :meth:`addDynBlocks` instead:
+
+.. code-block:: lua
+
+  -- this is a legacy method, please see above for DNSdist >= 1.3.0
+  function maintenance()
+      addDynBlocks(exceedQRate(20, 10), "Exceeded query rate", 60)
+  end
+
 Dynamic blocks in force are displayed with :func:`showDynBlocks` and can be cleared with :func:`clearDynBlocks`.
 They return a table whose key is a :class:`ComboAddress` object, representing the client's source address, and whose value is an integer representing the number of queries matching the corresponding condition (for example the qtype for :func:`exceedQTypeRate`, rcode for :func:`exceedServFails`).
 
@@ -40,18 +54,6 @@ Starting with dnsdist 1.3.0, a new :ref:`dynBlockRulesGroup` function can be use
 designed to make the processing of multiple rate-limiting rules faster by walking the query and response buffers only once
 for each invocation, instead of once per existing `exceed*()` invocation.
 
-For example, instead of having something like:
-
-.. code-block:: lua
-
-  function maintenance()
-    addDynBlocks(exceedQRate(30, 10), "Exceeded query rate", 60)
-    addDynBlocks(exceedNXDOMAINs(20, 10), "Exceeded NXD rate", 60)
-    addDynBlocks(exceedServFails(20, 10), "Exceeded ServFail rate", 60)
-    addDynBlocks(exceedQTypeRate(DNSQType.ANY, 5, 10), "Exceeded ANY rate", 60)
-    addDynBlocks(exceedRespByterate(1000000, 10), "Exceeded resp BW rate", 60)
-  end
-
 The new syntax would be:
 
 .. code-block:: lua
@@ -67,6 +69,20 @@ The new syntax would be:
     dbr:apply()
   end
 
+Before 1.3.0 the legacy syntax was:
+
+.. code-block:: lua
+
+  function maintenance()
+    -- this example is using legacy methods, please see above for DNSdist >= 1.3.0
+    addDynBlocks(exceedQRate(30, 10), "Exceeded query rate", 60)
+    addDynBlocks(exceedNXDOMAINs(20, 10), "Exceeded NXD rate", 60)
+    addDynBlocks(exceedServFails(20, 10), "Exceeded ServFail rate", 60)
+    addDynBlocks(exceedQTypeRate(DNSQType.ANY, 5, 10), "Exceeded ANY rate", 60)
+    addDynBlocks(exceedRespByterate(1000000, 10), "Exceeded resp BW rate", 60)
+  end
+
+
 The old syntax would walk the query buffer 2 times and the response one 3 times, while the new syntax does it only once for each.
 It also reuse the same internal table to keep track of the source IPs, reducing the CPU usage.
 

diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst
index d7c41e7317e6d16035d19ac082ce2a5b837e4faf..462f8b5f343d46dd24fa88d7730f32c10355f725 100644 (file)
--- a/pdns/dnsdistdist/docs/reference/config.rst
+++ b/pdns/dnsdistdist/docs/reference/config.rst
@@ -1364,6 +1364,7 @@ Dynamic Blocks
 
   Block a set of addresses with ``message`` for (optionally) a number of seconds.
   The default number of seconds to block for is 10.
+  Since 1.3.0, the use of a :ref:`DynBlockRulesGroup` is a much more efficient way of doing the same thing.
 
   :param addresses: set of Addresses as returned by an exceed function
   :param string message: The message to show next to the blocks

diff --git a/pdns/dnsdistdist/docs/reference/ebpf.rst b/pdns/dnsdistdist/docs/reference/ebpf.rst
index 2a3b4f71f13903c3642ef246c9591cf2ac2df7a9..111ec2359b6ba0a4c1fa6156f52ea3aa14508b0b 100644 (file)
--- a/pdns/dnsdistdist/docs/reference/ebpf.rst
+++ b/pdns/dnsdistdist/docs/reference/ebpf.rst
@@ -7,6 +7,7 @@ These are all the functions, objects and methods related to the :doc:`../advance
 
   This is the eBPF equivalent of :func:`addDynBlocks`, blocking a set of addresses for (optionally) a number of seconds, using an eBPF dynamic filter.
   The default number of seconds to block for is 10.
+  Since 1.6.0, the use of a :ref:`DynBlockRulesGroup` is a much more efficient way of doing the same thing.
 
   :param addresses: set of Addresses as returned by an :ref:`exceed function <exceedfuncs>`
   :param DynBPFFilter dynbpf: The dynamic eBPF filter to use