configuration.rst 20.7 KB
Newer Older
1
.. highlight:: none
2
.. _Configuration:
3

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

8
Simple configuration
9 10
====================

11
The following example presents a simple configuration file
12
which can be used as a base for your Knot DNS setup::
13

14
    # Example of a very simple Knot DNS configuration.
15

16 17 18
    server:
        listen: 0.0.0.0@53
        listen: ::@53
19

20 21 22 23
    zone:
      - domain: example.com
        storage: /var/lib/knot/zones/
        file: example.com.zone
24

25
    log:
26
      - target: syslog
27
        any: info
28

29
Now let's walk through this configuration step by step:
30

31 32
- The :ref:`server_listen` statement in the :ref:`server section<Server section>`
  defines where the server will listen for incoming connections.
33
  We have defined the server to listen on all available IPv4 and IPv6 addresses,
34 35
  all on port 53.
- The :ref:`zone section<Zone section>` defines the zones that the server will
36
  serve. In this case, we defined one zone named *example.com* which is stored
37
  in the zone file :file:`/var/lib/knot/zones/example.com.zone`.
38
- The :ref:`log section<Logging section>` defines the log facilities for
39
  the server. In this example, we told Knot DNS to send its log messages with
40 41 42 43 44 45 46 47
  the severity ``info`` or more serious to the syslog.

For detailed description of all configuration items see
:ref:`Configuration Reference`.

Zone templates
==============

48
A zone template allows a single zone configuration to be shared among several zones.
49 50
The ``default`` template identifier is reserved for the default template::

51 52 53 54 55 56 57
    template:
      - id: default
        storage: /var/lib/knot/master
        semantic-checks: on

      - id: signed
        storage: /var/lib/knot/signed
58
        dnssec-signing: on
59
        semantic-checks: on
Daniel Salzman's avatar
Daniel Salzman committed
60
        master: [master1, master2]
61 62 63 64 65 66 67 68 69 70 71 72

      - id: slave
        storage: /var/lib/knot/slave

    zone:
      - domain: example1.com     # Uses default template

      - domain: example2.com     # Uses default template
        semantic-checks: off     # Override default settings

      - domain: example.cz
        template: signed
Daniel Salzman's avatar
Daniel Salzman committed
73
        master: master3          # Override masters to just master3
74 75 76 77 78 79 80 81 82

      - domain: example1.eu
        template: slave
        master: master1

      - domain: example2.eu
        template: slave
        master: master2

Daniel Salzman's avatar
Daniel Salzman committed
83 84 85
.. NOTE::
   Each template option can be explicitly overridden in zone-specific configuration.

86 87 88
Access control list (ACL)
=========================

89 90 91
The Access control list is a list of rules specifying remotes which are allowed to send certain types of requests to the server.
Remotes can be specified by a single IP address or a network subnet. A TSIG
key can also be assigned (see :doc:`keymgr <man_keymgr>` on how to generate a TSIG key).
92

93 94
Without any ACL rules, all the actions are denied for the zone. Each ACL rule
can allow one or more actions for a given address/subnet/TSIG, or deny them.
95

96 97 98
If there are multiple ACL rules for a single zone, they are applied in the order
of appearance in the :ref:`zone_acl` configuration item of a zone or a template.
The first one to match the given remote is applied, the rest is ignored.
99

Zuzana Lena Ansorgova's avatar
Zuzana Lena Ansorgova committed
100 101 102
See the following examples and :ref:`ACL section`.

::
103 104

    acl:
105
      - id: address_rule
106 107
        address: [2001:db8::1, 192.168.2.0/24]
        action: transfer
108

109
      - id: deny_rule
110 111
        address: 192.168.2.100
        action: transfer
112 113 114 115 116 117 118 119 120
        deny: on

    zone:
      - domain: acl1.example.com.
        acl: [deny_rule, address_rule] # deny_rule first here to take precendence

