reference.rst 21.1 KB
Newer Older
1 2 3
.. meta::
   :description: reStructuredText plaintext markup language

4
.. _Configuration Reference:
5

6 7 8
***********************
Configuration Reference
***********************
9

10
.. _Description:
11

12 13
Description
===========
14

15 16
Configuration file for Knot DNS uses simplified YAML format. Simplified means
that not all features are supported.
17

18 19
For the configuration items description, there are some symbol with the
folowing meaning:
20

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

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

43 44
Multi-valued item can be specified either as a YAML sequence [val1, val2, ...]
or as more single-valued items each on the extra line.
45

46 47
If an item value contains spaces or other special characters, it is necessary
to double quote such value with ``"`` ``"``.
48

49
.. _Comments:
50

51 52
Comments
========
53

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

59
.. _Includes:
60

61 62
Includes
========
63

64 65 66
Another configuration file or all configuration files in a directory can be
included at the top level in the current file. If the file or directory path
is not absolute, then it is relative to the current file directory.
67 68 69

::

70
 include: STR
71

72
.. _Server section:
73

74 75
Server section
==============
76

77
General options related to the server.
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
 server:
     identity: [STR]
     version: [STR]
     nsid: [STR|HEXSTR]
     rundir: STR
     user: STR[:STR]
     pidfile: STR
     workers: INT
     background-workers: INT
     asynchronous-start: BOOL
     max-conn-idle: TIME
     max-conn-handshake: TIME
     max-conn-reply: TIME
     max-tcp-clients: INT
     max-udp-payload: SIZE
     transfers: INT
     rate-limit: INT
     rate-limit-slip: INT
     rate-limit-size: INT
     listen: ADDR[@INT] ...

.. _server_identity:
103

104 105
identity
--------
106

107 108
An identity of the server returned in the response for the query for TXT
record ``id.server.`` or ``hostname.bind.`` in the CHAOS class (see RFC 4892).
109
Set empty value to disable.
110

111
Default: FQDN hostname
112

113
.. _server_version:
114

115 116
version
-------
117

118 119
A version of the server software returned in the response for the query
for TXT record ``version.server.`` or ``version.bind.`` in the CHAOS
120
class (see RFC 4892). Set empty value to disable.
121

122
Default: server version
123

124
.. _server_nsid:
125

126 127
nsid
----
128

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

131
Default: FQDN hostname
132

133
.. _server_rundir:
134

135 136
rundir
------
137

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

140
Default: ``${localstatedir}/run/knot`` (configured with ``--with-rundir=path``)
141

142
.. _server_user:
143

144 145
user
----
146

147 148 149
A system user with an optional system group (*user*:*group*) under which the
server is run after starting and binding to interfaces. Linux capabilities
are employed if supported.
150

151
Default: root:root
152

153
.. _server_pidfile:
154

155 156
pidfile
-------
157

158
A PID file location.
159

160
Default: :ref:`rundir<server_rundir>`/knot.pid
161

162
.. _server_workers:
163

164 165
workers
-------
166

167
A number of quering workers (threads) per server interface.
168

169
Default: auto-estimated optimal value based on the number of online CPUs
170

171
.. _server_background-workers:
172

173 174
background-workers
------------------
175

176 177
A number of workers (threads) used to execute background operations (zone
loading, zone updates, etc.).
178

179
Default: auto-estimated optimal value based on the number of online CPUs
180

181
.. _server_asynchronous-start:
182

183 184
asynchronous-start
------------------
185

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

189 190 191
Default: off

.. _server_max-conn-idle:
192 193

max-conn-idle
194 195 196 197
-------------

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

199
Default: 20
200

201
.. _server_max-conn-handshake:
202 203

max-conn-handshake
204
------------------
205

206 207 208
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.
209

210 211 212
Default: 5

.. _server_max-conn-reply:
213 214

max-conn-reply
215
--------------
216 217 218

Maximum time to wait for a reply to an issued SOA query.

219 220 221
Default: 10

.. _server_max-tcp-clients:
222 223

max-tcp-clients
224 225 226 227
---------------

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

229
Default: 100
230

231
.. _server_transfers:
232 233

transfers
234
---------
235

236 237
A maximum number of parallel transfers, including pending SOA queries. The
minimum value is determined by the number of CPUs.
238

239 240 241
Default: 10

.. _server_rate-limit:
242 243

rate-limit
244
----------
245

