summaryrefslogtreecommitdiffstats
path: root/doc/reference.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/reference.rst2726
1 files changed, 2726 insertions, 0 deletions
diff --git a/doc/reference.rst b/doc/reference.rst
new file mode 100644
index 0000000..737c4e5
--- /dev/null
+++ b/doc/reference.rst
@@ -0,0 +1,2726 @@
+.. highlight:: none
+.. _Configuration Reference:
+
+***********************
+Configuration Reference
+***********************
+
+.. _Description:
+
+Description
+===========
+
+Configuration files for Knot DNS use simplified YAML format. Simplified means
+that not all of the features are supported.
+
+For the description of configuration items, we have to declare a meaning of
+the following symbols:
+
+- ``INT`` – Integer
+- ``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
+ (``B`` ~ 1, ``K`` ~ 1024, ``M`` ~ 1024^2 or ``G`` ~ 1024^3)
+- ``BASE64`` – Base64 encoded string
+- ``ADDR`` – IPv4 or IPv6 address
+- ``DNAME`` – Domain name
+- ``...`` – Multi-valued item, order of the values is preserved
+- ``[`` ``]`` – Optional value
+- ``|`` – Choice
+
+The configuration consists of several fixed sections and optional module
+sections. There are 16 fixed sections (``module``, ``server``, ``xdp``, ``control``,
+``log``, ``statistics``, ``database``, ``keystore``, ``key``, ``remote``,
+``remotes``, ``acl``, ``submission``, ``policy``, ``template``, ``zone``).
+Module sections are prefixed with the ``mod-`` prefix (e.g. ``mod-stats``).
+
+Most of the sections (e.g. ``zone``) are sequences of settings blocks. Each
+settings block begins with a unique identifier, which can be used as a reference
+from other sections (such an identifier must be defined in advance).
+
+A multi-valued item can be specified either as a YAML sequence::
+
+ address: [10.0.0.1, 10.0.0.2]
+
+or as more single-valued items each on an extra line::
+
+ address: 10.0.0.1
+ address: 10.0.0.2
+
+If an item value contains spaces or other special characters, it is necessary
+to enclose such a value within double quotes ``"`` ``"``.
+
+.. _Comments:
+
+Comments
+========
+
+A comment begins with a ``#`` character and is ignored during processing.
+Also each configuration section or sequence block allows a permanent
+comment using the ``comment`` item which is stored in the server beside the
+configuration.
+
+.. _including configuration:
+
+Including configuration
+=======================
+
+Another configuration file or files, matching a pattern, can be included at
+the top level in the current file.
+
+::
+
+ include: STR
+
+.. _include:
+
+include
+-------
+
+A path or a matching pattern specifying one or more files that are included
+at the place of the include option position in the configuration.
+If the path is not absolute, then it is considered to be relative to the
+current file. The pattern can be an arbitrary string meeting POSIX *glob*
+requirements, e.g. dir/\*.conf. Matching files are processed in sorted order.
+
+*Default:* not set
+
+.. _module section:
+
+``module`` section
+==================
+
+Dynamic modules loading configuration.
+
+.. NOTE::
+ If configured with non-empty ```--with-moduledir=path``` parameter, all
+ shared modules in this directory will be automatically loaded.
+
+::
+
+ module:
+ - id: STR
+ file: STR
+
+.. _module_id:
+
+id
+--
+
+A module identifier in the form of the ``mod-`` prefix and module name suffix.
+
+.. _module_file:
+
+file
+----
+
+A path to a shared library file with the module implementation.
+
+.. WARNING::
+ If the path is not absolute, the library is searched in the set of
+ system directories. See ``man dlopen`` for more details.
+
+*Default:* ``${libdir}/knot/modules-${version}``/module_name.so
+(or ``${path}``/module_name.so if configured with ``--with-moduledir=path``)
+
+.. _server section:
+
+``server`` section
+==================
+
+General options related to the server.
+
+::
+
+ server:
+ identity: [STR]
+ version: [STR]
+ nsid: [STR|HEXSTR]
+ rundir: STR
+ user: STR[:STR]
+ pidfile: STR
+ udp-workers: INT
+ tcp-workers: INT
+ background-workers: INT
+ async-start: BOOL
+ tcp-idle-timeout: TIME
+ tcp-io-timeout: INT
+ tcp-remote-io-timeout: INT
+ tcp-max-clients: INT
+ tcp-reuseport: BOOL
+ tcp-fastopen: BOOL
+ quic-max-clients: INT
+ quic-outbuf-max-size: SIZE
+ quic-idle-close-timeout: TIME
+ remote-pool-limit: INT
+ remote-pool-timeout: TIME
+ remote-retry-delay: TIME
+ socket-affinity: BOOL
+ udp-max-payload: SIZE
+ udp-max-payload-ipv4: SIZE
+ udp-max-payload-ipv6: SIZE
+ key-file: STR
+ cert-file: STR
+ edns-client-subnet: BOOL
+ answer-rotation: BOOL
+ automatic-acl: BOOL
+ proxy-allowlist: ADDR[/INT] | ADDR-ADDR ...
+ dbus-event: none | running | zone-updated | ksk-submission | dnssec-invalid ...
+ dbus-init-delay: TIME
+ listen: ADDR[@INT] ...
+
+.. CAUTION::
+ When you change configuration parameters dynamically or via configuration file
+ reload, some parameters in the Server section require restarting the Knot server
+ so that the changes take effect. See below for the details.
+
+.. _server_identity:
+
+identity
+--------
+
+An identity of the server returned in the response to the query for TXT
+record ``id.server.`` or ``hostname.bind.`` in the CHAOS class (:rfc:`4892`).
+Set to an empty value to disable.
+
+*Default:* FQDN hostname
+
+.. _server_version:
+
+version
+-------
+
+A version of the server software returned in the response to the query
+for TXT record ``version.server.`` or ``version.bind.`` in the CHAOS
+class (:rfc:`4892`). Set to an empty value to disable.
+
+*Default:* server version
+
+.. _server_nsid:
+
+nsid
+----
+
+A DNS name server identifier (:rfc:`5001`). Set to an empty value to disable.
+
+*Default:* FQDN hostname at the moment of the daemon start
+
+.. _server_rundir:
+
+rundir
+------
+
+A path for storing run-time data (PID file, unix sockets, etc.).
+
+Depending on the usage of this parameter, its change may require restart of the Knot
+server to take effect.
+
+*Default:* ``${localstatedir}/run/knot`` (configured with ``--with-rundir=path``)
+
+.. _server_user:
+
+user
+----
+
+A system user with an optional system group (``user:group``) under which the
+server is run after starting and binding to interfaces. Linux capabilities
+are employed if supported.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* ``root:root``
+
+.. _server_pidfile:
+
+pidfile
+-------
+
+A PID file location.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* :ref:`rundir<server_rundir>`\ ``/knot.pid``
+
+.. _server_udp-workers:
+
+udp-workers
+-----------
+
+A number of UDP workers (threads) used to process incoming queries
+over UDP.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* equal to the number of online CPUs
+
+.. _server_tcp-workers:
+
+tcp-workers
+-----------
+
+A number of TCP workers (threads) used to process incoming queries
+over TCP.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* equal to the number of online CPUs, default value is at least 10
+
+.. _server_background-workers:
+
+background-workers
+------------------
+
+A number of workers (threads) used to execute background operations (zone
+loading, zone updates, etc.).
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* equal to the number of online CPUs, default value is at most 10
+
+.. _server_async-start:
+
+async-start
+-----------
+
+If enabled, server doesn't wait for the zones to be loaded and starts
+responding immediately with SERVFAIL answers until the zone loads.
+
+*Default:* ``off``
+
+.. _server_tcp-idle-timeout:
+
+tcp-idle-timeout
+----------------
+
+Maximum idle time (in seconds) between requests on an inbound TCP connection.
+It means if there is no activity on an inbound TCP connection during this limit,
+the connection is closed by the server.
+
+*Minimum:* ``1``
+
+*Default:* ``10``
+
+.. _server_tcp-io-timeout:
+
+tcp-io-timeout
+--------------
+
+Maximum time (in milliseconds) to receive or send one DNS message over an inbound
+TCP connection. It means this limit applies to normal DNS queries and replies,
+incoming DDNS, and **outgoing zone transfers**. The timeout is measured since some
+data is already available for processing.
+Set to 0 for infinity.
+
+*Default:* ``500`` (milliseconds)
+
+.. CAUTION::
+ In order to reduce the risk of Slow Loris attacks, it's recommended setting
+ this limit as low as possible on public servers.
+
+.. _server_tcp-remote-io-timeout:
+
+tcp-remote-io-timeout
+---------------------
+
+Maximum time (in milliseconds) to receive or send one DNS message over an outbound
+TCP connection which has already been established to a configured remote server.
+It means this limit applies to incoming zone transfers, sending NOTIFY,
+DDNS forwarding, and DS check or push. This timeout includes the time needed
+for a network round-trip and for a query processing by the remote.
+Set to 0 for infinity.
+
+*Default:* ``5000`` (milliseconds)
+
+.. _server_tcp-reuseport:
+
+tcp-reuseport
+-------------
+
+If enabled, each TCP worker listens on its own socket and the OS kernel
+socket load balancing is employed using SO_REUSEPORT (or SO_REUSEPORT_LB
+on FreeBSD). Due to the lack of one shared socket, the server can offer
+higher response rate processing over TCP. However, in the case of
+time-consuming requests (e.g. zone transfers of a TLD zone), enabled reuseport
+may result in delayed or not being responded client requests. So it is
+advisable to use this option on secondary servers.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* ``off``
+
+.. _server_tcp-fastopen:
+
+tcp-fastopen
+------------
+
+If enabled, use TCP Fast Open for outbound TCP communication (client side):
+incoming zone transfers, sending NOTIFY, and DDNS forwarding. This mode simplifies
+TCP handshake and can result in better networking performance. TCP Fast Open
+for inbound TCP communication (server side) isn't affected by this
+configuration as it's enabled automatically if supported by OS.
+
+.. NOTE::
+ The TCP Fast Open support must also be enabled on the OS level:
+
+ * Linux/macOS: ensure kernel parameter ``net.ipv4.tcp_fastopen`` is ``2`` or
+ ``3`` for server side, and ``1`` or ``3`` for client side.
+ * FreeBSD: ensure kernel parameter ``net.inet.tcp.fastopen.server_enable``
+ is ``1`` for server side, and ``net.inet.tcp.fastopen.client_enable`` is
+ ``1`` for client side.
+
+*Default:* ``off``
+
+.. _server_quic-max-clients:
+
+quic-max-clients
+----------------
+
+A maximum number of QUIC clients connected in parallel.
+
+See also :ref:`xdp_quic`.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Minimum:* ``128``
+
+*Default:* ``10000`` (ten thousand)
+
+.. _server_quic-outbuf-max-size:
+
+quic-outbuf-max-size
+--------------------
+
+Maximum cumulative size of memory used for buffers of unACKed
+sent messages.
+
+.. NOTE::
+ Set low if little memory is available (together with :ref:`server_quic-max-clients`
+ since QUIC connections are memory-heavy). Set to high value if outgoing zone
+ transfers of big zone over QUIC are expected.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Minimum:* ``1M`` (1 MiB)
+
+*Default:* ``100M`` (100 MiB)
+
+.. _server_quic-idle-close-timeout:
+
+quic-idle-close-timeout
+-----------------------
+
+Time in seconds, after which any idle QUIC connection is gracefully closed.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Minimum:* ``1``
+
+*Default:* ``4``
+
+.. _server_remote-pool-limit:
+
+remote-pool-limit
+-----------------
+
+If nonzero, the server will keep up to this number of outgoing TCP connections
+open for later use. This is an optimization to avoid frequent opening of
+TCP connections to the same remote.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* ``0``
+
+.. _server_remote-pool-timeout:
+
+remote-pool-timeout
+-------------------
+
+The timeout in seconds after which the unused kept-open outgoing TCP connections
+to remote servers are closed.
+
+*Default:* ``5``
+
+.. _server_remote-retry-delay:
+
+remote-retry-delay
+------------------
+
+When a connection attempt times out to some remote address, this information will be
+kept for this specified time (in milliseconds) and other connections to the same address won't
+be attempted. This prevents repetitive waiting for timeout on an unreachable remote.
+
+*Default:* ``0``
+
+.. _server_socket-affinity:
+
+socket-affinity
+---------------
+
+If enabled and if SO_REUSEPORT is available on Linux, all configured network
+sockets are bound to UDP and TCP workers in order to increase the networking performance.
+This mode isn't recommended for setups where the number of network card queues
+is lower than the number of UDP or TCP workers.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* ``off``
+
+.. _server_tcp-max-clients:
+
+tcp-max-clients
+---------------
+
+A maximum number of TCP clients connected in parallel, set this below the file
+descriptor limit to avoid resource exhaustion.
+
+.. NOTE::
+ It is advisable to adjust the maximum number of open files per process in your
+ operating system configuration.
+
+*Default:* one half of the file descriptor limit for the server process
+
+.. _server_udp-max-payload:
+
+udp-max-payload
+---------------
+
+Maximum EDNS0 UDP payload size default for both IPv4 and IPv6.
+
+*Default:* ``1232``
+
+.. _server_udp-max-payload-ipv4:
+
+udp-max-payload-ipv4
+--------------------
+
+Maximum EDNS0 UDP payload size for IPv4.
+
+*Default:* ``1232``
+
+.. _server_udp-max-payload-ipv6:
+
+udp-max-payload-ipv6
+--------------------
+
+Maximum EDNS0 UDP payload size for IPv6.
+
+*Default:* ``1232``
+
+.. _server_key-file:
+
+key-file
+--------
+
+Path to a server key PEM file which is used for DNS over QUIC communication.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* one-time in-memory key
+
+.. _server_cert-file:
+
+cert-file
+---------
+
+Path to a server certificate PEM file which is used for DNS over QUIC communication.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* one-time in-memory certificate
+
+.. _server_edns-client-subnet:
+
+edns-client-subnet
+------------------
+
+Enable or disable EDNS Client Subnet support. If enabled, responses to queries
+containing the EDNS Client Subnet option
+always contain a valid EDNS Client Subnet option according to :rfc:`7871`.
+
+*Default:* ``off``
+
+.. _server_answer-rotation:
+
+answer-rotation
+---------------
+
+Enable or disable sorted-rrset rotation in the answer section of normal replies.
+The rotation shift is simply determined by a query ID.
+
+*Default:* ``off``
+
+.. _server_automatic-acl:
+
+automatic-acl
+-------------
+
+If enabled, :ref:`automatic ACL<remote_automatic-acl>` setting of
+configured remotes is considered when evaluating authorized operations.
+
+*Default:* ``off``
+
+.. _server_proxy-allowlist:
+
+proxy-allowlist
+---------------
+
+An ordered list of IP addresses, network subnets, or network ranges
+which are allowed as a source address of proxied DNS traffic over UDP.
+The supported proxy protocol is
+`haproxy PROXY v2 <https://www.haproxy.org/download/2.5/doc/proxy-protocol.txt>`_.
+
+.. NOTE::
+ TCP is not supported.
+
+*Default:* not set
+
+.. _server_dbus-event:
+
+dbus-event
+----------
+
+Specification of server or zone states which emit a D-Bus signal on the system
+bus. The bus name is ``cz.nic.knotd``, the object path is ``/cz/nic/knotd``, and
+the interface name is ``cz.nic.knotd.events``.
+
+Possible values:
+
+- ``none`` – No signal is emitted.
+- ``running`` – The signal ``started`` is emitted when the server is fully operational
+ and the signal ``stopped`` is emitted at the beginning of the server shutdown.
+- ``zone-updated`` – The signal ``zone_updated`` is emitted when a zone has been updated;
+ the signal parameters are `zone name` and `zone SOA serial`.
+- ``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`.
+
+.. NOTE::
+ This function requires systemd version at least 221.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* ``none``
+
+.. _server_dbus-init-delay:
+
+dbus-init-delay
+---------------
+
+Time in seconds which the server waits upon D-Bus initialization to ensure
+the D-Bus client is ready to receive signals.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Minimum:* ``0``
+
+*Default:* ``1``
+
+.. _server_listen:
+
+listen
+------
+
+One or more IP addresses where the server listens for incoming queries.
+Optional port specification (default is 53) can be appended to each address
+using ``@`` separator. Use ``0.0.0.0`` for all configured IPv4 addresses or
+``::`` for all configured IPv6 addresses. Filesystem path can be specified
+for listening on local unix SOCK_STREAM socket. Non-local address binding
+is automatically enabled if supported by the operating system.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* not set
+
+.. _xdp section:
+
+``xdp`` section
+===============
+
+Various options related to XDP listening, especially TCP.
+
+::
+
+ xdp:
+ listen: STR[@INT] | ADDR[@INT] ...
+ udp: BOOL
+ tcp: BOOL
+ quic: BOOL
+ quic-port: INT
+ quic-log: BOOL
+ tcp-max-clients: INT
+ tcp-inbuf-max-size: SIZE
+ tcp-outbuf-max-size: SIZE
+ tcp-idle-close-timeout: TIME
+ tcp-idle-reset-timeout: TIME
+ tcp-resend-timeout: TIME
+ route-check: BOOL
+
+.. CAUTION::
+ When you change configuration parameters dynamically or via configuration file
+ reload, some parameters in the XDP section require restarting the Knot server
+ so that the changes take effect.
+
+.. _xdp_listen:
+
+listen
+------
+
+One or more network device names (e.g. ``ens786f0``) on which the :ref:`Mode XDP`
+is enabled. Alternatively, an IP address can be used instead of a device name,
+but the server will still listen on all addresses belonging to the same interface!
+Optional port specification (default is 53) can be appended to each device name
+or address using ``@`` separator.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+.. CAUTION::
+ If XDP workers only process regular DNS traffic over UDP, it is strongly
+ recommended to also :ref:`listen <server_listen>` on the addresses which are
+ intended to offer the DNS service, at least to fulfil the DNS requirement for
+ working TCP.
+
+*Default:* not set
+
+.. _xdp_udp:
+
+udp
+---
+
+If enabled, DNS over UDP is processed with XDP workers.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* ``on``
+
+.. _xdp_tcp:
+
+tcp
+---
+
+If enabled, DNS over TCP traffic is processed with XDP workers.
+
+The TCP stack limitations:
+
+ - Congestion control is not implemented.
+ - Lost packets that do not contain TCP payload may not be resend.
+ - Not optimized for transfers of non-trivial zones.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* ``off``
+
+.. _xdp_quic:
+
+quic
+----
+
+If enabled, DNS over QUIC is processed with XDP workers.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* ``off``
+
+.. _xdp_quic-port:
+
+quic-port
+---------
+
+DNS over QUIC will listen on the interfaces configured by :ref:`xdp_listen`,
+but on different port, configured by this option.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* ``853``
+
+.. _xdp_quic-log:
+
+quic-log
+--------
+
+Triggers extensive logging of all QUIC protocol internals for every connection.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+*Default:* ``off``
+
+.. _xdp_tcp-max-clients:
+
+tcp-max-clients
+---------------
+
+A maximum number of TCP clients connected in parallel.
+
+*Minimum:* ``1024``
+
+*Default:* ``1000000`` (one million)
+
+.. _xdp_tcp-inbuf-max-size:
+
+tcp-inbuf-max-size
+------------------
+
+Maximum cumulative size of memory used for buffers of incompletely
+received messages.
+
+*Minimum:* ``1M`` (1 MiB)
+
+*Default:* ``100M`` (100 MiB)
+
+.. _xdp_tcp-outbuf-max-size:
+
+tcp-outbuf-max-size
+-------------------
+
+Maximum cumulative size of memory used for buffers of unACKed
+sent messages.
+
+*Minimum:* ``1M`` (1 MiB)
+
+*Default:* ``100M`` (100 MiB)
+
+.. _xdp_tcp-idle-close-timeout:
+
+tcp-idle-close-timeout
+----------------------
+
+Time in seconds, after which any idle connection is gracefully closed.
+
+*Minimum:* ``1``
+
+*Default:* ``10``
+
+.. _xdp_tcp-idle-reset-timeout:
+
+tcp-idle-reset-timeout
+----------------------
+
+Time in seconds, after which any idle connection is forcibly closed.
+
+*Minimum:* ``1``
+
+*Default:* ``20``
+
+.. _xdp_tcp-resend-timeout:
+
+tcp-resend-timeout
+------------------
+
+Resend outgoing data packets (with DNS response payload) if not ACKed
+before this timeout.
+
+*Minimum:* ``1``
+
+*Default:* ``5``
+
+.. _xdp_route-check:
+
+route-check
+-----------
+
+If enabled, routing information from the operating system is considered
+when processing every incoming DNS packet received over the XDP interface:
+
+- If the outgoing interface of the corresponding DNS response differs from
+ the incoming one, the packet is processed normally by UDP/TCP workers
+ (XDP isn't used).
+- If the destination address is blackholed, unreachable, or prohibited,
+ the DNS packet is dropped without any response.
+- The destination MAC address and possible VLAN tag for the response are taken
+ from the routing system.
+
+If disabled, symmetrical routing is applied. It means that the query source
+MAC address is used as a response destination MAC address. Possible VLAN tag
+is preserved.
+
+Change of this parameter requires restart of the Knot server to take effect.
+
+.. NOTE::
+ This mode requires forwarding enabled on the loopback interface
+ (``sysctl -w net.ipv4.conf.lo.forwarding=1`` and ``sysctl -w net.ipv6.conf.lo.forwarding=1``).
+ If forwarding is disabled, all incoming DNS packets are dropped!
+
+ Only VLAN 802.1Q is supported.
+
+*Default:* ``off``
+
+.. _control section:
+
+``control`` section
+===================
+
+Configuration of the server control interface.
+
+::
+
+ control:
+ listen: STR
+ timeout: TIME
+
+.. _control_listen:
+
+listen
+------
+
+A UNIX socket path where the server listens for control commands.
+
+*Default:* :ref:`rundir<server_rundir>`\ ``/knot.sock``
+
+.. _control_timeout:
+
+timeout
+-------
+
+Maximum time (in seconds) the control socket operations can take.
+Set to 0 for infinity.
+
+*Default:* ``5``
+
+.. _log section:
+
+``log`` section
+===============
+
+Server can be configured to log to the standard output, standard error
+output, syslog (or systemd journal if systemd is enabled) or into an arbitrary
+file.
+
+There are 6 logging severity levels:
+
+- ``critical`` – Non-recoverable error resulting in server shutdown.
+- ``error`` – Recoverable error, action should be taken.
+- ``warning`` – Warning that might require user action.
+- ``notice`` – Server notice or hint.
+- ``info`` – Informational message.
+- ``debug`` – Debug or detailed message.
+
+In the case of a missing log section, ``warning`` or more serious messages
+will be logged to both standard error output and syslog. The ``info`` and
+``notice`` messages will be logged to standard output.
+
+::
+
+ log:
+ - target: stdout | stderr | syslog | STR
+ server: critical | error | warning | notice | info | debug
+ control: critical | error | warning | notice | info | debug
+ zone: critical | error | warning | notice | info | debug
+ any: critical | error | warning | notice | info | debug
+
+.. _log_target:
+
+target
+------
+
+A logging output.
+
+Possible values:
+
+- ``stdout`` – Standard output.
+- ``stderr`` – Standard error output.
+- ``syslog`` – Syslog or systemd journal.
+- *file\_name* – A specific file.
+
+With ``syslog`` target, syslog service is used. However, if Knot DNS has been compiled
+with systemd support and operating system has been booted with systemd, systemd journal
+is used for logging instead of syslog.
+
+.. _log_server:
+
+server
+------
+
+Minimum severity level for messages related to general operation of the server to be
+logged.
+
+*Default:* not set
+
+.. _log_control:
+
+control
+-------
+
+Minimum severity level for messages related to server control to be logged.
+
+*Default:* not set
+
+.. _log_zone:
+
+zone
+----
+
+Minimum severity level for messages related to zones to be logged.
+
+*Default:* not set
+
+.. _log_any:
+
+any
+---
+
+Minimum severity level for all message types to be logged.
+
+*Default:* not set
+
+.. _stats section:
+
+``stats`` section
+=================
+
+Periodic server statistics dumping.
+
+::
+
+ statistics:
+ timer: TIME
+ file: STR
+ append: BOOL
+
+.. _statistics_timer:
+
+timer
+-----
+
+A period after which all available statistics metrics will by written to the
+:ref:`file<statistics_file>`.
+
+*Default:* not set
+
+.. _statistics_file:
+
+file
+----
+
+A file path of statistics output in the YAML format.
+
+*Default:* :ref:`rundir<server_rundir>`\ ``/stats.yaml``
+
+.. _statistics_append:
+
+append
+------
+
+If enabled, the output will be appended to the :ref:`file<statistics_file>`
+instead of file replacement.
+
+*Default:* ``off``
+
+.. _database section:
+
+``database`` section
+====================
+
+Configuration of databases for zone contents, DNSSEC metadata, or event timers.
+
+::
+
+ database:
+ storage: STR
+ journal-db: STR
+ journal-db-mode: robust | asynchronous
+ journal-db-max-size: SIZE
+ kasp-db: STR
+ kasp-db-max-size: SIZE
+ timer-db: STR
+ timer-db-max-size: SIZE
+ catalog-db: str
+ catalog-db-max-size: SIZE
+
+.. _database_storage:
+
+storage
+-------
+
+A data directory for storing journal, KASP, and timer databases.
+
+*Default:* ``${localstatedir}/lib/knot`` (configured with ``--with-storage=path``)
+
+.. _database_journal-db:
+
+journal-db
+----------
+
+An explicit specification of the persistent journal database directory.
+Non-absolute path (i.e. not starting with ``/``) is relative to
+:ref:`storage<database_storage>`.
+
+*Default:* :ref:`storage<database_storage>`\ ``/journal``
+
+.. _database_journal-db-mode:
+
+journal-db-mode
+---------------
+
+Specifies journal LMDB backend configuration, which influences performance
+and durability.
+
+Possible values:
+
+- ``robust`` – The journal database disk synchronization ensures database
+ durability but is generally slower.
+- ``asynchronous`` – The journal database disk synchronization is optimized for
+ better performance at the expense of lower database durability in the case of
+ a crash. This mode is recommended on secondary servers with many zones.
+
+*Default:* ``robust``
+
+.. _database_journal-db-max-size:
+
+journal-db-max-size
+-------------------
+
+The hard limit for the journal database maximum size. There is no cleanup logic
+in journal to recover from reaching this limit. Journal simply starts refusing
+changes across all zones. Decreasing this value has no effect if it is lower
+than the actual database file size.
+
+It is recommended to limit :ref:`journal-max-usage<zone_journal-max-usage>`
+per-zone instead of :ref:`journal-db-max-size<database_journal-db-max-size>`
+in most cases. Please keep this value larger than the sum of all zones'
+journal usage limits. See more details regarding
+:ref:`journal behaviour<Journal behaviour>`.
+
+.. NOTE::
+ This value also influences server's usage of virtual memory.
+
+*Default:* ``20G`` (20 GiB), or ``512M`` (512 MiB) for 32-bit
+
+.. _database_kasp-db:
+
+kasp-db
+-------
+
+An explicit specification of the KASP database directory.
+Non-absolute path (i.e. not starting with ``/``) is relative to
+:ref:`storage<database_storage>`.
+
+*Default:* :ref:`storage<database_storage>`\ ``/keys``
+
+.. _database_kasp-db-max-size:
+
+kasp-db-max-size
+----------------
+
+The hard limit for the KASP database maximum size.
+
+.. NOTE::
+ This value also influences server's usage of virtual memory.
+
+*Default:* ``500M`` (500 MiB)
+
+.. _database_timer-db:
+
+timer-db
+--------
+
+An explicit specification of the persistent timer database directory.
+Non-absolute path (i.e. not starting with ``/``) is relative to
+:ref:`storage<database_storage>`.
+
+*Default:* :ref:`storage<database_storage>`\ ``/timers``
+
+.. _database_timer-db-max-size:
+
+timer-db-max-size
+-----------------
+
+The hard limit for the timer database maximum size.
+
+.. NOTE::
+ This value also influences server's usage of virtual memory.
+
+*Default:* ``100M`` (100 MiB)
+
+.. _database_catalog-db:
+
+catalog-db
+----------
+
+An explicit specification of the zone catalog database directory.
+Only useful if :ref:`catalog-zones` are enabled.
+Non-absolute path (i.e. not starting with ``/``) is relative to
+:ref:`storage<database_storage>`.
+
+*Default:* :ref:`storage<database_storage>`\ ``/catalog``
+
+.. _database_catalog-db-max-size:
+
+catalog-db-max-size
+-------------------
+
+The hard limit for the catalog database maximum size.
+
+.. NOTE::
+ This value also influences server's usage of virtual memory.
+
+*Default:* ``20G`` (20 GiB), or ``512M`` (512 MiB) for 32-bit
+
+.. _keystore section:
+
+``keystore`` section
+====================
+
+DNSSEC keystore configuration.
+
+::
+
+ keystore:
+ - id: STR
+ backend: pem | pkcs11
+ config: STR
+ key-label: BOOL
+
+.. _keystore_id:
+
+id
+--
+
+A keystore identifier.
+
+
+.. _keystore_backend:
+
+backend
+-------
+
+A key storage backend type.
+
+Possible values:
+
+- ``pem`` – PEM files.
+- ``pkcs11`` – PKCS #11 storage.
+
+*Default:* ``pem``
+
+.. _keystore_config:
+
+config
+------
+
+A backend specific configuration. A directory with PEM files (the path can
+be specified as a relative path to :ref:`kasp-db<database_kasp-db>`) or
+a configuration string for PKCS #11 storage (`<pkcs11-url> <module-path>`).
+
+.. NOTE::
+ Example configuration string for PKCS #11::
+
+ "pkcs11:token=knot;pin-value=1234 /usr/lib64/pkcs11/libsofthsm2.so"
+
+*Default:* :ref:`kasp-db<database_kasp-db>`\ ``/keys``
+
+.. _keystore_key-label:
+
+key-label
+---------
+
+If enabled in combination with the PKCS #11 :ref:`keystore_backend`, generated keys
+are labeled in the form ``<zone_name> KSK|ZSK``.
+
+*Default:* ``off``
+
+.. _key section:
+
+``key`` section
+===============
+
+Shared TSIG keys used to authenticate communication with the server.
+
+::
+
+ key:
+ - id: DNAME
+ algorithm: hmac-md5 | hmac-sha1 | hmac-sha224 | hmac-sha256 | hmac-sha384 | hmac-sha512
+ secret: BASE64
+
+.. _key_id:
+
+id
+--
+
+A key name identifier.
+
+.. NOTE::
+ This value MUST be exactly the same as the name of the TSIG key on the
+ opposite primary/secondary server(s).
+
+.. _key_algorithm:
+
+algorithm
+---------
+
+A TSIG key algorithm. See
+`TSIG Algorithm Numbers <https://www.iana.org/assignments/tsig-algorithm-names/tsig-algorithm-names.xhtml>`_.
+
+Possible values:
+
+- ``hmac-md5``
+- ``hmac-sha1``
+- ``hmac-sha224``
+- ``hmac-sha256``
+- ``hmac-sha384``
+- ``hmac-sha512``
+
+*Default:* not set
+
+.. _key_secret:
+
+secret
+------
+
+Shared key secret.
+
+*Default:* not set
+
+.. _remote section:
+
+``remote`` section
+==================
+
+Definitions of remote servers for outgoing connections (source of a zone
+transfer, target for a notification, etc.).
+
+::
+
+ remote:
+ - id: STR
+ address: ADDR[@INT] ...
+ via: ADDR[@INT] ...
+ key: key_id
+ block-notify-after-transfer: BOOL
+ no-edns: BOOL
+ automatic-acl: BOOL
+
+.. _remote_id:
+
+id
+--
+
+A remote identifier.
+
+.. _remote_address:
+
+address
+-------
+
+An ordered list of destination IP addresses which are used for communication
+with the remote server. The addresses are tried in sequence until the
+remote is reached. Optional destination port (default is 53)
+can be appended to the address using ``@`` separator.
+
+*Default:* not set
+
+.. NOTE::
+ If the remote is contacted and it refuses to perform requested action,
+ no more addresses will be tried for this remote.
+
+.. _remote_via:
+
+via
+---
+
+An ordered list of source IP addresses. The first address with the same family
+as the destination address is used as a source address for communication with
+the remote. This option can help if the server listens on more addresses.
+Optional source port (default is random) can be appended
+to the address using ``@`` separator.
+
+*Default:* not set
+
+.. _remote_key:
+
+key
+---
+
+A :ref:`reference<key_id>` to the TSIG key which is used to authenticate
+the communication with the remote server.
+
+*Default:* not set
+
+.. _remote_block-notify-after-transfer:
+
+block-notify-after-transfer
+---------------------------
+
+When incoming AXFR/IXFR from this remote (as a primary server), suppress
+sending NOTIFY messages to all configured secondary servers.
+
+*Default:* ``off``
+
+.. _remote_no-edns:
+
+no-edns
+-------
+
+If enabled, no OPT record (EDNS) is inserted to outgoing requests to this
+remote server. This mode is necessary for communication with some broken
+implementations (e.g. Windows Server 2016).
+
+.. NOTE::
+ This option effectively disables :ref:`zone expire<Zone expiration>` timer
+ updates via EDNS EXPIRE option specified in :rfc:`7314`.
+
+*Default:* ``off``
+
+.. _remote_automatic-acl:
+
+automatic-acl
+-------------
+
+If enabled, some authorized operations for the remote are automatically allowed
+based on the context:
+
+- Incoming NOTIFY is allowed from the remote if it's configured as a
+ :ref:`primary server <zone_master>` for the zone.
+- Outgoing zone transfer is allowed to the remote if it's configured as a
+ :ref:`NOTIFY target <zone_notify>` for the zone.
+
+Automatic ACL rules are evaluated before explicit :ref:`zone ACL <zone_acl>` configuration.
+
+.. NOTE::
+ This functionality requires global activation via
+ :ref:`server_automatic-acl` in the server section.
+
+*Default:* ``on``
+
+.. _remotes section:
+
+``remotes`` section
+===================
+
+Definitions of groups of remote servers. Remote grouping can simplify the
+configuration.
+
+::
+
+ remotes:
+ - id: STR
+ remote: remote_id ...
+
+.. _remotes_id:
+
+id
+--
+
+A remote group identifier.
+
+.. _remotes_remote:
+
+remote
+------
+
+An ordered list of :ref:`references<remote_id>` to remote server definitions.
+
+*Default:* not set
+
+.. _acl section:
+
+``acl`` section
+===============
+
+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.
+
+::
+
+ acl:
+ - id: STR
+ address: ADDR[/INT] | ADDR-ADDR ...
+ key: key_id ...
+ remote: remote_id | remotes_id ...
+ action: query | notify | transfer | update ...
+ deny: BOOL
+ update-type: STR ...
+ update-owner: key | zone | name
+ update-owner-match: sub-or-equal | equal | sub
+ update-owner-name: STR ...
+
+.. _acl_id:
+
+id
+--
+
+An ACL rule identifier.
+
+.. _acl_address:
+
+address
+-------
+
+An ordered list of IP addresses, network subnets, or network ranges. The query's
+source address must match one of them. If this item is not set, address match is not
+required.
+
+*Default:* not set
+
+.. _acl_key:
+
+key
+---
+
+An ordered list of :ref:`reference<key_id>`\ s to TSIG keys. The query must
+match one of them. If this item is not set, transaction authentication is not used.
+
+*Default:* not set
+
+.. _acl_remote:
+
+remote
+------
+
+An ordered list of references :ref:`remote<remote_id>` and
+:ref:`remotes<remotes_id>`. The query must
+match one of the remotes. Specifically, one of the remote's addresses and remote's
+TSIG key if configured must match.
+
+.. NOTE::
+ This option cannot be specified along with the :ref:`acl_address` or
+ :ref:`acl_key` option at one ACL item.
+
+*Default:* not set
+
+.. _acl_action:
+
+action
+------
+
+An ordered list of allowed (or denied) actions.
+
+Possible values:
+
+- ``query`` – Allow regular DNS query. As normal queries are always allowed,
+ this action is only useful in combination with :ref:`TSIG key<acl_key>`.
+- ``notify`` – Allow incoming notify (NOTIFY).
+- ``transfer`` – Allow zone transfer (AXFR, IXFR).
+- ``update`` – Allow zone updates (DDNS).
+
+*Default:* ``query``
+
+.. _acl_deny:
+
+deny
+----
+
+If enabled, instead of allowing, deny the specified :ref:`action<acl_action>`,
+:ref:`address<acl_address>`, :ref:`key<acl_key>`, or combination if these
+items. If no action is specified, deny all actions.
+
+*Default:* ``off``
+
+.. _acl_update-type:
+
+update-type
+-----------
+
+A list of allowed types of Resource Records in a zone update. Every record in an update
+must match one of the specified types.
+
+*Default:* not set
+
+.. _acl_update-owner:
+
+update-owner
+------------
+
+This option restricts possible owners of Resource Records in a zone update by comparing
+them to either the :ref:`TSIG key<acl_key>` identity, the current zone name, or to a list of
+domain names given by the :ref:`acl_update-owner-name` option.
+The comparison method is given by the :ref:`acl_update-owner-match` option.
+
+Possible values:
+
+- ``key`` — The owner of each updated RR must match the identity of the TSIG key if used.
+- ``name`` — The owner of each updated RR must match at least one name in the
+ :ref:`acl_update-owner-name` list.
+- ``zone`` — The owner of each updated RR must match the current zone name.
+
+*Default:* not set
+
+.. _acl_update-owner-match:
+
+update-owner-match
+------------------
+
+This option defines how the owners of Resource Records in an update are matched to the domain name(s)
+set by the :ref:`acl_update-owner` option.
+
+Possible values:
+
+- ``sub-or-equal`` — The owner of each RR in an update must either be equal to
+ or be a subdomain of at least one domain name set by :ref:`acl_update-owner`.
+- ``equal`` — The owner of each updated RR must be equal to at least one domain
+ name set by :ref:`acl_update-owner`.
+- ``sub`` — The owner of each updated RR must be a subdomain of, but MUST NOT
+ be equal to at least one domain name set by :ref:`acl_update-owner`.
+
+*Default:* ``sub-or-equal``
+
+.. _acl_update-owner-name:
+
+update-owner-name
+-----------------
+
+A list of allowed owners of RRs in a zone update used with :ref:`acl_update-owner`
+set to ``name``. Every listed owner name which is not FQDN (i.e. it doesn't end
+in a dot) is considered as if it was appended with the target zone name.
+Such a relative owner name specification allows better ACL rule reusability across
+multiple zones.
+
+*Default:* not set
+
+.. _submission section:
+
+``submission`` section
+======================
+
+Parameters of KSK submission checks.
+
+::
+
+ submission:
+ - id: STR
+ parent: remote_id | remotes_id ...
+ check-interval: TIME
+ timeout: TIME
+ parent-delay: TIME
+
+.. _submission_id:
+
+id
+--
+
+A submission identifier.
+
+.. _submission_parent:
+
+parent
+------
+
+A list of references :ref:`remote<remote_id>` and :ref:`remotes<remotes_id>`
+to parent's DNS servers to be checked for
+presence of corresponding DS records in the case of KSK submission. All of them must
+have a corresponding DS for the rollover to continue. If none is specified, the
+rollover must be pushed forward manually.
+
+*Default:* not set
+
+.. TIP::
+ A DNSSEC-validating resolver can be set as a parent.
+
+.. _submission_check-interval:
+
+check-interval
+--------------
+
+Interval for periodic checks of DS presence on parent's DNS servers, in the
+case of the KSK submission.
+
+*Default:* ``1h`` (1 hour)
+
+.. _submission_timeout:
+
+timeout
+-------
+
+After this time period (in seconds) the KSK submission is automatically considered
+successful, even if all the checks were negative or no parents are configured.
+Set to 0 for infinity.
+
+*Default:* ``0``
+
+.. _submission_parent-delay:
+
+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.
+
+*Default:* ``0``
+
+.. _policy section:
+
+``policy`` section
+==================
+
+DNSSEC policy configuration.
+
+::
+
+ policy:
+ - id: STR
+ keystore: keystore_id
+ manual: BOOL
+ single-type-signing: BOOL
+ algorithm: rsasha1 | rsasha1-nsec3-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384 | ed25519 | ed448
+ ksk-size: SIZE
+ zsk-size: SIZE
+ ksk-shared: BOOL
+ dnskey-ttl: TIME
+ zone-max-ttl: TIME
+ ksk-lifetime: TIME
+ zsk-lifetime: TIME
+ delete-delay: TIME
+ propagation-delay: TIME
+ rrsig-lifetime: TIME
+ rrsig-refresh: TIME
+ rrsig-pre-refresh: TIME
+ reproducible-signing: BOOL
+ nsec3: BOOL
+ nsec3-iterations: INT
+ nsec3-opt-out: BOOL
+ nsec3-salt-length: INT
+ nsec3-salt-lifetime: TIME
+ signing-threads: INT
+ ksk-submission: submission_id
+ ds-push: remote_id | remotes_id ...
+ cds-cdnskey-publish: none | delete-dnssec | rollover | always | double-ds
+ cds-digest-type: sha256 | sha384
+ dnskey-management: full | incremental
+ offline-ksk: BOOL
+ unsafe-operation: none | no-check-keyset | no-update-dnskey | no-update-nsec | no-update-expired ...
+
+.. _policy_id:
+
+id
+--
+
+A policy identifier.
+
+.. _policy_keystore:
+
+keystore
+--------
+
+A :ref:`reference<keystore_id>` to a keystore holding private key material
+for zones.
+
+*Default:* an imaginary keystore with all default values
+
+.. NOTE::
+ A configured keystore called "default" won't be used unless explicitly referenced.
+
+.. _policy_manual:
+
+manual
+------
+
+If enabled, automatic key management is not used.
+
+*Default:* ``off``
+
+.. _policy_single-type-signing:
+
+single-type-signing
+-------------------
+
+If enabled, Single-Type Signing Scheme is used in the automatic key management
+mode.
+
+*Default:* ``off`` (:ref:`module onlinesign<mod-onlinesign>` has default ``on``)
+
+.. _policy_algorithm:
+
+algorithm
+---------
+
+An algorithm of signing keys and issued signatures. See
+`DNSSEC Algorithm Numbers <https://www.iana.org/assignments/dns-sec-alg-numbers/dns-sec-alg-numbers.xhtml#dns-sec-alg-numbers-1>`_.
+
+Possible values:
+
+- ``rsasha1``
+- ``rsasha1-nsec3-sha1``
+- ``rsasha256``
+- ``rsasha512``
+- ``ecdsap256sha256``
+- ``ecdsap384sha384``
+- ``ed25519``
+- ``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``
+
+.. _policy_ksk-size:
+
+ksk-size
+--------
+
+A length of newly generated :abbr:`KSK (Key Signing Key)` or
+:abbr:`CSK (Combined Signing Key)` keys.
+
+*Default:* ``2048`` (rsa*), ``256`` (ecdsap256), ``384`` (ecdsap384), ``256`` (ed25519),
+``456`` (ed448)
+
+.. _policy_zsk-size:
+
+zsk-size
+--------
+
+A length of newly generated :abbr:`ZSK (Zone Signing Key)` keys.
+
+*Default:* see default for :ref:`ksk-size<policy_ksk-size>`
+
+.. _policy_ksk-shared:
+
+ksk-shared
+----------
+
+If enabled, all zones with this policy assigned will share one or more KSKs.
+More KSKs can be shared during a KSK rollover.
+
+.. WARNING::
+ As the shared KSK set is bound to the policy :ref:`id<policy_id>`, renaming the
+ policy breaks this connection and new shared KSK set is initiated when
+ a new KSK is needed.
+
+*Default:* ``off``
+
+.. _policy_dnskey-ttl:
+
+dnskey-ttl
+----------
+
+A TTL value for DNSKEY records added into zone apex.
+
+.. NOTE::
+ Has influence over ZSK key lifetime.
+
+.. WARNING::
+ Ensure all DNSKEYs with updated TTL are propagated before any subsequent
+ DNSKEY rollover starts.
+
+*Default:* zone SOA TTL
+
+.. _policy_zone-max-ttl:
+
+zone-max-ttl
+------------
+
+Declare (override) maximal TTL value among all the records in zone.
+
+.. NOTE::
+ It's generally recommended to override the maximal TTL computation by setting this
+ explicitly whenever possible. It's required for :ref:`DNSSEC Offline KSK` and
+ really reasonable when records are generated dynamically
+ (e.g. by a :ref:`module<mod-synthrecord>`).
+
+*Default:* computed after zone is loaded
+
+.. _policy_ksk-lifetime:
+
+ksk-lifetime
+------------
+
+A period between KSK activation and the next rollover initiation.
+
+.. NOTE::
+ KSK key lifetime is also influenced by propagation-delay, dnskey-ttl,
+ and KSK submission delay.
+
+ Zero (aka infinity) value causes no KSK rollover as a result.
+
+ This applies for CSK lifetime if single-type-signing is enabled.
+
+*Default:* ``0``
+
+.. _policy_zsk-lifetime:
+
+zsk-lifetime
+------------
+
+A period between ZSK activation and the next rollover initiation.
+
+.. NOTE::
+ More exactly, this period is measured since a ZSK is activated,
+ and after this, a new ZSK is generated to replace it within
+ following roll-over.
+
+ ZSK key lifetime is also influenced by propagation-delay and dnskey-ttl
+
+ Zero (aka infinity) value causes no ZSK rollover as a result.
+
+*Default:* ``30d`` (30 days)
+
+.. _policy_delete-delay:
+
+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
+is needed.
+
+*Default:* ``0``
+
+.. _policy_propagation-delay:
+
+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.
+
+.. NOTE::
+ Has influence over ZSK key lifetime.
+
+*Default:* ``1h`` (1 hour)
+
+.. _policy_rrsig-lifetime:
+
+rrsig-lifetime
+--------------
+
+A validity period of newly issued signatures.
+
+.. NOTE::
+ The RRSIG's signature inception time is set to 90 minutes in the past. This
+ time period is not counted to the signature lifetime.
+
+*Default:* ``14d`` (14 days)
+
+.. _policy_rrsig-refresh:
+
+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.
+
+*Default:* :ref:`policy_propagation-delay` + :ref:`policy_zone-max-ttl`
+
+.. _policy_rrsig-pre-refresh:
+
+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).
+
+*Default:* ``1h`` (1 hour)
+
+.. _policy_reproducible-signing:
+
+reproducible-signing
+--------------------
+
+For ECDSA algorithms, generate RRSIG signatures deterministically (:rfc:`6979`).
+Besides better theoretical cryptographic security, this mode allows significant
+speed-up of loading signed (by the same method) zones. However, the zone signing
+is a bit slower.
+
+*Default:* ``off``
+
+.. _policy_nsec3:
+
+nsec3
+-----
+
+Specifies if NSEC3 will be used instead of NSEC.
+
+*Default:* ``off``
+
+.. _policy_nsec3-iterations:
+
+nsec3-iterations
+----------------
+
+A number of additional times the hashing is performed.
+
+*Default:* ``0``
+
+.. _policy_nsec3-opt-out:
+
+nsec3-opt-out
+-------------
+
+If set, NSEC3 records won't be created for insecure delegations.
+This speeds up the zone signing and reduces overall zone size.
+
+.. WARNING::
+ NSEC3 with the Opt-Out bit set no longer works as a proof of non-existence
+ in this zone.
+
+*Default:* ``off``
+
+.. _policy_nsec3-salt-length:
+
+nsec3-salt-length
+-----------------
+
+A length of a salt field in octets, which is appended to the original owner
+name before hashing.
+
+*Default:* ``8``
+
+.. _policy_nsec3-salt-lifetime:
+
+nsec3-salt-lifetime
+-------------------
+
+A validity period of newly issued salt field.
+
+Zero value means infinity.
+
+Special value *-1* triggers re-salt every time when active ZSK changes.
+This optimizes the number of big changes to the zone.
+
+*Default:* ``30d`` (30 days)
+
+.. _policy_signing-threads:
+
+signing-threads
+---------------
+
+When signing zone or update, use this number of threads for parallel signing.
+
+Those are extra threads independent of :ref:`Background workers<server_background-workers>`.
+
+.. NOTE::
+ Some steps of the DNSSEC signing operation are not parallelized.
+
+*Default:* ``1`` (no extra threads)
+
+.. _policy_ksk-submission-check:
+
+ksk-submission
+--------------
+
+A reference to :ref:`submission<submission_id>` section holding parameters of
+KSK submission checks.
+
+*Default:* not set
+
+.. _policy_ds-push:
+
+ds-push
+-------
+
+Optional references :ref:`remote<remote_id>` and :ref:`remotes<remotes_id>`
+to authoritative DNS server of the
+parent's zone. The remote server must be configured to accept DS record
+updates via DDNS. Whenever a CDS record in the local zone is changed, the
+corresponding DS record is sent as a dynamic update (DDNS) to the parent
+DNS server. All previous DS records are deleted within the DDNS message.
+It's possible to manage both child and parent zones by the same Knot DNS server.
+
+.. NOTE::
+ This feature requires :ref:`cds-cdnskey-publish<policy_cds-cdnskey-publish>`
+ not to be set to ``none``.
+
+.. NOTE::
+ The mentioned change to CDS record usually means that a KSK roll-over is running
+ and the new key being rolled-in is in "ready" state already for the period of
+ :ref:`propagation-delay<policy_propagation-delay>`.
+
+.. NOTE::
+ Module :ref:`Onlinesign<mod-onlinesign>` doesn't support DS push.
+
+*Default:* not set
+
+.. _policy_cds-cdnskey-publish:
+
+cds-cdnskey-publish
+-------------------
+
+Controls if and how shall the CDS and CDNSKEY be published in the zone.
+
+Possible values:
+
+- ``none`` – Never publish any CDS or CDNSKEY records in the zone.
+- ``delete-dnssec`` – Publish special CDS and CDNSKEY records indicating turning off DNSSEC.
+- ``rollover`` – Publish CDS and CDNSKEY records for ready and not yet active KSK (submission phase of KSK rollover).
+- ``always`` – Always publish one CDS and one CDNSKEY records for the current KSK.
+- ``double-ds`` – Always publish up to two CDS and two CDNSKEY records for ready and/or active KSKs.
+
+.. NOTE::
+ If the zone keys are managed manually, the CDS and CDNSKEY rrsets may contain
+ more records depending on the keys available.
+
+.. WARNING::
+ The ``double-ds`` value does not trigger double-DS roll-over method. That method is
+ only supported when performed manually, with unset :ref:`policy_ksk-submission-check`.
+
+*Default:* ``rollover``
+
+.. _policy_cds-digest-type:
+
+cds-digest-type
+---------------
+
+Specify digest type for published CDS records.
+
+*Default:* ``sha256``
+
+.. _policy_dnskey-management:
+
+dnskey-management
+-----------------
+
+Specify how the DNSKEY, CDNSKEY, and CDS RRSets at the zone apex are handled
+when (re-)signing the zone.
+
+Possible values:
+
+- ``full`` – Upon every zone (re-)sign, delete all unknown DNSKEY, CDNSKEY, and CDS
+ records and keep just those that are related to the zone keys stored in the KASP database.
+- ``incremental`` – Keep unknown DNSKEY, CDNSKEY, and CDS records in the zone, and
+ modify server-managed records incrementally by employing changes in the KASP database.
+
+.. NOTE::
+ Prerequisites for *incremental*:
+
+ - The :ref:`Offline KSK <DNSSEC Offline KSK>` isn't supported.
+ - The :ref:`policy_delete-delay` is long enough to cover possible daemon
+ shutdown (e.g. due to server maintenance).
+ - Avoided manual deletion of keys with :doc:`keymgr<man_keymgr>`.
+
+ Otherwise there might remain some DNSKEY records in the zone, belonging to
+ deleted keys.
+
+*Default:* ``full``
+
+.. _policy_offline-ksk:
+
+offline-ksk
+-----------
+
+Specifies if :ref:`Offline KSK <DNSSEC Offline KSK>` feature is enabled.
+
+*Default:* ``off``
+
+.. _policy_unsafe-operation:
+
+unsafe-operation
+----------------
+
+Turn off some DNSSEC safety features.
+
+Possible values:
+
+- ``none`` – Nothing disabled.
+- ``no-check-keyset`` – Don't check active keys in present algorithms. This may
+ lead to violation of :rfc:`4035#section-2.2`.
+- ``no-update-dnskey`` – Don't maintain/update DNSKEY, CDNSKEY, and CDS records
+ in the zone apex according to KASP database. Juste leave them as they are in the zone.
+- ``no-update-nsec`` – Don't maintain/update NSEC/NSEC3 chain. Leave all the records
+ as they are in the zone.
+- ``no-update-expired`` – Don't update expired RRSIGs.
+
+Multiple values may be specified.
+
+.. WARNING::
+ This mode is intended for DNSSEC experts who understand the corresponding consequences.
+
+*Default:* ``none``
+
+.. _template section:
+
+``template`` section
+====================
+
+A template is shareable zone settings, which can simplify configuration by
+reducing duplicates. A special default template (with the *default* identifier)
+can be used for global zone configuration or as an implicit configuration
+if a zone doesn't have another template specified.
+
+::
+
+ template:
+ - id: STR
+ global-module: STR/STR ...
+ # All zone options (excluding 'template' item)
+
+.. NOTE::
+ If an item is explicitly specified both in the referenced template and
+ the zone, the template item value is overridden by the zone item value.
+
+.. _template_id:
+
+id
+--
+
+A template identifier.
+
+.. _template_global-module:
+
+global-module
+-------------
+
+An ordered list of references to query modules in the form of *module_name* or
+*module_name/module_id*. These modules apply to all queries.
+
+.. NOTE::
+ This option is only available in the *default* template.
+
+*Default:* not set
+
+.. _zone section:
+
+``zone`` section
+================
+
+Definition of zones served by the server.
+
+::
+
+ zone:
+ - domain: DNAME
+ template: template_id
+ storage: STR
+ file: STR
+ master: remote_id | remotes_id ...
+ ddns-master: remote_id
+ notify: remote_id | remotes_id ...
+ acl: acl_id ...
+ provide-ixfr: BOOL
+ semantic-checks: BOOL | soft
+ zonefile-sync: TIME
+ zonefile-load: none | difference | difference-no-serial | whole
+ journal-content: none | changes | all
+ journal-max-usage: SIZE
+ journal-max-depth: INT
+ zone-max-size : SIZE
+ adjust-threads: INT
+ dnssec-signing: BOOL
+ dnssec-validation: BOOL
+ dnssec-policy: policy_id
+ ds-push: remote_id | remotes_id ...
+ zonemd-verify: BOOL
+ zonemd-generate: none | zonemd-sha384 | zonemd-sha512 | remove
+ serial-policy: increment | unixtime | dateserial
+ refresh-min-interval: TIME
+ refresh-max-interval: TIME
+ retry-min-interval: TIME
+ retry-max-interval: TIME
+ expire-min-interval: TIME
+ expire-max-interval: TIME
+ catalog-role: none | interpret | generate | member
+ catalog-template: template_id ...
+ catalog-zone: DNAME
+ catalog-group: STR
+ module: STR/STR ...
+
+.. _zone_domain:
+
+domain
+------
+
+A zone name identifier.
+
+.. _zone_template:
+
+template
+--------
+
+A :ref:`reference<template_id>` to a configuration template.
+
+*Default:* not set or ``default`` (if the template exists)
+
+.. _zone_storage:
+
+storage
+-------
+
+A data directory for storing zone files.
+
+*Default:* ``${localstatedir}/lib/knot`` (configured with ``--with-storage=path``)
+
+.. _zone_file:
+
+file
+----
+
+A path to the zone file. Non-absolute path (i.e. not starting with ``/``) is
+relative to :ref:`storage<zone_storage>`.
+It is also possible to use the following formatters:
+
+- ``%c[``\ *N*\ ``]`` or ``%c[``\ *N*\ ``-``\ *M*\ ``]`` – Means the *N*\ th
+ character or a sequence of characters beginning from the *N*\ th and ending
+ with the *M*\ th character of the textual zone name (see ``%s``). The
+ indexes are counted from 0 from the left. All dots (including the terminal
+ one) are considered. If the character is not available, the formatter has no effect.
+- ``%l[``\ *N*\ ``]`` – Means the *N*\ th label of the textual zone name
+ (see ``%s``). The index is counted from 0 from the right (0 ~ TLD).
+ If the label is not available, the formatter has no effect.
+- ``%s`` – Means the current zone name in the textual representation.
+ The zone name doesn't include the terminating dot (the result for the root
+ zone is the empty string!).
+- ``%%`` – Means the ``%`` character.
+
+.. WARNING::
+ Beware of special characters which are escaped or encoded in the \\DDD form
+ where DDD is corresponding decimal ASCII code.
+
+*Default:* :ref:`storage<zone_storage>`\ ``/%s.zone``
+
+.. _zone_master:
+
+master
+------
+
+An ordered list of references :ref:`remote<remote_id>` and
+:ref:`remotes<remotes_id>` to zone primary servers
+(formerly known as master servers).
+
+*Default:* not set
+
+.. _zone_ddns-master:
+
+ddns-master
+-----------
+
+A :ref:`reference<remote_id>` to zone primary master. If not specified,
+the first :ref:`master<zone_master>` server is used.
+
+*Default:* not set
+
+.. _zone_notify:
+
+notify
+------
+
+An ordered list of references :ref:`remote<remote_id>` and
+:ref:`remotes<remotes_id>` to secondary servers to which notify
+message is sent if the zone changes.
+
+*Default:* not set
+
+.. _zone_acl:
+
+acl
+---
+
+An ordered list of :ref:`references<acl_id>` to ACL rules which can allow
+or disallow zone transfers, updates or incoming notifies.
+
+*Default:* not set
+
+.. _zone_provide-ixfr:
+
+provide-ixfr
+------------
+
+If disabled, the server is forced to respond with AXFR to IXFR queries.
+If enabled, IXFR requests are responded normally.
+
+*Default:* ``on``
+
+.. _zone_semantic-checks:
+
+semantic-checks
+---------------
+
+Selects if extra zone semantic checks are used or impacts of the mandatory checks.
+
+There are several mandatory checks which are always enabled and cannot be turned
+off. An error in a mandatory check causes the zone not to be loaded. Most of
+the mandatory checks can be weakened by setting ``soft``, which allows the zone to
+be loaded even if the check fails.
+
+If enabled, extra checks are used. These checks don't prevent the zone from loading.
+
+The mandatory checks are applied to zone files, zone transfers, and updates via
+control interface. The extra checks are applied to zone files only!
+
+Mandatory checks:
+
+- Missing SOA record at the zone apex (:rfc:`1034`) (*)
+- An extra record exists together with a CNAME record except for RRSIG and NSEC (:rfc:`1034`)
+- Multiple CNAME records with the same owner exist (:rfc:`1034`)
+- DNAME record having a record under it (:rfc:`6672`)
+- Multiple DNAME records with the same owner exist (:rfc:`6672`)
+- NS record exists together with a DNAME record (:rfc:`6672`)
+
+(*) The marked check can't be weakened by the soft mode. All other mandatory checks
+are subject to the optional soft mode.
+
+Extra checks:
+
+- Missing NS record at the zone apex
+- Missing glue A or AAAA record
+- Invalid DS or NSEC3PARAM record
+- CDS or CDNSKEY inconsistency
+- All other DNSSEC checks executed during :ref:`zone_dnssec-validation`
+
+.. NOTE::
+ The soft mode allows the refresh event to ignore a CNAME response to a SOA
+ query (malformed message) and triggers a zone bootstrap instead.
+
+*Default:* ``off``
+
+.. _zone_zonefile-sync:
+
+zonefile-sync
+-------------
+
+The time after which the current zone in memory will be synced with a zone file
+on the disk (see :ref:`file<zone_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
+DNSSEC signing. In order to completely disable automatic zone file synchronization,
+set the value to -1. In that case, it is still possible to force a manual zone flush
+using the ``-f`` option.
+
+.. NOTE::
+ If you are serving large zones with frequent updates where
+ the immediate sync with a zone file is not desirable, increase the value.
+
+*Default:* ``0`` (immediate)
+
+.. _zone_zonefile-load:
+
+zonefile-load
+-------------
+
+Selects how the zone file contents are applied during zone load.
+
+Possible values:
+
+- ``none`` – The zone file is not used at all.
+- ``difference`` – If the zone contents are already available during server start or reload,
+ the difference is computed between them and the contents of the zone file. This difference
+ is then checked for semantic errors and applied to the current zone contents.
+- ``difference-no-serial`` – Same as ``difference``, but the SOA serial in the zone file is
+ ignored, the server takes care of incrementing the serial automatically.
+- ``whole`` – Zone contents are loaded from the zone file.
+
+When ``difference`` is configured and there are no zone contents yet (cold start
+and no zone contents in the journal), it behaves the same way as ``whole``.
+
+*Default:* ``whole``
+
+.. _zone_journal-content:
+
+journal-content
+---------------
+
+Selects how the journal shall be used to store zone and its changes.
+
+Possible values:
+
+- ``none`` – The journal is not used at all.
+- ``changes`` – Zone changes history is stored in journal.
+- ``all`` – Zone contents and history is stored in journal.
+
+*Default:* ``changes``
+
+.. _zone_journal-max-usage:
+
+journal-max-usage
+-----------------
+
+Policy how much space in journal DB will the zone's journal occupy.
+
+.. NOTE::
+ Journal DB may grow far above the sum of journal-max-usage across
+ all zones, because of DB free space fragmentation.
+
+*Default:* ``100M`` (100 MiB)
+
+.. _zone_journal-max-depth:
+
+journal-max-depth
+-----------------
+
+Maximum history length of the journal.
+
+.. NOTE::
+ Zone-in-journal changeset isn't counted to the limit.
+
+*Minimum:* ``2``
+
+*Default:* ``20``
+
+.. _zone_zone-max-size:
+
+zone-max-size
+-------------
+
+Maximum size of the zone. The size is measured as size of the zone records
+in wire format without compression. The limit is enforced for incoming zone
+transfers and dynamic updates.
+
+For incremental transfers (IXFR), the effective limit for the total size of
+the records in the transfer is twice the configured value. However the final
+size of the zone must satisfy the configured value.
+
+*Default:* unlimited
+
+.. _zone_adjust-threads:
+
+adjust-threads
+--------------
+
+Parallelize internal zone adjusting procedures by using specified number of
+threads. This is useful with huge zones with NSEC3. Speedup observable at
+server startup and while processing NSEC3 re-salt.
+
+*Default:* ``1`` (no extra threads)
+
+.. _zone_dnssec-signing:
+
+dnssec-signing
+--------------
+
+If enabled, automatic DNSSEC signing for the zone is turned on.
+
+*Default:* ``off``
+
+.. _zone_dnssec-validation:
+
+dnssec-validation
+-----------------
+
+If enabled, the zone contents are validated for being correctly signed
+(including NSEC/NSEC3 chain) with DNSSEC signatures every time the zone
+is loaded or changed (including AXFR/IXFR).
+
+When the validation fails, the zone being loaded or update being applied
+is cancelled with an error, and either none or previous zone state is published.
+
+List of DNSSEC checks:
+
+- Every zone RRSet is correctly signed by at least one present DNSKEY.
+- DNSKEY RRSet is signed by KSK.
+- NSEC(3) RR exists for each name (unless opt-out) with correct bitmap.
+- Every NSEC(3) RR is linked to the lexicographically next one.
+
+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.
+
+*Default:* not set
+
+.. NOTE::
+
+ Redundant or garbage NSEC3 records are ignored.
+
+ This mode is not compatible with :ref:`zone_dnssec-signing`.
+
+.. _zone_dnssec-policy:
+
+dnssec-policy
+-------------
+
+A :ref:`reference<policy_id>` to DNSSEC signing policy.
+
+*Default:* an imaginary policy with all default values
+
+.. NOTE::
+ A configured policy called "default" won't be used unless explicitly referenced.
+
+.. _zone_ds-push:
+
+ds-push
+-------
+
+Per zone configuration of :ref:`policy_ds-push`. This option overrides possible
+per policy option.
+
+*Default:* not set
+
+.. _zone_zonemd-verify:
+
+zonemd-verify
+-------------
+
+On each zone load/update, verify that ZONEMD is present in the zone and valid.
+
+.. NOTE::
+ Zone digest calculation may take much time and CPU on large zones.
+
+*Default:* ``off``
+
+.. _zone_zonemd-generate:
+
+zonemd-generate
+---------------
+
+On each zone update, calculate ZONEMD and put it into the zone.
+
+Possible values:
+
+- ``none`` – No action regarding ZONEMD.
+- ``zonemd-sha384`` – Generate ZONEMD using SHA384 algorithm.
+- ``zonemd-sha512`` – Generate ZONEMD using SHA512 algorithm.
+- ``remove`` – Remove any ZONEMD from the zone apex.
+
+*Default:* ``none``
+
+.. _zone_serial-policy:
+
+serial-policy
+-------------
+
+Specifies how the zone serial is updated after a dynamic update or
+automatic DNSSEC signing. If the serial is changed by the dynamic update,
+no change is made.
+
+Possible values:
+
+- ``increment`` – The serial is incremented according to serial number arithmetic.
+- ``unixtime`` – The serial is set to the current unix time.
+- ``dateserial`` – The 10-digit serial (YYYYMMDDnn) is incremented, the first
+ 8 digits match the current iso-date.
+
+.. NOTE::
+ If the resulting serial for ``unixtime`` or ``dateserial`` is lower than or
+ equal to the current serial (this happens e.g. when migrating from other policy or
+ frequent updates), the serial is incremented instead.
+
+ To avoid user confusion, use ``dateserial`` only if you expect at most
+ 100 updates per day per zone and ``unixtime`` only if you expect at most
+ one update per second per zone.
+
+ Generated catalog zones use ``unixtime`` only.
+
+*Default:* ``increment`` (``unixtime`` for generated catalog zones)
+
+.. _zone_refresh-min-interval:
+
+refresh-min-interval
+--------------------
+
+Forced minimum zone refresh interval (in seconds) to avoid flooding primary server.
+
+*Minimum:* ``2``
+
+*Default:* ``2``
+
+.. _zone_refresh-max-interval:
+
+refresh-max-interval
+--------------------
+
+Forced maximum zone refresh interval (in seconds).
+
+*Default:* not set
+
+.. _zone_retry-min-interval:
+
+retry-min-interval
+------------------
+
+Forced minimum zone retry interval (in seconds) to avoid flooding primary server.
+
+*Minimum:* ``1``
+
+*Default:* ``1``
+
+.. _zone_retry-max-interval:
+
+retry-max-interval
+------------------
+
+Forced maximum zone retry interval (in seconds).
+
+*Default:* not set
+
+.. _zone_expire-min-interval:
+
+expire-min-interval
+-------------------
+
+Forced minimum zone expire interval (in seconds) to avoid flooding primary server.
+
+*Minimum:* ``3``
+
+*Default:* ``3``
+
+.. _zone_expire-max-interval:
+
+expire-max-interval
+-------------------
+
+Forced maximum zone expire interval (in seconds).
+
+*Default:* not set
+
+.. _zone_catalog-role:
+
+catalog-role
+------------
+
+Trigger zone catalog feature. Possible values:
+
+- ``none`` – Not a catalog zone.
+- ``interpret`` – A catalog zone which is loaded from a zone file or XFR,
+ and member zones shall be configured based on its contents.
+- ``generate`` – A catalog zone whose contents are generated according to
+ assigned member zones.
+- ``member`` – A member zone that is assigned to one generated catalog zone.
+
+*Default:* ``none``
+
+.. _zone_catalog-template:
+
+catalog-template
+----------------
+
+For the catalog member zones, the specified configuration template will be applied.
+
+Multiple catalog templates may be defined. The first one is used unless the member zone
+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.
+
+*Default:* not set
+
+.. _zone_catalog-zone:
+
+catalog-zone
+------------
+
+Assign this member zone to specified generated catalog zone.
+
+.. NOTE::
+ This option must be set if and only if :ref:`zone_catalog-role` is *member*.
+
+ The referenced catalog zone must exist and have :ref:`zone_catalog-role` set to *generate*.
+
+*Default:* not set
+
+.. _zone_catalog-group:
+
+catalog-group
+-------------
+
+Assign this member zone to specified catalog group (configuration template).
+
+.. NOTE::
+ This option has effect if and only if :ref:`zone_catalog-role` is *member*.
+
+*Default:* not set
+
+.. _zone_module:
+
+module
+------
+
+An ordered list of references to query modules in the form of *module_name* or
+*module_name/module_id*. These modules apply only to the current zone queries.
+
+*Default:* not set