1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
.. SPDX-License-Identifier: GPL-3.0-or-later
.. _upgrading:
*********
Upgrading
*********
This section summarizes steps required for upgrade to newer Knot Resolver versions.
We advise users to also read :ref:`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 :c:type:`kr_request.trace_log` handler need update to modified handler API. Example migration is `modules/watchdog/watchdog.lua <https://gitlab.nic.cz/knot/knot-resolver/-/merge_requests/957/diffs#6831501329bbf9e494048fe269c6b02944fc227c>`_.
* Modules which were using logger :c:func:`kr_log_qverbose_impl` need migration to new logger :c:func:`kr_log_q`. Example migration is `modules/rebinding/rebinding.lua <https://gitlab.nic.cz/knot/knot-resolver/-/merge_requests/957/diffs#6c74dcae147221ca64286a3ed028057adb6813b9>`_.
* Modules which were using :c:func:`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
.. csv-table::
:header: "","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 <https://gitlab.nic.cz/knot/knot-resolver/issues/529>`_;
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
:func:`net.listen` instead of systemd sockets (`#485
<https://gitlab.nic.cz/knot/knot-resolver/issues/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.
.. csv-table::
:header: "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' })``"
* :func:`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
<https://gitlab.nic.cz/knot/knot-resolver/commit/edb8ffef7fbe48befeb3f7164d38079dd0be3302#1fe36e8ac0729b279645f7237b7122b1c457a982>`_.
.. _upgrade-from-3-to-4:
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
:ref:`dnssec-config`.
* ``-k/--keyfile`` and ``-K/--keyfile-ro`` daemon options were removed. If needed,
use ``trust_anchors.add_file()`` in configuration file instead.
* Configuration for :ref:`HTTP module <mod-http>` changed significantly as result of
adding :ref:`mod-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:
.. csv-table::
:header: "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 :func:`trust_anchors.remove()`.
.. csv-table::
:header: "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 :ref:`network-configuration`. Migration table:
.. csv-table::
:header: "3.x configuration", "4.x configuration"
"``modules = { http = { host = '192.0.2.1', port = 443 }}``","see chapter :ref:`network-configuration`"
"``http.config({ host = '192.0.2.1', port = 443 })``","see chapter :ref:`network-configuration`"
"``modules = { http = { endpoints = ... }}``","see chapter :ref:`mod-http-custom-endpoint`"
"``http.config({ endpoints = ... })``","see chapter :ref:`mod-http-custom-endpoint`"
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 :ref:`build`. Packagers should pay attention to section :ref:`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 <https://gitlab.nic.cz/knot/knot-resolver/commit/2875a3970#9fa69cdc6ee1903dc22e3262f58996395acab364>`_.
.. _upgrade-from-2-to-3:
2.x to 3.x
==========
Users
-----
* Module :ref:`mod-hints` has option :func:`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 :ref:`significant-lua-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.
|
