Upgrading

This section summarizes steps required for upgrade 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.

5.0 to 5.1

Module changes

  • Modules which use kr_request.trace_log handler need update to modified handler API. Example migration is modules/watchdog/watchdog.lua.

  • Modules which were using logger kr_log_qverbose_impl() need migration to new logger kr_log_q(). Example migration is modules/rebinding/rebinding.lua.

  • Modules which were using kr_ranked_rrarray_add() should note that on success it no longer returns exclusively zero but index into the array (non-negative). Error states are unchanged (negative).

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 DNS-over-HTTP (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 enpoints, 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.