reference.rst 28.9 KB
Newer Older
1
.. highlight:: none
2
.. _Configuration Reference:
3

4 5 6
***********************
Configuration Reference
***********************
7

8
.. _Description:
9

10 11
Description
===========
12

13 14
Configuration files for Knot DNS use simplified YAML format. Simplified means
that not all of the features are supported.
15

16
For the description of configuration items, we have to declare a meaning of
17
the following symbols:
18

19 20 21 22 23
- *INT* – Integer
- *STR* – Textual string
- *HEXSTR* – Hexadecimal string (with ``0x`` prefix)
- *BOOL* – Boolean value (``on``/``off`` or ``true``/``false``)
- *TIME* – Number of seconds, an integer with possible time multiplier suffix
24
  (``s`` ~ 1, ``m`` ~ 60, ``h`` ~ 3600 or ``d`` ~ 24 * 3600)
25
- *SIZE* – Number of bytes, an integer with possible size multiplier suffix
26
  (``B`` ~ 1, ``K`` ~ 1024, ``M`` ~ 1024^2 or ``G`` ~ 1024^3)
27 28 29 30 31 32
- *BASE64* – Base64 encoded string
- *ADDR* – IPv4 or IPv6 address
- *DNAME* – Domain name
- ... – Multi-valued item, order of the values is preserved
- [ ] – Optional value
- \| – Choice
33

34 35 36 37
There are 10 main sections (``server``, ``control``, ``log``, ``keystore``,
``policy``, ``key``, ``acl``, ``remote``, ``template``, and ``zone``) and
module sections with the ``mod-`` prefix. Most of the sections (excluding
``server`` and ``control``) are sequences of settings blocks. Each settings block
38 39
begins with a unique identifier, which can be used as a reference from other
sections (such identifier must be defined in advance).
40

41 42 43 44 45 46 47 48
A multi-valued item can be specified either as a YAML sequence::

 address: [10.0.0.1, 10.0.0.2]

or as more single-valued items each on an extra line::

 address: 10.0.0.1
 address: 10.0.0.2
49

50
If an item value contains spaces or other special characters, it is necessary
51
to enclose such value within double quotes ``"`` ``"``.
52

53
.. _Comments:
54

55 56
Comments
========
57

58
A comment begins with a ``#`` character and is ignored during processing.
59 60 61
Also each configuration section or sequence block allows to specify permanent
comment using ``comment`` item which is stored in the server beside the
configuration.
62

63
.. _Includes:
64

65 66
Includes
========
67

68 69 70 71
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 *glob* requirements, e.g. dir/\*.conf.
72
Matching files are processed in sorted order.
73 74 75

::

76
 include: STR
77

78
.. _Server section:
79

80 81
Server section
==============
82

83
General options related to the server.
84 85 86

::

87 88 89 90 91 92 93
 server:
     identity: [STR]
     version: [STR]
     nsid: [STR|HEXSTR]
     rundir: STR
     user: STR[:STR]
     pidfile: STR
94 95
     udp-workers: INT
     tcp-workers: INT
96
     background-workers: INT
97
     async-start: BOOL
98
     tcp-handshake-timeout: TIME
99
     tcp-idle-timeout: TIME
100
     tcp-reply-timeout: TIME
101 102 103 104
     max-tcp-clients: INT
     max-udp-payload: SIZE
     rate-limit: INT
     rate-limit-slip: INT
105
     rate-limit-table-size: INT
106
     rate-limit-whitelist: ADDR[/INT] | ADDR-ADDR ...
107 108 109
     listen: ADDR[@INT] ...

.. _server_identity:
110

111 112
identity
--------
113

114
An identity of the server returned in the response to the query for TXT
115
record ``id.server.`` or ``hostname.bind.`` in the CHAOS class (see RFC 4892).
116
Set empty value to disable.
117

118
*Default:* FQDN hostname
119

120
.. _server_version:
121

122 123
version
-------
124

125
A version of the server software returned in the response to the query
126
for TXT record ``version.server.`` or ``version.bind.`` in the CHAOS
127
class (see RFC 4892). Set empty value to disable.
128

