]>

Kea stores leases in one of several supported databases. As future versions of Kea are released, the structure of those databases will change. For example, Kea currently only stores lease information: in the future, additional data - such as host reservation details - will also be stored. A given version of Kea expects a particular structure in the database. It ensures this by checking the version of the database it is using. Separate version numbers are maintained for backend databases, independent of the version of Kea itself. It is possible that the backend database version will stay the same through several Kea revisions. Likewise, it is possible that the version of backend database may go up several revisions during a Kea upgrade. Versions for each database are independent, so an increment in the MySQL database version does not imply an increment in that of PostgreSQL. Backend versions are specified in a major.minor format. The minor number is increased when there are backward compatibile changes introduced. For example, the addition of a new index. It is desirable, but not mandatory to to apply such a change; you can run on older database version if you want to. (Although, in the example given, running without the new index may be at the expense of a performance penalty.) On the other hand, the major number is increased when an incompatible change is introduced, for example an extra column is added to a table. If you try to run Kea software on a database that is too old (as signified by mismatched backend major version number), Kea will refuse to run: administrative action will be required to upgrade the database.

To manage the databases, Kea provides the kea-admin tool. It is able to initialize a new database, check its version number, perform a database upgrade, and dump lease data to a text file. 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 the lease database version number. This is not necessarily equal to the Kea version number as each backend has its own versioning scheme. lease-upgrade — Conducts a lease database upgrade. This is useful when upgrading Kea. lease-dump — Dumps the contents of the lease database (for MySQL or PostgreSQL backends) to CSV text file. The first line of the file contains the column names. This is meant to be used as a diagnostic tool that provides a portable, human-readable form of lease data. backend specifies the backend type. Currently supported types are: memfile — Lease information is stored on disk in a text file. mysql — Lease information is stored in a MySQL relational database. pgsql — Lease information is stored in a PostgreSQL relational database. Additional parameters may be needed, depending on your setup and specific operation: 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 the memfile backend. During the first run, both kea-dhcp4 and kea-dhcp6 will create an empty lease file if one is not present. Necessary disk write permission is required.

The MySQL database must be properly set up if you want Kea to store information in MySQL. This section can be safely ignored if you chose to store the data in other backends.

If you are setting the MySQL database for the first time, you need to create the database area within MySQL and set up the MySQL user ID under which Kea will access the database. This needs to be done manually: kea-admin is not able to do this for you. To create the database: Log into MySQL as "root": $ mysql -u root -p Enter password: mysql> Create the MySQL database: mysql> CREATE DATABASE database-name; (database-name is the name you have chosen for the database.) 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'; (user-name and password are the user ID and password you are using to allow Keas access to the MySQL instance. All apostrophes in the command lines above are required.) At this point, you may elect to create the database tables. (Alternatively, you can exit MySQL and create the tables using the kea-admin tool, as explained below.) To do this: mysql> CONNECT database-name; mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql (path-to-kea is the location where you installed Kea.) Exit MySQL: mysql> quit Bye $ If you elected not to create the tables in step 4, you can do so now by running the kea-admin tool: $ kea-admin lease-init mysql -u database-user -p database-password -n database-name (Do not do this if you did create the tables in step 4.) kea-admin implements rudimentary checks: it will refuse to initialize a database that contains any existing tables. If you want to start from scratch, you must remove all data manually. (This process is a manual operation on purpose to avoid possibly irretrievable mistakes by kea-admin.)

Sometimes a new Kea version may use newer database schema, so there will be a need to upgrade the existing database. This can be done using the kea-admin lease-upgrade command. To check the current version of the database, use the following command: $ kea-admin lease-version mysql -u database-user -p database-password -n database-name (See for a discussion about versioning.) If the version does not match the minimum required for the new version of Kea (as described in the release notes), the database needs to be upgraded. Before upgrading, please make sure that the database is backed up. The upgrade process does not discard any data but, depending on the nature of the changes, it may be impossible to subsequently downgrade to an earlier version. To perform an upgrade, issue the following command: $ kea-admin lease-upgrade mysql -u database-user -p database-password -n database-name

A PostgreSQL database must be set up if you want Kea to store lease and other information in PostgreSQL. This step can be safely ignored if you are using other database backends.

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: Log into PostgreSQL as "root": $ sudo -u postgres psql postgres Enter password: postgres=# Create the database: postgres=# CREATE DATABASE database-name; CREATE DATABASE postgres=# (database-name is the name you have chosen for the database.) 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=# Exit PostgreSQL: postgres=# \q Bye $ At this point you are ready to create the database tables. This can be done using the kea-admin tool as explained in the next section (recommended), or manually. To create the tables manually enter the following command. Note that PostgreSQL will prompt you to enter the new user's password you specified in Step 3. 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/scripts/pgsql/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 $ (path-to-kea is the location where you installed Kea.) 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 These edits are primarily intended as a starting point not a definitive reference on PostgreSQL administration or database security. Please consult your PostgreSQL user manual before making these changes as they may expose other databases that you run. It may be necessary to restart PostgreSQL in order for these changes to take effect.

If you elected not to create the tables manually, you can do so now by running the kea-admin tool: $ kea-admin lease-init pgsql -u database-user -p database-password -n database-name Do not do this if you already created the tables in manually. kea-admin implements rudimentary checks: it will refuse to initialize a database that contains any existing tables. If you want to start from scratch, you must remove all data manually. (This process is a manual operation on purpose to avoid possibly irretrievable mistakes by kea-admin.)

Currently, PostgreSQL only supports Kea schema version 1.0 so no upgrades are available. As upgrades become available, kea-admin will support them.

The lease expiration time is stored in the SQL database for each lease as a timestamp value. Kea developers observed that MySQL database doesn't accept timestamps beyond 2147483647 seconds (maximum signed 32-bit number) from the beginning of the epoch. At the same time, some versions of PostgreSQL do accept greater values but the value is altered when it is read back. For this reason the lease database backends put the restriction for the maximum timestamp to be stored in the database, which is equal to the maximum signed 32-bit number. This effectively means that the current Kea version can't store the leases which expiration time is later than 2147483647 seconds since the beginning of the epoch (around year 2038).