1KNOT.CONF(5)                       Knot DNS                       KNOT.CONF(5)
2
3
4

NAME

6       knot.conf - Knot DNS configuration file
7

DESCRIPTION

9       Configuration files for Knot DNS use simplified YAML format. Simplified
10       means that not all of the features are supported.
11
12       For the description of configuration items, we have to declare a  mean‐
13       ing of the following symbols:
14
15       · INT – Integer
16
17       · STR – Textual string
18
19       · HEXSTR – Hexadecimal string (with 0x prefix)
20
21       · BOOL – Boolean value (on/off or true/false)
22
23       · TIME  –  Number  of seconds, an integer with possible time multiplier
24         suffix (s ~ 1, m ~ 60, h ~ 3600 or d ~ 24 * 3600)
25
26       · 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
29       · BASE64 – Base64 encoded string
30
31       · ADDR – IPv4 or IPv6 address
32
33       · DNAME – Domain name
34
35       · ... – Multi-valued item, order of the values is preserved
36
37       · [ ] – Optional value
38
39       · | – Choice
40
41       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
47       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
52       A multi-valued item can be specified either as a YAML sequence:
53
54          address: [10.0.0.1, 10.0.0.2]
55
56       or as more single-valued items each on an extra line:
57
58          address: 10.0.0.1
59          address: 10.0.0.2
60
61       If an item value contains spaces or other  special  characters,  it  is
62       necessary to enclose such a value within double quotes " ".
63

COMMENTS

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

INCLUDES

71       Another configuration  file  or  files,  matching  a  pattern,  can  be
72       included 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
77          include: STR
78

MODULE SECTION

80       Dynamic modules loading configuration.
81
82       NOTE:
83          If configured with non-empty `--with-moduledir=path` parameter,  all
84          shared modules in this directory will be automatically loaded.
85
86          module:
87            - id: STR
88              file: STR
89
90   id
91       A module identifier in the form of the mod- prefix and module name suf‐
92       fix.
93
94   file
95       A path to a shared library file with the module implementation.
96
97       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
101       Default:      ${libdir}/knot/modules-${version}/module_name.so      (or
102       ${path}/module_name.so if configured with --with-moduledir=path)
103

SERVER SECTION

105       General options related to the server.
106
107          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
132       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
136          below for the details.
137
138   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
143       Default: FQDN hostname
144
145   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
150       Default: server version
151
152   nsid
153       A  DNS name server identifier (RFC 5001). Set to an empty value to dis‐
154       able.
155
156       Default: FQDN hostname
157
158   rundir
159       A path for storing run-time data (PID file, unix sockets, etc.).
160
161       Depending on the usage  of  this  parameter,  its  change  may  require
162       restart of the Knot server to take effect.
163
164       Default: ${localstatedir}/run/knot (configured with --with-rundir=path)
165
166   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
171       Change  of  this  parameter requires restart of the Knot server to take
172       effect.
173
174       Default: root:root
175
176   pidfile
177       A PID file location.
178
179       Change of this parameter requires restart of the Knot  server  to  take
180       effect.
181
182       Default: rundir/knot.pid
183
184   udp-workers
185       A number of UDP workers (threads) used to process incoming queries over
186       UDP.
187
188       Change of this parameter requires restart of the Knot  server  to  take
189       effect.
190
191       Default: equal to the number of online CPUs
192
193   tcp-workers
194       A number of TCP workers (threads) used to process incoming queries over
195       TCP.
196
197       Change of this parameter requires restart of the Knot  server  to  take
198       effect.
199
200       Default:  equal to the number of online CPUs, default value is at least
201       10
202
203   background-workers
204       A number of workers (threads) used  to  execute  background  operations
205       (zone loading, zone updates, etc.).
206
207       Change  of  this  parameter requires restart of the Knot server to take
208       effect.
209
210       Default: equal to the number of online CPUs, default value is  at  most
211       10
212
213   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
217       Default: off
218
219   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
224       Minimum: 1 s
225
226       Default: 10 s
227
228   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
235       Default: 500 ms
236
237       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
241   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
249       Default: 5000 ms
250
251   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
260       Change of this parameter requires restart of the Knot  server  to  take
261       effect.
262
263       Default: off
264
265   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
272       Change  of  this  parameter requires restart of the Knot server to take
273       effect.
274
275       Default: off
276
277   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
281       NOTE:
282          It  is  advisable  to  adjust  the  maximum number of open files per
283          process in your operating system configuration.
284
285       Default: one half of the file descriptor limit for the server process
286
287   udp-max-payload
288       Maximum EDNS0 UDP payload size default for both IPv4 and IPv6.
289
290       Default: 1232
291
292   udp-max-payload-ipv4
293       Maximum EDNS0 UDP payload size for IPv4.
294
295       Default: 1232
296
297   udp-max-payload-ipv6
298       Maximum EDNS0 UDP payload size for IPv6.
299
300       Default: 1232
301
302   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
307       Default: off
308
309   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
313       Default: off
314
315   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
318       address  using  @  separator.  Use  0.0.0.0  for  all  configured  IPv4
319       addresses or :: for all configured IPv6  addresses.  Non-local  address
320       binding is automatically enabled if supported by the operating system.
321
322       Change  of  this  parameter requires restart of the Knot server to take
323       effect.
324
325       Default: not set
326
327   listen-xdp
328       One or more network device names (e.g. ens786f0) on which the Mode  XDP
329       is  enabled.  Alternatively,  an  IP  address  can be used instead of a
330       device name, but the server will still listen on all addresses  belong‐
331       ing to the same interface!  Optional port specification (default is 53)
332       can be appended to each device name or address using @ separator.
333
334       Change of this parameter requires restart of the Knot  server  to  take
335       effect.
336
337       Default: not set
338
339       CAUTION:
340          Since  XDP  workers only process regular DNS traffic over UDP, it is
341          strongly recommended to also  listen  on  the  addresses  which  are
342          intended  to  offer  the  DNS  service,  at  least to fulfil the DNS
343          requirement for working TCP.
344