129
*Default:* server version
130

131
.. _server_nsid:
132

133 134
nsid
----
135

136
A DNS name server identifier (see RFC 5001). Set empty value to disable.
137

138
*Default:* FQDN hostname
139

140
.. _server_rundir:
141

142 143
rundir
------
144

145
A path for storing run-time data (PID file, unix sockets, etc.).
146

147
*Default:* ``${localstatedir}/run/knot`` (configured with ``--with-rundir=path``)
148

149
.. _server_user:
150

151 152
user
----
153

154
A system user with an optional system group (``user:group``) under which the
155 156
server is run after starting and binding to interfaces. Linux capabilities
are employed if supported.
157

158
*Default:* root:root
159

160
.. _server_pidfile:
161

162 163
pidfile
-------
164

165
A PID file location.
166

167
*Default:* :ref:`rundir<server_rundir>`/knot.pid
168

169
.. _server_udp-workers:
170

171 172
udp-workers
-----------
173

174 175
A number of quering UDP workers (threads).

176
*Default:* auto-estimated optimal value based on the number of online CPUs
177 178 179 180 181 182 183

.. _server_tcp-workers:

tcp-workers
-----------

A number of quering TCP workers (threads).
184

185
*Default:* auto-estimated optimal value based on the number of online CPUs
186

187
.. _server_background-workers:
188

189 190
background-workers
------------------
191

192 193
A number of workers (threads) used to execute background operations (zone
loading, zone updates, etc.).
194

195
*Default:* auto-estimated optimal value based on the number of online CPUs
196

197
.. _server_async-start:
198

199 200
async-start
-----------
201

202 203
If enabled, server doesn't wait for the zones to be loaded and starts
responding immediately with SERVFAIL answers until the zone loads.
204

205
*Default:* off
206

207
.. _server_tcp-handshake-timeout:
208

209 210
tcp-handshake-timeout
---------------------
211

212 213 214
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.
215

216
*Default:* 5
217

218 219 220 221 222 223 224 225
.. _server_tcp-idle-timeout:

tcp-idle-timeout
----------------

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.

226
*Default:* 20
227

228
.. _server_tcp-reply-timeout:
229

230 231
tcp-reply-timeout
-----------------
232

233 234 235
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.
236

237
*Default:* 10
238 239

.. _server_max-tcp-clients:
240 241

max-tcp-clients
242 243 244 245
---------------

A maximum number of TCP clients connected in parallel, set this below the file
descriptor limit to avoid resource exhaustion.
246

247
*Default:* 100
248

249
.. _server_rate-limit:
250 251

rate-limit
252
----------
253

254 255
Rate limiting is based on the token bucket scheme. A rate basically
represents a number of tokens available each second. Each response is
256
processed and classified (based on several discriminators, e.g.
257
source netblock, query type, zone name, rcode, etc.). Classified responses are
258
then hashed and assigned to a bucket containing number of available
259
tokens, timestamp and metadata. When available tokens are exhausted,
260 261
response is dropped or sent as truncated (see :ref:`server_rate-limit-slip`).
Number of available tokens is recalculated each second.
262

263
*Default:* 0 (disabled)
264

265
.. _server_rate-limit-table-size:
266

267 268
rate-limit-table-size
---------------------
269

270
Size of the hash table in a number of buckets. The larger the hash table, the lesser
271 272 273
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.
274
Hash table is internally chained and works well up to a fill rate of 90 %, general
275
rule of thumb is to select a prime near 1.2 * maximum_qps.
276

277
*Default:* 393241
278

279
.. _server_rate-limit-slip:
280 281

rate-limit-slip
282
---------------
283 284

As attacks using DNS/UDP are usually based on a forged source address,
285
an attacker could deny services to the victim's netblock if all
286
responses would be completely blocked. The idea behind SLIP mechanism
287
is to send each N\ :sup:`th` response as truncated, thus allowing client to
288 289 290
reconnect via TCP for at least some degree of service. It is worth
noting, that some responses can't be truncated (e.g. SERVFAIL).

Jan Včelák's avatar
Jan Včelák committed
291 292 293 294 295 296
- Setting the value to **0** will cause that all rate-limited responses will
  be dropped. The outbound bandwidth and packet rate will be strictly capped
  by the :ref:`server_rate-limit` option. All legitimate requestors affected
  by the limit will face denial of service and will observe excessive timeouts.
  Therefore this setting is not recommended.

297 298 299 300 301 302 303 304 305 306 307
- Setting the value to **1** 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't be lower than the incoming bandwidth.
  Also the outbound packet rate will be the same as without RRL.

- Setting the value to **2** 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.

Jan Včelák's avatar
Jan Včelák committed
308 309 310 311
- Setting the value to anything **larger than 2** 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.
312

313
*Default:* 1
314

315 316 317 318 319 320 321 322 323 324 325
.. _server_rate-limit-whitelist:

rate-limit-whitelist
--------------------

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.

*Default:* not set

326
.. _server_max-udp-payload:
327 328

max-udp-payload
329
---------------
330 331 332

Maximum EDNS0 UDP payload size.

333
*Default:* 4096
334

335
.. _server_listen:
336

337 338
listen
------
339

340 341 342 343
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 ``@`` separator. Use ``0.0.0.0`` for all configured IPv4 addresses or
``::`` for all configured IPv6 addresses.
344

345
*Default:* not set
346

347
.. _Key section:
348

349 350
Key section
===========
351

352
Shared TSIG keys used to authenticate communication with the server.
353

354
::
355

356 357 358 359
 key:
   - id: DNAME
     algorithm: hmac-md5 | hmac-sha1 | hmac-sha224 | hmac-sha256 | hmac-sha384 | hmac-sha512
     secret: BASE64
360

361
.. _key_id:
362

363 364
id
--
365

366
A key name identifier.
367

368
.. _key_algorithm:
369

370 371 372 373 374
algorithm
---------

A key algorithm.

375
*Default:* not set
376

377
.. _key_secret:
378

379 380
secret
------
381

382
Shared key secret.
383

384
*Default:* not set
385

386 387 388 389 390
.. _ACL section:

ACL section
===========

391 392 393
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.).
394 395 396

::

397 398
 acl:
   - id: STR
399
     address: ADDR[/INT] | ADDR-ADDR ...
400
     key: key_id ...
401
     action: notify | transfer | update ...
402
     deny: BOOL
403

404
.. _acl_id:
405

406 407
id
--
408

409
An ACL rule identifier.
410

411
.. _acl_address:
412

413 414
address
-------
415

416 417
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.
418

419
*Default:* not set
420

421
.. _acl_key:
422

423 424
key
---
425

426 427
An ordered list of :ref:`reference<key_id>`\ s to TSIG keys. The query must
match one of them. Empty value means that TSIG key is not required.
428

429
*Default:* not set
430

431
.. _acl_action:
432

433 434
action
------
435

436 437
An ordered list of allowed actions. Empty action list is only allowed if
:ref:`deny<acl_deny>` is set.
438

439
Possible values:
440

441 442 443
- ``transfer`` – Allow zone transfer
- ``notify`` – Allow incoming notify
- ``update`` – Allow zone updates
444

445
*Default:* not set
446 447 448 449 450 451 452 453 454

.. _acl_deny:

deny
----

Deny if :ref:`address<acl_address>`, :ref:`key<acl_key>` and
:ref:`action<acl_action>` match.

455
*Default:* off
456

457
.. _Control section:
458

459 460
Control section
===============
461

462
Configuration of the server control interface.
463

464
::
465

466
 control:
467
     listen: STR
468
     timeout: TIME
469

470
.. _control_listen:
471

472 473
listen
------
474

475
A UNIX socket path where the server listens for control commands.
476

477
*Default:* :ref:`rundir<server_rundir>`/knot.sock
478

479 480 481 482 483 484 485 486 487
.. _control_timeout:

timeout
-------

Maximum time the control socket operations can take. Set 0 for infinity.

*Default:* 5

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
.. _Keystore section:

Keystore section
================

DNSSEC keystore configuration.

::

 keystore:
   - id: STR
     backend: pem | pkcs11
     config: STR

