1.. highlight:: none 2.. _Configuration Reference: 3 4*********************** 5Configuration Reference 6*********************** 7 8.. _Description: 9 10Description 11=========== 12 13Configuration files for Knot DNS use simplified YAML format. Simplified means 14that not all of the features are supported. 15 16For the description of configuration items, we have to declare a meaning of 17the following symbols: 18 19- *INT* – Integer 20- *STR* – Textual string 21- *HEXSTR* – Hexadecimal string (with ``0x`` prefix) 22- *BOOL* – Boolean value (``on``/``off`` or ``true``/``false``) 23- *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- *BASE64* – Base64 encoded string 28- *ADDR* – IPv4 or IPv6 address 29- *DNAME* – Domain name 30- ... – Multi-valued item, order of the values is preserved 31- [ ] – Optional value 32- \| – Choice 33 34The configuration consists of several fixed sections and optional module 35sections. There are 15 fixed sections (``module``, ``server``, ``xdp``, ``control``, 36``log``, ``statistics``, ``database``, ``keystore``, ``key``, ``remote``, 37``acl``, ``submission``, ``policy``, ``template``, ``zone``). 38Module sections are prefixed with the ``mod-`` prefix (e.g. ``mod-stats``). 39 40Most of the sections (e.g. ``zone``) are sequences of settings blocks. Each 41settings block begins with a unique identifier, which can be used as a reference 42from other sections (such an identifier must be defined in advance). 43 44A multi-valued item can be specified either as a YAML sequence:: 45 46 address: [10.0.0.1, 10.0.0.2] 47 48or as more single-valued items each on an extra line:: 49 50 address: 10.0.0.1 51 address: 10.0.0.2 52 53If an item value contains spaces or other special characters, it is necessary 54to enclose such a value within double quotes ``"`` ``"``. 55 56.. _Comments: 57 58Comments 59======== 60 61A comment begins with a ``#`` character and is ignored during processing. 62Also each configuration section or sequence block allows a permanent 63comment using the ``comment`` item which is stored in the server beside the 64configuration. 65 66.. _Includes: 67 68Includes 69======== 70 71Another configuration file or files, matching a pattern, can be included at 72the top level in the current file. If the path is not absolute, then it 73is considered to be relative to the current file. The pattern can be 74an arbitrary string meeting POSIX *glob* requirements, e.g. dir/\*.conf. 75Matching files are processed in sorted order. 76 77:: 78 79 include: STR 80 81.. _Module section: 82 83Module section 84============== 85 86Dynamic modules loading configuration. 87 88.. NOTE:: 89 If configured with non-empty ```--with-moduledir=path``` parameter, all 90 shared modules in this directory will be automatically loaded. 91 92:: 93 94 module: 95 - id: STR 96 file: STR 97 98.. _module_id: 99 100id 101-- 102 103A module identifier in the form of the ``mod-`` prefix and module name suffix. 104 105.. _module_file: 106 107file 108---- 109 110A path to a shared library file with the module implementation. 111 112.. WARNING:: 113 If the path is not absolute, the library is searched in the set of 114 system directories. See ``man dlopen`` for more details. 115 116*Default:* ``${libdir}/knot/modules-${version}``/module_name.so 117(or ``${path}``/module_name.so if configured with ``--with-moduledir=path``) 118 119.. _Server section: 120 121Server section 122============== 123 124General options related to the server. 125 126:: 127 128 server: 129 identity: [STR] 130 version: [STR] 131 nsid: [STR|HEXSTR] 132 rundir: STR 133 user: STR[:STR] 134 pidfile: STR 135 udp-workers: INT 136 tcp-workers: INT 137 background-workers: INT 138 async-start: BOOL 139 tcp-idle-timeout: TIME 140 tcp-io-timeout: INT 141 tcp-remote-io-timeout: INT 142 tcp-max-clients: INT 143 tcp-reuseport: BOOL 144 tcp-fastopen: BOOL 145 remote-pool-limit: INT 146 remote-pool-timeout: TIME 147 remote-retry-delay: TIME 148 socket-affinity: BOOL 149 udp-max-payload: SIZE 150 udp-max-payload-ipv4: SIZE 151 udp-max-payload-ipv6: SIZE 152 edns-client-subnet: BOOL 153 answer-rotation: BOOL 154 listen: ADDR[@INT] ... 155 156.. CAUTION:: 157 When you change configuration parameters dynamically or via configuration file 158 reload, some parameters in the Server section require restarting the Knot server 159 so that the changes take effect. See below for the details. 160 161.. _server_identity: 162 163identity 164-------- 165 166An identity of the server returned in the response to the query for TXT 167record ``id.server.`` or ``hostname.bind.`` in the CHAOS class (:rfc:`4892`). 168Set to an empty value to disable. 169 170*Default:* FQDN hostname 171 172.. _server_version: 173 174version 175------- 176 177A version of the server software returned in the response to the query 178for TXT record ``version.server.`` or ``version.bind.`` in the CHAOS 179class (:rfc:`4892`). Set to an empty value to disable. 180 181*Default:* server version 182 183.. _server_nsid: 184 185nsid 186---- 187 188A DNS name server identifier (:rfc:`5001`). Set to an empty value to disable. 189 190*Default:* FQDN hostname at the moment of the daemon start 191 192.. _server_rundir: 193 194rundir 195------ 196 197A path for storing run-time data (PID file, unix sockets, etc.). 198 199Depending on the usage of this parameter, its change may require restart of the Knot 200server to take effect. 201 202*Default:* ``${localstatedir}/run/knot`` (configured with ``--with-rundir=path``) 203 204.. _server_user: 205 206user 207---- 208 209A system user with an optional system group (``user:group``) under which the 210server is run after starting and binding to interfaces. Linux capabilities 211are employed if supported. 212 213Change of this parameter requires restart of the Knot server to take effect. 214 215*Default:* root:root 216 217.. _server_pidfile: 218 219pidfile 220------- 221 222A PID file location. 223 224Change of this parameter requires restart of the Knot server to take effect. 225 226*Default:* :ref:`rundir<server_rundir>`/knot.pid 227 228.. _server_udp-workers: 229 230udp-workers 231----------- 232 233A number of UDP workers (threads) used to process incoming queries 234over UDP. 235 236Change of this parameter requires restart of the Knot server to take effect. 237 238*Default:* equal to the number of online CPUs 239 240.. _server_tcp-workers: 241 242tcp-workers 243----------- 244 245A number of TCP workers (threads) used to process incoming queries 246over TCP. 247 248Change of this parameter requires restart of the Knot server to take effect. 249 250*Default:* equal to the number of online CPUs, default value is at least 10 251 252.. _server_background-workers: 253 254background-workers 255------------------ 256 257A number of workers (threads) used to execute background operations (zone 258loading, zone updates, etc.). 259 260Change of this parameter requires restart of the Knot server to take effect. 261 262*Default:* equal to the number of online CPUs, default value is at most 10 263 264.. _server_async-start: 265 266async-start 267----------- 268 269If enabled, server doesn't wait for the zones to be loaded and starts 270responding immediately with SERVFAIL answers until the zone loads. 271 272*Default:* off 273 274.. _server_tcp-idle-timeout: 275 276tcp-idle-timeout 277---------------- 278 279Maximum idle time (in seconds) between requests on an inbound TCP connection. 280It means if there is no activity on an inbound TCP connection during this limit, 281the connection is closed by the server. 282 283*Minimum:* 1 s 284 285*Default:* 10 s 286 287.. _server_tcp-io-timeout: 288 289tcp-io-timeout 290-------------- 291 292Maximum time (in milliseconds) to receive or send one DNS message over an inbound 293TCP connection. It means this limit applies to normal DNS queries and replies, 294incoming DDNS, and **outgoing zone transfers**. The timeout is measured since some 295data is already available for processing. 296Set to 0 for infinity. 297 298*Default:* 500 ms 299 300.. CAUTION:: 301 In order to reduce the risk of Slow Loris attacks, it's recommended setting 302 this limit as low as possible on public servers. 303 304.. _server_tcp-remote-io-timeout: 305 306tcp-remote-io-timeout 307--------------------- 308 309Maximum time (in milliseconds) to receive or send one DNS message over an outbound 310TCP connection which has already been established to a configured remote server. 311It means this limit applies to incoming zone transfers, sending NOTIFY, 312DDNS forwarding, and DS check or push. This timeout includes the time needed 313for a network round-trip and for a query processing by the remote. 314Set to 0 for infinity. 315 316*Default:* 5000 ms 317 318.. _server_tcp-reuseport: 319 320tcp-reuseport 321------------- 322 323If enabled, each TCP worker listens on its own socket and the OS kernel 324socket load balancing is employed using SO_REUSEPORT (or SO_REUSEPORT_LB 325on FreeBSD). Due to the lack of one shared socket, the server can offer 326higher response rate processing over TCP. However, in the case of 327time-consuming requests (e.g. zone transfers of a TLD zone), enabled reuseport 328may result in delayed or not being responded client requests. So it is 329advisable to use this option on secondary servers. 330 331Change of this parameter requires restart of the Knot server to take effect. 332 333*Default:* off 334 335.. _server_tcp-fastopen: 336 337tcp-fastopen 338------------ 339 340If enabled, use TCP Fast Open for outbound TCP communication (client side): 341incoming zone transfers, sending NOTIFY, and DDNS forwarding. This mode simplifies 342TCP handshake and can result in better networking performance. TCP Fast Open 343for inbound TCP communication (server side) isn't affected by this 344configuration as it's enabled automatically if supported by OS. 345 346.. NOTE:: 347 The TCP Fast Open support must also be enabled on the OS level: 348 349 * Linux/macOS: ensure kernel parameter ``net.ipv4.tcp_fastopen`` is ``2`` or 350 ``3`` for server side, and ``1`` or ``3`` for client side. 351 * FreeBSD: ensure kernel parameter ``net.inet.tcp.fastopen.server_enable`` 352 is ``1`` for server side, and ``net.inet.tcp.fastopen.client_enable`` is 353 ``1`` for client side. 354 355*Default:* off 356 357.. _server_remote-pool-limit: 358 359remote-pool-limit 360----------------- 361 362If nonzero, the server will keep up to this number of outgoing TCP connections 363open for later use. This is an optimization to avoid frequent opening of 364TCP connections to the same remote. 365 366Change of this parameter requires restart of the Knot server to take effect. 367 368*Default:* 0 369 370.. _server_remote-pool-timeout: 371 372remote-pool-timeout 373------------------- 374 375The timeout in seconds after which the unused kept-open outgoing TCP connections 376to remote servers are closed. 377 378*Default:* 5 379 380.. _server_remote-retry-delay: 381 382remote-retry-delay 383------------------ 384 385When a connection attempt times out to some remote address, this information will be 386kept for this specified time (in milliseconds) and other connections to the same address won't 387be attempted. This prevents repetitive waiting for timeout on an unreachable remote. 388 389*Default:* 0 390 391.. _server_socket-affinity: 392 393socket-affinity 394--------------- 395 396If enabled and if SO_REUSEPORT is available on Linux, all configured network 397sockets are bound to UDP and TCP workers in order to increase the networking performance. 398This mode isn't recommended for setups where the number of network card queues 399is lower than the number of UDP or TCP workers. 400 401Change of this parameter requires restart of the Knot server to take effect. 402 403*Default:* off 404 405.. _server_tcp-max-clients: 406 407tcp-max-clients 408--------------- 409 410A maximum number of TCP clients connected in parallel, set this below the file 411descriptor limit to avoid resource exhaustion. 412 413.. NOTE:: 414 It is advisable to adjust the maximum number of open files per process in your 415 operating system configuration. 416 417*Default:* one half of the file descriptor limit for the server process 418 419.. _server_udp-max-payload: 420 421udp-max-payload 422--------------- 423 424Maximum EDNS0 UDP payload size default for both IPv4 and IPv6. 425 426*Default:* 1232 427 428.. _server_udp-max-payload-ipv4: 429 430udp-max-payload-ipv4 431-------------------- 432 433Maximum EDNS0 UDP payload size for IPv4. 434 435*Default:* 1232 436 437.. _server_udp-max-payload-ipv6: 438 439udp-max-payload-ipv6 440-------------------- 441 442Maximum EDNS0 UDP payload size for IPv6. 443 444*Default:* 1232 445 446.. _server_edns-client-subnet: 447 448edns-client-subnet 449------------------ 450 451Enable or disable EDNS Client Subnet support. If enabled, responses to queries 452containing the EDNS Client Subnet option 453always contain a valid EDNS Client Subnet option according to :rfc:`7871`. 454 455*Default:* off 456 457.. _server_answer-rotation: 458 459answer-rotation 460--------------- 461 462Enable or disable sorted-rrset rotation in the answer section of normal replies. 463The rotation shift is simply determined by a query ID. 464 465*Default:* off 466 467.. _server_listen: 468 469listen 470------ 471 472One or more IP addresses where the server listens for incoming queries. 473Optional port specification (default is 53) can be appended to each address 474using ``@`` separator. Use ``0.0.0.0`` for all configured IPv4 addresses or 475``::`` for all configured IPv6 addresses. Filesystem path can be specified 476for listening on local unix SOCK_STREAM socket. Non-local address binding 477is automatically enabled if supported by the operating system. 478 479Change of this parameter requires restart of the Knot server to take effect. 480 481*Default:* not set 482 483.. _XDP section: 484 485XDP section 486=========== 487 488Various options related to XDP listening, especially TCP. 489 490:: 491 492 xdp: 493 listen: STR[@INT] | ADDR[@INT] ... 494 tcp: BOOL 495 tcp-max-clients: INT 496 tcp-inbuf-max-size: SIZE 497 tcp-idle-close-timeout: TIME 498 tcp-idle-reset-timeout: TIME 499 route-check: BOOL 500 501.. CAUTION:: 502 When you change configuration parameters dynamically or via configuration file 503 reload, some parameters in the XDP section require restarting the Knot server 504 so that the changes take effect. 505 506.. _xdp_listen: 507 508listen 509------ 510 511One or more network device names (e.g. ``ens786f0``) on which the :ref:`Mode XDP` 512is enabled. Alternatively, an IP address can be used instead of a device name, 513but the server will still listen on all addresses belonging to the same interface! 514Optional port specification (default is 53) can be appended to each device name 515or address using ``@`` separator. 516 517Change of this parameter requires restart of the Knot server to take effect. 518 519.. CAUTION:: 520 If XDP workers only process regular DNS traffic over UDP, it is strongly 521 recommended to also :ref:`listen <server_listen>` on the addresses which are 522 intended to offer the DNS service, at least to fulfil the DNS requirement for 523 working TCP. 524 525*Default:* not set 526 527.. _xdp_tcp: 528 529tcp 530--- 531 532If enabled, DNS over TCP traffic is also processed with XDP workers. 533 534The TCP stack features: 535 536- Basic connection handling, sending/receiving data 537- Close inactive connections 538- Reset inactive connections which aren't able to close 539- Reset invalid connections 540- Ignore invalid resets and ACKs 541- Receive fragmented data – one DNS message in multiple packets 542- Limit total size of incoming buffers, reset most inactive connections 543 with buffered data 544- Send fragmented data – DNS message larger than allowed by MSS 545- Send MSS option calculated from configured MSS and device MTU 546- Receive and honor MSS option, limit the size of outgoing packet 547- Send window size option (set to infinity) 548 549Missing features: 550 551- Receive and honor window size option, send only such amount of data at once, 552 cache outgoing data 553- Allow multi-message DNS responses (depends on above) 554- Resend lost outgoing packets (not ACKed in time), including data 555 556Change of this parameter requires restart of the Knot server to take effect. 557 558.. WARNING:: 559 This feature is experimental and it may eat your hamster as well as any 560 other hamsters connected to the network. 561 562*Default:* off 563 564.. _xdp_tcp-max-clients: 565 566tcp-max-clients 567--------------- 568 569A maximum number of TCP clients connected in parallel. 570 571*Default:* 1000000 (one million) 572 573.. _xdp_tcp-inbuf-max-size: 574 575tcp-inbuf-max-size 576------------------ 577 578Maximum cumulative size of memory used for buffers of incompletely 579received messages. 580 581*Minimum:* 1 MiB 582 583*Default:* 100 MiB 584 585.. _xdp_tcp-idle-close-timeout: 586 587tcp-idle-close-timeout 588---------------------- 589 590Time in seconds, after which any idle connection is gracefully closed. 591 592*Minimum:* 1 s 593 594*Default:* 10 s 595 596.. _xdp_tcp-idle-reset-timeout: 597 598tcp-idle-reset-timeout 599---------------------- 600 601Time in seconds, after which any idle connection is forcibly closed. 602 603*Minimum:* 1 s 604 605*Default:* 20 s 606 607.. _xdp_route-check: 608 609route-check 610----------- 611 612If enabled, routing information from the operating system is considered 613when processing every incoming DNS packet received over the XDP interface: 614 615- If the outgoing interface of the corresponding DNS response differs from 616 the incoming one, the packet is processed normally by UDP/TCP workers 617 (XDP isn't used). 618- If the destination address is blackholed, unreachable, or prohibited, 619 the DNS packet is dropped without any response. 620- The destination MAC address for the response is taken from the routing system. 621 622If disabled, symmetrical routing is applied. It means that the query source 623MAC address is used as a response destination MAC address. 624 625Change of this parameter requires restart of the Knot server to take effect. 626 627.. NOTE:: 628 This mode requires forwarding enabled on the loopback interface 629 (``sysctl -w net.ipv4.conf.lo.forwarding=1`` and ``sysctl -w net.ipv6.conf.lo.forwarding=1``). 630 If forwarding is disabled, all incoming DNS packets are dropped! 631 632*Default:* off 633 634.. _Control section: 635 636Control section 637=============== 638 639Configuration of the server control interface. 640 641:: 642 643 control: 644 listen: STR 645 timeout: TIME 646 647.. _control_listen: 648 649listen 650------ 651 652A UNIX socket path where the server listens for control commands. 653 654*Default:* :ref:`rundir<server_rundir>`/knot.sock 655 656.. _control_timeout: 657 658timeout 659------- 660 661Maximum time (in seconds) the control socket operations can take. 662Set to 0 for infinity. 663 664*Default:* 5 665 666.. _Logging section: 667 668Logging section 669=============== 670 671Server can be configured to log to the standard output, standard error 672output, syslog (or systemd journal if systemd is enabled) or into an arbitrary 673file. 674 675There are 6 logging severity levels: 676 677- ``critical`` – Non-recoverable error resulting in server shutdown. 678- ``error`` – Recoverable error, action should be taken. 679- ``warning`` – Warning that might require user action. 680- ``notice`` – Server notice or hint. 681- ``info`` – Informational message. 682- ``debug`` – Debug or detailed message. 683 684In the case of a missing log section, ``warning`` or more serious messages 685will be logged to both standard error output and syslog. The ``info`` and 686``notice`` messages will be logged to standard output. 687 688:: 689 690 log: 691 - target: stdout | stderr | syslog | STR 692 server: critical | error | warning | notice | info | debug 693 control: critical | error | warning | notice | info | debug 694 zone: critical | error | warning | notice | info | debug 695 any: critical | error | warning | notice | info | debug 696 697.. _log_target: 698 699target 700------ 701 702A logging output. 703 704Possible values: 705 706- ``stdout`` – Standard output. 707- ``stderr`` – Standard error output. 708- ``syslog`` – Syslog or systemd journal. 709- *file\_name* – A specific file. 710 711With ``syslog`` target, syslog service is used. However, if Knot DNS has been compiled 712with systemd support and operating system has been booted with systemd, systemd journal 713is used for logging instead of syslog. 714 715.. _log_server: 716 717server 718------ 719 720Minimum severity level for messages related to general operation of the server to be 721logged. 722 723*Default:* not set 724 725.. _log_control: 726 727control 728------- 729 730Minimum severity level for messages related to server control to be logged. 731 732*Default:* not set 733 734.. _log_zone: 735 736zone 737---- 738 739Minimum severity level for messages related to zones to be logged. 740 741*Default:* not set 742 743.. _log_any: 744 745any 746--- 747 748Minimum severity level for all message types to be logged. 749 750*Default:* not set 751 752.. _statistics_section: 753 754Statistics section 755================== 756 757Periodic server statistics dumping. 758 759:: 760 761 statistics: 762 timer: TIME 763 file: STR 764 append: BOOL 765 766.. _statistics_timer: 767 768timer 769----- 770 771A period after which all available statistics metrics will by written to the 772:ref:`file<statistics_file>`. 773 774*Default:* not set 775 776.. _statistics_file: 777 778file 779---- 780 781A file path of statistics output in the YAML format. 782 783*Default:* :ref:`rundir<server_rundir>`/stats.yaml 784 785.. _statistics_append: 786 787append 788------ 789 790If enabled, the output will be appended to the :ref:`file<statistics_file>` 791instead of file replacement. 792 793*Default:* off 794 795.. _Database section: 796 797Database section 798================ 799 800Configuration of databases for zone contents, DNSSEC metadata, or event timers. 801 802:: 803 804 database: 805 storage: STR 806 journal-db: STR 807 journal-db-mode: robust | asynchronous 808 journal-db-max-size: SIZE 809 kasp-db: STR 810 kasp-db-max-size: SIZE 811 timer-db: STR 812 timer-db-max-size: SIZE 813 catalog-db: str 814 catalog-db-max-size: SIZE 815 816.. _database_storage: 817 818storage 819------- 820 821A data directory for storing journal, KASP, and timer databases. 822 823*Default:* ``${localstatedir}/lib/knot`` (configured with ``--with-storage=path``) 824 825.. _database_journal-db: 826 827journal-db 828---------- 829 830An explicit specification of the persistent journal database directory. 831Non-absolute path (i.e. not starting with ``/``) is relative to 832:ref:`storage<database_storage>`. 833 834*Default:* :ref:`storage<database_storage>`/journal 835 836.. _database_journal-db-mode: 837 838journal-db-mode 839--------------- 840 841Specifies journal LMDB backend configuration, which influences performance 842and durability. 843 844Possible values: 845 846- ``robust`` – The journal database disk synchronization ensures database 847 durability but is generally slower. 848- ``asynchronous`` – The journal database disk synchronization is optimized for 849 better performance at the expense of lower database durability in the case of 850 a crash. This mode is recommended on secondary servers with many zones. 851 852*Default:* robust 853 854.. _database_journal-db-max-size: 855 856journal-db-max-size 857------------------- 858 859The hard limit for the journal database maximum size. There is no cleanup logic 860in journal to recover from reaching this limit. Journal simply starts refusing 861changes across all zones. Decreasing this value has no effect if it is lower 862than the actual database file size. 863 864It is recommended to limit :ref:`journal-max-usage<zone_journal-max-usage>` 865per-zone instead of :ref:`journal-db-max-size<database_journal-db-max-size>` 866in most cases. Please keep this value larger than the sum of all zones' 867journal usage limits. See more details regarding 868:ref:`journal behaviour<Journal behaviour>`. 869 870.. NOTE:: 871 This value also influences server's usage of virtual memory. 872 873*Default:* 20 GiB (512 MiB for 32-bit) 874 875.. _database_kasp-db: 876 877kasp-db 878------- 879 880An explicit specification of the KASP database directory. 881Non-absolute path (i.e. not starting with ``/``) is relative to 882:ref:`storage<database_storage>`. 883 884*Default:* :ref:`storage<database_storage>`/keys 885 886.. _database_kasp-db-max-size: 887 888kasp-db-max-size 889---------------- 890 891The hard limit for the KASP database maximum size. 892 893.. NOTE:: 894 This value also influences server's usage of virtual memory. 895 896*Default:* 500 MiB 897 898.. _database_timer-db: 899 900timer-db 901-------- 902 903An explicit specification of the persistent timer database directory. 904Non-absolute path (i.e. not starting with ``/``) is relative to 905:ref:`storage<database_storage>`. 906 907*Default:* :ref:`storage<database_storage>`/timers 908 909.. _database_timer-db-max-size: 910 911timer-db-max-size 912----------------- 913 914The hard limit for the timer database maximum size. 915 916.. NOTE:: 917 This value also influences server's usage of virtual memory. 918 919*Default:* 100 MiB 920 921.. _database_catalog-db: 922 923catalog-db 924---------- 925 926An explicit specification of the zone catalog database directory. 927Only useful if :ref:`catalog-zones` are enabled. 928Non-absolute path (i.e. not starting with ``/``) is relative to 929:ref:`storage<database_storage>`. 930 931*Default:* :ref:`storage<database_storage>`/catalog 932 933.. _database_catalog-db-max-size: 934 935catalog-db-max-size 936------------------- 937 938The hard limit for the catalog database maximum size. 939 940.. NOTE:: 941 This value also influences server's usage of virtual memory. 942 943*Default:* 20 GiB (512 MiB for 32-bit) 944 945.. _Keystore section: 946 947Keystore section 948================ 949 950DNSSEC keystore configuration. 951 952:: 953 954 keystore: 955 - id: STR 956 backend: pem | pkcs11 957 config: STR 958 959.. _keystore_id: 960 961id 962-- 963 964A keystore identifier. 965 966 967.. _keystore_backend: 968 969backend 970------- 971 972A key storage backend type. 973 974Possible values: 975 976- ``pem`` – PEM files. 977- ``pkcs11`` – PKCS #11 storage. 978 979*Default:* pem 980 981.. _keystore_config: 982 983config 984------ 985 986A backend specific configuration. A directory with PEM files (the path can 987be specified as a relative path to :ref:`kasp-db<database_kasp-db>`) or 988a configuration string for PKCS #11 storage (`<pkcs11-url> <module-path>`). 989 990.. NOTE:: 991 Example configuration string for PKCS #11:: 992 993 "pkcs11:token=knot;pin-value=1234 /usr/lib64/pkcs11/libsofthsm2.so" 994 995*Default:* :ref:`kasp-db<database_kasp-db>`/keys 996 997.. _Key section: 998 999Key section 1000=========== 1001 1002Shared TSIG keys used to authenticate communication with the server. 1003 1004:: 1005 1006 key: 1007 - id: DNAME 1008 algorithm: hmac-md5 | hmac-sha1 | hmac-sha224 | hmac-sha256 | hmac-sha384 | hmac-sha512 1009 secret: BASE64 1010 1011.. _key_id: 1012 1013id 1014-- 1015 1016A key name identifier. 1017 1018.. NOTE:: 1019 This value MUST be exactly the same as the name of the TSIG key on the 1020 opposite primary/secondary server(s). 1021 1022.. _key_algorithm: 1023 1024algorithm 1025--------- 1026 1027A TSIG key algorithm. See 1028`TSIG Algorithm Numbers <https://www.iana.org/assignments/tsig-algorithm-names/tsig-algorithm-names.xhtml>`_. 1029 1030Possible values: 1031 1032- ``hmac-md5`` 1033- ``hmac-sha1`` 1034- ``hmac-sha224`` 1035- ``hmac-sha256`` 1036- ``hmac-sha384`` 1037- ``hmac-sha512`` 1038 1039*Default:* not set 1040 1041.. _key_secret: 1042 1043secret 1044------ 1045 1046Shared key secret. 1047 1048*Default:* not set 1049 1050.. _Remote section: 1051 1052Remote section 1053============== 1054 1055Definitions of remote servers for outgoing connections (source of a zone 1056transfer, target for a notification, etc.). 1057 1058:: 1059 1060 remote: 1061 - id: STR 1062 address: ADDR[@INT] ... 1063 via: ADDR[@INT] ... 1064 key: key_id 1065 block-notify-after-transfer: BOOL 1066 1067.. _remote_id: 1068 1069id 1070-- 1071 1072A remote identifier. 1073 1074.. _remote_address: 1075 1076address 1077------- 1078 1079An ordered list of destination IP addresses which are used for communication 1080with the remote server. The addresses are tried in sequence until the 1081remote is reached. Optional destination port (default is 53) 1082can be appended to the address using ``@`` separator. 1083 1084*Default:* not set 1085 1086.. NOTE:: 1087 If the remote is contacted and it refuses to perform requested action, 1088 no more addresses will be tried for this remote. 1089 1090.. _remote_via: 1091 1092via 1093--- 1094 1095An ordered list of source IP addresses. The first address with the same family 1096as the destination address is used as a source address for communication with 1097the remote. This option can help if the server listens on more addresses. 1098Optional source port (default is random) can be appended 1099to the address using ``@`` separator. 1100 1101*Default:* not set 1102 1103.. _remote_key: 1104 1105key 1106--- 1107 1108A :ref:`reference<key_id>` to the TSIG key which is used to authenticate 1109the communication with the remote server. 1110 1111*Default:* not set 1112 1113.. _remote_block-notify-after-transfer: 1114 1115block-notify-after-transfer 1116--------------------------- 1117 1118When incoming AXFR/IXFR from this remote (as a primary server), suppress 1119sending NOTIFY messages to all configured secondary servers. 1120 1121*Default:* off 1122 1123.. _ACL section: 1124 1125ACL section 1126=========== 1127 1128Access control list rule definitions. The ACLs are used to match incoming 1129connections to allow or deny requested operation (zone transfer request, DDNS 1130update, etc.). 1131 1132:: 1133 1134 acl: 1135 - id: STR 1136 address: ADDR[/INT] | ADDR-ADDR ... 1137 key: key_id ... 1138 remote: remote_id ... 1139 action: notify | transfer | update ... 1140 deny: BOOL 1141 update-type: STR ... 1142 update-owner: key | zone | name 1143 update-owner-match: sub-or-equal | equal | sub 1144 update-owner-name: STR ... 1145 1146.. _acl_id: 1147 1148id 1149-- 1150 1151An ACL rule identifier. 1152 1153.. _acl_address: 1154 1155address 1156------- 1157 1158An ordered list of IP addresses, network subnets, or network ranges. The query's 1159source address must match one of them. Empty value means that address match is not 1160required. 1161 1162*Default:* not set 1163 1164.. _acl_key: 1165 1166key 1167--- 1168 1169An ordered list of :ref:`reference<key_id>`\ s to TSIG keys. The query must 1170match one of them. Empty value means that transaction authentication is not used. 1171 1172*Default:* not set 1173 1174.. _acl_remote: 1175 1176remote 1177------ 1178 1179An ordered list of :ref:`references<remote_id>` to remotes. The query must 1180match one of the remotes. Specifically, one of the remote's addresses and remote's 1181TSIG key if configured must match. 1182 1183.. NOTE:: 1184 This option cannot be specified along with the :ref:`acl_address` or 1185 :ref:`acl_key` option at one ACL item. 1186 1187*Default:* not set 1188 1189.. _acl_action: 1190 1191action 1192------ 1193 1194An ordered list of allowed (or denied) actions. 1195 1196Possible values: 1197 1198- ``notify`` – Allow incoming notify. 1199- ``transfer`` – Allow zone transfer. 1200- ``update`` – Allow zone updates. 1201 1202*Default:* not set 1203 1204.. _acl_deny: 1205 1206deny 1207---- 1208 1209If enabled, instead of allowing, deny the specified :ref:`action<acl_action>`, 1210:ref:`address<acl_address>`, :ref:`key<acl_key>`, or combination if these 1211items. If no action is specified, deny all actions. 1212 1213*Default:* off 1214 1215.. _acl_update_type: 1216 1217update-type 1218----------- 1219 1220A list of allowed types of Resource Records in a zone update. Every record in an update 1221must match one of the specified types. 1222 1223*Default:* not set 1224 1225.. _acl_update_owner: 1226 1227update-owner 1228------------ 1229 1230This option restricts possible owners of Resource Records in a zone update by comparing 1231them to either the :ref:`TSIG key<acl_key>` identity, the current zone name, or to a list of 1232domain names given by the :ref:`update-owner-name<acl_update_owner_name>` option. 1233The comparison method is given by the :ref:`update-owner-match<acl_update_owner_match>` option. 1234 1235Possible values: 1236 1237- ``key`` — The owner of each updated RR must match the identity of the TSIG key if used. 1238- ``name`` — The owner of each updated RR must match at least one name in the 1239 :ref:`update-owner-name<acl_update_owner_name>` list. 1240- ``zone`` — The owner of each updated RR must match the current zone name. 1241 1242*Default:* not set 1243 1244.. _acl_update_owner_match: 1245 1246update-owner-match 1247------------------ 1248 1249This option defines how the owners of Resource Records in an update are matched to the domain name(s) 1250set by the :ref:`update-owner<acl_update_owner>` option. 1251 1252Possible values: 1253 1254- ``sub-or-equal`` — The owner of each Resource Record in an update must either be equal to 1255 or be a subdomain of at least one domain set by :ref:`update-owner<acl_update_owner>`. 1256- ``equal`` — The owner of each updated RR must be equal to at least one domain set by 1257 :ref:`update-owner<acl_update_owner>`. 1258- ``sub`` — The owner of each updated RR must be a subdomain of, but MUST NOT be equal to at least 1259 one domain set by :ref:`update-owner<acl_update_owner>`. 1260 1261*Default:* sub-or-equal 1262 1263.. _acl_update_owner_name: 1264 1265update-owner-name 1266----------------- 1267 1268A list of allowed owners of RRs in a zone update used with :ref:`update-owner<acl_update_owner>` 1269set to ``name``. Every listed owner name which is not FQDN (i.e. it doesn't end 1270in a dot) is considered as if it was appended with the target zone name. 1271Such a relative owner name specification allows better ACL rule reusability across 1272multiple zones. 1273 1274*Default:* not set 1275 1276.. _Submission section: 1277 1278Submission section 1279================== 1280 1281Parameters of KSK submission checks. 1282 1283:: 1284 1285 submission: 1286 - id: STR 1287 parent: remote_id ... 1288 check-interval: TIME 1289 timeout: TIME 1290 1291.. _submission_id: 1292 1293id 1294-- 1295 1296A submission identifier. 1297 1298.. _submission_parent: 1299 1300parent 1301------ 1302 1303A list of :ref:`references<remote_id>` to parent's DNS servers to be checked for 1304presence of corresponding DS records in the case of KSK submission. All of them must 1305have a corresponding DS for the rollover to continue. If none is specified, the 1306rollover must be pushed forward manually. 1307 1308*Default:* not set 1309 1310.. TIP:: 1311 A DNSSEC-validating resolver can be set as a parent. 1312 1313.. _submission_check-interval: 1314 1315check-interval 1316-------------- 1317 1318Interval for periodic checks of DS presence on parent's DNS servers, in the 1319case of the KSK submission. 1320 1321*Default:* 1 hour 1322 1323.. _submission_timeout: 1324 1325timeout 1326------- 1327 1328After this time period (in seconds) the KSK submission is automatically considered 1329successful, even if all the checks were negative or no parents are configured. 1330Set to 0 for infinity. 1331 1332*Default:* 0 1333 1334.. _Policy section: 1335 1336Policy section 1337============== 1338 1339DNSSEC policy configuration. 1340 1341:: 1342 1343 policy: 1344 - id: STR 1345 keystore: keystore_id 1346 manual: BOOL 1347 single-type-signing: BOOL 1348 algorithm: rsasha1 | rsasha1-nsec3-sha1 | rsasha256 | rsasha512 | ecdsap256sha256 | ecdsap384sha384 | ed25519 | ed448 1349 ksk-size: SIZE 1350 zsk-size: SIZE 1351 ksk-shared: BOOL 1352 dnskey-ttl: TIME 1353 zone-max-ttl: TIME 1354 ksk-lifetime: TIME 1355 zsk-lifetime: TIME 1356 delete-delay: TIME 1357 propagation-delay: TIME 1358 rrsig-lifetime: TIME 1359 rrsig-refresh: TIME 1360 rrsig-pre-refresh: TIME 1361 reproducible-signing: BOOL 1362 nsec3: BOOL 1363 nsec3-iterations: INT 1364 nsec3-opt-out: BOOL 1365 nsec3-salt-length: INT 1366 nsec3-salt-lifetime: TIME 1367 signing-threads: INT 1368 ksk-submission: submission_id 1369 ds-push: remote_id 1370 cds-cdnskey-publish: none | delete-dnssec | rollover | always | double-ds 1371 cds-digest-type: sha256 | sha384 1372 offline-ksk: BOOL 1373 unsafe-operation: none | no-check-keyset | no-update-dnskey | no-update-nsec | no-update-expired ... 1374 1375.. _policy_id: 1376 1377id 1378-- 1379 1380A policy identifier. 1381 1382.. _policy_keystore: 1383 1384keystore 1385-------- 1386 1387A :ref:`reference<keystore_id>` to a keystore holding private key material 1388for zones. 1389 1390*Default:* an imaginary keystore with all default values 1391 1392.. NOTE:: 1393 A configured keystore called "default" won't be used unless explicitly referenced. 1394 1395.. _policy_manual: 1396 1397manual 1398------ 1399 1400If enabled, automatic key management is not used. 1401 1402*Default:* off 1403 1404.. _policy_single-type-signing: 1405 1406single-type-signing 1407------------------- 1408 1409If enabled, Single-Type Signing Scheme is used in the automatic key management 1410mode. 1411 1412*Default:* off (:ref:`module onlinesign<mod-onlinesign>` has default on) 1413 1414.. _policy_algorithm: 1415 1416algorithm 1417--------- 1418 1419An algorithm of signing keys and issued signatures. See 1420`DNSSEC Algorithm Numbers <https://www.iana.org/assignments/dns-sec-alg-numbers/dns-sec-alg-numbers.xhtml#dns-sec-alg-numbers-1>`_. 1421 1422Possible values: 1423 1424- ``rsasha1`` 1425- ``rsasha1-nsec3-sha1`` 1426- ``rsasha256`` 1427- ``rsasha512`` 1428- ``ecdsap256sha256`` 1429- ``ecdsap384sha384`` 1430- ``ed25519`` 1431- ``ed448`` 1432 1433.. NOTE:: 1434 Ed25519 algorithm is only available if compiled with GnuTLS 3.6.0+. 1435 1436 Ed448 algorithm is only available if compiled with GnuTLS 3.6.12+ and Nettle 3.6+. 1437 1438*Default:* ecdsap256sha256 1439 1440.. _policy_ksk-size: 1441 1442ksk-size 1443-------- 1444 1445A length of newly generated :abbr:`KSK (Key Signing Key)` or 1446:abbr:`CSK (Combined Signing Key)` keys. 1447 1448*Default:* 2048 (rsa*), 256 (ecdsap256), 384 (ecdsap384), 256 (ed25519), 456 (ed448) 1449 1450.. _policy_zsk-size: 1451 1452zsk-size 1453-------- 1454 1455A length of newly generated :abbr:`ZSK (Zone Signing Key)` keys. 1456 1457*Default:* see default for :ref:`ksk-size<policy_ksk-size>` 1458 1459.. _policy_ksk-shared: 1460 1461ksk-shared 1462---------- 1463 1464If enabled, all zones with this policy assigned will share one or more KSKs. 1465More KSKs can be shared during a KSK rollover. 1466 1467.. WARNING:: 1468 As the shared KSK set is bound to the policy :ref:`id<policy_id>`, renaming the 1469 policy breaks this connection and new shared KSK set is initiated when 1470 a new KSK is needed. 1471 1472*Default:* off 1473 1474.. _policy_dnskey-ttl: 1475 1476dnskey-ttl 1477---------- 1478 1479A TTL value for DNSKEY records added into zone apex. 1480 1481.. NOTE:: 1482 Has influence over ZSK key lifetime. 1483 1484.. WARNING:: 1485 Ensure all DNSKEYs with updated TTL are propagated before any subsequent 1486 DNSKEY rollover starts. 1487 1488*Default:* zone SOA TTL 1489 1490.. _policy_zone-max-ttl: 1491 1492zone-max-ttl 1493------------ 1494 1495Declare (override) maximal TTL value among all the records in zone. 1496 1497.. NOTE:: 1498 It's generally recommended to override the maximal TTL computation by setting this 1499 explicitly whenever possible. It's required for :ref:`DNSSEC Offline KSK` and 1500 really reasonable when records are generated dynamically 1501 (e.g. by a :ref:`module<mod-synthrecord>`). 1502 1503*Default:* computed after zone is loaded 1504 1505.. _policy_ksk-lifetime: 1506 1507ksk-lifetime 1508------------ 1509 1510A period between KSK activation and the next rollover initiation. 1511 1512.. NOTE:: 1513 KSK key lifetime is also influenced by propagation-delay, dnskey-ttl, 1514 and KSK submission delay. 1515 1516 Zero (aka infinity) value causes no KSK rollover as a result. 1517 1518 This applies for CSK lifetime if single-type-signing is enabled. 1519 1520*Default:* 0 1521 1522.. _policy_zsk-lifetime: 1523 1524zsk-lifetime 1525------------ 1526 1527A period between ZSK activation and the next rollover initiation. 1528 1529.. NOTE:: 1530 More exactly, this period is measured since a ZSK is activated, 1531 and after this, a new ZSK is generated to replace it within 1532 following roll-over. 1533 1534 ZSK key lifetime is also influenced by propagation-delay and dnskey-ttl 1535 1536 Zero (aka infinity) value causes no ZSK rollover as a result. 1537 1538*Default:* 30 days 1539 1540.. _policy_delete-delay: 1541 1542delete-delay 1543------------ 1544 1545Once a key (KSK or ZSK) is rolled-over and removed from the zone, 1546keep it in the KASP database for at least this period before deleting it completely. 1547This might be useful in some troubleshooting cases when resurrection 1548is needed. 1549 1550*Default:* 0 1551 1552.. _policy_propagation-delay: 1553 1554propagation-delay 1555----------------- 1556 1557An extra delay added for each key rollover step. This value should be high 1558enough to cover propagation of data from the primary server to all 1559secondary servers. 1560 1561.. NOTE:: 1562 Has influence over ZSK key lifetime. 1563 1564*Default:* 1 hour 1565 1566.. _policy_rrsig-lifetime: 1567 1568rrsig-lifetime 1569-------------- 1570 1571A validity period of newly issued signatures. 1572 1573.. NOTE:: 1574 The RRSIG's signature inception time is set to 90 minutes in the past. This 1575 time period is not counted to the signature lifetime. 1576 1577*Default:* 14 days 1578 1579.. _policy_rrsig-refresh: 1580 1581rrsig-refresh 1582------------- 1583 1584A period how long at least before a signature expiration the signature will be refreshed, 1585in order to prevent expired RRSIGs on secondary servers or resolvers' caches. 1586 1587*Default:* 7 days 1588 1589.. _policy_rrsig-pre-refresh: 1590 1591rrsig-pre-refresh 1592----------------- 1593 1594A period how long at most before a signature refresh time the signature might be refreshed, 1595in order to refresh RRSIGs in bigger batches on a frequently updated zone 1596(avoid re-sign event too often). 1597 1598*Default:* 1 hour 1599 1600.. _policy_reproducible-signing: 1601 1602reproducible-signing 1603-------------------- 1604 1605For ECDSA algorithms, generate RRSIG signatures deterministically (:rfc:`6979`). 1606Besides better theoretical cryptographic security, this mode allows significant 1607speed-up of loading signed (by the same method) zones. However, the zone signing 1608is a bit slower. 1609 1610*Default:* off 1611 1612.. _policy_nsec3: 1613 1614nsec3 1615----- 1616 1617Specifies if NSEC3 will be used instead of NSEC. 1618 1619*Default:* off 1620 1621.. _policy_nsec3-iterations: 1622 1623nsec3-iterations 1624---------------- 1625 1626A number of additional times the hashing is performed. 1627 1628*Default:* 10 1629 1630.. _policy_nsec3-opt-out: 1631 1632nsec3-opt-out 1633------------- 1634 1635If set, NSEC3 records won't be created for insecure delegations. 1636This speeds up the zone signing and reduces overall zone size. 1637 1638.. WARNING:: 1639 NSEC3 with the Opt-Out bit set no longer works as a proof of non-existence 1640 in this zone. 1641 1642*Default:* off 1643 1644.. _policy_nsec3-salt-length: 1645 1646nsec3-salt-length 1647----------------- 1648 1649A length of a salt field in octets, which is appended to the original owner 1650name before hashing. 1651 1652*Default:* 8 1653 1654.. _policy_nsec3-salt-lifetime: 1655 1656nsec3-salt-lifetime 1657------------------- 1658 1659A validity period of newly issued salt field. 1660 1661Zero value means infinity. 1662 1663*Default:* 30 days 1664 1665.. _policy_signing-threads: 1666 1667signing-threads 1668--------------- 1669 1670When signing zone or update, use this number of threads for parallel signing. 1671 1672Those are extra threads independent of :ref:`Background workers<server_background-workers>`. 1673 1674.. NOTE:: 1675 Some steps of the DNSSEC signing operation are not parallelized. 1676 1677*Default:* 1 (no extra threads) 1678 1679.. _policy_ksk-submission-check: 1680 1681ksk-submission 1682-------------- 1683 1684A reference to :ref:`submission<submission_id>` section holding parameters of 1685KSK submission checks. 1686 1687*Default:* not set 1688 1689.. _policy_ds-push: 1690 1691ds-push 1692------- 1693 1694An optional :ref:`reference<remote_id>` to authoritative DNS server of the 1695parent's zone. The remote server must be configured to accept DS record 1696updates via DDNS. Whenever a CDS record in the local zone is changed, the 1697corresponding DS record is sent as a dynamic update (DDNS) to the parent 1698DNS server. All previous DS records are deleted within the DDNS message. 1699It's possible to manage both child and parent zones by the same Knot DNS server. 1700 1701.. NOTE:: 1702 This feature requires :ref:`cds-cdnskey-publish<policy_cds-cdnskey-publish>` 1703 not to be set to ``none``. 1704 1705.. NOTE:: 1706 Module :ref:`Onlinesign<mod-onlinesign>` doesn't support DS push. 1707 1708*Default:* not set 1709 1710.. _policy_cds-cdnskey-publish: 1711 1712cds-cdnskey-publish 1713------------------- 1714 1715Controls if and how shall the CDS and CDNSKEY be published in the zone. 1716 1717Possible values: 1718 1719- ``none`` – Never publish any CDS or CDNSKEY records in the zone. 1720- ``delete-dnssec`` – Publish special CDS and CDNSKEY records indicating turning off DNSSEC. 1721- ``rollover`` – Publish CDS and CDNSKEY records for ready and not yet active KSK (submission phase of KSK rollover). 1722- ``always`` – Always publish one CDS and one CDNSKEY records for the current KSK. 1723- ``double-ds`` – Always publish up to two CDS and two CDNSKEY records for ready and/or active KSKs. 1724 1725.. NOTE:: 1726 If the zone keys are managed manually, the CDS and CDNSKEY rrsets may contain 1727 more records depending on the keys available. 1728 1729*Default:* rollover 1730 1731.. _policy_cds-digest-type: 1732 1733cds-digest-type 1734--------------- 1735 1736Specify digest type for published CDS records. 1737 1738*Default:* sha256 1739 1740.. _policy_offline-ksk: 1741 1742offline-ksk 1743----------- 1744 1745Specifies if :ref:`Offline KSK <DNSSEC Offline KSK>` feature is enabled. 1746 1747*Default:* off 1748 1749.. _policy_unsafe-operation: 1750 1751unsafe-operation 1752---------------- 1753 1754Turn off some DNSSEC safety features. 1755 1756Possible values: 1757 1758- ``none`` – Nothing disabled. 1759- ``no-check-keyset`` – Don't check active keys in present algorithms. This may 1760 lead to violation of :rfc:`4035#section-2.2`. 1761- ``no-update-dnskey`` – Don't maintain/update DNSKEY, CDNSKEY, and CDS records 1762 in the zone apex according to KASP database. Juste leave them as they are in the zone. 1763- ``no-update-nsec`` – Don't maintain/update NSEC/NSEC3 chain. Leave all the records 1764 as they are in the zone. 1765- ``no-update-expired`` – Don't update expired RRSIGs. 1766 1767Multiple values may be specified. 1768 1769.. WARNING:: 1770 This mode is intended for DNSSEC experts who understand the corresponding consequences. 1771 1772*Default:* none 1773 1774.. _Template section: 1775 1776Template section 1777================ 1778 1779A template is shareable zone settings, which can simplify configuration by 1780reducing duplicates. A special default template (with the *default* identifier) 1781can be used for global zone configuration or as an implicit configuration 1782if a zone doesn't have another template specified. 1783 1784:: 1785 1786 template: 1787 - id: STR 1788 global-module: STR/STR ... 1789 # All zone options (excluding 'template' item) 1790 1791.. _template_id: 1792 1793id 1794-- 1795 1796A template identifier. 1797 1798.. _template_global-module: 1799 1800global-module 1801------------- 1802 1803An ordered list of references to query modules in the form of *module_name* or 1804*module_name/module_id*. These modules apply to all queries. 1805 1806.. NOTE:: 1807 This option is only available in the *default* template. 1808 1809*Default:* not set 1810 1811.. _Zone section: 1812 1813Zone section 1814============ 1815 1816Definition of zones served by the server. 1817 1818:: 1819 1820 zone: 1821 - domain: DNAME 1822 template: template_id 1823 storage: STR 1824 file: STR 1825 master: remote_id ... 1826 ddns-master: remote_id 1827 notify: remote_id ... 1828 acl: acl_id ... 1829 semantic-checks: BOOL 1830 zonefile-sync: TIME 1831 zonefile-load: none | difference | difference-no-serial | whole 1832 journal-content: none | changes | all 1833 journal-max-usage: SIZE 1834 journal-max-depth: INT 1835 zone-max-size : SIZE 1836 adjust-threads: INT 1837 dnssec-signing: BOOL 1838 dnssec-validation: BOOL 1839 dnssec-policy: policy_id 1840 zonemd-verify: BOOL 1841 zonemd-generate: none | zonemd-sha384 | zonemd-sha512 | remove 1842 serial-policy: increment | unixtime | dateserial 1843 refresh-min-interval: TIME 1844 refresh-max-interval: TIME 1845 catalog-role: none | interpret | generate | member 1846 catalog-template: template_id ... 1847 catalog-zone: DNAME 1848 catalog-group: STR 1849 module: STR/STR ... 1850 1851.. _zone_domain: 1852 1853domain 1854------ 1855 1856A zone name identifier. 1857 1858.. _zone_template: 1859 1860template 1861-------- 1862 1863A :ref:`reference<template_id>` to a configuration template. 1864 1865*Default:* not set or *default* (if the template exists) 1866 1867.. _zone_storage: 1868 1869storage 1870------- 1871 1872A data directory for storing zone files. 1873 1874*Default:* ``${localstatedir}/lib/knot`` (configured with ``--with-storage=path``) 1875 1876.. _zone_file: 1877 1878file 1879---- 1880 1881A path to the zone file. Non-absolute path (i.e. not starting with ``/``) is 1882relative to :ref:`storage<zone_storage>`. 1883It is also possible to use the following formatters: 1884 1885- ``%c[``\ *N*\ ``]`` or ``%c[``\ *N*\ ``-``\ *M*\ ``]`` – Means the *N*\ th 1886 character or a sequence of characters beginning from the *N*\ th and ending 1887 with the *M*\ th character of the textual zone name (see ``%s``). The 1888 indexes are counted from 0 from the left. All dots (including the terminal 1889 one) are considered. If the character is not available, the formatter has no effect. 1890- ``%l[``\ *N*\ ``]`` – Means the *N*\ th label of the textual zone name 1891 (see ``%s``). The index is counted from 0 from the right (0 ~ TLD). 1892 If the label is not available, the formatter has no effect. 1893- ``%s`` – Means the current zone name in the textual representation. 1894 The zone name doesn't include the terminating dot (the result for the root 1895 zone is the empty string!). 1896- ``%%`` – Means the ``%`` character. 1897 1898.. WARNING:: 1899 Beware of special characters which are escaped or encoded in the \\DDD form 1900 where DDD is corresponding decimal ASCII code. 1901 1902*Default:* :ref:`storage<zone_storage>`/``%s``\ .zone 1903 1904.. _zone_master: 1905 1906master 1907------ 1908 1909An ordered list of :ref:`references<remote_id>` to zone primary servers 1910(formerly known as master servers). 1911 1912*Default:* not set 1913 1914.. _zone_ddns-master: 1915 1916ddns-master 1917----------- 1918 1919A :ref:`reference<remote_id>` to zone primary master. If not specified, 1920the first :ref:`master<zone_master>` server is used. 1921 1922*Default:* not set 1923 1924.. _zone_notify: 1925 1926notify 1927------ 1928 1929An ordered list of :ref:`references<remote_id>` to remotes to which notify 1930message is sent if the zone changes. 1931 1932*Default:* not set 1933 1934.. _zone_acl: 1935 1936acl 1937--- 1938 1939An ordered list of :ref:`references<acl_id>` to ACL rules which can allow 1940or disallow zone transfers, updates or incoming notifies. 1941 1942*Default:* not set 1943 1944.. _zone_semantic-checks: 1945 1946semantic-checks 1947--------------- 1948 1949If enabled, extra zone semantic checks are turned on. 1950 1951Several checks are enabled by default and cannot be turned off. An error in 1952mandatory checks causes zone not to be loaded. An error in extra checks is 1953logged only. 1954 1955Mandatory checks: 1956 1957- SOA record missing in the zone (:rfc:`1034`) 1958- An extra record together with CNAME record except for RRSIG and DS (:rfc:`1034`) 1959- Multiple CNAME record with the same owner 1960- DNAME record having a record under it (:rfc:`2672`) 1961 1962Extra checks: 1963 1964- Missing NS record at the zone apex 1965- Missing glue A or AAAA record 1966- Invalid DNSKEY, DS, or NSEC3PARAM record 1967- CDS or CDNSKEY inconsistency 1968- Missing, invalid, or unverifiable RRSIG record 1969- Invalid NSEC(3) record 1970- Broken or non-cyclic NSEC(3) chain 1971 1972*Default:* off 1973 1974.. _zone_zonefile-sync: 1975 1976zonefile-sync 1977------------- 1978 1979The time after which the current zone in memory will be synced with a zone file 1980on the disk (see :ref:`file<zone_file>`). The server will serve the latest 1981zone even after a restart using zone journal, but the zone file on the disk will 1982only be synced after ``zonefile-sync`` time has expired (or after manual zone 1983flush). This is applicable when the zone is updated via IXFR, DDNS or automatic 1984DNSSEC signing. In order to completely disable automatic zone file synchronization, 1985set the value to -1. In that case, it is still possible to force a manual zone flush 1986using the ``-f`` option. 1987 1988.. NOTE:: 1989 If you are serving large zones with frequent updates where 1990 the immediate sync with a zone file is not desirable, increase the value. 1991 1992*Default:* 0 (immediate) 1993 1994.. _zone_zonefile-load: 1995 1996zonefile-load 1997------------- 1998 1999Selects how the zone file contents are applied during zone load. 2000 2001Possible values: 2002 2003- ``none`` – The zone file is not used at all. 2004- ``difference`` – If the zone contents are already available during server start or reload, 2005 the difference is computed between them and the contents of the zone file. This difference 2006 is then checked for semantic errors and applied to the current zone contents. 2007- ``difference-no-serial`` – Same as ``difference``, but the SOA serial in the zone file is 2008 ignored, the server takes care of incrementing the serial automatically. 2009- ``whole`` – Zone contents are loaded from the zone file. 2010 2011When ``difference`` is configured and there are no zone contents yet (cold start 2012and no zone contents in the journal), it behaves the same way as ``whole``. 2013 2014*Default:* whole 2015 2016.. _zone_journal-content: 2017 2018journal-content 2019--------------- 2020 2021Selects how the journal shall be used to store zone and its changes. 2022 2023Possible values: 2024 2025- ``none`` – The journal is not used at all. 2026- ``changes`` – Zone changes history is stored in journal. 2027- ``all`` – Zone contents and history is stored in journal. 2028 2029*Default:* changes 2030 2031.. _zone_journal-max-usage: 2032 2033journal-max-usage 2034----------------- 2035 2036Policy how much space in journal DB will the zone's journal occupy. 2037 2038.. NOTE:: 2039 Journal DB may grow far above the sum of journal-max-usage across 2040 all zones, because of DB free space fragmentation. 2041 2042*Default:* 100 MiB 2043 2044.. _zone_journal-max-depth: 2045 2046journal-max-depth 2047----------------- 2048 2049Maximum history length of the journal. 2050 2051.. NOTE:: 2052 Zone-in-journal changeset isn't counted to the limit. 2053 2054*Minimum:* 2 2055 2056*Default:* 2^64 2057 2058.. _zone_zone-max-size: 2059 2060zone-max-size 2061------------- 2062 2063Maximum size of the zone. The size is measured as size of the zone records 2064in wire format without compression. The limit is enforced for incoming zone 2065transfers and dynamic updates. 2066 2067For incremental transfers (IXFR), the effective limit for the total size of 2068the records in the transfer is twice the configured value. However the final 2069size of the zone must satisfy the configured value. 2070 2071*Default:* 2^64 2072 2073.. _zone_adjust-threads: 2074 2075adjust-threads 2076-------------- 2077 2078Parallelize internal zone adjusting procedures. This is useful with huge 2079zones with NSEC3. Speedup observable at server startup and while processing 2080NSEC3 re-salt. 2081 2082*Default:* 1 2083 2084.. _zone_dnssec-signing: 2085 2086dnssec-signing 2087-------------- 2088 2089If enabled, automatic DNSSEC signing for the zone is turned on. 2090 2091*Default:* off 2092 2093.. _zone_dnssec-validation: 2094 2095dnssec-validation 2096----------------- 2097 2098If enabled, the zone contents are validated for being correctly signed 2099(including NSEC/NSEC3 chain) with DNSSEC signatures every time the zone 2100is loaded or changed (including AXFR/IXFR). 2101 2102When the validation fails, the zone being loaded or update being applied 2103is cancelled with an error, and either none or previous zone state is published. 2104 2105List of DNSSEC checks: 2106 2107- Every zone RRSet is correctly signed by at least one present DNSKEY. 2108- DNSKEY RRSet is signed by KSK. 2109- NSEC(3) RR exists for each name (unless opt-out) with correct bitmap. 2110- Every NSEC(3) RR is linked to the lexicographically next one. 2111 2112The validation is not affected by :ref:`zone_dnssec-policy` configuration, 2113except for :ref:`policy_signing-threads` option, which specifies the number 2114of threads for parallel validation. 2115 2116.. NOTE:: 2117 2118 Redundant or garbage NSEC3 records are ignored. 2119 2120 This mode is not compatible with :ref:`zone_dnssec-signing`. 2121 2122.. _zone_dnssec-policy: 2123 2124dnssec-policy 2125------------- 2126 2127A :ref:`reference<policy_id>` to DNSSEC signing policy. 2128 2129*Default:* an imaginary policy with all default values 2130 2131.. NOTE:: 2132 A configured policy called "default" won't be used unless explicitly referenced. 2133 2134.. _zone_zonemd-verify: 2135 2136zonemd-verify 2137------------- 2138 2139On each zone load/update, verify that ZONEMD is present in the zone and valid. 2140 2141.. NOTE:: 2142 Zone digest calculation may take much time and CPU on large zones. 2143 2144*Default:* off 2145 2146.. _zone_zonemd-generate: 2147 2148zonemd-generate 2149--------------- 2150 2151On each zone update, calculate ZONEMD and put it into the zone. 2152 2153Possible values: 2154 2155- ``none`` – No action regarding ZONEMD. 2156- ``zonemd-sha384`` – Generate ZONEMD using SHA384 algorithm. 2157- ``zonemd-sha512`` – Generate ZONEMD using SHA512 algorithm. 2158- ``remove`` – Remove any ZONEMD from the zone apex. 2159 2160*Default:* none 2161 2162.. _zone_serial-policy: 2163 2164serial-policy 2165------------- 2166 2167Specifies how the zone serial is updated after a dynamic update or 2168automatic DNSSEC signing. If the serial is changed by the dynamic update, 2169no change is made. 2170 2171Possible values: 2172 2173- ``increment`` – The serial is incremented according to serial number arithmetic. 2174- ``unixtime`` – The serial is set to the current unix time. 2175- ``dateserial`` – The 10-digit serial (YYYYMMDDnn) is incremented, the first 2176 8 digits match the current iso-date. 2177 2178.. NOTE:: 2179 If the resulting serial for ``unixtime`` or ``dateserial`` is lower or equal 2180 than the current serial (this happens e.g. when migrating from other policy or 2181 frequent updates), the serial is incremented instead. 2182 2183 To avoid user confusion, use ``dateserial`` only if you expect at most 2184 100 updates per day per zone and ``unixtime`` only if you expect at most 2185 one update per second per zone. 2186 2187*Default:* increment 2188 2189.. _zone_refresh-min-interval: 2190 2191refresh-min-interval 2192-------------------- 2193 2194Forced minimum zone refresh interval to avoid flooding primary server. 2195 2196*Default:* 2 2197 2198.. _zone_refresh-max-interval: 2199 2200refresh-max-interval 2201-------------------- 2202 2203Forced maximum zone refresh interval. 2204 2205*Default:* not set 2206 2207.. _zone_catalog-role: 2208 2209catalog-role 2210------------ 2211 2212Trigger zone catalog feature. Possible values: 2213 2214- ``none`` – Not a catalog zone. 2215- ``interpret`` – A catalog zone which is loaded from a zone file or XFR, 2216 and member zones shall be configured based on its contents. 2217- ``generate`` – A catalog zone whose contents are generated according to 2218 assigned member zones. 2219- ``member`` – A member zone that is assigned to one generated catalog zone. 2220 2221*Default:* none 2222 2223.. _zone_catalog-template: 2224 2225catalog-template 2226---------------- 2227 2228For the catalog member zones, the specified configuration template will be applied. 2229 2230Multiple catalog templates may be defined. The first one is used unless the member zone 2231has the *group* property defined, matching another catalog template. 2232 2233.. NOTE:: 2234 This option must be set if and only if :ref:`zone_catalog-role` is *interpret*. 2235 2236*Default:* not set 2237 2238.. _zone_catalog-zone: 2239 2240catalog-zone 2241------------ 2242 2243Assign this member zone to specified generated catalog zone. 2244 2245.. NOTE:: 2246 This option must be set if and only if :ref:`zone_catalog-role` is *member*. 2247 2248 The referenced catalog zone must exist and have :ref:`zone_catalog-role` set to *generate*. 2249 2250*Default:* not set 2251 2252.. _zone_catalog-group: 2253 2254catalog-group 2255------------- 2256 2257Assign this member zone to specified catalog group (configuration template). 2258 2259.. NOTE:: 2260 This option has effect if and only if :ref:`zone_catalog-role` is *member*. 2261 2262*Default:* not set 2263 2264.. _zone_module: 2265 2266module 2267------ 2268 2269An ordered list of references to query modules in the form of *module_name* or 2270*module_name/module_id*. These modules apply only to the current zone queries. 2271 2272*Default:* not set 2273