diff options
Diffstat (limited to 'doc/migration.rst')
| -rw-r--r-- | doc/migration.rst | 437 |
1 files changed, 437 insertions, 0 deletions
diff --git a/doc/migration.rst b/doc/migration.rst new file mode 100644 index 0000000..f79539c --- /dev/null +++ b/doc/migration.rst @@ -0,0 +1,437 @@ +.. highlight:: none +.. _Migration: + +********* +Migration +********* + +.. _Upgrade 2.4.x to 2.5.x: + +Upgrade 2.4.x to 2.5.x +====================== + +This chapter describes some steps necessary after upgrading Knot DNS from +version 2.4.x to 2.5.x. + +.. _Building changes: + +Building changes +---------------- + +The ``--enable-dnstap`` configure option now enables the dnstap support in +:doc:`kdig<man_kdig>` only! To build the dnstap query module, ``--with-module-dnstap`` +have to be used. + +Since Knot DNS version 2.5.0 each query module can be configured to be: + +- disabled: ``--with-module-``\ MODULE_NAME\ ``=no`` +- embedded: ``--with-module-``\ MODULE_NAME\ ``=yes`` +- external: ``--with-module-``\ MODULE_NAME\ ``=shared`` (excluding + ``dnsproxy`` and ``onlinesign``) + +The ``--with-timer-mapsize`` configure option was replaced with the runtime +``template.max-timer-db-size`` configuration option. + +.. _KASP DB migration: + +KASP DB migration +----------------- + +Knot DNS version 2.4.x and earlier uses JSON files to store DNSSEC keys metadata, +one for each zone. 2.5.x versions store those in binary format in a LMDB, all zones +together. The migration is possible with the +`pykeymgr <https://gitlab.nic.cz/knot/knot-dns/blob/2.6/src/utils/pykeymgr/pykeymgr.in>`_ +script:: + + $ pykeymgr -i path/to/keydir + +The path to KASP DB directory is configuration-dependent, usually it is the ``keys`` +subdirectory in the zone storage. + +In rare installations, the JSON files might be spread across more directories. In such +case, it is necessary to put them together into one directory and migrate at once. + +.. _Configuration changes 2.5: + +Configuration changes +--------------------- + +It is no longer possible to configure KASP DB per zone or in a non-default +template. Ensure just one common KASP DB configuration in the default +template. + +As Knot DNS version 2.5.0 brings dynamically loaded modules, some modules +were renamed for technical reasons. So it is necessary to rename all +occurrences (module section names and references from zones or templates) +of the following module names in the configuration:: + + mod-online-sign -> mod-onlinesign + + mod-synth-record -> mod-synthrecord + +.. _Upgrade 2.5.x to 2.6.x: + +Upgrade 2.5.x to 2.6.x +====================== + +Upgrading from Knot DNS version 2.5.x to 2.6.x is almost seamless. + +.. _Configuration changes 2.6: + +Configuration changes +--------------------- + +The ``dsa`` and ``dsa-nsec3-sha1`` algorithm values are no longer supported +by the :ref:`policy_algorithm` option. + +The ``ixfr-from-differences`` zone/template option was deprecated in favor of +the :ref:`zone_zonefile-load` option. + +.. _Upgrade 2.6.x to 2.7.x: + +Upgrade 2.6.x to 2.7.x +====================== + +Upgrading from Knot DNS version 2.6.x to 2.7.x is seamless if no obsolete +configuration or module rosedb is used. + +.. _Upgrade 2.7.x to 2.8.x: + +Upgrade 2.7.x to 2.8.x +====================== + +Upgrading from Knot DNS version 2.7.x to 2.8.x is seamless. + +However, if the previous version was migrated (possibly indirectly) +from version 2.5.x, the format of the keys stored in +Keys And Signature Policy Database +is no longer compatible and needs to be updated. + +The easiest ways to update how keys are stored in KASP DB is to modify +with Keymgr version 2.7.x +some of each key's parameters in an undamaging way, e.g.:: + + $ keymgr example.com. list + $ keymgr example.com. set <keyTag> created=1 + $ keymgr example.com. set <keyTag2> created=1 + ... + +.. _Upgrade 2.8.x to 2.9.x: + +Upgrade 2.8.x to 2.9.x +====================== + +Upgrading from Knot DNS version 2.8.x to 2.9.x is almost seamless but check +the following changes first. + +Configuration changes +--------------------- + +- Imperfect runtime reconfiguration of :ref:`server_udp-workers`, + :ref:`server_tcp-workers`, and :ref:`server_listen` + is no longer supported. + +- Replaced options (with backward compatibility): + + .. csv-table:: + :header: Old section, Old item name, New section, New item name + :widths: 35, 60, 35, 60 + + :ref:`server<Server section>` , ``tcp-reply-timeout`` [s] , :ref:`server<Server section>` , :ref:`server_tcp-remote-io-timeout` [ms] + :ref:`server<Server section>` , ``max-tcp-clients`` , :ref:`server<Server section>` , :ref:`server_tcp-max-clients` + :ref:`server<Server section>` , ``max-udp-payload`` , :ref:`server<Server section>` , :ref:`server_udp-max-payload` + :ref:`server<Server section>` , ``max-ipv4-udp-payload`` , :ref:`server<Server section>` , :ref:`server_udp-max-payload-ipv4` + :ref:`server<Server section>` , ``max-ipv6-udp-payload`` , :ref:`server<Server section>` , :ref:`server_udp-max-payload-ipv6` + :ref:`template<Template section>` , ``journal-db`` , :ref:`database<Database section>` , :ref:`database_journal-db` + :ref:`template<Template section>` , ``journal-db-mode`` , :ref:`database<Database section>` , :ref:`database_journal-db-mode` + :ref:`template<Template section>` , ``max-journal-db-size`` , :ref:`database<Database section>` , :ref:`database_journal-db-max-size` + :ref:`template<Template section>` , ``kasp-db`` , :ref:`database<Database section>` , :ref:`database_kasp-db` + :ref:`template<Template section>` , ``max-kasp-db-size`` , :ref:`database<Database section>` , :ref:`database_kasp-db-max-size` + :ref:`template<Template section>` , ``timer-db`` , :ref:`database<Database section>` , :ref:`database_timer-db` + :ref:`template<Template section>` , ``max-timer-db-size`` , :ref:`database<Database section>` , :ref:`database_timer-db-max-size` + :ref:`zone<Zone section>` , ``max-journal-usage`` , :ref:`zone<Zone section>` , :ref:`zone_journal-max-usage` + :ref:`zone<Zone section>` , ``max-journal-depth`` , :ref:`zone<Zone section>` , :ref:`zone_journal-max-depth` + :ref:`zone<Zone section>` , ``max-zone-size`` , :ref:`zone<Zone section>` , :ref:`zone_zone-max-size` + :ref:`zone<Zone section>` , ``max-refresh-interval`` , :ref:`zone<Zone section>` , :ref:`zone_refresh-max-interval` + :ref:`zone<Zone section>` , ``min-refresh-interval`` , :ref:`zone<Zone section>` , :ref:`zone_refresh-min-interval` + +- Removed options (no backward compatibility): + + - ``server.tcp-handshake-timeout`` + - ``zone.request-edns-option`` + +- New default value for: + + - :ref:`server_tcp-workers` + - :ref:`server_tcp-max-clients` + - :ref:`server_udp-max-payload` + - :ref:`server_udp-max-payload-ipv4` + - :ref:`server_udp-max-payload-ipv6` + +- New DNSSEC policy option :ref:`policy_rrsig-pre-refresh` may affect + configuration validity, which is ``rrsig-refresh + rrsig-pre-refresh < rrsig-lifetime`` + +Miscellaneous changes +--------------------- + +- Memory use estimation via ``knotc zone-memstats`` was removed +- Based on `<https://tools.ietf.org/html/draft-ietf-dnsop-server-cookies>`_ + the module :ref:`DNS Cookies<mod-cookies>` was updated to be interoperable +- Number of open files limit is set to 1048576 in upstream packages + +.. _Upgrade 2.9.x to 3.0.x: + +Upgrade 2.9.x to 3.0.x +====================== + +Knot DNS version 3.0.x is functionally compatible with 2.9.x with the following +exceptions. + +ACL +--- + +Configuration option :ref:`acl_update-owner-name` is newly FQDN-sensitive. +It means that values ``a.example.com`` and ``a.example.com.`` are not equivalent. + +Module synthrecord +------------------ + +:ref:`Reverse IPv6 address shortening<mod-synthrecord_reverse-short>` is enabled by default. +For example, the module generates:: + + dynamic-2620-0-b61-100--1.test. 400 IN AAAA 2620:0:b61:100::1 + +instead of:: + + dynamic-2620-0000-0b61-0100-0000-0000-0000-0001.test. 400 IN AAAA 2620:0:b61:100::1 + +Query module API change +----------------------- + +The following functions require additional parameter (thread id – ``qdata->params->thread_id``) +on the second position:: + + knotd_mod_stats_incr() + knotd_mod_stats_decr() + knotd_mod_stats_store() + +Building notes +-------------- + +- The embedded library *LMDB* is no longer part of the source code. Almost every + modern operating system has a sufficient version of this library. +- DoH support in kdig requires optional library *libnghttp2*. +- XDP support on Linux requires optional library *libbpf >= 0.0.6*. If not available, + an embedded library can be used via ``--enable-xdp=yes`` configure option. + +.. _Upgrade 3.0.x to 3.1.x: + +Upgrade 3.0.x to 3.1.x +====================== + +Knot DNS version 3.1.x is functionally compatible with 3.0.x with the following +exceptions. + +Configuration changes +--------------------- + +- Automatic SOA serial incrementation (``zonefile-load: difference-no-serial``) + requires having full zone stored in the journal (``journal-content: all``). + This change is necessary for reliable operation. + +- Replaced options (with backward compatibility): + + .. csv-table:: + :header: Old section, Old item name, New section, New item name + :widths: 40, 60, 40, 60 + + :ref:`server<Server section>`, ``listen-xdp``, :ref:`xdp<XDP section>`, :ref:`xdp_listen` + +- Ignored obsolete options (with a notice log): + + - ``server.max-journal-depth`` + - ``server.max-journal-usage`` + - ``server.max-refresh-interval`` + - ``server.min-refresh-interval`` + - ``server.max-ipv4-udp-payload`` + - ``server.max-ipv6-udp-payload`` + - ``server.max-udp-payload`` + - ``server.max-tcp-clients`` + - ``server.tcp-reply-timeout`` + - ``template.journal-db`` + - ``template.kasp-db`` + - ``template.timer-db`` + - ``template.max-zone-size`` + - ``template.max-journal-db-size`` + - ``template.max-timer-db-size`` + - ``template.max-kasp-db-size`` + - ``template.journal-db-mode`` + +- Silently ignored obsolete options: + + - ``server.tcp-handshake-timeout`` + - ``zone.disable-any`` + +Zone backup and restore +----------------------- + +The online backup format has changed slightly since 3.0 version. For zone-restore +from backups in the previous format, it's necessary to set the *-f* option. +Offline restore procedure of zone files from online backups is different than +what it was before. The details are described in :ref:`Data and metadata backup`. + +Building notes +-------------- + +- The configure option ``--enable-xdp=yes`` has slightly changed its semantics. + It first tries to find an external library *libbpf*. If it's not detected, + the embedded one is used instead. +- The kxdpgun tool also depends on library *libmnl*. + +Packaging +--------- + +Users who use module :ref:`geoip<mod-geoip>` or :ref:`dnstap<mod-dnstap>` might +need installing an additional package with the module. + +.. _Upgrade 3.1.x to 3.2.x: + +Upgrade 3.1.x to 3.2.x +====================== + +Knot DNS version 3.2.x is functionally compatible with 3.1.x with the following +exceptions. + +Configuration changes +--------------------- + +- Default value for: + + - :ref:`zone_journal-max-depth` was lowered to 20. + This change may trigger journal history merging. + - :ref:`policy_nsec3-iterations` was lowered to 0. + This change may trigger complete NSEC3 chain reconstruction! + - :ref:`policy_rrsig-refresh` is set to :ref:`policy_propagation-delay` + "zone maximum TTL". + This change affects effective RRSIG lifetime! + +- New checks: + + - :ref:`policy_rrsig-refresh` must be high enough to ensure all RRSIGs are + refreshed before their expiration. + - A notice log message is emitted if :ref:`policy_algorithm` is deprecated. + +- Ignored obsolete option (with a notice log): + + - ``server.listen-xdp`` + +Utilities: +---------- + +- :doc:`knotc<man_knotc>` prints simplified zones status by default. Use ``-e`` + for full output. +- :doc:`keymgr<man_keymgr>` uses the brief key listing mode by default. Use ``-e`` + for full output. +- :doc:`keymgr<man_keymgr>` parameter ``-d`` was renamed to ``-D``. +- :doc:`kjournalprint<man_kjournalprint>` parameter ``-c`` was renamed to ``-H``. + +Packaging +--------- + +- Linux distributions Debian 9 and Ubuntu 16.04 are no longer supported. + +- Packages for CentOS 7 are stored in a separate COPR repository + ``cznic/knot-dns-latest-centos7``. + +- Utilities :doc:`kzonecheck<man_kzonecheck>`, :doc:`kzonesign<man_kzonesign>`, + and :doc:`knsec3hash<man_knsec3hash>` are located in a new ``knot-dnssecutils`` + package. + +Python +------ + +- Compatibility with Python 2 was removed. + +.. _Upgrade 3.2.x to 3.3.x: + +Upgrade 3.2.x to 3.3.x +====================== + +There are some changes between Knot DNS versions 3.3.x and 3.2.x that should be +taken into consideration before upgrading. + +Configuration changes +--------------------- + +- The configuration option ``xdp_quic-log`` has been replaced with a more general + logging option :ref:`log_quic`, which applies to both conventional QUIC and + QUIC over XDP. + +Functionality +------------- + +- Responses to forwarded DDNS requests are signed with the local TSIG key instead + of the remote one if the TSIG secret is known. To forward DDNS requests + signed with a locally unknown key, an ACL rule for the action ``update`` without + a key must be configured for the zone. +- Addresses for the remote which is considered the source of the NOTIFY are tried + in the order they are specified in the remote configuration, regardless of which + address the NOTIFY came from. +- Semantic checks don't allow DS record at non-delegation point. +- The ``Version:`` prefix has been removed from the ``status version`` control output. +- DNS over QUIC requires ``doq`` ALPN. The previous versions ``doq-i03`` and + ``doq-i11`` are no longer supported. + +XDP +--- + +The embedded library ``libbpf`` has been removed from the project, and an external +one is required for the XDP support. If ``libbpf`` is version 1.0 or higher, +an additional library ``libxdp`` is also required. + +Query module API change +----------------------- + +The function ``knotd_qdata_local_addr()`` only takes one parameter. + +.. _Knot DNS for BIND users: + +Knot DNS for BIND users +======================= + +.. _Automatic DNSSEC signing: + +Automatic DNSSEC signing +------------------------ + +Migrating automatically signed zones from BIND to Knot DNS requires copying +up-to-date zone files from BIND, importing existing private keys, and updating +server configuration: + +1. To obtain current content of the zone which is being migrated, + request BIND to flush the zone into the zone file: ``rndc sync + example.com``. + + .. NOTE:: + If dynamic updates (DDNS) are enabled for the given zone, you + might need to freeze the zone before flushing it. That can be done + similarly:: + + $ rndc freeze example.com + +2. Copy the fresh zone file into the zones :ref:`storage<zone_storage>` + directory of Knot DNS. + +3. Import all existing zone keys into the KASP database. Make sure that all + the keys were imported correctly:: + + $ keymgr example.com. import-bind path/to/Kexample.com.+013+11111 + $ keymgr example.com. import-bind path/to/Kexample.com.+013+22222 + $ ... + $ keymgr example.com. list + + .. NOTE:: + If the server configuration file or database is not at the default location, + add a configuration parameter (-c or -C). See :doc:`keymgr<man_keymgr>` + for more info about required access rights to the key files. + +4. Follow :ref:`Automatic DNSSEC signing` steps to configure DNSSEC signing. |