reference.rst 31.7 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 38
There are 12 main sections (``module``, ``server``, ``control``, ``log``,
``statistics``, ``keystore``, ``policy``, ``key``, ``acl``, ``remote``,
``template``, and ``zone``) and module sections with the ``mod-`` prefix.
Most of the sections (excluding ``server``, ``control``, and ``statistics``)
are sequences of settings blocks. Each settings block begins with a unique identifier,
39 40
which can be used as a reference from other sections (such identifier
must be defined in advance).
41

42 43 44 45 46 47 48 49
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
50

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

54
.. _Comments:
55

56 57
Comments
========
58

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

64
.. _Includes:
65

66 67
Includes
========
68

69 70 71 72
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.
73
Matching files are processed in sorted order.
74 75 76

::

77
 include: STR
78

79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
.. _Module section:

Module section
==============

Dynamic modules loading configuration.

.. NOTE::
   If configured with non-empty ```--with-moduledir=path``` parameter, all
   shared modules in this directory will be automatically loaded.

::

 module:
   - id: STR
     file: STR

.. _module_id:

id
--

A module identifier in the form of the ``mod-`` prefix and module name suffix.

.. _module_file:

file
----

A path to a shared library file with the module implementation.

*Default:* ``${libdir}/knot/modules-${version}``/module_name.so
(or ``${path}``/module_name.so if configured with ``--with-moduledir=path``)

.. WARNING::
   If the path is not absolute, the library is searched in the set of
   system directories. See ``man dlopen`` for more details.

117
.. _Server section:
118

119 120
Server section
==============
121

122
General options related to the server.
123 124 125

::

126 127 128 129 130 131 132
 server:
     identity: [STR]
     version: [STR]
     nsid: [STR|HEXSTR]
     rundir: STR
     user: STR[:STR]
     pidfile: STR
133 134
     udp-workers: INT
     tcp-workers: INT
135
     background-workers: INT
136
     async-start: BOOL
137
     tcp-handshake-timeout: TIME
138
     tcp-idle-timeout: TIME
139
     tcp-reply-timeout: TIME
140 141
     max-tcp-clients: INT
     max-udp-payload: SIZE
142 143
     max-ipv4-udp-payload: SIZE
     max-ipv6-udp-payload: SIZE
144 145 146
     listen: ADDR[@INT] ...

.. _server_identity:
147

148 149
identity
--------
150

151
An identity of the server returned in the response to the query for TXT
152
record ``id.server.`` or ``hostname.bind.`` in the CHAOS class (:rfc:`4892`).
153
Set empty value to disable.
154

155
*Default:* FQDN hostname
156

157
.. _server_version:
158

159 160
version
-------
161

162
A version of the server software returned in the response to the query
163
for TXT record ``version.server.`` or ``version.bind.`` in the CHAOS
164
class (:rfc:`4892`). Set empty value to disable.
165

166
*Default:* server version
167

168
.. _server_nsid:
169

170 171
nsid
----
172

173
A DNS name server identifier (:rfc:`5001`). Set empty value to disable.
174

175
*Default:* FQDN hostname
176

177
.. _server_rundir:
178

179 180
rundir
------
181

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

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

186
.. _server_user:
187

188 189
user
----
190

191
A system user with an optional system group (``user:group``) under which the
192 193
server is run after starting and binding to interfaces. Linux capabilities
are employed if supported.
194

195
*Default:* root:root
196

197
.. _server_pidfile:
198

199 200
pidfile
-------
201

202
A PID file location.
203

204
*Default:* :ref:`rundir<server_rundir>`/knot.pid
205

206
.. _server_udp-workers:
207

208 209
udp-workers
-----------
210

211 212
A number of UDP workers (threads) used to process incoming queries
over UDP.
213

214
*Default:* auto-estimated optimal value based on the number of online CPUs
215 216 217 218 219 220

.. _server_tcp-workers:

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

221 222
A number of TCP workers (threads) used to process incoming queries
over TCP.
223