::

    key:
121
      - id: key1                  # The real TSIG key name
122 123 124 125 126 127 128
        algorithm: hmac-md5
        secret: Wg==

    acl:
      - id: deny_all
        address: 192.168.3.0/24
        deny: on # no action specified and deny on implies denial of all actions
129 130 131

      - id: key_rule
        key: key1                 # Access based just on TSIG key
132
        action: [transfer, notify]
133 134

    zone:
135 136
      - domain: acl2.example.com
        acl: [deny_all, key_rule]
137

138 139 140 141
.. NOTE::
   If more conditions (address ranges and/or a key)
   are given in a single ACL rule, all of them have to be satisfied for the rule to match.

142 143 144 145
Slave zone
==========

Knot DNS doesn't strictly differ between master and slave zones. The
146
only requirement is to have a :ref:`master<zone_master>` statement set for
147 148
the given zone. Also note that you need to explicitly allow incoming zone
changed notifications via ``notify`` :ref:`acl_action` through zone's
149
:ref:`zone_acl` list, otherwise the update will be rejected by the server.
150
If the zone file doesn't exist it will be bootstrapped over AXFR::
151 152 153 154 155 156

    remote:
      - id: master
        address: 192.168.1.1@53

    acl:
157
      - id: notify_from_master
158 159 160 161 162 163 164 165
        address: 192.168.1.1
        action: notify

    zone:
      - domain: example.com
        storage: /var/lib/knot/zones/
        # file: example.com.zone   # Default value
        master: master
166
        acl: notify_from_master
167

168
Note that the :ref:`zone_master` option accepts a list of multiple remotes.
169 170 171 172
The remotes should be listed according to their preference. The first remote
has the highest preference, the other remotes are used for failover. When the
server receives a zone update notification from a listed remote, that remote
will be the most preferred one for the subsequent transfer.
173

174 175
To use TSIG for transfers and notification messages authentication, configure
a TSIG key and assign the key both to the remote and the ACL rule. Notice that
Jan Včelák's avatar
Jan Včelák committed
176 177
the :ref:`remote <Remote section>` and :ref:`ACL <ACL section>` definitions are
independent::
178 179 180 181 182 183 184 185 186 187 188 189

    key:
      - id: slave1_key
        algorithm: hmac-md5
        secret: Wg==

    remote:
      - id: master
        address: 192.168.1.1@53
        key: slave1_key

    acl:
190
      - id: notify_from_master
191 192 193 194
        address: 192.168.1.1
        key: slave1_key
        action: notify

195 196 197 198 199 200 201 202 203 204
.. NOTE::
   When transferring a lot of zones, the server may easily get into a state
   when all available ports are in the TIME_WAIT state, thus the transfers
   seize until the operating system closes the ports for good. There are
   several ways to work around this:

   * Allow reusing of ports in TIME_WAIT (sysctl -w net.ipv4.tcp_tw_reuse=1)
   * Shorten TIME_WAIT timeout (tcp_fin_timeout)
   * Increase available local port count

205 206 207
Master zone
===========

208
An ACL with the ``transfer`` action must be configured to allow outgoing zone
209
transfers. An ACL rule consists of a single address or a network subnet::
210 211 212 213 214 215 216 217

    remote:
      - id: slave1
        address: 192.168.2.1@53

    acl:
      - id: slave1_acl
        address: 192.168.2.1
218
        action: transfer
219 220 221

      - id: others_acl
        address: 192.168.3.0/24
222
        action: transfer
223 224 225 226 227 228 229 230

    zone:
      - domain: example.com
        storage: /var/lib/knot/zones/
        file: example.com.zone
        notify: slave1
        acl: [slave1_acl, others_acl]

