configuration.rst 30.3 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 49
A zone template allows a single zone configuration to be shared among several zones.
Each template option can be explicitly overridden in zone-specific configurations.
50 51 52 53 54 55 56 57 58
A ``default`` template identifier is reserved for the default template::

    template:
      - id: default
        storage: /var/lib/knot/master
        semantic-checks: on

      - id: signed
        storage: /var/lib/knot/signed
59
        dnssec-signing: on
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
        semantic-checks: on

      - 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

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

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

Access control list (ACL)
=========================

85
An ACL list specifies which remotes are allowed to send the server a specific
86
request. A remote can be a single IP address or a network subnet. Also a TSIG
87
key can be assigned::
88 89

    acl:
90 91 92
      - id: address_rule
        address: [2001:db8::1, 192.168.2.0/24] # Allowed IP address list
        action: [transfer, update]  # Allow zone transfers and updates
93

94 95 96 97
      - id: deny_rule             # Negative match rule
        address: 192.168.2.100
        action: transfer
        deny: on                  # The request is denied
98 99 100

      - id: key_rule
        key: key1                 # Access based just on TSIG key
101
        action: transfer
102

103
These rules can then be referenced from a zone :ref:`zone_acl`::
104 105 106

    zone:
      - domain: example.com
107
        acl: [address_rule, deny_rule, key_rule]
108 109 110 111 112

Slave zone
==========

Knot DNS doesn't strictly differ between master and slave zones. The
113
only requirement is to have a :ref:`master<zone_master>` statement set for
114 115
the given zone. Also note that you need to explicitly allow incoming zone
changed notifications via ``notify`` :ref:`acl_action` through zone's
116
:ref:`zone_acl` list, otherwise the update will be rejected by the server.
117
If the zone file doesn't exist it will be bootstrapped over AXFR::
118 119 120 121 122 123

    remote:
      - id: master
        address: 192.168.1.1@53

    acl:
124
      - id: notify_from_master
125 126 127 128 129 130 131 132
        address: 192.168.1.1
        action: notify

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

135
Note that the :ref:`zone_master` option accepts a list of multiple remotes.
136 137 138 139
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.
140

141 142
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
143 144
the :ref:`remote <Remote section>` and :ref:`ACL <ACL section>` definitions are
independent::
145 146 147 148 149 150 151 152 153 154 155 156

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

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

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

Master zone
===========

165
An ACL with the ``transfer`` action must be configured to allow outgoing zone
166
transfers. An ACL rule consists of a single address or a network subnet::
167 168 169 170 171 172 173 174

    remote:
      - id: slave1
        address: 192.168.2.1@53

    acl:
      - id: slave1_acl
        address: 192.168.2.1
175
        action: transfer
176 177 178

      - id: others_acl
        address: 192.168.3.0/24
179
        action: transfer
180 181 182 183 184 185 186 187

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

188
Optionally, a TSIG key can be specified::
189 190 191 192 193 194 195 196 197 198 199 200 201 202 203

    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
204
        action: transfer
205 206 207

      - id: others_acl
        address: 192.168.3.0/24
208
        action: transfer
209 210 211 212

Dynamic updates
===============

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

218
However, if the zone is configured as a master, the update is accepted and
219
processed::
220

221 222 223 224
    acl:
      - id: update_acl
        address: 192.168.3.0/24
        action: update
225

226 227 228 229
    zone:
      - domain: example.com
        file: example.com.zone
        acl: update_acl
230

231 232
Response rate limiting
======================
233

234 235 236 237 238 239 240 241 242 243 244 245 246 247
Response rate limiting (RRL) is a method to combat DNS reflection amplification
attacks. These attacks rely on the fact that source address of a UDP query
can be forged, and without a worldwide deployment of `BCP38
<https://tools.ietf.org/html/bcp38>`_, such a forgery cannot be prevented.
An attacker can use a DNS server (or multiple servers) as an amplification
source and can flood a victim with a large number of unsolicited DNS responses.