224
*Default:* auto-estimated optimal value based on the number of online CPUs
225

226
.. _server_background-workers:
227

228 229
background-workers
------------------
230

231 232
A number of workers (threads) used to execute background operations (zone
loading, zone updates, etc.).
233

234
*Default:* auto-estimated optimal value based on the number of online CPUs
235

236
.. _server_async-start:
237

238 239
async-start
-----------
240

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

244
*Default:* off
245

246
.. _server_tcp-handshake-timeout:
247

248 249
tcp-handshake-timeout
---------------------
250

251 252 253
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.
254

255
*Default:* 5
256

257 258 259 260 261 262 263 264
.. _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.

265
*Default:* 20
266

267
.. _server_tcp-reply-timeout:
268

269 270
tcp-reply-timeout
-----------------
271

272
Maximum time to wait for an outgoing connection or for a reply to an issued
273
request (SOA, NOTIFY, AXFR...).
274

275
*Default:* 10
276 277

.. _server_max-tcp-clients:
278 279

max-tcp-clients
280 281 282 283
---------------

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

285
*Default:* 100
286

287
.. _server_max-udp-payload:
288 289

max-udp-payload
290
---------------
291

292 293 294 295 296 297 298
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
299
--------------------
300 301 302 303 304 305 306 307

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
308
--------------------
309 310

Maximum EDNS0 UDP payload size for IPv6.
311

312
*Default:* 4096
313

314
.. _server_listen:
315

316 317
listen
------
318

319 320 321 322
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.
323

324
*Default:* not set
325

326
.. _Key section:
327

328 329
Key section
===========
330

331
Shared TSIG keys used to authenticate communication with the server.
332

333
::
334

335 336 337 338
 key:
   - id: DNAME
     algorithm: hmac-md5 | hmac-sha1 | hmac-sha224 | hmac-sha256 | hmac-sha384 | hmac-sha512
     secret: BASE64
339

340
.. _key_id:
341

342 343
id
--
344

345
A key name identifier.
346

347 348 349 350
.. NOTE::
   This value MUST be exactly the same as the name of the TSIG key on the
   opposite master/slave server(s).

351
.. _key_algorithm:
352

353 354 355 356 357
algorithm
---------

A key algorithm.

358
*Default:* not set
359

360
.. _key_secret:
361

362 363
secret
------
364

365
Shared key secret.
366

367
*Default:* not set
368

369 370 371 372 373
.. _ACL section:

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

374 375 376
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.).
377 378 379

::

380 381
 acl:
   - id: STR
382
     address: ADDR[/INT] | ADDR-ADDR ...
383
     key: key_id ...
384
     action: notify | transfer | update ...
385
     deny: BOOL
386

387
.. _acl_id:
388

389 390
id
--
391

392
An ACL rule identifier.
393

394
.. _acl_address:
395

396 397
address
-------
398

399 400
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.
401

402
*Default:* not set
403

404
.. _acl_key:
405

406 407
key
---
408

409
An ordered list of :ref:`reference<key_id>`\ s to TSIG keys. The query must
410
match one of them. Empty value means that transaction authentication is not used.
411

412
*Default:* not set
413

414
.. _acl_action:
415

416 417
action
------
418

419
An ordered list of allowed (or denied) actions.
420

421
Possible values:
422

423 424 425
- ``transfer`` – Allow zone transfer
- ``notify`` – Allow incoming notify
- ``update`` – Allow zone updates
426

427
*Default:* not set
428 429 430 431 432 433

.. _acl_deny:

deny
----

434 435 436
If enabled, instead of allowing, deny the specified :ref:`action<acl_action>`,
:ref:`address<acl_address>`, :ref:`key<acl_key>`, or combination if these
items. If no action is specified, deny all actions.
437

438
*Default:* off
439

440
.. _Control section:
441

442 443
Control section
===============
444

445
Configuration of the server control interface.
446

447
::
448

449
 control:
450
     listen: STR
451
     timeout: TIME
452

453
.. _control_listen:
454

455 456
listen
------
457

458
A UNIX socket path where the server listens for control commands.
459

460
*Default:* :ref:`rundir<server_rundir>`/knot.sock
461

462 463 464 465 466 467 468 469 470
.. _control_timeout:

timeout
-------

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

*Default:* 5

471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513
.. _statistics_section:

Statistics section
==================

Periodic server statistics dumping.

::

  statistics:
      timer: TIME
      file: STR
      append: BOOL

.. _statistics_timer:

timer
-----

A period after which all available statistics metrics will by written to the
:ref:`file<statistics_file>`.

*Default:* not set

.. _statistics_file:

file
----

A file path of statistics output in the YAML format.

*Default:* :ref:`rundir<server_rundir>`/stats.yaml

.. _statistics_append:

append
------

If enabled, the output will be appended to the :ref:`file<statistics_file>`
instead of file replacement.

*Default:* off

514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540
.. _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
541
A key storage backend type. A directory with PEM files or a PKCS #11 storage.
542 543 544 545 546 547 548 549

*Default:* pem

.. _keystore_config:

config
------

550
A backend specific configuration. A directory with PEM files (the path can
551
be specified as a relative path to :ref:`kasp-db<template_kasp-db>`) or
Jan Včelák's avatar
Jan Včelák committed
552
a configuration string for PKCS #11 storage.
553 554

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

557
     "pkcs11:token=knot;pin-value=1234 /usr/lib64/pkcs11/libsofthsm2.so"
558

559
*Default:* :ref:`kasp-db<template_kasp-db>`/keys
560

561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588
.. _Submission section:

Submission section
==================

Parameters of KSK submission checks.

::

 submission:
   - id: STR
     parent: remote_id ...
     check-interval: TIME
     timeout: TIME

.. _submission_id:

id
--

A submission identifier.

.. _submission_parent:

parent
------

A list of :ref:`references<remote_id>` to parent's DNS servers to be checked for
589 590 591
presence of corresponding DS records in the case of KSK submission. All of them must
have a corresponding DS for the rollover to continue. If none is specified, the
rollover must be pushed forward manually.
592

Daniel Salzman's avatar
Daniel Salzman committed
593 594
*Default:* not set

595 596 597 598 599
.. _submission_check-interval:

check-interval
--------------

600 601
Interval for periodic checks of DS presence on parent's DNS servers, in the
case of the KSK submission.
602 603 604 605 606 607 608 609 610

*Default:* 1 hour

.. _submission_timeout:

timeout
-------

After this period, the KSK submission is automatically considered successful, even
Daniel Salzman's avatar
Daniel Salzman committed
611
if all the checks were negative or no parents are configured. Set 0 for infinity.
612

613
*Default:* 0
614

615 616 617 618 619 620 621 622 623 624 625 626 627
.. _Policy section:

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

DNSSEC policy configuration.

::

 policy:
   - id: STR
     keystore: STR
     manual: BOOL
628
     single-type-signing: BOOL
629
     algorithm: rsasha1 | rsasha1-nsec3-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384 | ed25519
630 631
     ksk-size: SIZE
     zsk-size: SIZE
Libor Peltan's avatar
Libor Peltan committed
632
     ksk-shared: BOOL
633 634
     dnskey-ttl: TIME
     zsk-lifetime: TIME
Libor Peltan's avatar
Libor Peltan committed
635
     ksk-lifetime: TIME
636
     propagation-delay: TIME
637 638 639 640
     rrsig-lifetime: TIME
     rrsig-refresh: TIME
     nsec3: BOOL
     nsec3-iterations: INT
Libor Peltan's avatar
Libor Peltan committed
641
     nsec3-opt-out: BOOL
642
     nsec3-salt-length: INT
643
     nsec3-salt-lifetime: TIME
644
     ksk-submission: submission_id
645
     cds-cdnskey-publish: none | delete-dnssec | always
646 647 648 649 650 651 652 653 654 655 656 657 658 659

.. _policy_id:

id
--