231
Optionally, a TSIG key can be specified::
232 233 234 235 236 237 238 239 240 241 242 243 244 245 246

    key:
      - id: slave1_key
        algorithm: hmac-md5
        secret: Wg==

    remote:
      - id: slave1
        address: 192.168.2.1@53
        key: slave1_key

    acl:
      - id: slave1_acl
        address: 192.168.2.1
        key: slave1_key
247
        action: transfer
248 249 250

      - id: others_acl
        address: 192.168.3.0/24
251
        action: transfer
252

253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281
Note that a slave zone may serve as a master zone at the same time::

    remote:
      - id: master
        address: 192.168.1.1@53
      - id: slave1
        address: 192.168.2.1@53

    acl:
      - id: notify_from_master
        address: 192.168.1.1
        action: notify

      - id: slave1_acl
        address: 192.168.2.1
        action: transfer

      - id: others_acl
        address: 192.168.3.0/24
        action: transfer

    zone:
      - domain: example.com
        storage: /var/lib/knot/zones/
        file: example.com.zone
        master: master
        notify: slave1
        acl: [notify_from_master, slave1_acl, others_acl]

282 283 284
Dynamic updates
===============

285
Dynamic updates for the zone are allowed via proper ACL rule with the
286
``update`` action. If the zone is configured as a slave and a DNS update
287 288
message is accepted, the server forwards the message to its primary master.
The master's response is then forwarded back to the originator.
289

290
However, if the zone is configured as a master, the update is accepted and
291
processed::
292

293 294 295 296
    acl:
      - id: update_acl
        address: 192.168.3.0/24
        action: update
297

298 299 300 301
    zone:
      - domain: example.com
        file: example.com.zone
        acl: update_acl
302

303 304
.. _dnssec:

305 306 307
Automatic DNSSEC signing
========================

308 309 310
Knot DNS supports automatic DNSSEC signing for static zones. The signing
can operate in two modes:

Libor Peltan's avatar
Libor Peltan committed
311
1. :ref:`Automatic key management <dnssec-automatic-zsk-management>`.
312
   In this mode, the server maintains signing keys. New keys are generated
313 314 315
   according to assigned policy and are rolled automatically in a safe manner.
   No zone operator intervention is necessary.

316 317 318
2. :ref:`Manual key management <dnssec-manual-key-management>`.
   In this mode, the server maintains zone signatures only. The signatures
   are kept up-to-date and signing keys are rolled according to timing
319 320
   parameters assigned to the keys. The keys must be generated and timing
   parameters must be assigned by the zone operator.
321

322
The DNSSEC signing process maintains some metadata which is stored in the
323 324
:abbr:`KASP (Key And Signature Policy)` database. This database is backed
by LMDB.
325

326
.. WARNING::
327
  Make sure to set the KASP database permissions correctly. For manual key
328
  management, the database must be *readable* by the server process. For
329 330
  automatic key management, it must be *writeable*. If no HSM is used,
  the database also contains private key material – don't set the permissions
331
  too weak.
332

Libor Peltan's avatar
Libor Peltan committed
333
.. _dnssec-automatic-zsk-management:
334

Libor Peltan's avatar
Libor Peltan committed
335
Automatic ZSK management
336 337
------------------------

338 339 340 341 342
For automatic ZSK management a signing :ref:`policy<Policy section>` has to
be configured and assigned to the zone. The policy specifies how the zone
is signed (i.e. signing algorithm, key size, key lifetime, signature lifetime,
etc.). If no policy is specified or the ``default`` one is assigned, the
default signing parameters are used.
343 344

A minimal zone configuration may look as follows::
345

346 347 348
  zone:
    - domain: myzone.test
      dnssec-signing: on
349

350
With a custom signing policy, the policy section will be added::
351

352
  policy:
353
    - id: rsa
354 355 356
      algorithm: RSASHA256
      ksk-size: 2048
      zsk-size: 1024
357 358 359

  zone:
    - domain: myzone.test
360
      dnssec-signing: on
361
      dnssec-policy: rsa
362

363
After configuring the server, reload the changes:
364 365

