reference.rst 30 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

Daniel Salzman's avatar
Daniel Salzman committed
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

Daniel Salzman's avatar
Daniel Salzman committed
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
Also each configuration section or sequence block allows a permanent
comment using the ``comment`` item which is stored in the server beside the
61
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
     max-tcp-clients: INT
     max-udp-payload: SIZE
103 104
     max-ipv4-udp-payload: SIZE
     max-ipv6-udp-payload: SIZE
105 106
     rate-limit: INT
     rate-limit-slip: INT
107
     rate-limit-table-size: INT
108
     rate-limit-whitelist: ADDR[/INT] | ADDR-ADDR ...
109 110 111
     listen: ADDR[@INT] ...

.. _server_identity:
112

113 114
identity
--------
115

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

120
*Default:* FQDN hostname
121

122
.. _server_version:
123

124 125
version
-------
126

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

131
*Default:* server version
132

133
.. _server_nsid:
134

135 136
nsid
----
137

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

140
*Default:* FQDN hostname
141

142
.. _server_rundir:
143

144 145
rundir
------
146

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

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

151
.. _server_user:
152

153 154
user
----
155

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

160
*Default:* root:root
161

162
.. _server_pidfile:
163

164 165
pidfile
-------
166

167
A PID file location.
168

169
*Default:* :ref:`rundir<server_rundir>`/knot.pid
170

171
.. _server_udp-workers:
172

173 174
udp-workers
-----------
175

176 177
A number of UDP workers (threads) used to process incoming queries
over UDP.
178

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

.. _server_tcp-workers:

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

186 187
A number of TCP workers (threads) used to process incoming queries
over TCP.
188

189
*Default:* auto-estimated optimal value based on the number of online CPUs
190

191
.. _server_background-workers:
192

193 194
background-workers
------------------
195

196 197
A number of workers (threads) used to execute background operations (zone
loading, zone updates, etc.).
198

199
*Default:* auto-estimated optimal value based on the number of online CPUs
200

201
.. _server_async-start:
202

203 204
async-start
-----------
205

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

209
*Default:* off
210

211
.. _server_tcp-handshake-timeout:
212

213 214
tcp-handshake-timeout
---------------------
215

216 217 218
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.
219

220
*Default:* 5
221

222 223 224 225 226 227 228 229
.. _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.

230
*Default:* 20
231

232
.. _server_tcp-reply-timeout:
233

234 235
tcp-reply-timeout
-----------------
236

237
Maximum time to wait for an outgoing connection or for a reply to an issued
238
request (SOA, NOTIFY, AXFR...).
239

240
*Default:* 10
241 242

.. _server_max-tcp-clients:
243 244

max-tcp-clients
245 246 247 248
---------------

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

250
*Default:* 100
251

252
.. _server_rate-limit:
253 254

rate-limit
255
----------
256

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

266
*Default:* 0 (disabled)
267

268
.. _server_rate-limit-table-size:
269

270 271
rate-limit-table-size
---------------------
272

Jan Včelák's avatar
Jan Včelák committed
273
Size of the hash table in a number of buckets. The larger the hash table, the lesser
274 275 276
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.
277
Hash table is internally chained and works well up to a fill rate of 90 %, general
278
rule of thumb is to select a prime near 1.2 * maximum_qps.
279

280
*Default:* 393241
281

282
.. _server_rate-limit-slip:
283 284

rate-limit-slip
285
---------------
286 287

As attacks using DNS/UDP are usually based on a forged source address,
Jan Včelák's avatar
Jan Včelák committed
288
an attacker could deny services to the victim's netblock if all
289
responses would be completely blocked. The idea behind SLIP mechanism
Jan Včelák's avatar
Jan Včelák committed
290
is to send each N\ :sup:`th` response as truncated, thus allowing client to
291 292 293
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
294 295 296 297 298 299
- 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.

Jan Včelák's avatar
Jan Včelák committed
300 301 302 303 304 305 306 307 308 309 310
- 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
311 312 313 314
- 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.
315

316
*Default:* 1
317

