From: Matthias Valvekens <matthias@mvalvekens.be>
Date: Wed, 23 Apr 2025 19:50:35 +0000 (+0200)
Subject: Rearrange confusingly ordered docs on DNS update checks
X-Git-Tag: dnsdist-2.0.0-alpha2~62^2
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=refs%2Fpull%2F15457%2Fhead;p=thirdparty%2Fpdns.git

Rearrange confusingly ordered docs on DNS update checks

Structure-wise, the paragraph on the interaction between ``allow-dnsupdate-from``, ``ALLOW-DNSUPDATE-FROM`` and ``TSIG-ALLOW-DNSUPDATE`` wound up in the section of the document on Lua update policies.

That seems unintentional, and it's additionally confusing because the description of the Lua update policy setting explicitly mentions that it causes all other enforcement mechanisms to be disabled. This change attempts to correct that.
---

diff --git a/docs/dnsupdate.rst b/docs/dnsupdate.rst
index e474ccc074..3d473486d7 100644
--- a/docs/dnsupdate.rst
+++ b/docs/dnsupdate.rst
@@ -23,8 +23,8 @@ support DNS update:
 Configuration options
 ---------------------
 
-There are two configuration parameters that can be used within the
-powerdns configuration file.
+There are several configuration parameters that can be used within the
+powerdns configuration file to influence DNS update behavior.
 
 ``dnsupdate``
 ~~~~~~~~~~~~~
@@ -46,6 +46,20 @@ combination with the ``ALLOW-DNSUPDATE-FROM`` :doc:`domain metadata <domainmetad
 zone. Setting a range here and in ``ALLOW-DNSUPDATE-FROM`` enables updates
 from either address range.
 
+The semantics are that first a dynamic update has to be allowed either
+by the global :ref:`setting-allow-dnsupdate-from` setting, or by a per-zone
+``ALLOW-DNSUPDATE-FROM`` metadata setting.
+
+Secondly, if a zone has a ``TSIG-ALLOW-DNSUPDATE`` metadata setting, that
+must match too.
+
+So to only allow dynamic DNS updates to a zone based on TSIG key, and
+regardless of IP address, set :ref:`setting-allow-dnsupdate-from` to empty, set
+``ALLOW-DNSUPDATE-FROM`` to "0.0.0.0/0" and "::/0" and set the
+``TSIG-ALLOW-DNSUPDATE`` to the proper key name.
+
+Further information can be found :ref:`below <dnsupdate-how-it-works>`.
+
 ``dnsupdate-require-tsig``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -78,20 +92,6 @@ authorization methods, and you are expected to take care of everything
 yourself. See :ref:`dnsupdate-update-policy` for details and
 examples.
 
-The semantics are that first a dynamic update has to be allowed either
-by the global :ref:`setting-allow-dnsupdate-from` setting, or by a per-zone
-``ALLOW-DNSUPDATE-FROM`` metadata setting.
-
-Secondly, if a zone has a ``TSIG-ALLOW-DNSUPDATE`` metadata setting, that
-must match too.
-
-So to only allow dynamic DNS updates to a zone based on TSIG key, and
-regardless of IP address, set :ref:`setting-allow-dnsupdate-from` to empty, set
-``ALLOW-DNSUPDATE-FROM`` to "0.0.0.0/0" and "::/0" and set the
-``TSIG-ALLOW-DNSUPDATE`` to the proper key name.
-
-Further information can be found :ref:`below <dnsupdate-how-it-works>`.
-
 .. _dnsupdate-metadata:
 
 Per zone settings