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 14 fixed sections (module, server, control,
43 log, statistics, database, keystore, key, remote, acl, submission, pol‐
44 icy, template, zone). Module sections are prefixed with the mod- pre‐
45 fix (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 socket-affinity: BOOL
124 udp-max-payload: SIZE
125 udp-max-payload-ipv4: SIZE
126 udp-max-payload-ipv6: SIZE
127 edns-client-subnet: BOOL
128 answer-rotation: BOOL
129 listen: ADDR[@INT] ...
130 listen-xdp: STR[@INT] | 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
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 socket-affinity
266 If enabled and if SO_REUSEPORT is available on Linux, all configured
267 network sockets are bound to UDP and TCP workers in order to increase
268 the networking performance. This mode isn't recommended for setups
269 where the number of network card queues is lower than the number of UDP
270 or TCP workers.
271 Change of this parameter requires restart of the Knot server to take
273 effect.
274 Default: off
276 tcp-max-clients
278 A maximum number of TCP clients connected in parallel, set this below
279 the file descriptor limit to avoid resource exhaustion.
280 NOTE:
282 It is advisable to adjust the maximum number of open files per
283 process in your operating system configuration.
284 Default: one half of the file descriptor limit for the server process
286 udp-max-payload
288 Maximum EDNS0 UDP payload size default for both IPv4 and IPv6.
289 Default: 1232
291 udp-max-payload-ipv4
293 Maximum EDNS0 UDP payload size for IPv4.
294 Default: 1232
296 udp-max-payload-ipv6
298 Maximum EDNS0 UDP payload size for IPv6.
299 Default: 1232
301 edns-client-subnet
303 Enable or disable EDNS Client Subnet support. If enabled, responses to
304 queries containing the EDNS Client Subnet option always contain a valid
305 EDNS Client Subnet option according to RFC 7871.
306 Default: off
308 answer-rotation
310 Enable or disable sorted-rrset rotation in the answer section of normal
311 replies. The rotation shift is simply determined by a query ID.
312 Default: off
314 listen
316 One or more IP addresses where the server listens for incoming queries.
317 Optional port specification (default is 53) can be appended to each ad‐
318 dress using @ separator. Use 0.0.0.0 for all configured IPv4 addresses
319 or :: for all configured IPv6 addresses. Filesystem path can be speci‐
320 fied for listening on local unix SOCK_STREAM socket. Non-local address
321 binding is automatically enabled if supported by the operating system.
322 Change of this parameter requires restart of the Knot server to take
324 effect.
325 Default: not set
327 listen-xdp
329 One or more network device names (e.g. ens786f0) on which the Mode XDP
330 is enabled. Alternatively, an IP address can be used instead of a de‐
331 vice name, but the server will still listen on all addresses belonging
332 to the same interface! Optional port specification (default is 53) can
333 be appended to each device name or address using @ separator.
334 Change of this parameter requires restart of the Knot server to take
336 effect.
337 Default: not set
339 CAUTION:
341 Since XDP workers only process regular DNS traffic over UDP, it is
342 strongly recommended to also listen on the addresses which are in‐
343 tended to offer the DNS service, at least to fulfil the DNS require‐
344 ment for working TCP.
345
347 Configuration of the server control interface.
348 control:
350 listen: STR
351 timeout: TIME
352 listen
354 A UNIX socket path where the server listens for control commands.
355 Default: rundir/knot.sock
357 timeout
359 Maximum time (in seconds) the control socket operations can take. Set
360 to 0 for infinity.
361 Default: 5
363
365 Server can be configured to log to the standard output, standard error
366 output, syslog (or systemd journal if systemd is enabled) or into an
367 arbitrary file.
368 There are 6 logging severity levels:
370 • critical – Non-recoverable error resulting in server shutdown.
372 • error – Recoverable error, action should be taken.
374 • warning – Warning that might require user action.
376 • notice – Server notice or hint.
378 • info – Informational message.
380 • debug – Debug or detailed message.
382 In the case of a missing log section, warning or more serious messages
384 will be logged to both standard error output and syslog. The info and
385 notice messages will be logged to standard output.
386 log:
388 - target: stdout | stderr | syslog | STR
389 server: critical | error | warning | notice | info | debug
390 control: critical | error | warning | notice | info | debug
391 zone: critical | error | warning | notice | info | debug
392 any: critical | error | warning | notice | info | debug
393 target
395 A logging output.
396 Possible values:
398 • stdout – Standard output.
400 • stderr – Standard error output.
402 • syslog – Syslog or systemd journal.
404 • file_name – A specific file.
406 With syslog target, syslog service is used. However, if Knot DNS has
408 been compiled with systemd support and operating system has been booted
409 with systemd, systemd journal is used for logging instead of syslog.
410 server
412 Minimum severity level for messages related to general operation of the
413 server to be logged.
414 Default: not set
416 control
418 Minimum severity level for messages related to server control to be
419 logged.
420 Default: not set
422 zone
424 Minimum severity level for messages related to zones to be logged.
425 Default: not set
427 any
429 Minimum severity level for all message types to be logged.
430 Default: not set
432
434 Periodic server statistics dumping.
435 statistics:
437 timer: TIME
438 file: STR
439 append: BOOL
440 timer
442 A period after which all available statistics metrics will by written
443 to the file.
444 Default: not set
446 file
448 A file path of statistics output in the YAML format.
449 Default: rundir/stats.yaml
451 append
453 If enabled, the output will be appended to the file instead of file re‐
454 placement.
455 Default: off
457
459 Configuration of databases for zone contents, DNSSEC metadata, or event
460 timers.
461 database:
463 storage: STR
464 journal-db: STR
465 journal-db-mode: robust | asynchronous
466 journal-db-max-size: SIZE
467 kasp-db: STR
468 kasp-db-max-size: SIZE
469 timer-db: STR
470 timer-db-max-size: SIZE
471 catalog-db: str
472 catalog-db-max-size: SIZE
473 storage
475 A data directory for storing journal, KASP, and timer databases.
476 Default: ${localstatedir}/lib/knot (configured with --with-stor‐
478 age=path)
479 journal-db
481 An explicit specification of the persistent journal database directory.
482 Non-absolute path (i.e. not starting with /) is relative to storage.
483 Default: storage/journal
485 journal-db-mode
487 Specifies journal LMDB backend configuration, which influences perfor‐
488 mance and durability.
489 Possible values:
491 • robust – The journal database disk sychronization ensures database
493 durability but is generally slower.
494 • asynchronous – The journal database disk synchronization is optimized
496 for better performance at the expense of lower database durability in
497 the case of a crash. This mode is recommended on secondary servers
498 with many zones.
499 Default: robust
501 journal-db-max-size
503 The hard limit for the journal database maximum size. There is no
504 cleanup logic in journal to recover from reaching this limit. Journal
505 simply starts refusing changes across all zones. Decreasing this value
506 has no effect if it is lower than the actual database file size.
507 It is recommended to limit journal-max-usage per-zone instead of
509 journal-db-max-size in most cases. Please keep this value larger than
510 the sum of all zones' journal usage limits. See more details regarding
511 journal behaviour.
512 NOTE:
514 This value also influences server's usage of virtual memory.
515 Default: 20 GiB (512 MiB for 32-bit)
517 kasp-db
519 An explicit specification of the KASP database directory. Non-absolute
520 path (i.e. not starting with /) is relative to storage.
521 Default: storage/keys
523 kasp-db-max-size
525 The hard limit for the KASP database maximum size.
526 NOTE:
528 This value also influences server's usage of virtual memory.
529 Default: 500 MiB
531 timer-db
533 An explicit specification of the persistent timer database directory.
534 Non-absolute path (i.e. not starting with /) is relative to storage.
535 Default: storage/timers
537 timer-db-max-size
539 The hard limit for the timer database maximum size.
540 NOTE:
542 This value also influences server's usage of virtual memory.
543 Default: 100 MiB
545 catalog-db
547 An explicit specification of the zone catalog database directory. Only
548 useful if catalog-zones are enabled. Non-absolute path (i.e. not
549 starting with /) is relative to storage.
550 Default: storage/catalog
552 catalog-db-max-size
554 The hard limit for the catalog database maximum size.
555 NOTE:
557 This value also influences server's usage of virtual memory.
558 Default: 20 GiB (512 MiB for 32-bit)
560
562 DNSSEC keystore configuration.
563 keystore:
565 - id: STR
566 backend: pem | pkcs11
567 config: STR
568 id
570 A keystore identifier.
571 backend
573 A key storage backend type.
574 Possible values:
576 • pem – PEM files.
578 • pkcs11 – PKCS #11 storage.
580 Default: pem
582 config
584 A backend specific configuration. A directory with PEM files (the path
585 can be specified as a relative path to kasp-db) or a configuration
586 string for PKCS #11 storage (<pkcs11-url> <module-path>).
587 NOTE:
589 Example configuration string for PKCS #11:
590 "pkcs11:token=knot;pin-value=1234 /usr/lib64/pkcs11/libsofthsm2.so"
592 Default: kasp-db/keys
594
596 Shared TSIG keys used to authenticate communication with the server.
597 key:
599 - id: DNAME
600 algorithm: hmac-md5 | hmac-sha1 | hmac-sha224 | hmac-sha256 | hmac-sha384 | hmac-sha512
601 secret: BASE64
602 id
604 A key name identifier.
605 NOTE:
607 This value MUST be exactly the same as the name of the TSIG key on
608 the opposite primary/secondary server(s).
609 algorithm
611 A TSIG key algorithm. See TSIG Algorithm Numbers.
612 Possible values:
614 • hmac-md5
616 • hmac-sha1
618 • hmac-sha224
620 • hmac-sha256
622 • hmac-sha384
624 • hmac-sha512
626 Default: not set
628 secret
630 Shared key secret.
631 Default: not set
633
635 Definitions of remote servers for outgoing connections (source of a
636 zone transfer, target for a notification, etc.).
637 remote:
639 - id: STR
640 address: ADDR[@INT] ...
641 via: ADDR[@INT] ...
642 key: key_id
643 block-notify-after-transfer: BOOL
644 id
646 A remote identifier.
647 address
649 An ordered list of destination IP addresses which are used for communi‐
650 cation with the remote server. The addresses are tried in sequence un‐
651 til the remote is reached. Optional destination port (default is 53)
652 can be appended to the address using @ separator.
653 Default: not set
655 NOTE:
657 If the remote is contacted and it refuses to perform requested ac‐
658 tion, no more addresses will be tried for this remote.
659 via
661 An ordered list of source IP addresses. The first address with the same
662 family as the destination address is used. Optional source port (de‐
663 fault is random) can be appended to the address using @ separator.
664 Default: not set
666 key
668 A reference to the TSIG key which is used to authenticate the communi‐
669 cation with the remote server.
670 Default: not set
672 block-notify-after-transfer
674 When incoming AXFR/IXFR from this remote (as a primary server), sup‐
675 press sending NOTIFY messages to all configured secondary servers.
676 Default: off
678
680 Access control list rule definitions. The ACLs are used to match incom‐
681 ing connections to allow or deny requested operation (zone transfer re‐
682 quest, DDNS update, etc.).
683 acl:
685 - id: STR
686 address: ADDR[/INT] | ADDR-ADDR ...
687 key: key_id ...
688 remote: remote_id ...
689 action: notify | transfer | update ...
690 deny: BOOL
691 update-type: STR ...
692 update-owner: key | zone | name
693 update-owner-match: sub-or-equal | equal | sub
694 update-owner-name: STR ...
695 id
697 An ACL rule identifier.
698 address
700 An ordered list of IP addresses, network subnets, or network ranges.
701 The query's source address must match one of them. Empty value means
702 that address match is not required.
703 Default: not set
705 key
707 An ordered list of references to TSIG keys. The query must match one of
708 them. Empty value means that transaction authentication is not used.
709 Default: not set
711 remote
713 An ordered list of references to remotes. The query must match one of
714 the remotes. Specifically, one of the remote's addresses and remote's
715 TSIG key if configured must match.
716 NOTE:
718 This option cannot be specified along with the address or key option
719 at one ACL item.
720 Default: not set
722 action
724 An ordered list of allowed (or denied) actions.
725 Possible values:
727 • notify – Allow incoming notify.
729 • transfer – Allow zone transfer.
731 • update – Allow zone updates.
733 Default: not set
735 deny
737 If enabled, instead of allowing, deny the specified action, address,
738 key, or combination if these items. If no action is specified, deny all
739 actions.
740 Default: off
742 update-type
744 A list of allowed types of Resource Records in a zone update. Every
745 record in an update must match one of the specified types.
746 Default: not set
748 update-owner
750 This option restricts possible owners of Resource Records in a zone up‐
751 date by comparing them to either the TSIG key identity, the current
752 zone name, or to a list of domain names given by the update-owner-name
753 option. The comparison method is given by the update-owner-match op‐
754 tion.
755 Possible values:
757 • key — The owner of each updated RR must match the identity of the
759 TSIG key if used.
760 • name — The owner of each updated RR must match at least one name in
762 the update-owner-name list.
763 • zone — The owner of each updated RR must match the current zone name.
765 Default: not set
767 update-owner-match
769 This option defines how the owners of Resource Records in an update are
770 matched to the domain name(s) set by the update-owner option.
771 Possible values:
773 • sub-or-equal — The owner of each Resource Record in an update must
775 either be equal to or be a subdomain of at least one domain set by
776 update-owner.
777 • equal — The owner of each updated RR must be equal to at least one
779 domain set by update-owner.
780 • sub — The owner of each updated RR must be a subdomain of, but MUST
782 NOT be equal to at least one domain set by update-owner.
783 Default: sub-or-equal
785 update-owner-name
787 A list of allowed owners of RRs in a zone update used with update-owner
788 set to name. Every listed owner name which is not FQDN (i.e. it doesn't
789 end in a dot) is considered as if it was appended with the target zone
790 name. Such a relative owner name specification allows better ACL rule
791 reusability across multiple zones.
792 Default: not set
794
796 Parameters of KSK submission checks.
797 submission:
799 - id: STR
800 parent: remote_id ...
801 check-interval: TIME
802 timeout: TIME
803 id
805 A submission identifier.
806 parent
808 A list of references to parent's DNS servers to be checked for presence
809 of corresponding DS records in the case of KSK submission. All of them
810 must have a corresponding DS for the rollover to continue. If none is
811 specified, the rollover must be pushed forward manually.
812 Default: not set
814 TIP:
816 A DNSSEC-validating resolver can be set as a parent.
817 check-interval
819 Interval for periodic checks of DS presence on parent's DNS servers, in
820 the case of the KSK submission.
821 Default: 1 hour
823 timeout
825 After this time period (in seconds) the KSK submission is automatically
826 considered successful, even if all the checks were negative or no par‐
827 ents are configured. Set to 0 for infinity.
828 Default: 0
830
832 DNSSEC policy configuration.
833 policy:
835 - id: STR
836 keystore: STR
837 manual: BOOL
838 single-type-signing: BOOL
839 algorithm: rsasha1 | rsasha1-nsec3-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384 | ed25519 | ed448
840 ksk-size: SIZE
841 zsk-size: SIZE
842 ksk-shared: BOOL
843 dnskey-ttl: TIME
844 zone-max-ttl: TIME
845 ksk-lifetime: TIME
846 zsk-lifetime: TIME
847 propagation-delay: TIME
848 rrsig-lifetime: TIME
849 rrsig-refresh: TIME
850 rrsig-pre-refresh: TIME
851 reproducible-signing: BOOL
852 nsec3: BOOL
853 nsec3-iterations: INT
854 nsec3-opt-out: BOOL
855 nsec3-salt-length: INT
856 nsec3-salt-lifetime: TIME
857 signing-threads: INT
858 ksk-submission: submission_id
859 ds-push: remote_id
860 cds-cdnskey-publish: none | delete-dnssec | rollover | always | double-ds
861 offline-ksk: BOOL
862 id
864 A policy identifier.
865 keystore
867 A reference to a keystore holding private key material for zones.
868 Default: an imaginary keystore with all default values
870 NOTE:
872 A configured keystore called "default" won't be used unless explic‐
873 itly referenced.
874 manual
876 If enabled, automatic key management is not used.
877 Default: off
879 single-type-signing
881 If enabled, Single-Type Signing Scheme is used in the automatic key
882 management mode.
883 Default: off (module onlinesign has default on)
885 algorithm
887 An algorithm of signing keys and issued signatures. See DNSSEC Algo‐
888 rithm Numbers.
889 Possible values:
891 • rsasha1
893 • rsasha1-nsec3-sha1
895 • rsasha256
897 • rsasha512
899 • ecdsap256sha256
901 • ecdsap384sha384
903 • ed25519
905 • ed448
907 NOTE:
909 Ed25519 algorithm is only available if compiled with GnuTLS 3.6.0+.
910 Ed448 algorithm is only available if compiled with GnuTLS 3.6.12+
912 and Nettle 3.6+.
913 Default: ecdsap256sha256
915 ksk-size
917 A length of newly generated KSK or CSK keys.
918 Default: 2048 (rsa*), 256 (ecdsap256), 384 (ecdsap384), 256 (ed25519),
920 456 (ed448)
921 zsk-size
923 A length of newly generated ZSK keys.
924 Default: see default for ksk-size
926 ksk-shared
928 If enabled, all zones with this policy assigned will share one KSK.
929 Default: off
931 dnskey-ttl
933 A TTL value for DNSKEY records added into zone apex.
934 NOTE:
936 Has infuence over ZSK key lifetime.
937 WARNING:
939 Ensure all DNSKEYs with updated TTL are propagated before any subse‐
940 quent DNSKEY rollover starts.
941 Default: zone SOA TTL
943 zone-max-ttl
945 Declare (override) maximal TTL value among all the records in zone.
946 NOTE:
948 It's generally recommended to override the maximal TTL computation
949 by setting this explicitly whenever possible. It's required for
950 DNSSEC Offline KSK and really reasonable when records are generated
951 dynamically (e.g. by a module).
952 Default: computed after zone is loaded
954 ksk-lifetime
956 A period between KSK activation and the next rollover initiation.
957 NOTE:
959 KSK key lifetime is also infuenced by propagation-delay, dnskey-ttl,
960 and KSK submission delay.
961 Zero (aka infinity) value causes no KSK rollover as a result.
963 This applies for CSK lifetime if single-type-signing is enabled.
965 Default: 0
967 zsk-lifetime
969 A period between ZSK activation and the next rollover initiation.
970 NOTE:
972 More exactly, this period is measured since a ZSK is activated, and
973 after this, a new ZSK is generated to replace it within following
974 roll-over.
975 ZSK key lifetime is also infuenced by propagation-delay and
977 dnskey-ttl
978 Zero (aka infinity) value causes no ZSK rollover as a result.
980 Default: 30 days
982 propagation-delay
984 An extra delay added for each key rollover step. This value should be
985 high enough to cover propagation of data from the primary server to all
986 secondary servers.
987 NOTE:
989 Has infuence over ZSK key lifetime.
990 Default: 1 hour
992 rrsig-lifetime
994 A validity period of newly issued signatures.
995 NOTE:
997 The RRSIG's signature inception time is set to 90 minutes in the
998 past. This time period is not counted to the signature lifetime.
999 Default: 14 days
1001 rrsig-refresh
1003 A period how long at least before a signature expiration the signature
1004 will be refreshed, in order to prevent expired RRSIGs on secondary
1005 servers or resolvers' caches.
1006 Default: 7 days
1008 rrsig-pre-refresh
1010 A period how long at most before a signature refresh time the signature
1011 might be refreshed, in order to refresh RRSIGs in bigger batches on a
1012 frequently updated zone (avoid re-sign event too often).
1013 Default: 1 hour
1015 reproducible-signing
1017 For ECDSA algorithms, generate RRSIG signatures deterministically (RFC
1018 6979). Besides better theoretical cryptographic security, this mode
1019 allows significant speed-up of loading signed (by the same method)
1020 zones. However, the zone signing is a bit slower.
1021 Default: off
1023 nsec3
1025 Specifies if NSEC3 will be used instead of NSEC.
1026 Default: off
1028 nsec3-iterations
1030 A number of additional times the hashing is performed.
1031 Default: 10
1033 nsec3-opt-out
1035 If set, NSEC3 records won't be created for insecure delegations. This
1036 speeds up the zone signing and reduces overall zone size.
1037 WARNING:
1039 NSEC3 with the Opt-Out bit set no longer works as a proof of non-ex‐
1040 istence in this zone.
1041 Default: off
1043 nsec3-salt-length
1045 A length of a salt field in octets, which is appended to the original
1046 owner name before hashing.
1047 Default: 8
1049 nsec3-salt-lifetime
1051 A validity period of newly issued salt field.
1052 Zero value means infinity.
1054 Default: 30 days
1056 signing-threads
1058 When signing zone or update, use this number of threads for parallel
1059 signing.
1060 Those are extra threads independent of Background workers.
1062 NOTE:
1064 Some steps of the DNSSEC signing operation are not parallelized.
1065 Default: 1 (no extra threads)
1067 ksk-submission
1069 A reference to submission section holding parameters of KSK submission
1070 checks.
1071 Default: not set
1073 ds-push
1075 An optional reference to authoritative DNS server of the parent's zone.
1076 The remote server must be configured to accept DS record updates via
1077 DDNS. Whenever a CDS record in the local zone is changed, the corre‐
1078 sponding DS record is sent as a dynamic update (DDNS) to the parent DNS
1079 server. All previous DS records are deleted within the DDNS message.
1080 It's possible to manage both child and parent zones by the same Knot
1081 DNS server.
1082 NOTE:
1084 This feature requires cds-cdnskey-publish not to be set to none.
1085 NOTE:
1087 Module Onlinesign doesn't support DS push.
1088 Default: not set
1090 cds-cdnskey-publish
1092 Controls if and how shall the CDS and CDNSKEY be published in the zone.
1093 Possible values:
1095 • none – Never publish any CDS or CDNSKEY records in the zone.
1097 • delete-dnssec – Publish special CDS and CDNSKEY records indicating
1099 turning off DNSSEC.
1100 • rollover – Publish CDS and CDNSKEY records for ready and not yet ac‐
1102 tive KSK (submission phase of KSK rollover).
1103 • always – Always publish one CDS and one CDNSKEY records for the cur‐
1105 rent KSK.
1106 • double-ds – Always publish up to two CDS and two CDNSKEY records for
1108 ready and/or active KSKs.
1109 NOTE:
1111 If the zone keys are managed manually, the CDS and CDNSKEY rrsets
1112 may contain more records depending on the keys available.
1113 Default: rollover
1115 offline-ksk
1117 Specifies if Offline KSK feature is enabled.
1118 Default: off
1120
1122 A template is shareable zone settings, which can simplify configuration
1123 by reducing duplicates. A special default template (with the default
1124 identifier) can be used for global zone configuration or as an implicit
1125 configuration if a zone doesn't have another template specified.
1126 template:
1128 - id: STR
1129 global-module: STR/STR ...
1130 # All zone options (excluding 'template' item)
1131 id
1133 A template identifier.
1134 global-module
1136 An ordered list of references to query modules in the form of mod‐
1137 ule_name or module_name/module_id. These modules apply to all queries.
1138 NOTE:
1140 This option is only available in the default template.
1141 Default: not set
1143
1145 Definition of zones served by the server.
1146 zone:
1148 - domain: DNAME
1149 template: template_id
1150 storage: STR
1151 file: STR
1152 master: remote_id ...
1153 ddns-master: remote_id
1154 notify: remote_id ...
1155 acl: acl_id ...
1156 semantic-checks: BOOL
1157 zonefile-sync: TIME
1158 zonefile-load: none | difference | difference-no-serial | whole
1159 journal-content: none | changes | all
1160 journal-max-usage: SIZE
1161 journal-max-depth: INT
1162 zone-max-size : SIZE
1163 adjust-threads: INT
1164 dnssec-signing: BOOL
1165 dnssec-validation: BOOL
1166 dnssec-policy: STR
1167 serial-policy: increment | unixtime | dateserial
1168 refresh-min-interval: TIME
1169 refresh-max-interval: TIME
1170 catalog-role: none | interpret
1171 catalog-template: template_id
1172 module: STR/STR ...
1173 domain
1175 A zone name identifier.
1176 template
1178 A reference to a configuration template.
1179 Default: not set or default (if the template exists)
1181 storage
1183 A data directory for storing zone files.
1184 Default: ${localstatedir}/lib/knot (configured with --with-stor‐
1186 age=path)
1187 file
1189 A path to the zone file. Non-absolute path (i.e. not starting with /)
1190 is relative to storage. It is also possible to use the following for‐
1191 matters:
1192 • %c[N] or %c[N-M] – Means the Nth character or a sequence of charac‐
1194 ters beginning from the Nth and ending with the Mth character of the
1195 textual zone name (see %s). The indexes are counted from 0 from the
1196 left. All dots (including the terminal one) are considered. If the
1197 character is not available, the formatter has no effect.
1198 • %l[N] – Means the Nth label of the textual zone name (see %s). The
1200 index is counted from 0 from the right (0 ~ TLD). If the label is
1201 not available, the formatter has no effect.
1202 • %s – Means the current zone name in the textual representation. The
1204 zone name doesn't include the terminating dot (the result for the
1205 root zone is the empty string!).
1206 • %% – Means the % character.
1208 WARNING:
1210 Beware of special characters which are escaped or encoded in the
1211 \DDD form where DDD is corresponding decimal ASCII code.
1212 Default: storage/%s.zone
1214 master
1216 An ordered list of references to zone primary servers (formerly known
1217 as master servers).
1218 Default: not set
1220 ddns-master
1222 A reference to zone primary master. If not specified, the first master
1223 server is used.
1224 Default: not set
1226 notify
1228 An ordered list of references to remotes to which notify message is
1229 sent if the zone changes.
1230 Default: not set
1232 acl
1234 An ordered list of references to ACL rules which can allow or disallow
1235 zone transfers, updates or incoming notifies.
1236 Default: not set
1238 semantic-checks
1240 If enabled, extra zone semantic checks are turned on.
1241 Several checks are enabled by default and cannot be turned off. An er‐
1243 ror in mandatory checks causes zone not to be loaded. An error in extra
1244 checks is logged only.
1245 Mandatory checks:
1247 • SOA record missing in the zone (RFC 1034)
1249 • An extra record together with CNAME record except for RRSIG and DS (‐
1251 RFC 1034)
1252 • Multiple CNAME record with the same owner
1254 • DNAME record having a record under it (RFC 2672)
1256 Extra checks:
1258 • Missing NS record at the zone apex
1260 • Missing glue A or AAAA record
1262 • Invalid DNSKEY, DS, or NSEC3PARAM record
1264 • CDS or CDNSKEY inconsistency
1266 • Missing, invalid, or unverifiable RRSIG record
1268 • Invalid NSEC(3) record
1270 • Broken or non-cyclic NSEC(3) chain
1272 Default: off
1274 zonefile-sync
1276 The time after which the current zone in memory will be synced with a
1277 zone file on the disk (see file). The server will serve the latest zone
1278 even after a restart using zone journal, but the zone file on the disk
1279 will only be synced after zonefile-sync time has expired (or after man‐
1280 ual zone flush). This is applicable when the zone is updated via IXFR,
1281 DDNS or automatic DNSSEC signing. In order to completely disable auto‐
1282 matic zone file synchronization, set the value to -1. In that case, it
1283 is still possible to force a manual zone flush using the -f option.
1284 NOTE:
1286 If you are serving large zones with frequent updates where the imme‐
1287 diate sync with a zone file is not desirable, increase the value.
1288 Default: 0 (immediate)
1290 zonefile-load
1292 Selects how the zone file contents are applied during zone load.
1293 Possible values:
1295 • none – The zone file is not used at all.
1297 • difference – If the zone contents are already available during server
1299 start or reload, the difference is computed between them and the con‐
1300 tents of the zone file. This difference is then checked for semantic
1301 errors and applied to the current zone contents.
1302 • difference-no-serial – Same as difference, but the SOA serial in the
1304 zone file is ignored, the server takes care of incrementing the se‐
1305 rial automatically.
1306 • whole – Zone contents are loaded from the zone file.
1308 When difference is configured and there are no zone contents yet (cold
1310 start of Knot and no zone contents in journal), it behaves the same way
1311 like whole.
1312 Default: whole
1314 journal-content
1316 Selects how the journal shall be used to store zone and its changes.
1317 Possible values:
1319 • none – The journal is not used at all.
1321 • changes – Zone changes history is stored in journal.
1323 • all – Zone contents and history is stored in journal.
1325 Default: changes
1327 journal-max-usage
1329 Policy how much space in journal DB will the zone's journal occupy.
1330 NOTE:
1332 Journal DB may grow far above the sum of journal-max-usage across
1333 all zones, because of DB free space fragmentation.
1334 Default: 100 MiB
1336 journal-max-depth
1338 Maximum history length of journal.
1339 Minimum: 2
1341 Default: 2^64
1343 zone-max-size
1345 Maximum size of the zone. The size is measured as size of the zone
1346 records in wire format without compression. The limit is enforced for
1347 incoming zone transfers and dynamic updates.
1348 For incremental transfers (IXFR), the effective limit for the total
1350 size of the records in the transfer is twice the configured value. How‐
1351 ever the final size of the zone must satisfy the configured value.
1352 Default: 2^64
1354 adjust-threads
1356 Parallelize internal zone adjusting procedures. This is useful with
1357 huge zones with NSEC3. Speedup observable at server startup and while
1358 processing NSEC3 re-salt.
1359 Default: 1
1361 dnssec-signing
1363 If enabled, automatic DNSSEC signing for the zone is turned on.
1364 Default: off
1366 dnssec-validation
1368 If enabled, the zone contents are validated for being correctly signed
1369 (including NSEC/NSEC3 chain) with DNSSEC signatures every time the zone
1370 is loaded or changed (including AXFR/IXFR).
1371 When the validation fails, the zone being loaded or update being ap‐
1373 plied is cancelled with an error, and either none or previous zone
1374 state is published.
1375 List of DNSSEC checks:
1377 • Every zone RRSet is correctly signed by at least one present DNSKEY.
1379 • DNSKEY RRSet is signed by KSK.
1381 • NSEC(3) RR exists for each name (unless opt-out) with correct bitmap.
1383 • Every NSEC(3) RR is linked to the lexicographically next one.
1385 The validation is not affected by dnssec-policy configuration, except
1387 for signing-threads option, which specifies the number of threads for
1388 parallel validation.
1389 NOTE:
1391 Redundant or garbage NSEC3 records are ignored.
1392 This mode is not compatible with dnssec-signing.
1394 dnssec-policy
1396 A reference to DNSSEC signing policy.
1397 Default: an imaginary policy with all default values
1399 NOTE:
1401 A configured policy called "default" won't be used unless explicitly
1402 referenced.
1403 serial-policy
1405 Specifies how the zone serial is updated after a dynamic update or au‐
1406 tomatic DNSSEC signing. If the serial is changed by the dynamic update,
1407 no change is made.
1408 Possible values:
1410 • increment – The serial is incremented according to serial number
1412 arithmetic.
1413 • unixtime – The serial is set to the current unix time.
1415 • dateserial – The 10-digit serial (YYYYMMDDnn) is incremented, the
1417 first 8 digits match the current iso-date.
1418 NOTE:
1420 If the resulting serial for unixtime or dateserial is lower or equal
1421 than the current serial (this happens e.g. when migrating from other
1422 policy or frequent updates), the serial is incremented instead.
1423 To avoid user confusion, use dateserial only if you expect at most
1425 100 updates per day per zone and unixtime only if you expect at most
1426 one update per second per zone.
1427 Default: increment
1429 refresh-min-interval
1431 Forced minimum zone refresh interval to avoid flooding primary server.
1432 Default: 2
1434 refresh-max-interval
1436 Forced maximum zone refresh interval.
1437 Default: not set
1439 catalog-role
1441 Trigger zone catalog feature. Possible values:
1442 • none – Not a catalog zone.
1444 • interpret – A catalog zone which is loaded from a zone file or XFR,
1446 and member zones shall be configured based on its contents.
1447 Default: none
1449 catalog-template
1451 For the catalog-member zones, the specified configuration template will
1452 be applied.
1453 NOTE:
1455 This option must be set if and only if catalog-role is interpret.
1456 Default: not set
1458 module
1460 An ordered list of references to query modules in the form of mod‐
1461 ule_name or module_name/module_id. These modules apply only to the cur‐
1462 rent zone queries.
1463 Default: not set
1465
1467 CZ.NIC Labs <https://www.knot-dns.cz>
1468
1470 Copyright 2010–2021, CZ.NIC, z.s.p.o.
14713.0.6 2021-05-12 KNOT.CONF(5)