The RRL lowers the amplification factor of these attacks by sending some of
the responses as truncated or by dropping them altogether.

You can enable RRL by setting the :ref:`server_rate-limit` option in the
:ref:`server section<Server section>`. The option controls how many responses
per second are permitted for each flow. Responses exceeding this rate are
limited. The option :ref:`server_rate-limit-slip` then configures how many
Jan Včelák's avatar
Jan Včelák committed
248 249 250
limited responses are sent as truncated (slip) instead of being dropped.

::
251 252

    server:
253 254
        rate-limit: 200     # Allow 200 resp/s for each flow
        rate-limit-slip: 2  # Every other response slips
255

256 257
.. _dnssec:

258 259 260
Automatic DNSSEC signing
========================

261 262 263 264 265 266 267 268 269 270
Knot DNS supports automatic DNSSEC signing for static zones. The signing
can operate in two modes:

1. :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
   parameters assigned to the keys. The keys must be generated by the zone
   operator.

2. :ref:`Automatic key management <dnssec-automatic-key-management>`.
271
   In this mode, the server also maintains signing keys. New keys are generated
272 273 274
   according to assigned policy and are rolled automatically in a safe manner.
   No zone operator intervention is necessary.

275 276
The DNSSEC signing is controlled by the :ref:`zone_dnssec-signing` and
:ref:`zone_kasp_db` configuration options. The first option states
277 278 279 280 281
if the signing is enabled for a particular zone, the second option points to
a KASP database holding the signing configuration.

.. _dnssec-example:

282 283 284
Example configuration
---------------------

285 286 287
The example configuration enables automatic signing for all zones in the
default template, but the signing is explicitly disabled for zone
``example.dev``. The KASP database is common for all zones::
288

289 290
    template:
      - id: default
291
        dnssec-signing: on
292
        kasp-db: /var/lib/knot/kasp
293

294 295 296
    zone:
      - domain: example.com
        file: example.com.zone
297

298 299
      - domain: example.dev
        file: example.dev.zone
300
        dnssec-signing: off
301

302 303 304 305 306
.. _dnssec-kasp:

DNSSEC KASP database
--------------------

307
The configuration for DNSSEC is stored in the :abbr:`KASP (Key And Signature
308
Policy)` database. The database is simply a directory in the file-system
309
containing files in the JSON format. The database contains
310

311
- definitions of signing policies;
312 313
- private key stores configuration; and
- zones configuration and signing metadata.
314 315

The :doc:`keymgr <man_keymgr>` utility serves for the database maintenance.
316 317 318
To initialize the database, run:

.. code-block:: console
319 320 321 322 323

  $ mkdir -p /var/lib/knot/kasp
  $ cd /var/lib/knot/kasp
  $ keymgr init

324 325 326 327 328
The *init* command initializes the database, defines a default signing policy
named *default* with default signing parameters, and defines a default key
store named *default* with file-backed key store within the KASP database
directory.

329 330
.. ATTENTION::
  Make sure to set the KASP database permissions correctly. For manual key
331 332
  management, the database must be *readable* by the server process. For
  automatic key management, it must be *writeable*. The database also
333
  contains private key material – don't set the permissions too loose.
334 335 336 337 338 339

.. _dnssec-automatic-key-management:

Automatic key management
------------------------

340
For automatic key management, a signing policy has to be defined in the
341
first place. This policy specifies how a zone is signed (i.e. signing
342
algorithm, key size, signature lifetime, key lifetime, etc.).
343

344
To create a new policy named *rsa* using *RSA-SHA-256* algorithm for
345 346 347
signing keys, 1024-bit long ZSK, and 2048-bit long KSK, run:

.. code-block:: console
348

349
  $ keymgr policy add rsa algorithm RSASHA256 zsk-size 1024 ksk-size 2048
350 351 352 353 354

The unspecified policy parameters are set to defaults. The complete definition
of the policy will be printed after executing the command.