A policy identifier.

.. _policy_keystore:

keystore
--------

A :ref:`reference<keystore_id>` to a keystore holding private key material
660
for zones. A special *default* value can be used for the default keystore settings.
661 662 663 664 665 666 667 668 669 670 671 672

*Default:* default

.. _policy_manual:

manual
------

If enabled, automatic key management is not used.

*Default:* off

673 674 675 676 677 678 679 680 681 682 683 684 685 686
.. _policy_single-type-signing:

single-type-signing
-------------------

If enabled, Single-Type Signing Scheme is used in the automatic key management
mode.

.. NOTE::
   Because key rollover is not supported yet, just one combined signing key is
   generated if none is available.

*Default:* off

687 688 689 690 691 692 693
.. _policy_algorithm:

algorithm
---------

An algorithm of signing keys and issued signatures.

694
*Default:* ecdsap256sha256
695

696 697 698
.. NOTE::
   Ed25519 algorithm is only available when compiled with GnuTLS 3.6.0+.

699 700 701 702 703
.. _policy_ksk-size:

ksk-size
--------

704 705
A length of newly generated :abbr:`KSK (Key Signing Key)` or 
:abbr:`CSK (Combined Signing Key)` keys.
706

707
*Default:* 2048 (rsa*), 256 (ecdsap256), 384 (ecdsap384), 256 (ed25519)
708 709 710 711 712 713 714 715

.. _policy_zsk-size:

zsk-size
--------

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

716
*Default:* see default for :ref:`ksk-size<policy_ksk-size>`
717

Libor Peltan's avatar
Libor Peltan committed
718 719 720 721 722 723 724 725
.. _policy_ksk-shared:

ksk-shared
----------

If enabled, all zones with this policy assigned will share one KSK.

*Default:* off
726 727 728 729 730 731 732 733

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

A TTL value for DNSKEY records added into zone apex.

*Default:* zone SOA TTL

734 735 736
.. NOTE::
   has infuence over ZSK key lifetime

737 738 739 740 741 742 743 744 745
.. _policy_zsk-lifetime:

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

A period between ZSK publication and the next rollover initiation.

*Default:* 30 days

746 747 748
.. NOTE::
   ZSK key lifetime is also infuenced by propagation-delay and dnskey-ttl

749 750
   Zero (aka infinity) value causes no ZSK rollover as a result.

Libor Peltan's avatar
Libor Peltan committed
751 752 753 754 755 756 757
.. _policy_ksk-lifetime:

ksk-lifetime
------------

A period between KSK publication and the next rollover initiation.

758
*Default:* 0
Libor Peltan's avatar
Libor Peltan committed
759 760 761

.. NOTE::
   KSK key lifetime is also infuenced by propagation-delay, dnskey-ttl,
762
   and KSK submission delay.
Libor Peltan's avatar
Libor Peltan committed
763

764
   Zero (aka infinity) value causes no KSK rollover as a result.
Libor Peltan's avatar
Libor Peltan committed
765

766 767
   This applies for CSK lifetime if single-type-signing is enabled.

768 769 770 771 772 773 774 775 776 777 778 779 780
.. _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

781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816
.. _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

Libor Peltan's avatar
Libor Peltan committed
817 818 819 820 821 822 823 824 825 826 827 828 829 830
.. _policy_nsec3-opt-out:

nsec3-opt-out
-------------

If set, NSEC3 records won't be created for insecure delegations.
This speeds up the zone signing and reduces overall zone size.

.. WARNING::
  NSEC3 with the Opt-Out bit set no longer works as a proof of non-existence
  in this zone.

*Default:* off

831 832 833 834 835 836 837 838 839 840
.. _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

841
.. _policy_nsec3-salt-lifetime:
842

843 844
nsec3-salt-lifetime
-------------------
845 846 847 848 849

A validity period of newly issued salt field.

*Default:* 30 days

850
.. _policy_ksk-submission-check:
Libor Peltan's avatar
Libor Peltan committed
851

