Migration

Upgrade 2.4.x to 2.5.x

This chapter describes some steps necessary after upgrading Knot DNS from version 2.4.x to 2.5.x.

Building changes

The --enable-dnstap configure option now enables the dnstap support in kdig only! To build the dnstap query module, --with-module-dnstap have to be used.

Since Knot DNS version 2.5.0 each query module can be configured to be:

  • disabled: --with-module-MODULE_NAME=no

  • embedded: --with-module-MODULE_NAME=yes

  • external: --with-module-MODULE_NAME=shared (excluding dnsproxy and onlinesign)

The --with-timer-mapsize configure option was replaced with the runtime template.max-timer-db-size configuration option.

KASP DB migration

Knot DNS version 2.4.x and earlier uses JSON files to store DNSSEC keys metadata, one for each zone. 2.5.x versions store those in binary format in a LMDB, all zones together. The migration is possible with the pykeymgr script:

$ pykeymgr -i path/to/keydir

The path to KASP DB directory is configuration-dependent, usually it is the keys subdirectory in the zone storage.

In rare installations, the JSON files might be spread across more directories. In such case, it is necessary to put them together into one directory and migrate at once.

Configuration changes

It is no longer possible to configure KASP DB per zone or in a non-default template. Ensure just one common KASP DB configuration in the default template.

As Knot DNS version 2.5.0 brings dynamically loaded modules, some modules were renamed for technical reasons. So it is necessary to rename all occurrences (module section names and references from zones or templates) of the following module names in the configuration:

mod-online-sign -> mod-onlinesign

mod-synth-record -> mod-synthrecord

Upgrade 2.5.x to 2.6.x

Upgrading from Knot DNS version 2.5.x to 2.6.x is almost seamless.

Configuration changes

The dsa and dsa-nsec3-sha1 algorithm values are no longer supported by the algorithm option.

The ixfr-from-differences zone/template option was deprecated in favor of the zonefile-load option.

Upgrade 2.6.x to 2.7.x

Upgrading from Knot DNS version 2.6.x to 2.7.x is seamless if no obsolete configuration or module rosedb is used.

Upgrade 2.7.x to 2.8.x

Upgrading from Knot DNS version 2.7.x to 2.8.x is seamless.

However, if the previous version was migrated (possibly indirectly) from version 2.5.x, the format of the keys stored in Keys And Signature Policy Database is no longer compatible and needs to be updated.

The easiest ways to update how keys are stored in KASP DB is to modify with Keymgr version 2.7.x some of each key's parameters in an undamaging way, e.g.:

$ keymgr example.com. list
$ keymgr example.com. set <keyTag> created=1
$ keymgr example.com. set <keyTag2> created=1
...

Upgrade 2.8.x to 2.9.x

Upgrading from Knot DNS version 2.8.x to 2.9.x is almost seamless but check the following changes first.

Configuration changes

Miscellaneous changes

Upgrade 2.9.x to 3.0.x

Knot DNS version 3.0.x is functionally compatible with 2.9.x with the following exceptions.

ACL

Configuration option update-owner-name is newly FQDN-sensitive. It means that values a.example.com and a.example.com. are not equivalent.

Module synthrecord

Reverse IPv6 address shortening is enabled by default. For example, the module generates:

dynamic-2620-0-b61-100--1.test. 400 IN AAAA 2620:0:b61:100::1

instead of:

dynamic-2620-0000-0b61-0100-0000-0000-0000-0001.test. 400 IN AAAA 2620:0:b61:100::1

Query module API change

The following functions require additional parameter (thread id – qdata->params->thread_id) on the second position:

knotd_mod_stats_incr()
knotd_mod_stats_decr()
knotd_mod_stats_store()

Building notes

  • The embedded library LMDB is no longer part of the source code. Almost every modern operating system has a sufficient version of this library.

  • DoH support in kdig requires optional library libnghttp2.

  • XDP support on Linux requires optional library libbpf >= 0.0.6. If not available, an embedded library can be used via --enable-xdp=yes configure option.

Upgrade 3.0.x to 3.1.x

Knot DNS version 3.1.x is functionally compatible with 3.0.x with the following exceptions.

Configuration changes

  • Automatic SOA serial incrementation (zonefile-load: difference-no-serial) requires having full zone stored in the journal (journal-content: all). This change is necessary for reliable operation.

  • Replaced options (with backward compatibility):

    Old section

    Old item name

    New section

    New item name

    server

    listen-xdp

    xdp

    listen

  • Ignored obsolete options (with a notice log):

    • server.max-ipv4-udp-payload

    • server.max-ipv6-udp-payload

    • server.max-udp-payload

    • server.max-tcp-clients

    • server.tcp-reply-timeout

    • zone.max-journal-depth

    • zone.max-journal-usage

    • zone.max-refresh-interval

    • zone.min-refresh-interval

    • zone.max-zone-size

    • template.journal-db

    • template.kasp-db

    • template.timer-db

    • template.max-journal-db-size

    • template.max-timer-db-size

    • template.max-kasp-db-size

    • template.journal-db-mode

  • Silently ignored obsolete options:

    • server.tcp-handshake-timeout

    • zone.disable-any