246 247 248 249
Rate limiting is based on the token bucket scheme. Rate basically
represents number of tokens available each second. Each response is
processed and classified (based on several discriminators, e.g.
source netblock, qtype, name, rcode, etc.). Classified responses are
250
then hashed and assigned to a bucket containing number of available
251 252 253 254
tokens, timestamp and metadata. When available tokens are exhausted,
response is rejected or enters :ref:`SLIP<server_rate-limit-slip>`
(server responds with a truncated response). Number of available tokens
is recalculated each second.
255

256
Default: 0 (disabled)
257

258
.. _server_rate-limit-size:
259 260

rate-limit-size
261
---------------
262

263 264 265 266 267 268
Size of hashtable buckets. The larger the hashtable, the lesser probability
of a hash collision, but at the expense of additional memory costs. Each bucket
is estimated roughly to 32 bytes. Size should be selected as a reasonably large
prime due to the better hash function distribution properties. Hash table is
internally chained and works well up to a fill rate of 90 %, general
rule of thumb is to select a prime near 1.2 * maximum_qps.
269

270
Default: 393241
271

272
.. _server_rate-limit-slip:
273 274

rate-limit-slip
275
---------------
276 277 278

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

It is advisable not to set the slip interval to a value larger than 2,
as too large slip value means more denial of service for legitimate
requestors, and introduces excessive timeouts during resolution.
On the other hand, slipping truncated answer gives the legitimate
requestors a chance to reconnect over TCP.
289

290
Default: 1
291

292
.. _server_max-udp-payload:
293 294

max-udp-payload
295
---------------
296 297 298

Maximum EDNS0 UDP payload size.

299
Default: 4096
300

301
.. _server_listen:
302

303 304
listen
------
305

306 307 308 309
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.
310

311
Default: empty
312

313
.. _Key section:
314

315 316
Key section
===========
317

318
Shared TSIG keys used to authenticate communication with the server.
319

320
::
321

322 323 324 325
 key:
   - id: DNAME
     algorithm: hmac-md5 | hmac-sha1 | hmac-sha224 | hmac-sha256 | hmac-sha384 | hmac-sha512
     secret: BASE64
326

327
.. _key_id:
328

329 330
id
--
331

332
A key name identifier.
333

334
.. _key_algorithm:
335

336 337 338 339 340 341
algorithm
---------

A key algorithm.

Default: empty
342

343
.. _key_secret:
344

345 346
secret
------
347

348
Shared key secret.
349

350
Default: empty
351

352 353 354 355 356 357
.. _ACL section:

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

Access control list rules definition.
358 359 360

::

361 362 363 364 365
 acl:
   - id: STR
     address: ADDR[/INT]
     key: key_id
     action: deny | xfer | notify | update | control ...
366

367
.. _acl_id:
368

369 370
id
--
371

372
An ACL rule identifier.
373

374
.. _acl_address:
375

376 377
address
-------
378

379 380
A single IP address or network subnet with the given prefix the query
must match.
381

382
Default: empty
383

384
.. _acl_key:
385

386 387
key
---
388

389
A :ref:`reference<key_id>` to the TSIG key the query must match.
390

391
Default: empty
392

393
.. _acl_action:
394

395 396
action
------
397

398
An ordered list of allowed actions.
399

400
Possible values:
401

402 403 404 405 406
- ``deny`` - Block the matching query
- ``xfer`` - Allow zone transfer
- ``notify`` - Allow incoming notify
- ``update`` - Allow zone updates
- ``control`` - Allow remote control
407

408
Default: deny
409

410
.. _Control section:
411

412 413
Control section
===============
414

415
Configuration of the server remote control.
416

417 418 419
Caution: The control protocol is not encrypted, and susceptible to replay
attacks in a short timeframe until message digest expires, for that reason,
it is recommended to use default UNIX socket.
420

421
::
422

423 424 425
 control:
     listen: ADDR[@INT]
     acl: acl_id ...
426

427
.. _control_listen:
428

429 430
listen
------
431

432 433 434
A UNIX socket path or IP address where the server listens for remote control
commands. Optional port specification (default is 5533) can be appended to the
address using ``@`` separator.
435

436
Default: :ref:`rundir<server_rundir>`/knot.sock
437

438
.. _control_acl:
439

440 441
acl
---
442

443 444
An ordered list of :ref:`references<acl_id>` to ACL rules allowing the remote
control.
445

