Upgrading

This section summarizes steps required when upgrading to newer Knot Resolver versions. We advise users to also read Release notes for respective versions. Section Module changes is relevant only for users who develop or use third-party modules.

Upcoming changes

Following section provides information about selected changes in not-yet-released versions. We advise users to prepare for these changes sooner rather than later to make it easier to upgrade to newer versions when they are released.

5.4 to 5.5

Packagers & Developers

  • Knot DNS >= 3.0.2 is required.

Module API changes

  • Function cache.zone_import was removed; you can use ffi.C.zi_zone_import instead (different API).

  • When using PROXYv2 protocol, the meaning of qsource.flags and qsource.comm_flags in kr_request changes so that flags describes the original client communicating with the proxy, while comm_flags describes the proxy communicating with the resolver. When there is no proxy, flags and comm_flags are the same.

5.3 to 5.4

Configuration file

  • kind='doh' in net.listen() was renamed to kind='doh_legacy'. It is recommended to switch to the new DoH implementation with kind='doh2'.

  • verbose() has been deprecated. In case you want to change logging level, there is new function log_level().

Packagers & Developers

  • meson option verbose_log was removed.

Module changes

  • lua function warn() was removed, use log_warn() instead. The new function takes a log group number as the first argument.

  • C functions kr_log_req() and kr_log_q() were replaced by kr_log_req1() and kr_log_q1() respectively. The new function have slightly different API.

5.2 to 5.3

Configuration file

  • Module dnstap: option log_responses has been moved inside a new client section. Refer to the configuration example in Dnstap (traffic collection).

Packagers & Developers

  • Knot DNS >= 2.9 is required.

5.1 to 5.2

Users

  • DoH over HTTP/1 and unencrypted transports is still available in legacy http module (kind='doh'). This module will not receive receive any more bugfixes and will be eventually removed.

  • Users of Control sockets API need to terminate each command sent to resolver with newline character (ASCII \n). Correct usage: cache.stats()\n. Newline terminated commands are accepted by all resolver versions >= 1.0.0.

  • DNS Flag Day 2020 is now effective and Knot Resolver uses maximum size of UDP answer to 1232 bytes. Please double-check your firewall, it has to allow DNS traffic on UDP and also TCP port 53.

  • Human readable output in interactive mode and from Control sockets was improved and as consequence slightly changed its format. Users who need machine readable output for scripts should use Lua function tojson() to convert Lua values into standard JSON format instead of attempting to parse the human readable output. For example API call tojson(cache.stats())\n will return JSON string with cache.stats() results represented as dictionary. Function tojson() is available in all resolver versions >= 1.0.0.

Configuration file

Module changes

5.0 to 5.1

Module changes

4.x to 5.x

Users

  • Control socket location has changed

    4.x location

    5.x location

    with systemd

    /run/knot-resolver/control@$ID

    /run/knot-resolver/control/$ID

    without systemd

    $PWD/tty/$PID

    $PWD/control/$PID

  • -f / --forks command-line option is deprecated. In case you just want to trigger non-interactive mode, there’s new -n / --noninteractive. This forking style was not ergonomic; with independent kresd processes you can better utilize a process manager (e.g. systemd).

