# Installation

## Packages

Some operating systems or software package vendors may provide ready-to-use, pre-built software packages for Kea. Installing a pre-built package means you do not need to install build-only prerequisites and do not need to make the software.

FreeBSD ports, NetBSD pkgsrc, and Debian testing package collections provide all the prerequisite packages.

## Install Hierarchy

The following is the directory layout of the complete Kea installation (all directories paths are relative to the installation directory):

- `bin/` &mdash; general tools and diagnostic clients.

- `etc/bind10/` &mdash; configuration files.

- `lib/` &mdash; libraries and python modules.

- `libexec/bind10/` &mdash; executables that a user wouldn't normally run directly and are not run independently. These are the BIND 10 and Kea modules which are daemons started by the `b10-init` master process.

- `sbin/` &mdash; commands used by the system administrator.

- `share/bind10/` &mdash; configuration specifications.

- `share/doc/bind10/` &mdash; this guide and other supplementary documentation.

- `share/man/` &mdash; manual pages (online documentation).

- `var/bind10/` &mdash; data source and configuration databases.

## Building Requirements

In addition to the run-time requirements (listed in ), building Kea from source code requires various development include headers and program development tools.

Some operating systems have split their distribution packages into a run-time and a development package. You will need to install the development package versions, which include header files and libraries, to build Kea from the source code.

Building from source code requires the following software installed on the system:

- Boost build-time headers (). At least Boost version 1.35 is required.

- Botan (at least version 1.8).

- log4cplus (at least version 1.0.3) development include headers.

- A C++ compiler and standard development headers. Kea builds have been tested with GCC g++ 3.4.3, 4.1.2, 4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.

- The development tools "make" and "pkg-config".

Visit the user-contributed wiki at for system-specific installation tips.

## Installation from Source

Kea is open source software written in C++ (some components of the BIND 10 framework are written in Python). It is freely available in source code form from ISC as a downloadable tar file or via Kea Git code revision control service. (It may also be available in pre-compiled ready-to-use packages from operating system vendors.)

### Download Tar File

Kea 0.8 is available as a part of BIND10 1.2 release, which is a final release of BIND10 from ISC. This release can be downloaded from: . The upcoming Kea 0.9 and all following releases will be shipped as a stand-alone tarball.

### Retrieve from Git

Downloading this "bleeding edge" code is recommended only for developers or advanced users. Using development code in a production environment is not recommended.

When building from source code retrieved via Git, additional software will be required: automake (v1.11 or later), libtoolize, and autoconf (2.59 or later). These may need to be installed.

The latest development code (together with temporary experiments and un-reviewed code) is available via the Kea code revision control system. This is powered by Git and all the Kea development is public. The leading development is done in the master branch.

The code can be checked out from `git://git.kea.isc.org/kea`:

    $ git clone git://git.kea.isc.org/kea

The code checked out from the git repository doesn't include the generated configure script, Makefile.in files, nor their related build files. They can be created by running `autoreconf` with the `--install` switch. This will run `autoconf`, `aclocal`, `libtoolize`, `autoheader`, `automake`, and related commands.

### Configure before the build

Kea uses the GNU Build System to discover build environment details. To generate the makefiles using the defaults, simply run:

    $ ./configure

Run `./configure` with the `--help` switch to view the different options. Some commonly-used options are:

--prefix

  Define the installation location (the default is `/usr/local`).

--with-boost-include

  Define the path to find the Boost headers.

--with-pythonpath

  Define the path to Python 3.x if it is not in the standard execution path. Python 3.x is mandatory for Kea 0.8, but will not be required for the upcoming Kea 0.9.

--with-gtest

  Enable the building of the C++ Unit Tests using the Google Test framework. Optionally this can define the path to the gtest header files and library. (If the framework is not already installed on your system, it can be downloaded from .)

--with-openssl

  Replace Botan by OpenSSL for the crypto library. The default is to try to find a working Botan then OpenSSL only if Botan is not found.

--without-werror

  Disable the default use of the `-Werror` compiler flag so that compiler warnings do not result in build failures.

