upstream/knot-dns
1
0
Fork 0
mirror of https://gitlab.nic.cz/knot/knot-dns.git synced 2026-06-04 14:13:08 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: serial modulo/shift enhancements

Browse source
This commit is contained in:
Libor Peltan 2025-01-28 14:40:46 +01:00 committed by Daniel Salzman
parent daf9f6d0f5
commit f66c2b7c74
2 changed files with 61 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
doc/operation.rst
View file

@ -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 <https://github.com/DNSSEC-Provisioning/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 <zone_master-pin-tolerance>` 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

25
doc/reference.rst
View file

@ -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<zone_dnssec-signing>` 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: