configuration.rst 25.5 KB
Newer Older
1
.. highlight:: yaml
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 124 125 126 127 128 129 130 131 132 133 134

    remote:
      - id: master
        address: 192.168.1.1@53

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

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

135
Note that the :ref:`zone_master` option accepts a list of multiple remotes.
136 137 138 139
The first remote in the list is used as the primary master, and the rest is used
for failover if the connection with the primary master fails.
The list is rotated in this case, and a new primary is elected.
The preference list is reset on the configuration reload.
140

141 142 143
To use TSIG for transfer authentication, configure a TSIG key and assign the
key to the remote. If the notifications are used, the same key should be
configured in a proper ACL rule::
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163

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

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

    acl:
      - id: master_acl
        address: 192.168.1.1
        key: slave1_key
        action: notify

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

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

    remote:
      - id: slave1
        address: 192.168.2.1@53

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

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

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

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

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

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

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

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

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

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

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

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

Response rate limiting (RRL) is a method to combat recent DNS
234
reflection amplification attacks. These attacks rely on the fact
235 236 237 238 239 240
that source address of a UDP query could be forged, and without a
worldwide deployment of BCP38, such a forgery could not be detected.
Attacker could then exploit DNS server responding to every query,
potentially flooding the victim with a large unsolicited DNS
responses.

241 242 243 244
You can enable RRL with the :ref:`server_rate-limit` option in the
:ref:`server section<Server section>`. Setting to a value greater than ``0``
means that every flow is allowed N responses per second, (i.e. ``rate-limit
50;`` means ``50`` responses per second). It is also possible to
245 246
configure :ref:`server_rate-limit-slip` interval, which causes every N\ :sup:`th`
blocked response to be slipped as a truncated response::
247 248 249 250

    server:
        rate-limit: 200     # Each flow is allowed to 200 resp. per second
        rate-limit-slip: 1  # Every response is slipped
251

252 253
.. _dnssec:

254 255 256
Automatic DNSSEC signing
========================

257 258 259 260 261 262 263 264 265 266
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>`.
267
   In this mode, the server also maintains signing keys. New keys are generated
268 269 270
   according to assigned policy and are rolled automatically in a safe manner.
   No zone operator intervention is necessary.

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

.. _dnssec-example:

278 279 280
Example configuration
---------------------

281 282 283
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::
284

285 286
    template:
      - id: default
287
        dnssec-signing: on
288
        kasp-db: /var/lib/knot/kasp
289

290 291 292
    zone:
      - domain: example.com
        file: example.com.zone
293

294 295
      - domain: example.dev
        file: example.dev.zone
296
        dnssec-signing: off
297

298 299 300 301 302 303
.. _dnssec-kasp:

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

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

307 308 309
- definitions of signing policies;
- zones configuration; and
- private key material.
310 311

The :doc:`keymgr <man_keymgr>` utility serves for the database maintenance.
312 313 314
To initialize the database, run:

.. code-block:: console
315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330

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

.. ATTENTION::
  Make sure to set the KASP database permissions correctly. For manual key
  management, the database must be **readable** by the server process. For
  automatic key management, it must be **writeable**. The database also
  contains private key material -- don't set the permissions too loose.

.. _dnssec-automatic-key-management:

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

331
For automatic key management, a signing policy has to be defined in the
332
first place. This policy specifies how a zone is signed (i.e. signing
333
algorithm, key size, signature lifetime, key lifetime, etc.).
334 335

To create a new policy named *default_rsa* using *RSA-SHA-256* algorithm for
336 337 338
signing keys, 1024-bit long ZSK, and 2048-bit long KSK, run:

.. code-block:: console
339 340 341 342 343 344 345

  $ keymgr policy add default_rsa algorithm RSASHA256 zsk-size 1024 ksk-size 2048

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
346 347 348
created policy:

.. code-block:: console
349 350 351

  $ keymgr zone add myzone.test policy default_rsa

352 353 354
Make sure everything is set correctly:

.. code-block:: console
355 356 357 358 359 360 361 362 363

  $ keymgr policy show default_rsa
  $ 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
364
      storage: /var/lib/knot
365
      kasp-db: kasp
366 367 368

  zone:
    - domain: myzone.test
369
      dnssec-signing: on
370

371 372 373
Finally, reload the server:

.. code-block:: console
374

375
  $ knotc reload
376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394

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
need not be defined.

395 396 397
Create a zone entry for the zone *myzone.test* without a policy:

.. code-block:: console
398 399

  $ keymgr zone add myzone.test
400

401
Generate signing keys for the zone. Let's use the Single-Type Signing scheme
402
with two algorithms (this scheme is not supported in automatic key management).
403 404 405
Run:

.. code-block:: console
406

407 408
  $ keymgr zone key generate myzone.test algorithm RSASHA256 size 1024
  $ keymgr zone key generate myzone.test algorithm ECDSAP256SHA256 size 256
409

410 411 412
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`.
413