.. code-block:: console
366

367
  $ knotc reload
368 369 370 371

The server will generate initial signing keys and sign the zone properly. Check
the server logs to see whether everything went well.

372
.. WARNING::
373 374
  This guide assumes that the zone *myzone.test* was not signed prior to
  enabling the automatic key management. If the zone was already signed, all
Daniel Salzman's avatar
Daniel Salzman committed
375
  existing keys must be imported using ``keymgr import-bind`` command
376
  before enabling the automatic signing. Also the algorithm in the policy must
377
  match the algorithm of all imported keys. Otherwise the zone will be re-signed
378
  at all.
379

Libor Peltan's avatar
Libor Peltan committed
380 381 382 383 384 385 386 387 388 389
.. _dnssec-automatic-ksk-management:

Automatic KSK management
------------------------

For automatic KSK management, first configure ZSK management like above, and use
additional options in :ref:`policy section <Policy section>`, mostly specifying
desired (finite) lifetime for KSK: ::

  remote:
Daniel Salzman's avatar
Daniel Salzman committed
390
    - id: test_zone_server
Libor Peltan's avatar
Libor Peltan committed
391
      address: 192.168.12.1@53
Libor Peltan's avatar
Libor Peltan committed
392

393
  submission:
Daniel Salzman's avatar
Daniel Salzman committed
394 395
    - id: test_zone_sbm
      parent: [test_zone_server]
396

Libor Peltan's avatar
Libor Peltan committed
397 398 399 400 401
  policy:
    - id: rsa
      algorithm: RSASHA256
      ksk-size: 2048
      zsk-size: 1024
Daniel Salzman's avatar
Daniel Salzman committed
402
      zsk-lifetime: 30d
Libor Peltan's avatar
Libor Peltan committed
403
      ksk-lifetime: 365d
Daniel Salzman's avatar
Daniel Salzman committed
404
      ksk-submission: test_zone_sbm
Libor Peltan's avatar
Libor Peltan committed
405 406 407 408 409 410 411

  zone:
    - domain: myzone.test
      dnssec-signing: on
      dnssec-policy: rsa

After the initially-generated KSK reaches its lifetime, new KSK is published and after
412
convenience delay the submission is started. The server publishes CDS and CDNSKEY records
Libor Peltan's avatar
Libor Peltan committed
413 414 415
and the user shall propagate them to the parent. The server periodically checks for
DS at the master and when positive, finishes the rollover.

Libor Peltan's avatar
Libor Peltan committed
416 417 418 419 420
To share KSKs among zones, set the ksk-shared policy parameter. It is strongly discouraged to
change the policy ``id`` afterwards! The shared key's creation timestamp will be equal for all
zones, but other timers (e.g. activate, retire) may get out of sync. ::

  policy:
Daniel Salzman's avatar
Daniel Salzman committed
421 422
    - id: shared
      ...
Libor Peltan's avatar
Libor Peltan committed
423 424 425 426 427
      ksk-shared: true

  zone:
    - domain: firstzone.test
      dnssec-signing: on
Daniel Salzman's avatar
Daniel Salzman committed
428
      dnssec-policy: shared
Libor Peltan's avatar
Libor Peltan committed
429 430 431 432

  zone:
    - domain: secondzone.test
      dnssec-signing: on
Daniel Salzman's avatar
Daniel Salzman committed
433
      dnssec-policy: shared
Libor Peltan's avatar
Libor Peltan committed
434

435 436 437 438 439 440
.. _dnssec-manual-key-management:

Manual key management
---------------------

For automatic DNSSEC signing with manual key management, a signing policy
441
with manual key management flag has to be set::
442

443
  policy:
444
    - id: manual
445
      manual: on
446

447 448 449
  zone:
    - domain: myzone.test
      dnssec-signing: on
450
      dnssec-policy: manual
451

