knot.conf.5in 32.5 KB
Newer Older
1 2
.\" Man page generated from reStructuredText.
.
3
.TH "KNOT.CONF" "5" "@RELEASE_DATE@" "@VERSION@" "Knot DNS"
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
.SH NAME
knot.conf \- Knot DNS configuration file
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH DESCRIPTION
.sp
35 36
Configuration files for Knot DNS use simplified YAML format. Simplified means
that not all of the features are supported.
37
.sp
38 39
For the description of configuration items, we have to declare a meaning of
the following symbols:
40 41
.INDENT 0.0
.IP \(bu 2
42
\fIINT\fP – Integer
43
.IP \(bu 2
44
\fISTR\fP – Textual string
45
.IP \(bu 2
46
\fIHEXSTR\fP – Hexadecimal string (with \fB0x\fP prefix)
47
.IP \(bu 2
48
\fIBOOL\fP – Boolean value (\fBon\fP/\fBoff\fP or \fBtrue\fP/\fBfalse\fP)
49
.IP \(bu 2
50
\fITIME\fP – Number of seconds, an integer with possible time multiplier suffix
51 52
(\fBs\fP ~ 1, \fBm\fP ~ 60, \fBh\fP ~ 3600 or \fBd\fP ~ 24 * 3600)
.IP \(bu 2
53
\fISIZE\fP – Number of bytes, an integer with possible size multiplier suffix
54 55
(\fBB\fP ~ 1, \fBK\fP ~ 1024, \fBM\fP ~ 1024^2 or \fBG\fP ~ 1024^3)
.IP \(bu 2
56
\fIBASE64\fP – Base64 encoded string
57
.IP \(bu 2
58
\fIADDR\fP – IPv4 or IPv6 address
59
.IP \(bu 2
60
\fIDNAME\fP – Domain name
61
.IP \(bu 2
62
\&... – Multi\-valued item, order of the values is preserved
63
.IP \(bu 2
64
[ ] – Optional value
65
.IP \(bu 2
66
| – Choice
67 68
.UNINDENT
.sp
69 70 71 72 73
There are 12 main sections (\fBmodule\fP, \fBserver\fP, \fBcontrol\fP, \fBlog\fP,
\fBstatistics\fP, \fBkeystore\fP, \fBpolicy\fP, \fBkey\fP, \fBacl\fP, \fBremote\fP,
\fBtemplate\fP, and \fBzone\fP) and module sections with the \fBmod\-\fP prefix.
Most of the sections (excluding \fBserver\fP, \fBcontrol\fP, and \fBstatistics\fP)
are sequences of settings blocks. Each settings block begins with a unique identifier,
74 75
which can be used as a reference from other sections (such identifier
must be defined in advance).
76
.sp
77 78 79 80 81 82 83 84 85 86 87 88 89
A multi\-valued item can be specified either as a YAML sequence:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
address: [10.0.0.1, 10.0.0.2]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or as more single\-valued items each on an extra line:
90 91 92 93 94 95 96 97 98 99 100
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
address: 10.0.0.1
address: 10.0.0.2
.ft P
.fi
.UNINDENT
.UNINDENT
101 102
.sp
If an item value contains spaces or other special characters, it is necessary
103
to enclose such value within double quotes \fB"\fP \fB"\fP\&.
104 105
.SH COMMENTS
.sp
106
A comment begins with a \fB#\fP character and is ignored during processing.
107 108
Also each configuration section or sequence block allows a permanent
comment using the \fBcomment\fP item which is stored in the server beside the
109 110 111
configuration.
.SH INCLUDES
.sp
112 113 114 115
Another configuration file or files, matching a pattern, can be included at
the top level in the current file. If the path is not absolute, then it
is considered to be relative to the current file. The pattern can be
an arbitrary string meeting POSIX \fIglob\fP requirements, e.g. dir/*.conf.
116
Matching files are processed in sorted order.
117 118 119 120 121 122 123 124 125 126
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include: STR
.ft P
.fi
.UNINDENT
.UNINDENT
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
.SH MODULE SECTION
.sp
Dynamic modules loading configuration.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If configured with non\-empty \fB\(ga\-\-with\-moduledir=path\(ga\fP parameter, all
shared modules in this directory will be automatically loaded.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
module:
  \- id: STR
    file: STR
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier in the form of the \fBmod\-\fP prefix and module name suffix.
.SS file
.sp
A path to a shared library file with the module implementation.
.sp
\fIDefault:\fP \fB${libdir}/knot/modules\-${version}\fP/module_name.so
(or \fB${path}\fP/module_name.so if configured with \fB\-\-with\-moduledir=path\fP)
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
If the path is not absolute, the library is searched in the set of
system directories. See \fBman dlopen\fP for more details.
.UNINDENT
.UNINDENT
167 168 169 170 171 172 173 174 175 176 177 178 179 180 181
.SH SERVER SECTION
.sp
General options related to the server.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
server:
    identity: [STR]
    version: [STR]
    nsid: [STR|HEXSTR]
    rundir: STR
    user: STR[:STR]
    pidfile: STR
182 183
    udp\-workers: INT
    tcp\-workers: INT
184
    background\-workers: INT
185
    async\-start: BOOL
186
    tcp\-handshake\-timeout: TIME
187
    tcp\-idle\-timeout: TIME
188
    tcp\-reply\-timeout: TIME
189 190
    max\-tcp\-clients: INT
    max\-udp\-payload: SIZE
191 192
    max\-ipv4\-udp\-payload: SIZE
    max\-ipv6\-udp\-payload: SIZE
193 194 195 196 197 198 199
    listen: ADDR[@INT] ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS identity
.sp
200
An identity of the server returned in the response to the query for TXT
201
record \fBid.server.\fP or \fBhostname.bind.\fP in the CHAOS class (\fI\%RFC 4892\fP).
202 203
Set empty value to disable.
.sp
204
\fIDefault:\fP FQDN hostname
205 206
.SS version
.sp
207
A version of the server software returned in the response to the query
208
for TXT record \fBversion.server.\fP or \fBversion.bind.\fP in the CHAOS
209
class (\fI\%RFC 4892\fP). Set empty value to disable.
210
.sp
211
\fIDefault:\fP server version
212 213
.SS nsid
.sp
214
A DNS name server identifier (\fI\%RFC 5001\fP). Set empty value to disable.
215
.sp
216
\fIDefault:\fP FQDN hostname
217 218 219 220
.SS rundir
.sp
A path for storing run\-time data (PID file, unix sockets, etc.).
.sp
221
\fIDefault:\fP \fB${localstatedir}/run/knot\fP (configured with \fB\-\-with\-rundir=path\fP)
222 223
.SS user
.sp
224
A system user with an optional system group (\fBuser:group\fP) under which the
225 226 227
server is run after starting and binding to interfaces. Linux capabilities
are employed if supported.
.sp
228
\fIDefault:\fP root:root
229 230 231 232
.SS pidfile
.sp
A PID file location.
.sp
233
\fIDefault:\fP \fI\%rundir\fP/knot.pid
234
.SS udp\-workers
235
.sp
236 237
A number of UDP workers (threads) used to process incoming queries
over UDP.
238
.sp
239
\fIDefault:\fP auto\-estimated optimal value based on the number of online CPUs
240 241
.SS tcp\-workers
.sp
242 243
A number of TCP workers (threads) used to process incoming queries
over TCP.
244
.sp
245
\fIDefault:\fP auto\-estimated optimal value based on the number of online CPUs
246 247 248 249 250
.SS background\-workers
.sp
A number of workers (threads) used to execute background operations (zone
loading, zone updates, etc.).
.sp
251
\fIDefault:\fP auto\-estimated optimal value based on the number of online CPUs
252
.SS async\-start
253 254 255 256
.sp
If enabled, server doesn\(aqt wait for the zones to be loaded and starts
responding immediately with SERVFAIL answers until the zone loads.
.sp
257
\fIDefault:\fP off
258
.SS tcp\-handshake\-timeout
259 260 261 262 263
.sp
Maximum time between newly accepted TCP connection and the first query.
This is useful to disconnect inactive connections faster than connections
that already made at least 1 meaningful query.
.sp
264
\fIDefault:\fP 5
265 266 267 268 269
.SS tcp\-idle\-timeout
.sp
Maximum idle time between requests on a TCP connection. This also limits
receiving of a single query, each query must be received in this time limit.
.sp
270
\fIDefault:\fP 20
271
.SS tcp\-reply\-timeout
272
.sp
273
Maximum time to wait for an outgoing connection or for a reply to an issued
274
request (SOA, NOTIFY, AXFR...).
275
.sp
276
\fIDefault:\fP 10
277 278 279 280 281
.SS max\-tcp\-clients
.sp
A maximum number of TCP clients connected in parallel, set this below the file
descriptor limit to avoid resource exhaustion.
.sp
282
\fIDefault:\fP 100
283 284
.SS max\-udp\-payload
.sp
285 286 287 288 289 290 291 292 293 294 295
Maximum EDNS0 UDP payload size default for both IPv4 and IPv6.
.sp
\fIDefault:\fP 4096
.SS max\-ipv4\-udp\-payload
.sp
Maximum EDNS0 UDP payload size for IPv4.
.sp
\fIDefault:\fP 4096
.SS max\-ipv6\-udp\-payload
.sp
Maximum EDNS0 UDP payload size for IPv6.
296
.sp
297
\fIDefault:\fP 4096
298 299 300 301 302 303 304
.SS listen
.sp
One or more IP addresses where the server listens for incoming queries.
Optional port specification (default is 53) can be appended to each address
using \fB@\fP separator. Use \fB0.0.0.0\fP for all configured IPv4 addresses or
\fB::\fP for all configured IPv6 addresses.
.sp
305
\fIDefault:\fP not set
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324
.SH KEY SECTION
.sp
Shared TSIG keys used to authenticate communication with the server.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
key:
  \- id: DNAME
    algorithm: hmac\-md5 | hmac\-sha1 | hmac\-sha224 | hmac\-sha256 | hmac\-sha384 | hmac\-sha512
    secret: BASE64
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A key name identifier.
325 326 327 328 329 330 331 332
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This value MUST be exactly the same as the name of the TSIG key on the
opposite master/slave server(s).
.UNINDENT
.UNINDENT
333 334 335 336
.SS algorithm
.sp
A key algorithm.
.sp
337
\fIDefault:\fP not set
338 339 340 341
.SS secret
.sp
Shared key secret.
.sp
342
\fIDefault:\fP not set
343 344
.SH ACL SECTION
.sp
345 346 347
Access control list rule definitions. The ACLs are used to match incoming
connections to allow or deny requested operation (zone transfer request, DDNS
update, etc.).
348 349 350 351 352 353 354
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
acl:
  \- id: STR
355
    address: ADDR[/INT] | ADDR\-ADDR ...
356
    key: key_id ...
357
    action: notify | transfer | update ...
358
    deny: BOOL
359 360 361 362 363 364 365 366 367
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
An ACL rule identifier.
.SS address
.sp
368 369
An ordered list of IP addresses, network subnets, or network ranges. The query
must match one of them. Empty value means that address match is not required.
370
.sp
371
\fIDefault:\fP not set
372 373
.SS key
.sp
374 375
An ordered list of \fI\%reference\fPs to TSIG keys. The query must
match one of them. Empty value means that TSIG key is not required.
376
.sp
377
\fIDefault:\fP not set
378 379
.SS action
.sp
380
An ordered list of allowed (or denied) actions.
381 382 383 384
.sp
Possible values:
.INDENT 0.0
.IP \(bu 2
385
\fBtransfer\fP – Allow zone transfer
386
.IP \(bu 2
387
\fBnotify\fP – Allow incoming notify
388
.IP \(bu 2
389
\fBupdate\fP – Allow zone updates
390 391
.UNINDENT
.sp
392
\fIDefault:\fP not set
393 394
.SS deny
.sp
395 396 397
If enabled, instead of allowing, deny the specified \fI\%action\fP,
\fI\%address\fP, \fI\%key\fP, or combination if these
items. If no action is specified, deny all actions.
398
.sp
399
\fIDefault:\fP off
400 401
.SH CONTROL SECTION
.sp
402
Configuration of the server control interface.
403 404 405 406 407 408
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
control:
409
    listen: STR
410
    timeout: TIME
411 412 413 414 415 416
.ft P
.fi
.UNINDENT
.UNINDENT
.SS listen
.sp
417
A UNIX socket path where the server listens for control commands.
418
.sp
419
\fIDefault:\fP \fI\%rundir\fP/knot.sock
420 421 422 423 424
.SS timeout
.sp
Maximum time the control socket operations can take. Set 0 for infinity.
.sp
\fIDefault:\fP 5
425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457
.SH STATISTICS SECTION
.sp
Periodic server statistics dumping.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
statistics:
    timer: TIME
    file: STR
    append: BOOL
.ft P
.fi
.UNINDENT
.UNINDENT
.SS timer
.sp
A period after which all available statistics metrics will by written to the
\fI\%file\fP\&.
.sp
\fIDefault:\fP not set
.SS file
.sp
A file path of statistics output in the YAML format.
.sp
\fIDefault:\fP \fI\%rundir\fP/stats.yaml
.SS append
.sp
If enabled, the output will be appended to the \fI\%file\fP
instead of file replacement.
.sp
\fIDefault:\fP off
458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478
.SH KEYSTORE SECTION
.sp
DNSSEC keystore configuration.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
keystore:
  \- id: STR
    backend: pem | pkcs11
    config: STR
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A keystore identifier.
.SS backend
.sp
Jan Včelák's avatar
Jan Včelák committed
479
A key storage backend type. A directory with PEM files or a PKCS #11 storage.
480 481 482 483
.sp
\fIDefault:\fP pem
.SS config
.sp
484
A backend specific configuration. A directory with PEM files (the path can
485
be specified as a relative path to \fI\%kasp\-db\fP) or
Jan Včelák's avatar
Jan Včelák committed
486
a configuration string for PKCS #11 storage.
487 488 489 490
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Jan Včelák's avatar
Jan Včelák committed
491
Example configuration string for PKCS #11:
492 493 494 495 496
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
497
"pkcs11:token=knot;pin\-value=1234 /usr/lib64/pkcs11/libsofthsm2.so"
498 499 500 501 502 503 504 505
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP \fI\%kasp\-db\fP/keys
506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528
.SH SUBMISSION SECTION
.sp
Parameters of KSK submission checks.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
submission:
  \- id: STR
    parent: remote_id ...
    check\-interval: TIME
    timeout: TIME
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A submission identifier.
.SS parent
.sp
A list of \fI\%references\fP to parent\(aqs DNS servers to be checked for
529 530 531
presence of corresponding DS records in the case of KSK submission. All of them must
have a corresponding DS for the rollover to continue. If none is specified, the
rollover must be pushed forward manually.
Daniel Salzman's avatar
Daniel Salzman committed
532 533
.sp
\fIDefault:\fP not set
534 535
.SS check\-interval
.sp
536 537
Interval for periodic checks of DS presence on parent\(aqs DNS servers, in the
case of the KSK submission.
538 539 540 541 542
.sp
\fIDefault:\fP 1 hour
.SS timeout
.sp
After this period, the KSK submission is automatically considered successful, even
Daniel Salzman's avatar
Daniel Salzman committed
543
if all the checks were negative or no parents are configured. Set 0 for infinity.
544
.sp
545
\fIDefault:\fP 0
546 547 548 549 550 551 552 553 554 555 556 557
.SH POLICY SECTION
.sp
DNSSEC policy configuration.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
policy:
  \- id: STR
    keystore: STR
    manual: BOOL
558
    single\-type\-signing: BOOL
559
    algorithm: rsasha1 | rsasha1\-nsec3\-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384 | ed25519
560 561
    ksk\-size: SIZE
    zsk\-size: SIZE
Libor Peltan's avatar
Libor Peltan committed
562
    ksk\-shared: BOOL
563 564
    dnskey\-ttl: TIME
    zsk\-lifetime: TIME
Libor Peltan's avatar
Libor Peltan committed
565
    ksk\-lifetime: TIME
566
    propagation\-delay: TIME
567 568 569 570
    rrsig\-lifetime: TIME
    rrsig\-refresh: TIME
    nsec3: BOOL
    nsec3\-iterations: INT
Libor Peltan's avatar
Libor Peltan committed
571
    nsec3\-opt\-out: BOOL
572
    nsec3\-salt\-length: INT
573
    nsec3\-salt\-lifetime: TIME
574
    ksk\-submission: submission_id
575
    cds\-cdnskey\-publish: none | delete\-dnssec | always
576 577 578 579 580 581 582 583 584 585
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A policy identifier.
.SS keystore
.sp
A \fI\%reference\fP to a keystore holding private key material
586
for zones. A special \fIdefault\fP value can be used for the default keystore settings.
587 588 589 590 591 592 593
.sp
\fIDefault:\fP default
.SS manual
.sp
If enabled, automatic key management is not used.
.sp
\fIDefault:\fP off
594 595 596 597 598 599 600 601 602 603 604 605 606 607
.SS single\-type\-signing
.sp
If enabled, Single\-Type Signing Scheme is used in the automatic key management
mode.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Because key rollover is not supported yet, just one combined signing key is
generated if none is available.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP off
608 609 610 611
.SS algorithm
.sp
An algorithm of signing keys and issued signatures.
.sp
612
\fIDefault:\fP ecdsap256sha256
613 614 615 616 617 618 619
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Ed25519 algorithm is only available when compiled with GnuTLS 3.6.0+.
.UNINDENT
.UNINDENT
620 621
.SS ksk\-size
.sp
622 623
A length of newly generated KSK or
CSK keys.
624
.sp
625
\fIDefault:\fP 2048 (rsa*), 256 (ecdsap256), 384 (ecdsap384), 256 (ed25519)
626 627 628 629
.SS zsk\-size
.sp
A length of newly generated ZSK keys.
.sp
630
\fIDefault:\fP see default for \fI\%ksk\-size\fP
Libor Peltan's avatar
Libor Peltan committed
631 632 633 634 635
.SS ksk\-shared
.sp
If enabled, all zones with this policy assigned will share one KSK.
.sp
\fIDefault:\fP off
636 637 638 639 640
.SS dnskey\-ttl
.sp
A TTL value for DNSKEY records added into zone apex.
.sp
\fIDefault:\fP zone SOA TTL
641 642 643 644 645 646 647
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
has infuence over ZSK key lifetime
.UNINDENT
.UNINDENT
648 649 650 651 652
.SS zsk\-lifetime
.sp
A period between ZSK publication and the next rollover initiation.
.sp
\fIDefault:\fP 30 days
653 654 655 656 657 658 659
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
ZSK key lifetime is also infuenced by propagation\-delay and dnskey\-ttl
.UNINDENT
.UNINDENT
Libor Peltan's avatar
Libor Peltan committed
660 661 662 663 664 665 666 667 668 669
.SS ksk\-lifetime
.sp
A period between KSK publication and the next rollover initiation.
.sp
\fIDefault:\fP infinity
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
KSK key lifetime is also infuenced by propagation\-delay, dnskey\-ttl,
670
and KSK submission delay.
Libor Peltan's avatar
Libor Peltan committed
671 672
.sp
The default infinite value causes no KSK rollover as a result.
673 674
.sp
This applies for CSK lifetime if single\-type\-signing is enabled.
Libor Peltan's avatar
Libor Peltan committed
675 676
.UNINDENT
.UNINDENT
677 678 679 680 681 682 683 684 685 686 687 688 689
.SS propagation\-delay
.sp
An extra delay added for each key rollover step. This value should be high
enough to cover propagation of data from the master server to all slaves.
.sp
\fIDefault:\fP 1 day
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
has infuence over ZSK key lifetime
.UNINDENT
.UNINDENT
690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709
.SS rrsig\-lifetime
.sp
A validity period of newly issued signatures.
.sp
\fIDefault:\fP 14 days
.SS rrsig\-refresh
.sp
A period how long before a signature expiration the signature will be refreshed.
.sp
\fIDefault:\fP 7 days
.SS nsec3
.sp
Specifies if NSEC3 will be used instead of NSEC.
.sp
\fIDefault:\fP off
.SS nsec3\-iterations
.sp
A number of additional times the hashing is performed.
.sp
\fIDefault:\fP 5
Libor Peltan's avatar
Libor Peltan committed
710 711 712 713 714 715 716 717 718 719 720 721 722 723
.SS nsec3\-opt\-out
.sp
If set, NSEC3 records won\(aqt be created for insecure delegations.
This speeds up the zone signing and reduces overall zone size.
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
NSEC3 with the Opt\-Out bit set no longer works as a proof of non\-existence
in this zone.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP off
724 725 726 727 728 729
.SS nsec3\-salt\-length
.sp
A length of a salt field in octets, which is appended to the original owner
name before hashing.
.sp
\fIDefault:\fP 8
730
.SS nsec3\-salt\-lifetime
731 732 733 734
.sp
A validity period of newly issued salt field.
.sp
\fIDefault:\fP 30 days
735
.SS ksk\-submission
Libor Peltan's avatar
Libor Peltan committed
736
.sp
737 738
A reference to \fI\%submission\fP section holding parameters of
KSK submittion checks.
Libor Peltan's avatar
Libor Peltan committed
739 740
.sp
\fIDefault:\fP not set
741
.SS cds\-cdnskey\-publish
742 743 744 745 746 747 748 749 750 751 752 753 754 755 756
.sp
Controls if and how shall the CDS and CDNSKEY be published in the zone.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This only applies if the zone keys are automatically managed by the server.
.UNINDENT
.UNINDENT
.sp
Possible values:
.INDENT 0.0
.IP \(bu 2
\fBnone\fP \- never publish any CDS or CDNSKEY records in the zone
.IP \(bu 2
757
\fBdelete\-dnssec\fP \- publish special CDS and CDNSKEY records indicating turning off DNSSEC
758 759 760 761 762
.IP \(bu 2
\fBalways\fP \- always publish CDS and CDNSKEY records for the current KSK
.UNINDENT
.sp
\fIDefault:\fP always
763 764
.SH REMOTE SECTION
.sp
765 766
Definitions of remote servers for outgoing connections (source of a zone
transfer, target for a notification, etc.).
767 768 769 770 771 772 773
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
remote:
  \- id: STR
774 775
    address: ADDR[@INT] ...
    via: ADDR[@INT] ...
776 777 778 779 780 781 782 783 784 785
    key: key_id
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A remote identifier.
.SS address
.sp
786 787 788 789
An ordered list of destination IP addresses which are used for communication
with the remote server. The addresses are tried in sequence unless the
operation is successful. Optional destination port (default is 53)
can be appended to the address using \fB@\fP separator.
790
.sp
791
\fIDefault:\fP not set
792 793
.SS via
.sp
794 795 796
An ordered list of source IP addresses. The first address with the same family
as the destination address is used. Optional source port (default is random)
can be appended to the address using \fB@\fP separator.
797
.sp
798
\fIDefault:\fP not set
799 800
.SS key
.sp
Daniel Salzman's avatar
Daniel Salzman committed
801
A \fI\%reference\fP to the TSIG key which is used to authenticate
802 803
the communication with the remote server.
.sp
804
\fIDefault:\fP not set
805 806
.SH TEMPLATE SECTION
.sp
807 808
A template is a shareable zone setting which can be used for configuration of
many zones in one place. A special default template (with the \fIdefault\fP identifier)
809
can be used for global querying configuration or as an implicit configuration
810
if a zone doesn\(aqt have another template specified.
811 812 813 814 815 816 817
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
template:
  \- id: STR
818
    timer\-db: STR
819
    max\-timer\-db\-size: SIZE
Daniel Salzman's avatar
Daniel Salzman committed
820
    journal\-db: STR
821
    journal\-db\-mode: robust | asynchronous
Daniel Salzman's avatar
Daniel Salzman committed
822
    max\-journal\-db\-size: SIZE
823 824
    kasp\-db: STR
    max\-kasp\-db\-size: SIZE
825
    global\-module: STR/STR ...
826 827 828 829 830 831 832 833
    # All zone options (excluding \(aqtemplate\(aq item)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A template identifier.
834 835 836 837 838
.SS timer\-db
.sp
Specifies a path of the persistent timer database. The path can be specified
as a relative path to the \fIdefault\fP template \fI\%storage\fP\&.
.sp
839 840 841 842 843 844
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
845 846
.sp
\fIDefault:\fP \fI\%storage\fP/timers
847 848 849 850 851 852 853 854 855 856 857 858
.SS max\-timer\-db\-size
.sp
Hard limit for the timer database maximum size.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP 100 MiB
859 860 861 862 863 864 865 866 867 868 869 870 871
.SS journal\-db
.sp
Specifies a path of the persistent journal database. The path can be specified
as a relative path to the \fIdefault\fP template \fI\%storage\fP\&.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP \fI\%storage\fP/journal
872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895
.SS journal\-db\-mode
.sp
Specifies journal LMDB backend configuration, which influences performance
and durability.
.sp
Possible values:
.INDENT 0.0
.IP \(bu 2
\fBrobust\fP – The journal DB disk sychronization ensures DB durability but is
generally slower
.IP \(bu 2
\fBasynchronous\fP – The journal DB disk synchronization is optimized for
better perfomance at the expense of lower DB durability; this mode is
recommended only on slave nodes with many zones
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP robust
896 897 898 899 900 901 902 903 904
.SS max\-journal\-db\-size
.sp
Hard limit for the common journal DB. There is no cleanup logic in journal
to recover from reaching this limit: journal simply starts refusing changes
across all zones. Decreasing this value has no effect if lower than actual
DB file size.
.sp
It is recommended to limit \fI\%max\-journal\-usage\fP
per\-zone instead of max\-journal\-size in most cases. Please keep this value
905 906
larger than the sum of all zones\(aq journal usage limits. See more details
regarding journal behaviour\&.
907 908
.sp
This value also influences server\(aqs usage of virtual memory.
909 910 911 912 913 914 915 916
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
.sp
917
\fIDefault:\fP 20 GiB (1 GiB for 32\-bit)
918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942
.SS kasp\-db
.sp
A KASP database path. Non\-absolute path is relative to
\fI\%storage\fP\&.
.sp
\fIDefault:\fP \fI\%storage\fP/keys
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
.SS max\-kasp\-db\-size
.sp
Hard limit for the KASP database maximum size.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP 500 MiB
943 944
.SS global\-module
.sp
945
An ordered list of references to query modules in the form of \fImodule_name\fP or
946 947
\fImodule_name/module_id\fP\&. These modules apply to all queries.
.sp
948 949 950 951 952 953
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
954
.sp
955
\fIDefault:\fP not set
956 957 958 959 960 961 962 963 964 965 966
.SH ZONE SECTION
.sp
Definition of zones served by the server.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
zone:
  \- domain: DNAME
    template: template_id
967
    storage: STR
968
    file: STR
969
    master: remote_id ...
970
    ddns\-master: remote_id
971 972 973 974 975
    notify: remote_id ...
    acl: acl_id ...
    semantic\-checks: BOOL
    disable\-any: BOOL
    zonefile\-sync: TIME
976 977
    zonefile\-load: none | difference | whole
    journal\-content: none | changes | all
978
    max\-journal\-usage: SIZE
Daniel Salzman's avatar
Daniel Salzman committed
979
    max\-journal\-depth: INT
Jan Včelák's avatar
Jan Včelák committed
980
    max\-zone\-size : SIZE
981
    dnssec\-signing: BOOL
982
    dnssec\-policy: STR
983
    request\-edns\-option: INT:[HEXSTR]
984
    serial\-policy: increment | unixtime
985 986
    min\-refresh\-interval: TIME
    max\-refresh\-interval: TIME
987 988 989 990 991
    module: STR/STR ...
.ft P
.fi
.UNINDENT
.UNINDENT
992
.SS domain
993
.sp
994 995 996
A zone name identifier.
.SS template
.sp
997
A \fI\%reference\fP to a configuration template.
998
.sp
999
\fIDefault:\fP not set or \fIdefault\fP (if the template exists)
1000 1001
.SS storage
.sp
1002
A data directory for storing zone files, journal database, and timers database.
1003 1004
.sp
\fIDefault:\fP \fB${localstatedir}/lib/knot\fP (configured with \fB\-\-with\-storage=path\fP)
1005 1006
.SS file
.sp
1007
A path to the zone file. Non\-absolute path is relative to
1008 1009 1010
\fI\%storage\fP\&. It is also possible to use the following formatters:
.INDENT 0.0
.IP \(bu 2
1011 1012 1013
\fB%c[\fP\fIN\fP\fB]\fP or \fB%c[\fP\fIN\fP\fB\-\fP\fIM\fP\fB]\fP – means the \fIN\fPth
character or a sequence of characters beginning from the \fIN\fPth and ending
with the \fIM\fPth character of the textual zone name (see \fB%s\fP). The
1014 1015
indexes are counted from 0 from the left. All dots (including the terminal
one) are considered. If the character is not available, the formatter has no effect.
1016 1017 1018 1019 1020
.IP \(bu 2
\fB%l[\fP\fIN\fP\fB]\fP – means the \fIN\fPth label of the textual zone name
(see \fB%s\fP). The index is counted from 0 from the right (0 ~ TLD).
If the label is not available, the formatter has no effect.
.IP \(bu 2
1021 1022 1023
\fB%s\fP – means the current zone name in the textual representation.
The zone name doesn\(aqt include the terminating dot (the result for the root
zone is the empty string!).
1024
.IP \(bu 2
1025
\fB%%\fP – means the \fB%\fP character
1026 1027
.UNINDENT
.sp
1028 1029 1030 1031 1032 1033 1034 1035
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Beware of special characters which are escaped or encoded in the \eDDD form
where DDD is corresponding decimal ASCII code.
.UNINDENT
.UNINDENT
.sp
1036
\fIDefault:\fP \fI\%storage\fP/\fB%s\fP\&.zone
1037 1038 1039 1040
.SS master
.sp
An ordered list of \fI\%references\fP to zone master servers.
.sp
1041
\fIDefault:\fP not set
1042 1043
.SS ddns\-master
.sp
1044
A \fI\%reference\fP to zone primary master server.
1045 1046
If not specified, the first \fI\%master\fP server is used.
.sp
1047
\fIDefault:\fP not set
1048 1049 1050 1051 1052
.SS notify
.sp
An ordered list of \fI\%references\fP to remotes to which notify
message is sent if the zone changes.
.sp
1053
\fIDefault:\fP not set
1054 1055 1056 1057 1058
.SS acl
.sp
An ordered list of \fI\%references\fP to ACL rules which can allow
or disallow zone transfers, updates or incoming notifies.
.sp
1059
\fIDefault:\fP not set
1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070
.SS semantic\-checks
.sp
If enabled, extra zone file semantic checks are turned on.
.sp
Several checks are enabled by default and cannot be turned off. An error in
mandatory checks causes zone not to be loaded. An error in extra checks is
logged only.
.sp
Mandatory checks:
.INDENT 0.0
.IP \(bu 2
1071
SOA record missing in the zone (\fI\%RFC 1034\fP)
1072
.IP \(bu 2
1073
An extra record together with CNAME record except for RRSIG and DS (\fI\%RFC 1034\fP)
1074
.IP \(bu 2
1075
Multiple CNAME record with the same owner
1076
.IP \(bu 2
1077
DNAME record having a record under it (\fI\%RFC 2672\fP)
1078 1079 1080 1081 1082 1083 1084
.UNINDENT
.sp
Extra checks:
.INDENT 0.0
.IP \(bu 2
Missing NS record at the zone apex
.IP \(bu 2
1085
Missing glue A or AAAA record
1086
.IP \(bu 2
1087
Invalid DNSKEY, DS, or NSEC3PARAM record
1088
.IP \(bu 2
1089
CDS or CDNSKEY inconsistency
1090
.IP \(bu 2
1091
Missing, invalid, or unverifiable RRSIG record
1092
.IP \(bu 2
1093
Invalid NSEC(3) record
1094
.IP \(bu 2
1095
Broken or non\-cyclic NSEC(3) chain
1096 1097
.UNINDENT
.sp
1098
\fIDefault:\fP off
1099 1100
.SS disable\-any
.sp
1101
If enabled, all authoritative ANY queries sent over UDP will be answered
1102 1103 1104
with an empty response and with the TC bit set. Use this option to minimize
the risk of DNS reflection attack.
.sp
1105
\fIDefault:\fP off
1106 1107
.SS zonefile\-sync
.sp
1108
The time after which the current zone in memory will be synced with a zone file
1109
on the disk (see \fI\%file\fP). The server will serve the latest
1110
zone even after a restart using zone journal, but the zone file on the disk will
1111
only be synced after \fBzonefile\-sync\fP time has expired (or after manual zone
1112
flush). This is applicable when the zone is updated via IXFR, DDNS or automatic
1113 1114 1115
DNSSEC signing. In order to completely disable automatic zonefile synchronization,
set the value to \-1. In that case, it is still possible to force a manual zone flush
using the \fB\-f\fP option.
1116
.sp
1117 1118 1119 1120
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you are serving large zones with frequent updates where
1121
the immediate sync with a zone file is not desirable, increase the value.
1122 1123
.UNINDENT
.UNINDENT
1124
.sp
1125
\fIDefault:\fP 0 (immediate)
1126
.SS zonefile\-load
1127
.sp
1128
Selects how the zonefile contents are applied during zone load.
1129
.sp
1130
Possible values:
1131
.INDENT 0.0
1132 1133 1134 1135 1136 1137 1138
.IP \(bu 2
\fBnone\fP – The zonefile is not used at all.
.IP \(bu 2
\fBdifference\fP – If the zone contents are available during server start or reload,
the difference is computed between them and the zonefile, checked and applied afterwards.
.IP \(bu 2
\fBwhole\fP – Zone contents are loaded from zonefile.
1139 1140
.UNINDENT
.sp
1141 1142
When \fBdifference\fP is configured and there are no zone contents yet (cold start of Knot
and no zone contents in journal), it behaves the same way like \fBwhole\fP\&.
1143
.sp
1144 1145
\fIDefault:\fP whole
.SS journal\-content
1146
.sp
1147
Selects how the journal shall be used to store zone and its changes.
1148
.sp
1149
Possible values:
1150
.INDENT 0.0
1151 1152 1153 1154 1155 1156
.IP \(bu 2
\fBnone\fP – The journal is not used at all.
.IP \(bu 2
\fBchanges\fP – Zone changes history is stored in journal.
.IP \(bu 2
\fBall\fP – Zone contents and history is stored in journal.
1157
.UNINDENT
1158
.sp
1159
\fIDefault:\fP changes
1160
.SS max\-journal\-usage
1161
.sp
1162
Policy how much space in journal DB will the zone\(aqs journal occupy.
1163
.sp
1164
\fIDefault:\fP 100 MiB
1165 1166 1167 1168
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
1169 1170
Journal DB may grow far above the sum of max\-journal\-usage across
all zones, because of DB free space fragmentation.
1171 1172
.UNINDENT
.UNINDENT
1173 1174 1175 1176
.SS max\-journal\-depth
.sp
Maximum history length of journal.
.sp
1177 1178
\fIMinimum:\fP 2
.sp
1179
\fIDefault:\fP 2^64
Jan Včelák's avatar
Jan Včelák committed
1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190
.SS max\-zone\-size
.sp
Maximum size of the zone. The size is measured as size of the zone records
in wire format without compression. The limit is enforced for incoming zone
transfers and dynamic updates.
.sp
For incremental transfers (IXFR), the effective limit for the total size of
the records in the transfer is twice the configured value. However the final
size of the zone must satisfy the configured value.
.sp
\fIDefault:\fP 2^64
1191
.SS dnssec\-signing
1192 1193 1194
.sp
If enabled, automatic DNSSEC signing for the zone is turned on.
.sp
1195 1196 1197 1198 1199 1200
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Cannot be enabled on a slave zone.
.UNINDENT
.UNINDENT
1201
.sp
1202
\fIDefault:\fP off
1203 1204
.SS dnssec\-policy
.sp
1205 1206
A \fI\%reference\fP to DNSSEC signing policy. A special \fIdefault\fP
value can be used for the default policy settings.
1207
.sp
1208
\fIRequired\fP
1209 1210 1211 1212 1213
.SS request\-edns\-option
.sp
An arbitrary EDNS0 option which is included into a server request (AXFR, IXFR,
SOA, or NOTIFY). The value is in the option_code:option_data format.
.sp
1214
\fIDefault:\fP not set
1215 1216 1217 1218 1219 1220 1221 1222 1223
.SS serial\-policy
.sp
Specifies how the zone serial is updated after a dynamic update or
automatic DNSSEC signing. If the serial is changed by the dynamic update,
no change is made.
.sp
Possible values:
.INDENT 0.0
.IP \(bu 2
1224
\fBincrement\fP – The serial is incremented according to serial number arithmetic
1225
.IP \(bu 2
1226
\fBunixtime\fP – The serial is set to the current unix time
1227 1228
.UNINDENT
.sp
1229 1230 1231 1232
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If your serial was in other than unix time format, be careful
1233 1234
with the transition to unix time.  It may happen that the new serial will
be \(aqlower\(aq than the old one. If this is the case, the transition should be
1235
done by hand (\fI\%RFC 1982\fP).
1236 1237
.UNINDENT
.UNINDENT
1238
.sp
1239
\fIDefault:\fP increment
1240 1241 1242 1243 1244 1245 1246 1247 1248 1249
.SS min\-refresh\-interval
.sp
Forced minimum zone refresh interval to avoid flooding master.
.sp
\fIDefault:\fP 2
.SS max\-refresh\-interval
.sp
Forced maximum zone refresh interval.
.sp
\fIDefault:\fP not set
1250 1251
.SS module
.sp
1252
An ordered list of references to query modules in the form of \fImodule_name\fP or
1253
\fImodule_name/module_id\fP\&. These modules apply only to the current zone queries.
1254
.sp
1255
\fIDefault:\fP not set
1256 1257 1258 1259 1260 1261
.SH LOGGING SECTION
.sp
Server can be configured to log to the standard output, standard error
output, syslog (or systemd journal if systemd is enabled) or into an arbitrary
file.
.sp
1262
There are 6 logging severity levels:
1263 1264
.INDENT 0.0
.IP \(bu 2
1265
\fBcritical\fP – Non\-recoverable error resulting in server shutdown
1266
.IP \(bu 2
1267
\fBerror\fP – Recoverable error, action should be taken
1268
.IP \(bu 2
1269
\fBwarning\fP – Warning that might require user action
1270
.IP \(bu 2
1271
\fBnotice\fP – Server notice or hint
1272
.IP \(bu 2
1273
\fBinfo\fP – Informational message
1274
.IP \(bu 2
1275
\fBdebug\fP – Debug messages (must be turned on at compile time)
1276 1277
.UNINDENT
.sp
1278
In the case of missing log section, \fBwarning\fP or more serious messages
1279 1280 1281 1282 1283 1284 1285 1286
will be logged to both standard error output and syslog. The \fBinfo\fP and
\fBnotice\fP messages will be logged to standard output.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
log:
1287
  \- target: stdout | stderr | syslog | STR
1288
    server: critical | error | warning | notice | info | debug
Daniel Salzman's avatar
Daniel Salzman committed
1289
    control: critical | error | warning | notice | info | debug
1290 1291 1292 1293 1294 1295
    zone: critical | error | warning | notice | info | debug
    any: critical | error | warning | notice | info | debug
.ft P
.fi
.UNINDENT
.UNINDENT
1296
.SS target
1297 1298 1299 1300 1301 1302
.sp
A logging output.
.sp
Possible values:
.INDENT 0.0
.IP \(bu 2
1303
\fBstdout\fP – Standard output
1304
.IP \(bu 2
1305
\fBstderr\fP – Standard error output
1306
.IP \(bu 2
1307
\fBsyslog\fP – Syslog
1308
.IP \(bu 2
1309
\fIfile_name\fP – File
1310 1311 1312 1313 1314 1315
.UNINDENT
.SS server
.sp
Minimum severity level for messages related to general operation of the server
that are logged.
.sp
1316
\fIDefault:\fP not set
Daniel Salzman's avatar
Daniel Salzman committed
1317 1318 1319 1320 1321
.SS control
.sp
Minimum severity level for messages related to server control that are logged.
.sp
\fIDefault:\fP not set
1322 1323 1324 1325
.SS zone
.sp
Minimum severity level for messages related to zones that are logged.
.sp
1326
\fIDefault:\fP not set
1327 1328 1329 1330
.SS any
.sp
Minimum severity level for all message types that are logged.
.sp
1331
\fIDefault:\fP not set
1332 1333 1334
.SH AUTHOR
CZ.NIC Labs <http://www.knot-dns.cz>
.SH COPYRIGHT
1335
Copyright 2010–2017, CZ.NIC, z.s.p.o.
1336 1337
.\" Generated by docutils manpage writer.
.