knot.conf.5in 38.6 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 74 75
There are 11 main sections (\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,
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 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141
.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
142 143
    udp\-workers: INT
    tcp\-workers: INT
144
    background\-workers: INT
145
    async\-start: BOOL
146
    tcp\-handshake\-timeout: TIME
147
    tcp\-idle\-timeout: TIME
148
    tcp\-reply\-timeout: TIME
149 150
    max\-tcp\-clients: INT
    max\-udp\-payload: SIZE
151 152
    max\-ipv4\-udp\-payload: SIZE
    max\-ipv6\-udp\-payload: SIZE
153 154 155 156 157 158 159
    listen: ADDR[@INT] ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS identity
.sp
160
An identity of the server returned in the response to the query for TXT
161 162 163
record \fBid.server.\fP or \fBhostname.bind.\fP in the CHAOS class (see RFC 4892).
Set empty value to disable.
.sp
164
\fIDefault:\fP FQDN hostname
165 166
.SS version
.sp
167
A version of the server software returned in the response to the query
168 169 170
for TXT record \fBversion.server.\fP or \fBversion.bind.\fP in the CHAOS
class (see RFC 4892). Set empty value to disable.
.sp
171
\fIDefault:\fP server version
172 173 174 175
.SS nsid
.sp
A DNS name server identifier (see RFC 5001). Set empty value to disable.
.sp
176
\fIDefault:\fP FQDN hostname
177 178 179 180
.SS rundir
.sp
A path for storing run\-time data (PID file, unix sockets, etc.).
.sp
181
\fIDefault:\fP \fB${localstatedir}/run/knot\fP (configured with \fB\-\-with\-rundir=path\fP)
182 183
.SS user
.sp
184
A system user with an optional system group (\fBuser:group\fP) under which the
185 186 187
server is run after starting and binding to interfaces. Linux capabilities
are employed if supported.
.sp
188
\fIDefault:\fP root:root
189 190 191 192
.SS pidfile
.sp
A PID file location.
.sp
193
\fIDefault:\fP \fI\%rundir\fP/knot.pid
194
.SS udp\-workers
195
.sp
196 197
A number of UDP workers (threads) used to process incoming queries
over UDP.
198
.sp
199
\fIDefault:\fP auto\-estimated optimal value based on the number of online CPUs
200 201
.SS tcp\-workers
.sp
202 203
A number of TCP workers (threads) used to process incoming queries
over TCP.
204
.sp
205
\fIDefault:\fP auto\-estimated optimal value based on the number of online CPUs
206 207 208 209 210
.SS background\-workers
.sp
A number of workers (threads) used to execute background operations (zone
loading, zone updates, etc.).
.sp
211
\fIDefault:\fP auto\-estimated optimal value based on the number of online CPUs
212
.SS async\-start
213 214 215 216
.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
217
\fIDefault:\fP off
218
.SS tcp\-handshake\-timeout
219 220 221 222 223
.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
224
\fIDefault:\fP 5
225 226 227 228 229
.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
230
\fIDefault:\fP 20
231
.SS tcp\-reply\-timeout
232
.sp
233
Maximum time to wait for an outgoing connection or for a reply to an issued
234
request (SOA, NOTIFY, AXFR...).
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 max\-udp\-payload
.sp
245 246 247 248 249 250 251 252 253 254 255
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.
256
.sp
257
\fIDefault:\fP 4096
258 259 260 261 262 263 264
.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
265
\fIDefault:\fP not set
266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288
.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
289
\fIDefault:\fP not set
290 291 292 293
.SS secret
.sp
Shared key secret.
.sp
294
\fIDefault:\fP not set
295 296
.SH ACL SECTION
.sp
297 298 299
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.).
300 301 302 303 304 305 306
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
acl:
  \- id: STR
307
    address: ADDR[/INT] | ADDR\-ADDR ...
308
    key: key_id ...
309
    action: notify | transfer | update ...
310
    deny: BOOL