Daniel Salzman's avatar
Daniel Salzman committed
452
To generate signing keys, use the :doc:`keymgr <man_keymgr>` utility.
453
Let's use the Single-Type Signing scheme with two algorithms. Run:
454 455

.. code-block:: console
456

457 458
  $ keymgr myzone.test. generate algorithm=ECDSAP256SHA256
  $ keymgr myzone.test. generate algorithm=ED25519
459

460
And reload the server. The zone will be signed.
461

462 463
To perform a manual rollover of a key, the timing parameters of the key need
to be set. Let's roll the RSA key. Generate a new RSA key, but do not activate
464 465 466
it yet:

.. code-block:: console
467

468
  $ keymgr myzone.test. generate algorithm=RSASHA256 size=1024 active=+1d
469 470

Take the key ID (or key tag) of the old RSA key and disable it the same time
471 472 473
the new key gets activated:

.. code-block:: console
474

475
  $ keymgr myzone.test. set <old_key_id> retire=+1d remove=+1d
476

477 478 479 480 481
Reload the server again. The new key will be published (i.e. the DNSKEY record
will be added into the zone). Do not forget to update the DS record in the
parent zone to include a reference to the new RSA key. This must happen in one
day (in this case) including a delay required to propagate the new DS to
caches.
482 483 484 485 486 487 488 489

Note that as the ``+1d`` time specification is computed from the current time,
the key replacement will not happen at once. First, a new key will be
activated.  A few moments later, the old key will be deactivated and removed.
You can use exact time specification to make these two actions happen in one
go.

.. _dnssec-signing:
490 491 492 493 494 495

Zone signing
------------

The signing process consists of the following steps:

496 497 498 499 500
#. Processing KASP database events. (e.g. performing a step of a rollover).
#. Updating the DNSKEY records. The whole DNSKEY set in zone apex is replaced
   by the keys from the KASP database. Note that keys added into the zone file
   manually will be removed. To add an extra DNSKEY record into the set, the
   key must be imported into the KASP database (possibly deactivated).
501
#. Fixing the NSEC or NSEC3 chain.
502
#. Removing expired signatures, invalid signatures, signatures expiring
503
   in a short time, and signatures issued by an unknown key.
504 505 506
#. Creating missing signatures. Unless the Single-Type Signing Scheme
   is used, DNSKEY records in a zone apex are signed by KSK keys and
   all other records are signed by ZSK keys.
507
#. Updating and re-signing SOA record.
508 509 510

The signing is initiated on the following occasions:

511 512 513
- Start of the server
- Zone reload
- Reaching the signature refresh period
514
- Key set changed due to rollover event
515
- Received DDNS update
516
- Forced zone re-sign via server control interface
517

518
On a forced zone re-sign, all signatures in the zone are dropped and recreated.
519

520
The ``knotc zone-status`` command can be used to see when the next scheduled
521
DNSSEC re-sign will happen.
522

Libor Peltan's avatar
Libor Peltan committed
523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546
.. _dnssec-on-slave-signing:

On-slave signing
----------------

It is possible to enable automatic DNSSEC zone signing even on a slave
server. If enabled, the zone is signed after every AXFR/IXFR transfer
from master, so that the slave always serves a signed up-to-date version
of the zone.

It is strongly recommended to block any outside access to the master
server, so that only the slave's signed version of the zone is served.

Enabled on-slave signing introduces events when the slave zone changes
while the master zone remains unchanged, such as a key rollover or
refreshing of RRSIG records, which cause inequality of zone SOA serial
between master and slave. The slave server handles this by saving the
master's SOA serial in a special variable inside KASP DB and appropriately
modifiying AXFR/IXFR queries/answers to keep the communication with
master consistent while applying the changes with a different serial.

It is recommended to use UNIX time serial policy on master and incremental
serial policy on slave so that their SOA serials are equal most of the time.

547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568
.. _query-modules:

Query modules
=============