318 319 320 321 322 323 324 325 326 327 328
.. _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

329
.. _server_max-udp-payload:
330 331

max-udp-payload
332
---------------
333

334 335 336 337 338 339 340
Maximum EDNS0 UDP payload size default for both IPv4 and IPv6.

*Default:* 4096

.. _server_max-ipv4-udp-payload:

max-ipv4-udp-payload
Filip Siroky's avatar
Filip Siroky committed
341
--------------------
342 343 344 345 346 347 348 349

Maximum EDNS0 UDP payload size for IPv4.

*Default:* 4096

.. _server_max-ipv6-udp-payload:

max-ipv6-udp-payload
Filip Siroky's avatar
Filip Siroky committed
350
--------------------
351 352

Maximum EDNS0 UDP payload size for IPv6.
353

354
*Default:* 4096
355

356
.. _server_listen:
357

358 359
listen
------
360

361 362 363 364
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.
365

366
*Default:* not set
367

368
.. _Key section:
369

370 371
Key section
===========
372

373
Shared TSIG keys used to authenticate communication with the server.
374

375
::
376

377 378 379 380
 key:
   - id: DNAME
     algorithm: hmac-md5 | hmac-sha1 | hmac-sha224 | hmac-sha256 | hmac-sha384 | hmac-sha512
     secret: BASE64
381

382
.. _key_id:
383

384 385
id
--
386

387
A key name identifier.
388

389
.. _key_algorithm:
390

391 392 393 394 395
algorithm
---------

A key algorithm.

396
*Default:* not set
397

398
.. _key_secret:
399

400 401
secret
------
402

403
Shared key secret.
404

405
*Default:* not set
406

407 408 409 410 411
.. _ACL section:

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

412 413 414
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.).
415 416 417

::

418 419
 acl:
   - id: STR
420
     address: ADDR[/INT] | ADDR-ADDR ...
421
     key: key_id ...
Daniel Salzman's avatar
Daniel Salzman committed
422
     action: notify | transfer | update ...
423
     deny: BOOL
424

425
.. _acl_id:
426

427 428
id
--
429

430
An ACL rule identifier.
431

432
.. _acl_address:
433

434 435
address
-------
436

437 438
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.
439

440
*Default:* not set
441

442
.. _acl_key:
443

444 445
key
---
446

447 448
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.
449

450
*Default:* not set
451

452
.. _acl_action:
453

454 455
action
------
456

457 458
An ordered list of allowed actions. Empty action list is only allowed if
:ref:`deny<acl_deny>` is set.
459

460
Possible values:
461

462 463 464
- ``transfer`` – Allow zone transfer
- ``notify`` – Allow incoming notify
- ``update`` – Allow zone updates
465

466
*Default:* not set
467 468 469 470 471 472 473 474 475

.. _acl_deny:

deny
----

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

476
*Default:* off
477

478
.. _Control section:
479

480 481
Control section
===============
482

Daniel Salzman's avatar
Daniel Salzman committed
483
Configuration of the server control interface.
484

485
::
486

487
 control:
Daniel Salzman's avatar
Daniel Salzman committed
488
     listen: STR
489
     timeout: TIME
490

491
.. _control_listen:
492

493 494
listen
------
495

496
A UNIX socket path where the server listens for control commands.
497

498
*Default:* :ref:`rundir<server_rundir>`/knot.sock
499

500 501 502 503 504 505 506 507 508
.. _control_timeout:

timeout
-------

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

*Default:* 5

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
.. _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
536
A key storage backend type. A directory with PEM files or a PKCS #11 storage.
537 538 539 540 541 542 543 544

*Default:* pem

.. _keystore_config:

config
------

