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:
For detailed description of all configuration items see Configuration Reference.
A zone template allows a single zone configuration to be shared among several zones. 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.
An ACL list specifies which remotes are allowed to send the server a specific request. A remote can be a single IP address or a network subnet. Also a TSIG key can be assigned (see keymgr how to generate a TSIG key):
key:
- id: key1
algorithm: hmac-md5
secret: Wg==
acl:
- id: address_rule
address: [2001:db8::1, 192.168.2.0/24] # Allowed IP address list
action: [transfer, update] # Allow zone transfers and updates
- id: deny_rule # Negative match rule
address: 192.168.2.100
action: transfer
deny: on # The request is denied
- id: key_rule
key: key1 # Access based just on TSIG key
action: transfer
These rules can then be referenced from a zone acl:
zone:
- domain: example.com
acl: [address_rule, deny_rule, key_rule]
Knot DNS doesn't strictly differ between master and slave zones. The only requirement is to have a master statement set for the given zone. Also note that you need to explicitly allow incoming zone changed notifications via notify action through 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
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 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:
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
Dynamic updates for the zone are allowed via proper ACL rule with the update action. If the zone is configured as a slave and a DNS update message is accepted, the server forwards the message to its primary master. The master's response is then forwarded back to the originator.
However, if the zone is configured as a master, 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
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, 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 rate-limit option in the server section. The option controls how many responses per second are permitted for each flow. Responses exceeding this rate are limited. The option rate-limit-slip then configures how many limited responses are sent as truncated (slip) instead of being dropped.
server:
rate-limit: 200 # Allow 200 resp/s for each flow
rate-limit-slip: 2 # Every other response slips
Knot DNS supports automatic DNSSEC signing for static zones. The signing can operate in two modes:
The DNSSEC signing process maintains some metadata which is stored in the KASP database. This database is simply a directory in the file-system containing files in the JSON format.
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 week.
For automatic key 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.). The policy can be configured in the policy section, or a default policy with the default parameters can be used.
A minimal zone configuration may look as follows:
zone:
- domain: myzone.test
dnssec-signing: on
dnssec-policy: default
With custom signing policy, the policy section will be added:
policy:
- id: rsa
algorithm: RSASHA256
ksk-size: 2048
zsk-size: 1024
zone:
- domain: myzone.test
dnssec-signing: on
dnssec-policy: rsa
After configuring the server, reload the changes:
$ knotc reload
The server will generate initial signing keys and sign the zone properly. Check the server logs to see whether everything went well.
Warning
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 enabling the automatic signing. Also the algorithm in the policy must match the algorithm of all imported keys. Otherwise the zone will be resigned at all.
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. Let's use the Single-Type Signing scheme with two algorithms, which is a scheme currently not supported by the automatic key management. Run:
$ keymgr zone key generate myzone.test algorithm RSASHA256 size 1024
$ keymgr zone key generate myzone.test algorithm ECDSAP256SHA256 size 256
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 RSA key. Generate a new RSA key, but do not activate it yet:
$ keymgr zone key generate myzone.test algorithm RSASHA256 size 1024 active +1d
Take the key ID (or key tag) of the old RSA key and disable it the same time the new key gets activated:
$ keymgr zone key set myzone.test <old_key_id> retire +1d remove +1d
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.
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.
The signing process consists of the following steps:
The signing is initiated on the following occasions:
On a forced zone resign, all signatures in the zone are dropped and recreated.
The knotc zone-status command can be used to see when the next scheduled DNSSEC resign will happen.
The current DNSSEC implementation in Knot DNS has some limitations. Most of the limitations will be hopefully removed in the near future.