diff options
Diffstat (limited to 'doc/man/knot.conf.5in')
| -rw-r--r-- | doc/man/knot.conf.5in | 2826 |
1 files changed, 2826 insertions, 0 deletions
diff --git a/doc/man/knot.conf.5in b/doc/man/knot.conf.5in new file mode 100644 index 0000000..72f0a4a --- /dev/null +++ b/doc/man/knot.conf.5in @@ -0,0 +1,2826 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "KNOT.CONF" "5" "@RELEASE_DATE@" "@VERSION@" "Knot DNS" +.SH NAME +knot.conf \- Knot DNS configuration file +.SH DESCRIPTION +.sp +Configuration files for Knot DNS use simplified YAML format. Simplified means +that not all of the features are supported. +.sp +For the description of configuration items, we have to declare a meaning of +the following symbols: +.INDENT 0.0 +.IP \(bu 2 +\fBINT\fP – Integer +.IP \(bu 2 +\fBSTR\fP – Textual string +.IP \(bu 2 +\fBHEXSTR\fP – Hexadecimal string (with \fB0x\fP prefix) +.IP \(bu 2 +\fBBOOL\fP – Boolean value (\fBon\fP/\fBoff\fP or \fBtrue\fP/\fBfalse\fP) +.IP \(bu 2 +\fBTIME\fP – Number of seconds, an integer with possible time multiplier suffix +(\fBs\fP ~ 1, \fBm\fP ~ 60, \fBh\fP ~ 3600 or \fBd\fP ~ 24 * 3600) +.IP \(bu 2 +\fBSIZE\fP – Number of bytes, an integer with possible size multiplier suffix +(\fBB\fP ~ 1, \fBK\fP ~ 1024, \fBM\fP ~ 1024^2 or \fBG\fP ~ 1024^3) +.IP \(bu 2 +\fBBASE64\fP – Base64 encoded string +.IP \(bu 2 +\fBADDR\fP – IPv4 or IPv6 address +.IP \(bu 2 +\fBDNAME\fP – Domain name +.IP \(bu 2 +\fB\&...\fP – Multi\-valued item, order of the values is preserved +.IP \(bu 2 +\fB[\fP \fB]\fP – Optional value +.IP \(bu 2 +\fB|\fP – Choice +.UNINDENT +.sp +The configuration consists of several fixed sections and optional module +sections. There are 16 fixed sections (\fBmodule\fP, \fBserver\fP, \fBxdp\fP, \fBcontrol\fP, +\fBlog\fP, \fBstatistics\fP, \fBdatabase\fP, \fBkeystore\fP, \fBkey\fP, \fBremote\fP, +\fBremotes\fP, \fBacl\fP, \fBsubmission\fP, \fBpolicy\fP, \fBtemplate\fP, \fBzone\fP). +Module sections are prefixed with the \fBmod\-\fP prefix (e.g. \fBmod\-stats\fP). +.sp +Most of the sections (e.g. \fBzone\fP) 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). +.sp +A multi\-valued item can be specified either as a YAML sequence: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +address: [10.0.0.1, 10.0.0.2] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +or as more single\-valued items each on an extra line: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +address: 10.0.0.1 +address: 10.0.0.2 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +If an item value contains spaces or other special characters, it is necessary +to enclose such a value within double quotes \fB\(dq\fP \fB\(dq\fP\&. +.sp +If not specified otherwise, an item representing a file or a directory path may +be defined either as an absolute path (starting with \fB/\fP), or a path relative +to the same directory as the default value of the item. +.SH COMMENTS +.sp +A comment begins with a \fB#\fP character and is ignored during processing. +Also each configuration section or sequence block allows a permanent +comment using the \fBcomment\fP item which is stored in the server beside the +configuration. +.SH INCLUDING CONFIGURATION +.sp +Another configuration file or files, matching a pattern, can be included at +the top level in the current file. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +include: STR +.ft P +.fi +.UNINDENT +.UNINDENT +.SS include +.sp +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 \fIglob\fP +requirements, e.g. dir/*.conf. Matching files are processed in sorted order. +.sp +\fIDefault:\fP not set +.SH CLEARING CONFIGURATION SECTIONS +.sp +It\(aqs possible to clear specified configuration sections at given phases +of the configuration parsing. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +clear: STR +.ft P +.fi +.UNINDENT +.UNINDENT +.SS clear +.sp +A matching pattern specifying configuration sections that are cleared when +this item is parsed. This allows overriding of existing configuration +in the configuration database when including a configuration file or +ensures that some configuration wasn\(aqt specified in previous includes. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +For the pattern matching the POSIX function +\fI\%fnmatch()\fP +is used. On Linux, the GNU extension +\fI\%FNM_EXTMATCH\fP +is enabled, which allows extended pattern matching. +Examples: +.INDENT 0.0 +.IP \(bu 2 +\fBclear: zone\fP – Clears the \fBzone\fP section. +.IP \(bu 2 +\fBclear: mod\-*\fP – Clears all module sections. +.IP \(bu 2 +\fBclear: \(dq[!z]*\(dq\fP – Clears all sections not beginning with letter \fBz\fP\&. +.IP \(bu 2 +\fBclear: !(zone)\fP – (GNU only) Clears all sections except the \fBzone\fP one. +.IP \(bu 2 +\fBclear: @(zone|template)\fP – (GNU only) Clears the \fBzone\fP and \fBtemplate\fP sections. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SH MODULE SECTION +.sp +Dynamic modules loading configuration. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If configured with non\-empty \fB\-\-with\-moduledir=path\fP parameter, all +shared modules in this directory will be automatically loaded. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +module: + \- id: STR + file: STR +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A module identifier in the form of the \fBmod\-\fP prefix and module name suffix. +.SS file +.sp +A path to a shared library file with the module implementation. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +If the path is not absolute, the library is searched in the set of +system directories. See \fBman dlopen\fP for more details. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB${libdir}/knot/modules\-${version}\fP/module_name.so +(or \fB${path}\fP/module_name.so if configured with \fB\-\-with\-moduledir=path\fP) +.SH SERVER SECTION +.sp +General options related to the server. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +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] | STR ... + listen\-quic: ADDR[@INT] ... +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBCAUTION:\fP +.INDENT 0.0 +.INDENT 3.5 +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. +.UNINDENT +.UNINDENT +.SS identity +.sp +An identity of the server returned in the response to the query for TXT +record \fBid.server.\fP or \fBhostname.bind.\fP in the CHAOS class (\fI\%RFC 4892\fP). +Set to an empty value to disable. +.sp +\fIDefault:\fP FQDN hostname +.SS version +.sp +A version of the server software returned in the response to the query +for TXT record \fBversion.server.\fP or \fBversion.bind.\fP in the CHAOS +class (\fI\%RFC 4892\fP). Set to an empty value to disable. +.sp +\fIDefault:\fP server version +.SS nsid +.sp +A DNS name server identifier (\fI\%RFC 5001\fP). Set to an empty value to disable. +.sp +\fIDefault:\fP FQDN hostname at the moment of the daemon start +.SS rundir +.sp +A path for storing run\-time data (PID file, unix sockets, etc.). A non\-absolute +path is relative to the \fI\%knotd\fP startup directory. +.sp +Depending on the usage of this parameter, its change may require restart of the Knot +server to take effect. +.sp +\fIDefault:\fP \fB${localstatedir}/run/knot\fP (configured with \fB\-\-with\-rundir=path\fP) +.SS user +.sp +A system user with an optional system group (\fBuser:group\fP) under which the +server is run after starting and binding to interfaces. Linux capabilities +are employed if supported. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBroot:root\fP +.SS pidfile +.sp +A PID file \fI\%location\fP\&. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fI\%rundir\fP\fB/knot.pid\fP +.SS udp\-workers +.sp +A number of UDP workers (threads) used to process incoming queries +over UDP. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP equal to the number of online CPUs +.SS tcp\-workers +.sp +A number of TCP workers (threads) used to process incoming queries +over TCP. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP equal to the number of online CPUs, default value is at least 10 +.SS background\-workers +.sp +A number of workers (threads) used to execute background operations (zone +loading, zone updates, etc.). +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP equal to the number of online CPUs, default value is at most 10 +.SS async\-start +.sp +If enabled, server doesn\(aqt wait for the zones to be loaded and starts +responding immediately with SERVFAIL answers until the zone loads. +.sp +\fIDefault:\fP \fBoff\fP +.SS tcp\-idle\-timeout +.sp +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. +.sp +\fIMinimum:\fP \fB1\fP +.sp +\fIDefault:\fP \fB10\fP +.SS tcp\-io\-timeout +.sp +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 \fBoutgoing zone transfers\fP\&. The timeout is measured since some +data is already available for processing. +Set to 0 for infinity. +.sp +\fIDefault:\fP \fB500\fP (milliseconds) +.sp +\fBCAUTION:\fP +.INDENT 0.0 +.INDENT 3.5 +In order to reduce the risk of Slow Loris attacks, it\(aqs recommended setting +this limit as low as possible on public servers. +.UNINDENT +.UNINDENT +.SS tcp\-remote\-io\-timeout +.sp +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. +.sp +\fIDefault:\fP \fB5000\fP (milliseconds) +.SS tcp\-reuseport +.sp +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. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBoff\fP +.SS tcp\-fastopen +.sp +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\(aqt affected by this +configuration as it\(aqs enabled automatically if supported by OS. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The TCP Fast Open support must also be enabled on the OS level: +.INDENT 0.0 +.IP \(bu 2 +Linux/macOS: ensure kernel parameter \fBnet.ipv4.tcp_fastopen\fP is \fB2\fP or +\fB3\fP for server side, and \fB1\fP or \fB3\fP for client side. +.IP \(bu 2 +FreeBSD: ensure kernel parameter \fBnet.inet.tcp.fastopen.server_enable\fP +is \fB1\fP for server side, and \fBnet.inet.tcp.fastopen.client_enable\fP is +\fB1\fP for client side. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS quic\-max\-clients +.sp +A maximum number of QUIC clients connected in parallel. +.sp +See also \fI\%quic\fP\&. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIMinimum:\fP \fB128\fP +.sp +\fIDefault:\fP \fB10000\fP (ten thousand) +.SS quic\-outbuf\-max\-size +.sp +Maximum cumulative size of memory used for buffers of unACKed +sent messages. This limit is per one UDP worker. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Set low if little memory is available (together with \fI\%quic\-max\-clients\fP +since QUIC connections are memory\-heavy). Set to high value if outgoing zone +transfers of big zone over QUIC are expected. +.UNINDENT +.UNINDENT +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIMinimum:\fP \fB1M\fP (1 MiB) +.sp +\fIDefault:\fP \fB100M\fP (100 MiB) +.SS quic\-idle\-close\-timeout +.sp +Time in seconds, after which any idle QUIC connection is gracefully closed. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIMinimum:\fP \fB1\fP +.sp +\fIDefault:\fP \fB4\fP +.SS remote\-pool\-limit +.sp +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. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fB0\fP +.SS remote\-pool\-timeout +.sp +The timeout in seconds after which the unused kept\-open outgoing TCP connections +to remote servers are closed. +.sp +\fIDefault:\fP \fB5\fP +.SS remote\-retry\-delay +.sp +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\(aqt +be attempted. This prevents repetitive waiting for timeout on an unreachable remote. +.sp +\fIDefault:\fP \fB0\fP +.SS socket\-affinity +.sp +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\(aqt recommended for setups where the number of network card queues +is lower than the number of UDP or TCP workers. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBoff\fP +.SS tcp\-max\-clients +.sp +A maximum number of TCP clients connected in parallel, set this below the file +descriptor limit to avoid resource exhaustion. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +It is advisable to adjust the maximum number of open files per process in your +operating system configuration. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP one half of the file descriptor limit for the server process +.SS udp\-max\-payload +.sp +Maximum EDNS0 UDP payload size default for both IPv4 and IPv6. +.sp +\fIDefault:\fP \fB1232\fP +.SS udp\-max\-payload\-ipv4 +.sp +Maximum EDNS0 UDP payload size for IPv4. +.sp +\fIDefault:\fP \fB1232\fP +.SS udp\-max\-payload\-ipv6 +.sp +Maximum EDNS0 UDP payload size for IPv6. +.sp +\fIDefault:\fP \fB1232\fP +.SS key\-file +.sp +Path to a server key PEM file which is used for DNS over QUIC communication. +A non\-absolute path of a user specified key file is relative to the +\fB@config_dir@\fP directory. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP auto\-generated key +.SS cert\-file +.sp +Path to a server certificate PEM file which is used for DNS over QUIC communication. +A non\-absolute path is relative to the \fB@config_dir@\fP directory. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP one\-time in\-memory certificate +.SS edns\-client\-subnet +.sp +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 \fI\%RFC 7871\fP\&. +.sp +\fIDefault:\fP \fBoff\fP +.SS answer\-rotation +.sp +Enable or disable sorted\-rrset rotation in the answer section of normal replies. +The rotation shift is simply determined by a query ID. +.sp +\fIDefault:\fP \fBoff\fP +.SS automatic\-acl +.sp +If enabled, \fI\%automatic ACL\fP setting of +configured remotes is considered when evaluating authorized operations. +.sp +\fIDefault:\fP \fBoff\fP +.SS proxy\-allowlist +.sp +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 +\fI\%haproxy PROXY v2\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +TCP is not supported. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS dbus\-event +.sp +Specification of server or zone states which emit a D\-Bus signal on the system +bus. The bus name is \fBcz.nic.knotd\fP, the object path is \fB/cz/nic/knotd\fP, and +the interface name is \fBcz.nic.knotd.events\fP\&. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – No signal is emitted. +.IP \(bu 2 +\fBrunning\fP – There are two possible signals emitted: +.INDENT 2.0 +.IP \(bu 2 +\fBstarted\fP when the server is started and all configured zones (including +catalog zones and their members) are loaded or successfully bootstrapped. +.IP \(bu 2 +\fBstopped\fP when the server shutdown sequence is initiated. +.UNINDENT +.IP \(bu 2 +\fBzone\-updated\fP – The signal \fBzone_updated\fP is emitted when a zone has been updated; +the signal parameters are \fIzone name\fP and \fIzone SOA serial\fP\&. +.IP \(bu 2 +\fBkeys\-updated\fP \- The signal \fBkeys_updated\fP is emitted when a DNSSEC key set +of this zone is updated. +.IP \(bu 2 +\fBksk\-submission\fP – The signal \fBzone_ksk_submission\fP is emitted if there is +a ready KSK present when the zone is signed; the signal parameters are +\fIzone name\fP, \fIKSK keytag\fP, and \fIKSK KASP id\fP\&. +.IP \(bu 2 +\fBdnssec\-invalid\fP – The signal \fBzone_dnssec_invalid\fP is emitted when DNSSEC +validation fails; the signal parameter is \fIzone name\fP\&. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This function requires systemd version at least 221. +.UNINDENT +.UNINDENT +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBnone\fP +.SS dbus\-init\-delay +.sp +Time in seconds which the server waits upon D\-Bus initialization to ensure +the D\-Bus client is ready to receive signals. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIMinimum:\fP \fB0\fP +.sp +\fIDefault:\fP \fB1\fP +.SS listen +.sp +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 \fB@\fP separator. Use \fB0.0.0.0\fP for all configured IPv4 addresses or +\fB::\fP for all configured IPv6 addresses. Filesystem path can be specified +for listening on local unix SOCK_STREAM socket. Non\-absolute path +(i.e. not starting with \fB/\fP) is relative to \fI\%rundir\fP\&. +Non\-local address binding is automatically enabled if supported by the operating system. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP not set +.SS listen\-quic +.sp +One or more IP addresses (and optionally ports) where the server listens +for incoming queries over QUIC protocol. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP not set +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Incoming \fI\%DDNS\fP over QUIC isn\(aqt supported. +The server always responds with SERVFAIL. +.UNINDENT +.UNINDENT +.SH XDP SECTION +.sp +Various options related to XDP listening, especially TCP. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +xdp: + listen: STR[@INT] | ADDR[@INT] ... + udp: BOOL + tcp: BOOL + quic: BOOL + quic\-port: INT + 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 +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBCAUTION:\fP +.INDENT 0.0 +.INDENT 3.5 +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. +.UNINDENT +.UNINDENT +.SS listen +.sp +One or more network device names (e.g. \fBens786f0\fP) on which the \fI\%Mode XDP\fP +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 \fB@\fP separator. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fBCAUTION:\fP +.INDENT 0.0 +.INDENT 3.5 +If XDP workers only process regular DNS traffic over UDP, it is strongly +recommended to also \fI\%listen\fP on the addresses which are +intended to offer the DNS service, at least to fulfil the DNS requirement for +working TCP. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Incoming \fI\%DDNS\fP over XDP isn\(aqt supported. +The server always responds with SERVFAIL. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS udp +.sp +If enabled, DNS over UDP is processed with XDP workers. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBon\fP +.SS tcp +.sp +If enabled, DNS over TCP traffic is processed with XDP workers. +.sp +The TCP stack limitations: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +Congestion control is not implemented. +.IP \(bu 2 +Lost packets that do not contain TCP payload may not be resend. +.IP \(bu 2 +Not optimized for transfers of non\-trivial zones. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBoff\fP +.SS quic +.sp +If enabled, DNS over QUIC is processed with XDP workers. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fBoff\fP +.SS quic\-port +.sp +DNS over QUIC will listen on the interfaces configured by \fI\%listen\fP, +but on different port, configured by this option. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fIDefault:\fP \fB853\fP +.SS tcp\-max\-clients +.sp +A maximum number of TCP clients connected in parallel. +.sp +\fIMinimum:\fP \fB1024\fP +.sp +\fIDefault:\fP \fB1000000\fP (one million) +.SS tcp\-inbuf\-max\-size +.sp +Maximum cumulative size of memory used for buffers of incompletely +received messages. +.sp +\fIMinimum:\fP \fB1M\fP (1 MiB) +.sp +\fIDefault:\fP \fB100M\fP (100 MiB) +.SS tcp\-outbuf\-max\-size +.sp +Maximum cumulative size of memory used for buffers of unACKed +sent messages. +.sp +\fIMinimum:\fP \fB1M\fP (1 MiB) +.sp +\fIDefault:\fP \fB100M\fP (100 MiB) +.SS tcp\-idle\-close\-timeout +.sp +Time in seconds, after which any idle connection is gracefully closed. +.sp +\fIMinimum:\fP \fB1\fP +.sp +\fIDefault:\fP \fB10\fP +.SS tcp\-idle\-reset\-timeout +.sp +Time in seconds, after which any idle connection is forcibly closed. +.sp +\fIMinimum:\fP \fB1\fP +.sp +\fIDefault:\fP \fB20\fP +.SS tcp\-resend\-timeout +.sp +Resend outgoing data packets (with DNS response payload) if not ACKed +before this timeout. +.sp +\fIMinimum:\fP \fB1\fP +.sp +\fIDefault:\fP \fB5\fP +.SS route\-check +.sp +If enabled, routing information from the operating system is considered +when processing every incoming DNS packet received over the XDP interface: +.INDENT 0.0 +.IP \(bu 2 +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\(aqt used). +.IP \(bu 2 +If the destination address is blackholed, unreachable, or prohibited, +the DNS packet is dropped without any response. +.IP \(bu 2 +The destination MAC address and possible VLAN tag for the response are taken +from the routing system. +.UNINDENT +.sp +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. +.sp +Change of this parameter requires restart of the Knot server to take effect. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This mode requires forwarding enabled on the loopback interface +(\fBsysctl \-w net.ipv4.conf.lo.forwarding=1\fP and \fBsysctl \-w net.ipv6.conf.lo.forwarding=1\fP). +If forwarding is disabled, all incoming DNS packets are dropped! +.sp +Only VLAN 802.1Q is supported. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SH CONTROL SECTION +.sp +Configuration of the server control interface. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +control: + listen: STR + timeout: TIME +.ft P +.fi +.UNINDENT +.UNINDENT +.SS listen +.sp +A UNIX socket \fI\%path\fP where the server listens for +control commands. +.sp +\fIDefault:\fP \fI\%rundir\fP\fB/knot.sock\fP +.SS timeout +.sp +Maximum time (in seconds) the control socket operations can take. +Set to 0 for infinity. +.sp +\fIDefault:\fP \fB5\fP +.SH LOG SECTION +.sp +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. +.sp +There are 6 logging severity levels: +.INDENT 0.0 +.IP \(bu 2 +\fBcritical\fP – Non\-recoverable error resulting in server shutdown. +.IP \(bu 2 +\fBerror\fP – Recoverable error, action should be taken. +.IP \(bu 2 +\fBwarning\fP – Warning that might require user action. +.IP \(bu 2 +\fBnotice\fP – Server notice or hint. +.IP \(bu 2 +\fBinfo\fP – Informational message. +.IP \(bu 2 +\fBdebug\fP – Debug or detailed message. +.UNINDENT +.sp +In the case of a missing log section, \fBwarning\fP or more serious messages +will be logged to both standard error output and syslog. The \fBinfo\fP and +\fBnotice\fP messages will be logged to standard output. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +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 + quic: critical | error | warning | notice | info | debug + any: critical | error | warning | notice | info | debug +.ft P +.fi +.UNINDENT +.UNINDENT +.SS target +.sp +A logging output. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBstdout\fP – Standard output. +.IP \(bu 2 +\fBstderr\fP – Standard error output. +.IP \(bu 2 +\fBsyslog\fP – Syslog or systemd journal. +.IP \(bu 2 +\fIfile_name\fP – A specific file. +.UNINDENT +.sp +With \fBsyslog\fP 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. +.sp +A \fIfile_name\fP may be specified as an absolute path or a path relative to the +\fI\%knotd\fP startup directory. +.SS server +.sp +Minimum severity level for messages related to general operation of the server to be +logged. +.sp +\fIDefault:\fP not set +.SS control +.sp +Minimum severity level for messages related to server control to be logged. +.sp +\fIDefault:\fP not set +.SS zone +.sp +Minimum severity level for messages related to zones to be logged. +.sp +\fIDefault:\fP not set +.SS quic +.sp +Minimum severity level for messages related to QUIC to be logged. +.sp +\fIDefault:\fP not set +.SS any +.sp +Minimum severity level for all message types, except \fBquic\fP, to be logged. +.sp +\fIDefault:\fP not set +.SH STATS SECTION +.sp +Periodic server statistics dumping. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +statistics: + timer: TIME + file: STR + append: BOOL +.ft P +.fi +.UNINDENT +.UNINDENT +.SS timer +.sp +A period (in seconds) after which all available statistics metrics will by written to the +\fI\%file\fP\&. +.sp +\fIDefault:\fP not set +.SS file +.sp +A file \fI\%path\fP of statistics output in the YAML format. +.sp +\fIDefault:\fP \fI\%rundir\fP\fB/stats.yaml\fP +.SS append +.sp +If enabled, the output will be appended to the \fI\%file\fP +instead of file replacement. +.sp +\fIDefault:\fP \fBoff\fP +.SH DATABASE SECTION +.sp +Configuration of databases for zone contents, DNSSEC metadata, or event timers. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +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 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS storage +.sp +A data directory for storing journal, KASP, and timer databases. A non\-absolute +path is relative to the \fI\%knotd\fP startup directory. +.sp +\fIDefault:\fP \fB${localstatedir}/lib/knot\fP (configured with \fB\-\-with\-storage=path\fP) +.SS journal\-db +.sp +An explicit \fI\%specification\fP of the persistent journal database +directory. +.sp +\fIDefault:\fP \fI\%storage\fP\fB/journal\fP +.SS journal\-db\-mode +.sp +Specifies journal LMDB backend configuration, which influences performance +and durability. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBrobust\fP – The journal database disk synchronization ensures database +durability but is generally slower. +.IP \(bu 2 +\fBasynchronous\fP – 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. +.UNINDENT +.sp +\fIDefault:\fP \fBrobust\fP +.SS journal\-db\-max\-size +.sp +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. +.sp +It is recommended to limit \fI\%journal\-max\-usage\fP +per\-zone instead of \fI\%journal\-db\-max\-size\fP +in most cases. Please keep this value larger than the sum of all zones\(aq +journal usage limits. See more details regarding +\fI\%journal behaviour\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This value also influences server\(aqs usage of virtual memory. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB20G\fP (20 GiB), or \fB512M\fP (512 MiB) for 32\-bit +.SS kasp\-db +.sp +An explicit \fI\%specification\fP of the KASP database directory. +.sp +\fIDefault:\fP \fI\%storage\fP\fB/keys\fP +.SS kasp\-db\-max\-size +.sp +The hard limit for the KASP database maximum size. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This value also influences server\(aqs usage of virtual memory. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB500M\fP (500 MiB) +.SS timer\-db +.sp +An explicit \fI\%specification\fP of the persistent timer +database directory. +.sp +\fIDefault:\fP \fI\%storage\fP\fB/timers\fP +.SS timer\-db\-max\-size +.sp +The hard limit for the timer database maximum size. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This value also influences server\(aqs usage of virtual memory. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB100M\fP (100 MiB) +.SS catalog\-db +.sp +An explicit \fI\%specification\fP of the zone catalog +database directory. Only useful if \fI\%Catalog zones\fP are enabled. +.sp +\fIDefault:\fP \fI\%storage\fP\fB/catalog\fP +.SS catalog\-db\-max\-size +.sp +The hard limit for the catalog database maximum size. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This value also influences server\(aqs usage of virtual memory. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB20G\fP (20 GiB), or \fB512M\fP (512 MiB) for 32\-bit +.SH KEYSTORE SECTION +.sp +DNSSEC keystore configuration. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +keystore: + \- id: STR + backend: pem | pkcs11 + config: STR + key\-label: BOOL +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A keystore identifier. +.SS backend +.sp +A key storage backend type. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBpem\fP – PEM files. +.IP \(bu 2 +\fBpkcs11\fP – PKCS #11 storage. +.UNINDENT +.sp +\fIDefault:\fP \fBpem\fP +.SS config +.sp +A backend specific configuration. A directory with PEM files (the path can +be specified as a relative path to \fI\%kasp\-db\fP) or +a configuration string for PKCS #11 storage (\fI<pkcs11\-uri> <module\-path>\fP). +The PKCS #11 URI Scheme is defined in \fI\%RFC 7512\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Example configuration string for PKCS #11: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +\(dqpkcs11:token=knot;pin\-value=1234 /usr/lib64/pkcs11/libsofthsm2.so\(dq +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fI\%kasp\-db\fP\fB/keys\fP +.SS key\-label +.sp +If enabled in combination with the PKCS #11 \fI\%backend\fP, generated keys +are labeled in the form \fB<zone_name> KSK|ZSK\fP\&. +.sp +\fIDefault:\fP \fBoff\fP +.SH KEY SECTION +.sp +Shared TSIG keys used to authenticate communication with the server. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +key: + \- id: DNAME + algorithm: hmac\-md5 | hmac\-sha1 | hmac\-sha224 | hmac\-sha256 | hmac\-sha384 | hmac\-sha512 + secret: BASE64 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A key name identifier. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This value MUST be exactly the same as the name of the TSIG key on the +opposite primary/secondary server(s). +.UNINDENT +.UNINDENT +.SS algorithm +.sp +A TSIG key algorithm. See +\fI\%TSIG Algorithm Numbers\fP\&. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBhmac\-md5\fP +.IP \(bu 2 +\fBhmac\-sha1\fP +.IP \(bu 2 +\fBhmac\-sha224\fP +.IP \(bu 2 +\fBhmac\-sha256\fP +.IP \(bu 2 +\fBhmac\-sha384\fP +.IP \(bu 2 +\fBhmac\-sha512\fP +.UNINDENT +.sp +\fIDefault:\fP not set +.SS secret +.sp +Shared key secret. +.sp +\fIDefault:\fP not set +.SH REMOTE SECTION +.sp +Definitions of remote servers for outgoing connections (source of a zone +transfer, target for a notification, etc.). +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +remote: + \- id: STR + address: ADDR[@INT] | STR ... + via: ADDR[@INT] ... + quic: BOOL + key: key_id + cert\-key: BASE64 ... + block\-notify\-after\-transfer: BOOL + no\-edns: BOOL + automatic\-acl: BOOL +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A remote identifier. +.SS address +.sp +An ordered list of destination IP addresses or UNIX socket paths which are +used for communication with the remote server. Non\-absolute path +(i.e. not starting with \fB/\fP) is relative to \fI\%rundir\fP\&. +Optional destination port (default is 53 for UDP/TCP and 853 for QUIC) +can be appended to the address using \fB@\fP separator. +The addresses are tried in sequence until the +remote is reached. +.sp +\fIDefault:\fP not set +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If the remote is contacted and it refuses to perform requested action, +no more addresses will be tried for this remote. +.UNINDENT +.UNINDENT +.SS via +.sp +An ordered list of source IP addresses which are used as source addresses +for communication with the remote. For the N\-th \fI\%remote address\fP, +the last, but at most N\-th, specified \fI\%via address\fP +of the same family is used. +This option can help if the server listens on more addresses. +Optional source port (default is random) can be appended +to the address using \fB@\fP separator. +.sp +\fIDefault:\fP not set +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +For the following configuration: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +remote: + \- id: example + address: [198.51.100.10, 2001:db8::10, 198.51.100.20, 2001:db8::20] + via: [198.51.100.1, 198.51.100.2, 2001:db8::1] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +the (\fBvia\fP \-> \fBaddress\fP) mapping is: +.INDENT 0.0 +.IP \(bu 2 +\fB198.51.100.1\fP \-> \fB198.51.100.10\fP +.IP \(bu 2 +\fB2001:db8::1\fP \-> \fB2001:db8::10\fP +.IP \(bu 2 +\fB198.51.100.2\fP \-> \fB198.51.100.20\fP +.IP \(bu 2 +\fB2001:db8::1\fP \-> \fB2001:db8::20\fP +.UNINDENT +.UNINDENT +.UNINDENT +.SS quic +.sp +If this option is set, the QUIC protocol will be used for outgoing communication +with this remote. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +One connection per each remote is opened; \fI\%remote\-pool\-limit\fP +does not take effect for QUIC. However, fast QUIC handshakes utilizing obtained +session tickets are used for reopening connections to recently (up to 1 day) +queried remotes. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS key +.sp +A \fI\%reference\fP to the TSIG key which is used to authenticate +the communication with the remote server. +.sp +\fIDefault:\fP not set +.SS cert\-key +.sp +An ordered list of remote certificate public key PINs. If the list is non\-empty, +communication with the remote is possible only via QUIC protocol and +a peer certificate is required. The peer certificate key must match one of the +specified PINs. +.sp +A PIN is a unique identifier that represents the public key of the peer certificate. +It\(aqs a base64\-encoded SHA\-256 hash of the public key. This identifier +remains the same on a certificate renewal. +.sp +\fIDefault:\fP not set +.SS block\-notify\-after\-transfer +.sp +When incoming AXFR/IXFR from this remote (as a primary server), suppress +sending NOTIFY messages to all configured secondary servers. +.sp +\fIDefault:\fP \fBoff\fP +.SS no\-edns +.sp +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). +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option effectively disables \fI\%zone expire\fP timer +updates via EDNS EXPIRE option specified in \fI\%RFC 7314\fP\&. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS automatic\-acl +.sp +If enabled, some authorized operations for the remote are automatically allowed +based on the context: +.INDENT 0.0 +.IP \(bu 2 +Incoming NOTIFY is allowed from the remote if it\(aqs configured as a +\fI\%primary server\fP for the zone. +.IP \(bu 2 +Outgoing zone transfer is allowed to the remote if it\(aqs configured as a +\fI\%NOTIFY target\fP for the zone. +.UNINDENT +.sp +Automatic ACL rules are evaluated before explicit \fI\%zone ACL\fP configuration. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This functionality requires global activation via +\fI\%automatic\-acl\fP in the server section. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBon\fP +.SH REMOTES SECTION +.sp +Definitions of groups of remote servers. Remote grouping can simplify the +configuration. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +remotes: + \- id: STR + remote: remote_id ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A remote group identifier. +.SS remote +.sp +An ordered list of \fI\%references\fP to remote server definitions. +.sp +\fIDefault:\fP not set +.SH ACL SECTION +.sp +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. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +acl: + \- id: STR + address: ADDR[/INT] | ADDR\-ADDR | STR ... + key: key_id ... + cert\-key: BASE64 ... + 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 | pattern + update\-owner\-name: STR ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +An ACL rule identifier. +.SS address +.sp +An ordered list of IP addresses, absolute UNIX socket paths, network subnets, +or network ranges. The query\(aqs +source address must match one of them. If this item is not set, address match is not +required. +.sp +\fIDefault:\fP not set +.SS key +.sp +An ordered list of \fI\%reference\fPs to TSIG keys. The query must +match one of them. If this item is not set, transaction authentication is not used. +.sp +\fIDefault:\fP not set +.SS cert\-key +.sp +An ordered list of remote certificate public key PINs. If the list is non\-empty, +communication with the remote is possible only via QUIC protocol and +a peer certificate is required. The peer certificate key must match one of the +specified PINs. +.sp +A PIN is a unique identifier that represents the public key of the peer certificate. +It\(aqs a base64\-encoded SHA\-256 hash of the public key. This identifier +remains the same on a certificate renewal. +.sp +\fIDefault:\fP not set +.SS remote +.sp +An ordered list of references \fI\%remote\fP and +\fI\%remotes\fP\&. The query must +match one of the remotes. Specifically, one of the remote\(aqs addresses and remote\(aqs +TSIG key if configured must match. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option cannot be specified along with the \fI\%address\fP or +\fI\%key\fP option at one ACL item. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS action +.sp +An ordered list of allowed (or denied) actions. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBquery\fP – Allow regular DNS query. As normal queries are always allowed, +this action is only useful in combination with \fI\%TSIG key\fP\&. +.IP \(bu 2 +\fBnotify\fP – Allow incoming notify (NOTIFY). +.IP \(bu 2 +\fBtransfer\fP – Allow zone transfer (AXFR, IXFR). +.IP \(bu 2 +\fBupdate\fP – Allow zone updates (DDNS). +.UNINDENT +.sp +\fIDefault:\fP \fBquery\fP +.SS deny +.sp +If enabled, instead of allowing, deny the specified \fI\%action\fP, +\fI\%address\fP, \fI\%key\fP, or combination if these +items. If no action is specified, deny all actions. +.sp +\fIDefault:\fP \fBoff\fP +.SS update\-type +.sp +A list of allowed types of Resource Records in a zone update. Every record in an update +must match one of the specified types. +.sp +\fIDefault:\fP not set +.SS update\-owner +.sp +This option restricts possible owners of Resource Records in a zone update by comparing +them to either the \fI\%TSIG key\fP identity, the current zone name, or to a list of +domain names given by the \fI\%update\-owner\-name\fP option. +The comparison method is given by the \fI\%update\-owner\-match\fP option. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBkey\fP — The owner of each updated RR must match the identity of the TSIG key if used. +.IP \(bu 2 +\fBname\fP — The owner of each updated RR must match at least one name in the +\fI\%update\-owner\-name\fP list. +.IP \(bu 2 +\fBzone\fP — The owner of each updated RR must match the current zone name. +.UNINDENT +.sp +\fIDefault:\fP not set +.SS update\-owner\-match +.sp +This option defines how the owners of Resource Records in an update are matched to the domain name(s) +set by the \fI\%update\-owner\fP option. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBsub\-or\-equal\fP — 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 \fI\%update\-owner\fP\&. +.IP \(bu 2 +\fBequal\fP — The owner of each updated RR must be equal to at least one domain +name set by \fI\%update\-owner\fP\&. +.IP \(bu 2 +\fBsub\fP — The owner of each updated RR must be a subdomain of, but MUST NOT +be equal to at least one domain name set by \fI\%update\-owner\fP\&. +.IP \(bu 2 +\fBpattern\fP — The owner of each updated RR must match a pattern specified by +\fI\%update\-owner\fP\&. The pattern can be an arbitrary FQDN or non\-FQDN +domain name. If a label consists of one \fB*\fP (asterisk) character, it +matches any label. More asterisk labels can be specified. +.UNINDENT +.sp +\fIDefault:\fP \fBsub\-or\-equal\fP +.SS update\-owner\-name +.sp +A list of allowed owners of RRs in a zone update used with \fI\%update\-owner\fP +set to \fBname\fP\&. Every listed owner name which is not FQDN (i.e. it doesn\(aqt 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. +.sp +\fIDefault:\fP not set +.SH SUBMISSION SECTION +.sp +Parameters of KSK submission checks. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +submission: + \- id: STR + parent: remote_id | remotes_id ... + check\-interval: TIME + timeout: TIME + parent\-delay: TIME +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A submission identifier. +.SS parent +.sp +A list of references \fI\%remote\fP and \fI\%remotes\fP +to parent\(aqs 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. +.sp +\fIDefault:\fP not set +.sp +\fBTIP:\fP +.INDENT 0.0 +.INDENT 3.5 +A DNSSEC\-validating resolver can be set as a parent. +.UNINDENT +.UNINDENT +.SS check\-interval +.sp +Interval for periodic checks of DS presence on parent\(aqs DNS servers, in the +case of the KSK submission. +.sp +\fIDefault:\fP \fB1h\fP (1 hour) +.SS timeout +.sp +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. +.sp +\fIDefault:\fP \fB0\fP +.SS parent\-delay +.sp +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. +.sp +\fIDefault:\fP \fB0\fP +.SH DNSKEY-SYNC SECTION +.sp +Parameters of DNSKEY dynamic\-update synchrnization. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +dnskey\-sync: + \- id: STR + remote: remote_id | remotes_id ... + check\-interval: TIME +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A dnskey\-sync identifier. +.SS remote +.sp +A list of references \fI\%remote\fP and \fI\%remotes\fP +to other signers or common master, which the DDNS updates with +DNSKEY/CDNSKEY/CDS records shall be sent to. +.sp +\fIDefault:\fP not set +.SS check\-interval +.sp +If the last DNSKEY sync failed or resulted in any change, re\-check +the consistence after this interval and re\-try if needed. +.sp +\fIDefault:\fP \fB60\fP (1 minute) +.SH POLICY SECTION +.sp +DNSSEC policy configuration. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +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 ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS id +.sp +A policy identifier. +.SS keystore +.sp +A \fI\%reference\fP to a keystore holding private key material +for zones. +.sp +\fIDefault:\fP an imaginary keystore with all default values +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +A configured keystore called \(dqdefault\(dq won\(aqt be used unless explicitly referenced. +.UNINDENT +.UNINDENT +.SS manual +.sp +If enabled, automatic key management is not used. +.sp +\fIDefault:\fP \fBoff\fP +.SS single\-type\-signing +.sp +If enabled, Single\-Type Signing Scheme is used in the automatic key management +mode. +.sp +\fIDefault:\fP \fBoff\fP (\fI\%module onlinesign\fP has default \fBon\fP) +.SS algorithm +.sp +An algorithm of signing keys and issued signatures. See +\fI\%DNSSEC Algorithm Numbers\fP\&. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBrsasha1\fP +.IP \(bu 2 +\fBrsasha1\-nsec3\-sha1\fP +.IP \(bu 2 +\fBrsasha256\fP +.IP \(bu 2 +\fBrsasha512\fP +.IP \(bu 2 +\fBecdsap256sha256\fP +.IP \(bu 2 +\fBecdsap384sha384\fP +.IP \(bu 2 +\fBed25519\fP +.IP \(bu 2 +\fBed448\fP +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Ed25519 algorithm is only available if compiled with GnuTLS 3.6.0+. +.sp +Ed448 algorithm is only available if compiled with GnuTLS 3.6.12+ and Nettle 3.6+. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBecdsap256sha256\fP +.SS ksk\-size +.sp +A length of newly generated KSK or +CSK keys. +.sp +\fIDefault:\fP \fB2048\fP (rsa*), \fB256\fP (ecdsap256), \fB384\fP (ecdsap384), \fB256\fP (ed25519), +\fB456\fP (ed448) +.SS zsk\-size +.sp +A length of newly generated ZSK keys. +.sp +\fIDefault:\fP see default for \fI\%ksk\-size\fP +.SS ksk\-shared +.sp +If enabled, all zones with this policy assigned will share one or more KSKs. +More KSKs can be shared during a KSK rollover. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +As the shared KSK set is bound to the policy \fI\%id\fP, renaming the +policy breaks this connection and new shared KSK set is initiated when +a new KSK is needed. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS dnskey\-ttl +.sp +A TTL value for DNSKEY records added into zone apex. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Has influence over ZSK key lifetime. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Ensure all DNSKEYs with updated TTL are propagated before any subsequent +DNSKEY rollover starts. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP zone SOA TTL +.SS zone\-max\-ttl +.sp +Declare (override) maximal TTL value among all the records in zone. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +It\(aqs generally recommended to override the maximal TTL computation by setting this +explicitly whenever possible. It\(aqs required for \fI\%DNSSEC Offline KSK\fP and +really reasonable when records are generated dynamically +(e.g. by a \fI\%module\fP). +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP computed after zone is loaded +.SS ksk\-lifetime +.sp +A period between KSK generation and the next rollover initiation. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +KSK key lifetime is also influenced by propagation\-delay, dnskey\-ttl, +and KSK submission delay. +.sp +Zero (aka infinity) value causes no KSK rollover as a result. +.sp +This applies for CSK lifetime if single\-type\-signing is enabled. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB0\fP +.SS zsk\-lifetime +.sp +A period between ZSK activation and the next rollover initiation. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +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. +.sp +ZSK key lifetime is also influenced by propagation\-delay and dnskey\-ttl +.sp +Zero (aka infinity) value causes no ZSK rollover as a result. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB30d\fP (30 days) +.SS delete\-delay +.sp +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. +.sp +\fIDefault:\fP \fB0\fP +.SS propagation\-delay +.sp +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. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Has influence over ZSK key lifetime. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB1h\fP (1 hour) +.SS rrsig\-lifetime +.sp +A validity period of newly issued signatures. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The RRSIG\(aqs signature inception time is set to 90 minutes in the past. This +time period is not counted to the signature lifetime. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB14d\fP (14 days) +.SS rrsig\-refresh +.sp +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\(aq caches. +.sp +\fIDefault:\fP 0.1 * \fI\%rrsig\-lifetime\fP + \fI\%propagation\-delay\fP + \fI\%zone\-max\-ttl\fP +.SS rrsig\-pre\-refresh +.sp +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). +.sp +\fIDefault:\fP \fB1h\fP (1 hour) +.SS reproducible\-signing +.sp +For ECDSA algorithms, generate RRSIG signatures deterministically (\fI\%RFC 6979\fP). +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. +.sp +\fIDefault:\fP \fBoff\fP +.SS nsec3 +.sp +Specifies if NSEC3 will be used instead of NSEC. +.sp +\fIDefault:\fP \fBoff\fP +.SS nsec3\-iterations +.sp +A number of additional times the hashing is performed. +.sp +\fIDefault:\fP \fB0\fP +.SS nsec3\-opt\-out +.sp +If set, NSEC3 records won\(aqt be created for insecure delegations. +This speeds up the zone signing and reduces overall zone size. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +NSEC3 with the Opt\-Out bit set no longer works as a proof of non\-existence +in this zone. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS nsec3\-salt\-length +.sp +A length of a salt field in octets, which is appended to the original owner +name before hashing. +.sp +\fIDefault:\fP \fB8\fP +.SS nsec3\-salt\-lifetime +.sp +A validity period of newly issued salt field. +.sp +Zero value means infinity. +.sp +Special value \fI\-1\fP triggers re\-salt every time when active ZSK changes. +This optimizes the number of big changes to the zone. +.sp +\fIDefault:\fP \fB30d\fP (30 days) +.SS signing\-threads +.sp +When signing zone or update, use this number of threads for parallel signing. +.sp +Those are extra threads independent of \fI\%Background workers\fP\&. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Some steps of the DNSSEC signing operation are not parallelized. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB1\fP (no extra threads) +.SS ksk\-submission +.sp +A reference to \fI\%submission\fP section holding parameters of +KSK submission checks. +.sp +\fIDefault:\fP not set +.SS ds\-push +.sp +Optional references \fI\%remote\fP and \fI\%remotes\fP +to authoritative DNS server of the +parent\(aqs 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\(aqs possible to manage both child and parent zones by the same Knot DNS server. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This feature requires \fI\%cds\-cdnskey\-publish\fP +not to be set to \fBnone\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The mentioned change to CDS record usually means that a KSK roll\-over is running +and the new key being rolled\-in is in \(dqready\(dq state already for the period of +\fI\%propagation\-delay\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Module \fI\%Onlinesign\fP doesn\(aqt support DS push. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS dnskey\-sync +.sp +A reference to \fI\%dnskey\-sync\fP section holding parameters +of DNSKEY synchronization. +.sp +\fIDefault:\fP not set +.SS cds\-cdnskey\-publish +.sp +Controls if and how shall the CDS and CDNSKEY be published in the zone. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – Never publish any CDS or CDNSKEY records in the zone. +.IP \(bu 2 +\fBdelete\-dnssec\fP – Publish special CDS and CDNSKEY records indicating turning off DNSSEC. +.IP \(bu 2 +\fBrollover\fP – Publish CDS and CDNSKEY records for ready and not yet active KSK (submission phase of KSK rollover). +.IP \(bu 2 +\fBalways\fP – Always publish one CDS and one CDNSKEY records for the current KSK. +.IP \(bu 2 +\fBdouble\-ds\fP – Always publish up to two CDS and two CDNSKEY records for ready and/or active KSKs. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If the zone keys are managed manually, the CDS and CDNSKEY rrsets may contain +more records depending on the keys available. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +The \fBdouble\-ds\fP value does not trigger double\-DS roll\-over method. That method is +only supported when performed manually, with unset \fI\%ksk\-submission\fP\&. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBrollover\fP +.SS cds\-digest\-type +.sp +Specify digest type for published CDS records. +.sp +\fIDefault:\fP \fBsha256\fP +.SS dnskey\-management +.sp +Specify how the DNSKEY, CDNSKEY, and CDS RRSets at the zone apex are handled +when (re\-)signing the zone. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBfull\fP – 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. +.IP \(bu 2 +\fBincremental\fP – Keep unknown DNSKEY, CDNSKEY, and CDS records in the zone, and +modify server\-managed records incrementally by employing changes in the KASP database. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Prerequisites for \fIincremental\fP: +.INDENT 0.0 +.IP \(bu 2 +The \fI\%Offline KSK\fP isn\(aqt supported. +.IP \(bu 2 +The \fI\%delete\-delay\fP is long enough to cover possible daemon +shutdown (e.g. due to server maintenance). +.IP \(bu 2 +Avoided manual deletion of keys with \fI\%keymgr\fP\&. +.UNINDENT +.sp +Otherwise there might remain some DNSKEY records in the zone, belonging to +deleted keys. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBfull\fP +.SS offline\-ksk +.sp +Specifies if \fI\%Offline KSK\fP feature is enabled. +.sp +\fIDefault:\fP \fBoff\fP +.SS unsafe\-operation +.sp +Turn off some DNSSEC safety features. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – Nothing disabled. +.IP \(bu 2 +\fBno\-check\-keyset\fP – Don\(aqt check active keys in present algorithms. This may +lead to violation of \fI\%RFC 4035#section\-2.2\fP\&. +.IP \(bu 2 +\fBno\-update\-dnskey\fP – Don\(aqt maintain/update DNSKEY, CDNSKEY, and CDS records +in the zone apex according to KASP database. Juste leave them as they are in the zone. +.IP \(bu 2 +\fBno\-update\-nsec\fP – Don\(aqt maintain/update NSEC/NSEC3 chain. Leave all the records +as they are in the zone. +.IP \(bu 2 +\fBno\-update\-expired\fP – Don\(aqt update expired RRSIGs. +.UNINDENT +.sp +Multiple values may be specified. +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +This mode is intended for DNSSEC experts who understand the corresponding consequences. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBnone\fP +.SH TEMPLATE SECTION +.sp +A template is shareable zone settings, which can simplify configuration by +reducing duplicates. A special default template (with the \fIdefault\fP identifier) +can be used for global zone configuration or as an implicit configuration +if a zone doesn\(aqt have another template specified. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +template: + \- id: STR + global\-module: STR/STR ... + # All zone options (excluding \(aqtemplate\(aq item) +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +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. +.UNINDENT +.UNINDENT +.SS id +.sp +A template identifier. +.SS global\-module +.sp +An ordered list of references to query modules in the form of \fImodule_name\fP or +\fImodule_name/module_id\fP\&. These modules apply to all queries. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option is only available in the \fIdefault\fP template. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SH ZONE SECTION +.sp +Definition of zones served by the server. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +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 ... + master\-pin\-tolerance: TIME + 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 + ixfr\-benevolent: BOOL + ixfr\-by\-one: BOOL + ixfr\-from\-axfr: BOOL + 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 + serial\-modulo: INT/INT + reverse\-generate: DNAME + 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 ... +.ft P +.fi +.UNINDENT +.UNINDENT +.SS domain +.sp +A zone name identifier. +.SS template +.sp +A \fI\%reference\fP to a configuration template. +.sp +\fIDefault:\fP not set or \fBdefault\fP (if the template exists) +.SS storage +.sp +A data directory for storing zone files. A non\-absolute path is relative to +the \fI\%knotd\fP startup directory. +.sp +\fIDefault:\fP \fB${localstatedir}/lib/knot\fP (configured with \fB\-\-with\-storage=path\fP) +.SS file +.sp +A \fI\%path\fP to the zone file. It is also possible to use +the following formatters: +.INDENT 0.0 +.IP \(bu 2 +\fB%c[\fP\fIN\fP\fB]\fP or \fB%c[\fP\fIN\fP\fB\-\fP\fIM\fP\fB]\fP – Means the \fIN\fPth +character or a sequence of characters beginning from the \fIN\fPth and ending +with the \fIM\fPth character of the textual zone name (see \fB%s\fP). 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. +.IP \(bu 2 +\fB%l[\fP\fIN\fP\fB]\fP – Means the \fIN\fPth label of the textual zone name +(see \fB%s\fP). The index is counted from 0 from the right (0 ~ TLD). +If the label is not available, the formatter has no effect. +.IP \(bu 2 +\fB%s\fP – Means the current zone name in the textual representation. +The zone name doesn\(aqt include the terminating dot (the result for the root +zone is the empty string!). +.IP \(bu 2 +\fB%%\fP – Means the \fB%\fP character. +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +Beware of special characters which are escaped or encoded in the \eDDD form +where DDD is corresponding decimal ASCII code. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fI\%storage\fP\fB/%s.zone\fP +.SS master +.sp +An ordered list of references \fI\%remote\fP and +\fI\%remotes\fP to zone primary servers +(formerly known as master servers). +.sp +\fIDefault:\fP not set +.SS ddns\-master +.sp +A \fI\%reference\fP to a zone primary master where DDNS messages +should be forwarded to. If not specified, the first \fI\%master\fP +server is used. +.sp +If set to the empty value (\(dq\(dq), incoming DDNS messages aren\(aqt forwarded but are applied +to the local zone instead, no matter if it is a secondary server. This is only allowed in +combination with \fI\%dnssec\-signing\fP enabled. +.sp +\fIDefault:\fP not set +.SS notify +.sp +An ordered list of references \fI\%remote\fP and +\fI\%remotes\fP to secondary servers to which notify +message is sent if the zone changes. +.sp +\fIDefault:\fP not set +.SS acl +.sp +An ordered list of \fI\%references\fP to ACL rules which can allow +or disallow zone transfers, updates or incoming notifies. +.sp +\fIDefault:\fP not set +.SS master\-pin\-tolerance +.sp +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. +.sp +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. +.sp +\fIDefault:\fP 0 +.SS provide\-ixfr +.sp +If disabled, the server is forced to respond with AXFR to IXFR queries. +If enabled, IXFR requests are responded normally. +.sp +\fIDefault:\fP \fBon\fP +.SS semantic\-checks +.sp +Selects if extra zone semantic checks are used or impacts of the mandatory checks. +.sp +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 \fBsoft\fP, which allows the zone to +be loaded even if the check fails. +.sp +If enabled, extra checks are used. These checks don\(aqt prevent the zone from loading. +.sp +The mandatory checks are applied to zone files, zone transfers, and updates via +control interface. The extra checks are applied to zone files only! +.sp +Mandatory checks: +.INDENT 0.0 +.IP \(bu 2 +Missing SOA record at the zone apex (\fI\%RFC 1034\fP) (*) +.IP \(bu 2 +An extra record exists together with a CNAME record except for RRSIG and NSEC (\fI\%RFC 1034\fP) +.IP \(bu 2 +Multiple CNAME records with the same owner exist (\fI\%RFC 1034\fP) +.IP \(bu 2 +DNAME record having a record under it (\fI\%RFC 6672\fP) +.IP \(bu 2 +Multiple DNAME records with the same owner exist (\fI\%RFC 6672\fP) +.IP \(bu 2 +NS record exists together with a DNAME record (\fI\%RFC 6672\fP) +.IP \(bu 2 +DS record exists at the zone apex (\fI\%RFC 3658\fP) +.UNINDENT +.sp +(*) The marked check can\(aqt be weakened by the soft mode. All other mandatory checks +are subject to the optional soft mode. +.sp +Extra checks: +.INDENT 0.0 +.IP \(bu 2 +Missing NS record at the zone apex +.IP \(bu 2 +Missing glue A or AAAA record +.IP \(bu 2 +Invalid DS or NSEC3PARAM record +.IP \(bu 2 +CDS or CDNSKEY inconsistency +.IP \(bu 2 +All other DNSSEC checks executed during \fI\%dnssec\-validation\fP +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +The soft mode allows the refresh event to ignore a CNAME response to a SOA +query (malformed message) and triggers a zone bootstrap instead. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS zonefile\-sync +.sp +The time after which the current zone in memory will be synced with a zone file +on the disk (see \fI\%file\fP). 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 \fBzonefile\-sync\fP 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 \fB\-f\fP option. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If you are serving large zones with frequent updates where +the immediate sync with a zone file is not desirable, increase the value. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB0\fP (immediate) +.SS zonefile\-load +.sp +Selects how the zone file contents are applied during zone load. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – The zone file is not used at all. +.IP \(bu 2 +\fBdifference\fP – 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. +.IP \(bu 2 +\fBdifference\-no\-serial\fP – Same as \fBdifference\fP, but the SOA serial in the zone file is +ignored, the server takes care of incrementing the serial automatically. +.IP \(bu 2 +\fBwhole\fP – Zone contents are loaded from the zone file. +.UNINDENT +.sp +When \fBdifference\fP is configured and there are no zone contents yet (cold start +and no zone contents in the journal), it behaves the same way as \fBwhole\fP\&. +.sp +\fIDefault:\fP \fBwhole\fP +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +See \fI\%Handling zone file, journal, changes, serials\fP for guidance on +configuring these and related options to ensure reliable operation. +.UNINDENT +.UNINDENT +.SS journal\-content +.sp +Selects how the journal shall be used to store zone and its changes. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – The journal is not used at all. +.IP \(bu 2 +\fBchanges\fP – Zone changes history is stored in journal. +.IP \(bu 2 +\fBall\fP – Zone contents and history is stored in journal. +.UNINDENT +.sp +\fIDefault:\fP \fBchanges\fP +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +When this option is changed, the journal still contains data respective to +the previous setting. For example, changing it to \fBnone\fP does not purge +the journal. Also, changing it from \fBall\fP to \fBchanges\fP +does not cause the deletion of the zone\-in\-journal and the behaviour of the +zone loading procedure might be different than expected. It is recommended +to consider purging the journal when this option is changed. +.UNINDENT +.UNINDENT +.SS journal\-max\-usage +.sp +Policy how much space in journal DB will the zone\(aqs journal occupy. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Journal DB may grow far above the sum of journal\-max\-usage across +all zones, because of DB free space fragmentation. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB100M\fP (100 MiB) +.SS journal\-max\-depth +.sp +Maximum history length of the journal. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Zone\-in\-journal changeset isn\(aqt counted to the limit. +.UNINDENT +.UNINDENT +.sp +\fIMinimum:\fP \fB2\fP +.sp +\fIDefault:\fP \fB20\fP +.SS ixfr\-benevolent +.sp +If enabled, incoming IXFR is applied even when it contains removals of non\-existing +or additions of existing records. +.sp +\fIDefault:\fP off +.SS ixfr\-by\-one +.sp +Within incoming IXFR, process only one changeset at a time, not multiple together. +This preserves the complete history in the journal and prevents the merging of +changesets when multiple changesets are IXFRed simultaneously. However, this does not +prevent the merging (or deletion) of old changesets in the journal to save space, +as described in \fI\%journal behaviour\fP\&. +.sp +This option leads to increased server load when processing IXFR, including +network traffic. +.sp +\fIDefault:\fP \fBoff\fP +.SS ixfr\-from\-axfr +.sp +If a primary sends AXFR\-style\-IXFR upon an IXFR request, compute the difference +and process it as an incremental zone update (e.g. by storing the changeset in +the journal). +.sp +\fIDefault:\fP \fBoff\fP +.SS zone\-max\-size +.sp +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. +.sp +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. +.sp +\fIDefault:\fP unlimited +.SS adjust\-threads +.sp +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. +.sp +\fIDefault:\fP \fB1\fP (no extra threads) +.SS dnssec\-signing +.sp +If enabled, automatic DNSSEC signing for the zone is turned on. +.sp +\fIDefault:\fP \fBoff\fP +.SS dnssec\-validation +.sp +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). +.sp +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. +.sp +List of DNSSEC checks: +.INDENT 0.0 +.IP \(bu 2 +Every zone RRSet is correctly signed by at least one present DNSKEY. +.IP \(bu 2 +DNSKEY RRSet is signed by KSK. +.IP \(bu 2 +NSEC(3) RR exists for each name (unless opt\-out) with correct bitmap. +.IP \(bu 2 +Every NSEC(3) RR is linked to the lexicographically next one. +.UNINDENT +.sp +The validation is not affected by \fI\%dnssec\-policy\fP configuration, +except for \fI\%signing\-threads\fP option, which specifies the number +of threads for parallel validation. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Redundant or garbage NSEC3 records are ignored. +.sp +This mode is not compatible with \fI\%dnssec\-signing\fP\&. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS dnssec\-policy +.sp +A \fI\%reference\fP to DNSSEC signing policy. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +A configured policy called \(dqdefault\(dq won\(aqt be used unless explicitly referenced. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP an imaginary policy with all default values +.SS ds\-push +.sp +Per zone configuration of \fI\%ds\-push\fP\&. This option overrides possible +per policy option. +.sp +\fIDefault:\fP not set +.SS zonemd\-verify +.sp +On each zone load/update, verify that ZONEMD is present in the zone and valid. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Zone digest calculation may take much time and CPU on large zones. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBoff\fP +.SS zonemd\-generate +.sp +On each zone update, calculate ZONEMD and put it into the zone. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – No action regarding ZONEMD. +.IP \(bu 2 +\fBzonemd\-sha384\fP – Generate ZONEMD using SHA384 algorithm. +.IP \(bu 2 +\fBzonemd\-sha512\fP – Generate ZONEMD using SHA512 algorithm. +.IP \(bu 2 +\fBremove\fP – Remove any ZONEMD from the zone apex. +.UNINDENT +.sp +\fIDefault:\fP \fBnone\fP +.SS serial\-policy +.sp +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. +.sp +Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBincrement\fP – The serial is incremented according to serial number arithmetic. +.IP \(bu 2 +\fBunixtime\fP – The serial is set to the current unix time. +.IP \(bu 2 +\fBdateserial\fP – The 10\-digit serial (YYYYMMDDnn) is incremented, the first +8 digits match the current iso\-date. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If the resulting serial for \fBunixtime\fP or \fBdateserial\fP 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. +.sp +To avoid user confusion, use \fBdateserial\fP only if you expect at most +100 updates per day per zone and \fBunixtime\fP only if you expect at most +one update per second per zone. +.sp +Generated catalog zones use \fBunixtime\fP only. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBincrement\fP (\fBunixtime\fP for generated catalog zones) +.SS serial\-modulo +.sp +Specifies that the zone serials shall be congruent by specified modulo. +The option value must be a string in the format \fBR/M\fP, where \fBR < M <= 256\fP are +positive integers. Whenever the zone serial is incremented, it is ensured +that \fBserial % M == R\fP\&. This can be useful in the case of multiple inconsistent +primaries, where distinct zone serial sequences prevent cross\-master\-IXFR +by any secondary. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +In order to ensure the congruent policy, this option is only allowed +with \fI\%DNSSEC signing enabled\fP and +\fI\%zonefile\-load\fP to be either \fBdifference\-no\-serial\fP or \fBnone\fP\&. +.sp +Because the zone serial effectively always increments by \fBM\fP instead of +\fB1\fP, it is not recommended to use \fBdateserial\fP \fI\%serial\-policy\fP +or even \fBunixtime\fP in case of rapidly updated zone. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fB0/1\fP +.SS reverse\-generate +.sp +This option triggers the automatic generation of reverse PTR records based on +A/AAAA records in the specified zone. The entire generated zone is automatically +stored in the journal. +.sp +Current limitations: +.INDENT 0.0 +.IP \(bu 2 +Only one zone to be reversed can be specified. +.IP \(bu 2 +Is slow for large zones (even when changing a little). +.UNINDENT +.sp +\fIDefault:\fP none +.SS refresh\-min\-interval +.sp +Forced minimum zone refresh interval (in seconds) to avoid flooding primary server. +.sp +\fIMinimum:\fP \fB2\fP +.sp +\fIDefault:\fP \fB2\fP +.SS refresh\-max\-interval +.sp +Forced maximum zone refresh interval (in seconds). +.sp +\fIDefault:\fP not set +.SS retry\-min\-interval +.sp +Forced minimum zone retry interval (in seconds) to avoid flooding primary server. +.sp +\fIMinimum:\fP \fB1\fP +.sp +\fIDefault:\fP \fB1\fP +.SS retry\-max\-interval +.sp +Forced maximum zone retry interval (in seconds). +.sp +\fIDefault:\fP not set +.SS expire\-min\-interval +.sp +Forced minimum zone expire interval (in seconds) to avoid flooding primary server. +.sp +\fIMinimum:\fP \fB3\fP +.sp +\fIDefault:\fP \fB3\fP +.SS expire\-max\-interval +.sp +Forced maximum zone expire interval (in seconds). +.sp +\fIDefault:\fP not set +.SS catalog\-role +.sp +Trigger zone catalog feature. Possible values: +.INDENT 0.0 +.IP \(bu 2 +\fBnone\fP – Not a catalog zone. +.IP \(bu 2 +\fBinterpret\fP – A catalog zone which is loaded from a zone file or XFR, +and member zones shall be configured based on its contents. +.IP \(bu 2 +\fBgenerate\fP – A catalog zone whose contents are generated according to +assigned member zones. +.IP \(bu 2 +\fBmember\fP – A member zone that is assigned to one generated catalog zone. +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If set to \fBgenerate\fP, the \fI\%zonefile\-load\fP option has no effect +since a zone file is never loaded. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP \fBnone\fP +.SS catalog\-template +.sp +For the catalog member zones, the specified configuration template will be applied. +.sp +Multiple catalog templates may be defined. The first one is used unless the member zone +has the \fIgroup\fP property defined, matching another catalog template. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option must be set if and only if \fI\%catalog\-role\fP is \fIinterpret\fP\&. +.sp +Nested catalog zones aren\(aqt supported. Therefore catalog templates can\(aqt use +\fI\%catalog\-template\fP, \fI\%catalog\-role\fP, \fI\%catalog\-zone\fP, +and \fI\%catalog\-group\fP options. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS catalog\-zone +.sp +Assign this member zone to specified generated catalog zone. +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option must be set if and only if \fI\%catalog\-role\fP is \fImember\fP\&. +.sp +The referenced catalog zone must exist and have \fI\%catalog\-role\fP set to \fIgenerate\fP\&. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS catalog\-group +.sp +Assign this member zone to specified catalog group (configuration template). +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +This option has effect if and only if \fI\%catalog\-role\fP is \fImember\fP\&. +.UNINDENT +.UNINDENT +.sp +\fIDefault:\fP not set +.SS module +.sp +An ordered list of references to query modules in the form of \fImodule_name\fP or +\fImodule_name/module_id\fP\&. These modules apply only to the current zone queries. +.sp +\fIDefault:\fP not set +.SH AUTHOR +CZ.NIC Labs <https://www.knot-dns.cz> +.SH COPYRIGHT +Copyright 2010–2024, CZ.NIC, z.s.p.o. +.\" Generated by docutils manpage writer. +. |