1KNOT.CONF(5) Knot DNS KNOT.CONF(5)
2
6 knot.conf - Knot DNS configuration file
7
9 Configuration files for Knot DNS use simplified YAML format. Simplified
10 means that not all of the features are supported.
11 For the description of configuration items, we have to declare a mean‐
13 ing of the following symbols:
14 • INT – Integer
16 • STR – Textual string
18 • HEXSTR – Hexadecimal string (with 0x prefix)
20 • BOOL – Boolean value (on/off or true/false)
22 • TIME – Number of seconds, an integer with possible time multiplier
24 suffix (s ~ 1, m ~ 60, h ~ 3600 or d ~ 24 * 3600)
25 • SIZE – Number of bytes, an integer with possible size multiplier suf‐
27 fix (B ~ 1, K ~ 1024, M ~ 1024^2 or G ~ 1024^3)
28 • BASE64 – Base64 encoded string
30 • ADDR – IPv4 or IPv6 address
32 • DNAME – Domain name
34 • ... – Multi-valued item, order of the values is preserved
36 • [ ] – Optional value
38 • | – Choice
40 The configuration consists of several fixed sections and optional mod‐
42 ule sections. There are 16 fixed sections (module, server, xdp, con‐
43 trol, log, statistics, database, keystore, key, remote, remotes, acl,
44 submission, policy, template, zone). Module sections are prefixed with
45 the mod- prefix (e.g. mod-stats).
46 Most of the sections (e.g. zone) are sequences of settings blocks. Each
48 settings block begins with a unique identifier, which can be used as a
49 reference from other sections (such an identifier must be defined in
50 advance).
51 A multi-valued item can be specified either as a YAML sequence:
53 address: [10.0.0.1, 10.0.0.2]
55 or as more single-valued items each on an extra line:
57 address: 10.0.0.1
59 address: 10.0.0.2
60 If an item value contains spaces or other special characters, it is
62 necessary to enclose such a value within double quotes " ".
63 If not specified otherwise, an item representing a file or a directory
65 path may be defined either as an absolute path (starting with /), or a
66 path relative to the same directory as the default value of the item.
67
69 A comment begins with a # character and is ignored during processing.
70 Also each configuration section or sequence block allows a permanent
71 comment using the comment item which is stored in the server beside the
72 configuration.
73
75 Another configuration file or files, matching a pattern, can be in‐
76 cluded at the top level in the current file.
77 include: STR
79 include
81 A path or a matching pattern specifying one or more files that are in‐
82 cluded at the place of the include option position in the configura‐
83 tion. If the path is not absolute, then it is considered to be rela‐
84 tive to the current file. The pattern can be an arbitrary string meet‐
85 ing POSIX glob requirements, e.g. dir/*.conf. Matching files are pro‐
86 cessed in sorted order.
87 Default: not set
89
91 Dynamic modules loading configuration.
92 NOTE:
94 If configured with non-empty --with-moduledir=path parameter, all
95 shared modules in this directory will be automatically loaded.
96 module:
98 - id: STR
99 file: STR
100 id
102 A module identifier in the form of the mod- prefix and module name suf‐
103 fix.
104 file
106 A path to a shared library file with the module implementation.
107 WARNING:
109 If the path is not absolute, the library is searched in the set of
110 system directories. See man dlopen for more details.
111 Default: ${libdir}/knot/modules-${version}/module_name.so (or
113 ${path}/module_name.so if configured with --with-moduledir=path)
114
116 General options related to the server.
117 server:
119 identity: [STR]
120 version: [STR]
121 nsid: [STR|HEXSTR]
122 rundir: STR
123 user: STR[:STR]
124 pidfile: STR
125 udp-workers: INT
126 tcp-workers: INT
127 background-workers: INT
128 async-start: BOOL
129 tcp-idle-timeout: TIME
130 tcp-io-timeout: INT
131 tcp-remote-io-timeout: INT
132 tcp-max-clients: INT
133 tcp-reuseport: BOOL
134 tcp-fastopen: BOOL
135 quic-max-clients: INT
136 quic-outbuf-max-size: SIZE
137 quic-idle-close-timeout: TIME
138 remote-pool-limit: INT
139 remote-pool-timeout: TIME
140 remote-retry-delay: TIME
141 socket-affinity: BOOL
142 udp-max-payload: SIZE
143 udp-max-payload-ipv4: SIZE
144 udp-max-payload-ipv6: SIZE
145 key-file: STR
146 cert-file: STR
147 edns-client-subnet: BOOL
148 answer-rotation: BOOL
149 automatic-acl: BOOL
150 proxy-allowlist: ADDR[/INT] | ADDR-ADDR ...
151 dbus-event: none | running | zone-updated | ksk-submission | dnssec-invalid ...
152 dbus-init-delay: TIME
153 listen: ADDR[@INT] | STR ...
154 listen-quic: ADDR[@INT] ...
155 CAUTION:
157 When you change configuration parameters dynamically or via configu‐
158 ration file reload, some parameters in the Server section require
159 restarting the Knot server so that the changes take effect. See be‐
160 low for the details.
161 identity
163 An identity of the server returned in the response to the query for TXT
164 record id.server. or hostname.bind. in the CHAOS class (RFC 4892). Set
165 to an empty value to disable.
166 Default: FQDN hostname
168 version
170 A version of the server software returned in the response to the query
171 for TXT record version.server. or version.bind. in the CHAOS class (RFC
172 4892). Set to an empty value to disable.
173 Default: server version
175 nsid
177 A DNS name server identifier (RFC 5001). Set to an empty value to dis‐
178 able.
179 Default: FQDN hostname at the moment of the daemon start
181 rundir
183 A path for storing run-time data (PID file, unix sockets, etc.). A
184 non-absolute path is relative to the knotd startup directory.
185 Depending on the usage of this parameter, its change may require
187 restart of the Knot server to take effect.
188 Default: ${localstatedir}/run/knot (configured with --with-rundir=path)
190 user
192 A system user with an optional system group (user:group) under which
193 the server is run after starting and binding to interfaces. Linux capa‐
194 bilities are employed if supported.
195 Change of this parameter requires restart of the Knot server to take
197 effect.
198 Default: root:root
200 pidfile
202 A PID file location.
203 Change of this parameter requires restart of the Knot server to take
205 effect.
206 Default: rundir/knot.pid
208 udp-workers
210 A number of UDP workers (threads) used to process incoming queries over
211 UDP.
212 Change of this parameter requires restart of the Knot server to take
214 effect.
215 Default: equal to the number of online CPUs
217 tcp-workers
219 A number of TCP workers (threads) used to process incoming queries over
220 TCP.
221 Change of this parameter requires restart of the Knot server to take
223 effect.
224 Default: equal to the number of online CPUs, default value is at least
226 10
227 background-workers
229 A number of workers (threads) used to execute background operations
230 (zone loading, zone updates, etc.).
231 Change of this parameter requires restart of the Knot server to take
233 effect.
234 Default: equal to the number of online CPUs, default value is at most
236 10
237 async-start
239 If enabled, server doesn't wait for the zones to be loaded and starts
240 responding immediately with SERVFAIL answers until the zone loads.
241 Default: off
243 tcp-idle-timeout
245 Maximum idle time (in seconds) between requests on an inbound TCP con‐
246 nection. It means if there is no activity on an inbound TCP connection
247 during this limit, the connection is closed by the server.
248 Minimum: 1
250 Default: 10
252 tcp-io-timeout
254 Maximum time (in milliseconds) to receive or send one DNS message over
255 an inbound TCP connection. It means this limit applies to normal DNS
256 queries and replies, incoming DDNS, and outgoing zone transfers. The
257 timeout is measured since some data is already available for process‐
258 ing. Set to 0 for infinity.
259 Default: 500 (milliseconds)
261 CAUTION:
263 In order to reduce the risk of Slow Loris attacks, it's recommended
264 setting this limit as low as possible on public servers.
265 tcp-remote-io-timeout
267 Maximum time (in milliseconds) to receive or send one DNS message over
268 an outbound TCP connection which has already been established to a con‐
269 figured remote server. It means this limit applies to incoming zone
270 transfers, sending NOTIFY, DDNS forwarding, and DS check or push. This
271 timeout includes the time needed for a network round-trip and for a
272 query processing by the remote. Set to 0 for infinity.
273 Default: 5000 (milliseconds)
275 tcp-reuseport
277 If enabled, each TCP worker listens on its own socket and the OS kernel
278 socket load balancing is employed using SO_REUSEPORT (or SO_REUSE‐
279 PORT_LB on FreeBSD). Due to the lack of one shared socket, the server
280 can offer higher response rate processing over TCP. However, in the
281 case of time-consuming requests (e.g. zone transfers of a TLD zone),
282 enabled reuseport may result in delayed or not being responded client
283 requests. So it is advisable to use this option on secondary servers.
284 Change of this parameter requires restart of the Knot server to take
286 effect.
287 Default: off
289 tcp-fastopen
291 If enabled, use TCP Fast Open for outbound TCP communication (client
292 side): incoming zone transfers, sending NOTIFY, and DDNS forwarding.
293 This mode simplifies TCP handshake and can result in better networking
294 performance. TCP Fast Open for inbound TCP communication (server side)
295 isn't affected by this configuration as it's enabled automatically if
296 supported by OS.
297 NOTE:
299 The TCP Fast Open support must also be enabled on the OS level:
300 • Linux/macOS: ensure kernel parameter net.ipv4.tcp_fastopen is 2 or
302 3 for server side, and 1 or 3 for client side.
303 • FreeBSD: ensure kernel parameter net.inet.tcp.fastopen.server_en‐
305 able is 1 for server side, and net.inet.tcp.fastopen.client_enable
306 is 1 for client side.
307 Default: off
309 quic-max-clients
311 A maximum number of QUIC clients connected in parallel.
312 See also quic.
314 Change of this parameter requires restart of the Knot server to take
316 effect.
317 Minimum: 128
319 Default: 10000 (ten thousand)
321 quic-outbuf-max-size
323 Maximum cumulative size of memory used for buffers of unACKed sent mes‐
324 sages. This limit is per one UDP worker.
325 NOTE:
327 Set low if little memory is available (together with
328 quic-max-clients since QUIC connections are memory-heavy). Set to
329 high value if outgoing zone transfers of big zone over QUIC are ex‐
330 pected.
331 Change of this parameter requires restart of the Knot server to take
333 effect.
334 Minimum: 1M (1 MiB)
336 Default: 100M (100 MiB)
338 quic-idle-close-timeout
340 Time in seconds, after which any idle QUIC connection is gracefully
341 closed.
342 Change of this parameter requires restart of the Knot server to take
344 effect.
345 Minimum: 1
347 Default: 4
349 remote-pool-limit
351 If nonzero, the server will keep up to this number of outgoing TCP con‐
352 nections open for later use. This is an optimization to avoid frequent
353 opening of TCP connections to the same remote.
354 Change of this parameter requires restart of the Knot server to take
356 effect.
357 Default: 0
359 remote-pool-timeout
361 The timeout in seconds after which the unused kept-open outgoing TCP
362 connections to remote servers are closed.
363 Default: 5
365 remote-retry-delay
367 When a connection attempt times out to some remote address, this infor‐
368 mation will be kept for this specified time (in milliseconds) and other
369 connections to the same address won't be attempted. This prevents
370 repetitive waiting for timeout on an unreachable remote.
371 Default: 0
373 socket-affinity
375 If enabled and if SO_REUSEPORT is available on Linux, all configured
376 network sockets are bound to UDP and TCP workers in order to increase
377 the networking performance. This mode isn't recommended for setups
378 where the number of network card queues is lower than the number of UDP
379 or TCP workers.
380 Change of this parameter requires restart of the Knot server to take
382 effect.
383 Default: off
385 tcp-max-clients
387 A maximum number of TCP clients connected in parallel, set this below
388 the file descriptor limit to avoid resource exhaustion.
389 NOTE:
391 It is advisable to adjust the maximum number of open files per
392 process in your operating system configuration.
393 Default: one half of the file descriptor limit for the server process
395 udp-max-payload
397 Maximum EDNS0 UDP payload size default for both IPv4 and IPv6.
398 Default: 1232
400 udp-max-payload-ipv4
402 Maximum EDNS0 UDP payload size for IPv4.
403 Default: 1232
405 udp-max-payload-ipv6
407 Maximum EDNS0 UDP payload size for IPv6.
408 Default: 1232
410 key-file
412 Path to a server key PEM file which is used for DNS over QUIC communi‐
413 cation. A non-absolute path of a user specified key file is relative
414 to the /etc/knot directory.
415 Change of this parameter requires restart of the Knot server to take
417 effect.
418 Default: auto-generated key
420 cert-file
422 Path to a server certificate PEM file which is used for DNS over QUIC
423 communication. A non-absolute path is relative to the /etc/knot direc‐
424 tory.
425 Change of this parameter requires restart of the Knot server to take
427 effect.
428 Default: one-time in-memory certificate
430 edns-client-subnet
432 Enable or disable EDNS Client Subnet support. If enabled, responses to
433 queries containing the EDNS Client Subnet option always contain a valid
434 EDNS Client Subnet option according to RFC 7871.
435 Default: off
437 answer-rotation
439 Enable or disable sorted-rrset rotation in the answer section of normal
440 replies. The rotation shift is simply determined by a query ID.
441 Default: off
443 automatic-acl
445 If enabled, automatic ACL setting of configured remotes is considered
446 when evaluating authorized operations.
447 Default: off
449 proxy-allowlist
451 An ordered list of IP addresses, network subnets, or network ranges
452 which are allowed as a source address of proxied DNS traffic over UDP.
453 The supported proxy protocol is haproxy PROXY v2.
454 NOTE:
456 TCP is not supported.
457 Default: not set
459 dbus-event
461 Specification of server or zone states which emit a D-Bus signal on the
462 system bus. The bus name is cz.nic.knotd, the object path is
463 /cz/nic/knotd, and the interface name is cz.nic.knotd.events.
464 Possible values:
466 • none – No signal is emitted.
468 • running – There are two possible signals emitted:
470 • started when the server is started and all configured zones (in‐
472 cluding catalog zones and their members) are loaded or successfully
473 bootstrapped.
474 • stopped when the server shutdown sequence is initiated.
476 • zone-updated – The signal zone_updated is emitted when a zone has
478 been updated; the signal parameters are zone name and zone SOA se‐
479 rial.
480 • keys-updated - The signal keys_updated is emitted when a DNSSEC key
482 set of this zone is updated.
483 • ksk-submission – The signal zone_ksk_submission is emitted if there
485 is a ready KSK present when the zone is signed; the signal parameters
486 are zone name, KSK keytag, and KSK KASP id.
487 • dnssec-invalid – The signal zone_dnssec_invalid is emitted when
489 DNSSEC validation fails; the signal parameter is zone name.
490 NOTE:
492 This function requires systemd version at least 221.
493 Change of this parameter requires restart of the Knot server to take
495 effect.
496 Default: none
498 dbus-init-delay
500 Time in seconds which the server waits upon D-Bus initialization to en‐
501 sure the D-Bus client is ready to receive signals.
502 Change of this parameter requires restart of the Knot server to take
504 effect.
505 Minimum: 0
507 Default: 1
509 listen
511 One or more IP addresses where the server listens for incoming queries.
512 Optional port specification (default is 53) can be appended to each ad‐
513 dress using @ separator. Use 0.0.0.0 for all configured IPv4 addresses
514 or :: for all configured IPv6 addresses. Filesystem path can be speci‐
515 fied for listening on local unix SOCK_STREAM socket. Non-absolute path
516 (i.e. not starting with /) is relative to rundir. Non-local address
517 binding is automatically enabled if supported by the operating system.
518 Change of this parameter requires restart of the Knot server to take
520 effect.
521 Default: not set
523 listen-quic
525 One or more IP addresses (and optionally ports) where the server lis‐
526 tens for incoming queries over QUIC protocol.
527 Change of this parameter requires restart of the Knot server to take
529 effect.
530 Default: not set
532 NOTE:
534 Incoming DDNS over QUIC isn't supported. The server always responds
535 with SERVFAIL.
536
538 Various options related to XDP listening, especially TCP.
539 xdp:
541 listen: STR[@INT] | ADDR[@INT] ...
542 udp: BOOL
543 tcp: BOOL
544 quic: BOOL
545 quic-port: INT
546 tcp-max-clients: INT
547 tcp-inbuf-max-size: SIZE
548 tcp-outbuf-max-size: SIZE
549 tcp-idle-close-timeout: TIME
550 tcp-idle-reset-timeout: TIME
551 tcp-resend-timeout: TIME
552 route-check: BOOL
553 CAUTION:
555 When you change configuration parameters dynamically or via configu‐
556 ration file reload, some parameters in the XDP section require
557 restarting the Knot server so that the changes take effect.
558 listen
560 One or more network device names (e.g. ens786f0) on which the Mode XDP
561 is enabled. Alternatively, an IP address can be used instead of a de‐
562 vice name, but the server will still listen on all addresses belonging
563 to the same interface! Optional port specification (default is 53) can
564 be appended to each device name or address using @ separator.
565 Change of this parameter requires restart of the Knot server to take
567 effect.
568 CAUTION:
570 If XDP workers only process regular DNS traffic over UDP, it is
571 strongly recommended to also listen on the addresses which are in‐
572 tended to offer the DNS service, at least to fulfil the DNS require‐
573 ment for working TCP.
574 NOTE:
576 Incoming DDNS over XDP isn't supported. The server always responds
577 with SERVFAIL.
578 Default: not set
580 udp
582 If enabled, DNS over UDP is processed with XDP workers.
583 Change of this parameter requires restart of the Knot server to take
585 effect.
586 Default: on
588 tcp
590 If enabled, DNS over TCP traffic is processed with XDP workers.
591 The TCP stack limitations:
593 • Congestion control is not implemented.
595 • Lost packets that do not contain TCP payload may not be resend.
597 • Not optimized for transfers of non-trivial zones.
599 Change of this parameter requires restart of the Knot server to take
601 effect.
602 Default: off
604 quic
606 If enabled, DNS over QUIC is processed with XDP workers.
607 Change of this parameter requires restart of the Knot server to take
609 effect.
610 Default: off
612 quic-port
614 DNS over QUIC will listen on the interfaces configured by listen, but
615 on different port, configured by this option.
616 Change of this parameter requires restart of the Knot server to take
618 effect.
619 Default: 853
621 tcp-max-clients
623 A maximum number of TCP clients connected in parallel.
624 Minimum: 1024
626 Default: 1000000 (one million)
628 tcp-inbuf-max-size
630 Maximum cumulative size of memory used for buffers of incompletely re‐
631 ceived messages.
632 Minimum: 1M (1 MiB)
634 Default: 100M (100 MiB)
636 tcp-outbuf-max-size
638 Maximum cumulative size of memory used for buffers of unACKed sent mes‐
639 sages.
640 Minimum: 1M (1 MiB)
642 Default: 100M (100 MiB)
644 tcp-idle-close-timeout
646 Time in seconds, after which any idle connection is gracefully closed.
647 Minimum: 1
649 Default: 10
651 tcp-idle-reset-timeout
653 Time in seconds, after which any idle connection is forcibly closed.
654 Minimum: 1
656 Default: 20
658 tcp-resend-timeout
660 Resend outgoing data packets (with DNS response payload) if not ACKed
661 before this timeout.
662 Minimum: 1
664 Default: 5
666 route-check
668 If enabled, routing information from the operating system is considered
669 when processing every incoming DNS packet received over the XDP inter‐
670 face:
671 • If the outgoing interface of the corresponding DNS response differs
673 from the incoming one, the packet is processed normally by UDP/TCP
674 workers (XDP isn't used).
675 • If the destination address is blackholed, unreachable, or prohibited,
677 the DNS packet is dropped without any response.
678 • The destination MAC address and possible VLAN tag for the response
680 are taken from the routing system.
681 If disabled, symmetrical routing is applied. It means that the query
683 source MAC address is used as a response destination MAC address. Pos‐
684 sible VLAN tag is preserved.
685 Change of this parameter requires restart of the Knot server to take
687 effect.
688 NOTE:
690 This mode requires forwarding enabled on the loopback interface
691 (sysctl -w net.ipv4.conf.lo.forwarding=1 and sysctl -w
692 net.ipv6.conf.lo.forwarding=1). If forwarding is disabled, all in‐
693 coming DNS packets are dropped!
694 Only VLAN 802.1Q is supported.
696 Default: off
698
700 Configuration of the server control interface.
701 control:
703 listen: STR
704 timeout: TIME
705 listen
707 A UNIX socket path where the server listens for control commands.
708 Default: rundir/knot.sock
710 timeout
712 Maximum time (in seconds) the control socket operations can take. Set
713 to 0 for infinity.
714 Default: 5
716
718 Server can be configured to log to the standard output, standard error
719 output, syslog (or systemd journal if systemd is enabled) or into an
720 arbitrary file.
721 There are 6 logging severity levels:
723 • critical – Non-recoverable error resulting in server shutdown.
725 • error – Recoverable error, action should be taken.
727 • warning – Warning that might require user action.
729 • notice – Server notice or hint.
731 • info – Informational message.
733 • debug – Debug or detailed message.
735 In the case of a missing log section, warning or more serious messages
737 will be logged to both standard error output and syslog. The info and
738 notice messages will be logged to standard output.
739 log:
741 - target: stdout | stderr | syslog | STR
742 server: critical | error | warning | notice | info | debug
743 control: critical | error | warning | notice | info | debug
744 zone: critical | error | warning | notice | info | debug
745 quic: critical | error | warning | notice | info | debug
746 any: critical | error | warning | notice | info | debug
747 target
749 A logging output.
750 Possible values:
752 • stdout – Standard output.
754 • stderr – Standard error output.
756 • syslog – Syslog or systemd journal.
758 • file_name – A specific file.
760 With syslog target, syslog service is used. However, if Knot DNS has
762 been compiled with systemd support and operating system has been booted
763 with systemd, systemd journal is used for logging instead of syslog.
764 A file_name may be specified as an absolute path or a path relative to
766 the knotd startup directory.
767 server
769 Minimum severity level for messages related to general operation of the
770 server to be logged.
771 Default: not set
773 control
775 Minimum severity level for messages related to server control to be
776 logged.
777 Default: not set
779 zone
781 Minimum severity level for messages related to zones to be logged.
782 Default: not set
784 quic
786 Minimum severity level for messages related to QUIC to be logged.
787 Default: not set
789 any
791 Minimum severity level for all message types, except quic, to be
792 logged.
793 Default: not set
795
797 Periodic server statistics dumping.
798 statistics:
800 timer: TIME
801 file: STR
802 append: BOOL
803 timer
805 A period (in seconds) after which all available statistics metrics will
806 by written to the file.
807 Default: not set
809 file
811 A file path of statistics output in the YAML format.
812 Default: rundir/stats.yaml
814 append
816 If enabled, the output will be appended to the file instead of file re‐
817 placement.
818 Default: off
820
822 Configuration of databases for zone contents, DNSSEC metadata, or event
823 timers.
824 database:
826 storage: STR
827 journal-db: STR
828 journal-db-mode: robust | asynchronous
829 journal-db-max-size: SIZE
830 kasp-db: STR
831 kasp-db-max-size: SIZE
832 timer-db: STR
833 timer-db-max-size: SIZE
834 catalog-db: str
835 catalog-db-max-size: SIZE
836 storage
838 A data directory for storing journal, KASP, and timer databases. A
839 non-absolute path is relative to the knotd startup directory.
840 Default: ${localstatedir}/lib/knot (configured with --with-stor‐
842 age=path)
843 journal-db
845 An explicit specification of the persistent journal database directory.
846 Default: storage/journal
848 journal-db-mode
850 Specifies journal LMDB backend configuration, which influences perfor‐
851 mance and durability.
852 Possible values:
854 • robust – The journal database disk synchronization ensures database
856 durability but is generally slower.
857 • asynchronous – The journal database disk synchronization is optimized
859 for better performance at the expense of lower database durability in
860 the case of a crash. This mode is recommended on secondary servers
861 with many zones.
862 Default: robust
864 journal-db-max-size
866 The hard limit for the journal database maximum size. There is no
867 cleanup logic in journal to recover from reaching this limit. Journal
868 simply starts refusing changes across all zones. Decreasing this value
869 has no effect if it is lower than the actual database file size.
870 It is recommended to limit journal-max-usage per-zone instead of
872 journal-db-max-size in most cases. Please keep this value larger than
873 the sum of all zones' journal usage limits. See more details regarding
874 journal behaviour.
875 NOTE:
877 This value also influences server's usage of virtual memory.
878 Default: 20G (20 GiB), or 512M (512 MiB) for 32-bit
880 kasp-db
882 An explicit specification of the KASP database directory.
883 Default: storage/keys
885 kasp-db-max-size
887 The hard limit for the KASP database maximum size.
888 NOTE:
890 This value also influences server's usage of virtual memory.
891 Default: 500M (500 MiB)
893 timer-db
895 An explicit specification of the persistent timer database directory.
896 Default: storage/timers
898 timer-db-max-size
900 The hard limit for the timer database maximum size.
901 NOTE:
903 This value also influences server's usage of virtual memory.
904 Default: 100M (100 MiB)
906 catalog-db
908 An explicit specification of the zone catalog database directory. Only
909 useful if Catalog zones are enabled.
910 Default: storage/catalog
912 catalog-db-max-size
914 The hard limit for the catalog database maximum size.
915 NOTE:
917 This value also influences server's usage of virtual memory.
918 Default: 20G (20 GiB), or 512M (512 MiB) for 32-bit
920
922 DNSSEC keystore configuration.
923 keystore:
925 - id: STR
926 backend: pem | pkcs11
927 config: STR
928 key-label: BOOL
929 id
931 A keystore identifier.
932 backend
934 A key storage backend type.
935 Possible values:
937 • pem – PEM files.
939 • pkcs11 – PKCS #11 storage.
941 Default: pem
943 config
945 A backend specific configuration. A directory with PEM files (the path
946 can be specified as a relative path to kasp-db) or a configuration
947 string for PKCS #11 storage (<pkcs11-uri> <module-path>). The PKCS #11
948 URI Scheme is defined in RFC 7512.
949 NOTE:
951 Example configuration string for PKCS #11:
952 "pkcs11:token=knot;pin-value=1234 /usr/lib64/pkcs11/libsofthsm2.so"
954 Default: kasp-db/keys
956 key-label
958 If enabled in combination with the PKCS #11 backend, generated keys are
959 labeled in the form <zone_name> KSK|ZSK.
960 Default: off
962
964 Shared TSIG keys used to authenticate communication with the server.
965 key:
967 - id: DNAME
968 algorithm: hmac-md5 | hmac-sha1 | hmac-sha224 | hmac-sha256 | hmac-sha384 | hmac-sha512
969 secret: BASE64
970 id
972 A key name identifier.
973 NOTE:
975 This value MUST be exactly the same as the name of the TSIG key on
976 the opposite primary/secondary server(s).
977 algorithm
979 A TSIG key algorithm. See TSIG Algorithm Numbers.
980 Possible values:
982 • hmac-md5
984 • hmac-sha1
986 • hmac-sha224
988 • hmac-sha256
990 • hmac-sha384
992 • hmac-sha512
994 Default: not set
996 secret
998 Shared key secret.
999 Default: not set
1001
1003 Definitions of remote servers for outgoing connections (source of a
1004 zone transfer, target for a notification, etc.).
1005 remote:
1007 - id: STR
1008 address: ADDR[@INT] | STR ...
1009 via: ADDR[@INT] ...
1010 quic: BOOL
1011 key: key_id
1012 cert-key: BASE64 ...
1013 block-notify-after-transfer: BOOL
1014 no-edns: BOOL
1015 automatic-acl: BOOL
1016 id
1018 A remote identifier.
1019 address
1021 An ordered list of destination IP addresses or UNIX socket paths which
1022 are used for communication with the remote server. Non-absolute path
1023 (i.e. not starting with /) is relative to rundir. Optional destination
1024 port (default is 53 for UDP/TCP and 853 for QUIC) can be appended to
1025 the address using @ separator. The addresses are tried in sequence un‐
1026 til the remote is reached.
1027 Default: not set
1029 NOTE:
1031 If the remote is contacted and it refuses to perform requested ac‐
1032 tion, no more addresses will be tried for this remote.
1033 via
1035 An ordered list of source IP addresses. The first address with the same
1036 family as the destination address is used as a source address for com‐
1037 munication with the remote. This option can help if the server listens
1038 on more addresses. Optional source port (default is random) can be ap‐
1039 pended to the address using @ separator.
1040 Default: not set
1042 quic
1044 If this option is set, the QUIC protocol will be used for outgoing com‐
1045 munication with this remote.
1046 NOTE:
1048 One connection per each remote is opened; remote-pool-limit does not
1049 take effect for QUIC. However, fast QUIC handshakes utilizing ob‐
1050 tained session tickets are used for reopening connections to re‐
1051 cently (up to 1 day) queried remotes.
1052 Default: off
1054 key
1056 A reference to the TSIG key which is used to authenticate the communi‐
1057 cation with the remote server.
1058 Default: not set
1060 cert-key
1062 An ordered list of remote certificate public key PINs. If the list is
1063 non-empty, communication with the remote is possible only via QUIC pro‐
1064 tocol and a peer certificate is required. The peer certificate key must
1065 match one of the specified PINs.
1066 A PIN is a unique identifier that represents the public key of the peer
1068 certificate. It's a base64-encoded SHA-256 hash of the public key.
1069 This identifier remains the same on a certificate renewal.
1070 Default: not set
1072 block-notify-after-transfer
1074 When incoming AXFR/IXFR from this remote (as a primary server), sup‐
1075 press sending NOTIFY messages to all configured secondary servers.
1076 Default: off
1078 no-edns
1080 If enabled, no OPT record (EDNS) is inserted to outgoing requests to
1081 this remote server. This mode is necessary for communication with some
1082 broken implementations (e.g. Windows Server 2016).
1083 NOTE:
1085 This option effectively disables zone expire timer updates via EDNS
1086 EXPIRE option specified in RFC 7314.
1087 Default: off
1089 automatic-acl
1091 If enabled, some authorized operations for the remote are automatically
1092 allowed based on the context:
1093 • Incoming NOTIFY is allowed from the remote if it's configured as a
1095 primary server for the zone.
1096 • Outgoing zone transfer is allowed to the remote if it's configured as
1098 a NOTIFY target for the zone.
1099 Automatic ACL rules are evaluated before explicit zone ACL configura‐
1101 tion.
1102 NOTE:
1104 This functionality requires global activation via automatic-acl in
1105 the server section.
1106 Default: on
1108
1110 Definitions of groups of remote servers. Remote grouping can simplify
1111 the configuration.
1112 remotes:
1114 - id: STR
1115 remote: remote_id ...
1116 id
1118 A remote group identifier.
1119 remote
1121 An ordered list of references to remote server definitions.
1122 Default: not set
1124
1126 Access control list rule definitions. An ACL rule is a description of
1127 one or more authorized operations (zone transfer request, zone change
1128 notification, and dynamic DNS update) which are allowed to be processed
1129 or denied.
1130 acl:
1132 - id: STR
1133 address: ADDR[/INT] | ADDR-ADDR | STR ...
1134 key: key_id ...
1135 cert-key: BASE64 ...
1136 remote: remote_id | remotes_id ...
1137 action: query | notify | transfer | update ...
1138 deny: BOOL
1139 update-type: STR ...
1140 update-owner: key | zone | name
1141 update-owner-match: sub-or-equal | equal | sub
1142 update-owner-name: STR ...
1143 id
1145 An ACL rule identifier.
1146 address
1148 An ordered list of IP addresses, absolute UNIX socket paths, network
1149 subnets, or network ranges. The query's source address must match one
1150 of them. If this item is not set, address match is not required.
1151 Default: not set
1153 key
1155 An ordered list of references to TSIG keys. The query must match one of
1156 them. If this item is not set, transaction authentication is not used.
1157 Default: not set
1159 cert-key
1161 An ordered list of remote certificate public key PINs. If the list is
1162 non-empty, communication with the remote is possible only via QUIC pro‐
1163 tocol and a peer certificate is required. The peer certificate key must
1164 match one of the specified PINs.
1165 A PIN is a unique identifier that represents the public key of the peer
1167 certificate. It's a base64-encoded SHA-256 hash of the public key.
1168 This identifier remains the same on a certificate renewal.
1169 Default: not set
1171 remote
1173 An ordered list of references remote and remotes. The query must match
1174 one of the remotes. Specifically, one of the remote's addresses and re‐
1175 mote's TSIG key if configured must match.
1176 NOTE:
1178 This option cannot be specified along with the address or key option
1179 at one ACL item.
1180 Default: not set
1182 action
1184 An ordered list of allowed (or denied) actions.
1185 Possible values:
1187 • query – Allow regular DNS query. As normal queries are always al‐
1189 lowed, this action is only useful in combination with TSIG key.
1190 • notify – Allow incoming notify (NOTIFY).
1192 • transfer – Allow zone transfer (AXFR, IXFR).
1194 • update – Allow zone updates (DDNS).
1196 Default: query
1198 deny
1200 If enabled, instead of allowing, deny the specified action, address,
1201 key, or combination if these items. If no action is specified, deny all
1202 actions.
1203 Default: off
1205 update-type
1207 A list of allowed types of Resource Records in a zone update. Every
1208 record in an update must match one of the specified types.
1209 Default: not set
1211 update-owner
1213 This option restricts possible owners of Resource Records in a zone up‐
1214 date by comparing them to either the TSIG key identity, the current
1215 zone name, or to a list of domain names given by the update-owner-name
1216 option. The comparison method is given by the update-owner-match op‐
1217 tion.
1218 Possible values:
1220 • key — The owner of each updated RR must match the identity of the
1222 TSIG key if used.
1223 • name — The owner of each updated RR must match at least one name in
1225 the update-owner-name list.
1226 • zone — The owner of each updated RR must match the current zone name.
1228 Default: not set
1230 update-owner-match
1232 This option defines how the owners of Resource Records in an update are
1233 matched to the domain name(s) set by the update-owner option.
1234 Possible values:
1236 • sub-or-equal — The owner of each RR in an update must either be equal
1238 to or be a subdomain of at least one domain name set by update-owner.
1239 • equal — The owner of each updated RR must be equal to at least one
1241 domain name set by update-owner.
1242 • sub — The owner of each updated RR must be a subdomain of, but MUST
1244 NOT be equal to at least one domain name set by update-owner.
1245 Default: sub-or-equal
1247 update-owner-name
1249 A list of allowed owners of RRs in a zone update used with update-owner
1250 set to name. Every listed owner name which is not FQDN (i.e. it doesn't
1251 end in a dot) is considered as if it was appended with the target zone
1252 name. Such a relative owner name specification allows better ACL rule
1253 reusability across multiple zones.
1254 Default: not set
1256
1258 Parameters of KSK submission checks.
1259 submission:
1261 - id: STR
1262 parent: remote_id | remotes_id ...
1263 check-interval: TIME
1264 timeout: TIME
1265 parent-delay: TIME
1266 id
1268 A submission identifier.
1269 parent
1271 A list of references remote and remotes to parent's DNS servers to be
1272 checked for presence of corresponding DS records in the case of KSK
1273 submission. All of them must have a corresponding DS for the rollover
1274 to continue. If none is specified, the rollover must be pushed forward
1275 manually.
1276 Default: not set
1278 TIP:
1280 A DNSSEC-validating resolver can be set as a parent.
1281 check-interval
1283 Interval for periodic checks of DS presence on parent's DNS servers, in
1284 the case of the KSK submission.
1285 Default: 1h (1 hour)
1287 timeout
1289 After this time period (in seconds) the KSK submission is automatically
1290 considered successful, even if all the checks were negative or no par‐
1291 ents are configured. Set to 0 for infinity.
1292 Default: 0
1294 parent-delay
1296 After successful parent DS check, wait for this period before continu‐
1297 ing the next key roll-over step. This delay shall cover the propagation
1298 delay of update in the parent zone.
1299 Default: 0
1301
1303 Parameters of DNSKEY dynamic-update synchrnization.
1304 dnskey-sync:
1306 - id: STR
1307 remote: remote_id | remotes_id ...
1308 check-interval: TIME
1309 id
1311 A dnskey-sync identifier.
1312 remote
1314 A list of references remote and remotes to other signers or common mas‐
1315 ter, which the DDNS updates with DNSKEY/CDNSKEY/CDS records shall be
1316 sent to.
1317 Default: not set
1319 check-interval
1321 If the last DNSKEY sync failed or resulted in any change, re-check the
1322 consistence after this interval and re-try if needed.
1323 Default: 60 (1 minute)
1325
1327 DNSSEC policy configuration.
1328 policy:
1330 - id: STR
1331 keystore: keystore_id
1332 manual: BOOL
1333 single-type-signing: BOOL
1334 algorithm: rsasha1 | rsasha1-nsec3-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384 | ed25519 | ed448
1335 ksk-size: SIZE
1336 zsk-size: SIZE
1337 ksk-shared: BOOL
1338 dnskey-ttl: TIME
1339 zone-max-ttl: TIME
1340 ksk-lifetime: TIME
1341 zsk-lifetime: TIME
1342 delete-delay: TIME
1343 propagation-delay: TIME
1344 rrsig-lifetime: TIME
1345 rrsig-refresh: TIME
1346 rrsig-pre-refresh: TIME
1347 reproducible-signing: BOOL
1348 nsec3: BOOL
1349 nsec3-iterations: INT
1350 nsec3-opt-out: BOOL
1351 nsec3-salt-length: INT
1352 nsec3-salt-lifetime: TIME
1353 signing-threads: INT
1354 ksk-submission: submission_id
1355 ds-push: remote_id | remotes_id ...
1356 cds-cdnskey-publish: none | delete-dnssec | rollover | always | double-ds
1357 cds-digest-type: sha256 | sha384
1358 dnskey-management: full | incremental
1359 offline-ksk: BOOL
1360 unsafe-operation: none | no-check-keyset | no-update-dnskey | no-update-nsec | no-update-expired ...
1361 id
1363 A policy identifier.
1364 keystore
1366 A reference to a keystore holding private key material for zones.
1367 Default: an imaginary keystore with all default values
1369 NOTE:
1371 A configured keystore called "default" won't be used unless explic‐
1372 itly referenced.
1373 manual
1375 If enabled, automatic key management is not used.
1376 Default: off
1378 single-type-signing
1380 If enabled, Single-Type Signing Scheme is used in the automatic key
1381 management mode.
1382 Default: off (module onlinesign has default on)
1384 algorithm
1386 An algorithm of signing keys and issued signatures. See DNSSEC Algo‐
1387 rithm Numbers.
1388 Possible values:
1390 • rsasha1
1392 • rsasha1-nsec3-sha1
1394 • rsasha256
1396 • rsasha512
1398 • ecdsap256sha256
1400 • ecdsap384sha384
1402 • ed25519
1404 • ed448
1406 NOTE:
1408 Ed25519 algorithm is only available if compiled with GnuTLS 3.6.0+.
1409 Ed448 algorithm is only available if compiled with GnuTLS 3.6.12+
1411 and Nettle 3.6+.
1412 Default: ecdsap256sha256
1414 ksk-size
1416 A length of newly generated KSK or CSK keys.
1417 Default: 2048 (rsa*), 256 (ecdsap256), 384 (ecdsap384), 256 (ed25519),
1419 456 (ed448)
1420 zsk-size
1422 A length of newly generated ZSK keys.
1423 Default: see default for ksk-size
1425 ksk-shared
1427 If enabled, all zones with this policy assigned will share one or more
1428 KSKs. More KSKs can be shared during a KSK rollover.
1429 WARNING:
1431 As the shared KSK set is bound to the policy id, renaming the policy
1432 breaks this connection and new shared KSK set is initiated when a
1433 new KSK is needed.
1434 Default: off
1436 dnskey-ttl
1438 A TTL value for DNSKEY records added into zone apex.
1439 NOTE:
1441 Has influence over ZSK key lifetime.
1442 WARNING:
1444 Ensure all DNSKEYs with updated TTL are propagated before any subse‐
1445 quent DNSKEY rollover starts.
1446 Default: zone SOA TTL
1448 zone-max-ttl
1450 Declare (override) maximal TTL value among all the records in zone.
1451 NOTE:
1453 It's generally recommended to override the maximal TTL computation
1454 by setting this explicitly whenever possible. It's required for
1455 DNSSEC Offline KSK and really reasonable when records are generated
1456 dynamically (e.g. by a module).
1457 Default: computed after zone is loaded
1459 ksk-lifetime
1461 A period between KSK activation and the next rollover initiation.
1462 NOTE:
1464 KSK key lifetime is also influenced by propagation-delay,
1465 dnskey-ttl, and KSK submission delay.
1466 Zero (aka infinity) value causes no KSK rollover as a result.
1468 This applies for CSK lifetime if single-type-signing is enabled.
1470 Default: 0
1472 zsk-lifetime
1474 A period between ZSK activation and the next rollover initiation.
1475 NOTE:
1477 More exactly, this period is measured since a ZSK is activated, and
1478 after this, a new ZSK is generated to replace it within following
1479 roll-over.
1480 ZSK key lifetime is also influenced by propagation-delay and
1482 dnskey-ttl
1483 Zero (aka infinity) value causes no ZSK rollover as a result.
1485 Default: 30d (30 days)
1487 delete-delay
1489 Once a key (KSK or ZSK) is rolled-over and removed from the zone, keep
1490 it in the KASP database for at least this period before deleting it
1491 completely. This might be useful in some troubleshooting cases when
1492 resurrection is needed.
1493 Default: 0
1495 propagation-delay
1497 An extra delay added for each key rollover step. This value should be
1498 high enough to cover propagation of data from the primary server to all
1499 secondary servers, as well as the duration of signing routine itself
1500 and possible outages in signing and propagation infrastructure. In
1501 other words, this delay should ensure that within this period of time
1502 after planned change of the key set, all public-facing secondaries will
1503 already serve new DNSKEY RRSet for sure.
1504 NOTE:
1506 Has influence over ZSK key lifetime.
1507 Default: 1h (1 hour)
1509 rrsig-lifetime
1511 A validity period of newly issued signatures.
1512 NOTE:
1514 The RRSIG's signature inception time is set to 90 minutes in the
1515 past. This time period is not counted to the signature lifetime.
1516 Default: 14d (14 days)
1518 rrsig-refresh
1520 A period how long at least before a signature expiration the signature
1521 will be refreshed, in order to prevent expired RRSIGs on secondary
1522 servers or resolvers' caches.
1523 Default: propagation-delay + zone-max-ttl
1525 rrsig-pre-refresh
1527 A period how long at most before a signature refresh time the signature
1528 might be refreshed, in order to refresh RRSIGs in bigger batches on a
1529 frequently updated zone (avoid re-sign event too often).
1530 Default: 1h (1 hour)
1532 reproducible-signing
1534 For ECDSA algorithms, generate RRSIG signatures deterministically (RFC
1535 6979). Besides better theoretical cryptographic security, this mode
1536 allows significant speed-up of loading signed (by the same method)
1537 zones. However, the zone signing is a bit slower.
1538 Default: off
1540 nsec3
1542 Specifies if NSEC3 will be used instead of NSEC.
1543 Default: off
1545 nsec3-iterations
1547 A number of additional times the hashing is performed.
1548 Default: 0
1550 nsec3-opt-out
1552 If set, NSEC3 records won't be created for insecure delegations. This
1553 speeds up the zone signing and reduces overall zone size.
1554 WARNING:
1556 NSEC3 with the Opt-Out bit set no longer works as a proof of non-ex‐
1557 istence in this zone.
1558 Default: off
1560 nsec3-salt-length
1562 A length of a salt field in octets, which is appended to the original
1563 owner name before hashing.
1564 Default: 8
1566 nsec3-salt-lifetime
1568 A validity period of newly issued salt field.
1569 Zero value means infinity.
1571 Special value -1 triggers re-salt every time when active ZSK changes.
1573 This optimizes the number of big changes to the zone.
1574 Default: 30d (30 days)
1576 signing-threads
1578 When signing zone or update, use this number of threads for parallel
1579 signing.
1580 Those are extra threads independent of Background workers.
1582 NOTE:
1584 Some steps of the DNSSEC signing operation are not parallelized.
1585 Default: 1 (no extra threads)
1587 ksk-submission
1589 A reference to submission section holding parameters of KSK submission
1590 checks.
1591 Default: not set
1593 ds-push
1595 Optional references remote and remotes to authoritative DNS server of
1596 the parent's zone. The remote server must be configured to accept DS
1597 record updates via DDNS. Whenever a CDS record in the local zone is
1598 changed, the corresponding DS record is sent as a dynamic update (DDNS)
1599 to the parent DNS server. All previous DS records are deleted within
1600 the DDNS message. It's possible to manage both child and parent zones
1601 by the same Knot DNS server.
1602 NOTE:
1604 This feature requires cds-cdnskey-publish not to be set to none.
1605 NOTE:
1607 The mentioned change to CDS record usually means that a KSK
1608 roll-over is running and the new key being rolled-in is in "ready"
1609 state already for the period of propagation-delay.
1610 NOTE:
1612 Module Onlinesign doesn't support DS push.
1613 Default: not set
1615 dnskey-sync
1617 A reference to dnskey-sync section holding parameters of DNSKEY syn‐
1618 chronization.
1619 Default: not set
1621 cds-cdnskey-publish
1623 Controls if and how shall the CDS and CDNSKEY be published in the zone.
1624 Possible values:
1626 • none – Never publish any CDS or CDNSKEY records in the zone.
1628 • delete-dnssec – Publish special CDS and CDNSKEY records indicating
1630 turning off DNSSEC.
1631 • rollover – Publish CDS and CDNSKEY records for ready and not yet ac‐
1633 tive KSK (submission phase of KSK rollover).
1634 • always – Always publish one CDS and one CDNSKEY records for the cur‐
1636 rent KSK.
1637 • double-ds – Always publish up to two CDS and two CDNSKEY records for
1639 ready and/or active KSKs.
1640 NOTE:
1642 If the zone keys are managed manually, the CDS and CDNSKEY rrsets
1643 may contain more records depending on the keys available.
1644 WARNING:
1646 The double-ds value does not trigger double-DS roll-over method.
1647 That method is only supported when performed manually, with unset
1648 ksk-submission.
1649 Default: rollover
1651 cds-digest-type
1653 Specify digest type for published CDS records.
1654 Default: sha256
1656 dnskey-management
1658 Specify how the DNSKEY, CDNSKEY, and CDS RRSets at the zone apex are
1659 handled when (re-)signing the zone.
1660 Possible values:
1662 • full – Upon every zone (re-)sign, delete all unknown DNSKEY, CDNSKEY,
1664 and CDS records and keep just those that are related to the zone keys
1665 stored in the KASP database.
1666 • incremental – Keep unknown DNSKEY, CDNSKEY, and CDS records in the
1668 zone, and modify server-managed records incrementally by employing
1669 changes in the KASP database.
1670 NOTE:
1672 Prerequisites for incremental:
1673 • The Offline KSK isn't supported.
1675 • The delete-delay is long enough to cover possible daemon shutdown
1677 (e.g. due to server maintenance).
1678 • Avoided manual deletion of keys with keymgr.
1680 Otherwise there might remain some DNSKEY records in the zone, be‐
1682 longing to deleted keys.
1683 Default: full
1685 offline-ksk
1687 Specifies if Offline KSK feature is enabled.
1688 Default: off
1690 unsafe-operation
1692 Turn off some DNSSEC safety features.
1693 Possible values:
1695 • none – Nothing disabled.
1697 • no-check-keyset – Don't check active keys in present algorithms. This
1699 may lead to violation of RFC 4035#section-2.2.
1700 • no-update-dnskey – Don't maintain/update DNSKEY, CDNSKEY, and CDS
1702 records in the zone apex according to KASP database. Juste leave them
1703 as they are in the zone.
1704 • no-update-nsec – Don't maintain/update NSEC/NSEC3 chain. Leave all
1706 the records as they are in the zone.
1707 • no-update-expired – Don't update expired RRSIGs.
1709 Multiple values may be specified.
1711 WARNING:
1713 This mode is intended for DNSSEC experts who understand the corre‐
1714 sponding consequences.
1715 Default: none
1717
1719 A template is shareable zone settings, which can simplify configuration
1720 by reducing duplicates. A special default template (with the default
1721 identifier) can be used for global zone configuration or as an implicit
1722 configuration if a zone doesn't have another template specified.
1723 template:
1725 - id: STR
1726 global-module: STR/STR ...
1727 # All zone options (excluding 'template' item)
1728 NOTE:
1730 If an item is explicitly specified both in the referenced template
1731 and the zone, the template item value is overridden by the zone item
1732 value.
1733 id
1735 A template identifier.
1736 global-module
1738 An ordered list of references to query modules in the form of mod‐
1739 ule_name or module_name/module_id. These modules apply to all queries.
1740 NOTE:
1742 This option is only available in the default template.
1743 Default: not set
1745
1747 Definition of zones served by the server.
1748 zone:
1750 - domain: DNAME
1751 template: template_id
1752 storage: STR
1753 file: STR
1754 master: remote_id | remotes_id ...
1755 ddns-master: remote_id
1756 notify: remote_id | remotes_id ...
1757 acl: acl_id ...
1758 master-pin-tolerance: TIME
1759 provide-ixfr: BOOL
1760 semantic-checks: BOOL | soft
1761 zonefile-sync: TIME
1762 zonefile-load: none | difference | difference-no-serial | whole
1763 journal-content: none | changes | all
1764 journal-max-usage: SIZE
1765 journal-max-depth: INT
1766 ixfr-benevolent: BOOL
1767 ixfr-by-one: BOOL
1768 ixfr-from-axfr: BOOL
1769 zone-max-size : SIZE
1770 adjust-threads: INT
1771 dnssec-signing: BOOL
1772 dnssec-validation: BOOL
1773 dnssec-policy: policy_id
1774 ds-push: remote_id | remotes_id ...
1775 zonemd-verify: BOOL
1776 zonemd-generate: none | zonemd-sha384 | zonemd-sha512 | remove
1777 serial-policy: increment | unixtime | dateserial
1778 serial-modulo: INT/INT
1779 reverse-generate: DNAME
1780 refresh-min-interval: TIME
1781 refresh-max-interval: TIME
1782 retry-min-interval: TIME
1783 retry-max-interval: TIME
1784 expire-min-interval: TIME
1785 expire-max-interval: TIME
1786 catalog-role: none | interpret | generate | member
1787 catalog-template: template_id ...
1788 catalog-zone: DNAME
1789 catalog-group: STR
1790 module: STR/STR ...
1791 domain
1793 A zone name identifier.
1794 template
1796 A reference to a configuration template.
1797 Default: not set or default (if the template exists)
1799 storage
1801 A data directory for storing zone files. A non-absolute path is rela‐
1802 tive to the knotd startup directory.
1803 Default: ${localstatedir}/lib/knot (configured with --with-stor‐
1805 age=path)
1806 file
1808 A path to the zone file. It is also possible to use the following for‐
1809 matters:
1810 • %c[N] or %c[N-M] – Means the Nth character or a sequence of charac‐
1812 ters beginning from the Nth and ending with the Mth character of the
1813 textual zone name (see %s). The indexes are counted from 0 from the
1814 left. All dots (including the terminal one) are considered. If the
1815 character is not available, the formatter has no effect.
1816 • %l[N] – Means the Nth label of the textual zone name (see %s). The
1818 index is counted from 0 from the right (0 ~ TLD). If the label is
1819 not available, the formatter has no effect.
1820 • %s – Means the current zone name in the textual representation. The
1822 zone name doesn't include the terminating dot (the result for the
1823 root zone is the empty string!).
1824 • %% – Means the % character.
1826 WARNING:
1828 Beware of special characters which are escaped or encoded in the
1829 \DDD form where DDD is corresponding decimal ASCII code.
1830 Default: storage/%s.zone
1832 master
1834 An ordered list of references remote and remotes to zone primary
1835 servers (formerly known as master servers).
1836 Default: not set
1838 ddns-master
1840 A reference to a zone primary master where DDNS messages should be for‐
1841 warded to. If not specified, the first master server is used.
1842 If set to the empty value (""), incoming DDNS messages aren't forwarded
1844 but are applied to the local zone instead, no matter if it is a sec‐
1845 ondary server. This is only allowed in combination with dnssec-signing
1846 enabled.
1847 Default: not set
1849 notify
1851 An ordered list of references remote and remotes to secondary servers
1852 to which notify message is sent if the zone changes.
1853 Default: not set
1855 acl
1857 An ordered list of references to ACL rules which can allow or disallow
1858 zone transfers, updates or incoming notifies.
1859 Default: not set
1861 master-pin-tolerance
1863 If set to a nonzero value on a secondary, always request AXFR/IXFR from
1864 the same primary as the last time, effectively pinning one primary.
1865 Only when another primary is updated and the current one lags behind
1866 for the specified amount of time (defined by this option), change to
1867 the updated primary and force AXFR.
1868 This option is useful when multiple primaries may have different zone
1870 history in their journals, making it unsafe to combine interchanged
1871 IXFR from different primaries.
1872 Default: 0
1874 provide-ixfr
1876 If disabled, the server is forced to respond with AXFR to IXFR queries.
1877 If enabled, IXFR requests are responded normally.
1878 Default: on
1880 semantic-checks
1882 Selects if extra zone semantic checks are used or impacts of the manda‐
1883 tory checks.
1884 There are several mandatory checks which are always enabled and cannot
1886 be turned off. An error in a mandatory check causes the zone not to be
1887 loaded. Most of the mandatory checks can be weakened by setting soft,
1888 which allows the zone to be loaded even if the check fails.
1889 If enabled, extra checks are used. These checks don't prevent the zone
1891 from loading.
1892 The mandatory checks are applied to zone files, zone transfers, and up‐
1894 dates via control interface. The extra checks are applied to zone files
1895 only!
1896 Mandatory checks:
1898 • Missing SOA record at the zone apex (RFC 1034) (*)
1900 • An extra record exists together with a CNAME record except for RRSIG
1902 and NSEC (RFC 1034)
1903 • Multiple CNAME records with the same owner exist (RFC 1034)
1905 • DNAME record having a record under it (RFC 6672)
1907 • Multiple DNAME records with the same owner exist (RFC 6672)
1909 • NS record exists together with a DNAME record (RFC 6672)
1911 • DS record exists at the zone apex (RFC 3658)
1913 (*) The marked check can't be weakened by the soft mode. All other
1915 mandatory checks are subject to the optional soft mode.
1916 Extra checks:
1918 • Missing NS record at the zone apex
1920 • Missing glue A or AAAA record
1922 • Invalid DS or NSEC3PARAM record
1924 • CDS or CDNSKEY inconsistency
1926 • All other DNSSEC checks executed during dnssec-validation
1928 NOTE:
1930 The soft mode allows the refresh event to ignore a CNAME response to
1931 a SOA query (malformed message) and triggers a zone bootstrap in‐
1932 stead.
1933 Default: off
1935 zonefile-sync
1937 The time after which the current zone in memory will be synced with a
1938 zone file on the disk (see file). The server will serve the latest zone
1939 even after a restart using zone journal, but the zone file on the disk
1940 will only be synced after zonefile-sync time has expired (or after man‐
1941 ual zone flush). This is applicable when the zone is updated via IXFR,
1942 DDNS or automatic DNSSEC signing. In order to completely disable auto‐
1943 matic zone file synchronization, set the value to -1. In that case, it
1944 is still possible to force a manual zone flush using the -f option.
1945 NOTE:
1947 If you are serving large zones with frequent updates where the imme‐
1948 diate sync with a zone file is not desirable, increase the value.
1949 Default: 0 (immediate)
1951 zonefile-load
1953 Selects how the zone file contents are applied during zone load.
1954 Possible values:
1956 • none – The zone file is not used at all.
1958 • difference – If the zone contents are already available during server
1960 start or reload, the difference is computed between them and the con‐
1961 tents of the zone file. This difference is then checked for semantic
1962 errors and applied to the current zone contents.
1963 • difference-no-serial – Same as difference, but the SOA serial in the
1965 zone file is ignored, the server takes care of incrementing the se‐
1966 rial automatically.
1967 • whole – Zone contents are loaded from the zone file.
1969 When difference is configured and there are no zone contents yet (cold
1971 start and no zone contents in the journal), it behaves the same way as
1972 whole.
1973 Default: whole
1975 journal-content
1977 Selects how the journal shall be used to store zone and its changes.
1978 Possible values:
1980 • none – The journal is not used at all.
1982 • changes – Zone changes history is stored in journal.
1984 • all – Zone contents and history is stored in journal.
1986 Default: changes
1988 journal-max-usage
1990 Policy how much space in journal DB will the zone's journal occupy.
1991 NOTE:
1993 Journal DB may grow far above the sum of journal-max-usage across
1994 all zones, because of DB free space fragmentation.
1995 Default: 100M (100 MiB)
1997 journal-max-depth
1999 Maximum history length of the journal.
2000 NOTE:
2002 Zone-in-journal changeset isn't counted to the limit.
2003 Minimum: 2
2005 Default: 20
2007 ixfr-benevolent
2009 If enabled, incoming IXFR is applied even when it contains removals of
2010 non-existing or additions of existing records.
2011 Default: off
2013 ixfr-by-one
2015 Within incoming IXFR, process only one changeset at a time, not multi‐
2016 ple together. This preserves the complete history in the journal and
2017 prevents the merging of changesets when multiple changesets are IXFRed
2018 simultaneously. However, this does not prevent the merging (or dele‐
2019 tion) of old changesets in the journal to save space, as described in
2020 journal behaviour.
2021 This option leads to increased server load when processing IXFR, in‐
2023 cluding network traffic.
2024 Default: off
2026 ixfr-from-axfr
2028 If a primary sends AXFR-style-IXFR upon an IXFR request, compute the
2029 difference and process it as an incremental zone update (e.g. by stor‐
2030 ing the changeset in the journal).
2031 Default: off
2033 zone-max-size
2035 Maximum size of the zone. The size is measured as size of the zone
2036 records in wire format without compression. The limit is enforced for
2037 incoming zone transfers and dynamic updates.
2038 For incremental transfers (IXFR), the effective limit for the total
2040 size of the records in the transfer is twice the configured value. How‐
2041 ever the final size of the zone must satisfy the configured value.
2042 Default: unlimited
2044 adjust-threads
2046 Parallelize internal zone adjusting procedures by using specified num‐
2047 ber of threads. This is useful with huge zones with NSEC3. Speedup ob‐
2048 servable at server startup and while processing NSEC3 re-salt.
2049 Default: 1 (no extra threads)
2051 dnssec-signing
2053 If enabled, automatic DNSSEC signing for the zone is turned on.
2054 Default: off
2056 dnssec-validation
2058 If enabled, the zone contents are validated for being correctly signed
2059 (including NSEC/NSEC3 chain) with DNSSEC signatures every time the zone
2060 is loaded or changed (including AXFR/IXFR).
2061 When the validation fails, the zone being loaded or update being ap‐
2063 plied is cancelled with an error, and either none or previous zone
2064 state is published.
2065 List of DNSSEC checks:
2067 • Every zone RRSet is correctly signed by at least one present DNSKEY.
2069 • DNSKEY RRSet is signed by KSK.
2071 • NSEC(3) RR exists for each name (unless opt-out) with correct bitmap.
2073 • Every NSEC(3) RR is linked to the lexicographically next one.
2075 The validation is not affected by dnssec-policy configuration, except
2077 for signing-threads option, which specifies the number of threads for
2078 parallel validation.
2079 NOTE:
2081 Redundant or garbage NSEC3 records are ignored.
2082 This mode is not compatible with dnssec-signing.
2084 Default: not set
2086 dnssec-policy
2088 A reference to DNSSEC signing policy.
2089 NOTE:
2091 A configured policy called "default" won't be used unless explicitly
2092 referenced.
2093 Default: an imaginary policy with all default values
2095 ds-push
2097 Per zone configuration of ds-push. This option overrides possible per
2098 policy option.
2099 Default: not set
2101 zonemd-verify
2103 On each zone load/update, verify that ZONEMD is present in the zone and
2104 valid.
2105 NOTE:
2107 Zone digest calculation may take much time and CPU on large zones.
2108 Default: off
2110 zonemd-generate
2112 On each zone update, calculate ZONEMD and put it into the zone.
2113 Possible values:
2115 • none – No action regarding ZONEMD.
2117 • zonemd-sha384 – Generate ZONEMD using SHA384 algorithm.
2119 • zonemd-sha512 – Generate ZONEMD using SHA512 algorithm.
2121 • remove – Remove any ZONEMD from the zone apex.
2123 Default: none
2125 serial-policy
2127 Specifies how the zone serial is updated after a dynamic update or au‐
2128 tomatic DNSSEC signing. If the serial is changed by the dynamic update,
2129 no change is made.
2130 Possible values:
2132 • increment – The serial is incremented according to serial number
2134 arithmetic.
2135 • unixtime – The serial is set to the current unix time.
2137 • dateserial – The 10-digit serial (YYYYMMDDnn) is incremented, the
2139 first 8 digits match the current iso-date.
2140 NOTE:
2142 If the resulting serial for unixtime or dateserial is lower than or
2143 equal to the current serial (this happens e.g. when migrating from
2144 other policy or frequent updates), the serial is incremented in‐
2145 stead.
2146 To avoid user confusion, use dateserial only if you expect at most
2148 100 updates per day per zone and unixtime only if you expect at most
2149 one update per second per zone.
2150 Generated catalog zones use unixtime only.
2152 Default: increment (unixtime for generated catalog zones)
2154 serial-modulo
2156 Specifies that the zone serials shall be congruent by specified modulo.
2157 The option value must be a string in the format R/M, where R < M <= 256
2158 are positive integers. Whenever the zone serial is incremented, it is
2159 ensured that serial % M == R. This can be useful in the case of multi‐
2160 ple inconsistent primaries, where distinct zone serial sequences pre‐
2161 vent cross-master-IXFR by any secondary.
2162 NOTE:
2164 In order to ensure the congruent policy, this option is only allowed
2165 with DNSSEC signing enabled and zonefile-load to be either differ‐
2166 ence-no-serial or none.
2167 Because the zone serial effectively always increments by M instead
2169 of 1, it is not recommended to use dateserial serial-policy or even
2170 unixtime in case of rapidly updated zone.
2171 Default: 0/1
2173 reverse-generate
2175 This option triggers the automatic generation of reverse PTR records
2176 based on A/AAAA records in the specified zone. The entire generated
2177 zone is automatically stored in the journal.
2178 Current limitations:
2180 • Only one zone to be reversed can be specified.
2182 • Is slow for large zones (even when changing a little).
2184 Default: none
2186 refresh-min-interval
2188 Forced minimum zone refresh interval (in seconds) to avoid flooding
2189 primary server.
2190 Minimum: 2
2192 Default: 2
2194 refresh-max-interval
2196 Forced maximum zone refresh interval (in seconds).
2197 Default: not set
2199 retry-min-interval
2201 Forced minimum zone retry interval (in seconds) to avoid flooding pri‐
2202 mary server.
2203 Minimum: 1
2205 Default: 1
2207 retry-max-interval
2209 Forced maximum zone retry interval (in seconds).
2210 Default: not set
2212 expire-min-interval
2214 Forced minimum zone expire interval (in seconds) to avoid flooding pri‐
2215 mary server.
2216 Minimum: 3
2218 Default: 3
2220 expire-max-interval
2222 Forced maximum zone expire interval (in seconds).
2223 Default: not set
2225 catalog-role
2227 Trigger zone catalog feature. Possible values:
2228 • none – Not a catalog zone.
2230 • interpret – A catalog zone which is loaded from a zone file or XFR,
2232 and member zones shall be configured based on its contents.
2233 • generate – A catalog zone whose contents are generated according to
2235 assigned member zones.
2236 • member – A member zone that is assigned to one generated catalog
2238 zone.
2239 NOTE:
2241 If set to generate, the zonefile-load option has no effect since a
2242 zone file is never loaded.
2243 Default: none
2245 catalog-template
2247 For the catalog member zones, the specified configuration template will
2248 be applied.
2249 Multiple catalog templates may be defined. The first one is used unless
2251 the member zone has the group property defined, matching another cata‐
2252 log template.
2253 NOTE:
2255 This option must be set if and only if catalog-role is interpret.
2256 Nested catalog zones aren't supported. Therefore catalog templates
2258 can't use catalog-template, catalog-role, catalog-zone, and
2259 catalog-group options.
2260 Default: not set
2262 catalog-zone
2264 Assign this member zone to specified generated catalog zone.
2265 NOTE:
2267 This option must be set if and only if catalog-role is member.
2268 The referenced catalog zone must exist and have catalog-role set to
2270 generate.
2271 Default: not set
2273 catalog-group
2275 Assign this member zone to specified catalog group (configuration tem‐
2276 plate).
2277 NOTE:
2279 This option has effect if and only if catalog-role is member.
2280 Default: not set
2282 module
2284 An ordered list of references to query modules in the form of mod‐
2285 ule_name or module_name/module_id. These modules apply only to the cur‐
2286 rent zone queries.
2287 Default: not set
2289
2291 CZ.NIC Labs <https://www.knot-dns.cz>
2292
2294 Copyright 2010–2023, CZ.NIC, z.s.p.o.
22953.3.2 2023-10-20 KNOT.CONF(5)