knot.conf.5in 28.7 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
Jan Včelák's avatar
Jan Včelák committed
35 36
Configuration files for Knot DNS use simplified YAML format. Simplified means
that not all of the features are supported.
37
.sp
Jan Včelák's avatar
Jan Včelák committed
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
There are 10 main sections (\fBserver\fP, \fBcontrol\fP, \fBlog\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 and \fBcontrol\fP) are sequences of settings blocks. Each settings block
73 74 75
begins with a unique identifier, which can be used as a reference from other
sections (such identifier must be defined in advance).
.sp
Daniel Salzman's avatar
Daniel Salzman committed
76 77 78 79 80 81 82 83 84 85 86 87 88
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:
Jan Včelák's avatar
Jan Včelák committed
89 90 91 92 93 94 95 96 97 98 99
.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
100 101
.sp
If an item value contains spaces or other special characters, it is necessary
Jan Včelák's avatar
Jan Včelák committed
102
to enclose such value within double quotes \fB"\fP \fB"\fP\&.
103 104
.SH COMMENTS
.sp
Jan Včelák's avatar
Jan Včelák committed
105
A comment begins with a \fB#\fP character and is ignored during processing.
106 107 108 109 110
Also each configuration section or sequence block allows to specify permanent
comment using \fBcomment\fP item which is stored in the server beside the
configuration.
.SH INCLUDES
.sp
111 112 113 114
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.
115
Matching files are processed in sorted order.
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
include: STR
.ft P
.fi
.UNINDENT
.UNINDENT
.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
141 142
    udp\-workers: INT
    tcp\-workers: INT
143
    background\-workers: INT
144
    async\-start: BOOL
145
    tcp\-handshake\-timeout: TIME
146
    tcp\-idle\-timeout: TIME
147
    tcp\-reply\-timeout: TIME
148 149 150 151
    max\-tcp\-clients: INT
    max\-udp\-payload: SIZE
    rate\-limit: INT
    rate\-limit\-slip: INT
152
    rate\-limit\-table\-size: INT
153
    rate\-limit\-whitelist: ADDR[/INT] | ADDR\-ADDR ...
154 155 156 157 158 159 160
    listen: ADDR[@INT] ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS identity