.. _keystore_id:

id
--

A keystore identifier.


.. _keystore_backend:

backend
-------

Jan Včelák's avatar
Jan Včelák committed
515
A key storage backend type. A directory with PEM files or a PKCS #11 storage.
516 517 518 519 520 521 522 523

*Default:* pem

.. _keystore_config:

config
------

524
A backend specific configuration. A directory with PEM files (the path can
525
be specified as a relative path to :ref:`kasp-db<zone_kasp-db>`) or
Jan Včelák's avatar
Jan Včelák committed
526
a configuration string for PKCS #11 storage.
527 528

.. NOTE::
Jan Včelák's avatar
Jan Včelák committed
529
   Example configuration string for PKCS #11::
530

531
     "pkcs11:token=knot;pin-value=1234 /usr/lib64/pkcs11/libsofthsm2.so"
532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547

*Default:* :ref:`kasp-db<zone_kasp-db>`/keys

.. _Policy section:

Policy section
==============

DNSSEC policy configuration.

::

 policy:
   - id: STR
     keystore: STR
     manual: BOOL
548
     algorithm: dsa | rsasha1 | dsa-nsec3-sha1 | rsasha1-nsec3-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384
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
     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

.. _policy_id:

id
--

A policy identifier.

.. _policy_keystore:

keystore
--------

A :ref:`reference<keystore_id>` to a keystore holding private key material
574
for zones. A special *default* value can be used for the default keystore settings.
575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593

*Default:* default

.. _policy_manual:

manual
------

If enabled, automatic key management is not used.

*Default:* off

.. _policy_algorithm:

algorithm
---------

An algorithm of signing keys and issued signatures.

594
*Default:* ecdsap256sha256
595 596 597 598 599 600 601 602

.. _policy_ksk-size:

ksk-size
--------

A length of newly generated :abbr:`KSK (Key Signing Key)` keys.

603
*Default:* 1024 (dsa*), 2048 (rsa*), 256 (ecdsap256*), 384 (ecdsap384*)
604 605 606 607 608 609 610 611

.. _policy_zsk-size:

zsk-size
--------

A length of newly generated :abbr:`ZSK (Zone Signing Key)` keys.

612
*Default:* see default for :ref:`ksk-size<policy_ksk-size>`
613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696

.. _policy_dnskey-ttl:

dnskey-ttl
----------

A TTL value for DNSKEY records added into zone apex.

*Default:* zone SOA TTL

.. _policy_zsk-lifetime:

zsk-lifetime
------------

A period between ZSK publication and the next rollover initiation.

*Default:* 30 days

.. _policy_rrsig-lifetime:

rrsig-lifetime
--------------

A validity period of newly issued signatures.

*Default:* 14 days

.. _policy_rrsig-refresh:

rrsig-refresh
-------------

A period how long before a signature expiration the signature will be refreshed.

*Default:* 7 days

.. _policy_nsec:

nsec3
-----

Specifies if NSEC3 will be used instead of NSEC.

*Default:* off

.. _policy_nsec3-iterations:

nsec3-iterations
----------------

A number of additional times the hashing is performed.

*Default:* 5

.. _policy_nsec3-salt-length:

nsec3-salt-length
-----------------

A length of a salt field in octets, which is appended to the original owner
name before hashing.

*Default:* 8

.. _policy_nsec3-resalt:

nsec3-resalt
------------

A validity period of newly issued salt field.

*Default:* 30 days

.. _policy_propagation-delay:

propagation-delay
-----------------

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.

*Default:* 1 day

697 698 699 700
.. _Remote section:

Remote section
==============
701

702 703
Definitions of remote servers for outgoing connections (source of a zone
transfer, target for a notification, etc.).
704

705
::
706

707 708
 remote:
   - id: STR
709 710
     address: ADDR[@INT] ...
     via: ADDR[@INT] ...
711
     key: key_id
712 713 714

.. _remote_id:

715 716 717 718
id
--

A remote identifier.
719

720
.. _remote_address:
721

722 723
address
-------
724

725 726 727 728
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 ``@`` separator.
729

730
*Default:* not set
731

732
.. _remote_via:
733