Configuration file

  • Network interface are now configured in kresd.conf with net.listen() instead of systemd sockets (#485). See the following examples.

    Tip

    You can find suggested network interface settings based on your previous systemd socket configuration in /var/lib/knot-resolver/.upgrade-4-to-5/kresd.conf.net which is created during the package update to version 5.x.

    4.x - systemd socket file

    5.x - kresd.conf
    kresd.socket
    [Socket]
    ListenDatagram=127.0.0.1:53
    ListenStream=127.0.0.1:53
    net.listen('127.0.0.1', 53, { kind = 'dns' })
    kresd.socket
    [Socket]
    FreeBind=true
    BindIPv6Only=both
    ListenDatagram=[::1]:53
    ListenStream=[::1]:53
    net.listen('127.0.0.1', 53, { kind = 'dns', freebind = true })
    net.listen('::1', 53, { kind = 'dns', freebind = true })
    kresd-tls.socket
    [Socket]
    ListenStream=127.0.0.1:853
    net.listen('127.0.0.1', 853, { kind = 'tls' })
    kresd-doh.socket
    [Socket]
    ListenStream=127.0.0.1:443
    net.listen('127.0.0.1', 443, { kind = 'doh' })
    kresd-webmgmt.socket
    [Socket]
    ListenStream=127.0.0.1:8453
    net.listen('127.0.0.1', 8453, { kind = 'webmgmt' })

  • net.listen() throws an error if it fails to bind. Use freebind=true option to bind to nonlocal addresses.

4.2.2 to 4.3+

Module changes

  • In case you wrote your own module which directly calls function kr_ranked_rrarray_add(), you need to additionally call function kr_ranked_rrarray_finalize() after each batch (before changing the added memory regions). For a specific example see changes in dns64 module.

4.x to 4.2.1+

Users

  • If you have previously installed knot-resolver-dbgsym package on Debian, please remove it and install knot-resolver-dbg instead.

3.x to 4.x

Users

  • DNSSEC validation is now turned on by default. If you need to disable it, see DNSSEC, data verification.

  • -k/--keyfile and -K/--keyfile-ro daemon options were removed. If needed, use trust_anchors.add_file() in configuration file instead.

  • Configuration for HTTP module changed significantly as result of adding Legacy DNS-over-HTTPS (DoH) support. Please see examples below.

  • In case you are using your own custom modules, move them to the new module location. The exact location depends on your distribution. Generally, modules previously in /usr/lib/kdns_modules should be moved to /usr/lib/knot-resolver/kres_modules.

Configuration file

  • trust_anchors.file, trust_anchors.config() and trust_anchors.negative aliases were removed to avoid duplicity and confusion. Migration table:

    3.x configuration

    4.x configuration

    trust_anchors.file = path

    trust_anchors.add_file(path)

    trust_anchors.config(path, readonly)

    trust_anchors.add_file(path, readonly)

    trust_anchors.negative = nta_set

    trust_anchors.set_insecure(nta_set)

  • trust_anchors.keyfile_default is no longer accessible and is can be set only at compile time. To turn off DNSSEC, use trust_anchors.remove().

    3.x configuration

    4.x configuration

    trust_anchors.keyfile_default = nil

    trust_anchors.remove('.')

  • Network for HTTP endpoints is now configured using same mechanism as for normal DNS endpoints, please refer to chapter Networking and protocols. Migration table:

    3.x configuration

    4.x configuration

    modules = { http = { host = '192.0.2.1', port = 443 }}

    see chapter Networking and protocols

    http.config({ host = '192.0.2.1', port = 443 })

    see chapter Networking and protocols

    modules = { http = { endpoints = ... }}

    see chapter Custom HTTP services

    http.config({ endpoints = ... })

    see chapter Custom HTTP services

Packagers & Developers

  • Knot DNS >= 2.8 is required.

  • meson >= 0.46 and ninja is required.

  • meson build system is now used for compiling the project. For instructions, see the Building from sources. Packagers should pay attention to section Packaging for information about systemd unit files and trust anchors.

  • Embedding LMDB is no longer supported, lmdb is now required as an external dependency.

  • Trust anchors file from upstream is installed and used as default unless you override keyfile_default during build.

Module changes

  • Default module location has changed from {libdir}/kdns_modules to {libdir}/knot-resolver/kres_modules. Modules are now in the lua namespace kres_modules.*.

  • kr_straddr_split() API has changed.

  • C modules defining *_layer or *_props symbols need to use a different style, but it’s typically a trivial change. Instead of exporting the corresponding symbols, the module should assign pointers to its static structures inside its *_init() function. Example migration: bogus_log module.

2.x to 3.x

Users

  • Module Static hints has option hints.use_nodata() enabled by default, which is what most users expect. Add hints.use_nodata(false) to your config to revert to the old behavior.

  • Modules cookie and version were removed. Please remove relevant configuration lines with modules.load() and modules = from configuration file.

  • Valid configuration must open cache using cache.open() or cache.size = before executing cache operations like cache.clear(). (Older versions were silently ignoring such cache operations.)

Packagers & Developers

  • Knot DNS >= 2.7.2 is required.

Module changes

  • API for Lua modules was refactored, please see Significant Lua API changes.

  • New layer was added: answer_finalize.

  • kr_request keeps ::qsource.packet beyond the begin layer.

  • kr_request::qsource.tcp renamed to ::qsource.flags.tcp.

  • kr_request::has_tls renamed to ::qsource.flags.tls.

  • kr_zonecut_add(), kr_zonecut_del() and kr_nsrep_sort() changed parameters slightly.