Documentation updates: new runtime switch and some clarification for configuring...

diff --git a/.github/actions/spell-check/expect.txt b/.github/actions/spell-check/expect.txt
index 27808f9d7efa123ab333d3163020bb204f3fb588..0999cf5481ff37bbfc1f31e8a2bb87d87f872d46 100644 (file)
--- a/.github/actions/spell-check/expect.txt
+++ b/.github/actions/spell-check/expect.txt
@@ -841,6 +841,7 @@ Krul
 ksk
 kskroll
 kskrollcdnskey
+KTNAME
 Kuehrer
 kvs
 Ladot

diff --git a/docs/settings.rst b/docs/settings.rst
index ef7860c9f59a01c8d6c0203df6e12aa6cbc3eedd..5395308559d0b518cdb7a6990558237bb6c7b68b 100644 (file)
--- a/docs/settings.rst
+++ b/docs/settings.rst
@@ -653,6 +653,17 @@ This setting MUST be 32 hexadecimal characters, as the siphash algorithm's key u
 
 Enables EDNS subnet processing, for backends that support it.
 
+.. _setting-enable-gss-tsig:
+
+``enable-gss-tsig``
+-------------------
+
+-  Boolean
+-  Default: no
+
+Enable the accepting of GSS-TSIG signed messages.
+In addition to this setting, see :doc:`tsig`.
+
 .. _setting-enable-lua-records:
 
 ``enable-lua-records``

diff --git a/docs/tsig.rst b/docs/tsig.rst
index 1f7941c89f59522768b8291613b8c9890e4831c5..c68c16e695ae7457ad37902923f525e0e96d1cd1 100644 (file)
--- a/docs/tsig.rst
+++ b/docs/tsig.rst
@@ -129,10 +129,12 @@ using Kerberos with TSIG signatures.
 Prerequisites
 ~~~~~~~~~~~~~
 
--  Working Kerberos environment. Please refer to your Kerberos vendor
-   documentation on how to setup it.
--  Principal (such as ``DNS/<your.dns.server.name>@REALM``) in either
-   per-user keytab or system keytab.
+-  Working Kerberos environment. Please refer to your Kerberos vendor documentation on how to set it up.
+-  Accepting Principal (of the form ``DNS/your.dns.server.name@REALM``) in either per-user keytab or
+   system keytab, where ``your.dns.server.name`` must match the nameserver name in the SOA record of the zone.
+   If a user keytab is used, specify it using the ``KRB5_KTNAME`` environment variable when starting up PDNS server,
+   which must be able to read the keytab file.
+
 
 In particular, if something does not work, read logs and ensure that
 your kerberos environment is ok before filing an issue. Most common
@@ -141,12 +143,13 @@ problems are time synchronization or changes done to the principal.
 Setting up
 ~~~~~~~~~~
 
-To allow AXFR / DNS update to work, you need to configure
-``GSS-ACCEPTOR-PRINCIPAL`` in
-:doc:`domainmetadata`. This will define the
-principal that is used to accept any GSS context requests. This *must*
-match to your keytab. Next you need to define one or more
-``GSS-ALLOW-AXFR-PRINCIPAL`` entries for AXFR, or
-``TSIG-ALLOW-DNSUPDATE`` entries for DNS update. These must be set to
-the exact initiator principal names you intend to use. No wildcards
-accepted.
+To allow AXFR / DNS update to work, you need to set :ref:`setting-enable-gss-tsig` and configure ``GSS-ACCEPTOR-PRINCIPAL`` in :doc:`domainmetadata`.
+This will define the principal that is used to accept any GSS context requests for names in the specified domain.
+This *must* match to a principal in the keytab used by PDNS Server.
+Next you need to define one or more ``GSS-ALLOW-AXFR-PRINCIPAL`` entries for AXFR,
+or ``TSIG-ALLOW-DNSUPDATE`` entries for DNS update.
+These must be set to the exact initiator (client) principal names you intend to allow either AXFR or DNS update.
+No wildcards accepted.
+If a Lua update policy is defined (see :doc:`dnsupdate`) no ``TSIG-ALLOW-DNSUPDATE`` entries are needed,
+as the Lua policy defines which principals can update which records.
+