734 735
via
---
736

737 738 739
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 ``@`` separator.
740

741
*Default:* not set
742

743
.. _remote_key:
744

745 746
key
---
747

748 749
A :ref:`reference<key_id>` to the TSIG key which ise used to autenticate
the communication with the remote server.
750

751
*Default:* not set
752

753
.. _Template section:
754

755 756
Template section
================
757

758 759
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 *default* identifier)
760
can be used for global querying configuration or as an implicit configuration
761
if a zone doesn't have another template specified.
762 763 764

::

765 766
 template:
   - id: STR
767
     timer-db: STR
768
     global-module: STR/STR ...
769 770 771 772 773 774 775 776 777
     # All zone options (excluding 'template' item)

.. _template_id:

id
--

A template identifier.

778 779 780 781 782 783 784 785
.. _template_timer-db:

timer-db
--------

Specifies a path of the persistent timer database. The path can be specified
as a relative path to the *default* template :ref:`storage<zone_storage>`.

786 787
.. NOTE::
   This option is only available in the *default* template.
788 789 790

*Default:* :ref:`storage<zone_storage>`/timers

791 792 793 794 795 796 797 798
.. _template_global-module:

global-module
-------------

An ordered list of references to query modules in the form
*module_name/module_id*. These modules apply to all queries.

799 800
.. NOTE::
   This option is only available in the *default* template.
801

802
*Default:* not set
803

804 805 806 807 808 809 810 811 812 813 814 815 816
.. _Zone section:

Zone section
============

Definition of zones served by the server.

::

 zone:
   - domain: DNAME
     template: template_id
     file: STR
817 818
     storage: STR
     master: remote_id ...
819
     ddns-master: remote_id
820 821 822 823 824 825
     notify: remote_id ...
     acl: acl_id ...
     semantic-checks: BOOL
     disable-any: BOOL
     zonefile-sync: TIME
     ixfr-from-differences: BOOL
826
     max-journal-size: SIZE
Vitezslav Kriz's avatar
Vitezslav Kriz committed
827
     max-zone-size : SIZE
828
     dnssec-signing: BOOL
829
     dnssec-policy: STR
830
     kasp-db: STR
831
     request-edns-option: INT:[HEXSTR]
832 833
     serial-policy: increment | unixtime
     module: STR/STR ...
834

835
.. _zone_domain:
836

837 838
domain
------
839

840 841 842 843 844 845 846
A zone name identifier.

.. _zone_template:

template
--------

847
A :ref:`reference<template_id>` to a configuration template.
848

849
*Default:* not set or *default* (if the template exists)
850 851 852 853 854

.. _zone_file:

file
----
855

856
A path to the zone file. Non absolute path is relative to
857
:ref:`storage<zone_storage>`. It is also possible to use the following formatters:
858

859 860 861 862 863 864 865 866
- ``%c[``\ *N*\ ``]`` or ``%c[``\ *N*\ ``-``\ *M*\ ``]`` – means the *N*\ th
  character or a sequence of characters beginning from the *N*\ th and ending
  with the *M*\ th character of the textual zone name (see ``%s``). The
  indexes are counted from 0 from the left. If the character is not available,
  the formatter has no effect.
- ``%l[``\ *N*\ ``]`` – means the *N*\ th label of the textual zone name
  (see ``%s``). The index is counted from 0 from the right (0 ~ TLD).
  If the label is not available, the formatter has no effect.
867
- ``%s`` – means the current zone name in the textual representation (beware
868 869
  of special characters which are escaped or encoded in the \\DDD form where
  DDD is corresponding decimal ASCII code). The zone name doesn't include the
870
  terminating dot (the result for the root zone is the empty string!).
871
- ``%%`` – means the ``%`` character
872

873
*Default:* :ref:`storage<zone_storage>`/``%s``\ .zone
874 875

.. _zone_storage:
876

877 878
storage
-------
879

880
A data directory for storing zone files, journal files and timers database.
881

882
*Default:* ``${localstatedir}/lib/knot`` (configured with ``--with-storage=path``)
883

884
.. _zone_master:
885

886 887
master
------
888