Next, create a zone entry for zone *myzone.test* and assign it the newly
355 356 357
created policy:

.. code-block:: console
358

359
  $ keymgr zone add myzone.test policy rsa
360

361 362 363
Make sure everything is set correctly:

.. code-block:: console
364

365
  $ keymgr policy show rsa
366 367 368 369 370 371 372
  $ keymgr zone show myzone.test

Add the zone into the server configuration and enable DNSSEC for that zone.
The configuration fragment might look similar to::

  template:
    - id: default
373
      storage: /var/lib/knot
374
      kasp-db: kasp
375 376 377

  zone:
    - domain: myzone.test
378
      dnssec-signing: on
379

380 381 382
Finally, reload the server:

.. code-block:: console
383

384
  $ knotc reload
385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401

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

.. ATTENTION::
  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
  existing keys must be imported using ``keymgr zone key import`` command
  before reloading the server. Also the algorithm in the policy must match
  the algorithm of all imported keys.

.. _dnssec-manual-key-management:

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

For automatic DNSSEC signing with manual key management, a signing policy
402 403 404 405 406 407 408
with manual key management flag has to be set.

Define a signing policy named *man* with disabled automatic key management:

.. code-block:: console

  $ keymgr policy add man manual true
409

410
Create a zone entry for the zone *myzone.test* with the created policy:
411 412

.. code-block:: console
413

414
  $ keymgr zone add myzone.test policy man
415

416
Generate signing keys for the zone. Let's use the Single-Type Signing scheme
417 418
with two algorithms, which is a scheme currently not supported by the automatic
key management. Run:
419 420

.. code-block:: console
421

422 423
  $ keymgr zone key generate myzone.test algorithm RSASHA256 size 1024
  $ keymgr zone key generate myzone.test algorithm ECDSAP256SHA256 size 256
424

425 426 427
Enable automatic DNSSEC signing for the zone in the server configuration and
reload the server. Use the same steps as in
:ref:`dnssec-automatic-key-management`.
428

429 430
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
431 432 433
it yet:

.. code-block:: console
434 435 436 437

  $ keymgr zone key generate myzone.test algorithm RSASHA256 size 1024 activate +1d

Take the key ID (or key tag) of the old RSA key and disable it the same time
438 439 440
the new key gets activated:

.. code-block:: console
441 442 443 444 445 446 447 448 449 450 451 452 453 454 455

  $ keymgr zone key set myzone.test <old_key_id> retire +1d remove +1d

Reload the server again. The new key gets published. Do not forget to update
the DS record in the parent zone to include the 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.

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-policy:
456 457 458 459

Signing policy
--------------

460 461 462 463 464 465
The signing policy used in the KASP database defines parameters, how the zone
signatures and keys should be handled. At the moment, the policy comprises
of the following parameters:

Signing algorithm
  An algorithm of signing keys and issued signatures. The default value is
466
  *ECDSA-P256-SHA256*.
467 468

:abbr:`KSK (Key Signing Key)` size
469 470
  Desired length of the newly generated ZSK keys. The default value is 256
  bits (the only feasible value for the default signing algorithm).
471 472

:abbr:`ZSK (Zone Signing Key)` size
473
  Desired length of the newly generated ZSK keys. The default value is 256
474
  bits.
475

476 477 478 479 480 481
DNSKEY TTL
  TTL value for DNSKEY records added into zone apex. This parameter is
  temporarily overridden by the TTL value of the zone SOA record and thus
  has no default value.

ZSK lifetime
482 483
  Period between ZSK publication and the next rollover initiation. The default
  value is 30 days.
484 485

RRSIG lifetime
486
  Validity period of newly issued signatures. The default value is 14 days.
487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510

RRSIG refresh
  Specifies how long before a signature expiration the signature will be
  refreshed. The default value is 7 days.