CONTROL SECTION

346       Configuration of the server control interface.
347
348          control:
349              listen: STR
350              timeout: TIME
351
352   listen
353       A UNIX socket path where the server listens for control commands.
354
355       Default: rundir/knot.sock
356
357   timeout
358       Maximum time (in seconds) the control socket operations can take.   Set
359       to 0 for infinity.
360
361       Default: 5
362

LOGGING SECTION

364       Server  can be configured to log to the standard output, standard error
365       output, syslog (or systemd journal if systemd is enabled)  or  into  an
366       arbitrary file.
367
368       There are 6 logging severity levels:
369
370       · critical – Non-recoverable error resulting in server shutdown.
371
372       · error – Recoverable error, action should be taken.
373
374       · warning – Warning that might require user action.
375
376       · notice – Server notice or hint.
377
378       · info – Informational message.
379
380       · debug – Debug or detailed message.
381
382       In  the case of a missing log section, warning or more serious messages
383       will be logged to both standard error output and syslog. The  info  and
384       notice messages will be logged to standard output.
385
386          log:
387            - target: stdout | stderr | syslog | STR
388              server: critical | error | warning | notice | info | debug
389              control: critical | error | warning | notice | info | debug
390              zone: critical | error | warning | notice | info | debug
391              any: critical | error | warning | notice | info | debug
392
393   target
394       A logging output.
395
396       Possible values:
397
398       · stdout – Standard output.
399
400       · stderr – Standard error output.
401
402       · syslog – Syslog or systemd journal.
403
404       · file_name – A specific file.
405
406       With  syslog  target,  syslog service is used. However, if Knot DNS has
407       been compiled with systemd support and operating system has been booted
408       with systemd, systemd journal is used for logging instead of syslog.
409
410   server
411       Minimum severity level for messages related to general operation of the
412       server to be logged.
413
414       Default: not set
415
416   control
417       Minimum severity level for messages related to  server  control  to  be
418       logged.
419
420       Default: not set
421
422   zone
423       Minimum severity level for messages related to zones to be logged.
424
425       Default: not set
426
427   any
428       Minimum severity level for all message types to be logged.
429
430       Default: not set
431

STATISTICS SECTION

433       Periodic server statistics dumping.
434
435          statistics:
436              timer: TIME
437              file: STR
438              append: BOOL
439
440   timer
441       A  period  after which all available statistics metrics will by written
442       to the file.
443
444       Default: not set
445
446   file
447       A file path of statistics output in the YAML format.
448
449       Default: rundir/stats.yaml
450
451   append
452       If enabled, the output will be appended to the  file  instead  of  file
453       replacement.
454
455       Default: off
456

DATABASE SECTION