852 853
ksk-submission
--------------
Libor Peltan's avatar
Libor Peltan committed
854

855 856
A reference to :ref:`submission<submission_id>` section holding parameters of
KSK submittion checks.
Libor Peltan's avatar
Libor Peltan committed
857 858 859

*Default:* not set

860
.. _policy_cds-cdnskey-publish:
861

862 863
cds-cdnskey-publish
-------------------
864 865 866 867 868 869 870 871 872

Controls if and how shall the CDS and CDNSKEY be published in the zone.

.. NOTE::
   This only applies if the zone keys are automatically managed by the server.

Possible values:

- ``none`` - never publish any CDS or CDNSKEY records in the zone
873
- ``delete-dnssec`` - publish special CDS and CDNSKEY records indicating turning off DNSSEC
874 875 876 877
- ``always`` - always publish CDS and CDNSKEY records for the current KSK

*Default:* always

878 879 880 881
.. _Remote section:

Remote section
==============
882

883 884
Definitions of remote servers for outgoing connections (source of a zone
transfer, target for a notification, etc.).
885

886
::
887

888 889
 remote:
   - id: STR
890 891
     address: ADDR[@INT] ...
     via: ADDR[@INT] ...
892
     key: key_id
893 894 895

.. _remote_id:

896 897 898 899
id
--

A remote identifier.
900

901
.. _remote_address:
902

903 904
address
-------
905

906 907 908 909
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.
910

911
*Default:* not set
912

913
.. _remote_via:
914

915 916
via
---
917

918 919 920
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.
921

922
*Default:* not set
923

924
.. _remote_key:
925

926 927
key
---
928

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

932
*Default:* not set
933

934
.. _Template section:
935

936 937
Template section
================
938

939 940
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)
941
can be used for global querying configuration or as an implicit configuration
942
if a zone doesn't have another template specified.
943 944 945

::

946 947
 template:
   - id: STR
948
     timer-db: STR
949
     max-timer-db-size: SIZE
950
     journal-db: STR
951
     journal-db-mode: robust | asynchronous
952
     max-journal-db-size: SIZE
953 954
     kasp-db: STR
     max-kasp-db-size: SIZE
955
     global-module: STR/STR ...
956 957 958 959 960 961 962 963 964
     # All zone options (excluding 'template' item)

.. _template_id:

id
--

A template identifier.