446
Caution: This option has no effect with UNIX socket.
447

448
Default: empty
449

450 451 452 453
.. _Remote section:

Remote section
==============
454

455
Definition of remote servers for zone transfers or notifications.
456

457
::
458

459 460 461 462 463
 remote:
   - id: STR
     address: ADDR[@INT]
     via: ADDR[@INT]
     key: key_id
464 465 466

.. _remote_id:

467 468 469 470
id
--

A remote identifier.
471

472
.. _remote_address:
473

474 475
address
-------
476

477 478 479
A destination IP address of the remote server. Optional destination port
specification (default is 53) can be appended to the address using ``@``
separator.
480

481
Default: empty
482

483
.. _remote_via:
484

485 486
via
---
487

488 489 490
A source IP address which is used to communicate with the remote server.
Optional source port specification can be appended to the address using
``@`` separator.
491

492
Default: empty
493

494
.. _remote_key:
495

496 497
key
---
498

499 500
A :ref:`reference<key_id>` to the TSIG key which ise used to autenticate
the communication with the remote server.
501

502
Default: empty
503

504
.. _Template section:
505

506 507
Template section
================
508

509 510 511 512
A template is shareable zone settings which can be used for configuration of
many zones at one place. A special default template (with *default* identifier)
can be used for general quering configuration or as an implicit default
configuration if a zone doesn't have a teplate specified.
513 514 515

::

516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533
 template:
   - id: STR
     storage: STR
     master: remote_id ...
     notify: remote_id ...
     acl: acl_id ...
     semantic-checks: BOOL
     disable-any: BOOL
     notify-timeout: TIME
     notify-retries: INT
     zonefile-sync: TIME
     ixfr-from-differences: BOOL
     ixfr-fslimit: SIZE
     dnssec-enable: BOOL
     dnssec-keydir: STR
     signature-lifetime: TIME
     serial-policy: increment | unixtime
     module: STR/STR ...
534

535
.. _template_id:
536

537 538
id
--
539

540
A template identifier.
541

542
.. _template_storage:
543

544 545
storage
-------
546

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

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

551
.. _template_master:
552

553 554
master
------
555

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

558
Default: empty
559

560
.. _template_notify:
561

562 563
notify
------
564

565 566
An ordered list of :ref:`references<remote_id>` to remotes to which notify
message is sent if the zone changes.
567

568
Default: empty
569

570
.. _template_acl:
571

572 573
acl
---
574

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

578
Default: empty
579

580
.. _template_semantic-checks:
581

582 583
semantic-checks
---------------
584

585
If enabled, extra zone file semantic checks are turned on.
586

587 588 589
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.
590

591
Mandatory checks:
592

593 594 595 596 597 598
- An extra record together with CNAME record (except for RRSIG and DS)
- CNAME link chain length greater than 10 (including infinite cycles)
- DNAME and CNAME records under the same owner (RFC 2672)
- CNAME and DNAME wildcards pointing to themselves
- SOA record missing in the zone (RFC 1034)
- DNAME records having records under it (DNAME children) (RFC 2672)
599

600
Extra checks:
601

602 603 604 605 606 607 608 609 610 611 612 613 614 615 616
- Missing NS record at the zone apex
- Missing glue A or AAAA records
- Broken or non-cyclic NSEC(3) chain
- Wrong NSEC(3) type bitmap
- Multiple NSEC records at the same node
- Missing NSEC records at authoritative nodes
- Extra record types under same name as NSEC3 record (this is RFC-valid, but
  Knot will not serve such a zone correctly)
- NSEC3-unsecured delegation that is not part of Opt-out span
- Wrong original TTL value in NSEC3 records
- Wrong RDATA TTL value in RRSIG record
- Signer name in RRSIG RR not the same as in DNSKEY
- Signed RRSIG
- Not all RRs in node are signed
- Wrong key flags or wrong key in RRSIG record (not the same as ZSK)
617

618
Default: off
619

620
.. _template_disable-any:
621

622 623
disable-any
-----------
624

625 626 627
If you enabled, all authoritative ANY queries sent over UDP will be answered
with an empty response and with the TC bit set. Use this option to minimize
the risk of DNS reflection attack.
628

629
Default: off
630

631
.. _template_notify-timeout:
632

633 634
notify-timeout
--------------
635

636
The time how long will server wait for a notify response.
637

638
Default: 60
639

640
.. _template_notify-retries:
641