Zone backup and restore

The online backup format has changed slightly since 3.0 version. For zone-restore from backups in the previous format, it's necessary to set the -f option. Offline restore procedure of zone files from online backups is different than what it was before. The details are described in Data and metadata backup.

Building notes

  • The configure option --enable-xdp=yes has slightly changed its semantics. It first tries to find an external library libbpf. If it's not detected, the embedded one is used instead.

  • The kxdpgun tool also depends on library libmnl.

Packaging

Users who use module geoip or dnstap might need installing an additional package with the module.

Upgrade 3.1.x to 3.2.x

Knot DNS version 3.2.x is functionally compatible with 3.1.x with the following exceptions.

Configuration changes

  • Default value for:

  • New checks:

    • rrsig-refresh must be high enough to ensure all RRSIGs are refreshed before their expiration.

    • A notice log message is emitted if algorithm is deprecated.

  • Ignored obsolete option (with a notice log):

    • server.listen-xdp

Utilities

  • knotc prints simplified zones status by default. Use -e for full output.

  • keymgr uses the brief key listing mode by default. Use -e for full output.

  • keymgr parameter -d was renamed to -D.

  • kjournalprint parameter -c was renamed to -H.

Packaging

  • Linux distributions Debian 9 and Ubuntu 16.04 are no longer supported.

  • Packages for CentOS 7 are stored in a separate COPR repository cznic/knot-dns-latest-centos7.

  • Utilities kzonecheck, kzonesign, and knsec3hash are located in a new knot-dnssecutils package.

Python

  • Compatibility with Python 2 was removed.

Upgrade 3.2.x to 3.3.x

There are some changes between Knot DNS versions 3.3.x and 3.2.x that should be taken into consideration before upgrading.

Configuration changes

  • The configuration option xdp_quic-log has been replaced with a more general logging option quic, which applies to both conventional QUIC and QUIC over XDP.

Functionality

  • Responses to forwarded DDNS requests are signed with the local TSIG key instead of the remote one if the TSIG secret is known. To forward DDNS requests signed with a locally unknown key, an ACL rule for the action update without a key must be configured for the zone.

  • Addresses for the remote which is considered the source of the NOTIFY are tried in the order they are specified in the remote configuration, regardless of which address the NOTIFY came from.

  • Semantic checks don't allow DS record at non-delegation point.

  • The Version: prefix has been removed from the status version control output.

  • DNS over QUIC requires doq ALPN. The previous versions doq-i03 and doq-i11 are no longer supported.

XDP

The embedded library libbpf has been removed from the project, and an external one is required for the XDP support. If libbpf is version 1.0 or higher, an additional library libxdp is also required.

Query module API change

The function knotd_qdata_local_addr() only takes one parameter.

Upgrade 3.3.x to 3.4.x

There are the following changes between Knot DNS versions 3.4.x and 3.3.x.

DNSSEC

  • DNSSEC validation fails if the remaining RRSIG validity is shorter than the corresponding rrsig-refresh value.

  • SKR verification fails if the end of a DNSKEY RRSIG validity period doesn't cover the next DNSKEY snapshot.

  • If DNSSEC signing is enabled, the outbound request's EDNS expire value is lowered to the earliest RRSIG expiration if it is higher.

Semantic checks

Configuration changes

  • The server no longer allows concurrent control zone and configuration transactions.

  • The server no longer allows opening a zone transaction when a blocking command is running.

  • Removed already ignored obsolete options:

    • server.max-ipv4-udp-payload

    • server.max-ipv6-udp-payload

    • server.max-udp-payload

    • server.max-tcp-clients

    • server.tcp-handshake-timeout

    • server.tcp-reply-timeout

    • server.listen-xdp

    • xdp.quic-log

    • zone.max-journal-depth

    • zone.max-journal-usage

    • zone.max-refresh-interval

    • zone.min-refresh-interval

    • zone.max-zone-size

    • zone.disable-any

    • template.journal-db

    • template.kasp-db

    • template.timer-db

    • template.max-journal-db-size

    • template.max-timer-db-size

    • template.max-kasp-db-size

    • template.journal-db-mode

Utilities

Documentation

  • Info pages are no longer supported.

Building notes

  • A GCC or LLVM Clang compiler with C11 support is required.

  • Minimum required GnuTLS version is 3.6.10.

  • Libidn version 1 is no longer supported.

  • Liburcu must be available via pkg-config.

  • Linux distributions CentOS 7, Debian 10, and Ubuntu 18.04 are no longer supported.

Upgrade 3.4.x to 3.5.x

There are the following changes between Knot DNS versions 3.5.x and 3.4.x.

DNSSEC

  • The default value of nsec3-salt-length was lowered to 0, which means no extra SHA-1 iterations are used. If the option value is not explicitly set, zones that rely on the default will be re-signed upon upgrade.

