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.
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.Human readable output from Control sockets is not stable and changes from time to time. 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 calltojson(cache.stats())\n
will return JSON string withcache.stats()
results represented as dictionary. Functiontojson()
is available in all resolver versions >= 1.0.0.DoH served with http module DNS-over-HTTP (DoH) will be marked as legacy and won’t receive any more bugfixes. A more reliable and scalable DoH module will be available instead. The new DoH module will only support HTTP/2 over TLS.
New releases since Octomer 2020 will contain changes for DNS Flag Day 2020. Please double-check your firewall, it has to allow DNS traffic on UDP and also TCP port 53.
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 loggerkr_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
withnet.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:53ListenStream=127.0.0.1:53
net.listen('127.0.0.1', 53, { kind = 'dns' })
- kresd.socket
- [Socket]FreeBind=trueBindIPv6Only=bothListenDatagram=[::1]:53ListenStream=[::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. Usefreebind=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 functionkr_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 installknot-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, usetrust_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()
andtrust_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, usetrust_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 namespacekres_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. Addhints.use_nodata(false)
to your config to revert to the old behavior.Modules
cookie
andversion
were removed. Please remove relevant configuration lines withmodules.load()
andmodules =
from configuration file.Valid configuration must open cache using
cache.open()
orcache.size =
before executing cache operations likecache.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 thebegin
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()
andkr_nsrep_sort()
changed parameters slightly.