642 643 644 645 646 647 648 649 650 651 652
notify-retries
--------------

The number of retries the server sends a notify message.

Default: 5

.. _template_zonefile-sync:

zonefile-sync
-------------
653

654 655 656 657 658 659
The time after which the current zone in memory will be synced to zone file
on the disk (see :ref:`file<zone_file>`). The server will serve the latest
zone even after restart using zone journal, but the zone file on the disk will
only be synced after ``zonefile-sync`` time has expired (or after manual zone
flush) This is applicable when the zone is updated via IXFR, DDNS or automatic
DNSSEC signing.
660

661 662
*Caution:* If you are serving large zones with frequent updates where
the immediate sync to zone file is not desirable, increase the default value.
663

664
Default: 0 (immediate)
665

666
.. _template_ixfr-from-differences:
667

668 669 670 671 672 673 674 675 676 677
ixfr-from-differences
---------------------

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

Default: off

.. _template_ixfr-fslimit:
678

679 680 681 682
ixfr-fslimit
------------

Maximum zone journal file.
683

684
Default: unlimited
685

686
.. _template_dnssec-enable:
687

688 689
dnssec-enable
-------------
690

691
If enabled, automatic DNSSEC signing for the zone is turned on.
692

693
Default: off
694

695
.. _template_dnssec-keydir:
696

697 698
dnssec-keydir
-------------
699

700 701
A data directory for storing DNSSEC signing keys. Non absolute path is
relative to :ref:`storage<template_storage>`.
702

703
Default: :ref:`storage<template_storage>`/keys
704

705
.. _template_signature-lifetime:
706

707 708
signature-lifetime
------------------
709

710 711 712 713 714
The time how long the automatically generated DNSSEC signatures should be valid.
Expiration will thus be set as current time (in the moment of signing)
+ ``signature-lifetime``. The signatures are refreshed one tenth of the
signature lifetime before the signature expiration (i.e. 3 days before the
expiration with the default value). Minimum possible value is 10801.
715

716
Default: 30 * 24 * 3600
717

718
.. _template_serial-policy:
719

720 721
serial-policy
-------------
722

723 724 725
Specifies how the zone serial is updated after a dynamic update or
automatic DNSSEC signing. If the serial is changed by the dynamic update,
no change is made.
726

727
Possible values:
728

729 730
- ``increment`` - The serial is incremented according to serial number arithmetic
- ``unixtime`` - The serial is set to the current unix time
731

732 733 734 735
*Caution:* If your serial was in other than unix time format, be careful
with the transition to unix time.  It may happen that the new serial will
be \'lower\' than the old one. If this is the case, the transition should be
done by hand (see RFC 1982).
736

737
Default: increment
738

739
.. _template_module:
740

741 742
module
------
743

744 745
An ordered list of references to query modules in the form
*module_name/module_id*.
746

747
Default: empty
748

749
.. _Zone section:
750

751 752
Zone section
============
753

754
Definitions of zones served by the server.
755

756 757 758
Zone configuration is a superset of :ref:`template configuration<Template section>`,
so each zone configuration can contain all template configuration options which
may override possible template configuration.
759 760 761

::

762 763 764 765 766
 zone:
   - domain: DNAME
     file: STR
     template: template_id
     # All template options
767

768
.. _zone_domain:
769

770 771
domain
------
772

773
A zone name identifier.
774

775
.. _zone_file:
776

777 778
file
----
779

780 781
A path to the zone file. Non absolute path is relative to
:ref:`storage<template_storage>`.
782

783
Default: :ref:`storage<template_storage>`/``domain``.zone
784

785
.. _zone_template:
786

787 788
template
--------
789

790 791
A :ref:`reference<template_id>` to configuration template. If not specified
and *default* template exists, then the default template is used.
792

793
Default: empty
794

795
.. _Logging section:
796

797 798
Logging section
===============
799

800 801 802
Server can be configured to log to the standard output, standard error
output, syslog (or systemd journal if systemd is enabled) or into an arbitrary
file.
803

804
There are 6 logging severities:
805

806
- ``critical`` - Non-recoverable error resulting in server shutdown
807

808
- ``error`` - Recoverable error, action should be taken
809

810
- ``warning`` - Warning that might require user action
811

812
- ``notice`` - Server notice or hint
813

814
- ``info`` - Informational message
815

816
- ``debug`` - Debug messages (must be turned on at compile time)
817