458       Configuration of databases for zone contents, DNSSEC metadata, or event
459       timers.
460
461          database:
462              storage: STR
463              journal-db: STR
464              journal-db-mode: robust | asynchronous
465              journal-db-max-size: SIZE
466              kasp-db: STR
467              kasp-db-max-size: SIZE
468              timer-db: STR
469              timer-db-max-size: SIZE
470              catalog-db: str
471              catalog-db-max-size: SIZE
472
473   storage
474       A data directory for storing journal, KASP, and timer databases.
475
476       Default:  ${localstatedir}/lib/knot   (configured   with   --with-stor‐
477       age=path)
478
479   journal-db
480       An explicit specification of the persistent journal database directory.
481       Non-absolute path (i.e. not starting with /) is relative to storage.
482
483       Default: storage/journal
484
485   journal-db-mode
486       Specifies journal LMDB backend configuration, which influences  perfor‐
487       mance and durability.
488
489       Possible values:
490
491       · robust  –  The  journal database disk sychronization ensures database
492         durability but is generally slower.
493
494       · asynchronous – The journal database disk synchronization is optimized
495         for better performance at the expense of lower database durability in
496         the case of a crash. This mode is recommended  on  secondary  servers
497         with many zones.
498
499       Default: robust
500
501   journal-db-max-size
502       The  hard  limit  for  the  journal  database maximum size. There is no
503       cleanup logic in journal to recover from reaching this  limit.  Journal
504       simply  starts refusing changes across all zones. Decreasing this value
505       has no effect if it is lower than the actual database file size.
506
507       It is  recommended  to  limit  journal-max-usage  per-zone  instead  of
508       journal-db-max-size  in  most cases. Please keep this value larger than
509       the sum of all zones' journal usage limits. See more details  regarding
510       journal behaviour.
511
512       NOTE:
513          This value also influences server's usage of virtual memory.
514
515       Default: 20 GiB (512 MiB for 32-bit)
516
517   kasp-db
518       An explicit specification of the KASP database directory.  Non-absolute
519       path (i.e. not starting with /) is relative to storage.
520
521       Default: storage/keys
522
523   kasp-db-max-size
524       The hard limit for the KASP database maximum size.
525
526       NOTE:
527          This value also influences server's usage of virtual memory.
528
529       Default: 500 MiB
530
531   timer-db
532       An explicit specification of the persistent timer  database  directory.
533       Non-absolute path (i.e. not starting with /) is relative to storage.
534
535       Default: storage/timers
536
537   timer-db-max-size
538       The hard limit for the timer database maximum size.
539
540       NOTE:
541          This value also influences server's usage of virtual memory.
542
543       Default: 100 MiB
544
545   catalog-db
546       An explicit specification of the zone catalog database directory.  Only
547       useful if catalog-zones  are  enabled.   Non-absolute  path  (i.e.  not
548       starting with /) is relative to storage.
549
550       Default: storage/catalog
551
552   catalog-db-max-size
553       The hard limit for the catalog database maximum size.
554
555       NOTE:
556          This value also influences server's usage of virtual memory.
557
558       Default: 20 GiB (512 MiB for 32-bit)
559

KEYSTORE SECTION

561       DNSSEC keystore configuration.
562
563          keystore:
564            - id: STR
565              backend: pem | pkcs11
566              config: STR
567
568   id
569       A keystore identifier.
570
571   backend
572       A key storage backend type.
573
574       Possible values:
575
576       · pem – PEM files.
577
578       · pkcs11 – PKCS #11 storage.
579
580       Default: pem
581
582   config
583       A  backend specific configuration. A directory with PEM files (the path
584       can be specified as a relative path  to  kasp-db)  or  a  configuration
585       string for PKCS #11 storage (<pkcs11-url> <module-path>).
586
587       NOTE:
588          Example configuration string for PKCS #11:
589
590              "pkcs11:token=knot;pin-value=1234 /usr/lib64/pkcs11/libsofthsm2.so"
591
592       Default: kasp-db/keys
593

KEY SECTION

595       Shared TSIG keys used to authenticate communication with the server.
596
597          key:
598            - id: DNAME
599              algorithm: hmac-md5 | hmac-sha1 | hmac-sha224 | hmac-sha256 | hmac-sha384 | hmac-sha512
600              secret: BASE64
601
602   id
603       A key name identifier.
604
605       NOTE:
606          This  value  MUST be exactly the same as the name of the TSIG key on
607          the opposite primary/secondary server(s).
608
609   algorithm
610       A TSIG key algorithm. See TSIG Algorithm Numbers.
611
612       Possible values:
613
614       · hmac-md5
615
616       · hmac-sha1
617
618       · hmac-sha224
619
620       · hmac-sha256
621
622       · hmac-sha384
623
624       · hmac-sha512
625
626       Default: not set
627
628   secret
629       Shared key secret.
630
631       Default: not set
632

REMOTE SECTION

634       Definitions of remote servers for outgoing  connections  (source  of  a
635       zone transfer, target for a notification, etc.).
636
637          remote:
638            - id: STR
639              address: ADDR[@INT] ...
640              via: ADDR[@INT] ...
641              key: key_id
642              block-notify-after-transfer: BOOL
643
644   id
645       A remote identifier.
646
647   address
648       An ordered list of destination IP addresses which are used for communi‐
649       cation with the remote server. The  addresses  are  tried  in  sequence
650       until  the remote is reached. Optional destination port (default is 53)
651       can be appended to the address using @ separator.
652
653       Default: not set
654
655       NOTE:
656          If the remote is contacted  and  it  refuses  to  perform  requested
657          action, no more addresses will be tried for this remote.
658
659   via
660       An ordered list of source IP addresses. The first address with the same
661       family as  the  destination  address  is  used.  Optional  source  port
662       (default is random) can be appended to the address using @ separator.
663
664       Default: not set
665
666   key
667       A  reference to the TSIG key which is used to authenticate the communi‐
668       cation with the remote server.
669
670       Default: not set
671
672   block-notify-after-transfer
673       When incoming AXFR/IXFR from this remote (as a  primary  server),  sup‐
674       press sending NOTIFY messages to all configured secondary servers.
675
676       Default: off
677

ACL SECTION