Utilities

  • kzonecheck's zone origin auto-detection now uses the owner name of the first SOA record from the checked zone file. If the owner isn't a FQDN, the zone file name (without possible .zone suffix) is used as the initial zone origin.

  • knot-exporter: the following metrics, labes, or units have been changed:

    Old metric (old labels), New metric (new labels), New unit

    knot_memory_usage(section, type)

    knot_memory_usage(pid)

    bytes

    knot_*(section, type)

    knot_stats_*(module, type)

    knot_*(section)

    knot_stats_*(module, type="")

    knot_*(zone, section, type)

    knot_zone_stats_*(zone, module, type)

    knot_*(zone, section)

    knot_zone_stats_*(zone, module, type="")

    knot_zone_stats_*(zone)

    knot_zone_status_*(zone)

    knot_zone_refresh(zone)

    knot_zone_refresh(zone)

    seconds

    knot_zone_retry(zone)

    knot_zone_retry(zone)

    seconds

    knot_zone_expiration(zone)

    knot_zone_expiration(zone)

    seconds

Upgrade 3.5.x to 3.6.x

There are the following changes between Knot DNS versions 3.6.x and 3.5.x.

Database

  • Knot DNS uses several LMDB databases to store various types of data, specifically the journal, KASP, timer, catalog, and confdb databases. Since LMDB version 1.0, the underlying format has changed and is incompatible with the long-standing 0.9 format. For operational convenience, Knot DNS can automatically migrate databases from 0.9 to 1.x when opening them.

    This also applies when databases are opened by utilities (e.g. confdb accessed by knotc or journal accessed by kjournalprint). If the migration is successful, the previous database is stored in a backup directory (see the logs for details).

    Users should ensure exclusive access to each database during its migration (i.e. do not run the server and utilities concurrently). Making a backup of the data before migration is recommended.

  • LMDB is also used in the backup format. Knot DNS can migrate backups based on the LMDB format 0.9 to 1.x during data restoration.

    Users should ensure exclusive access to the backup data during its migration. Only one zone should be restored with migration. After a successful migration, the backup data can be accessed normally. If migration is expected, restoring from a copy of the backup data is recommended.

  • Note that LMDB incompatibility and migration issues are not related to Knot DNS 3.6 itself, but to the LMDB version that Knot DNS is linked against.

DNSSEC

  • In on-secondary signing mode, the last signed SOA serial is store in the KASP database by default. The storage can be configured via dnssec-metadata-db. Note that the value has been stored in the timer database since version 3.4.5.

  • The maximum allowed value of nsec3-iterations is 256.

  • Signed zones with more than 256 additional NSEC3 iterations specified in NSEC3PARAM are not loaded.

  • Changing NSEC3PARAM via DDNS is no longer possible.

  • Deleted keys are temporarily preserved in the trash bin.

TCP Fast Open

  • The server.tcp-fastopen configuration option has no effect.

  • The +fastopen kdig option no longer exists.

  • The mod-dnsproxy.tcp-fastopen configuration option no longer exists.

Zone

  • If zonefile-load is set to difference-no-serial, the configured serial policy is enforced even during initial zone file loading.

  • If zonefile-load is set to difference, zone file updates require an incremented SOA serial.

Logging

  • Non-syslog logging uses millisecond-precision prefix timestamps.

  • A colon separator has been added to the time zone specification in non-syslog logging.

Utilities

  • The IDN control in kdig has changed:

    • The +noidn option no longer exists.

    • Two new options, +[no]idnin and +[no]idnout, have been introduced.

    • Conversion to Punycode is disabled by default for non-tty outputs (e.g. file, pipe).

  • Mostly unified and improved output from knotc commands:

    • The zone name is omitted if one zone is explicitly specified.

    • The zone name is highlighted.

    • Statistic values are highlighted.

    • Zone-related output uses : as the key-value separator instead of =.

    • The = key-value separator was removed from the configuration listing to make it consistent with configuration setting.

  • In knotc command zone-purge, DNSSEC keys metadata are no longer purged with the filter +kaspdb or by default. DNSSEC keys and their metadata can be purged with a new filter +keys, while the filter +kaspdb purges all other KASP DB data.

Building notes

  • Minimum required GnuTLS version is 3.6.12.

  • The shared library libdnssec no longer exists, as it was integrated into the libknot library.

Knot DNS for BIND users

Automatic DNSSEC signing

Migrating automatically signed zones from BIND to Knot DNS requires copying up-to-date zone files from BIND, importing existing private keys, and updating server configuration:

  1. To obtain current content of the zone which is being migrated, request BIND to flush the zone into the zone file: rndc sync example.com.

    Note

    If dynamic updates (DDNS) are enabled for the given zone, you might need to freeze the zone before flushing it. That can be done similarly:

    $ rndc freeze example.com

  2. Copy the fresh zone file into the zones storage directory of Knot DNS.

  3. Import all existing zone keys into the KASP database. Make sure that all the keys were imported correctly:

    $ keymgr example.com. import-bind path/to/Kexample.com.+013+11111
$ keymgr example.com. import-bind path/to/Kexample.com.+013+22222
$ ...
$ keymgr example.com. list

    Note

    If the server configuration file or database is not at the default location, add a configuration parameter (-c or -C). See keymgr for more info about required access rights to the key files.

  4. Follow Automatic DNSSEC signing steps to configure DNSSEC signing.