--- title: "Upgrading to Kea 1.6" slug: "upgrading-to-kea-16" description: "Users of Kea DHCP 1.5 can use this guide to help them upgrade." tags: ["Archive", "Kea 1.6", "Kea 1.6.0 Upgrade", "kea dhcp"] updated: 2022-06-28T21:00:45Z published: 2022-06-28T21:00:45Z deprecated: true --- > ## Documentation Index > Fetch the complete documentation index at: https://kb.isc.org/llms.txt > Use this file to discover all available pages before exploring further. # Upgrading to Kea 1.6 > **Deprecated.** This software version is EOL :::(Error) (The Kea 1.6 branch is End of Life) These instructions may still be useful, but keep upgrading until you get to a currently-supported version! ::: This article describes how to migrate existing Kea 1.5.0 installations to Kea 1.6.0. Note there are 'general' changes listed first, followed by a procedure for updating High Availability pairs. 1. Default file locations for lease file, server-duid, log files and lock files changed in Kea 1.6.0. Files previously stored in `/var/kea` are now stored in `/var/run/kea`. Server hooks previously installed in `/usr/lib/hooks` are now installed in `/usr/lib/kea/hooks`. The log files are now stored in `/var/log/kea`. ([#538](https://gitlab.isc.org/isc-projects/kea/issues/538), [#686](https://gitlab.isc.org/isc-projects/kea/issues/686)) 2. The kea-admin commands (lease-init, lease-version, lease-upgrade) were renamed in Kea 1.6.0 to better reflect the fact that the database can store much more than just leases. They're now called db-init, db-version, db-upgrade. ([#466](https://gitlab.isc.org/isc-projects/kea/issues/466)) Kea 1.5.0 and earlier: ```bash $ kea-admin lease-upgrade ``` Kea 1.6.0 and later: ```bash $ kea-admin db-upgrade ``` 3. The Logging entry in the configuration file has moved to specific daemon sections. This require a simple configuration file modification. You need to move Logging entry from its global scope into the Dhcp4, Dhcp6, DhcpDdns, Control-agent or Netconf scope. ([#208](https://gitlab.isc.org/isc-projects/kea/issues/208)) As an example, the loggers defined in a Kea 1.5.0 Dhcp4 configuration could look like this: ``` "Dhcp4": { ... } "Logging": { "loggers": [ { "name": "kea-dhcp4", "output_options": [ { "output": "/var/log/kea/log/kea-dhcp4.log" } ], "severity": "INFO", "debuglevel": 0 } ] } ``` Note that `Logging` is a stand-alone section in the configuration file containing the definition of the `loggers`. In Kea 1.6.0, the same configuration snippet would be: ``` "Dhcp4": { ... "loggers": [ { "name": "kea-dhcp4", "output_options": [ { "output": "/var/log/kea/kea-dhcp4.log" } ], "severity": "INFO", "debuglevel": 0 } ] ... } ``` The `loggers` section is now contained within the "global" `Dhcp4` section. There is no-longer a "global" `Logging` section in this configuration. Kea 1.6.0 continues to support the global `logging` section in each server's configuration, but this backwards compatibility will be removed in an upcoming Kea release. * Moving from source (tarball) installation to Kea packages 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 location of the files may well have moved. Be very careful when installing packages that remnants of the previously installed code does not remain on the system. Not removing the executables can lead to issues during system startup or maintenance when an older version of servers 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. It is highly recommended that you make copies of your configuration files before you begin a source -> package migration. ------------------------------------ ### Upgrading Kea servers in HA mode from Kea 1.5.0 It's possible to upgrade Kea HA setup from 1.5.0 to 1.6.0 without stopping the DHCP service for the network but there is a specific set of instructions for both types of HA configuration (`load-balancing` and `hot-standby`). The main problem in migrating to the newer version is that Kea 1.5.0 is not able to synchronise leases that were issued by Kea 1.6.0 (Kea 1.6.0 introduced `lease6-bulk-apply` ([#683](https://gitlab.isc.org/isc-projects/kea/issues/683) & [#689](https://gitlab.isc.org/isc-projects/kea/issues/689) which is not backward-compatible) Please make sure that Kea 1.6.0 has been installed and configuration files have been prepared (taking into account all the changes described above) **BEFORE** you start this procedure; you don't want to encounter any problems with the system while part of your DHCP HA provisioning is disabled/removed during the upgrade. #### Upgrading a pair of Kea nodes that are in `hot-standby` 1. Determine which one of the pair of Kea servers is in `standby`. This is the server we will update first. 1. Stop the Kea 1.5.0 `standby` server (at this point the `primary` will still hand out leases, so service will be maintained). 1. Start Kea 1.6.0 on your `standby` server and wait as long as needed for lease file synchronisation. This process will end with the log message `[kea-dhcp6.commands/1353] COMMAND_RECEIVED Received command 'dhcp-enable'`. 1. Go to the 'primary' system on which Kea 1.5.0 is running. 1. Turn off the `primary` node. At this point DHCP service will be maintained by the freshly installed Kea 1.6.0 (if you had started the upgrade procedure with the `primary` node, you would have lost any leases handed out during the upgrade). 1. Start Kea 1.6.0 on your `primary` node and wait for the synchronisation process to finish (this will be much faster than in previous step). 1. At this point the Kea 1.6.0 `primary` node should have all of the leases handed out before upgrading as well as all of the leases handed out by the Kea instance configured in `standby` mode that we upgraded first. 1. You're finished - the Kea HA setup is upgraded to 1.6.0 #### Upgrading a pair of Kea nodes that are `load-balancing` 1. This process is easier to perform because it doesn't matter which server is upgraded first. 1. Choose the server to be upgraded first. 1. Stop Kea 1.5.0 and start Kea 1.6.0 1. Wait until lease synchronisation is finished 1. Go to the other Kea 1.5.0 node 1. Stop it and start Kea 1.6.0 1. Wait until lease synchronisation is finished (it will be much faster than in previous step due to `lease6-bulk-apply` command) 1. You're finished - the Kea HA setup is upgraded to 1.6.0 ### Upgrading an HA pair from Kea 1.4.0-P1 Unfortunately upgrading from 1.4.0-P1 requires turning off the DHCP service completely and manually moving the lease files to a new location. Kea 1.5.0 and 1.6.0 have a synchronisation process that is incompatible with Kea 1.4.0-P1. The procedure is exactly the same for the `load-balancing` and `hot-standby` HA types. Please make sure that Kea 1.6.0 has been installed and configuration files have been prepared (taking into account all the changes described above) **BEFORE** you start this procedure; you don't want to encounter any problems with the system while part of your DHCP HA provisioning is disabled/removed during the upgrade. #### Upgrading a `hot-standby` setup 1. Turn off the Kea 1.4.0-P1 `standby` server. 1. Turn off the Kea 1.4.0-P1 `primary` server. 1. Copy all `kea-leases6.csv*` files from the working directory for Kea 1.4.0-P1 to the new directory for Kea 1.6.0 1. Start the Kea 1.6.0 `primary` server, it will detect that lease file is an older version, and will issue this message: ``` HCPSRV_MEMFILE_NEEDS_UPGRADING version of lease file: /var/lib/kea/kea-leases6.csv schema is earlier than version 3.1 DHCPSRV_MEMFILE_CONVERTING_LEASE_FILES running LFC now to convert lease files to the current schema: 2.1 ``` 5. Start the Kea 1.6.0 `standby` server. Note that we will not move the lease files for this one because it will synchronise leases automatically with the `primary` server. 6. When the synchronisation is complete, the upgrade to the newer Kea version will be finished. #### Upgrading a `load-balance` setup 1. Turn off both Kea 1.4.0-P1 servers. 1. Copy all `kea-leases6.csv*` files from the working directory for Kea 1.4.0-P1 to the new directory for Kea 1.6.0 1. Start one Kea 1.6.0 server. It will detect that lease file is an older version, and will issue this message: ``` HCPSRV_MEMFILE_NEEDS_UPGRADING version of lease file: /var/lib/kea/kea-leases6.csv schema is earlier than version 3.1 DHCPSRV_MEMFILE_CONVERTING_LEASE_FILES running LFC now to convert lease files to the current schema: 2.1 ``` 5. Start the second Kea 1.6.0 server. Note that we will not move the lease files for this one because it will synchronise leases automatically with the first server. 6. When the synchronisation is complete, the upgrade to the newer Kea version will be finished. Note: the upgrade from Kea 1.4.0-P1 to Kea 1.5.0-P1 is exactly the same as for Kea 1.4.0-P1 to Kea 1.6.0. We recommend going straight to Kea 1.6.0.