NSEC3
  Specifies if NSEC3 will be used instead of NSEC. This value is temporarily
  ignored. The setting is derived from the NSEC3PARAM record presence in the
  zone. The default value has not been decided yet.

SOA minimum TTL
  Specifies the SOA Minimum TTL field value. This option is required for
  correct key rollovers. The value has no real meaning with Knot DNS because
  the server will use a real value from the zone.

Zone maximum TTL
  Maximum TTL value present in the zone. This option is required for correct
  key rollovers. Knot DNS will determine the value automatically in the future.

Propagation delay
  An extra delay added for each key rollover step. This value should be high
  enough to cover propagation of data from the master server to all slaves.
  The default value is 1 hour.

511 512 513 514 515 516 517 518
Key store name
  A name of a key store holding private key material for zones which use the
  policy. The default value is *default*.

Manual key management
  An option to disable key management for all zones which use the policy. The
  option is disabled by default.

519
.. _dnssec-signing:
520 521 522 523 524 525

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

The signing process consists of the following steps:

526 527 528 529 530 531 532
#. Processing KASP database events. (e.g. performing a step of a rollover).
#. Fixing the NSEC or NSEC3 chain.
#. 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).
#. Removing expired signatures, invalid signatures, signatures expiring
533
   in a short time, and signatures issued by an unknown key.
534 535 536 537 538 539 540
#. 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.
#. Updating and resigning SOA record.

The signing is initiated on the following occasions:

541 542 543 544 545
- Start of the server
- Zone reload
- Reaching the signature refresh period
- Received DDNS update
- Forced zone resign issued with ``knotc signzone``
546

547
On a forced zone resign, all signatures in the zone are dropped and recreated.
548 549 550 551 552 553 554 555 556 557

The ``knotc zonestatus`` command can be used to see when the next scheduled
DNSSEC resign will happen.

.. _dnssec-limitations:

Limitations
-----------

The current DNSSEC implementation in Knot DNS has a bunch of limitations. Most
558
of the limitations will be hopefully removed in the near future.
559 560 561

- Automatic key management:

562
  - Only one DNSSEC algorithm can be used per zone.
563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588
  - Single-Type Signing scheme is not supported.
  - ZSK rollover always uses key pre-publish method (actually a feature).
  - KSK rollover is not implemented.

- Manual key management:

  - Default values for signature lifetime are forced.

- NSEC3:

  - Use of NSEC3 is determined by the presence of NSEC3PARAM in the zone.
  - Automatic re-salt is not implemented.

- KASP policy:

  - DNSKEY TTL value is overridden by the SOA TTL.
  - NSEC3 related parameters are ignored.
  - Zone maximum TTL is not determined automatically.

- Signing:

  - Signature expiration jitter is not implemented.
  - Signature expiration skew is not implemented.

- Utilities:

589
  - Legacy key import requires a private key.
590 591
  - Legacy key export is not implemented.
  - DS record export is not implemented.
592 593 594 595 596

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

Knot DNS supports configurable query modules that can alter the way
597
queries are processed. The concept is quite simple – each query
598
requires a finite number of steps to be resolved. We call this set of
599
steps a *query plan*, an abstraction that groups these steps into
600 601
several stages.

602
* Before-query processing
603
* Answer, Authority, Additional records packet sections processing
604
* After-query processing
605

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

613
Each module is configured in the corresponding module section and is
614
identified for the subsequent usage. Then the identifier is referenced
615 616 617
in the form of ``module_name/module_id`` through a zone/template :ref:`zone_module`
option or through the *default* template :ref:`template_global-module` option
if it is used for all queries.
618

619 620
``dnstap`` – dnstap-enabled query logging
-----------------------------------------
621

622 623 624 625
A module for query and response logging based on dnstap_ library.
You can capture either all or zone-specific queries and responses; usually
you want to do the former. The configuration conprises only a
:ref:`mod-dnstap_sink` path parameter, which can be either a file or
626
a UNIX socket::
627

