From f66c2b7c748e68ad8800f46bb6e6c75fecb19224 Mon Sep 17 00:00:00 2001 From: Libor Peltan Date: Tue, 28 Jan 2025 14:40:46 +0100 Subject: [PATCH] doc: serial modulo/shift enhancements --- doc/operation.rst | 49 ++++++++++++++++++++++++++++++++++++++++++----- doc/reference.rst | 25 ++++++++++++++++-------- 2 files changed, 61 insertions(+), 13 deletions(-) diff --git a/doc/operation.rst b/doc/operation.rst index 0ba792731..44ad8810e 100644 --- a/doc/operation.rst +++ b/doc/operation.rst @@ -449,6 +449,48 @@ The sizing of journal limits needs to be taken into consideration .. NOTE:: This mode is not suitable if the zone can be modified externally (e.g. DDNS, knotc). +.. _Multi-primary: + +Multi-primary +============= + +In some setups, it is desirable for a secondary server to have multiple primaries configured. +An example is :ref:`DNSSEC multi-signer` or any other kind of fail-proof redundancy. +If the zone contents may differ among the primaries, it is necessary to avoid interchanged +IXFR zone transfers at the secondary. Applying mismatched incremental changes to different +zone versions can create inconsistencies that may be difficult to detect. + +Knot DNS provides the following options, which can also be combined. + +Master pinning +-------------- + +The :ref:`zone_master-pin-tolerance` option, configured on the secondary server, +ensures that the same primary is used unless it becomes unresponsive or remains +outdated for a configured time period. Additionally, if a fallback to a different +primary occurs, it enforces a full zone transfer (AXFR). + +Serial modulo +------------- + +The :ref:`zone_serial-modulo` option, configured on the primary servers, prevents +multiple primaries from using the same zone serial numbers. This ensures that even +secondaries without the master pinning support will use AXFR. + +Serial shift +------------ + +Another use case for this configuration option is mostly useful with the +``unixtime`` :ref:`zone_serial-policy`. It specifies that one primary is slightly +"ahead" or "behind" another in zone serial numbers. This naturally enforces master +pinning, even for secondaries that do not support it. + +Disabling IXFR +-------------- + +As a last resort, IXFR can be disabled on the primaries using :ref:`zone_provide-ixfr`, +with clear performance drawbacks. + .. _Zone bootstrap: Zone bootstrapping on secondary @@ -967,11 +1009,8 @@ within an organization. For multi-signer operations involving multiple `MUSIC `_. Regardless of the chosen mode from the following options, any secondary that has multiple signers -configured as primaries must prevent interchanged IXFR from them. This can be achieved -either by setting :ref:`master pinning ` on every secondary or -by setting distinct :ref:`zone_serial-modulo` on each signer. It is recommended to combine -both approaches. Alternatively, if any of the secondaries is not Knot DNS, -:ref:`zone_provide-ixfr` can be disabled on the signers. +configured as primaries must prevent interchanged IXFR from them. See +the relevant :ref:`Multi-primary` capter on how to achieve it. In order to prevent keytag conflicts, it is recommended that the keytags of keys generated by each signer are from distinct subset of possible values. With Knot DNS, this diff --git a/doc/reference.rst b/doc/reference.rst index aeb50b156..5572bf6a6 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -2543,7 +2543,7 @@ Definition of zones served by the server. zonemd-verify: BOOL zonemd-generate: none | zonemd-sha384 | zonemd-sha512 | remove serial-policy: increment | unixtime | dateserial - serial-modulo: INT/INT + serial-modulo: INT/INT | +INT | -INT | INT/INT+INT | INT/INT-INT reverse-generate: DNAME refresh-min-interval: TIME refresh-max-interval: TIME @@ -3032,23 +3032,32 @@ Possible values: serial-modulo ------------- -Specifies that the zone serials shall be congruent by specified modulo. -The option value must be a string in the format ``R/M``, where ``R < M <= 256`` are +The option value is a string consisting of two parts (with no separator between them), +each of which is optional. + +The first part specifies that the zone serials must be congruent modulo the specified value. +The format is ``R/M``, where ``R < M <= 256`` are positive integers. Whenever the zone serial is incremented, it is ensured that ``serial % M == R``. This can be useful in the case of multiple inconsistent primaries, where distinct zone serial sequences prevent cross-master-IXFR by any secondary. +.. NOTE:: + Because the zone serial effectively always increments by ``M`` instead of + ``1``, it is not recommended to use ``dateserial`` or even ``unixtime`` + :ref:`zone_serial-policy` in the case of rapidly updated zone. + +The second part specifies a numeric shift for the generated zone serial. +The shift is formatted as a signed integer, including the sign (``+`` or ``-``). +It is mostly useful with ``unixtime`` :ref:`zone_serial-policy`, where the generated +zone serial is shifted relative to the Unix time. + .. NOTE:: In order to ensure the congruent policy, this option is only allowed with :ref:`DNSSEC signing enabled` and :ref:`zone_zonefile-load` to be either ``difference-no-serial`` or ``none``. - Because the zone serial effectively always increments by ``M`` instead of - ``1``, it is not recommended to use ``dateserial`` :ref:`zone_serial-policy` - or even ``unixtime`` in case of rapidly updated zone. - -*Default:* ``0/1`` +*Default:* ``0/1+0`` .. _zone_reverse-generate: