diff options
Diffstat (limited to 'doc/reference.rst')
| -rw-r--r-- | doc/reference.rst | 114 |
1 files changed, 95 insertions, 19 deletions
diff --git a/doc/reference.rst b/doc/reference.rst index 6cb42f3..1aefc57 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -20,9 +20,10 @@ the following symbols: - ``STR`` – Textual string - ``HEXSTR`` – Hexadecimal string (with ``0x`` prefix) - ``BOOL`` – Boolean value (``on``/``off`` or ``true``/``false``) -- ``TIME`` – Number of seconds, an integer with possible time multiplier suffix - (``s`` ~ 1, ``m`` ~ 60, ``h`` ~ 3600 or ``d`` ~ 24 * 3600) -- ``SIZE`` – Number of bytes, an integer with possible size multiplier suffix +- ``TIME`` – Number of seconds, an integer with a possible time multiplier suffix + (``s`` ~ 1, ``m`` ~ 60, ``h`` ~ 3600, ``d`` ~ 24 * 3600, ``w`` ~ 7 * 24 * 3600, + ``M`` ~ 30 * 24 * 3600, ``y`` ~ 365 * 24 * 3600) +- ``SIZE`` – Number of bytes, an integer with a possible size multiplier suffix (``B`` ~ 1, ``K`` ~ 1024, ``M`` ~ 1024^2 or ``G`` ~ 1024^3) - ``BASE64`` – Base64 encoded string - ``ADDR`` – IPv4 or IPv6 address @@ -217,6 +218,7 @@ General options related to the server. dbus-init-delay: TIME listen: ADDR[@INT] | STR ... listen-quic: ADDR[@INT] ... + listen-tls: ADDR[@INT] ... .. CAUTION:: When you change configuration parameters dynamically or via configuration file @@ -561,12 +563,10 @@ Maximum EDNS0 UDP payload size for IPv6. key-file -------- -Path to a server key PEM file which is used for DNS over QUIC communication. +Path to a server key PEM file which is used for DNS over QUIC/TLS communication. A non-absolute path of a user specified key file is relative to the :file:`@config_dir@` directory. -Change of this parameter requires restart of the Knot server to take effect. - *Default:* auto-generated key .. _server_cert-file: @@ -574,11 +574,9 @@ Change of this parameter requires restart of the Knot server to take effect. cert-file --------- -Path to a server certificate PEM file which is used for DNS over QUIC communication. +Path to a server certificate PEM file which is used for DNS over QUIC/TLS communication. A non-absolute path is relative to the :file:`@config_dir@` directory. -Change of this parameter requires restart of the Knot server to take effect. - *Default:* one-time in-memory certificate .. _server_edns-client-subnet: @@ -646,16 +644,17 @@ Possible values: - ``stopped`` when the server shutdown sequence is initiated. - ``zone-updated`` – The signal ``zone_updated`` is emitted when a zone has been updated; the signal parameters are `zone name` and `zone SOA serial`. -- ``keys-updated`` - The signal ``keys_updated`` is emitted when a DNSSEC key set - of this zone is updated. +- ``keys-updated`` - The signal ``keys_updated`` is emitted when a DNSSEC key set + is updated; the signal parameter is `zone name`. - ``ksk-submission`` – The signal ``zone_ksk_submission`` is emitted if there is a ready KSK present when the zone is signed; the signal parameters are `zone name`, `KSK keytag`, and `KSK KASP id`. - ``dnssec-invalid`` – The signal ``zone_dnssec_invalid`` is emitted when DNSSEC - validation fails; the signal parameter is `zone name`. + validation fails; the signal parameters are `zone name`, and `remaining seconds` + until an RRSIG expires. .. NOTE:: - This function requires systemd version at least 221. + This function requires systemd version at least 221 or libdbus. Change of this parameter requires restart of the Knot server to take effect. @@ -704,9 +703,17 @@ Change of this parameter requires restart of the Knot server to take effect. *Default:* not set -.. NOTE:: - Incoming :ref:`DDNS<dynamic updates>` over QUIC isn't supported. - The server always responds with SERVFAIL. +.. _server_listen-tls: + +listen-tls +---------- + +One or more IP addresses (and optionally ports) where the server listens +for incoming queries over TLS protocol (DoT). + +Change of this parameter requires restart of the Knot server to take effect. + +*Default:* not set .. _xdp section: @@ -730,6 +737,9 @@ Various options related to XDP listening, especially TCP. tcp-idle-reset-timeout: TIME tcp-resend-timeout: TIME route-check: BOOL + ring-size: INT + busypoll-budget: INT + busypoll-timeout: INT .. CAUTION:: When you change configuration parameters dynamically or via configuration file @@ -912,6 +922,57 @@ Change of this parameter requires restart of the Knot server to take effect. *Default:* ``off`` +.. _xdp_ring-size: + +ring-size +--------- + +Size of RX, FQ, TX, and CQ rings. + +Change of this parameter requires restart of the Knot server to take effect. + +.. NOTE:: + This value should be at least as high as the configured RX size of the + network device in the XDP mode. + +*Default:* ``2048`` + +.. _xdp_busypoll-budget: + +busypoll-budget +--------------- + +If set to a positive value, preferred busy polling is enabled with the +specified budget. + +Change of this parameter requires restart of the Knot server to take effect. + +.. NOTE:: + + Preferred busy polling also requires setting ``napi_defer_hard_irqs`` and + ``gro_flush_timeout`` for the appropriate network interface. E.g.:: + + echo 2 | sudo tee /sys/class/net/<interface>/napi_defer_hard_irqs + echo 200000 | sudo tee /sys/class/net/<interface>/gro_flush_timeout + +.. NOTE:: + + A recommended value is between 8 and 64. + +*Default:* ``0`` (disabled) + +.. _xdp_busypoll-timeout: + +busypoll-timeout +---------------- + +Timeout in microseconds of preferrred busy polling if enabled by +:ref:`xdp_busypoll-budget`. + +Change of this parameter requires restart of the Knot server to take effect. + +*Default:* ``20`` (20 microseconds) + .. _control section: ``control`` section @@ -1378,6 +1439,7 @@ transfer, target for a notification, etc.). address: ADDR[@INT] | STR ... via: ADDR[@INT] ... quic: BOOL + tls: BOOL key: key_id cert-key: BASE64 ... block-notify-after-transfer: BOOL @@ -1459,6 +1521,16 @@ with this remote. *Default:* ``off`` +.. _remote_tls: + +tls +--- + +If this option is set, the TLS (DoT) protocol will be used for outgoing communication +with this remote. + +*Default:* ``off`` + .. _remote_key: key @@ -1955,8 +2027,6 @@ Possible values: - ``ed448`` .. NOTE:: - Ed25519 algorithm is only available if compiled with GnuTLS 3.6.0+. - Ed448 algorithm is only available if compiled with GnuTLS 3.6.12+ and Nettle 3.6+. *Default:* ``ecdsap256sha256`` @@ -2134,6 +2204,10 @@ resolvers' caches. *Default:* 0.1 * :ref:`policy_rrsig-lifetime` + :ref:`policy_propagation-delay` + :ref:`policy_zone-max-ttl` +If :ref:`zone_dnssec-validation` is enabled: + +*Default:* ``1d`` (1 day) + .. _policy_rrsig-pre-refresh: rrsig-pre-refresh @@ -2847,7 +2921,9 @@ List of DNSSEC checks: The validation is not affected by :ref:`zone_dnssec-policy` configuration, except for :ref:`policy_signing-threads` option, which specifies the number -of threads for parallel validation. +of threads for parallel validation, and :ref:`policy_rrsig-refresh`, which +defines minimal allowed remaining RRSIG validity (otherwise a warning is +logged). .. NOTE:: |