628 629 630
    mod-dnstap:
      - id: capture_all
        sink: /tmp/capture.tap
631

632 633
    template:
      - id: default
634
        global-module: mod-dnstap/capture_all
635 636 637

.. _dnstap: http://dnstap.info/

638 639
``synth-record`` – Automatic forward/reverse records
----------------------------------------------------
640

641
This module is able to synthesize either forward or reverse records for
642
a given prefix and subnet.
643

644
Records are synthesized only if the query can't be satisfied from the zone.
645
Both IPv4 and IPv6 are supported.
646

647 648
Automatic forward records
-------------------------
649

650 651 652 653 654 655 656
Example::

   mod-synth-record:
     - id: test1
       type: forward
       prefix: dynamic-
       ttl: 400
657
       network: 2620:0:b61::/52
658 659

   zone:
660 661
     - domain: test.
       file: test.zone # Must exist
662 663
       module: mod-synth-record/test1

664 665 666
Result:

.. code-block:: console
667

668
   $ kdig AAAA dynamic-2620-0000-0b61-0100-0000-0000-0000-0001.test.
669 670
   ...
   ;; QUESTION SECTION:
671
   ;; dynamic-2620-0000-0b61-0100-0000-0000-0000-0001.test. IN AAAA
672

673
   ;; ANSWER SECTION:
674
   dynamic-2620-0000-0b61-0100-0000-0000-0000-0001.test. 400 IN AAAA 2620:0:b61:100::1
675

676
You can also have CNAME aliases to the dynamic records, which are going to be
677
further resolved:
678 679

.. code-block:: console
680

681
   $ kdig AAAA alias.test.
682 683
   ...
   ;; QUESTION SECTION:
684
   ;; alias.test. IN AAAA
685

686
   ;; ANSWER SECTION:
687 688
   alias.test. 3600 IN CNAME dynamic-2620-0000-0b61-0100-0000-0000-0000-0002.test.
   dynamic-2620-0000-0b61-0100-0000-0000-0000-0002.test. 400 IN AAAA 2620:0:b61:100::2
689 690 691

Automatic reverse records
-------------------------
692

693 694 695 696 697 698
Example::

   mod-synth-record:
     - id: test2
       type: reverse
       prefix: dynamic-
699
       origin: test
700
       ttl: 400
701
       network: 2620:0:b61::/52
702 703 704

   zone:
     - domain: 1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.
705
       file: 1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.zone # Must exist
706 707
       module: mod-synth-record/test2

708 709 710
Result:

.. code-block:: console
711

712
   $ kdig -x 2620:0:b61::1
713 714
   ...
   ;; QUESTION SECTION:
715
   ;; 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. IN PTR
716 717

   ;; ANSWER SECTION:
718 719
   1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. 400 IN PTR
                                  dynamic-2620-0000-0b61-0000-0000-0000-0000-0001.test.
720

721 722
``dnsproxy`` – Tiny DNS proxy
-----------------------------
723

724
The module catches all unsatisfied queries and forwards them to the
725
indicated server for resolution, i.e. a tiny DNS proxy. There are several
726
uses of this feature:
727 728 729 730 731

