Configuration
Simple configuration
The following example presents a simple configuration file which can be used as a base for your Knot DNS setup:
# Example of a very simple Knot DNS configuration.
server:
listen: 0.0.0.0@53
listen: ::@53
zone:
- domain: example.com
storage: /var/lib/knot/zones/
file: example.com.zone
log:
- target: syslog
any: info
Now let’s walk through this configuration step by step:
The listen statement in the server section defines where the server will listen for incoming connections. We have defined the server to listen on all available IPv4 and IPv6 addresses, all on port 53.
The zone section defines the zones that the server will serve. In this case, we defined one zone named example.com which is stored in the zone file /var/lib/knot/zones/example.com.zone.
The log section defines the log facilities for the server. In this example, we told Knot DNS to send its log messages with the severity info or more serious to the syslog (or systemd journal).
For detailed description of all configuration items see Configuration Reference.
Zone templates
A zone template allows a single zone configuration to be shared among several zones. There is no inheritance between templates; they are exclusive. The 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
dnssec-signing: on
semantic-checks: on
master: [master1, master2]
- 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
master: master3 # Override masters to just master3
- domain: example1.eu
template: slave
master: master1
- domain: example2.eu
template: slave
master: master2
Note
Each template option can be explicitly overridden in zone-specific configuration.
Access control list (ACL)
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 keymgr on how to generate a TSIG key).
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.
If there are multiple ACL rules for a single zone, they are applied in the order of appearance in the acl configuration item of a zone or a template. The first one to match the given remote is applied, the rest is ignored.
For dynamic updates, additional rules may be specified, which will allow or deny updates according to the type or owner of Resource Records in the update.
See the following examples and ACL section.
acl:
- id: address_rule
address: [2001:db8::1, 192.168.2.0/24]
action: transfer
- id: deny_rule
address: 192.168.2.100
action: transfer
deny: on
zone:
- domain: acl1.example.com.
acl: [deny_rule, address_rule] # deny_rule first here to take precendence
key:
- id: key1 # The real TSIG key name
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
- id: key_rule
key: key1 # Access based just on TSIG key
action: [transfer, notify]
zone:
- domain: acl2.example.com
acl: [deny_all, key_rule]
acl:
- id: owner_type_rule
action: update
update-type: [A, AAAA, MX] # Updates are only allowed to update records of the specified types
update-owner: name # The allowed owners are specified by the list on the next line
update-owner-name: [a, b.example.com.] # Non-FQDN names are relative to the effective zone name
update-owner-match: equal # The owners of records in an update must be exactly equal to the names in the list
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.
Tip
In order to restrict regular DNS queries, use module queryacl.
Secondary (slave) zone
Knot DNS doesn’t strictly differ between primary (formerly known as master) and secondary (formerly known as slave) zones. The only requirement for a secondary zone is to have a master statement set. Also note that you need to explicitly allow incoming zone changed notifications via notify action through a zone’s acl list, otherwise the update will be rejected by the server. If the zone file doesn’t exist it will be bootstrapped over AXFR:
remote:
- id: master
address: 192.168.1.1@53
# via: 10.0.0.1 # Specify local source address if needed
acl:
- id: notify_from_master
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: notify_from_master
Note that the master option accepts a list of multiple remotes. 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.
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 the remote and ACL definitions are independent:
key:
- id: slave1_key
algorithm: hmac-md5
secret: Wg==
remote:
- id: master
address: 192.168.1.1@53
key: slave1_key
acl:
- id: notify_from_master
address: 192.168.1.1
key: slave1_key
action: notify
Note
When transferring a lot of zones, the server may easily get into a state where all available ports are in the TIME_WAIT state, thus transfers cease 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
Primary (master) zone
An ACL with the transfer action must be configured to allow outgoing zone transfers. An ACL rule consists of a single address or a network subnet:
remote:
- id: slave1
address: 192.168.2.1@53
acl:
- 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
notify: slave1
acl: [slave1_acl, others_acl]
Optionally, a TSIG key can be specified:
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
action: transfer
- id: others_acl
address: 192.168.3.0/24
action: transfer
Note that a secondary zone may serve as a primary 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]
Dynamic updates
Dynamic updates for the zone are allowed via proper ACL rule with the update action. If the zone is configured as a secondary and a DNS update message is accepted, the server forwards the message to its primary master. The primary master’s response is then forwarded back to the originator.
However, if the zone is configured as a primary, the update is accepted and processed:
acl:
- id: update_acl
address: 192.168.3.0/24
action: update
zone:
- domain: example.com
file: example.com.zone
acl: update_acl
Automatic DNSSEC signing
Knot DNS supports automatic DNSSEC signing of zones. The signing can operate in two modes:
Automatic key management. In this mode, the server maintains signing keys. New keys are generated according to assigned policy and are rolled automatically in a safe manner. No zone operator intervention is necessary.
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 and timing parameters must be assigned by the zone operator.
The DNSSEC signing process maintains some metadata which is stored in the KASP database. This database is backed by LMDB.
Warning
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. If no HSM is used, the database also contains private key material – don’t set the permissions too weak.
Automatic ZSK management
For automatic ZSK management a signing policy 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.
A minimal zone configuration may look as follows:
zone:
- domain: myzone.test
dnssec-signing: on
With a custom signing policy, the policy section will be added:
policy:
- id: custom_policy
signing-threads: 4
algorithm: ECDSAP256SHA256
zsk-lifetime: 60d
zone:
- domain: myzone.test
dnssec-signing: on
dnssec-policy: custom_policy
After configuring the server, reload the changes:
The server will generate initial signing keys and sign the zone properly. Check the server logs to see whether everything went well.
Automatic KSK management
For automatic KSK management, first configure ZSK management like above, and use additional options in policy section, mostly specifying desired (finite) lifetime for KSK:
remote:
- id: parent_zone_server
address: 192.168.12.1@53
submission:
- id: parent_zone_sbm
parent: [parent_zone_server]
policy:
- id: custom_policy
signing-threads: 4
algorithm: ECDSAP256SHA256
zsk-lifetime: 60d
ksk-lifetime: 365d
ksk-submission: parent_zone_sbm
zone:
- domain: myzone.test
dnssec-signing: on
dnssec-policy: custom_policy
After the initially-generated KSK reaches its lifetime, new KSK is published and after convenience delay the submission is started. The server publishes CDS and CDNSKEY records and the user shall propagate them to the parent. The server periodically checks for DS at the parent zone and when positive, finishes the rollover.
Manual key management
For automatic DNSSEC signing with manual key management, a signing policy with manual key management flag has to be set:
policy:
- id: manual
manual: on
zone:
- domain: myzone.test
dnssec-signing: on
dnssec-policy: manual
To generate signing keys, use the keymgr utility. For example, we can use Single-Type Signing:
$ keymgr myzone.test. generate algorithm=ECDSAP256SHA256 ksk=yes zsk=yes
And reload the server. The zone will be signed.
To perform a manual rollover of a key, the timing parameters of the key need to be set. Let’s roll the key. Generate a new key, but do not activate it yet:
$ keymgr myzone.test. generate algorithm=ECDSAP256SHA256 ksk=yes zsk=yes active=+1d
Take the key ID (or key tag) of the old key and disable it the same time the new key gets activated:
$ keymgr myzone.test. set <old_key_id> retire=+2d remove=+3d
Reload the server again. The new key will be published (i.e. the DNSKEY record will be added into the zone). Remember to update the DS record in the parent zone to include a reference to the new key. This must happen within one day (in this case) including a delay required to propagate the new DS to caches.
Warning
If you ever decide to switch from manual key management to automatic key management, note that the automatic key management uses zsk-lifetime and ksk-lifetime policy configuration options to schedule key rollovers and it internally uses timestamps of keys differently than in the manual case. As a consequence it might break if the retire or remove timestamps are set for the manually generated keys currently in use. Make sure to set these timestamps to zero using keymgr:
$ keymgr myzone.test. set <key_id> retire=0 remove=0
and configure your policy suitably according to Automatic ZSK management and Automatic KSK management.
Zone signing
The signing process consists of the following steps:
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).
Fixing the NSEC or NSEC3 chain.
Removing expired signatures, invalid signatures, signatures expiring in a short time, and signatures issued by an unknown key.
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 re-signing SOA record.
The signing is initiated on the following occasions:
Start of the server
Zone reload
Reaching the signature refresh period
Key set changed due to rollover event
Received DDNS update
Forced zone re-sign via server control interface
On a forced zone re-sign, all signatures in the zone are dropped and recreated.
The knotc zone-status command can be used to see when the next scheduled DNSSEC re-sign will happen.
On-secondary (on-slave) signing
It is possible to enable automatic DNSSEC zone signing even on a secondary server. If enabled, the zone is signed after every AXFR/IXFR transfer from primary, so that the secondary always serves a signed up-to-date version of the zone.
It is strongly recommended to block any outside access to the primary server, so that only the secondary server’s signed version of the zone is served.
Enabled on-secondary signing introduces events when the secondary zone changes while the primary zone remains unchanged, such as a key rollover or refreshing of RRSIG records, which cause inequality of zone SOA serial between primary and secondary. The secondary server handles this by saving the primary’s SOA serial in a special variable inside KASP DB and appropriately modifying AXFR/IXFR queries/answers to keep the communication with primary server consistent while applying the changes with a different serial.
Catalog zones
Catalog zones are a concept whereby a list of zones to be configured is maintained as contents of a separate, special zone. This approach has the benefit of simple propagation of a zone list to secondary servers, especially when the list is frequently updated. Currently, catalog zones are described in this Internet Draft.
Terminology first. Catalog zone is a meta-zone which shall not be a part of the DNS tree, but it contains information about the set of member zones and is transferable to secondary servers using common AXFR/IXFR techniques. Catalog-member zone (or just member zone) is a zone based on information from the catalog zone and not from configuration file/database.
A catalog zone is handled almost in the same way as a regular zone: It can be configured using all the standard options (but for example DNSSEC signing would be useless), including primary/secondary configuration and ACLs. A catalog zone is indicated by setting the option catalog-role. The difference is that standard DNS queries to a catalog zone are answered with REFUSED as though the zone doesn’t exist, unless querying over TCP from an address with transfers enabled by ACL. The name of the catalog zone is arbitrary. It’s required to include version record version 0 IN TXT "2", however. It’s possible to configure multiple catalog zones.
Warning
Don’t choose a name for a catalog zone below a name of any other existing zones configured on the server as it would effectively “shadow” part of your DNS subtree.
Upon catalog zone (re)load or change, all the PTR records in the zone sub-tree zones (e.g. unique-id1.zones.catalog. 0 IN PTR member.com.) are processed and member zones created, with zone names taken from the PTR records’ RData, and zone settings taken from the configuration template specified by catalog-template. Owner names of those PTR records may be arbitrary, but when a member zone is de-cataloged and re-cataloged again, the owner name of the relevant PTR record must be changed. It’s also recommended that all the PTR records have different owner names (in other words, catalog zone RRSets consist of one RR each) to prevent oversized RRSets (not AXFR-able) and to achieve interoperability.
All records other than PTR are ignored. They remain in the catalog zone, however, and might be for example transferred to a secondary server, which may interpret catalog zones differently. SOA still needs to be present in the catalog zone and its serial handled appropriately. An apex NS record should be present for the sake of interoperability.
A catalog zone may be modified using any standard means (e.g. AXFR/IXFR, DDNS, zone file reload). In the case of incremental change, only affected member zones are reloaded.
Any de-cataloged member zone is purged immediately, including its zone file, journal, timers, and DNSSEC keys. The zone file is not deleted if zonefile-sync is set to -1 for member zones.
When setting up catalog zones, it might be useful to set catalog-db and catalog-db-max-size to non-default values.
Warning
Bugs, limitations:
Knot does purge the member zone’s metadata whenever the respective PTR record owner changes in any way. This differs from the specification (see Internet Draft above), which requires this to be done only when the “unique” label (i.e. the one immediately left of the zones label) changes. It’s expected that Knot’s behaviour will be aligned to the specification in the future.
Knot does not work well if one member zone appears in two catalog zones concurrently. The user is encouraged to avoid this situation whatsoever. Thus, there is no way a member zone can be migrated from one catalog to another while preserving its metadata. Following steps may be used as a workaround:
Back up the member zone’s metadata (on each server separately).
Remove the member zone from the catalog it’s a member of.
Wait for the catalog zone to be propagated to all servers.
Add the member zone to the other catalog.
Restore the backed up metadata (on each server separately).
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.
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 to the zone/template module option or to the default 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 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-cookies, mod-rrl, mod-dnstap, mod-stats