818 819 820
In case of missing log section, ``warning`` or more serious messages
will be logged to both standard error output and syslog. The ``info`` and
``notice`` messages will be logged to standard output.
821

822
::
823

824 825 826 827 828
 log:
   - to: stdout | stderr | syslog | STR
     server: critical | error | warning | notice | info | debug
     zone: critical | error | warning | notice | info | debug
     any: critical | error | warning | notice | info | debug
829

830
.. _log_to:
831

832 833
to
--
834

835
A logging output.
836

837
Possible values:
838

839 840 841 842
- ``stdout`` - Standard output
- ``stderr`` - Standard error output
- ``syslog`` - Syslog
- *file_name* - File.
843

844
.. _log_server:
845

846 847
server
------
848

849 850
Minimum severity level for messages related to general operation of the server
that are logged.
851

852
Default: empty
853

854
.. _log_zone:
855

856 857
zone
----
858

859
Minimum severity level for messages related to zones that are logged.
860

861
Default: empty
862

863
.. _log_any:
864

865 866
any
---
867

868
Minimum severity level for all message types that are logged.
869

870
Default: empty
871

872
.. _Module dnstap:
873

874 875
Module dnstap
=============
876

877
Module dnstap allows query and response logging.
878

879 880
For all queries logging, use this module in the *default* template. For
zone-specific logging, use this module in the proper zone configuration.
881 882 883

::

884 885 886
 mod-dnstap:
   - id: STR
     sink: STR
887

888
.. _mod-dnstap_id:
889

890 891
id
--
892

893
A module identifier.
894

895
.. _mod-dnstap_sink:
896

897 898 899 900 901 902 903 904 905 906 907 908 909 910 911
sink
----

A sink path, which can either be a file or a UNIX socket prefixed with
``unix:``.

Default: empty

.. _Module synth-record:

Module synth-record
===================

This module is able to synthetise either forward or reverse records for the
given prefix and subnet.
912 913 914

::

915 916 917 918 919 920 921
 mod-synth-record:
   - id: STR
     type: forward | reverse
     prefix: STR
     zone: DNAME
     ttl: INT
     address: ADDR[/INT]
922

923
.. _mod-synth-record_id:
924

925 926
id
--
927

928
A module identifier.
929

930
.. _mod-synth-record_type:
931

932 933
type
----
934

935
The type of generated records.
936

937
Possible values:
938

939 940
- ``forward`` - Forward records
- ``reverse`` - Reverse records
941

942
Default: empty
943

944
.. _mod-synth-record_prefix:
945

946 947
prefix
------
948

949
A record owner prefix.
950

951 952
Caution: *prefix* doesn’t allow dots, address parts in the synthetic names are
separated with a dash.
953

954
Default: empty
955

956
.. _mod-synth-record_zone:
957

958 959
zone
----
960

961
A zone name suffix (only valid for :ref:`reverse type<mod-synth-record_type>`).
962

963
Default: empty
964

965
.. _mod-synth-record_ttl:
966

967 968
ttl
---
969

970
Time to live of the generated records.
971

972
Default: 3600
973

974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989
.. _mod-synth-record_address:

address
-------

A network subnet in the form of *address/prefix*.

Default: empty

.. _Module dnsproxy:

Module dnsproxy
===============

The module catches all unsatisfied queries and forwards them to the configured
server for resolution.
990 991 992

::

993 994 995
 mod-dnsproxy:
   - id: STR
     remote: ADDR[@INT]
996

997
.. _mod-dnsproxy_id:
998

999 1000
id
--
1001

1002
A module identifier.
1003

1004
.. _mod-dnsproxy_remote:
1005

1006 1007
remote
------
1008

1009 1010
An IP address of the destination server. Optional port specification
(default is 53) can be appended to the address using ``@`` separator.
1011

1012
Default: empty
1013

1014
.. _Module rosedb:
1015

1016 1017 1018 1019 1020
Module rosedb
=============

The module provides a mean to override responses for certain queries before
the record is searched in the available zones.
1021 1022 1023

::

1024 1025 1026
 mod-rosedb:
   - id: STR
     dbdir: STR
1027

1028
.. _mod-rosedb_id:
1029

1030 1031
id
--
1032

1033 1034 1035
A module identifier.

.. _mod-rosedb_dbdir:
1036

1037 1038
dbdir
-----
1039

1040
A path to the directory where the database will is stored.
1041

1042
Default: empty