679       Access control list rule definitions. The ACLs are used to match incom‐
680       ing connections to allow or deny  requested  operation  (zone  transfer
681       request, DDNS update, etc.).
682
683          acl:
684            - id: STR
685              address: ADDR[/INT] | ADDR-ADDR ...
686              key: key_id ...
687              remote: remote_id ...
688              action: notify | transfer | update ...
689              deny: BOOL
690              update-type: STR ...
691              update-owner: key | zone | name
692              update-owner-match: sub-or-equal | equal | sub
693              update-owner-name: STR ...
694
695   id
696       An ACL rule identifier.
697
698   address
699       An  ordered  list  of IP addresses, network subnets, or network ranges.
700       The query's source address must match one of them.  Empty  value  means
701       that address match is not required.
702
703       Default: not set
704
705   key
706       An ordered list of references to TSIG keys. The query must match one of
707       them. Empty value means that transaction authentication is not used.
708
709       Default: not set
710
711   remote
712       An ordered list of references to remotes. The query must match  one  of
713       the  remotes.  Specifically, one of the remote's addresses and remote's
714       TSIG key if configured must match.
715
716       NOTE:
717          This option cannot be specified along with the address or key option
718          at one ACL item.
719
720       Default: not set
721
722   action
723       An ordered list of allowed (or denied) actions.
724
725       Possible values:
726
727       · notify – Allow incoming notify.
728
729       · transfer – Allow zone transfer.
730
731       · update – Allow zone updates.
732
733       Default: not set
734
735   deny
736       If  enabled,  instead  of allowing, deny the specified action, address,
737       key, or combination if these items. If no action is specified, deny all
738       actions.
739
740       Default: off
741
742   update-type
743       A  list  of  allowed  types of Resource Records in a zone update. Every
744       record in an update must match one of the specified types.
745
746       Default: not set
747
748   update-owner
749       This option restricts possible owners of Resource  Records  in  a  zone
750       update  by  comparing them to either the TSIG key identity, the current
751       zone name, or to a list of domain names given by the  update-owner-name
752       option.   The  comparison  method  is  given  by the update-owner-match
753       option.
754
755       Possible values:
756
757       · key — The owner of each updated RR must match  the  identity  of  the
758         TSIG key if used.
759
760       · name  —  The owner of each updated RR must match at least one name in
761         the update-owner-name list.
762
763       · zone — The owner of each updated RR must match the current zone name.
764
765       Default: not set
766
767   update-owner-match
768       This option defines how the owners of Resource Records in an update are
769       matched to the domain name(s) set by the update-owner option.
770
771       Possible values:
772
773       · sub-or-equal  —  The  owner of each Resource Record in an update must
774         either be equal to or be a subdomain of at least one  domain  set  by
775         update-owner.
776
777       · equal  —  The  owner of each updated RR must be equal to at least one
778         domain set by update-owner.
779
780       · sub — The owner of each updated RR must be a subdomain of,  but  MUST
781         NOT be equal to at least one domain set by update-owner.
782
783       Default: sub-or-equal
784
785   update-owner-name
786       A list of allowed owners of RRs in a zone update used with update-owner
787       set to name. Every listed owner name which is not FQDN (i.e. it doesn't
788       end  in a dot) is considered as if it was appended with the target zone
789       name.  Such a relative owner name specification allows better ACL  rule
790       reusability across multiple zones.
791
792       Default: not set
793

SUBMISSION SECTION

795       Parameters of KSK submission checks.
796
797          submission:
798            - id: STR
799              parent: remote_id ...
800              check-interval: TIME
801              timeout: TIME
802
803   id
804       A submission identifier.
805
806   parent
807       A list of references to parent's DNS servers to be checked for presence
808       of corresponding DS records in the case of KSK submission. All of  them
809       must  have  a corresponding DS for the rollover to continue. If none is
810       specified, the rollover must be pushed forward manually.
811
812       Default: not set
813
814       TIP:
815          A DNSSEC-validating resolver can be set as a parent.
816
817   check-interval
818       Interval for periodic checks of DS presence on parent's DNS servers, in
819       the case of the KSK submission.
820
821       Default: 1 hour
822
823   timeout
824       After this time period (in seconds) the KSK submission is automatically
825       considered successful, even if all the checks were negative or no  par‐
826       ents are configured.  Set to 0 for infinity.
827
828       Default: 0
829

POLICY SECTION