414 415
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
416 417 418
it yet:

.. code-block:: console
419 420 421 422

  $ 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
423 424 425
the new key gets activated:

.. code-block:: console
426 427 428 429 430 431 432 433 434 435 436 437 438 439 440

  $ 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:
441 442 443 444

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

445 446 447 448 449 450 451 452 453 454 455 456 457 458 459
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
  *RSA-SHA-256*.

:abbr:`KSK (Key Signing Key)` size
  Desired length of the newly generated ZSK keys. The default value is 2048
  bits.

:abbr:`ZSK (Zone Signing Key)` size
  Desired length of the newly generated ZSK keys. The default value is 1024
  bits.
460

461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496
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
  Interval after which the ZSK rollover will be initiated. The default value
  is 30 days.

RRSIG lifetime
  Lifetime of newly issued signatures. The default value is 14 days.

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.

.. _dnssec-signing:
497 498 499 500 501 502

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

The signing process consists of the following steps:

503 504 505 506 507 508 509
#. 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
510
   in a short time, and signatures issued by an unknown key.
511 512 513 514 515 516 517
#. 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:

518 519 520 521 522
- Start of the server
- Zone reload
- Reaching the signature refresh period
- Received DDNS update
- Forced zone resign issued with ``knotc signzone``
523

524
On a forced zone resign, all signatures in the zone are dropped and recreated.
525 526 527 528 529 530 531 532 533 534

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
535
of the limitations will be hopefully removed in the near future.
536 537 538

- Automatic key management:

539
  - Only one DNSSEC algorithm can be used per zone.
540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565
  - 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:

566
  - Legacy key import requires a private key.
567 568
  - Legacy key export is not implemented.
  - DS record export is not implemented.
569 570 571 572 573

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

Knot DNS supports configurable query modules that can alter the way
574
queries are processed. The concept is quite simple -- each query
575
requires a finite number of steps to be resolved. We call this set of
576
steps a *query plan*, an abstraction that groups these steps into
577 578
several stages.

579
* Before-query processing
580
* Answer, Authority, Additional records packet sections processing
581
* After-query processing
582

583
For example, processing an Internet-zone query needs to find an
584
answer. Then based on the previous state, it may also append an
585
authority SOA or provide additional records. Each of these actions
586 587 588
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.
589

590
Each module is configured in the corresponding module section and is
591
identified for the subsequent usage. Then the identifier is referenced
592
through :ref:`zone_module` option (in the form of ``module_name/module_id``)
593
in the zone section or in the ``default`` template if it used for all queries.
594

595
``dnstap`` -- dnstap-enabled query logging
596 597
-----------------------------------------

598 599 600 601
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
602
a UNIX socket::
603

604 605 606
    mod-dnstap:
      - id: capture_all
        sink: /tmp/capture.tap
607

608 609 610
    template:
      - id: default
        module: mod-dnstap/capture_all
611 612 613

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

614
``synth-record`` -- Automatic forward/reverse records
615 616
----------------------------------------------------

617
This module is able to synthesize either forward or reverse records for
618
a given prefix and subnet.
619

620
Records are synthesized only if the query can't be satisfied from the zone.
621
Both IPv4 and IPv6 are supported.
622

623
*Note: Long names are snipped for readability.*
624

625 626
Automatic forward records
-------------------------
627

628 629 630 631 632 633 634
Example::

   mod-synth-record:
     - id: test1
       type: forward
       prefix: dynamic-
       ttl: 400
635
       network: 2620:0:b61::/52
636 637 638 639 640 641

   zone:
     - domain: example.
       file: example.zone # Zone file have to exist!
       module: mod-synth-record/test1

642 643 644
Result:

.. code-block:: console
645

646 647 648 649
   $ kdig AAAA dynamic-2620-0000-0b61-0100-0000-0000-0000-0000.example.
   ...
   ;; QUESTION SECTION:
   ;; dynamic-2620-0000-0b61-0100-0000-0000-0000-0000.example. 0	IN	AAAA
650

651 652
   ;; ANSWER SECTION:
   dynamic-2620-0000-0b61-0100... 400 IN AAAA 2620:0:b61:100::
653

654
You can also have CNAME aliases to the dynamic records, which are going to be
655
further resolved:
656 657

.. code-block:: console
658