.sp
Jan Včelák's avatar
Jan Včelák committed
161
An identity of the server returned in the response to the query for TXT
162 163 164
record \fBid.server.\fP or \fBhostname.bind.\fP in the CHAOS class (see RFC 4892).
Set empty value to disable.
.sp
165
\fIDefault:\fP FQDN hostname
166 167
.SS version
.sp
Jan Včelák's avatar
Jan Včelák committed
168
A version of the server software returned in the response to the query
169 170 171
for TXT record \fBversion.server.\fP or \fBversion.bind.\fP in the CHAOS
class (see RFC 4892). Set empty value to disable.
.sp
172
\fIDefault:\fP server version
173 174 175 176
.SS nsid
.sp
A DNS name server identifier (see RFC 5001). Set empty value to disable.
.sp
177
\fIDefault:\fP FQDN hostname
178 179 180 181
.SS rundir
.sp
A path for storing run\-time data (PID file, unix sockets, etc.).
.sp
182
\fIDefault:\fP \fB${localstatedir}/run/knot\fP (configured with \fB\-\-with\-rundir=path\fP)
183 184
.SS user
.sp
185
A system user with an optional system group (\fBuser:group\fP) under which the
186 187 188
server is run after starting and binding to interfaces. Linux capabilities
are employed if supported.
.sp
189
\fIDefault:\fP root:root
190 191 192 193
.SS pidfile
.sp
A PID file location.
.sp
194
\fIDefault:\fP \fI\%rundir\fP/knot.pid
195
.SS udp\-workers
196
.sp
197 198
A number of quering UDP workers (threads).
.sp
199
\fIDefault:\fP auto\-estimated optimal value based on the number of online CPUs
200 201 202
.SS tcp\-workers
.sp
A number of quering TCP workers (threads).
203
.sp
204
\fIDefault:\fP auto\-estimated optimal value based on the number of online CPUs
205 206 207 208 209
.SS background\-workers
.sp
A number of workers (threads) used to execute background operations (zone
loading, zone updates, etc.).
.sp
210
\fIDefault:\fP auto\-estimated optimal value based on the number of online CPUs
211
.SS async\-start
212 213 214 215
.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
216
\fIDefault:\fP off
217
.SS tcp\-handshake\-timeout
218 219 220 221 222
.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
223
\fIDefault:\fP 5
224 225 226 227 228
.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
229
\fIDefault:\fP 20
230
.SS tcp\-reply\-timeout
231
.sp
232 233 234
Maximum time to wait for an outgoing connection or for a reply to an issued
request (SOA, NOTIFY, AXFR...). This limit also applies to knotc remote
operation over an internet socket.
235
.sp
236
\fIDefault:\fP 10
237 238 239 240 241
.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
242
\fIDefault:\fP 100
243 244
.SS rate\-limit
.sp
Jan Včelák's avatar
Jan Včelák committed
245 246
Rate limiting is based on the token bucket scheme. A rate basically
represents a number of tokens available each second. Each response is
247
processed and classified (based on several discriminators, e.g.
Jan Včelák's avatar
Jan Včelák committed
248
source netblock, query type, zone name, rcode, etc.). Classified responses are
249 250
then hashed and assigned to a bucket containing number of available
tokens, timestamp and metadata. When available tokens are exhausted,
Jan Včelák's avatar
Jan Včelák committed
251 252
response is dropped or sent as truncated (see \fI\%rate\-limit\-slip\fP).
Number of available tokens is recalculated each second.
253
.sp
254
\fIDefault:\fP 0 (disabled)
255
.SS rate\-limit\-table\-size
256
.sp
Jan Včelák's avatar
Jan Včelák committed
257
Size of the hash table in a number of buckets. The larger the hash table, the lesser
Jan Včelák's avatar
Jan Včelák committed
258 259 260
the probability of a hash collision, but at the expense of additional memory costs.
Each bucket is estimated roughly to 32 bytes. The size should be selected as
a reasonably large prime due to better hash function distribution properties.
261
Hash table is internally chained and works well up to a fill rate of 90 %, general
262 263
rule of thumb is to select a prime near 1.2 * maximum_qps.
.sp
264
\fIDefault:\fP 393241
265 266 267
.SS rate\-limit\-slip
.sp
As attacks using DNS/UDP are usually based on a forged source address,
Jan Včelák's avatar
Jan Včelák committed
268
an attacker could deny services to the victim\(aqs netblock if all
269
responses would be completely blocked. The idea behind SLIP mechanism
Jan Včelák's avatar
Jan Včelák committed
270
is to send each N\s-2\uth\d\s0 response as truncated, thus allowing client to
271 272
reconnect via TCP for at least some degree of service. It is worth
noting, that some responses can\(aqt be truncated (e.g. SERVFAIL).
Jan Včelák's avatar
Jan Včelák committed
273 274
.INDENT 0.0
.IP \(bu 2
Jan Včelák's avatar
Jan Včelák committed
275 276 277 278 279 280
Setting the value to \fB0\fP will cause that all rate\-limited responses will
be dropped. The outbound bandwidth and packet rate will be strictly capped
by the \fI\%rate\-limit\fP option. All legitimate requestors affected
by the limit will face denial of service and will observe excessive timeouts.
Therefore this setting is not recommended.
.IP \(bu 2
Jan Včelák's avatar
Jan Včelák committed
281 282 283 284 285 286 287 288 289 290 291
Setting the value to \fB1\fP will cause that all rate\-limited responses will
be sent as truncated. The amplification factor of the attack will be reduced,
but the outbound data bandwidth won\(aqt be lower than the incoming bandwidth.
Also the outbound packet rate will be the same as without RRL.
.IP \(bu 2
Setting the value to \fB2\fP will cause that half of the rate\-limited responses
will be dropped, the other half will be sent as truncated. With this
configuration, both outbound bandwidth and packet rate will be lower than the
inbound. On the other hand, the dropped responses enlarge the time window
for possible cache poisoning attack on the resolver.
.IP \(bu 2
Jan Včelák's avatar
Jan Včelák committed
292 293 294 295
Setting the value to anything \fBlarger than 2\fP will keep on decreasing
the outgoing rate\-limited bandwidth, packet rate, and chances to notify
legitimate requestors to reconnect using TCP. These attributes are inversely
proportional to the configured value. Setting the value high is not advisable.
Jan Včelák's avatar
Jan Včelák committed
296
.UNINDENT
297
.sp
298
\fIDefault:\fP 1
299 300 301 302 303 304 305
.SS rate\-limit\-whitelist
.sp
A list of IP addresses, network subnets, or network ranges to exempt from
rate limiting. Empty list means that no incoming connection will be
white\-listed.
.sp
\fIDefault:\fP not set
306 307 308 309
.SS max\-udp\-payload
.sp
Maximum EDNS0 UDP payload size.
.sp
310
\fIDefault:\fP 4096
311 312 313 314 315 316 317
.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
318
\fIDefault:\fP not set
319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341
.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.
.SS algorithm
.sp
A key algorithm.
.sp
342
\fIDefault:\fP not set
343 344 345 346
.SS secret
.sp
Shared key secret.
.sp
347
\fIDefault:\fP not set
348 349
.SH ACL SECTION
.sp
350 351 352
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.).
353 354 355 356 357 358 359
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
acl:
  \- id: STR
360
    address: ADDR[/INT] | ADDR\-ADDR ...
361
    key: key_id ...
Daniel Salzman's avatar
Daniel Salzman committed
362
    action: notify | transfer | update ...
363
    deny: BOOL
364 365 366 367 368 369 370 371 372
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
An ACL rule identifier.
.SS address
.sp
373 374
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.
375
.sp
376
\fIDefault:\fP not set
377 378
.SS key
.sp
379 380
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.
381
.sp
382
\fIDefault:\fP not set
383 384
.SS action
.sp
385 386
An ordered list of allowed actions. Empty action list is only allowed if
\fI\%deny\fP is set.
387 388 389 390
.sp
Possible values:
.INDENT 0.0
.IP \(bu 2
391
\fBtransfer\fP – Allow zone transfer
392
.IP \(bu 2
393
\fBnotify\fP – Allow incoming notify
394
.IP \(bu 2
395
\fBupdate\fP – Allow zone updates
396 397
.UNINDENT
.sp
398
\fIDefault:\fP not set
399 400 401 402 403
.SS deny
.sp
Deny if \fI\%address\fP, \fI\%key\fP and
\fI\%action\fP match.
.sp
404
\fIDefault:\fP off
405 406
.SH CONTROL SECTION
.sp
Daniel Salzman's avatar
Daniel Salzman committed
407
Configuration of the server control interface.
408 409 410 411 412 413
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
control:
Daniel Salzman's avatar
Daniel Salzman committed
414
    listen: STR
415
    timeout: TIME
416 417 418 419 420 421
.ft P
.fi
.UNINDENT
.UNINDENT
.SS listen
.sp
422
A UNIX socket path where the server listens for control commands.
423
.sp
424
\fIDefault:\fP \fI\%rundir\fP/knot.sock
425 426 427 428 429
.SS timeout
.sp
Maximum time the control socket operations can take. Set 0 for infinity.
.sp
\fIDefault:\fP 5
430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450
.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
451
A key storage backend type. A directory with PEM files or a PKCS #11 storage.
452 453 454 455
.sp
\fIDefault:\fP pem
.SS config
.sp
456
A backend specific configuration. A directory with PEM files (the path can
457
be specified as a relative path to \fI\%kasp\-db\fP) or
Jan Včelák's avatar
Jan Včelák committed
458
a configuration string for PKCS #11 storage.
459 460 461 462
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Jan Včelák's avatar
Jan Včelák committed
463
Example configuration string for PKCS #11:
464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
"pkcs11:token=knot;pin\-value=1234 libsofthsm2.so"
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP \fI\%kasp\-db\fP/keys
.SH POLICY SECTION
.sp
DNSSEC policy configuration.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
policy:
  \- id: STR
    keystore: STR
    manual: BOOL
    algorithm: dsa | rsasha1 | dsansec3sha1 | rsasha1nsec3sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384
    ksk\-size: SIZE
    zsk\-size: SIZE
    dnskey\-ttl: TIME
    zsk\-lifetime: TIME
    rrsig\-lifetime: TIME
    rrsig\-refresh: TIME
    nsec3: BOOL
    nsec3\-iterations: INT
    nsec3\-salt\-length: INT
    nsec3\-resalt: TIME
    propagation\-delay: TIME
.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
for zones.
.sp
\fIDefault:\fP default
.SS manual
.sp
If enabled, automatic key management is not used.
.sp
\fIDefault:\fP off
.SS algorithm
.sp
An algorithm of signing keys and issued signatures.
.sp
\fIDefault:\fP ECDSA\-P256\-SHA256
.SS ksk\-size
.sp
A length of newly generated KSK keys.
.sp
\fIDefault:\fP 256 (algorithm dependent)
.SS zsk\-size
.sp
A length of newly generated ZSK keys.
.sp
\fIDefault:\fP 256 (algorithm dependent)
.SS dnskey\-ttl
.sp
A TTL value for DNSKEY records added into zone apex.
.sp
\fIDefault:\fP zone SOA TTL
.SS zsk\-lifetime
.sp
A period between ZSK publication and the next rollover initiation.
.sp
\fIDefault:\fP 30 days
.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
.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
.SS nsec3\-resalt
.sp
A validity period of newly issued salt field.
.sp
\fIDefault:\fP 30 days
.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
582 583
.SH REMOTE SECTION
.sp
584 585
Definitions of remote servers for outgoing connections (source of a zone
transfer, target for a notification, etc.).
586 587 588 589 590 591 592
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
remote:
  \- id: STR
593 594
    address: ADDR[@INT] ...
    via: ADDR[@INT] ...
595 596 597 598 599 600 601 602 603 604
    key: key_id
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A remote identifier.
.SS address
.sp
605 606 607 608
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.
609
.sp
610
\fIDefault:\fP not set
611 612
.SS via
.sp
613 614 615
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.
616
.sp
617
\fIDefault:\fP not set
618 619 620 621 622
.SS key
.sp
A \fI\%reference\fP to the TSIG key which ise used to autenticate
the communication with the remote server.
.sp
623
\fIDefault:\fP not set
624 625
.SH TEMPLATE SECTION
.sp
Jan Včelák's avatar
Jan Včelák committed
626 627
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)
Daniel Salzman's avatar
Daniel Salzman committed
628
can be used for global querying configuration or as an implicit configuration
Jan Včelák's avatar
Jan Včelák committed
629
if a zone doesn\(aqt have another template specified.
630 631 632 633 634 635 636
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
template:
  \- id: STR
637
    timer\-db: STR
Daniel Salzman's avatar
Daniel Salzman committed
638
    global\-module: STR/STR ...
639 640 641 642 643 644 645 646
    # All zone options (excluding \(aqtemplate\(aq item)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A template identifier.
647 648 649 650 651
.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
652 653 654 655 656 657
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
658 659
.sp
\fIDefault:\fP \fI\%storage\fP/timers
Daniel Salzman's avatar
Daniel Salzman committed
660 661 662 663 664
.SS global\-module
.sp
An ordered list of references to query modules in the form
\fImodule_name/module_id\fP\&. These modules apply to all queries.
.sp
665 666 667 668 669 670
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
Daniel Salzman's avatar
Daniel Salzman committed
671
.sp
672
\fIDefault:\fP not set
673 674 675 676 677 678 679 680 681 682 683 684
.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
    file: STR
685 686
    storage: STR
    master: remote_id ...
687
    ddns\-master: remote_id
688 689 690 691 692 693
    notify: remote_id ...
    acl: acl_id ...
    semantic\-checks: BOOL
    disable\-any: BOOL
    zonefile\-sync: TIME
    ixfr\-from\-differences: BOOL
694 695
    max\-journal\-size: SIZE
    dnssec\-signing: BOOL
696
    dnssec\-policy: STR
697
    kasp\-db: STR
698
    request\-edns\-option: INT:[HEXSTR]
699 700 701 702 703 704
    serial\-policy: increment | unixtime
    module: STR/STR ...
.ft P
.fi
.UNINDENT
.UNINDENT
705
.SS domain
706
.sp
707 708 709
A zone name identifier.
.SS template
.sp
710
A \fI\%reference\fP to a configuration template.
711
.sp
712
\fIDefault:\fP not set or \fIdefault\fP (if the template exists)
713 714 715 716 717 718
.SS file
.sp
A path to the zone file. Non absolute path is relative to
\fI\%storage\fP\&. It is also possible to use the following formatters:
.INDENT 0.0
.IP \(bu 2
719 720 721 722 723 724 725 726 727 728
\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
indexes are counted from 0 from the left. If the character is not available,
the formatter has no effect.
.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
729
\fB%s\fP – means the current zone name in the textual representation (beware
730 731
of special characters which are escaped or encoded in the \eDDD form where
DDD is corresponding decimal ASCII code). The zone name doesn\(aqt include the
732
terminating dot (the result for the root zone is the empty string!).
733
.IP \(bu 2
734
\fB%%\fP – means the \fB%\fP character
735 736
.UNINDENT
.sp
737
\fIDefault:\fP \fI\%storage\fP/\fB%s\fP\&.zone
738 739 740 741
.SS storage
.sp
A data directory for storing zone files, journal files and timers database.
.sp
742
\fIDefault:\fP \fB${localstatedir}/lib/knot\fP (configured with \fB\-\-with\-storage=path\fP)
743 744 745 746
.SS master
.sp
An ordered list of \fI\%references\fP to zone master servers.
.sp
747
\fIDefault:\fP not set
748 749
.SS ddns\-master
.sp
Jan Včelák's avatar
Jan Včelák committed
750
A \fI\%reference\fP to zone primary master server.
751 752
If not specified, the first \fI\%master\fP server is used.
.sp
753
\fIDefault:\fP not set
754 755 756 757 758
.SS notify
.sp
An ordered list of \fI\%references\fP to remotes to which notify
message is sent if the zone changes.
.sp
759
\fIDefault:\fP not set
760 761 762 763 764
.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
765
\fIDefault:\fP not set
766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798
.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
An extra record together with CNAME record (except for RRSIG and DS)
.IP \(bu 2
SOA record missing in the zone (RFC 1034)
.IP \(bu 2
DNAME records having records under it (DNAME children) (RFC 2672)
.UNINDENT
.sp
Extra checks:
.INDENT 0.0
.IP \(bu 2
Missing NS record at the zone apex
.IP \(bu 2
Missing glue A or AAAA records
.IP \(bu 2
Broken or non\-cyclic NSEC(3) chain
.IP \(bu 2
Wrong NSEC(3) type bitmap
.IP \(bu 2
Multiple NSEC records at the same node
.IP \(bu 2
Missing NSEC records at authoritative nodes
.IP \(bu 2
799
NSEC3 insecure delegation that is not part of Opt\-out span
800 801 802 803 804 805 806 807 808 809 810 811
.IP \(bu 2
Wrong original TTL value in NSEC3 records
.IP \(bu 2
Wrong RDATA TTL value in RRSIG record
.IP \(bu 2
Signer name in RRSIG RR not the same as in DNSKEY
.IP \(bu 2
Signed RRSIG
.IP \(bu 2
Wrong key flags or wrong key in RRSIG record (not the same as ZSK)
.UNINDENT
.sp
812
\fIDefault:\fP off
813 814
.SS disable\-any
.sp
Jan Včelák's avatar
Jan Včelák committed
815
If enabled, all authoritative ANY queries sent over UDP will be answered
816 817 818
with an empty response and with the TC bit set. Use this option to minimize
the risk of DNS reflection attack.
.sp
819
\fIDefault:\fP off
820 821
.SS zonefile\-sync
.sp
Jan Včelák's avatar
Jan Včelák committed
822
The time after which the current zone in memory will be synced with a zone file
823
on the disk (see \fI\%file\fP). The server will serve the latest
Jan Včelák's avatar
Jan Včelák committed
824
zone even after a restart using zone journal, but the zone file on the disk will
825
only be synced after \fBzonefile\-sync\fP time has expired (or after manual zone
Jan Včelák's avatar
Jan Včelák committed
826
flush). This is applicable when the zone is updated via IXFR, DDNS or automatic
827
DNSSEC signing. In order to disable automatic zonefile synchronization, \-1 value
828
can be used (manual zone flush is still possible).
829
.sp
830 831 832 833
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you are serving large zones with frequent updates where
Jan Včelák's avatar
Jan Včelák committed
834
the immediate sync with a zone file is not desirable, increase the value.
835 836
.UNINDENT
.UNINDENT
837
.sp
838
\fIDefault:\fP 0 (immediate)
839 840 841
.SS ixfr\-from\-differences
.sp
If enabled, the server creates zone differences from changes you made to the
Jan Včelák's avatar
Jan Včelák committed
842
zone file upon server reload. This option is relevant only if the server
843 844
is a master server for the zone.
.sp
845 846 847 848
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option has no effect with enabled
849
\fI\%dnssec\-signing\fP\&.
850 851
.UNINDENT
.UNINDENT
852
.sp
853
\fIDefault:\fP off
854
.SS max\-journal\-size
855
.sp
856
Maximum size of the zone journal file.
857
.sp
858
\fIDefault:\fP 2^64
859
.SS dnssec\-signing
860 861 862
.sp
If enabled, automatic DNSSEC signing for the zone is turned on.
.sp
863 864 865 866 867 868
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Cannot be enabled on a slave zone.
.UNINDENT
.UNINDENT
869
.sp
870
\fIDefault:\fP off
871 872 873 874 875
.SS dnssec\-policy
.sp
A \fI\%reference\fP to DNSSEC signing policy.
.sp
\fIDefault:\fP default
876
.SS kasp\-db
877
.sp
878 879
A KASP database path. Non absolute path is relative to
\fI\%storage\fP\&.
880
.sp
881
\fIDefault:\fP \fI\%storage\fP/keys
882 883 884 885 886
.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
887
\fIDefault:\fP not set
888 889 890 891 892 893 894 895 896
.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
897
\fBincrement\fP – The serial is incremented according to serial number arithmetic
898
.IP \(bu 2
899
\fBunixtime\fP – The serial is set to the current unix time
900 901
.UNINDENT
.sp
902 903 904 905
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If your serial was in other than unix time format, be careful
906 907 908
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
done by hand (see RFC 1982).
909 910
.UNINDENT
.UNINDENT
911
.sp
912
\fIDefault:\fP increment
913 914 915
.SS module
.sp
An ordered list of references to query modules in the form
Daniel Salzman's avatar
Daniel Salzman committed
916
\fImodule_name/module_id\fP\&. These modules apply only to the current zone queries.
917
.sp
918
\fIDefault:\fP not set
919 920 921 922 923 924
.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
Jan Včelák's avatar
Jan Včelák committed
925
There are 6 logging severity levels:
926 927
.INDENT 0.0
.IP \(bu 2
928
\fBcritical\fP – Non\-recoverable error resulting in server shutdown
929
.IP \(bu 2
930
\fBerror\fP – Recoverable error, action should be taken
931
.IP \(bu 2
932
\fBwarning\fP – Warning that might require user action
933
.IP \(bu 2
934
\fBnotice\fP – Server notice or hint
935
.IP \(bu 2
936
\fBinfo\fP – Informational message
937
.IP \(bu 2
938
\fBdebug\fP – Debug messages (must be turned on at compile time)
939 940
.UNINDENT
.sp
Jan Včelák's avatar
Jan Včelák committed
941
In the case of missing log section, \fBwarning\fP or more serious messages
942 943 944 945 946 947 948 949
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:
950
  \- target: stdout | stderr | syslog | STR
951 952 953 954 955 956 957
    server: critical | error | warning | notice | info | debug
    zone: critical | error | warning | notice | info | debug
    any: critical | error | warning | notice | info | debug
.ft P
.fi
.UNINDENT
.UNINDENT
958
.SS target
959 960 961 962 963 964
.sp
A logging output.
.sp
Possible values:
.INDENT 0.0
.IP \(bu 2
965
\fBstdout\fP – Standard output
966
.IP \(bu 2
967
\fBstderr\fP – Standard error output
968
.IP \(bu 2
969
\fBsyslog\fP – Syslog
970
.IP \(bu 2
971
\fIfile_name\fP – File
972 973 974 975 976 977
.UNINDENT
.SS server
.sp
Minimum severity level for messages related to general operation of the server
that are logged.
.sp
978
\fIDefault:\fP not set
979 980 981 982
.SS zone
.sp
Minimum severity level for messages related to zones that are logged.
.sp
983
\fIDefault:\fP not set
984 985 986 987
.SS any
.sp
Minimum severity level for all message types that are logged.
.sp
988
\fIDefault:\fP not set
989 990
.SH MODULE DNSTAP
.sp
Jan Včelák's avatar
Jan Včelák committed
991
The module dnstap allows query and response logging.
992 993 994 995 996 997 998 999 1000 1001 1002
.sp
For all queries logging, use this module in the \fIdefault\fP template. For
zone\-specific logging, use this module in the proper zone configuration.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-dnstap:
  \- id: STR
    sink: STR
1003 1004
    identity: STR
    version: STR
1005 1006 1007 1008 1009 1010 1011 1012 1013
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS sink
.sp
Jan Včelák's avatar
Jan Včelák committed
1014
A sink path, which can be either a file or a UNIX socket when prefixed with
1015 1016
\fBunix:\fP\&.
.sp
1017
\fIRequired\fP
1018 1019 1020 1021 1022 1023 1024 1025 1026 1027
.SS identity
.sp
A DNS server identity. Set empty value to disable.
.sp
\fIDefault:\fP FQDN hostname
.SS version
.sp
A DNS server version. Set empty value to disable.
.sp
\fIDefault:\fP server version
1028 1029
.SH MODULE SYNTH-RECORD
.sp
Jan Včelák's avatar
Jan Včelák committed
1030
This module is able to synthesize either forward or reverse records for the
1031 1032 1033 1034 1035 1036 1037 1038 1039 1040
given prefix and subnet.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-synth\-record:
  \- id: STR
    type: forward | reverse
    prefix: STR
1041
    origin: DNAME
1042
    ttl: INT
1043
    network: ADDR[/INT] | ADDR\-ADDR
1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS type
.sp
The type of generated records.
.sp
Possible values:
.INDENT 0.0
.IP \(bu 2
1058
\fBforward\fP – Forward records
1059
.IP \(bu 2
1060
\fBreverse\fP – Reverse records
1061 1062
.UNINDENT
.sp
1063
\fIRequired\fP
1064 1065 1066 1067
.SS prefix
.sp
A record owner prefix.
.sp
1068 1069 1070 1071
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The value doesn’t allow dots, address parts in the synthetic names are
1072
separated with a dash.
1073 1074
.UNINDENT
.UNINDENT
1075
.sp
1076
\fIDefault:\fP empty
1077
.SS origin
1078
.sp
Jan Včelák's avatar
Jan Včelák committed
1079
A zone origin (only valid for the \fI\%reverse type\fP).
1080
.sp
1081
\fIRequired\fP
1082 1083 1084 1085
.SS ttl
.sp
Time to live of the generated records.
.sp
1086
\fIDefault:\fP 3600
1087
.SS network
1088
.sp
1089
An IP address, a network subnet, or a network range the query must match.
1090
.sp
1091
\fIRequired\fP
1092 1093
.SH MODULE DNSPROXY
.sp
Jan Včelák's avatar
Jan Včelák committed
1094
The module catches all unsatisfied queries and forwards them to the indicated
1095 1096 1097 1098 1099 1100 1101 1102
server for resolution.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-dnsproxy:
  \- id: STR
1103 1104
    remote: remote_id
    catch\-nxdomain: BOOL
1105 1106 1107 1108 1109 1110 1111 1112 1113
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS remote
.sp
1114 1115
A \fI\%reference\fP to a remote server where the queries are
forwarded to.
1116
.sp
1117
\fIRequired\fP
1118 1119 1120 1121 1122
.SS catch\-nxdomain
.sp
If enabled, all unsatisfied queries (also applies to local zone lookups)
are forwarded.
.sp
1123
\fIDefault:\fP off
1124 1125 1126
.SH MODULE ROSEDB
.sp
The module provides a mean to override responses for certain queries before
Jan Včelák's avatar
Jan Včelák committed
1127
the available zones are searched for the record.
1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-rosedb:
  \- id: STR
    dbdir: STR
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS dbdir
.sp
A path to the directory where the database is stored.
.sp
1147
\fIRequired\fP
Jan Včelák's avatar
Jan Včelák committed
1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161
.SH MODULE ONLINE-SIGN
.sp
The module provides online DNSSEC signing.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-online\-sign:
  \- id: STR
.ft P
.fi
.UNINDENT
.UNINDENT
1162 1163 1164
.SS id
.sp
A module identifier.
1165 1166 1167
.SH AUTHOR
CZ.NIC Labs <http://www.knot-dns.cz>
.SH COPYRIGHT
Jan Včelák's avatar
Jan Včelák committed
1168
Copyright 2010–2016, CZ.NIC, z.s.p.o.
1169 1170
.\" Generated by docutils manpage writer.
.