831       DNSSEC policy configuration.
832
833          policy:
834            - id: STR
835              keystore: STR
836              manual: BOOL
837              single-type-signing: BOOL
838              algorithm: rsasha1 | rsasha1-nsec3-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384 | ed25519 | ed448
839              ksk-size: SIZE
840              zsk-size: SIZE
841              ksk-shared: BOOL
842              dnskey-ttl: TIME
843              zone-max-ttl: TIME
844              ksk-lifetime: TIME
845              zsk-lifetime: TIME
846              propagation-delay: TIME
847              rrsig-lifetime: TIME
848              rrsig-refresh: TIME
849              rrsig-pre-refresh: TIME
850              reproducible-signing: BOOL
851              nsec3: BOOL
852              nsec3-iterations: INT
853              nsec3-opt-out: BOOL
854              nsec3-salt-length: INT
855              nsec3-salt-lifetime: TIME
856              signing-threads: INT
857              ksk-submission: submission_id
858              ds-push: remote_id
859              cds-cdnskey-publish: none | delete-dnssec | rollover | always | double-ds
860              offline-ksk: BOOL
861
862   id
863       A policy identifier.
864
865   keystore
866       A reference to a keystore holding private key material for zones.
867
868       Default: an imaginary keystore with all default values
869
870       NOTE:
871          A  configured keystore called "default" won't be used unless explic‐
872          itly referenced.
873
874   manual
875       If enabled, automatic key management is not used.
876
877       Default: off
878
879   single-type-signing
880       If enabled, Single-Type Signing Scheme is used  in  the  automatic  key
881       management mode.
882
883       Default: off (module onlinesign has default on)
884
885   algorithm
886       An  algorithm  of  signing keys and issued signatures. See DNSSEC Algo‐
887       rithm Numbers.
888
889       Possible values:
890
891       · rsasha1
892
893       · rsasha1-nsec3-sha1
894
895       · rsasha256
896
897       · rsasha512
898
899       · ecdsap256sha256
900
901       · ecdsap384sha384
902
903       · ed25519
904
905       · ed448
906
907       NOTE:
908          Ed25519 algorithm is only available if compiled with GnuTLS 3.6.0+.
909
910          Ed448 algorithm is only available if compiled  with  GnuTLS  3.6.12+
911          and Nettle 3.6+.
912
913       Default: ecdsap256sha256
914
915   ksk-size
916       A length of newly generated KSK or CSK keys.
917
918       Default:  2048 (rsa*), 256 (ecdsap256), 384 (ecdsap384), 256 (ed25519),
919       456 (ed448)
920
921   zsk-size
922       A length of newly generated ZSK keys.
923
924       Default: see default for ksk-size
925
926   ksk-shared
927       If enabled, all zones with this policy assigned will share one KSK.
928
929       Default: off
930
931   dnskey-ttl
932       A TTL value for DNSKEY records added into zone apex.
933
934       NOTE:
935          Has infuence over ZSK key lifetime.
936
937       WARNING:
938          Ensure all DNSKEYs with updated TTL are propagated before any subse‐
939          quent DNSKEY rollover starts.
940
941       Default: zone SOA TTL
942
943   zone-max-ttl
944       Declare (override) maximal TTL value among all the records in zone.
945
946       NOTE:
947          It's  generally  recommended to override the maximal TTL computation
948          by setting this explicitly  whenever  possible.  It's  required  for
949          DNSSEC  Offline KSK and really reasonable when records are generated
950          dynamically (e.g. by a module).
951
952       Default: computed after zone is loaded
953
954   ksk-lifetime
955       A period between KSK activation and the next rollover initiation.
956
957       NOTE:
958          KSK key lifetime is also infuenced by propagation-delay, dnskey-ttl,
959          and KSK submission delay.
960
961          Zero (aka infinity) value causes no KSK rollover as a result.
962
963          This applies for CSK lifetime if single-type-signing is enabled.
964
965       Default: 0
966
967   zsk-lifetime
968       A period between ZSK activation and the next rollover initiation.
969
970       NOTE:
971          More  exactly, this period is measured since a ZSK is activated, and
972          after this, a new ZSK is generated to replace  it  within  following
973          roll-over.
974
975          ZSK   key  lifetime  is  also  infuenced  by  propagation-delay  and
976          dnskey-ttl
977
978          Zero (aka infinity) value causes no ZSK rollover as a result.
979
980       Default: 30 days
981
982   propagation-delay
983       An extra delay added for each key rollover step. This value  should  be
984       high enough to cover propagation of data from the primary server to all
985       secondary servers.
986
987       NOTE:
988          Has infuence over ZSK key lifetime.
989
990       Default: 1 hour
991
992   rrsig-lifetime
993       A validity period of newly issued signatures.
994
995       NOTE:
996          The RRSIG's signature inception time is set to  90  minutes  in  the
997          past. This time period is not counted to the signature lifetime.
998
999       Default: 14 days
1000
1001   rrsig-refresh
1002       A  period how long at least before a signature expiration the signature
1003       will be refreshed, in order to  prevent  expired  RRSIGs  on  secondary
1004       servers or resolvers' caches.
1005
1006       Default: 7 days
1007
1008   rrsig-pre-refresh
1009       A period how long at most before a signature refresh time the signature
1010       might be refreshed, in order to refresh RRSIGs in bigger batches  on  a
1011       frequently updated zone (avoid re-sign event too often).
1012
1013       Default: 1 hour
1014
1015   reproducible-signing
1016       For  ECDSA algorithms, generate RRSIG signatures deterministically (RFC
1017       6979).  Besides better theoretical cryptographic  security,  this  mode
1018       allows  significant  speed-up  of  loading  signed (by the same method)
1019       zones. However, the zone signing is a bit slower.
1020
1021       Default: off
1022
1023   nsec3
1024       Specifies if NSEC3 will be used instead of NSEC.
1025
1026       Default: off
1027
1028   nsec3-iterations
1029       A number of additional times the hashing is performed.
1030
1031       Default: 5
1032
1033   nsec3-opt-out
1034       If set, NSEC3 records won't be created for insecure delegations.   This
1035       speeds up the zone signing and reduces overall zone size.
1036
1037       WARNING:
1038          NSEC3  with  the  Opt-Out  bit  set  no  longer  works as a proof of
1039          non-existence in this zone.
1040
1041       Default: off
1042
1043   nsec3-salt-length
1044       A length of a salt field in octets, which is appended to  the  original
1045       owner name before hashing.
1046
1047       Default: 8
1048
1049   nsec3-salt-lifetime
1050       A validity period of newly issued salt field.
1051
1052       Zero value means infinity.
1053
1054       Default: 30 days
1055
1056   signing-threads
1057       When  signing  zone  or update, use this number of threads for parallel
1058       signing.
1059
1060       Those are extra threads independent of Background workers.
1061
1062       NOTE:
1063          Some steps of the DNSSEC signing operation are not parallelized.
1064
1065       Default: 1 (no extra threads)
1066
1067   ksk-submission
1068       A reference to submission section holding parameters of KSK  submission
1069       checks.
1070
1071       Default: not set
1072
1073   ds-push
1074       An optional reference to authoritative DNS server of the parent's zone.
1075       The remote server must be configured to accept DS  record  updates  via
1076       DDNS.  Whenever  a  CDS record in the local zone is changed, the corre‐
1077       sponding DS record is sent as a dynamic update (DDNS) to the parent DNS
1078       server.  All  previous  DS records are deleted within the DDNS message.
1079       It's possible to manage both child and parent zones by  the  same  Knot
1080       DNS server.
1081
1082       NOTE:
1083          This feature requires cds-cdnskey-publish not to be set to none.
1084
1085       NOTE:
1086          Module Onlinesign doesn't support DS push.
1087
1088       Default: not set
1089
1090   cds-cdnskey-publish
1091       Controls if and how shall the CDS and CDNSKEY be published in the zone.
1092
1093       Possible values:
1094
1095       · none – Never publish any CDS or CDNSKEY records in the zone.
1096
1097       · delete-dnssec  –  Publish  special CDS and CDNSKEY records indicating
1098         turning off DNSSEC.
1099
1100       · rollover – Publish CDS and CDNSKEY records  for  ready  and  not  yet
1101         active KSK (submission phase of KSK rollover).
1102
1103       · always  – Always publish one CDS and one CDNSKEY records for the cur‐
1104         rent KSK.
1105
1106       · double-ds – Always publish up to two CDS and two CDNSKEY records  for
1107         ready and/or active KSKs.
1108
1109       NOTE:
1110          If  the  zone  keys are managed manually, the CDS and CDNSKEY rrsets
1111          may contain more records depending on the keys available.
1112
1113       Default: rollover
1114
1115   offline-ksk
1116       Specifies if Offline KSK feature is enabled.
1117
1118       Default: off
1119