* A substitute public-facing server in front of the real one
* Local zones (poor man's "views"), rest is forwarded to the public-facing server
* etc.

732 733
*Note: The module does not alter the query/response as the resolver would,
and the original transport protocol is kept as well.*
734

735 736 737 738 739 740
The configuration is straightforward and just a single remote server is
required::

   remote:
     - id: hidden
       address: 10.0.1.1
741

742 743
   mod-dnsproxy:
     - id: default
744
       remote: hidden
745

746 747
   template:
     - id: default
748
       global-module: mod-dnsproxy/default
749

750 751
   zone:
     - domain: local.zone
752

753
When clients query for anything in the ``local.zone``, they will be
754
responded to locally. The rest of the requests will be forwarded to the
755
specified server (``10.0.1.1`` in this case).
756

757 758
``rosedb`` – Static resource records
------------------------------------
759

760
The module provides a mean to override responses for certain queries before
761
the record is searched in the available zones. The module comes with the
762
``rosedb_tool`` tool used to manipulate the database of static records.
763
Neither the tool nor the module are enabled by default, recompile with
764
the ``--enable-rosedb`` configuration flag to enable them.
765

766
For example, let's suppose we have a database of following records:
767 768

.. code-block:: none
769

770 771 772
   myrecord.com.      3600 IN A 127.0.0.1
   www.myrecord.com.  3600 IN A 127.0.0.2
   ipv6.myrecord.com. 3600 IN AAAA ::1
773

774
And we query the nameserver with the following:
775 776

.. code-block:: console
777

778 779 780 781 782 783 784 785 786 787 788
   $ kdig IN A myrecord.com
     ... returns NOERROR, 127.0.0.1
   $ kdig IN A www.myrecord.com
     ... returns NOERROR, 127.0.0.2
   $ kdig IN A stuff.myrecord.com
     ... returns NOERROR, 127.0.0.1
   $ kdig IN AAAA myrecord.com
     ... returns NOERROR, NODATA
   $ kdig IN AAAA ipv6.myrecord.com
     ... returns NOERROR, ::1

789
*Note: An entry in the database matches anything at the same or a lower domain
790 791
level, i.e. 'myrecord.com' matches 'a.a.myrecord.com' as well.
This can be utilized to create catch-all entries.*
792

793 794
You can also add authority information for the entries, provided you create
SOA + NS records for a name, like so:
795 796

.. code-block:: none
797

798 799 800 801 802
   myrecord.com.     3600 IN SOA master host 1 3600 60 3600 3600
   myrecord.com.     3600 IN NS ns1.myrecord.com.
   myrecord.com.     3600 IN NS ns2.myrecord.com.
   ns1.myrecord.com. 3600 IN A 127.0.0.1
   ns2.myrecord.com. 3600 IN A 127.0.0.2
803 804 805 806 807

In this case, the responses will:

1. Be authoritative (AA flag set)
2. Provide an authority section (SOA + NS)
808
3. Be NXDOMAIN if the name is found *(i.e. the 'IN AAAA myrecord.com' from
809
   the example)*, but not the RR type *(this is to allow the synthesis of
810
   negative responses)*
811

812
*Note: The SOA record applies only to the 'myrecord.com.', not to any other
813
record (not even those of its subdomains). From this point of view, all records
814
in the database are unrelated and not hierarchical. The idea is to provide
815
subtree isolation for each entry.*
816

817
In addition, the module is able to log matching queries via remote syslog if
818
you specify a syslog address endpoint and an optional string code.
819 820 821

Here is an example on how to use the module:

822 823 824
* Create the entries in the database:

  .. code-block:: console
825

826
   $ mkdir /tmp/static_rrdb
827
   $ # No logging
828
   $ rosedb_tool /tmp/static_rrdb add myrecord.com. A 3600 "127.0.0.1" "-" "-"
829
   $ # Logging as 'www_query' to Syslog at 10.0.0.1
830
   $ rosedb_tool /tmp/static_rrdb add www.myrecord.com. A 3600 "127.0.0.1" \
831 832
                                                    "www_query" "10.0.0.1"
   $ # Logging as 'ipv6_query' to Syslog at 10.0.0.1
833
   $ rosedb_tool /tmp/static_rrdb add ipv6.myrecord.com. AAAA 3600 "::1" \
834 835 836
                                                 "ipv6_query" "10.0.0.1"
   $ # Verify settings
   $ rosedb_tool /tmp/static_rrdb list
837 838 839
   www.myrecord.com.       A RDATA=10B     www_query       10.0.0.1
   ipv6.myrecord.com.      AAAA RDATA=22B  ipv6_query      10.0.0.1
   myrecord.com.           A RDATA=10B     -               -
840

841
  *Note: The database may be modified later on while the server is running.*
842

843 844 845 846 847 848 849 850
* Configure the query module::

   mod-rosedb:
     - id: default
       dbdir: /tmp/static_rrdb

   template:
     - id: default
851
       global-module: mod-rosedb/default
852

853
  *Note: The module accepts just one parameter – the path to the directory where
854
  the database will be stored.*
855

856 857 858
* Start the server:

  .. code-block:: console
859

860
   $ knotd -c knot.conf
861

862 863 864
* Verify the running instance:

  .. code-block:: console
865

866
   $ kdig @127.0.0.1#6667 A myrecord.com
867

868
``online-sign`` — Online DNSSEC signing
869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897
---------------------------------------

The module provides online DNSSEC signing. Instead of pre-computing the zone
signatures when the zone is loaded into the server or instead of loading an
externally signed zone, the signatures are computed on-the-fly during
answering.

The main purpose of the module is to enable authenticated responses with
zones which use other dynamic module (e.g., automatic reverse record
synthesis) because these zones cannot be pre-signed. However, it can be also
used as a simple signing solution for zones with low traffic and also as
a protection against zone content enumeration (zone walking).

In order to minimize the number of computed signatures per query, the module
produces a bit different responses from the responses that would be sent if
the zone was pre-signed. Still, the responses should be perfectly valid for
a DNSSEC validating resolver.

Differences from statically signed zones:

* The NSEC records are constructed as Minimally Covering NSEC Records
  (see Appendix A in :rfc:`7129`). Therefore the generated domain names cover
  the complete domain name space in the zone's authority.

* NXDOMAIN responses are promoted to NODATA responses. The module proves
  that the query type does not exist rather than that the domain name does not
  exist.

* Domain names matching a wildcard are expanded. The module pretends and proves
898
  that the domain name exists rather than proving a presence of the wildcard.
899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982

Records synthesized by the module:

* DNSKEY record is synthesized in the zone apex and includes public key
  material for the active signing key.

* NSEC records are synthesized as needed.

* RRSIG records are synthesized for authoritative content of the zone.

How to use the online signing module:

* First add the zone into the server's KASP database and generate a key to be
  used for signing:

  .. code-block:: console

   $ cd /path/to/kasp
   $ keymgr zone add example.com
   $ keymgr zone key generate example.com algorithm ecdsap256sha256 size 256

* Enable the module in server configuration and hook it to the zone::

   mod-online-sign:
     - id: default

   zone:
     - domain: example.com
       module: mod-online-sign/default
       dnssec-signing: false

* Make sure the zone is not signed and also that the automatic signing is
  disabled. All is set, you are good to go. Reload (or start) the server:

  .. code-block:: console

   $ knotc reload

The following example stacks the online signing with reverse record synthesis
module::

 mod-online-sign:
   - id: default

 mod-synth-record:
   - id: lan-forward
     type: forward
     prefix: ip-
     ttl: 1200
     network: 192.168.100.0/24

 template:
   - id: default
     dnssec-signing: false

 zone:
   - domain: corp.example.net
     module: mod-synth-record/lan-forward
     module: mod-online-sign/default

Known issues:

* The delegations are not signed correctly.

* Some CNAME records are not signed correctly.

Limitations:

* Only a Single-Type Signing scheme is supported.

* Only one active signing key can be used.

* Key rollover is not possible.

* The NSEC records may differ for one domain name if queried for different
  types. This is an implementation shortcoming as the dynamic modules
  cooperate loosely. Possible synthesis of a type by other module cannot
  be predicted. This dissimilarity should not affect response validation,
  even with validators performing `aggressive negative caching
  <https://datatracker.ietf.org/doc/draft-fujiwara-dnsop-nsec-aggressiveuse/>`_.

* The NSEC proofs will work well with other dynamic modules only if the
  modules synthesize only A and AAAA records. If synthesis of other type
  is required, please, report this information to Knot DNS developers.