Upgrading to Kea 1.6

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, #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)

Kea 1.5.0 and earlier:

$ kea-admin lease-upgrade <your database and additional parameters>

Kea 1.6.0 and later:

$ kea-admin db-upgrade <your database and additional parameters>

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)

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 & #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.
2. Stop the Kea 1.5.0 standby server (at this point the primary will still hand out leases, so service will be maintained).
3. 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'.
4. Go to the 'primary' system on which Kea 1.5.0 is running.
5. 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).
6. 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).
7. 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.
8. 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.
2. Choose the server to be upgraded first.
3. Stop Kea 1.5.0 and start Kea 1.6.0
4. Wait until lease synchronisation is finished
5. Go to the other Kea 1.5.0 node
6. Stop it and start Kea 1.6.0
7. Wait until lease synchronisation is finished (it will be much faster than in previous step due to lease6-bulk-apply command)
8. 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.
2. Turn off the Kea 1.4.0-P1 primary server.
3. 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
4. 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: <installation_path>/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.
2. 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
3. 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: <installation_path>/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.