]>

Kea is able to store leases in one of several supported databases. Additional types of data, like host reservation details, will be supported in the near future. To manage those databases, a tool called kea-admin was introduced. Currently it is able to initialize new database, check its version and perform database upgrade, if needed. Kea mantains separate version numbering for its database backends. These are independent of the Kea version. It is possible that the backend revision will stay the same through several Kea revisions. Likewise, it is possible that a backend may go up several times between two Kea revisions, if there were several changes introduced that required database schema change. Versions for each backend are independent, so a bump in MySQL version does not imply bump in the Postgres version. Backend versions are specified in major.minor format. Minor number is increased when there are backward compatibile changes introduced. For example, a new index is added. It is desirable, but not mandatory to have it. You can run on older database version if you want to. On the other hand, major number is increased when there's an incompatible change introduced, for example an extra column is added. If you try to run Kea software on a database that is too old (which is signified by mismatched major backend version number), Kea will refuse to run and an administrative action will be required to upgrade the database. kea-admin takes two mandatory parameters: command and backend. Additional, non-mandatory options may be specified. Currently supported commands are: lease-init — Initializes a new lease database. Useful during first Kea installation. The database is initialized to the latest version supported by the version of the software. lease-version — Reports lease database version. This is not necessarily equal to Kea version as each backend has its own versioning scheme. lease-upgrade — Conducts lease database upgrade. This is useful when migrating between old and new Kea versions. The backend specified backend type. Currently allowed backends are: memfile, mysql and pgsql. There are additional parameters that may be needed, depending on your setup and specific operation: specify username, password and database name or the directory where specific files are located. See appropriate manual page for details (man 8 kea-admin).

There are no special initialization steps necessary for memfile backend. During the first run, both kea-dhcp4 and kea-dhcp6 will create an empty lease file, if it is not present. Necessary disk write permission is required.

MySQL database must be properly set up if you want Kea to store lease and other information in MySQL. This step can be safely skipped if you chose to store the data in other backends, like memfile or PosgreSQL.

There are two ways to initialize the database. The first one involves running kea-admin tool, which attempts to automate the process. It is convenient to use, but may not cover more complex cases. The second alternative is to run all the commands manually. When kea-admin is told to initialize the database, it assumes that the database and database user has been created. If not, please follow the necessary instructions in . To initialize new MySQL database using kea-admin, use the following command: $ kea-admin lease-init mysql -u database-user -p database-password -d database-name kea-admin has rudimentary checks implemented. It will refuse to initialize a database that has any existing tables. If you want to start from scratch, you must remove existing data manually. This process is left manual on purpose to avoid mistakes that could not be undone.

Sometime a new Kea version may use newer database schema and there may be a need to upgrade existing database. This can be done using kea-admin. It is possible to check existing database version: $ kea-admin lease-version mysql -u database-user -p database-password -d database-name See for a discussion about versioning. It may be required to run database upgrade. This process is designed to not discard any data, but depending on the nature of the changes, it may be impossible to downgrade to earlier Kea version. Please back up your database if you consider reverting to an earlier Kea version. To conduct an upgrade, the following command should be used: $ kea-admin lease-upgrade mysql -u database-user -p database-password -d database-name

This paragraph explains how to create and initialize MySQL database manually. See for a kea-admin, a tool that automates most of those steps. The first task is to create both the lease database and the user under which the servers will access it. A number of steps are required: 1. Log into MySQL as "root": $ mysql -u root -p Enter password: : mysql> 2. Create the database: mysql> CREATE DATABASE database-name; (database-name is the name you have chosen for the database.) 3. Create the database tables by running the dhcpdb_create.mysql script supplied as part of Kea: mysql> CONNECT database-name; mysql> SOURCE path-to-kea/share/kea/dhcpdb_create.mysql 4. Create the user under which Kea will access the database (and give it a password), then grant it access to the database tables: mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password'; mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost'; 5. Exit MySQL: mysql> quit Bye $

PostgreSQL database must be properly set up if you want Kea to store lease and other information in PostgreSQL. This step can be safely skipped if you chose to store the data in other backends, like memfile or MySQL.

Support for PostgreSQL in kea-admin is currently not implemented.

The next task is to create both the lease database and the user under which the servers will access it. A number of steps are required: 1. Log into PostgreSQL as "root": $ sudo -u postgres psql postgres Enter password: : postgres=# 2. Create the database: postgres=# CREATE DATABASE database-name; CREATE DATABASE postgres=# (database-name is the name you have chosen for the database.) 3. Create the user under which Kea will access the database (and give it a password), then grant it access to the database: postgres=# CREATE USER user-name WITH PASSWORD 'password'; CREATE ROLE postgres=# postgres=# GRANT ALL PRIVILEGES ON DATABASE database-name TO user-name; GRANT postgres=# 4. Exit PostgreSQL: postgres=# \q Bye $ 5. Create the database tables using the new user's credentials and the dhcpdb_create.pgsql script supplied with Kea. After entering the following command, you will be prompted for the new user's password. When the command completes you will be returned to the shell prompt. You should see output similar to following: $ psql -d database-name -U user-name -f path-to-kea/share/kea/dhcpdb_create.pgsql Password for user user-name: CREATE TABLE CREATE INDEX CREATE INDEX CREATE TABLE CREATE INDEX CREATE TABLE START TRANSACTION INSERT 0 1 INSERT 0 1 INSERT 0 1 COMMIT CREATE TABLE START TRANSACTION INSERT 0 1 COMMIT $ If instead you encounter an error like: psql: FATAL: no pg_hba.conf entry for host "[local]", user "user-name", database "database-name", SSL off ... you will need to alter the PostgreSQL configuration. Kea uses password authentication when connecting to the database and must have the appropriate entries added to PostgreSQL's pg_hba.conf file. This file is normally located in the primary data directory for your PostgreSQL server. The precise path may vary but the default location for PostgreSQL 9.3 on Centos 6.5 is: /var/lib/pgsql/9.3/data/pg_hba.conf. Assuming Kea is running on the same host as PostgreSQL, adding lines similar to following should be sufficient to provide password-authenticated access to Kea's database: local database-name user-name password host database-name user-name 127.0.0.1/32 password host database-name user-name ::1/128 password Please consult your PostgreSQL user manual before making these changes as they may expose your other databases that you run on the same system.