545
A backend specific configuration. A directory with PEM files (the path can
546
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
547
a configuration string for PKCS #11 storage.
548 549

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

552
     "pkcs11:token=knot;pin-value=1234 /usr/lib64/pkcs11/libsofthsm2.so"
553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568

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

.. _Policy section:

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

DNSSEC policy configuration.

::

 policy:
   - id: STR
     keystore: STR
     manual: BOOL
569
     algorithm: dsa | rsasha1 | dsa-nsec3-sha1 | rsasha1-nsec3-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384
570 571 572 573
     ksk-size: SIZE
     zsk-size: SIZE
     dnskey-ttl: TIME
     zsk-lifetime: TIME
574
     propagation-delay: TIME
575 576 577 578 579
     rrsig-lifetime: TIME
     rrsig-refresh: TIME
     nsec3: BOOL
     nsec3-iterations: INT
     nsec3-salt-length: INT
580
     nsec3-salt-lifetime: TIME
581 582 583 584 585 586 587 588 589 590 591 592 593 594

.. _policy_id:

id
--

A policy identifier.

.. _policy_keystore:

keystore
--------

A :ref:`reference<keystore_id>` to a keystore holding private key material
595
for zones. A special *default* value can be used for the default keystore settings.
596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614

*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.

615
*Default:* ecdsap256sha256
616 617 618 619 620 621 622 623

.. _policy_ksk-size:

ksk-size
--------

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

624
*Default:* 1024 (dsa*), 2048 (rsa*), 256 (ecdsap256*), 384 (ecdsap384*)
625 626 627 628 629 630 631 632

.. _policy_zsk-size:

zsk-size
--------

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

633
*Default:* see default for :ref:`ksk-size<policy_ksk-size>`
634 635 636 637 638 639 640 641 642 643

.. _policy_dnskey-ttl:

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

A TTL value for DNSKEY records added into zone apex.

*Default:* zone SOA TTL

644 645 646
.. NOTE::
   has infuence over ZSK key lifetime

647 648 649 650 651 652 653 654 655
.. _policy_zsk-lifetime:

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

A period between ZSK publication and the next rollover initiation.

*Default:* 30 days

656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671
.. NOTE::
   ZSK key lifetime is also infuenced by propagation-delay and dnskey-ttl

.. _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

.. NOTE::
   has infuence over ZSK key lifetime

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 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717
.. _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

718
.. _policy_nsec3-salt-lifetime:
719

720 721
nsec3-salt-lifetime
-------------------
722 723 724 725 726

A validity period of newly issued salt field.

*Default:* 30 days

727 728 729 730
.. _Remote section:

Remote section
==============
731

732 733
Definitions of remote servers for outgoing connections (source of a zone
transfer, target for a notification, etc.).
734

735
::
736

737 738
 remote:
   - id: STR
739 740
     address: ADDR[@INT] ...
     via: ADDR[@INT] ...
741
     key: key_id
742 743 744

.. _remote_id:

745 746 747 748
id
--

A remote identifier.
749

750
.. _remote_address:
751

752 753
address
-------
754

755 756 757 758
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.
759

760
*Default:* not set
761

762
.. _remote_via:
763

764 765
via
---
766

767 768 769
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.
770

771
*Default:* not set
772

773
.. _remote_key:
774

775 776
key
---
777

Daniel Salzman's avatar
Daniel Salzman committed
778
A :ref:`reference<key_id>` to the TSIG key which is used to authenticate
779
the communication with the remote server.
780

781
*Default:* not set
782

783
.. _Template section:
784

785 786
Template section
================
787

788 789
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)
Daniel Salzman's avatar
Daniel Salzman committed
790
can be used for global querying configuration or as an implicit configuration
791
if a zone doesn't have another template specified.
792 793 794

::

795 796
 template:
   - id: STR
797
     timer-db: STR
Daniel Salzman's avatar
Daniel Salzman committed
798
     global-module: STR/STR ...
799 800 801 802 803 804 805 806 807
     # All zone options (excluding 'template' item)

.. _template_id:

id
--

A template identifier.