889
An ordered list of :ref:`references<remote_id>` to zone master servers.
890

891
*Default:* not set
892

893 894 895 896 897
.. _zone_ddns-master:

ddns-master
-----------

898
A :ref:`reference<remote_id>` to zone primary master server.
899 900
If not specified, the first :ref:`master<zone_master>` server is used.

901
*Default:* not set
902

903
.. _zone_notify:
904

905 906
notify
------
907

908 909
An ordered list of :ref:`references<remote_id>` to remotes to which notify
message is sent if the zone changes.
910

911
*Default:* not set
912

913
.. _zone_acl:
914

915 916
acl
---
917

918 919
An ordered list of :ref:`references<acl_id>` to ACL rules which can allow
or disallow zone transfers, updates or incoming notifies.
920

921
*Default:* not set
922

923
.. _zone_semantic-checks:
924

925 926
semantic-checks
---------------
927

928
If enabled, extra zone file semantic checks are turned on.
929

930 931 932
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.
933

934
Mandatory checks:
935

936 937 938
- An extra record together with CNAME record (except for RRSIG and DS)
- SOA record missing in the zone (RFC 1034)
- DNAME records having records under it (DNAME children) (RFC 2672)
939

940
Extra checks:
941

942 943 944 945 946 947
- Missing NS record at the zone apex
- Missing glue A or AAAA records
- Broken or non-cyclic NSEC(3) chain
- Wrong NSEC(3) type bitmap
- Multiple NSEC records at the same node
- Missing NSEC records at authoritative nodes
948
- NSEC3 insecure delegation that is not part of Opt-out span
949 950 951 952 953
- Wrong original TTL value in NSEC3 records
- Wrong RDATA TTL value in RRSIG record
- Signer name in RRSIG RR not the same as in DNSKEY
- Signed RRSIG
- Wrong key flags or wrong key in RRSIG record (not the same as ZSK)
954

955
*Default:* off
956

957
.. _zone_disable-any:
958

959 960
disable-any
-----------
961

962
If enabled, all authoritative ANY queries sent over UDP will be answered
963 964
with an empty response and with the TC bit set. Use this option to minimize
the risk of DNS reflection attack.
965

966
*Default:* off
967

968
.. _zone_zonefile-sync:
969 970 971

zonefile-sync
-------------
972

973
The time after which the current zone in memory will be synced with a zone file
974
on the disk (see :ref:`file<zone_file>`). The server will serve the latest
975
zone even after a restart using zone journal, but the zone file on the disk will
976
only be synced after ``zonefile-sync`` time has expired (or after manual zone
977
flush). This is applicable when the zone is updated via IXFR, DDNS or automatic
978
DNSSEC signing. In order to disable automatic zonefile synchronization, -1 value
979
can be used (manual zone flush is still possible).
980

981 982 983
.. NOTE::
   If you are serving large zones with frequent updates where
   the immediate sync with a zone file is not desirable, increase the value.
984

985
*Default:* 0 (immediate)
986

987
.. _zone_ixfr-from-differences:
988

989 990 991 992
ixfr-from-differences
---------------------

If enabled, the server creates zone differences from changes you made to the
993
zone file upon server reload. This option is relevant only if the server
994 995
is a master server for the zone.

996 997 998
.. NOTE::
   This option has no effect with enabled
   :ref:`dnssec-signing<zone_dnssec-signing>`.
999

1000
*Default:* off
1001

1002
.. _zone_max_journal_size:
1003

1004 1005
max-journal-size
----------------
1006

1007
Maximum size of the zone journal file.
1008

1009
*Default:* 2^64
1010

Vitezslav Kriz's avatar
Vitezslav Kriz committed
1011 1012 1013 1014 1015
.. _zone_max_zone_size:

max-zone-size
----------------

1016 1017
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
1018
transfers and dynamic updates.
1019 1020 1021 1022

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.
Vitezslav Kriz's avatar
Vitezslav Kriz committed
1023 1024 1025

*Default:* 2^64

1026
.. _zone_dnssec-signing:
1027

1028 1029
dnssec-signing
--------------
1030

