Upgrading¶
This section summarizes steps required for upgrade to newer Knot Resolver versions. We advise users to also read Release notes for respective versions.
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.