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 15 fixed sections (module, server, xdp, con‐
43 trol, log, statistics, database, keystore, key, remote, acl, submis‐
44 sion, policy, template, zone). Module sections are prefixed with the
45 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
65 A comment begins with a # character and is ignored during processing.
66 Also each configuration section or sequence block allows a permanent
67 comment using the comment item which is stored in the server beside the
68 configuration.
69
71 Another configuration file or files, matching a pattern, can be in‐
72 cluded at the top level in the current file. If the path is not abso‐
73 lute, then it is considered to be relative to the current file. The
74 pattern can be an arbitrary string meeting POSIX glob requirements,
75 e.g. dir/*.conf. Matching files are processed in sorted order.
76 include: STR
78
80 Dynamic modules loading configuration.
81 NOTE:
83 If configured with non-empty `--with-moduledir=path` parameter, all
84 shared modules in this directory will be automatically loaded.
85 module:
87 - id: STR
88 file: STR
89 id
91 A module identifier in the form of the mod- prefix and module name suf‐
92 fix.
93 file
95 A path to a shared library file with the module implementation.
96 WARNING:
98 If the path is not absolute, the library is searched in the set of
99 system directories. See man dlopen for more details.
100 Default: ${libdir}/knot/modules-${version}/module_name.so (or
102 ${path}/module_name.so if configured with --with-moduledir=path)
103
105 General options related to the server.
106 server:
108 identity: [STR]
109 version: [STR]
110 nsid: [STR|HEXSTR]
111 rundir: STR
112 user: STR[:STR]
113 pidfile: STR
114 udp-workers: INT
115 tcp-workers: INT
116 background-workers: INT
117 async-start: BOOL
118 tcp-idle-timeout: TIME
119 tcp-io-timeout: INT
120 tcp-remote-io-timeout: INT
121 tcp-max-clients: INT
122 tcp-reuseport: BOOL
123 tcp-fastopen: BOOL
124 socket-affinity: BOOL
125 udp-max-payload: SIZE
126 udp-max-payload-ipv4: SIZE
127 udp-max-payload-ipv6: SIZE
128 edns-client-subnet: BOOL
129 answer-rotation: BOOL
130 listen: ADDR[@INT] ...
131 CAUTION:
133 When you change configuration parameters dynamically or via configu‐
134 ration file reload, some parameters in the Server section require
135 restarting the Knot server so that the changes take effect. See be‐
136 low for the details.
137 identity
139 An identity of the server returned in the response to the query for TXT
140 record id.server. or hostname.bind. in the CHAOS class (RFC 4892). Set
141 to an empty value to disable.
142 Default: FQDN hostname
144 version
146 A version of the server software returned in the response to the query
147 for TXT record version.server. or version.bind. in the CHAOS class (RFC
148 4892). Set to an empty value to disable.
149 Default: server version
151 nsid
153 A DNS name server identifier (RFC 5001). Set to an empty value to dis‐
154 able.
155 Default: FQDN hostname at the moment of the daemon start
157 rundir
159 A path for storing run-time data (PID file, unix sockets, etc.).
160 Depending on the usage of this parameter, its change may require
162 restart of the Knot server to take effect.
163 Default: ${localstatedir}/run/knot (configured with --with-rundir=path)
165 user
167 A system user with an optional system group (user:group) under which
168 the server is run after starting and binding to interfaces. Linux capa‐
169 bilities are employed if supported.
170 Change of this parameter requires restart of the Knot server to take
172 effect.
173 Default: root:root
175 pidfile
177 A PID file location.
178 Change of this parameter requires restart of the Knot server to take
180 effect.
181 Default: rundir/knot.pid
183 udp-workers
185 A number of UDP workers (threads) used to process incoming queries over
186 UDP.
187 Change of this parameter requires restart of the Knot server to take
189 effect.
190 Default: equal to the number of online CPUs
192 tcp-workers
194 A number of TCP workers (threads) used to process incoming queries over
195 TCP.
196 Change of this parameter requires restart of the Knot server to take
198 effect.
199 Default: equal to the number of online CPUs, default value is at least
201 10
202 background-workers
204 A number of workers (threads) used to execute background operations
205 (zone loading, zone updates, etc.).
206 Change of this parameter requires restart of the Knot server to take
208 effect.
209 Default: equal to the number of online CPUs, default value is at most
211 10
212 async-start
214 If enabled, server doesn't wait for the zones to be loaded and starts
215 responding immediately with SERVFAIL answers until the zone loads.
216 Default: off
218 tcp-idle-timeout
220 Maximum idle time (in seconds) between requests on an inbound TCP con‐
221 nection. It means if there is no activity on an inbound TCP connection
222 during this limit, the connection is closed by the server.
223 Minimum: 1 s
225 Default: 10 s
227 tcp-io-timeout
229 Maximum time (in milliseconds) to receive or send one DNS message over
230 an inbound TCP connection. It means this limit applies to normal DNS
231 queries and replies, incoming DDNS, and outgoing zone transfers. The
232 timeout is measured since some data is already available for process‐
233 ing. Set to 0 for infinity.
234 Default: 500 ms
236 CAUTION:
238 In order to reduce the risk of Slow Loris attacks, it's recommended
239 setting this limit as low as possible on public servers.
240 tcp-remote-io-timeout
242 Maximum time (in milliseconds) to receive or send one DNS message over
243 an outbound TCP connection which has already been established to a con‐
244 figured remote server. It means this limit applies to incoming zone
245 transfers, sending NOTIFY, DDNS forwarding, and DS check or push. This
246 timeout includes the time needed for a network round-trip and for a
247 query processing by the remote. Set to 0 for infinity.
248 Default: 5000 ms
250 tcp-reuseport
252 If enabled, each TCP worker listens on its own socket and the OS kernel
253 socket load balancing is emloyed using SO_REUSEPORT (or SO_REUSEPORT_LB
254 on FreeBSD). Due to the lack of one shared socket, the server can offer
255 higher response rate processing over TCP. However, in the case of
256 time-consuming requests (e.g. zone transfers of a TLD zone), enabled
257 reuseport may result in delayed or not being responded client requests.
258 So it is advisable to use this option on secondary servers.
259 Change of this parameter requires restart of the Knot server to take
261 effect.
262 Default: off
264 tcp-fastopen
266 If enabled, use TCP Fast Open for outbound TCP communication (client
267 side): incoming zone transfers, sending NOTIFY, and DDNS forwarding.
268 This mode simplifies TCP handshake and can result in better networking
269 performance. TCP Fast Open for inbound TCP communication (server side)
270 isn't affected by this configuration as it's enabled automatically if
271 supported by OS.
272 NOTE:
274 The TCP Fast Open support must also be enabled on the OS level:
275 • Linux/macOS: ensure kernel parameter net.ipv4.tcp_fastopen is 2 or
277 3 for server side, and 1 or 3 for client side.
278 • FreeBSD: ensure kernel parameter net.inet.tcp.fastopen.server_en‐
280 able is 1 for server side, and net.inet.tcp.fastopen.client_enable
281 is 1 for client side.
282 Default: off
284 socket-affinity
286 If enabled and if SO_REUSEPORT is available on Linux, all configured
287 network sockets are bound to UDP and TCP workers in order to increase
288 the networking performance. This mode isn't recommended for setups
289 where the number of network card queues is lower than the number of UDP
290 or TCP workers.
291 Change of this parameter requires restart of the Knot server to take
293 effect.
294 Default: off
296 tcp-max-clients
298 A maximum number of TCP clients connected in parallel, set this below
299 the file descriptor limit to avoid resource exhaustion.
300 NOTE:
302 It is advisable to adjust the maximum number of open files per
303 process in your operating system configuration.
304 Default: one half of the file descriptor limit for the server process
306 udp-max-payload
308 Maximum EDNS0 UDP payload size default for both IPv4 and IPv6.
309 Default: 1232
311 udp-max-payload-ipv4
313 Maximum EDNS0 UDP payload size for IPv4.
314 Default: 1232
316 udp-max-payload-ipv6
318 Maximum EDNS0 UDP payload size for IPv6.
319 Default: 1232
321 edns-client-subnet
323 Enable or disable EDNS Client Subnet support. If enabled, responses to
324 queries containing the EDNS Client Subnet option always contain a valid
325 EDNS Client Subnet option according to RFC 7871.
326 Default: off
328 answer-rotation
330 Enable or disable sorted-rrset rotation in the answer section of normal
331 replies. The rotation shift is simply determined by a query ID.
332 Default: off
334 listen
336 One or more IP addresses where the server listens for incoming queries.
337 Optional port specification (default is 53) can be appended to each ad‐
338 dress using @ separator. Use 0.0.0.0 for all configured IPv4 addresses
339 or :: for all configured IPv6 addresses. Filesystem path can be speci‐
340 fied for listening on local unix SOCK_STREAM socket. Non-local address
341 binding is automatically enabled if supported by the operating system.
342 Change of this parameter requires restart of the Knot server to take
344 effect.
345 Default: not set
347
349 Various options related to XDP listening, especially TCP.
350 xdp:
352 listen: STR[@INT] | ADDR[@INT] ...
353 tcp: BOOL
354 tcp-max-clients: INT
355 tcp-inbuf-max-size: SIZE
356 tcp-idle-close-timeout: TIME
357 tcp-idle-reset-timeout: TIME
358 route-check: BOOL
359 CAUTION:
361 When you change configuration parameters dynamically or via configu‐
362 ration file reload, some parameters in the XDP section require
363 restarting the Knot server so that the changes take effect.
364 listen
366 One or more network device names (e.g. ens786f0) on which the Mode XDP
367 is enabled. Alternatively, an IP address can be used instead of a de‐
368 vice name, but the server will still listen on all addresses belonging
369 to the same interface! Optional port specification (default is 53) can
370 be appended to each device name or address using @ separator.
371 Change of this parameter requires restart of the Knot server to take
373 effect.
374 CAUTION:
376 If XDP workers only process regular DNS traffic over UDP, it is
377 strongly recommended to also listen on the addresses which are in‐
378 tended to offer the DNS service, at least to fulfil the DNS require‐
379 ment for working TCP.
380 Default: not set
382 tcp
384 If enabled, DNS over TCP traffic is also processed with XDP workers.
385 The TCP stack features:
387 • Basic connection handling, sending/receiving data
389 • Close inactive connections
391 • Reset inactive connections which aren't able to close
393 • Reset invalid connections
395 • Ignore invalid resets and ACKs
397 • Receive fragmented data – one DNS message in multiple packets
399 • Limit total size of incoming buffers, reset most inactive connections
401 with buffered data
402 • Send fragmented data – DNS message larger than allowed by MSS
404 • Send MSS option calculated from configured MSS and device MTU
406 • Receive and honor MSS option, limit the size of outgoing packet
408 • Send window size option (set to infinity)
410 Missing features:
412 • Receive and honor window size option, send only such amount of data
414 at once, cache outgoing data
415 • Allow multi-message DNS responses (depends on above)
417 • Resend lost outgoing packets (not ACKed in time), including data
419 Change of this parameter requires restart of the Knot server to take
421 effect.
422 WARNING:
424 This feature is experimental and it may eat your hamster as well as
425 any other hamsters connected to the network.
426 Default: off
428 tcp-max-clients
430 A maximum number of TCP clients connected in parallel.
431 Default: 1000000 (one million)
433 tcp-inbuf-max-size
435 Maximum cumulative size of memory used for buffers of incompletely re‐
436 ceived messages.
437 Minimum: 1 MiB
439 Default: 100 MiB
441 tcp-idle-close-timeout
443 Time in seconds, after which any idle connection is gracefully closed.
444 Minimum: 1 s
446 Default: 10 s
448 tcp-idle-reset-timeout
450 Time in seconds, after which any idle connection is forcibly closed.
451 Minimum: 1 s
453 Default: 20 s
455 route-check
457 If enabled, routing information from the operating system is considered
458 when processing every incoming DNS packet received over the XDP inter‐
459 face:
460 • If the outgoing interface of the corresponding DNS response differs
462 from the incoming one, the packet is processed normally by UDP/TCP
463 workers (XDP isn't used).
464 • If the destination address is blackholed, unreachable, or prohibited,
466 the DNS packet is dropped without any response.
467 • The destination MAC address for the response is taken from the rout‐
469 ing system.
470 If disabled, symmetrical routing is applied. It means that the query
472 source MAC address is used as a response destination MAC address.
473 Change of this parameter requires restart of the Knot server to take
475 effect.
476 NOTE:
478 This mode requires forwarding enabled on the loopback interface
479 (sysctl -w net.ipv4.conf.lo.forwarding=1 and sysctl -w
480 net.ipv6.conf.lo.forwarding=1). If forwarding is disabled, all in‐
481 coming DNS packets are dropped!
482 Default: off
484
486 Configuration of the server control interface.
487 control:
489 listen: STR
490 timeout: TIME
491 listen
493 A UNIX socket path where the server listens for control commands.
494 Default: rundir/knot.sock
496 timeout
498 Maximum time (in seconds) the control socket operations can take. Set
499 to 0 for infinity.
500 Default: 5
502
504 Server can be configured to log to the standard output, standard error
505 output, syslog (or systemd journal if systemd is enabled) or into an
506 arbitrary file.
507 There are 6 logging severity levels:
509 • critical – Non-recoverable error resulting in server shutdown.
511 • error – Recoverable error, action should be taken.
513 • warning – Warning that might require user action.
515 • notice – Server notice or hint.
517 • info – Informational message.
519 • debug – Debug or detailed message.
521 In the case of a missing log section, warning or more serious messages
523 will be logged to both standard error output and syslog. The info and
524 notice messages will be logged to standard output.
525 log:
527 - target: stdout | stderr | syslog | STR
528 server: critical | error | warning | notice | info | debug
529 control: critical | error | warning | notice | info | debug
530 zone: critical | error | warning | notice | info | debug
531 any: critical | error | warning | notice | info | debug
532 target
534 A logging output.
535 Possible values:
537 • stdout – Standard output.
539 • stderr – Standard error output.
541 • syslog – Syslog or systemd journal.
543 • file_name – A specific file.
545 With syslog target, syslog service is used. However, if Knot DNS has
547 been compiled with systemd support and operating system has been booted
548 with systemd, systemd journal is used for logging instead of syslog.
549 server
551 Minimum severity level for messages related to general operation of the
552 server to be logged.
553 Default: not set
555 control
557 Minimum severity level for messages related to server control to be
558 logged.
559 Default: not set
561 zone
563 Minimum severity level for messages related to zones to be logged.
564 Default: not set
566 any
568 Minimum severity level for all message types to be logged.
569 Default: not set
571
573 Periodic server statistics dumping.
574 statistics:
576 timer: TIME
577 file: STR
578 append: BOOL
579 timer
581 A period after which all available statistics metrics will by written
582 to the file.
583 Default: not set
585 file
587 A file path of statistics output in the YAML format.
588 Default: rundir/stats.yaml
590 append
592 If enabled, the output will be appended to the file instead of file re‐
593 placement.
594 Default: off
596
598 Configuration of databases for zone contents, DNSSEC metadata, or event
599 timers.
600 database:
602 storage: STR
603 journal-db: STR
604 journal-db-mode: robust | asynchronous
605 journal-db-max-size: SIZE
606 kasp-db: STR
607 kasp-db-max-size: SIZE
608 timer-db: STR
609 timer-db-max-size: SIZE
610 catalog-db: str
611 catalog-db-max-size: SIZE
612 storage
614 A data directory for storing journal, KASP, and timer databases.
615 Default: ${localstatedir}/lib/knot (configured with --with-stor‐
617 age=path)
618 journal-db
620 An explicit specification of the persistent journal database directory.
621 Non-absolute path (i.e. not starting with /) is relative to storage.
622 Default: storage/journal
624 journal-db-mode
626 Specifies journal LMDB backend configuration, which influences perfor‐
627 mance and durability.
628 Possible values:
630 • robust – The journal database disk sychronization ensures database
632 durability but is generally slower.
633 • asynchronous – The journal database disk synchronization is optimized
635 for better performance at the expense of lower database durability in
636 the case of a crash. This mode is recommended on secondary servers
637 with many zones.
638 Default: robust
640 journal-db-max-size
642 The hard limit for the journal database maximum size. There is no
643 cleanup logic in journal to recover from reaching this limit. Journal
644 simply starts refusing changes across all zones. Decreasing this value
645 has no effect if it is lower than the actual database file size.
646 It is recommended to limit journal-max-usage per-zone instead of
648 journal-db-max-size in most cases. Please keep this value larger than
649 the sum of all zones' journal usage limits. See more details regarding
650 journal behaviour.
651 NOTE:
653 This value also influences server's usage of virtual memory.
654 Default: 20 GiB (512 MiB for 32-bit)
656 kasp-db
658 An explicit specification of the KASP database directory. Non-absolute
659 path (i.e. not starting with /) is relative to storage.
660 Default: storage/keys
662 kasp-db-max-size
664 The hard limit for the KASP database maximum size.
665 NOTE:
667 This value also influences server's usage of virtual memory.
668 Default: 500 MiB
670 timer-db
672 An explicit specification of the persistent timer database directory.
673 Non-absolute path (i.e. not starting with /) is relative to storage.
674 Default: storage/timers
676 timer-db-max-size
678 The hard limit for the timer database maximum size.
679 NOTE:
681 This value also influences server's usage of virtual memory.
682 Default: 100 MiB
684 catalog-db
686 An explicit specification of the zone catalog database directory. Only
687 useful if catalog-zones are enabled. Non-absolute path (i.e. not
688 starting with /) is relative to storage.
689 Default: storage/catalog
691 catalog-db-max-size
693 The hard limit for the catalog database maximum size.
694 NOTE:
696 This value also influences server's usage of virtual memory.
697 Default: 20 GiB (512 MiB for 32-bit)
699
701 DNSSEC keystore configuration.
702 keystore:
704 - id: STR
705 backend: pem | pkcs11
706 config: STR
707 id
709 A keystore identifier.
710 backend
712 A key storage backend type.
713 Possible values:
715 • pem – PEM files.
717 • pkcs11 – PKCS #11 storage.
719 Default: pem
721 config
723 A backend specific configuration. A directory with PEM files (the path
724 can be specified as a relative path to kasp-db) or a configuration
725 string for PKCS #11 storage (<pkcs11-url> <module-path>).
726 NOTE:
728 Example configuration string for PKCS #11:
729 "pkcs11:token=knot;pin-value=1234 /usr/lib64/pkcs11/libsofthsm2.so"
731 Default: kasp-db/keys
733
735 Shared TSIG keys used to authenticate communication with the server.
736 key:
738 - id: DNAME
739 algorithm: hmac-md5 | hmac-sha1 | hmac-sha224 | hmac-sha256 | hmac-sha384 | hmac-sha512
740 secret: BASE64
741 id
743 A key name identifier.
744 NOTE:
746 This value MUST be exactly the same as the name of the TSIG key on
747 the opposite primary/secondary server(s).
748 algorithm
750 A TSIG key algorithm. See TSIG Algorithm Numbers.
751 Possible values:
753 • hmac-md5
755 • hmac-sha1
757 • hmac-sha224
759 • hmac-sha256
761 • hmac-sha384
763 • hmac-sha512
765 Default: not set
767 secret
769 Shared key secret.
770 Default: not set
772
774 Definitions of remote servers for outgoing connections (source of a
775 zone transfer, target for a notification, etc.).
776 remote:
778 - id: STR
779 address: ADDR[@INT] ...
780 via: ADDR[@INT] ...
781 key: key_id
782 block-notify-after-transfer: BOOL
783 id
785 A remote identifier.
786 address
788 An ordered list of destination IP addresses which are used for communi‐
789 cation with the remote server. The addresses are tried in sequence un‐
790 til the remote is reached. Optional destination port (default is 53)
791 can be appended to the address using @ separator.
792 Default: not set
794 NOTE:
796 If the remote is contacted and it refuses to perform requested ac‐
797 tion, no more addresses will be tried for this remote.
798 via
800 An ordered list of source IP addresses. The first address with the same
801 family as the destination address is used as a source address for com‐
802 munication with the remote. This option can help if the server listens
803 on more addresses. Optional source port (default is random) can be ap‐
804 pended to the address using @ separator.
805 Default: not set
807 key
809 A reference to the TSIG key which is used to authenticate the communi‐
810 cation with the remote server.
811 Default: not set
813 block-notify-after-transfer
815 When incoming AXFR/IXFR from this remote (as a primary server), sup‐
816 press sending NOTIFY messages to all configured secondary servers.
817 Default: off
819
821 Access control list rule definitions. The ACLs are used to match incom‐
822 ing connections to allow or deny requested operation (zone transfer re‐
823 quest, DDNS update, etc.).
824 acl:
826 - id: STR
827 address: ADDR[/INT] | ADDR-ADDR ...
828 key: key_id ...
829 remote: remote_id ...
830 action: notify | transfer | update ...
831 deny: BOOL
832 update-type: STR ...
833 update-owner: key | zone | name
834 update-owner-match: sub-or-equal | equal | sub
835 update-owner-name: STR ...
836 id
838 An ACL rule identifier.
839 address
841 An ordered list of IP addresses, network subnets, or network ranges.
842 The query's source address must match one of them. Empty value means
843 that address match is not required.
844 Default: not set
846 key
848 An ordered list of references to TSIG keys. The query must match one of
849 them. Empty value means that transaction authentication is not used.
850 Default: not set
852 remote
854 An ordered list of references to remotes. The query must match one of
855 the remotes. Specifically, one of the remote's addresses and remote's
856 TSIG key if configured must match.
857 NOTE:
859 This option cannot be specified along with the address or key option
860 at one ACL item.
861 Default: not set
863 action
865 An ordered list of allowed (or denied) actions.
866 Possible values:
868 • notify – Allow incoming notify.
870 • transfer – Allow zone transfer.
872 • update – Allow zone updates.
874 Default: not set
876 deny
878 If enabled, instead of allowing, deny the specified action, address,
879 key, or combination if these items. If no action is specified, deny all
880 actions.
881 Default: off
883 update-type
885 A list of allowed types of Resource Records in a zone update. Every
886 record in an update must match one of the specified types.
887 Default: not set
889 update-owner
891 This option restricts possible owners of Resource Records in a zone up‐
892 date by comparing them to either the TSIG key identity, the current
893 zone name, or to a list of domain names given by the update-owner-name
894 option. The comparison method is given by the update-owner-match op‐
895 tion.
896 Possible values:
898 • key — The owner of each updated RR must match the identity of the
900 TSIG key if used.
901 • name — The owner of each updated RR must match at least one name in
903 the update-owner-name list.
904 • zone — The owner of each updated RR must match the current zone name.
906 Default: not set
908 update-owner-match
910 This option defines how the owners of Resource Records in an update are
911 matched to the domain name(s) set by the update-owner option.
912 Possible values:
914 • sub-or-equal — The owner of each Resource Record in an update must
916 either be equal to or be a subdomain of at least one domain set by
917 update-owner.
918 • equal — The owner of each updated RR must be equal to at least one
920 domain set by update-owner.
921 • sub — The owner of each updated RR must be a subdomain of, but MUST
923 NOT be equal to at least one domain set by update-owner.
924 Default: sub-or-equal
926 update-owner-name
928 A list of allowed owners of RRs in a zone update used with update-owner
929 set to name. Every listed owner name which is not FQDN (i.e. it doesn't
930 end in a dot) is considered as if it was appended with the target zone
931 name. Such a relative owner name specification allows better ACL rule
932 reusability across multiple zones.
933 Default: not set
935
937 Parameters of KSK submission checks.
938 submission:
940 - id: STR
941 parent: remote_id ...
942 check-interval: TIME
943 timeout: TIME
944 id
946 A submission identifier.
947 parent
949 A list of references to parent's DNS servers to be checked for presence
950 of corresponding DS records in the case of KSK submission. All of them
951 must have a corresponding DS for the rollover to continue. If none is
952 specified, the rollover must be pushed forward manually.
953 Default: not set
955 TIP:
957 A DNSSEC-validating resolver can be set as a parent.
958 check-interval
960 Interval for periodic checks of DS presence on parent's DNS servers, in
961 the case of the KSK submission.
962 Default: 1 hour
964 timeout
966 After this time period (in seconds) the KSK submission is automatically
967 considered successful, even if all the checks were negative or no par‐
968 ents are configured. Set to 0 for infinity.
969 Default: 0
971
973 DNSSEC policy configuration.
974 policy:
976 - id: STR
977 keystore: keystore_id
978 manual: BOOL
979 single-type-signing: BOOL
980 algorithm: rsasha1 | rsasha1-nsec3-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384 | ed25519 | ed448
981 ksk-size: SIZE
982 zsk-size: SIZE
983 ksk-shared: BOOL
984 dnskey-ttl: TIME
985 zone-max-ttl: TIME
986 ksk-lifetime: TIME
987 zsk-lifetime: TIME
988 delete-delay: TIME
989 propagation-delay: TIME
990 rrsig-lifetime: TIME
991 rrsig-refresh: TIME
992 rrsig-pre-refresh: TIME
993 reproducible-signing: BOOL
994 nsec3: BOOL
995 nsec3-iterations: INT
996 nsec3-opt-out: BOOL
997 nsec3-salt-length: INT
998 nsec3-salt-lifetime: TIME
999 signing-threads: INT
1000 ksk-submission: submission_id
1001 ds-push: remote_id
1002 cds-cdnskey-publish: none | delete-dnssec | rollover | always | double-ds
1003 cds-digest-type: sha256 | sha384
1004 offline-ksk: BOOL
1005 unsafe-operation: none | no-check-keyset | no-update-dnskey | no-update-nsec | no-update-expired ...
1006 id
1008 A policy identifier.
1009 keystore
1011 A reference to a keystore holding private key material for zones.
1012 Default: an imaginary keystore with all default values
1014 NOTE:
1016 A configured keystore called "default" won't be used unless explic‐
1017 itly referenced.
1018 manual
1020 If enabled, automatic key management is not used.
1021 Default: off
1023 single-type-signing
1025 If enabled, Single-Type Signing Scheme is used in the automatic key
1026 management mode.
1027 Default: off (module onlinesign has default on)
1029 algorithm
1031 An algorithm of signing keys and issued signatures. See DNSSEC Algo‐
1032 rithm Numbers.
1033 Possible values:
1035 • rsasha1
1037 • rsasha1-nsec3-sha1
1039 • rsasha256
1041 • rsasha512
1043 • ecdsap256sha256
1045 • ecdsap384sha384
1047 • ed25519
1049 • ed448
1051 NOTE:
1053 Ed25519 algorithm is only available if compiled with GnuTLS 3.6.0+.
1054 Ed448 algorithm is only available if compiled with GnuTLS 3.6.12+
1056 and Nettle 3.6+.
1057 Default: ecdsap256sha256
1059 ksk-size
1061 A length of newly generated KSK or CSK keys.
1062 Default: 2048 (rsa*), 256 (ecdsap256), 384 (ecdsap384), 256 (ed25519),
1064 456 (ed448)
1065 zsk-size
1067 A length of newly generated ZSK keys.
1068 Default: see default for ksk-size
1070 ksk-shared
1072 If enabled, all zones with this policy assigned will share one or more
1073 KSKs. More KSKs can be shared during a KSK rollover.
1074 WARNING:
1076 As the shared KSK set is bound to the policy id, renaming the policy
1077 breaks this connection and new shared KSK set is initiated when a
1078 new KSK is needed.
1079 Default: off
1081 dnskey-ttl
1083 A TTL value for DNSKEY records added into zone apex.
1084 NOTE:
1086 Has infuence over ZSK key lifetime.
1087 WARNING:
1089 Ensure all DNSKEYs with updated TTL are propagated before any subse‐
1090 quent DNSKEY rollover starts.
1091 Default: zone SOA TTL
1093 zone-max-ttl
1095 Declare (override) maximal TTL value among all the records in zone.
1096 NOTE:
1098 It's generally recommended to override the maximal TTL computation
1099 by setting this explicitly whenever possible. It's required for
1100 DNSSEC Offline KSK and really reasonable when records are generated
1101 dynamically (e.g. by a module).
1102 Default: computed after zone is loaded
1104 ksk-lifetime
1106 A period between KSK activation and the next rollover initiation.
1107 NOTE:
1109 KSK key lifetime is also infuenced by propagation-delay, dnskey-ttl,
1110 and KSK submission delay.
1111 Zero (aka infinity) value causes no KSK rollover as a result.
1113 This applies for CSK lifetime if single-type-signing is enabled.
1115 Default: 0
1117 zsk-lifetime
1119 A period between ZSK activation and the next rollover initiation.
1120 NOTE:
1122 More exactly, this period is measured since a ZSK is activated, and
1123 after this, a new ZSK is generated to replace it within following
1124 roll-over.
1125 ZSK key lifetime is also infuenced by propagation-delay and
1127 dnskey-ttl
1128 Zero (aka infinity) value causes no ZSK rollover as a result.
1130 Default: 30 days
1132 delete-delay
1134 Once a key (KSK or ZSK) is rolled-over and removed from the zone, keep
1135 it in the KASP database for at least this period before deleting it
1136 completely. This might be useful in some troubleshooting cases when
1137 resurrection is needed.
1138 Default: 0
1140 propagation-delay
1142 An extra delay added for each key rollover step. This value should be
1143 high enough to cover propagation of data from the primary server to all
1144 secondary servers.
1145 NOTE:
1147 Has infuence over ZSK key lifetime.
1148 Default: 1 hour
1150 rrsig-lifetime
1152 A validity period of newly issued signatures.
1153 NOTE:
1155 The RRSIG's signature inception time is set to 90 minutes in the
1156 past. This time period is not counted to the signature lifetime.
1157 Default: 14 days
1159 rrsig-refresh
1161 A period how long at least before a signature expiration the signature
1162 will be refreshed, in order to prevent expired RRSIGs on secondary
1163 servers or resolvers' caches.
1164 Default: 7 days
1166 rrsig-pre-refresh
1168 A period how long at most before a signature refresh time the signature
1169 might be refreshed, in order to refresh RRSIGs in bigger batches on a
1170 frequently updated zone (avoid re-sign event too often).
1171 Default: 1 hour
1173 reproducible-signing
1175 For ECDSA algorithms, generate RRSIG signatures deterministically (RFC
1176 6979). Besides better theoretical cryptographic security, this mode
1177 allows significant speed-up of loading signed (by the same method)
1178 zones. However, the zone signing is a bit slower.
1179 Default: off
1181 nsec3
1183 Specifies if NSEC3 will be used instead of NSEC.
1184 Default: off
1186 nsec3-iterations
1188 A number of additional times the hashing is performed.
1189 Default: 10
1191 nsec3-opt-out
1193 If set, NSEC3 records won't be created for insecure delegations. This
1194 speeds up the zone signing and reduces overall zone size.
1195 WARNING:
1197 NSEC3 with the Opt-Out bit set no longer works as a proof of non-ex‐
1198 istence in this zone.
1199 Default: off
1201 nsec3-salt-length
1203 A length of a salt field in octets, which is appended to the original
1204 owner name before hashing.
1205 Default: 8
1207 nsec3-salt-lifetime
1209 A validity period of newly issued salt field.
1210 Zero value means infinity.
1212 Default: 30 days
1214 signing-threads
1216 When signing zone or update, use this number of threads for parallel
1217 signing.
1218 Those are extra threads independent of Background workers.
1220 NOTE:
1222 Some steps of the DNSSEC signing operation are not parallelized.
1223 Default: 1 (no extra threads)
1225 ksk-submission
1227 A reference to submission section holding parameters of KSK submission
1228 checks.
1229 Default: not set
1231 ds-push
1233 An optional reference to authoritative DNS server of the parent's zone.
1234 The remote server must be configured to accept DS record updates via
1235 DDNS. Whenever a CDS record in the local zone is changed, the corre‐
1236 sponding DS record is sent as a dynamic update (DDNS) to the parent DNS
1237 server. All previous DS records are deleted within the DDNS message.
1238 It's possible to manage both child and parent zones by the same Knot
1239 DNS server.
1240 NOTE:
1242 This feature requires cds-cdnskey-publish not to be set to none.
1243 NOTE:
1245 Module Onlinesign doesn't support DS push.
1246 Default: not set
1248 cds-cdnskey-publish
1250 Controls if and how shall the CDS and CDNSKEY be published in the zone.
1251 Possible values:
1253 • none – Never publish any CDS or CDNSKEY records in the zone.
1255 • delete-dnssec – Publish special CDS and CDNSKEY records indicating
1257 turning off DNSSEC.
1258 • rollover – Publish CDS and CDNSKEY records for ready and not yet ac‐
1260 tive KSK (submission phase of KSK rollover).
1261 • always – Always publish one CDS and one CDNSKEY records for the cur‐
1263 rent KSK.
1264 • double-ds – Always publish up to two CDS and two CDNSKEY records for
1266 ready and/or active KSKs.
1267 NOTE:
1269 If the zone keys are managed manually, the CDS and CDNSKEY rrsets
1270 may contain more records depending on the keys available.
1271 Default: rollover
1273 cds-digest-type
1275 Specify digest type for published CDS records.
1276 Default: sha256
1278 offline-ksk
1280 Specifies if Offline KSK feature is enabled.
1281 Default: off
1283 unsafe-operation
1285 Turn off some DNSSEC safety features.
1286 Possible values:
1288 • none – Nothing disabled.
1290 • no-check-keyset – Don't check active keys in present algorithms. This
1292 may lead to violation of RFC 4035#section-2.2.
1293 • no-update-dnskey – Don't maintain/update DNSKEY, CDNSKEY, and CDS
1295 records in the zone apex according to KASP database. Juste leave them
1296 as they are in the zone.
1297 • no-update-nsec – Don't maintain/update NSEC/NSEC3 chain. Leave all
1299 the records as they are in the zone.
1300 • no-update-expired – Don't update expired RRSIGs.
1302 Multiple values may be specified.
1304 WARNING:
1306 This mode is intended for DNSSEC experts who understand the corre‐
1307 sponding consequences.
1308 Default: none
1310
1312 A template is shareable zone settings, which can simplify configuration
1313 by reducing duplicates. A special default template (with the default
1314 identifier) can be used for global zone configuration or as an implicit
1315 configuration if a zone doesn't have another template specified.
1316 template:
1318 - id: STR
1319 global-module: STR/STR ...
1320 # All zone options (excluding 'template' item)
1321 id
1323 A template identifier.
1324 global-module
1326 An ordered list of references to query modules in the form of mod‐
1327 ule_name or module_name/module_id. These modules apply to all queries.
1328 NOTE:
1330 This option is only available in the default template.
1331 Default: not set
1333
1335 Definition of zones served by the server.
1336 zone:
1338 - domain: DNAME
1339 template: template_id
1340 storage: STR
1341 file: STR
1342 master: remote_id ...
1343 ddns-master: remote_id
1344 notify: remote_id ...
1345 acl: acl_id ...
1346 semantic-checks: BOOL
1347 zonefile-sync: TIME
1348 zonefile-load: none | difference | difference-no-serial | whole
1349 journal-content: none | changes | all
1350 journal-max-usage: SIZE
1351 journal-max-depth: INT
1352 zone-max-size : SIZE
1353 adjust-threads: INT
1354 dnssec-signing: BOOL
1355 dnssec-validation: BOOL
1356 dnssec-policy: policy_id
1357 zonemd-verify: BOOL
1358 zonemd-generate: none | zonemd-sha384 | zonemd-sha512
1359 serial-policy: increment | unixtime | dateserial
1360 refresh-min-interval: TIME
1361 refresh-max-interval: TIME
1362 catalog-role: none | interpret | generate | member
1363 catalog-template: template_id ...
1364 catalog-zone: DNAME
1365 catalog-group: STR
1366 module: STR/STR ...
1367 domain
1369 A zone name identifier.
1370 template
1372 A reference to a configuration template.
1373 Default: not set or default (if the template exists)
1375 storage
1377 A data directory for storing zone files.
1378 Default: ${localstatedir}/lib/knot (configured with --with-stor‐
1380 age=path)
1381 file
1383 A path to the zone file. Non-absolute path (i.e. not starting with /)
1384 is relative to storage. It is also possible to use the following for‐
1385 matters:
1386 • %c[N] or %c[N-M] – Means the Nth character or a sequence of charac‐
1388 ters beginning from the Nth and ending with the Mth character of the
1389 textual zone name (see %s). The indexes are counted from 0 from the
1390 left. All dots (including the terminal one) are considered. If the
1391 character is not available, the formatter has no effect.
1392 • %l[N] – Means the Nth label of the textual zone name (see %s). The
1394 index is counted from 0 from the right (0 ~ TLD). If the label is
1395 not available, the formatter has no effect.
1396 • %s – Means the current zone name in the textual representation. The
1398 zone name doesn't include the terminating dot (the result for the
1399 root zone is the empty string!).
1400 • %% – Means the % character.
1402 WARNING:
1404 Beware of special characters which are escaped or encoded in the
1405 \DDD form where DDD is corresponding decimal ASCII code.
1406 Default: storage/%s.zone
1408 master
1410 An ordered list of references to zone primary servers (formerly known
1411 as master servers).
1412 Default: not set
1414 ddns-master
1416 A reference to zone primary master. If not specified, the first master
1417 server is used.
1418 Default: not set
1420 notify
1422 An ordered list of references to remotes to which notify message is
1423 sent if the zone changes.
1424 Default: not set
1426 acl
1428 An ordered list of references to ACL rules which can allow or disallow
1429 zone transfers, updates or incoming notifies.
1430 Default: not set
1432 semantic-checks
1434 If enabled, extra zone semantic checks are turned on.
1435 Several checks are enabled by default and cannot be turned off. An er‐
1437 ror in mandatory checks causes zone not to be loaded. An error in extra
1438 checks is logged only.
1439 Mandatory checks:
1441 • SOA record missing in the zone (RFC 1034)
1443 • An extra record together with CNAME record except for RRSIG and DS (‐
1445 RFC 1034)
1446 • Multiple CNAME record with the same owner
1448 • DNAME record having a record under it (RFC 2672)
1450 Extra checks:
1452 • Missing NS record at the zone apex
1454 • Missing glue A or AAAA record
1456 • Invalid DNSKEY, DS, or NSEC3PARAM record
1458 • CDS or CDNSKEY inconsistency
1460 • Missing, invalid, or unverifiable RRSIG record
1462 • Invalid NSEC(3) record
1464 • Broken or non-cyclic NSEC(3) chain
1466 Default: off
1468 zonefile-sync
1470 The time after which the current zone in memory will be synced with a
1471 zone file on the disk (see file). The server will serve the latest zone
1472 even after a restart using zone journal, but the zone file on the disk
1473 will only be synced after zonefile-sync time has expired (or after man‐
1474 ual zone flush). This is applicable when the zone is updated via IXFR,
1475 DDNS or automatic DNSSEC signing. In order to completely disable auto‐
1476 matic zone file synchronization, set the value to -1. In that case, it
1477 is still possible to force a manual zone flush using the -f option.
1478 NOTE:
1480 If you are serving large zones with frequent updates where the imme‐
1481 diate sync with a zone file is not desirable, increase the value.
1482 Default: 0 (immediate)
1484 zonefile-load
1486 Selects how the zone file contents are applied during zone load.
1487 Possible values:
1489 • none – The zone file is not used at all.
1491 • difference – If the zone contents are already available during server
1493 start or reload, the difference is computed between them and the con‐
1494 tents of the zone file. This difference is then checked for semantic
1495 errors and applied to the current zone contents.
1496 • difference-no-serial – Same as difference, but the SOA serial in the
1498 zone file is ignored, the server takes care of incrementing the se‐
1499 rial automatically.
1500 • whole – Zone contents are loaded from the zone file.
1502 When difference is configured and there are no zone contents yet (cold
1504 start and no zone contents in the journal), it behaves the same way as
1505 whole.
1506 Default: whole
1508 journal-content
1510 Selects how the journal shall be used to store zone and its changes.
1511 Possible values:
1513 • none – The journal is not used at all.
1515 • changes – Zone changes history is stored in journal.
1517 • all – Zone contents and history is stored in journal.
1519 Default: changes
1521 journal-max-usage
1523 Policy how much space in journal DB will the zone's journal occupy.
1524 NOTE:
1526 Journal DB may grow far above the sum of journal-max-usage across
1527 all zones, because of DB free space fragmentation.
1528 Default: 100 MiB
1530 journal-max-depth
1532 Maximum history length of the journal.
1533 NOTE:
1535 Zone-in-journal changeset isn't counted to the limit.
1536 Minimum: 2
1538 Default: 2^64
1540 zone-max-size
1542 Maximum size of the zone. The size is measured as size of the zone
1543 records in wire format without compression. The limit is enforced for
1544 incoming zone transfers and dynamic updates.
1545 For incremental transfers (IXFR), the effective limit for the total
1547 size of the records in the transfer is twice the configured value. How‐
1548 ever the final size of the zone must satisfy the configured value.
1549 Default: 2^64
1551 adjust-threads
1553 Parallelize internal zone adjusting procedures. This is useful with
1554 huge zones with NSEC3. Speedup observable at server startup and while
1555 processing NSEC3 re-salt.
1556 Default: 1
1558 dnssec-signing
1560 If enabled, automatic DNSSEC signing for the zone is turned on.
1561 Default: off
1563 dnssec-validation
1565 If enabled, the zone contents are validated for being correctly signed
1566 (including NSEC/NSEC3 chain) with DNSSEC signatures every time the zone
1567 is loaded or changed (including AXFR/IXFR).
1568 When the validation fails, the zone being loaded or update being ap‐
1570 plied is cancelled with an error, and either none or previous zone
1571 state is published.
1572 List of DNSSEC checks:
1574 • Every zone RRSet is correctly signed by at least one present DNSKEY.
1576 • DNSKEY RRSet is signed by KSK.
1578 • NSEC(3) RR exists for each name (unless opt-out) with correct bitmap.
1580 • Every NSEC(3) RR is linked to the lexicographically next one.
1582 The validation is not affected by dnssec-policy configuration, except
1584 for signing-threads option, which specifies the number of threads for
1585 parallel validation.
1586 NOTE:
1588 Redundant or garbage NSEC3 records are ignored.
1589 This mode is not compatible with dnssec-signing.
1591 dnssec-policy
1593 A reference to DNSSEC signing policy.
1594 Default: an imaginary policy with all default values
1596 NOTE:
1598 A configured policy called "default" won't be used unless explicitly
1599 referenced.
1600 zonemd-verify
1602 On each zone load/update, verify that ZONEMD is present in the zone and
1603 valid.
1604 NOTE:
1606 Zone digest calculation may take much time and CPU on large zones.
1607 Default: off
1609 zonemd-generate
1611 On each zone update, calculate ZONEMD and put it into the zone.
1612 Possible values:
1614 • none – No action regarding ZONEMD.
1616 • zonemd-sha384 – Generate ZONEMD using SHA384 algorithm.
1618 • zonemd-sha512 – Generate ZONEMD using SHA512 algorithm.
1620 Default: none
1622 serial-policy
1624 Specifies how the zone serial is updated after a dynamic update or au‐
1625 tomatic DNSSEC signing. If the serial is changed by the dynamic update,
1626 no change is made.
1627 Possible values:
1629 • increment – The serial is incremented according to serial number
1631 arithmetic.
1632 • unixtime – The serial is set to the current unix time.
1634 • dateserial – The 10-digit serial (YYYYMMDDnn) is incremented, the
1636 first 8 digits match the current iso-date.
1637 NOTE:
1639 If the resulting serial for unixtime or dateserial is lower or equal
1640 than the current serial (this happens e.g. when migrating from other
1641 policy or frequent updates), the serial is incremented instead.
1642 To avoid user confusion, use dateserial only if you expect at most
1644 100 updates per day per zone and unixtime only if you expect at most
1645 one update per second per zone.
1646 Default: increment
1648 refresh-min-interval
1650 Forced minimum zone refresh interval to avoid flooding primary server.
1651 Default: 2
1653 refresh-max-interval
1655 Forced maximum zone refresh interval.
1656 Default: not set
1658 catalog-role
1660 Trigger zone catalog feature. Possible values:
1661 • none – Not a catalog zone.
1663 • interpret – A catalog zone which is loaded from a zone file or XFR,
1665 and member zones shall be configured based on its contents.
1666 • generate – A catalog zone whose contents are generated according to
1668 assigned member zones.
1669 • member – A member zone that is assigned to one generated catalog
1671 zone.
1672 Default: none
1674 catalog-template
1676 For the catalog member zones, the specified configuration template will
1677 be applied.
1678 Multiple catalog templates may be defined. The first one is used unless
1680 the member zone has the group property defined, matching another cata‐
1681 log template.
1682 NOTE:
1684 This option must be set if and only if catalog-role is interpret.
1685 Default: not set
1687 catalog-zone
1689 Assign this member zone to specified generated catalog zone.
1690 NOTE:
1692 This option must be set if and only if catalog-role is member.
1693 The referenced catalog zone must exist and have catalog-role set to
1695 generate.
1696 Default: not set
1698 catalog-group
1700 Assign this member zone to specified catalog group (configuration tem‐
1701 plate).
1702 NOTE:
1704 This option has effect if and only if catalog-role is member.
1705 Default: not set
1707 module
1709 An ordered list of references to query modules in the form of mod‐
1710 ule_name or module_name/module_id. These modules apply only to the cur‐
1711 rent zone queries.
1712 Default: not set
1714
1716 CZ.NIC Labs <https://www.knot-dns.cz>
1717
1719 Copyright 2010–2021, CZ.NIC, z.s.p.o.
17203.1.4 2021-11-04 KNOT.CONF(5)