1031
If enabled, automatic DNSSEC signing for the zone is turned on.
1032

1033 1034
.. NOTE::
   Cannot be enabled on a slave zone.
1035

1036
*Default:* off
1037

1038 1039 1040 1041 1042
.. _zone_dnssec-policy:

dnssec-policy
-------------

1043 1044
A :ref:`reference<policy_id>` to DNSSEC signing policy. A special *default*
value can be used for the default policy settings.
1045

1046
*Required*
1047 1048

.. _zone_kasp-db:
1049

1050
kasp-db
1051
-------
1052

1053
A KASP database path. Non absolute path is relative to
1054
:ref:`storage<zone_storage>`.
1055

1056
*Default:* :ref:`storage<zone_storage>`/keys
1057

1058 1059 1060 1061 1062 1063 1064 1065
.. _zone_request_edns_option:

request-edns-option
-------------------

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.

1066
*Default:* not set
1067

1068
.. _zone_serial-policy:
1069

1070 1071
serial-policy
-------------
1072

1073 1074 1075
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.
1076

1077
Possible values:
1078

1079 1080
- ``increment`` – The serial is incremented according to serial number arithmetic
- ``unixtime`` – The serial is set to the current unix time
1081

1082 1083 1084 1085 1086
.. NOTE::
   If your serial was in other than unix time format, be careful
   with the transition to unix time.  It may happen that the new serial will
   be \'lower\' than the old one. If this is the case, the transition should be
   done by hand (see RFC 1982).
1087

1088
*Default:* increment
1089

1090
.. _zone_module:
1091

1092 1093
module
------
1094

1095
An ordered list of references to query modules in the form
1096
*module_name/module_id*. These modules apply only to the current zone queries.
1097

1098
*Default:* not set
1099

1100
.. _Logging section:
1101

1102 1103
Logging section
===============
1104

1105 1106 1107
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.
1108

1109
There are 6 logging severity levels:
1110

1111
- ``critical`` – Non-recoverable error resulting in server shutdown
1112

1113
- ``error`` – Recoverable error, action should be taken
1114

1115
- ``warning`` – Warning that might require user action
1116

1117
- ``notice`` – Server notice or hint
1118

1119
- ``info`` – Informational message
1120

1121
- ``debug`` – Debug messages (must be turned on at compile time)
1122

1123
In the case of missing log section, ``warning`` or more serious messages
1124 1125
will be logged to both standard error output and syslog. The ``info`` and
``notice`` messages will be logged to standard output.
1126

1127
::
1128

1129
 log:
1130
   - target: stdout | stderr | syslog | STR
1131 1132 1133
     server: critical | error | warning | notice | info | debug
     zone: critical | error | warning | notice | info | debug
     any: critical | error | warning | notice | info | debug
1134

1135
.. _log_target:
1136

1137 1138
target
------
1139

1140
A logging output.
1141

1142
Possible values:
1143

1144 1145 1146 1147
- ``stdout`` – Standard output
- ``stderr`` – Standard error output
- ``syslog`` – Syslog
- *file\_name* – File
1148

1149
.. _log_server:
1150

1151 1152
server
------
1153

1154 1155
Minimum severity level for messages related to general operation of the server
that are logged.
1156

1157
*Default:* not set
1158

1159
.. _log_zone:
1160

1161 1162
zone
----
1163

1164
Minimum severity level for messages related to zones that are logged.
1165

1166
*Default:* not set
1167

1168
.. _log_any:
1169

1170 1171
any
---
1172

1173
Minimum severity level for all message types that are logged.
1174

1175
*Default:* not set
1176

1177
.. _Module dnstap:
1178

1179 1180
Module dnstap
=============
1181

1182
The module dnstap allows query and response logging.
1183

1184 1185
For all queries logging, use this module in the *default* template. For
zone-specific logging, use this module in the proper zone configuration.
1186 1187 1188

::

1189 1190 1191
 mod-dnstap:
   - id: STR
     sink: STR
1192 1193
     identity: STR
     version: STR
1194

1195
.. _mod-dnstap_id:
1196

1197 1198
id
--
1199

1200
A module identifier.
1201