659 660 661 662
   $ kdig AAAA hostalias.example.
   ...
   ;; QUESTION SECTION:
   ;hostalias.example. 0	IN	AAAA
663

664 665 666
   ;; ANSWER SECTION:
   hostalias.example. 3600 IN CNAME dynamic-2620-0000-0b61-0100...
   dynamic-2620-0000-0b61-0100... 400  IN AAAA  2620:0:b61:100::
667 668 669

Automatic reverse records
-------------------------
670

671 672 673 674 675 676
Example::

   mod-synth-record:
     - id: test2
       type: reverse
       prefix: dynamic-
677
       origin: example
678
       ttl: 400
679
       network: 2620:0:b61::/52
680 681 682 683 684 685

   zone:
     - domain: 1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.
       file: 1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.zone # Zone file have to exist!
       module: mod-synth-record/test2

686 687 688
Result:

.. code-block:: console
689 690 691 692 693 694 695 696

   $ kdig PTR 1.0.0...1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.
   ...
   ;; QUESTION SECTION:
   ;; 1.0.0...1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. 0	IN	PTR

   ;; ANSWER SECTION:
   ... 400 IN PTR dynamic-2620-0000-0b61-0000-0000-0000-0000-0001.example.
697

698 699
Limitations
^^^^^^^^^^^
700

701
* As of now, there is no authenticated denial of nonexistence (neither
702
  NSEC or NSEC3 is supported) nor DNSSEC signed records. However,
703 704
  since the module is hooked in the query processing plan, it will be
  possible to do online signing in the future.
705

706
``dnsproxy`` -- Tiny DNS proxy
707 708
-----------------------------

709
The module catches all unsatisfied queries and forwards them to the
710 711
indicated server for resolution, i.e. a tiny DNS proxy. There are several 
uses of this feature:
712 713 714 715 716

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

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

720 721
The configuration is straightforward and just a single IP address
(either IPv4 or IPv6) is required::
722

723 724 725
   mod-dnsproxy:
     - id: default
       remote: 10.0.1.1
726

727 728 729
   template:
     - id: default
       module: mod-dnsproxy/default
730

731 732
   zone:
     - domain: local.zone
733

734 735 736
When clients query for anything in the ``local.zone``, they will be
responded to locally. The rest of the requests will be forwarded to the 
specified server (``10.0.1.1`` in this case).
737

738
``rosedb`` -- Static resource records
739
------------------------------------
740

741
The module provides a mean to override responses for certain queries before
742 743
the record is searched in the available zones. The module comes with the 
``rosedb_tool`` tool used to manipulate the database of static records.
744
Neither the tool nor the module are enabled by default, recompile with
745
the ``--enable-rosedb`` configuration flag to enable them.
746

747
For example, let's suppose we have a database of following records:
748 749

.. code-block:: none
750

751 752 753
   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
754

755
And we query the nameserver with the following:
756 757

.. code-block:: console
758

759 760 761 762 763 764 765 766 767 768 769
   $ 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

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

774 775
You can also add authority information for the entries, provided you create
SOA + NS records for a name, like so:
776 777

.. code-block:: none
778

779 780 781 782 783
   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
784 785 786 787 788

In this case, the responses will:

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

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

798
In addition, the module is able to log matching queries via remote syslog if
799
you specify a syslog address endpoint and an optional string code.
800 801 802

Here is an example on how to use the module:

803 804 805
* Create the entries in the database:

  .. code-block:: console
806

807
   $ mkdir /tmp/static_rrdb
808 809 810 811 812 813
   $ rosedb_tool /tmp/static_rrdb add myrecord.com. A 3600 "127.0.0.1" "-" "-" 
       # No logging
   $ rosedb_tool /tmp/static_rrdb add www.myrecord.com. A 3600 "127.0.0.1" \
       "www_query" "10.0.0.1" # Syslog @ 10.0.0.1
   $ rosedb_tool /tmp/static_rrdb add ipv6.myrecord.com. AAAA 3600 "::1" \
       "ipv6_query" "10.0.0.1" # Syslog @ 10.0.0.1
814 815 816 817
   $ rosedb_tool /tmp/static_rrdb list # Verify
   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     -               -
818

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

821 822 823 824 825 826 827 828 829
* Configure the query module::

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

   template:
     - id: default
       module: mod-rosedb/default
830

831
  *Note: The module accepts just one parameter -- the path to the directory where
832
  the database will be stored.*
833

834 835 836
* Start the server:

  .. code-block:: console
837

838
   $ knotd -c knot.conf
839

840 841 842
* Verify the running instance:

  .. code-block:: console
843

844
   $ kdig @127.0.0.1#6667 A myrecord.com