TEMPLATE SECTION

1121       A template is shareable zone settings, which can simplify configuration
1122       by  reducing  duplicates.  A special default template (with the default
1123       identifier) can be used for global zone configuration or as an implicit
1124       configuration if a zone doesn't have another template specified.
1125
1126          template:
1127            - id: STR
1128              global-module: STR/STR ...
1129              # All zone options (excluding 'template' item)
1130
1131   id
1132       A template identifier.
1133
1134   global-module
1135       An  ordered  list  of  references  to query modules in the form of mod‐
1136       ule_name or module_name/module_id. These modules apply to all queries.
1137
1138       NOTE:
1139          This option is only available in the default template.
1140
1141       Default: not set
1142

ZONE SECTION

1144       Definition of zones served by the server.
1145
1146          zone:
1147            - domain: DNAME
1148              template: template_id
1149              storage: STR
1150              file: STR
1151              master: remote_id ...
1152              ddns-master: remote_id
1153              notify: remote_id ...
1154              acl: acl_id ...
1155              semantic-checks: BOOL
1156              zonefile-sync: TIME
1157              zonefile-load: none | difference | difference-no-serial | whole
1158              journal-content: none | changes | all
1159              journal-max-usage: SIZE
1160              journal-max-depth: INT
1161              zone-max-size : SIZE
1162              adjust-threads: INT
1163              dnssec-signing: BOOL
1164              dnssec-validation: BOOL
1165              dnssec-policy: STR
1166              serial-policy: increment | unixtime | dateserial
1167              refresh-min-interval: TIME
1168              refresh-max-interval: TIME
1169              catalog-role: none | interpret
1170              catalog-template: template_id
1171              module: STR/STR ...
1172
1173   domain
1174       A zone name identifier.
1175
1176   template
1177       A reference to a configuration template.
1178
1179       Default: not set or default (if the template exists)
1180
1181   storage
1182       A data directory for storing zone files.
1183
1184       Default:  ${localstatedir}/lib/knot   (configured   with   --with-stor‐
1185       age=path)
1186
1187   file
1188       A  path  to the zone file. Non-absolute path (i.e. not starting with /)
1189       is relative to storage.  It is also possible to use the following  for‐
1190       matters:
1191
1192       · %c[N]  or  %c[N-M] – Means the Nth character or a sequence of charac‐
1193         ters beginning from the Nth and ending with the Mth character of  the
1194         textual  zone  name (see %s). The indexes are counted from 0 from the
1195         left. All dots (including the terminal one) are  considered.  If  the
1196         character is not available, the formatter has no effect.
1197
1198       · %l[N]  –  Means  the Nth label of the textual zone name (see %s). The
1199         index is counted from 0 from the right (0 ~ TLD).  If  the  label  is
1200         not available, the formatter has no effect.
1201
1202       · %s  – Means the current zone name in the textual representation.  The
1203         zone name doesn't include the terminating dot  (the  result  for  the
1204         root zone is the empty string!).
1205
1206       · %% – Means the % character.
1207
1208       WARNING:
1209          Beware  of  special  characters  which are escaped or encoded in the
1210          \DDD form where DDD is corresponding decimal ASCII code.
1211
1212       Default: storage/%s.zone
1213
1214   master
1215       An ordered list of references to zone primary servers  (formerly  known
1216       as master servers).
1217
1218       Default: not set
1219
1220   ddns-master
1221       A  reference to zone primary master. If not specified, the first master
1222       server is used.
1223
1224       Default: not set
1225
1226   notify
1227       An ordered list of references to remotes to  which  notify  message  is
1228       sent if the zone changes.
1229
1230       Default: not set
1231
1232   acl
1233       An  ordered list of references to ACL rules which can allow or disallow
1234       zone transfers, updates or incoming notifies.
1235
1236       Default: not set
1237
1238   semantic-checks
1239       If enabled, extra zone semantic checks are turned on.
1240
1241       Several checks are enabled by default and  cannot  be  turned  off.  An
1242       error  in  mandatory  checks  causes zone not to be loaded. An error in
1243       extra checks is logged only.
1244
1245       Mandatory checks:
1246
1247       · SOA record missing in the zone (RFC 1034)
1248
1249       · An extra record together with CNAME record except for RRSIG and DS (‐
1250         RFC 1034)
1251
1252       · Multiple CNAME record with the same owner
1253
1254       · DNAME record having a record under it (RFC 2672)
1255
1256       Extra checks:
1257
1258       · Missing NS record at the zone apex
1259
1260       · Missing glue A or AAAA record
1261
1262       · Invalid DNSKEY, DS, or NSEC3PARAM record
1263
1264       · CDS or CDNSKEY inconsistency
1265
1266       · Missing, invalid, or unverifiable RRSIG record
1267
1268       · Invalid NSEC(3) record
1269
1270       · Broken or non-cyclic NSEC(3) chain
1271
1272       Default: off
1273
1274   zonefile-sync
1275       The  time  after which the current zone in memory will be synced with a
1276       zone file on the disk (see file). The server will serve the latest zone
1277       even  after a restart using zone journal, but the zone file on the disk
1278       will only be synced after zonefile-sync time has expired (or after man‐
1279       ual  zone flush). This is applicable when the zone is updated via IXFR,
1280       DDNS or automatic DNSSEC signing. In order to completely disable  auto‐
1281       matic  zone file synchronization, set the value to -1. In that case, it
1282       is still possible to force a manual zone flush using the -f option.
1283
1284       NOTE:
1285          If you are serving large zones with frequent updates where the imme‐
1286          diate sync with a zone file is not desirable, increase the value.
1287
1288       Default: 0 (immediate)
1289
1290   zonefile-load
1291       Selects how the zone file contents are applied during zone load.
1292
1293       Possible values:
1294
1295       · none – The zone file is not used at all.
1296
1297       · difference – If the zone contents are already available during server
1298         start or reload, the difference is computed between them and the con‐
1299         tents  of the zone file. This difference is then checked for semantic
1300         errors and applied to the current zone contents.
1301
1302       · difference-no-serial – Same as difference, but the SOA serial in  the
1303         zone  file  is  ignored,  the  server  takes care of incrementing the
1304         serial automatically.
1305
1306       · whole – Zone contents are loaded from the zone file.
1307
1308       When difference is configured and there are no zone contents yet  (cold
1309       start of Knot and no zone contents in journal), it behaves the same way
1310       like whole.
1311
1312       Default: whole
1313
1314   journal-content
1315       Selects how the journal shall be used to store zone and its changes.
1316
1317       Possible values:
1318
1319       · none – The journal is not used at all.
1320
1321       · changes – Zone changes history is stored in journal.
1322
1323       · all – Zone contents and history is stored in journal.
1324
1325       Default: changes
1326
1327   journal-max-usage
1328       Policy how much space in journal DB will the zone's journal occupy.
1329
1330       NOTE:
1331          Journal DB may grow far above the sum  of  journal-max-usage  across
1332          all zones, because of DB free space fragmentation.
1333
1334       Default: 100 MiB
1335
1336   journal-max-depth
1337       Maximum history length of journal.
1338
1339       Minimum: 2
1340
1341       Default: 2^64
1342
1343   zone-max-size
1344       Maximum  size  of  the  zone.  The size is measured as size of the zone
1345       records in wire format without compression. The limit is  enforced  for
1346       incoming zone transfers and dynamic updates.
1347
1348       For  incremental  transfers  (IXFR),  the effective limit for the total
1349       size of the records in the transfer is twice the configured value. How‐
1350       ever the final size of the zone must satisfy the configured value.
1351
1352       Default: 2^64
1353
1354   adjust-threads
1355       Parallelize  internal  zone  adjusting  procedures. This is useful with
1356       huge zones with NSEC3. Speedup observable at server startup  and  while
1357       processing NSEC3 re-salt.
1358
1359       Default: 1
1360
1361   dnssec-signing
1362       If enabled, automatic DNSSEC signing for the zone is turned on.
1363
1364       Default: off
1365
1366   dnssec-validation
1367       If  enabled, the zone contents are validated for being correctly signed
1368       (including NSEC/NSEC3 chain) with DNSSEC signatures every time the zone
1369       is loaded or changed (including AXFR/IXFR).
1370
1371       When  the  validation  fails,  the  zone  being  loaded or update being
1372       applied is cancelled with an error, and either none  or  previous  zone
1373       state is published.
1374
1375       List of DNSSEC checks:
1376
1377       · Every zone RRSet is correctly signed by at least one present DNSKEY.
1378
1379       · DNSKEY RRSet is signed by KSK.
1380
1381       · NSEC(3) RR exists for each name (unless opt-out) with correct bitmap.
1382
1383       · Every NSEC(3) RR is linked to the lexicographically next one.
1384
1385       The  validation  is not affected by dnssec-policy configuration, except
1386       for signing-threads option, which specifies the number of  threads  for
1387       parallel validation.
1388
1389       NOTE:
1390          Redundant or garbage NSEC3 records are ignored.
1391
1392          This mode is not compatible with dnssec-signing.
1393
1394   dnssec-policy
1395       A reference to DNSSEC signing policy.
1396
1397       Default: an imaginary policy with all default values
1398
1399       NOTE:
1400          A configured policy called "default" won't be used unless explicitly
1401          referenced.
1402
1403   serial-policy
1404       Specifies how the zone serial is updated  after  a  dynamic  update  or
1405       automatic  DNSSEC  signing.  If  the  serial  is changed by the dynamic
1406       update, no change is made.
1407
1408       Possible values:
1409
1410       · increment – The serial is  incremented  according  to  serial  number
1411         arithmetic.
1412
1413       · unixtime – The serial is set to the current unix time.
1414
1415       · dateserial  –  The  10-digit  serial (YYYYMMDDnn) is incremented, the
1416         first 8 digits match the current iso-date.
1417
1418       NOTE:
1419          If the resulting serial for unixtime or dateserial is lower or equal
1420          than the current serial (this happens e.g. when migrating from other
1421          policy or frequent updates), the serial is incremented instead.
1422
1423          To avoid user confusion, use dateserial only if you expect  at  most
1424          100 updates per day per zone and unixtime only if you expect at most
1425          one update per second per zone.
1426
1427       Default: increment
1428
1429   refresh-min-interval
1430       Forced minimum zone refresh interval to avoid flooding primary server.
1431
1432       Default: 2
1433
1434   refresh-max-interval
1435       Forced maximum zone refresh interval.
1436
1437       Default: not set
1438
1439   catalog-role
1440       Trigger zone catalog feature. Possible values:
1441
1442       · none – Not a catalog zone.
1443
1444       · interpret – A catalog zone which is loaded from a zone file  or  XFR,
1445         and member zones shall be configured based on its contents.
1446
1447       Default: none
1448
1449   catalog-template
1450       For the catalog-member zones, the specified configuration template will
1451       be applied.
1452
1453       NOTE:
1454          This option must be set if and only if catalog-role is interpret.
1455
1456       Default: not set
1457
1458   module
1459       An ordered list of references to query modules  in  the  form  of  mod‐
1460       ule_name or module_name/module_id. These modules apply only to the cur‐
1461       rent zone queries.
1462
1463       Default: not set
1464

AUTHOR

1466       CZ.NIC Labs <https://www.knot-dns.cz>
1467
1469       Copyright 2010–2021, CZ.NIC, z.s.p.o.
1470
1471
1472
1473
14743.0.5                             2021-03-25                      KNOT.CONF(5)
Impressum