Upgrading to a Newer Version of Kea
- 29 May 2024
- 3 Minutes to read
-
Contributors
-
Print
-
DarkLight
-
PDF
Upgrading to a Newer Version of Kea
- Updated on 29 May 2024
- 3 Minutes to read
-
Contributors
-
Print
-
DarkLight
-
PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
Introduction
Upgrading Kea is a relatively easy task. This article describes upgrading Kea for versions 1.6.0 and newer; for instructions on how to upgrade older versions, please visit our Kea wiki page. Please make sure that the version you are about to upgrade is not listed in the "Exceptions" section below.
If there are future releases that are not backward-compatible, we will update this article with migration instructions.
Upgrade Preparations
Before starting the upgrade process, please read the release notes for the new version to check for changes that make your current configuration incompatible and, if necessary, update your configuration. Fortunately, incompatibilities are rare; one example was when we moved the location of the logging statement in the Kea configuration hierarchy. These types of changes will always be noted in the release notes.
Kea database upgrade scripts can detect the current running schema version and execute all necessary steps to upgrade, so it's possible to update across several version bumps at once (i.e,. from 2.0.0 to 2.0.2, without 2.0.1 in between).
Moving from Source to Packages
Moving from a source (tarball) installation to using a Kea package must be done with caution. When building from source, the location of the binaries, system libraries, and other support files may be defined on the configure command line. When moving to ISC-supplied packages, the locations of the files may change.
Be very careful when installing packages that remnants of the previously installed code do not remain on the system. Not removing the executables can lead to issues during system startup or maintenance when an older version of the server is run instead of the newly installed version. Not removing shared libraries can cause newly installed servers to attempt to use the older libraries and fail with linker errors.
Best Practice
It is highly recommended that you make copies of your configuration files before you begin a source-to-package migration.
Upgrading a Single Server
These instructions are for deployments that are not using High Availability. If you are building from source, compile the new version first.
- Back up the configuration and leases files.
- Turn off Kea.
- Install the new version.
- If you are using a database backend, run the kea-admin script as stated in the Administrator's Reference Manual (ARM for mysql, ARM for pgsql). If you are using the default memfile option, that will be upgraded automatically.
- Start Kea.
Upgrading a High-Availability Pair
When upgrading a HA pair, you can follow essentially the same process as above; simply repeat some of the steps. Important things to know are:
- It is not necessary to turn off all nodes to upgrade. Each node can be updated in turn, while maintaining DHCP service in the network.
- Kea 1.7.4 and newer versions have an
in-maintenancemode, activated by the commandha-maintenance-start. It is recommended to use this command to instruct the HA partner server to take over all DHCP services, allowing the operator to upgrade the other server. - If you are not using
ha-maintenance-startfor some reason, always start the upgrade from the lowest priority node, and move up one by one:- If there are any backup machines, upgrade them first.
- If the servers are in hot-standby, upgrade the standby node, then the primary node.
- If the servers are in load-balancing, primary and secondary nodes can be upgraded in any order.
- If HA nodes are using separate database backends, each should be updated separately.
- If HA nodes are sharing a single database only one update is required.
Exceptions
- These instructions do not apply to Kea versions prior to 1.6.0. Please visit the Kea wiki page for details.
- For Kea version 2.3.2 and later, the package upgrade procedure may differ slightly on some platforms, namely Debian and Ubuntu. Please refer to the Upgrading Beyond Kea 2.3.2 article for more details.
- Users of pre-2.4 Kea (2.3.8 and prior to that) that are using MariaDB 10.10 or later for DHCPv6 lease storage are recommended to upgrade directly to 2.6.0 or later to avoid an issue that expires all leases immediately on schema upgrade. For details, see #3396.