Knot DNS supports configurable query modules that can alter the way
queries are processed. Each query requires a finite number of steps to
be resolved. We call this set of steps a *query plan*, an abstraction
that groups these steps into several stages.

* Before-query processing
* Answer, Authority, Additional records packet sections processing
* After-query processing

For example, processing an Internet-class query needs to find an
answer. Then based on the previous state, it may also append an
authority SOA or provide additional records. Each of these actions
represents a 'processing step'. Now, if a query module is loaded for a
zone, it is provided with an implicit query plan which can be extended
by the module or even changed altogether.

A module is active if its name, which includes the ``mod-`` prefix, is assigned
569
to the zone/template :ref:`zone_module` option or to the ``default`` template
570 571 572 573 574 575 576 577 578 579 580
:ref:`template_global-module` option if activating for all queries.
If the module is configurable, a corresponding module section with
an identifier must be created and then referenced in the form of
``module_name/module_id``. See :ref:`Modules` for the list of available modules.

.. NOTE::
   Query modules are processed in the order they are specified in the
   zone/template configuration. In most cases, the recommended order is::

      mod-synthrecord, mod-onlinesign, mod-rrl, mod-dnstap, mod-stats

581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648
Performance Tuning
==================

Numbers of Workers
------------------

There are three types of workers ready for parallel execution of performance-oriented tasks:
UDP workers, TCP workers, and Background workers. The first two types handle all network requests
coming through UDP and TCP protocol (respectively) and do all the response job for common
queries. Background workers process changes to the zone.

By default, Knot determines well-fitting number of workers based on the number of CPU cores.
The user can specify the numbers of workers for each type with configuration/server section:
:ref:`server_udp-workers`, :ref:`server_tcp-workers`, :ref:`server_background-workers`.

An indication on when to increase number of workers is a situation when the server is lagging behind
the expected performance, while the CPU usage is low. This is usually because of waiting for network
or I/O response during the operation. It may be caused by Knot design not fitting well the usecase.
The user should try increasing the number of workers (of the related type) slightly above 100 and if
the performance gets better, he can decide about further exact setting.

Sysctl and NIC optimizations
----------------------------

There are several recommendations based on Knot developers' experience with their specific HW and SW
(mainstream Intel-based servers, Debian-based GNU/Linux distribution). They may or may not positively
(or negatively) influence performance in common use cases.

If your NIC driver allows it (see /proc/interrupts for hint), set CPU affinity (/proc/irq/$IRQ/smp_affinity)
manually so that each NIC channel is served by unique CPU core(s). You must turn off irqbalance service
before to avoid configuration override.

Configure sysctl as follows: ::

    socket_bufsize=1048576
    busy_latency=0
    backlog=40000
    optmem_max=20480

    net.core.wmem_max     = $socket_bufsize
    net.core.wmem_default = $socket_bufsize
    net.core.rmem_max     = $socket_bufsize
    net.core.rmem_default = $socket_bufsize
    net.core.busy_read = $busy_latency
    net.core.busy_poll = $busy_latency
    net.core.netdev_max_backlog = $backlog
    net.core.optmem_max = $optmem_max

Disable huge pages.

Configure your CPU to "performance" mode. This can be achieved depending on architecture, e.g. in BIOS,
or e.g. configuring /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor to "performance".

Tune your NIC device with ethtool: ::

    ethtool -A $dev autoneg off rx off tx off
    ethtool -K $dev tso off gro off ufo off
    ethtool -G $dev rx 4096 tx 4096
    ethtool -C $dev rx-usecs 75
    ethtool -C $dev tx-usecs 75
    ethtool -N $dev rx-flow-hash udp4 sdfn
    ethtool -N $dev rx-flow-hash udp6 sdfn

On FreeBSD you can just: ::

    ifconfig ${dev} -rxcsum -txcsum -lro -tso

Knot developers are open to hear about users' further suggestions about network devices tuning/optimization.