From a04a7c41c9327144cc11ffd030c0efc2a4f85534 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 14 Jun 2024 18:17:58 +0200 Subject: Adding upstream version 3.3.6. Signed-off-by: Daniel Baumann --- doc/reference.rst | 115 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 75 insertions(+), 40 deletions(-) (limited to 'doc/reference.rst') diff --git a/doc/reference.rst b/doc/reference.rst index 45574dc..bbd4586 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -202,7 +202,7 @@ General options related to the server. quic-idle-close-timeout: TIME remote-pool-limit: INT remote-pool-timeout: TIME - remote-retry-delay: TIME + remote-retry-delay: INT socket-affinity: BOOL udp-max-payload: SIZE udp-max-payload-ipv4: SIZE @@ -875,7 +875,7 @@ tcp-resend-timeout ------------------ Resend outgoing data packets (with DNS response payload) if not ACKed -before this timeout. +before this timeout (in seconds). *Minimum:* ``1`` @@ -923,6 +923,7 @@ Configuration of the server control interface. control: listen: STR + backlog: INT timeout: TIME .. _control_listen: @@ -933,8 +934,21 @@ listen A UNIX socket :ref:`path` where the server listens for control commands. +Change of this parameter requires restart of the Knot server to take effect. + *Default:* :ref:`rundir`\ ``/knot.sock`` +.. _control_backlog: + +backlog +------- + +The control UNIX socket listen backlog size. + +Change of this parameter requires restart of the Knot server to take effect. + +*Default:* ``5`` + .. _control_timeout: timeout @@ -1553,8 +1567,9 @@ An ordered list of :ref:`references` to remote server definitions. =============== Access control list rule definitions. An ACL rule is a description of one -or more authorized operations (zone transfer request, zone change notification, -and dynamic DNS update) which are allowed to be processed or denied. +or more authorized actions (zone transfer request, zone change notification, +and dynamic DNS update) which are allowed to be processed or denied. Normal +DNS queries are always allowed. :: @@ -1637,7 +1652,7 @@ TSIG key if configured must match. action ------ -An ordered list of allowed (or denied) actions. +An ordered list of allowed, or denied, actions (request types). Possible values: @@ -1769,8 +1784,8 @@ rollover must be pushed forward manually. check-interval -------------- -Interval for periodic checks of DS presence on parent's DNS servers, in the -case of the KSK submission. +Interval (in seconds) for periodic checks of DS presence on parent's DNS +servers, in the case of the KSK submission. *Default:* ``1h`` (1 hour) @@ -1790,9 +1805,9 @@ Set to 0 for infinity. parent-delay ------------ -After successful parent DS check, wait for this period before continuing the next -key roll-over step. This delay shall cover the propagation delay of update in the -parent zone. +After successful parent DS check, wait for this period (in seconds) before +continuing the next key roll-over step. This delay shall cover the propagation +delay of update in the parent zone. *Default:* ``0`` @@ -1801,7 +1816,7 @@ parent zone. ``dnskey-sync`` section ======================= -Parameters of DNSKEY dynamic-update synchrnization. +Parameters of DNSKEY dynamic-update synchronization. :: @@ -1834,7 +1849,7 @@ check-interval -------------- If the last DNSKEY sync failed or resulted in any change, re-check -the consistence after this interval and re-try if needed. +the consistence after this interval (in seconds) and re-try if needed. *Default:* ``60`` (1 minute) @@ -1858,6 +1873,7 @@ DNSSEC policy configuration. ksk-shared: BOOL dnskey-ttl: TIME zone-max-ttl: TIME + keytag-modulo: INT/INT ksk-lifetime: TIME zsk-lifetime: TIME delete-delay: TIME @@ -2011,12 +2027,29 @@ Declare (override) maximal TTL value among all the records in zone. *Default:* computed after zone is loaded +.. _policy_keytag-modulo: + +keytag-modulo +------------- + +Specifies that the keytags of any generated keys shall be congruent by specified modulo. +The option value must be a string in the format ``R/M``, where ``R < M <= 256`` are +positive integers. Whenever a DNSSEC key is generated, it is ensured +that ``keytag % M == R``. This prevents keytag conflict in :ref:`DNSSEC Offline KSK` +or :ref:`DNSSEC multi-signer` (and possibly other) setups. + +.. NOTE:: + This only applies to newly generated keys when they are generated. Keys from + before this option and keys imported from elsewhere might not fulfill the policy. + +*Default:* ``0/1`` + .. _policy_ksk-lifetime: ksk-lifetime ------------ -A period between KSK generation and the next rollover initiation. +A period (in seconds) between KSK generation and the next rollover initiation. .. NOTE:: KSK key lifetime is also influenced by propagation-delay, dnskey-ttl, @@ -2026,14 +2059,14 @@ A period between KSK generation and the next rollover initiation. This applies for CSK lifetime if single-type-signing is enabled. -*Default:* ``0`` +*Default:* ``0`` (infinity) .. _policy_zsk-lifetime: zsk-lifetime ------------ -A period between ZSK activation and the next rollover initiation. +A period (in seconds) between ZSK activation and the next rollover initiation. .. NOTE:: More exactly, this period is measured since a ZSK is activated, @@ -2053,8 +2086,8 @@ delete-delay ------------ Once a key (KSK or ZSK) is rolled-over and removed from the zone, -keep it in the KASP database for at least this period before deleting it completely. -This might be useful in some troubleshooting cases when resurrection +keep it in the KASP database for at least this period (in seconds) before deleting +it completely. This might be useful in some troubleshooting cases when resurrection is needed. *Default:* ``0`` @@ -2064,13 +2097,13 @@ is needed. propagation-delay ----------------- -An extra delay added for each key rollover step. This value should be high -enough to cover propagation of data from the primary server to all -secondary servers, as well as the duration of signing routine itself and -possible outages in signing and propagation infrastructure. In other words, -this delay should ensure that within this period of time after planned -change of the key set, all public-facing secondaries will already serve -new DNSKEY RRSet for sure. +An extra delay added for each key rollover step. This value (in seconds) +should be high enough to cover propagation of data from the primary server +to all secondary servers, as well as the duration of signing routine itself +and possible outages in signing and propagation infrastructure. In other +words, this delay should ensure that within this period of time after +planned change of the key set, all public-facing secondaries will already +serve new DNSKEY RRSet for sure. .. NOTE:: Has influence over ZSK key lifetime. @@ -2082,7 +2115,7 @@ new DNSKEY RRSet for sure. rrsig-lifetime -------------- -A validity period of newly issued signatures. +A validity period (in seconds) of newly issued signatures. .. NOTE:: The RRSIG's signature inception time is set to 90 minutes in the past. This @@ -2095,8 +2128,9 @@ A validity period of newly issued signatures. rrsig-refresh ------------- -A period how long at least before a signature expiration the signature will be refreshed, -in order to prevent expired RRSIGs on secondary servers or resolvers' caches. +A period (in seconds) how long at least before a signature expiration the signature +will be refreshed, in order to prevent expired RRSIGs on secondary servers or +resolvers' caches. *Default:* 0.1 * :ref:`policy_rrsig-lifetime` + :ref:`policy_propagation-delay` + :ref:`policy_zone-max-ttl` @@ -2105,9 +2139,9 @@ in order to prevent expired RRSIGs on secondary servers or resolvers' caches. rrsig-pre-refresh ----------------- -A period how long at most before a signature refresh time the signature might be refreshed, -in order to refresh RRSIGs in bigger batches on a frequently updated zone -(avoid re-sign event too often). +A period (in seconds) how long at most before a signature refresh time the signature +might be refreshed, in order to refresh RRSIGs in bigger batches on a frequently updated +zone (avoid re-sign event too often). *Default:* ``1h`` (1 hour) @@ -2170,7 +2204,7 @@ name before hashing. nsec3-salt-lifetime ------------------- -A validity period of newly issued salt field. +A validity period (in seconds) of newly issued salt field. Zero value means infinity. @@ -2494,6 +2528,7 @@ master An ordered list of references :ref:`remote` and :ref:`remotes` to zone primary servers (formerly known as master servers). +Empty value is allowed for template value overriding. *Default:* not set @@ -2520,6 +2555,7 @@ notify An ordered list of references :ref:`remote` and :ref:`remotes` to secondary servers to which notify message is sent if the zone changes. +Empty value is allowed for template value overriding. *Default:* not set @@ -2541,13 +2577,13 @@ master-pin-tolerance If set to a nonzero value on a secondary, always request AXFR/IXFR from the same primary as the last time, effectively pinning one primary. Only when another primary is updated and the current one lags behind for the specified amount of time -(defined by this option), change to the updated primary and force AXFR. +(defined by this option in seconds), change to the updated primary and force AXFR. This option is useful when multiple primaries may have different zone history in their journals, making it unsafe to combine interchanged IXFR from different primaries. -*Default:* 0 +*Default:* ``0`` (disabled) .. _zone_provide-ixfr: @@ -2608,8 +2644,8 @@ Extra checks: zonefile-sync ------------- -The time after which the current zone in memory will be synced with a zone file -on the disk (see :ref:`file`). The server will serve the latest +The time in seconds after which the current zone in memory will be synced with +a zone file on the disk (see :ref:`file`). The server will serve the latest zone even after a restart using zone journal, but the zone file on the disk will only be synced after ``zonefile-sync`` time has expired (or after manual zone flush). This is applicable when the zone is updated via IXFR, DDNS or automatic @@ -2707,7 +2743,7 @@ ixfr-benevolent If enabled, incoming IXFR is applied even when it contains removals of non-existing or additions of existing records. -*Default:* off +*Default:* ``off`` .. _zone_ixfr-by-one: @@ -2821,7 +2857,7 @@ ds-push ------- Per zone configuration of :ref:`policy_ds-push`. This option overrides possible -per policy option. +per policy option. Empty value is allowed for template value overriding. *Default:* not set @@ -3014,9 +3050,8 @@ has the *group* property defined, matching another catalog template. .. NOTE:: This option must be set if and only if :ref:`zone_catalog-role` is *interpret*. - Nested catalog zones aren't supported. Therefore catalog templates can't use - :ref:`zone_catalog-template`, :ref:`zone_catalog-role`, :ref:`zone_catalog-zone`, - and :ref:`zone_catalog-group` options. + Nested catalog zones aren't supported. Therefore catalog templates can't + contain :ref:`zone_catalog-role` set to ``interpret`` or ``generate``. *Default:* not set -- cgit v1.2.3