Access control list (ACL)
Some types of incoming DNS requests must be authorized before they can be
processed by the server. A zone can have configured acl which is
a sequence of rules describing what requests are authorized.
By default if automatic ACL is not enabled, all requests,
which require authorization, are denied.
Every ACL rule can allow or deny one or more request types based on the
source IP address, network subnet, or address range and/or if the request is
secured by a given TSIG key. See keymgr -t on how
to generate a TSIG key.
If there are multiple ACL rules assigned to a zone, they are applied in the
specified order of the acl configuration. The first rule that matches
the given request is applied and the remaining rules are ignored. Some examples:
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] # Allow some addresses with an exception
key:
- id: key1 # The real TSIG key name
algorithm: hmac-sha256
secret: 4Tc0K1QkcMCs7cOW2LuSWnxQY0qysdvsZlSb4yTN9pA=
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] # Allow with the TSIG except for the subnet
In the case of dynamic DNS updates, some additional conditions may be specified
for more granular filtering. See more in the section Restricting dynamic updates.
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. For effective zone synchronization,
incoming zone change notifications (NOTIFY), which require authorization, can be
enabled using automatic ACL or explicit ACL
configuration. Optional transaction authentication (TSIG) is supported for both
zone transfers and zone notifications:
server:
automatic-acl: on # Enabled automatic ACL
key:
- id: xfr_notify_key # Common TSIG key for XFR an NOTIFY
algorithm: hmac-sha256
secret: VFRejzw8h4M7mb0xZKRFiZAfhhd1eDGybjqHr2FV3vc=
remote:
- id: primary
address: [2001:DB8:1::1, 192.168.1.1] # Primary server IP addresses
# via: [2001:DB8:2::1, 10.0.0.1] # Local source addresses (optional)
key: xfr_notify_key # TSIG key (optional)
zone:
- domain: example.com
master: primary # Primary remote(s)
An example of explicit ACL with different TSIG keys for zone transfers
and notifications:
key:
- id: notify_key # TSIG key for NOTIFY
algorithm: hmac-sha256
secret: uBbhV4aeSS4fPd+wF2ZIn5pxOMF35xEtdq2ibi2hHEQ=
- id: xfr_key # TSIG key for XFR
algorithm: hmac-sha256
secret: VFRejzw8h4M7mb0xZKRFiZAfhhd1eDGybjqHr2FV3vc=
remote:
- id: primary
address: [2001:DB8:1::1, 192.168.1.1] # Primary server IP addresses
# via: [2001:DB8:2::1, 10.0.0.1] # Local source addresses if needed
key: xfr_key # Optional TSIG key
acl:
- id: notify_from_primary # ACL rule for NOTIFY from primary
address: [2001:DB8:1::1, 192.168.1.1] # Primary addresses (optional)
key: notify_key # TSIG key (optional)
action: notify
zone:
- domain: example.com
master: primary # Primary remote(s)
acl: notify_from_primary # Explicit ACL(s)
Note that the master option accepts a list of remotes, which are
queried for a zone refresh sequentially in the specified order. When the server
receives a zone change notification from a listed remote, only that remote is
used for a subsequent zone transfer.
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
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.
A catalog-member zone (or just member zone) is a zone based on
information from the catalog zone and not from configuration file/database.
Member properties are some additional information related to each member zone,
also distributed with the catalog zone.
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 is useless as the zone won't be queried by clients), 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 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 format
unique-id.zones.catalog. 0 IN PTR member.com. (but not too.deep.zones.catalog.!)
are processed and member zones created, with zone names taken from the
PTR records' RData, and zone settings taken from the configuration
templates specified by catalog-template.
The owner names of the PTR records shall follow this scheme:
<unique-id>.zones.<catalog-zone>.
where the mentioned labels shall match:
Additionally, records in the format
group.unique-id.zones.catalog. 0 IN TXT "conf-template"
are processed as a definition of the member's group property. The
unique-id must match the one of the PTR record defining the member.
All other records and other member properties 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 must be
present as for any other zone. The version record version 0 IN TXT "2"
is required at the catalog zone apex.
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.
The catalog zone must have at least one catalog-template
configured. The configuration for any defined member zone is taken from its
group property value, which should match some catalog-template name.
If the group property is not defined for a member, is empty, or doesn't match
any of defined catalog-template names, the first catalog-template
(in the order from configuration) is used. Nesting of catalog zones isn't
supported.
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.
Any member zone, whose PTR record's owner has been changed, is purged
immediately if and only if the <unique-id> has been changed.
When setting up catalog zones, it might be useful to set
catalog-db and catalog-db-max-size
to non-default values.
Note
Whenever a catalog zone is updated, the server reloads itself with
all configured zones, including possibly existing other catalog zones.
It's similar to calling knotc zone-reload (for all zones).
The consequence is that new zone files might be discovered and reloaded,
even for zones that do not relate to updated catalog zone.
Catalog zones never expire automatically, regardless of what is declared
in the catalog zone SOA. However, a catalog zone can be expired manually
at any time using knotc -f zone-purge +expire.
Currently, expiration of a catalog zone doesn't have any effect on its
member zones. This will likely change in the future depending on the
Internet Draft.
Warning
The server 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).
Catalog zones configuration examples
Below are configuration snippets (e.g. server and log sections missing)
of very simple catalog zone setups, in order to illustrate the relations
between catalog-related configuration options.
First setup represents a very simple scenario where the primary is
the catalog zone generator and the secondary is the catalog zone consumer.
Primary configuration:
acl:
- id: slave_xfr
address: ...
action: transfer
template:
- id: mmemb
catalog-role: member
catalog-zone: catz.
acl: slave_xfr
zone:
- domain: catz.
catalog-role: generate
acl: slave_xfr
- domain: foo.com.
template: mmemb
- domain: bar.com.
template: mmemb
Secondary configuration:
acl:
- id: master_notify
address: ...
action: notify
template:
- id: smemb
master: master
acl: master_notify
zone:
- domain: catz.
master: master
acl: master_notify
catalog-role: interpret
catalog-template: smemb
When new zones are added (or removed) to the primary configuration with assigned
mmemb template, they will automatically propagate to the secondary
and have the smemb template assigned there.
Second example is with a hand-written (or script-generated) catalog zone,
while employing configuration groups:
catz. 0 SOA invalid. invalid. 1625079950 3600 600 2147483646 0
catz. 0 NS invalid.
version.catz. 0 TXT "2"
nj2xg5bnmz2w4ltd.zones.catz. 0 PTR just-fun.com.
group.nj2xg5bnmz2w4ltd.zones.catz. 0 TXT unsigned
nvxxezjnmz2w4ltd.zones.catz. 0 PTR more-fun.com.
group.nvxxezjnmz2w4ltd.zones.catz. 0 TXT unsigned
nfwxa33sorqw45bo.zones.catz. 0 PTR important.com.
group.nfwxa33sorqw45bo.zones.catz. 0 TXT signed
mjqw42zomnxw2lq0.zones.catz. 0 PTR bank.com.
group.mjqw42zomnxw2lq0.zones.catz. 0 TXT signed
And the server in this case is configured to distinguish the groups by applying
different templates:
template:
- id: unsigned
...
- id: signed
dnssec-signing: on
dnssec-policy: ...
...
zone:
- domain: catz.
file: ...
catalog-role: interpret
catalog-template: [ unsigned, signed ]
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