For additional instructions concerning the building and installation of Kea for various databases, see . For additional instructions concerning configuration backends, see .

For example, the following command configures Kea to find the Boost headers in /usr/pkg/include, specifies that PostgreSQL support should be enabled, and sets the installation location to /opt/kea:

    $ ./configure \
          --with-boost-include=/usr/pkg/include \
          --with-dhcp-pgsql=/usr/local/bin/pg_config \
          --prefix=/opt/kea

If the configure fails, it may be due to missing or old dependencies.

### Build

After the configure step is complete, build the executables from the C++ code and prepare the Python scripts by running the command:

    $ make

### Install

To install the Kea executables, support files, and documentation, issue the command:

    $ make install

Do not use any form of parallel or job server options (such as GNU make's `-j` option) when performing this step: doing so may cause errors.

The install step may require superuser privileges.

If required, run `ldconfig` as root with `/usr/local/lib` (or with ${prefix}/lib if configured with --prefix) in `/etc/ld.so.conf` (or the relevant linker cache configuration file for your OS):

    $ ldconfig

If you do not run `ldconfig` where it is required, you may see errors like the following:

    	      program: error while loading shared libraries: libkea-something.so.1:
    	      cannot open shared object file: No such file or directory

## Selecting the Configuration Backend

Kea 0.9 introduces configuration backends that are switchable during compilation phase. The backend is chosen using the --with-kea-config switch when running the configure script. It currently supports two values: BIND10 and JSON. This is currently only supported by DHCPv6 component.

BIND10

  BIND10 (which is the default value as of April 2014) means that Kea6 is linked with the BIND10 configuration backend that connects to the BIND10 framework and in general works exactly the same as Kea 0.8 and earlier versions. The benefits of that backend are uniform integration with BIND10 framework, easy on-line reconfiguration using bindctl, available RESTful API. On the other hand, it requires the whole heavy BIND10 framework that requires Python3 to be present. That backend is likely to go away with the release of Kea 0.9.

JSON

  JSON is a new configuration backend that causes Kea to read JSON configuration file from disk. It does not require any framework and thus is considered more lightweight. It will allow dynamic on-line reconfiguration, but will lack remote capabilities (i.e. no RESTful API). This configuration backend is expected to be the default for upcoming Kea 0.9.

## DHCP Database Installation and Configuration

Kea stores its leases in a lease database. The software has been written in a way that makes it possible to choose which database product should be used to store the lease information. At present, Kea supports three database backends: MySQL, PostgreSQL and Memfile. To limit external dependencies, both MySQL and PostgreSQL support are disabled by default and only Memfile (which is implemented in pure C++) is available. Support for a given database backend must be explicitly included when Kea is built. This section covers the building of Kea with MySQL and/or PostgreSQL and the creation of the lease database.

### Building with MySQL Support

Install MySQL according to the instructions for your system. The client development libraries must be installed.

Build and install Kea as described in , with the following modification: to enable the MySQL database code, at the "configure" step (see ), specify the location of the MySQL configuration program "mysql_config" with the "--with-dhcp-mysql" switch, i.e.

    ./configure [other-options] --with-dhcp-mysql

...if MySQL was installed in the default location, or:

    ./configure [other-options] --with-dhcp-mysql=path-to-mysql_config

...if not.

### Create the MySQL Database and the Kea User

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 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-bind10/share/bind10/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
    $

### Building with PostgreSQL support

Install PostgreSQL according to the instructions for your system. The client development libraries must be installed. Client development libraries are often packaged as "libpq".

Build and install Kea as described in , with the following modification: to enable the PostgreSQL database code, at the "configure" step (see ), specify the location of the PostgreSQL configuration program "pg_config" with the "--with-dhcp-pgsql" switch, i.e.

    ./configure [other-options] --with-dhcp-pgsql

...if PostgreSQL was installed in the default location, or:

    ./configure [other-options] --with-dhcp-pgsql=path-to-pg_config

...if not.

### Create PostgreSQL Database and Kea User

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-bind10/share/bind10/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.