Migrating Kea to a New MySQL Database Server

Introduction

This document describes how to migrate a Kea database from one MySQL/MariaDB server to another.

Assumptions

The following assumptions are made in this document:

• The operator has access to the database server (credentials, privileges, etc.)
• Both database servers are running MySQL or MariaDB
• The database software version(s) are the same or compatible
• The user name used by Kea to access the database is the same
• Scheduled downtime for maintenance

For best results, the same database software version on both hosts is ideal. Any differences in database server software version risk introducing incompatibilities. However, as long as the new software is sufficiently compatible with the old, it should work.

The user name Kea uses to access the database must be the same on both old and new hosts. This identity is stored in the database as the "definer" and changing it will cause errors.

This procedure is somewhat invasive and requires some downtime for Kea. The duration depends on the amount of data to transfer. An online migration may be possible using replication or other advanced features of your database software. Such scenarios are beyond the scope of this document. Consult your database administrator or vendor for assistance.

Example Names

The following names are used in examples in this document. Change them as appropriate for your environment.

General Procedure

Overview

1. Make backups of everything
2. Prepare the new database server
3. Shut down all Kea servers
4. Export the data from old database servers
5. Import the data into new database servers
6. Change database config on all Kea servers
7. Start Kea servers

The following sections explain the above steps in further detail.

Step 1: Make Backups

As with any major change, full backups of all involved resources should be made before you begin. This should include:

• The old database server and all data/tables on it
• The new database server and any data/tables already on it
• All Kea config files on all servers
• Any local Kea data files (leases, etc.) on all Kea servers

Step 2: Prepare the New Database

Most "out-of-the-box" database server configurations will need some preparation done, so you can import the Kea data.

All of the database commands in the following subsections can be run from the same database client session. In a stock MySQL installation, running the command mysql (with no arguments) as root on the database server itself will yield a client session will full privileges to the entire server. If more sophisticated MySQL security has been configured, the database client will typically need to be invoked by a database administrator.

Step 2a: Database User

As with a new install, you need to define a user that Kea will use to access the database server. For example:

CREATE USER keauser@keahost IDENTIFIED BY 'kea password';

Step 2b: Create Database

The Kea database will need to be created, so that the privileges can be configured (in step 2c). For example:

CREATE DATABASE keadb;

If needed, you can change the name of the Kea database during this process (but not the Kea database user name). If doing so, specify the new database name in the above (instead of keadb).

Step 2c: Grant Privileges

Both Kea itself, and the import process, will require full privileges on the Kea database. For example:

GRANT ALL PRIVILEGES ON keadb.* TO keauser@keahost

Step 2d: Apply Changes

Tell the database server to apply the above changes:

FLUSH PRIVILEGES;

Step 3: Shut Down Kea

Shutting down the Kea servers is strongly recommended. Otherwise, updates could come in to Kea (and the database) after the export is done. These updates would be lost when importing to the new database server. This could potentially include lease allocations, leading to IP address conflicts.

If you have multiple Kea servers, shut them all down.

Step 4: Export

The following command will export all Kea data and definitions from the old server, to a file. The use of --password alone causes the mysqldump command to prompt for the password. Note that this command is run using the same database user that Kea normally uses to access the database.

mysqldump --host=oldhost --user=keauser --password --events --routines --triggers keadb > kea.sql

Step 5: Import

If needed, copy the .sql dump file from step 4 to the new server (this may not be needed; the MySQL client can generally run over a network). Importing is then just a matter of sending the SQL output to the new server. See the example below. Again, this command is run using the same database user that Kea normally uses to access the database.

mysql --host=newhost --user=keauser --password keadb < kea.sql

If you are changing the name of the database, specify the new database name in the above (instead of keadb).

Step 6: Reconfigure Kea

Change the appropriate sections in your Kea config files.

• At the very least, you will need to change the database host name or address.
• As needed, also change the database name or password.
• If you run both dhcp4 and dhcp6 daemons, be sure to update both config files.
• If you use the database for multiple items (leases, hosts/reservations, config backend), be sure to update all sections in each config file.
• If you have multiple Kea servers, be sure to update all sections in all files on all servers.

Step 7: Restart Kea

Restart the Kea services. Check the logs to confirm each Kea process starts without trouble.