dnsdist: Document interactions between XFR, NOTIFY and the cache

diff --git a/pdns/dnsdistdist/docs/advanced/axfr.rst b/pdns/dnsdistdist/docs/advanced/axfr.rst
index b74fff93f40b5d6ffc1c5268073e8ccf432b53b3..2a6810cf61ff5d7c5698db3928388482fb360bc3 100644 (file)
--- a/pdns/dnsdistdist/docs/advanced/axfr.rst
+++ b/pdns/dnsdistdist/docs/advanced/axfr.rst
@@ -1,6 +1,9 @@
 AXFR, IXFR and NOTIFY
 =====================
 
+In front of primaries
+---------------------
+
 When :program:`dnsdist` is deployed in front of a primary authoritative server, it might receive
 AXFR or IXFR queries destined to this primary. There are two issues that can arise in this kind of setup:
 
@@ -24,6 +27,25 @@ and moving the source address check to :program:`dnsdist`'s side::
   Before 1.4.0, the QTypes were in the ``dnsdist`` namespace. Use ``dnsdist.AXFR`` and ``dnsdist.IXFR`` in these versions.
   Before 1.4.0, the RCodes were in the ``dnsdist`` namespace. Use ``dnsdist.REFUSED`` in these versions.
 
+A different way would be to configure dnsdist to pass the source IP of the client to the backend. The different options
+to do that are described in :doc:`Passing the source address to the backend <passing-source-address>`.
+
+.. warning::
+
+  Be wary of dnsdist caching the responses to AXFR and IXFR queries and sending these to the wrong clients.
+  This is mitigated by default when the source IP of the client is passed using EDNS Client Subnet, but
+  not when the proxy protocol is used, so disabling caching for these kinds of queries is advised:
+
+  .. code-block:: lua
+
+    -- this rule will not stop the processing, but disable caching for AXFR and IXFR responses
+    addAction(ORRule({QTypeRule(DNSQType.AXFR), QTypeRule(DNSQType.IXFR)}), SetSkipCacheAction())
+    -- this rule will route SOA, AXFR and IXFR queries to a specific pool of servers
+    addAction(OrRule({QTypeRule(DNSQType.SOA), QTypeRule(DNSQType.AXFR), QTypeRule(DNSQType.IXFR)}), PoolAction("primary"))
+
+In front of secondaries
+-----------------------
+
 When :program:`dnsdist` is deployed in front of secondaries, however, an issue might arise with NOTIFY
 queries, because the secondary will receive a notification coming from the :program:`dnsdist` address,
 and not the primary's one. One way to fix this issue is to allow NOTIFY from the :program:`dnsdist`
@@ -34,3 +56,14 @@ check to :program:`dnsdist`'s side::
 
 .. versionchanged:: 1.4.0
   Before 1.4.0, the RCodes were in the ``dnsdist`` namespace. Use ``dnsdist.REFUSED`` in these versions.
+
+.. warning::
+
+  Be wary of dnsdist caching the responses to NOTIFY queries and sending these to the wrong clients.
+  This is mitigated by default when the source IP of the client is passed using EDNS Client Subnet, but
+  not when the proxy protocol is used, so disabling caching for these kinds of queries is advised:
+
+  .. code-block:: lua
+
+    -- this rule will disable caching for NOTIFY responses
+    addAction(AndRule({OpcodeRule(DNSOpcode.Notify), QTypeRule(DNSQType.SOA)}), SetSkipCacheAction())