808 809 810 811 812 813 814 815
.. _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>`.

816 817
.. NOTE::
   This option is only available in the *default* template.
818 819 820

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

Daniel Salzman's avatar
Daniel Salzman committed
821 822 823 824 825
.. _template_global-module:

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

826
An ordered list of references to query modules in the form of *module_name* or
Daniel Salzman's avatar
Daniel Salzman committed
827 828
*module_name/module_id*. These modules apply to all queries.

829 830
.. NOTE::
   This option is only available in the *default* template.
Daniel Salzman's avatar
Daniel Salzman committed
831

832
*Default:* not set
Daniel Salzman's avatar
Daniel Salzman committed
833

834 835 836 837 838 839 840 841 842 843 844 845
.. _Zone section:

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

Definition of zones served by the server.

::

 zone:
   - domain: DNAME
     template: template_id
846
     storage: STR
847 848
     file: STR
     journal: STR
849
     master: remote_id ...
850
     ddns-master: remote_id
851 852 853 854 855 856
     notify: remote_id ...
     acl: acl_id ...
     semantic-checks: BOOL
     disable-any: BOOL
     zonefile-sync: TIME
     ixfr-from-differences: BOOL
857
     max-journal-size: SIZE
Vitezslav Kriz's avatar
Vitezslav Kriz committed
858
     max-zone-size : SIZE
859
     dnssec-signing: BOOL
860
     dnssec-policy: STR
861
     kasp-db: STR
862
     request-edns-option: INT:[HEXSTR]
863 864
     serial-policy: increment | unixtime
     module: STR/STR ...
865

866
.. _zone_domain:
867

868 869
domain
------
870

871 872 873 874 875 876 877
A zone name identifier.

.. _zone_template:

template
--------

878
A :ref:`reference<template_id>` to a configuration template.
879

880
*Default:* not set or *default* (if the template exists)
881

882 883 884 885 886 887 888 889 890
.. _zone_storage:

storage
-------

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

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

891 892 893 894
.. _zone_file:

file
----
895

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

899 900 901
- ``%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
902 903
  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.
904 905 906
- ``%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.
907
- ``%s`` – means the current zone name in the textual representation (beware
908 909
  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
910
  terminating dot (the result for the root zone is the empty string!).
911
- ``%%`` – means the ``%`` character
912

913
*Default:* :ref:`storage<zone_storage>`/``%s``\ .zone
914

915
.. _zone_journal:
916

917
journal
918
-------
919

920 921 922
A path to the zone journal. Non absolute path is relative to
:ref:`storage<zone_storage>`. The same set of formatters as for
:ref:`file<zone_file>` is supported.
923

924
*Default:* :ref:`storage<zone_storage>`/``%s``\ .db
925

926
.. _zone_master:
927

928 929
master
------
930

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

933
*Default:* not set
934

935 936 937 938 939
.. _zone_ddns-master:

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

940
A :ref:`reference<remote_id>` to zone primary master server.
941 942
If not specified, the first :ref:`master<zone_master>` server is used.

943
*Default:* not set
944

945
.. _zone_notify:
946

947 948
notify
------
949

950 951
An ordered list of :ref:`references<remote_id>` to remotes to which notify
message is sent if the zone changes.
952

953
*Default:* not set
954

955
.. _zone_acl:
956

957 958
acl
---
959

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

963
*Default:* not set
964

965
.. _zone_semantic-checks:
966

967 968
semantic-checks
---------------
969

970
If enabled, extra zone file semantic checks are turned on.
971

972 973 974
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.
975

976
Mandatory checks:
977

978 979 980
- 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)
981

982
Extra checks:
983

984 985 986 987 988 989
- 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
990
- NSEC3 insecure delegation that is not part of Opt-out span
991 992 993 994 995
- 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)
996

997
*Default:* off
998

999
.. _zone_disable-any:
1000

1001 1002
disable-any
-----------
1003

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

1008
*Default:* off
1009

1010
.. _zone_zonefile-sync:
1011 1012 1013

zonefile-sync
-------------
1014

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

1023 1024 1025
.. NOTE::
   If you are serving large zones with frequent updates where
   the immediate sync with a zone file is not desirable, increase the value.
1026

1027
*Default:* 0 (immediate)
1028

1029
.. _zone_ixfr-from-differences:
1030

1031 1032 1033 1034
ixfr-from-differences
---------------------

If enabled, the server creates zone differences from changes you made to the
1035
zone file upon server reload. This option is relevant only if the server