311 312 313 314 315 316 317 318 319
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
An ACL rule identifier.
.SS address
.sp
320 321
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.
322
.sp
323
\fIDefault:\fP not set
324 325
.SS key
.sp
326 327
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.
328
.sp
329
\fIDefault:\fP not set
330 331
.SS action
.sp
332
An ordered list of allowed (or denied) actions.
333 334 335 336
.sp
Possible values:
.INDENT 0.0
.IP \(bu 2
337
\fBtransfer\fP – Allow zone transfer
338
.IP \(bu 2
339
\fBnotify\fP – Allow incoming notify
340
.IP \(bu 2
341
\fBupdate\fP – Allow zone updates
342 343
.UNINDENT
.sp
344
\fIDefault:\fP not set
345 346
.SS deny
.sp
347 348 349
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.
350
.sp
351
\fIDefault:\fP off
352 353
.SH CONTROL SECTION
.sp
354
Configuration of the server control interface.
355 356 357 358 359 360
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
control:
361
    listen: STR
362
    timeout: TIME
363 364 365 366 367 368
.ft P
.fi
.UNINDENT
.UNINDENT
.SS listen
.sp
369
A UNIX socket path where the server listens for control commands.
370
.sp
371
\fIDefault:\fP \fI\%rundir\fP/knot.sock
372 373 374 375 376
.SS timeout
.sp
Maximum time the control socket operations can take. Set 0 for infinity.
.sp
\fIDefault:\fP 5
377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409
.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
410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430
.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
431
A key storage backend type. A directory with PEM files or a PKCS #11 storage.
432 433 434 435
.sp
\fIDefault:\fP pem
.SS config
.sp
436
A backend specific configuration. A directory with PEM files (the path can
437
be specified as a relative path to \fI\%kasp\-db\fP) or
Jan Včelák's avatar
Jan Včelák committed
438
a configuration string for PKCS #11 storage.
439 440 441 442
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Jan Včelák's avatar
Jan Včelák committed
443
Example configuration string for PKCS #11:
444 445 446 447 448
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
449
"pkcs11:token=knot;pin\-value=1234 /usr/lib64/pkcs11/libsofthsm2.so"
450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469
.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
470
    single\-type\-signing: BOOL
471
    algorithm: dsa | rsasha1 | dsa\-nsec3\-sha1 | rsasha1\-nsec3\-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384
472 473 474 475
    ksk\-size: SIZE
    zsk\-size: SIZE
    dnskey\-ttl: TIME
    zsk\-lifetime: TIME
476
    propagation\-delay: TIME
477 478 479 480 481
    rrsig\-lifetime: TIME
    rrsig\-refresh: TIME
    nsec3: BOOL
    nsec3\-iterations: INT
    nsec3\-salt\-length: INT
482
    nsec3\-salt\-lifetime: TIME
483 484 485 486 487 488 489 490 491 492
.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
493
for zones. A special \fIdefault\fP value can be used for the default keystore settings.
494 495 496 497 498 499 500
.sp
\fIDefault:\fP default
.SS manual
.sp
If enabled, automatic key management is not used.
.sp
\fIDefault:\fP off
501 502 503 504 505 506 507 508 509 510 511 512 513 514
.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
515 516 517 518
.SS algorithm
.sp
An algorithm of signing keys and issued signatures.
.sp
519
\fIDefault:\fP ecdsap256sha256
520 521 522 523
.SS ksk\-size
.sp
A length of newly generated KSK keys.
.sp
524
\fIDefault:\fP 1024 (dsa*), 2048 (rsa*), 256 (ecdsap256*), 384 (ecdsap384*)
525 526 527 528
.SS zsk\-size
.sp
A length of newly generated ZSK keys.
.sp
529
\fIDefault:\fP see default for \fI\%ksk\-size\fP
530 531 532 533 534
.SS dnskey\-ttl
.sp
A TTL value for DNSKEY records added into zone apex.
.sp
\fIDefault:\fP zone SOA TTL
535 536 537 538 539 540 541
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
has infuence over ZSK key lifetime
.UNINDENT
.UNINDENT
542 543 544 545 546
.SS zsk\-lifetime
.sp
A period between ZSK publication and the next rollover initiation.
.sp
\fIDefault:\fP 30 days
547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
ZSK key lifetime is also infuenced by propagation\-delay and dnskey\-ttl
.UNINDENT
.UNINDENT
.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
567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592
.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
593
.SS nsec3\-salt\-lifetime
594 595 596 597
.sp
A validity period of newly issued salt field.
.sp
\fIDefault:\fP 30 days
598 599
.SH REMOTE SECTION
.sp
600 601
Definitions of remote servers for outgoing connections (source of a zone
transfer, target for a notification, etc.).
602 603 604 605 606 607 608
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
remote:
  \- id: STR
609 610
    address: ADDR[@INT] ...
    via: ADDR[@INT] ...
611 612 613 614 615 616 617 618 619 620
    key: key_id
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A remote identifier.
.SS address
.sp
621 622 623 624
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.
625
.sp
626
\fIDefault:\fP not set
627 628
.SS via
.sp
629 630 631
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.
632
.sp
633
\fIDefault:\fP not set
634 635
.SS key
.sp
Daniel Salzman's avatar
Daniel Salzman committed
636
A \fI\%reference\fP to the TSIG key which is used to authenticate
637 638
the communication with the remote server.
.sp
639
\fIDefault:\fP not set
640 641
.SH TEMPLATE SECTION
.sp
642 643
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)
644
can be used for global querying configuration or as an implicit configuration
645
if a zone doesn\(aqt have another template specified.
646 647 648 649 650 651 652
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
template:
  \- id: STR
653
    timer\-db: STR
Daniel Salzman's avatar
Daniel Salzman committed
654
    journal\-db: STR
655
    journal\-db\-mode: robust | asynchronous
Daniel Salzman's avatar
Daniel Salzman committed
656
    max\-journal\-db\-size: SIZE
657
    global\-module: STR/STR ...
658 659 660 661 662 663 664 665
    # All zone options (excluding \(aqtemplate\(aq item)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A template identifier.
666 667 668 669 670
.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
671 672 673 674 675 676
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
677 678
.sp
\fIDefault:\fP \fI\%storage\fP/timers
679 680 681 682 683 684 685 686 687 688 689 690 691
.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
692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715
.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
716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733
.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
large enough. This value also influences server\(aqs usage of virtual memory.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
.sp
734
\fIDefault:\fP 20 GiB (1 GiB for 32\-bit)
735 736
.SS global\-module
.sp
737
An ordered list of references to query modules in the form of \fImodule_name\fP or
738 739
\fImodule_name/module_id\fP\&. These modules apply to all queries.
.sp
740 741 742 743 744 745
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option is only available in the \fIdefault\fP template.
.UNINDENT
.UNINDENT
746
.sp
747
\fIDefault:\fP not set
748 749 750 751 752 753 754 755 756 757 758
.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
759
    storage: STR
760
    file: STR
761
    master: remote_id ...
762
    ddns\-master: remote_id
763 764 765 766 767 768
    notify: remote_id ...
    acl: acl_id ...
    semantic\-checks: BOOL
    disable\-any: BOOL
    zonefile\-sync: TIME
    ixfr\-from\-differences: BOOL
769
    max\-journal\-usage: SIZE
Daniel Salzman's avatar
Daniel Salzman committed
770
    max\-journal\-depth: INT
Jan Včelák's avatar
Jan Včelák committed
771
    max\-zone\-size : SIZE
772
    dnssec\-signing: BOOL
773
    dnssec\-policy: STR
774
    kasp\-db: STR
775
    request\-edns\-option: INT:[HEXSTR]
776 777 778 779 780 781
    serial\-policy: increment | unixtime
    module: STR/STR ...
.ft P
.fi
.UNINDENT
.UNINDENT
782
.SS domain
783
.sp
784 785 786
A zone name identifier.
.SS template
.sp
787
A \fI\%reference\fP to a configuration template.
788
.sp
789
\fIDefault:\fP not set or \fIdefault\fP (if the template exists)
790 791
.SS storage
.sp
792
A data directory for storing zone files, journal database, and timers database.
793 794
.sp
\fIDefault:\fP \fB${localstatedir}/lib/knot\fP (configured with \fB\-\-with\-storage=path\fP)
795 796
.SS file
.sp
797
A path to the zone file. Non\-absolute path is relative to
798 799 800
\fI\%storage\fP\&. It is also possible to use the following formatters:
.INDENT 0.0
.IP \(bu 2
801 802 803
\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
804 805
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.
806 807 808 809 810
.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
811 812 813
\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!).
814
.IP \(bu 2
815
\fB%%\fP – means the \fB%\fP character
816 817
.UNINDENT
.sp
818 819 820 821 822 823 824 825
\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
826
\fIDefault:\fP \fI\%storage\fP/\fB%s\fP\&.zone
827 828 829 830
.SS master
.sp
An ordered list of \fI\%references\fP to zone master servers.
.sp
831
\fIDefault:\fP not set
832 833
.SS ddns\-master
.sp
834
A \fI\%reference\fP to zone primary master server.
835 836
If not specified, the first \fI\%master\fP server is used.
.sp
837
\fIDefault:\fP not set
838 839 840 841 842
.SS notify
.sp
An ordered list of \fI\%references\fP to remotes to which notify
message is sent if the zone changes.
.sp
843
\fIDefault:\fP not set
844 845 846 847 848
.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
849
\fIDefault:\fP not set
850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882
.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
883
NSEC3 insecure delegation that is not part of Opt\-out span
884 885 886 887 888 889 890 891 892 893 894 895
.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
896
\fIDefault:\fP off
897 898
.SS disable\-any
.sp
899
If enabled, all authoritative ANY queries sent over UDP will be answered
900 901 902
with an empty response and with the TC bit set. Use this option to minimize
the risk of DNS reflection attack.
.sp
903
\fIDefault:\fP off
904 905
.SS zonefile\-sync
.sp
906
The time after which the current zone in memory will be synced with a zone file
907
on the disk (see \fI\%file\fP). The server will serve the latest
908
zone even after a restart using zone journal, but the zone file on the disk will
909
only be synced after \fBzonefile\-sync\fP time has expired (or after manual zone
910
flush). This is applicable when the zone is updated via IXFR, DDNS or automatic
911
DNSSEC signing. In order to disable automatic zonefile synchronization, \-1 value
912
can be used (manual zone flush is still possible).
913
.sp
914 915 916 917
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you are serving large zones with frequent updates where
918
the immediate sync with a zone file is not desirable, increase the value.
919 920
.UNINDENT
.UNINDENT
921
.sp
922 923 924
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
925 926 927
If the zone file is not up\-to\-date, the zone should be flushed before its
zone file editation or the SOA record must be untouched after editation.
Otherwise the journal can\(aqt be applied.
928 929 930
.UNINDENT
.UNINDENT
.sp
931
\fIDefault:\fP 0 (immediate)
932 933 934
.SS ixfr\-from\-differences
.sp
If enabled, the server creates zone differences from changes you made to the
935
zone file upon server reload. This option is relevant only if the server
936 937
is a master server for the zone.
.sp
938 939 940 941
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This option has no effect with enabled
942
\fI\%dnssec\-signing\fP\&.
943 944
.UNINDENT
.UNINDENT
945
.sp
946
\fIDefault:\fP off
947
.SS max\-journal\-usage
948
.sp
949
Policy how much space in journal DB will the zone\(aqs journal occupy.
950
.sp
951
\fIDefault:\fP 100 MiB
952 953 954 955
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
956 957
Journal DB may grow far above the sum of max\-journal\-usage across
all zones, because of DB free space fragmentation.
958 959
.UNINDENT
.UNINDENT
960 961 962 963 964
.SS max\-journal\-depth
.sp
Maximum history length of journal.
.sp
\fIDefault:\fP 2^64
Jan Včelák's avatar
Jan Včelák committed
965 966 967 968 969 970 971 972 973 974 975
.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
976
.SS dnssec\-signing
977 978 979
.sp
If enabled, automatic DNSSEC signing for the zone is turned on.
.sp
980 981 982 983 984 985
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Cannot be enabled on a slave zone.
.UNINDENT
.UNINDENT
986
.sp
987
\fIDefault:\fP off
988 989
.SS dnssec\-policy
.sp
990 991
A \fI\%reference\fP to DNSSEC signing policy. A special \fIdefault\fP
value can be used for the default policy settings.
992
.sp
993
\fIRequired\fP
994
.SS kasp\-db
995
.sp
996
A KASP database path. Non\-absolute path is relative to
997
\fI\%storage\fP\&.
998
.sp
999
\fIDefault:\fP \fI\%storage\fP/keys
1000 1001 1002 1003 1004
.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
1005
\fIDefault:\fP not set
1006 1007 1008 1009 1010 1011 1012 1013 1014
.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
1015
\fBincrement\fP – The serial is incremented according to serial number arithmetic
1016
.IP \(bu 2
1017
\fBunixtime\fP – The serial is set to the current unix time
1018 1019
.UNINDENT
.sp
1020 1021 1022 1023
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If your serial was in other than unix time format, be careful
1024 1025 1026
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).
1027 1028
.UNINDENT
.UNINDENT
1029
.sp
1030
\fIDefault:\fP increment
1031 1032
.SS module
.sp
1033
An ordered list of references to query modules in the form of \fImodule_name\fP or
1034
\fImodule_name/module_id\fP\&. These modules apply only to the current zone queries.
1035
.sp
1036
\fIDefault:\fP not set
1037 1038 1039 1040 1041 1042
.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
1043
There are 6 logging severity levels:
1044 1045
.INDENT 0.0
.IP \(bu 2
1046
\fBcritical\fP – Non\-recoverable error resulting in server shutdown
1047
.IP \(bu 2
1048
\fBerror\fP – Recoverable error, action should be taken
1049
.IP \(bu 2
1050
\fBwarning\fP – Warning that might require user action
1051
.IP \(bu 2
1052
\fBnotice\fP – Server notice or hint
1053
.IP \(bu 2
1054
\fBinfo\fP – Informational message
1055
.IP \(bu 2
1056
\fBdebug\fP – Debug messages (must be turned on at compile time)
1057 1058
.UNINDENT
.sp
1059
In the case of missing log section, \fBwarning\fP or more serious messages
1060 1061 1062 1063 1064 1065 1066 1067
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:
1068
  \- target: stdout | stderr | syslog | STR
1069
    server: critical | error | warning | notice | info | debug
Daniel Salzman's avatar
Daniel Salzman committed
1070
    control: critical | error | warning | notice | info | debug
1071 1072 1073 1074 1075 1076
    zone: critical | error | warning | notice | info | debug
    any: critical | error | warning | notice | info | debug
.ft P
.fi
.UNINDENT
.UNINDENT
1077
.SS target
1078 1079 1080 1081 1082 1083
.sp
A logging output.
.sp
Possible values:
.INDENT 0.0
.IP \(bu 2
1084
\fBstdout\fP – Standard output
1085
.IP \(bu 2
1086
\fBstderr\fP – Standard error output
1087
.IP \(bu 2
1088
\fBsyslog\fP – Syslog
1089
.IP \(bu 2
1090
\fIfile_name\fP – File
1091 1092 1093 1094 1095 1096
.UNINDENT
.SS server
.sp
Minimum severity level for messages related to general operation of the server
that are logged.
.sp
1097
\fIDefault:\fP not set
Daniel Salzman's avatar
Daniel Salzman committed
1098 1099 1100 1101 1102
.SS control
.sp
Minimum severity level for messages related to server control that are logged.
.sp
\fIDefault:\fP not set
1103 1104 1105 1106
.SS zone
.sp
Minimum severity level for messages related to zones that are logged.
.sp
1107
\fIDefault:\fP not set
1108 1109 1110 1111
.SS any
.sp
Minimum severity level for all message types that are logged.
.sp
1112
\fIDefault:\fP not set
1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196
.SH MODULE RRL
.sp
A response rate limiting module.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-rrl:
  \- id: STR
    rate\-limit: INT
    slip: INT
    table\-size: INT
    whitelist: ADDR[/INT] | ADDR\-ADDR ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS rate\-limit
.sp
Rate limiting is based on the token bucket scheme. A rate basically
represents a number of tokens available each second. Each response is
processed and classified (based on several discriminators, e.g.
source netblock, query type, zone name, rcode, etc.). Classified responses are
then hashed and assigned to a bucket containing number of available
tokens, timestamp and metadata. When available tokens are exhausted,
response is dropped or sent as truncated (see \fI\%slip\fP).
Number of available tokens is recalculated each second.
.sp
\fIRequired\fP
.SS table\-size
.sp
Size of the hash table in a number of buckets. The larger the hash table, the lesser
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.
Hash table is internally chained and works well up to a fill rate of 90 %, general
rule of thumb is to select a prime near 1.2 * maximum_qps.
.sp
\fIDefault:\fP 393241
.SS slip
.sp
As attacks using DNS/UDP are usually based on a forged source address,
an attacker could deny services to the victim\(aqs netblock if all
responses would be completely blocked. The idea behind SLIP mechanism
is to send each N\s-2\uth\d\s0 response as truncated, thus allowing client to
reconnect via TCP for at least some degree of service. It is worth
noting, that some responses can\(aqt be truncated (e.g. SERVFAIL).
.INDENT 0.0
.IP \(bu 2
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
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
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.
.UNINDENT
.sp
\fIDefault:\fP 1
.SS 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
1197 1198
.SH MODULE DNSTAP
.sp
1199
The module dnstap allows query and response logging.
1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210
.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
1211 1212
    identity: STR
    version: STR
1213 1214
    log\-queries: BOOL
    log\-responses: BOOL
1215 1216 1217 1218 1219 1220 1221 1222 1223
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS sink
.sp
1224
A sink path, which can be either a file or a UNIX socket when prefixed with
1225 1226
\fBunix:\fP\&.
.sp
1227
\fIRequired\fP
1228 1229 1230 1231 1232 1233 1234 1235 1236 1237
.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
1238 1239 1240 1241 1242 1243 1244 1245 1246 1247
.SS log\-queries
.sp
If enabled, query messages will be logged.
.sp
\fIDefault:\fP on
.SS log\-responses
.sp
If enabled, response messages will be logged.
.sp
\fIDefault:\fP on
1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271
.SH MODULE ONLINE-SIGN
.sp
The module provides online DNSSEC signing. Instead of pre\-computing the zone signatures
when the zone is loaded into the server or instead of loading an externally signed zone,
the signatures are computed on\-the\-fly during answering.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-online\-sign:
  \- id: STR
    policy: STR
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS policy
.sp
A \fI\%reference\fP to DNSSEC signing policy. A special \fIdefault\fP
value can be used for the default policy settings.
1272 1273
.SH MODULE SYNTH-RECORD
.sp
1274
This module is able to synthesize either forward or reverse records for the
1275 1276 1277 1278 1279 1280 1281 1282 1283 1284
given prefix and subnet.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-synth\-record:
  \- id: STR
    type: forward | reverse
    prefix: STR
1285
    origin: DNAME
1286
    ttl: INT
1287
    network: ADDR[/INT] | ADDR\-ADDR
1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301
.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
1302
\fBforward\fP – Forward records
1303
.IP \(bu 2
1304
\fBreverse\fP – Reverse records
1305 1306
.UNINDENT
.sp
1307
\fIRequired\fP
1308 1309 1310 1311
.SS prefix
.sp
A record owner prefix.
.sp
1312 1313 1314 1315
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The value doesn’t allow dots, address parts in the synthetic names are
1316
separated with a dash.
1317 1318
.UNINDENT
.UNINDENT
1319
.sp
1320
\fIDefault:\fP empty
1321
.SS origin
1322
.sp
1323
A zone origin (only valid for the \fI\%reverse type\fP).
1324
.sp
1325
\fIRequired\fP
1326 1327 1328 1329
.SS ttl
.sp
Time to live of the generated records.
.sp
1330
\fIDefault:\fP 3600
1331
.SS network
1332
.sp
1333
An IP address, a network subnet, or a network range the query must match.
1334
.sp
1335
\fIRequired\fP
1336 1337
.SH MODULE DNSPROXY
.sp
1338
The module catches all unsatisfied queries and forwards them to the indicated
1339 1340 1341 1342 1343 1344 1345 1346
server for resolution.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-dnsproxy:
  \- id: STR
1347
    remote: remote_id
1348
    timeout: INT
1349
    fallback: BOOL
1350
    catch\-nxdomain: BOOL
1351 1352 1353 1354 1355 1356 1357 1358 1359
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS remote
.sp
1360 1361
A \fI\%reference\fP to a remote server where the queries are
forwarded to.
1362
.sp
1363
\fIRequired\fP
1364 1365 1366 1367 1368
.SS timeout
.sp
A remote response timeout in milliseconds.
.sp
\fIDefault:\fP 500
1369 1370 1371 1372 1373 1374 1375
.SS fallback
.sp
If enabled, localy unsatisfied queries leading to REFUSED (no zone) are forwarded.
If disabled, all queries are directly forwarded without any local attempts
to resolve them.
.sp
\fIDefault:\fP on
1376 1377
.SS catch\-nxdomain
.sp
1378 1379
If enabled, localy unsatisfied queries leading to NXDOMAIN are forwarded.
This option is only relevant in the fallback mode.
1380
.sp
1381
\fIDefault:\fP off
1382 1383 1384
.SH MODULE ROSEDB
.sp
The module provides a mean to override responses for certain queries before
1385
the available zones are searched for the record.
1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404
.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
1405
\fIRequired\fP
1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651
.SH MODULE STATS
.sp
The module provides incoming query processing statistics.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Leading 16\-bit message size over TCP is not considered.
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
mod\-stats:
  \- id: STR
    request\-protocol: BOOL
    server\-operation: BOOL
    request\-bytes: BOOL
    response\-bytes: BOOL
    edns\-presence: BOOL
    flag\-presence: BOOL
    response\-code: BOOL
    reply\-nodata: BOOL
    query\-type: BOOL
    query\-size: BOOL
    reply\-size: BOOL
.ft P
.fi
.UNINDENT
.UNINDENT
.SS id
.sp
A module identifier.
.SS request\-protocol
.sp
If enabled, all incoming requests are counted by the network protocol:
.INDENT 0.0
.IP \(bu 2
udp4 \- UDP over IPv4
.IP \(bu 2
tcp4 \- TCP over IPv4
.IP \(bu 2
udp6 \- UDP over IPv6
.IP \(bu 2
tcp6 \- TCP over IPv6
.UNINDENT
.sp
\fIDefault:\fP on
.SS server\-operation
.sp
If enabled, all incoming requests are counted by the server operation. The
server operation is based on message header OpCode and message query (meta) type:
.INDENT 0.0
.IP \(bu 2
query \- Normal query operation
.IP \(bu 2
update \- Dynamic update operation
.IP \(bu 2
notify \- NOTIFY request operation
.IP \(bu 2
axfr \- Full zone transfer operation
.IP \(bu 2
ixfr \- Incremental zone transfer operation
.IP \(bu 2
invalid \- Invalid server operation
.UNINDENT
.sp
\fIDefault:\fP on
.SS request\-bytes
.sp
If enabled, all incoming request bytes are counted by the server operation:
.INDENT 0.0
.IP \(bu 2
query \- Normal query bytes
.IP \(bu 2
update \- Dynamic update bytes
.IP \(bu 2
other \- Other request bytes
.UNINDENT
.sp
\fIDefault:\fP on
.SS response\-bytes
.sp
If enabled, outgoing response bytes are counted by the server operation:
.INDENT 0.0
.IP \(bu 2
reply \- Normal response bytes
.IP \(bu 2
transfer \- Zone transfer bytes
.IP \(bu 2
other \- Other response bytes
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Dynamic update response bytes are not counted by this module.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP on
.SS edns\-presence
.sp
If enabled, EDNS pseudo section presence is counted by the message direction:
.INDENT 0.0
.IP \(bu 2
request \- EDNS present in request
.IP \(bu 2
response \- EDNS present in response
.UNINDENT
.sp
\fIDefault:\fP off
.SS flag\-presence
.sp
If enabled, some message header flags are counted:
.INDENT 0.0
.IP \(bu 2
TC \- Truncated Answer in response
.IP \(bu 2
DO \- DNSSEC OK in request
.UNINDENT
.sp
\fIDefault:\fP off
.SS response\-code
.sp
If enabled, outgoing response code is counted:
.INDENT 0.0
.IP \(bu 2
NOERROR
.IP \(bu 2
\&...
.IP \(bu 2
NOTZONE
.IP \(bu 2
BADVERS
.IP \(bu 2
\&...
.IP \(bu 2
BADCOOKIE
.IP \(bu 2
other \- All other codes
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
In the case of multi\-message zone transfer response, just one counter is
incremented.
.UNINDENT
.UNINDENT
.sp
\fBWARNING:\fP
.INDENT 0.0
.INDENT 3.5
Dynamic update response code is not counted by this module.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP on
.SS reply\-nodata
.sp
If enabled, NODATA pseudo RCODE (see RFC 2308, Section 2.2) is counted by the
query type:
.INDENT 0.0
.IP \(bu 2
A
.IP \(bu 2
AAAA
.IP \(bu 2
other \- All other types
.UNINDENT
.sp
\fIDefault:\fP off
.SS query\-type
.sp
If enabled, normal query type is counted:
.INDENT 0.0
.IP \(bu 2
A (TYPE1)
.IP \(bu 2
\&...
.IP \(bu 2
TYPE65
.IP \(bu 2
SPF (TYPE99)
.IP \(bu 2
\&...
.IP \(bu 2
TYPE110
.IP \(bu 2
ANY (TYPE255)
.IP \(bu 2
\&...
.IP \(bu 2
TYPE260
.IP \(bu 2
other \- All other types
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Not all assigned meta types (IXFR, AXFR,...) have their own counters,
because such types are not processed as normal query.
.UNINDENT
.UNINDENT
.sp
\fIDefault:\fP off
.SS query\-size
.sp
If enabled, normal query message size distribution is counted by the size range
in bytes:
.INDENT 0.0
.IP \(bu 2
0\-15
.IP \(bu 2
16\-31
.IP \(bu 2
\&...
.IP \(bu 2
272\-287
.IP \(bu 2
288\-65535
.UNINDENT
.sp
\fIDefault:\fP off
.SS reply\-size
.sp
If enabled, normal reply message size distribution is counted by the size range
in bytes:
.INDENT 0.0
.IP \(bu 2
0\-15
.IP \(bu 2
16\-31
.IP \(bu 2
\&...
.IP \(bu 2
4080\-4095
.IP \(bu 2
4096\-65535
.UNINDENT
.sp
\fIDefault:\fP off
1652 1653 1654
.SH AUTHOR
CZ.NIC Labs <http://www.knot-dns.cz>
.SH COPYRIGHT
1655
Copyright 2010–2017, CZ.NIC, z.s.p.o.
1656 1657
.\" Generated by docutils manpage writer.
.