965 966 967 968 969 970 971 972
.. _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>`.

973 974
.. NOTE::
   This option is only available in the *default* template.
975 976 977

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

978 979 980 981 982 983 984 985 986 987 988 989
.. _template_max-timer-db-size:

max-timer-db-size
-----------------

Hard limit for the timer database maximum size.

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

*Default:* 100 MiB

990 991 992 993 994 995 996 997 998 999 1000 1001 1002
.. _template_journal-db:

journal-db
----------

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

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

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

1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015
.. _template_journal-db-mode:

journal-db-mode
---------------

Specifies journal LMDB backend configuration, which influences performance
and durability.

Possible values:

- ``robust`` – The journal DB disk sychronization ensures DB durability but is
  generally slower
- ``asynchronous`` – The journal DB disk synchronization is optimized for
1016
  better performance at the expense of lower DB durability; this mode is
1017 1018 1019 1020 1021 1022 1023
  recommended only on slave nodes with many zones

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

*Default:* robust

1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035
.. _template_max-journal-db-size:

max-journal-db-size
-------------------

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.

It is recommended to limit :ref:`max-journal-usage<zone_max-journal-usage>`
per-zone instead of max-journal-size in most cases. Please keep this value
1036 1037
larger than the sum of all zones' journal usage limits. See more details
regarding :ref:`journal behaviour<Journal behaviour>`.
1038 1039

This value also influences server's usage of virtual memory.
1040 1041 1042 1043

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

1044
*Default:* 20 GiB (1 GiB for 32-bit)
1045

1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070
.. _template_kasp-db:

kasp-db
-------

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

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

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

.. _template_max-kasp-db-size:

max-kasp-db-size
----------------

Hard limit for the KASP database maximum size.

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

*Default:* 500 MiB

1071 1072 1073 1074 1075
.. _template_global-module:

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

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

1079 1080
.. NOTE::
   This option is only available in the *default* template.
1081

1082
*Default:* not set
1083

1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095
.. _Zone section:

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

Definition of zones served by the server.

::

 zone:
   - domain: DNAME
     template: template_id
1096
     storage: STR
1097
     file: STR
1098
     master: remote_id ...
1099
     ddns-master: remote_id
1100 1101 1102 1103 1104
     notify: remote_id ...
     acl: acl_id ...
     semantic-checks: BOOL
     disable-any: BOOL
     zonefile-sync: TIME
1105 1106
     zonefile-load: none | difference | whole
     journal-content: none | changes | all
1107 1108
     max-journal-usage: SIZE
     max-journal-depth: INT
Vitezslav Kriz's avatar
Vitezslav Kriz committed
1109
     max-zone-size : SIZE
1110
     dnssec-signing: BOOL
1111
     dnssec-policy: STR
1112
     request-edns-option: INT:[HEXSTR]
1113
     serial-policy: increment | unixtime | dateserial
1114 1115
     min-refresh-interval: TIME
     max-refresh-interval: TIME
1116
     module: STR/STR ...
1117

1118
.. _zone_domain:
1119

1120 1121
domain
------
1122

1123 1124 1125 1126 1127 1128 1129
A zone name identifier.

.. _zone_template:

template
--------

1130
A :ref:`reference<template_id>` to a configuration template.
1131

1132
*Default:* not set or *default* (if the template exists)
1133

1134 1135 1136 1137 1138
.. _zone_storage:

storage
-------

1139
A data directory for storing zone files, journal database, and timers database.
1140 1141 1142

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

1143 1144 1145 1146
.. _zone_file:

file
----
1147

1148
A path to the zone file. Non-absolute path is relative to
1149
:ref:`storage<zone_storage>`. It is also possible to use the following formatters:
1150

1151 1152 1153
- ``%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
1154 1155
  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.
1156 1157 1158
- ``%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.
1159 1160 1161
- ``%s`` – means the current zone name in the textual representation.
  The zone name doesn't include the terminating dot (the result for the root
  zone is the empty string!).
1162
- ``%%`` – means the ``%`` character
1163

1164 1165 1166 1167
.. WARNING::
  Beware of special characters which are escaped or encoded in the \\DDD form
  where DDD is corresponding decimal ASCII code.

1168
*Default:* :ref:`storage<zone_storage>`/``%s``\ .zone
1169 1170

.. _zone_master:
1171

1172 1173
master
------
1174

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

1177
*Default:* not set
1178

1179 1180 1181 1182 1183
.. _zone_ddns-master:

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

1184
A :ref:`reference<remote_id>` to zone primary master server.
1185 1186
If not specified, the first :ref:`master<zone_master>` server is used.

1187
*Default:* not set
1188

1189
.. _zone_notify:
1190

1191 1192
notify
------
1193

1194 1195
An ordered list of :ref:`references<remote_id>` to remotes to which notify
message is sent if the zone changes.
1196

1197
*Default:* not set
1198

1199
.. _zone_acl:
1200

1201 1202
acl
---
1203

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

1207
*Default:* not set
1208

1209
.. _zone_semantic-checks:
1210

1211 1212
semantic-checks
---------------
1213

1214
If enabled, extra zone file semantic checks are turned on.
1215

1216 1217 1218
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.
1219

1220
Mandatory checks:
1221

1222 1223
- SOA record missing in the zone (:rfc:`1034`)
- An extra record together with CNAME record except for RRSIG and DS (:rfc:`1034`)
1224
- Multiple CNAME record with the same owner
1225
- DNAME record having a record under it (:rfc:`2672`)
1226

1227
Extra checks:
1228

1229
- Missing NS record at the zone apex
1230 1231 1232 1233 1234
- Missing glue A or AAAA record
- Invalid DNSKEY, DS, or NSEC3PARAM record
- CDS or CDNSKEY inconsistency
- Missing, invalid, or unverifiable RRSIG record
- Invalid NSEC(3) record
1235
- Broken or non-cyclic NSEC(3) chain
1236

1237
*Default:* off
1238

1239
.. _zone_disable-any:
1240

1241 1242
disable-any
-----------
1243

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

1248
*Default:* off
1249

1250
.. _zone_zonefile-sync:
1251 1252 1253

zonefile-sync
-------------
1254

1255
The time after which the current zone in memory will be synced with a zone file
1256
on the disk (see :ref:`file<zone_file>`). The server will serve the latest
1257
zone even after a restart using zone journal, but the zone file on the disk will
1258
only be synced after ``zonefile-sync`` time has expired (or after manual zone
1259
flush). This is applicable when the zone is updated via IXFR, DDNS or automatic
1260 1261 1262
DNSSEC signing. In order to completely disable automatic zonefile synchronization,
set the value to -1. In that case, it is still possible to force a manual zone flush
using the ``-f`` option.
1263

1264 1265 1266
.. NOTE::
   If you are serving large zones with frequent updates where
   the immediate sync with a zone file is not desirable, increase the value.
1267

1268
*Default:* 0 (immediate)
1269

1270
.. _zone_zonefile-load:
1271

1272 1273
zonefile-load
-------------
1274

1275
Selects how the zonefile contents are applied during zone load.
1276

1277
Possible values:
1278

1279 1280 1281 1282
- ``none`` – The zonefile is not used at all.
- ``difference`` – If the zone contents are available during server start or reload,
  the difference is computed between them and the zonefile, checked and applied afterwards.
- ``whole`` – Zone contents are loaded from zonefile.
1283

1284 1285
When ``difference`` is configured and there are no zone contents yet (cold start of Knot
and no zone contents in journal), it behaves the same way like ``whole``.
1286

1287
*Default:* whole
1288

1289
.. _zone_journal-content:
1290

1291 1292
journal-content
---------------
1293

1294
Selects how the journal shall be used to store zone and its changes.
1295

1296 1297 1298 1299 1300 1301 1302
Possible values:

- ``none`` – The journal is not used at all.
- ``changes`` – Zone changes history is stored in journal.
- ``all`` – Zone contents and history is stored in journal.

*Default:* changes
1303

1304
.. _zone_max-journal-usage:
1305

1306 1307
max-journal-usage
-----------------
1308

1309
Policy how much space in journal DB will the zone's journal occupy.
1310

1311
*Default:* 100 MiB
1312 1313

.. NOTE::
1314 1315 1316 1317 1318 1319 1320 1321 1322 1323
   Journal DB may grow far above the sum of max-journal-usage across
   all zones, because of DB free space fragmentation.

.. _zone_max_journal_depth:

max-journal-depth
-----------------

Maximum history length of journal.

1324 1325
*Minimum:* 2

1326
*Default:* 2^64
1327

Vitezslav Kriz's avatar
Vitezslav Kriz committed
1328 1329 1330 1331 1332
.. _zone_max_zone_size:

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

1333 1334
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
1335
transfers and dynamic updates.
1336 1337 1338 1339

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
1340 1341 1342

*Default:* 2^64

1343
.. _zone_dnssec-signing:
1344

1345 1346
dnssec-signing
--------------
1347

1348
If enabled, automatic DNSSEC signing for the zone is turned on.
1349

1350
*Default:* off
1351

1352 1353 1354 1355 1356
.. _zone_dnssec-policy:

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

1357 1358
A :ref:`reference<policy_id>` to DNSSEC signing policy. A special *default*
value can be used for the default policy settings.
1359

1360
*Required*
1361

1362 1363 1364 1365 1366 1367 1368 1369
.. _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.

1370
*Default:* not set
1371

1372
.. _zone_serial-policy:
1373

1374 1375
serial-policy
-------------
1376