3. Installation

3.1. Packages

ISC publishes native RPM, deb, and APK packages, along with the tarballs with the source code. The packages are available on Cloudsmith at https://cloudsmith.io/~isc/repos. The native packages can be downloaded and installed using the system available in a specific distribution (such as dpkg or rpm). The Kea repository can also be added to the system, making it easier to install updates. For details, please go to https://cloudsmith.io/~isc/repos, choose the repository of interest, and then click the Set Me Up button for detailed instructions.

3.2. Installation Hierarchy

The following is the directory layout of the complete Kea installation. (All directory paths are relative to the installation directory.)

  • etc/kea/ — configuration files.
  • include/ — C++ development header files.
  • lib/ — libraries.
  • lib/kea/hooks — additional hooks libraries.
  • sbin/ — server software and commands used by the system administrator.
  • share/doc/kea/ — this guide, other supplementary documentation, and examples.
  • share/kea/ — API command examples and database schema scripts.
  • share/man/ — manual pages (online documentation).
  • var/lib/kea/ — server identification and lease database files.
  • var/log/ - log files.
  • var/run/kea - PID file and logger lock file.

3.3. Build Requirements

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

Note

Some operating systems have split their distribution packages into a run-time and a development package. The development package versions, which include header files and libraries, must be installed to build Kea from the source code.

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

  • Boost C++ libraries (https://www.boost.org/). The oldest Boost version used for testing is 1.57 (although Kea may also work with older versions). The Boost system library must also be installed. Installing a header-only version of Boost is not recommended.
  • OpenSSL (at least version 1.0.2) or Botan (at least version 2). OpenSSL version 1.1.1 or later is strongly recommended.
  • log4cplus (at least version 1.0.3) development include headers.
  • A C++ compiler (with C++11 support) and standard development headers. The Kea build has been checked with GCC g++ 4.8.5 and some later versions, and Clang 800.0.38 and some later versions.
  • The development tools automake, libtool, and pkg-config.
  • The MySQL client and the client development libraries, when using the --with-mysql configuration flag to build the Kea MySQL database backend. In this case, an instance of the MySQL server running locally or on a machine reachable over a network is required. Note that running the unit tests requires a local MySQL server.
  • The PostgreSQL client and the client development libraries, when using the --with-pgsql configuration flag to build the Kea PostgreSQL database backend. In this case an instance of the PostgreSQL server running locally or on a machine reachable over a network is required. Note that running the unit tests requires a local PostgreSQL server.
  • The cpp-driver from DataStax is needed when using the --with-cql configuration flag to build Kea with the Cassandra database backend. In this case, an instance of the Cassandra server running locally or on a machine reachable over a network is required. Note that running the unit tests requires a local Cassandra server.
  • The FreeRADIUS client library is required to connect to a RADIUS server. This is specified using the --with-freeradius configuration switch.
  • Sysrepo v1.4.140 and libyang v1.0.240 are needed to connect to a Sysrepo datastore. Earlier versions are no longer supported. When compiling from sources, the configure switches that can be used are --with-libyang and --with-sysrepo without any parameters. If these dependencies were installed in custom paths, point the switches to them.
  • The MIT Kerberos 5 or Heimdal libraries are needed by Kea DDNS server to sign and verify DNS updates using GSS-TSIG. The configuration switch which enables this functionality is --with-gssapi without any parameters. If these dependencies were installed in custom paths, point the switch to them.
  • googletest (version 1.8 or later) is required when using the --with-gtest configuration option to build the unit tests.
  • The documentation generation tools Sphinx, texlive with its extensions, and Doxygen, if using the --enable-generate-docs configuration option to create the documentation. Specifically, with Fedora, python3-sphinx, texlive, and texlive-collection-latexextra are necessary; with Ubuntu, python3-sphinx, python3-sphinx-rtd-theme, and texlive-binaries are needed. If LaTeX packages are missing, Kea skips PDF generation and produces only HTML documents.

Visit ISC’s Knowledgebase at https://kb.isc.org/docs/installing-kea for system-specific installation tips.

3.4. Installation From Source

Although Kea may be available in pre-compiled, ready-to-use packages from operating system vendors, it is open source software written in C++. As such, it is freely available in source code form from ISC as a downloadable tar file. The source code can also be obtained from the Kea GitLab repository at https://gitlab.isc.org/isc-projects/kea. This section describes how to build Kea from the source code.

3.4.1. Download Tar File

The Kea release tarballs may be downloaded from: https://downloads.isc.org/isc/kea/.

3.4.2. Retrieve From Git

The latest development code is available on GitLab (see https://gitlab.isc.org/isc-projects/kea). The Kea source is public and development is done in the “master” branch.

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

Note

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

The code can be checked out from https://gitlab.isc.org/isc-projects/kea.git:

$ git clone https://gitlab.isc.org/isc-projects/kea.git

The code checked out from the git repository does not include the generated configure script or the 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.

Write access to the Kea repository is only granted to ISC staff. Developers planning to contribute to Kea should check our Contributor’s Guide. The Kea Developer’s Guide contains more information about the process, and describes the requirements for contributed code to be accepted by ISC.

3.4.3. 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-mysql Build Kea with code to allow it to store leases and host reservations in a MySQL database.
  • --with-pgsql Build Kea with code to allow it to store leases and host reservations in a PostgreSQL database.
  • --with-cql Build Kea with code to allow it to store leases and host reservations in a Cassandra (CQL) database. Support for Cassandra is now deprecated.
  • --with-log4cplus Define the path to find the Log4cplus headers and libraries. Normally this is not necessary.
  • --with-boost-include Define the path to find the Boost headers. Normally this is not necessary.
  • --with-botan-config Specify the path to the botan-config script to build with Botan for cryptographic functions. It is preferable to use OpenSSL (see below).
  • --with-openssl Use the OpenSSL cryptographic library instead of Botan. By default configure searches for a valid Botan installation; if one is not found, Kea searches for OpenSSL. Normally this is not necessary.
  • --enable-shell Build the optional kea-shell tool (more in The Kea Shell). The default is to not build it.
  • --with-site-packages Only useful when kea-shell is enabled, this switch causes the kea-shell Python packages to be installed in the specified directory. This is mostly useful for Debian-related distributions. While most systems store Python packages in ${prefix}/usr/lib/pythonX/site-packages, Debian introduced a separate directory for packages installed from DEB. Such Python packages are expected to be installed in /usr/lib/python3/dist-packages.
  • --enable-perfdhcp Build the optional perfdhcp DHCP benchmarking tool. The default is to not build it.
  • --with-freeradius Build the optional RADIUS hook. This option specifies the path to the patched version of the FreeRADIUS client. This feature is available in the subscriber-only version of Kea, and requires the subscription-only RADIUS hook.
  • --with-freeradius-dictionary Specify a non-standard location for a FreeRADIUS dictionary file, which contains a list of supported RADIUS attributes. This feature is available in the subscriber-only version of Kea, and requires the subscription-only RADIUS hook.

If the RADIUS options are not available, ensure that the RADIUS hook sources are in the premium directory and rerun autoreconf -i.

Note

For instructions concerning the installation and configuration of database backends for Kea, see DHCP Database Installation and Configuration.

There are many options that are typically not necessary for regular users. However, they may be useful for package maintainers, developers, or people who want to extend Kea code or send patches:

  • --with-gtest, --with-gtest-source Enable the building of C++ unit tests using the Google Test framework. This option specifies the path to the gtest source. (If the framework is not installed on the system, it can be downloaded from https://github.com/google/googletest.)
  • --enable-generate-docs Enable the rebuilding of Kea documentation. ISC publishes Kea documentation for each release; however, in some cases it may be desirable to rebuild it: for example, to change something in the docs, or to generate new ones from git sources that are not yet released.
  • --enable-generate-parser Enable the generation of parsers using flex or bison. Kea sources include .cc and .h parser files, pre-generated for users’ convenience. By default Kea does not use flex or bison, to avoid requiring installation of unnecessary dependencies for users. However, if anything in the parsers is changed (such as adding a new parameter), flex and bison are required to regenerate parsers. This option permits that.
  • --enable-generate-messages Enable the regeneration of messages files from their messages source files, e.g. regenerate xxx_messages.h and xxx_messages.cc from xxx_messages.mes using the Kea message compiler. By default Kea is built using these .h and .cc files from the distribution. However, if anything in a .mes file is changed (such as adding a new message), the Kea message compiler needs to be built and used. This option permits that.
  • --with-benchmark, --with-benchmark-source Enable the building of the database backend benchmarks using the Google Benchmark framework. This option specifies the path to the gtest source. (If the framework is not installed on the system, it can be downloaded from https://github.com/google/benchmark.) This support is experimental.

As an 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-pgsql=/usr/local/bin/pg_config \
      --prefix=/opt/kea

Users who have any problems with building Kea using the header-only Boost code, or who would like to use the Boost system library (assumed for the sake of this example to be located in /usr/pkg/lib), should issue these commands:

$ ./configure \
      --with-boost-libs=-lboost_system \
      --with-boost-lib-dir=/usr/pkg/lib

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

When configure succeeds, it displays a report with the parameters used to build the code. This report is saved into the file config.report and is also embedded into the executable binaries, e.g., kea-dhcp4.

3.4.4. Build

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

$ make

3.4.5. 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.

Note

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 the OS):

$ ldconfig

Note

If ldconfig is not run where required, users 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

3.4.6. Cross-Building

It is possible to cross-build Kea, i.e. to create binaries in a separate system (the build system) from the one where Kea runs (the host system).

It is outside of the scope of common administrator operations and requires some developer skills, but the Developer Guide explains how to do that using an x86_64 Linux system to build Kea for a Raspberry Pi box running Raspbian: Kea Cross-Compiling Example.

3.5. 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. Kea supports four database backends: MySQL, PostgreSQL, Cassandra[1], and memfile. To limit external dependencies, MySQL, PostgreSQL, and Cassandra support are disabled by default and only memfile is available. Support for the optional external database backend must be explicitly included when Kea is built. This section covers the building of Kea with one of the optional backends and the creation of the lease database.

[1] As of Kea 1.9.9, support for Cassandra is deprecated.

Note

When unit tests are built with Kea (i.e. the --with-gtest configuration option is specified), the databases must be manually pre-configured for the unit tests to run. The details of this configuration can be found in the Kea Developer’s Guide.

3.5.1. Building with MySQL Support

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

Build and install Kea as described in Installation, with the following modification. To enable the MySQL database code, at the “configure” step (see Configure Before the Build), the --with-mysql switch should be specified:

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

If MySQL was not installed in the default location, the location of the MySQL configuration program “mysql_config” should be included with the switch:

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

See First-Time Creation of the MySQL Database for details regarding MySQL database configuration.

3.5.2. Building with PostgreSQL support

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

Build and install Kea as described in Installation, with the following modification. To enable the PostgreSQL database code, at the “configure” step (see Configure Before the Build), the --with-pgsql switch should be specified:

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

If PostgreSQL was not installed in the default location, the location of the PostgreSQL configuration program “pg_config” should be included with the switch:

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

See First-Time Creation of the PostgreSQL Database for details regarding PostgreSQL database configuration.

3.5.3. Building with CQL (Cassandra) Support

As of Kea 1.9.9, support for Cassandra is deprecated. It is still available in current versions, but the support will be removed in a future version; new users are encouraged to choose an alternative.

Install Cassandra according to the instructions for the system. The Cassandra project website contains useful pointers: https://cassandra.apache.org.

If a cpp-driver package is available as binary or as source, simply install or build and install the package. Then build and install Kea as described in Installation. To enable the Cassandra (CQL) database code, at the “configure” step (see Configure Before the Build), enter:

$ ./configure [other-options] --with-cql=path-to-pkg-config

If pkg-config is at its standard location (and thus in the shell path), the path does not need to be specified. If it does not work (e.g. no pkg-config, package not available in pkg-config with the cassandra name), the cql_config script in the tools/ directory can still be used as described below.

Download and compile cpp-driver from DataStax. For details regarding dependencies for building cpp-driver, see the project homepage https://github.com/datastax/cpp-driver.

$ git clone https://github.com/datastax/cpp-driver.git
$ cd cpp-driver
$ mkdir build
$ cd build
$ cmake ..
$ make

Kea’s cpp-driver does not include the cql_config script. A cql_config script is present in the tools/ directory of the Kea sources. Before using it, please create a cql_config_defines.sh file in the same directory (there is an example available in cql_config_define.sh.sample; copy it over to cql_config_defines.sh and edit the path specified in it) and change the environment variable CPP_DRIVER_PATH to point to the directory where the cpp-driver sources are located. Make sure that appropriate access rights are set on this file; it should be executable by the system user building Kea.

Build and install Kea as described in Installation, with the following modification. To enable the Cassandra (CQL) database code, at the “configure” step (see Configure Before the Build), enter:

$ ./configure [other-options] --with-cql=path-to-cql_config

3.6. Hammer Building Tool

An optional building tool called Hammer was introduced with Kea 1.6.0. It is a Python 3 script that lets users automate tasks related to building Kea, such as setting up virtual machines, installing Kea dependencies, compiling Kea with various options, running unit-tests and more. This tool was created primarily for internal QA purposes at ISC and it is not included in the Kea distribution. However, it is available in the Kea git repository. This tool was developed primarily for internal purposes and ISC cannot guarantee its proper operation. If you decide to use it, please do so with care.

Note

Use of this tool is completely optional. Everything it does can be done manually.

The first-time user is strongly encouraged to look at Hammer’s built-in help:

$ ./hammer.py --help

It will list available parameters.

Hammer is able to set up various operating systems running either in LXC or in VirtualBox. For a list of supported systems, use the supported-systems command:

$ ./hammer.py supported-systems
fedora:
  - 27: lxc, virtualbox
  - 28: lxc, virtualbox
  - 29: lxc, virtualbox
centos:
  - 7: lxc, virtualbox
rhel:
  - 8: virtualbox
ubuntu:
  - 16.04: lxc, virtualbox
  - 18.04: lxc, virtualbox
  - 18.10: lxc, virtualbox
debian:
  - 8: lxc, virtualbox
  - 9: lxc, virtualbox
freebsd:
  - 11.2: virtualbox
  - 12.0: virtualbox

It is also possible to run the build locally, in the current system (if the OS is supported).

First, you must install the Hammer dependencies: Vagrant and either VirtualBox or LXC. To make life easier, Hammer can install Vagrant and the required Vagrant plugins using the command:

$ ./hammer.py ensure-hammer-deps

VirtualBox and LXC need to be installed manually.

The basic functions provided by Hammer are to prepare the build environment and perform the actual build, and to run the unit tests locally in the current system. This can be achieved by running the command:

$ ./hammer.py build -p local

The scope of the process can be defined using –with (-w) and –without (-x) options. By default the build command will build Kea with documentation, install it locally, and run unit tests.

To exclude the installation and generation of docs, type:

$ ./hammer.py build -p local -x install docs

The basic scope can be extended by: mysql, pgsql, cql, native-pkg, radius, shell, and forge.

Note

To build Kea locally, Hammer dependencies like Vagrant are not needed.

Hammer can be told to set up a new virtual machine with a specified operating system, without the build:

$ ./hammer.py prepare-system -p virtualbox -s freebsd -r 12.0

This way we can prepare a system for our own use. To get to such a system using SSH, invoke:

$ ./hammer.py ssh -p virtualbox -s freebsd -r 12.0

It is possible to speed up subsequent Hammer builds. To achieve this Hammer employs ccache. During compilation, ccache stores objects in a shared folder. In subsequent runs, instead of doing an actual compilation, ccache returns the stored earlier objects. The cache with these objects for reuse needs to be stored outside of VM or LXC. To indicate the folder, you must indicate the –ccache-dir parameter for Hammer. In the indicated folder, there are separate stored objects for each target operating system.

$ ./hammer.py build -p lxc -s ubuntu -r 18.04 --ccache-dir ~/kea-ccache

Note

ccache is currently only supported for LXC in Hammer; support for VirtualBox may be added later.

For more information check:

$ ./hammer.py --help

3.7. Running Kea From a Non-root Account on Linux

Both Kea DHCPv4 and DHCPv6 servers perform operations that in general require root access privileges. In particular, DHCPv4 opens raw sockets and both DHCPv4 and DHCPv6 open UDP sockets on privileged ports. However, with some extra system configuration, it is possible to run Kea from non-root accounts.

First, a regular user account must be created:

useradd admin

Then, change the binaries’ ownership and group to the new user. Note that the specific path may be different. Please refer to the --prefix parameter passed to the configure script:

chown -R admin /opt/kea
chgrp -R admin /opt/kea
chown -R admin /var/log/kea-dhcp4.log
chgrp -R admin /var/log/kea-dhcp4.log
chown -R admin /var/log/kea-dhcp6.log
chgrp -R admin /var/log/kea-dhcp6.log

If using systemd, modify its service file (e.g. /etc/systemd/system/kea-dhcp6.service):

User=admin
Group=admin

The most important step is to set the capabilities of the binaries. Refer to man capabilities to get more information.

setcap 'cap_net_bind_service,cap_net_raw=+ep' /opt/kea/sbin/kea-dhcp4
setcap 'cap_net_bind_service=+ep' /opt/kea/sbin/kea-dhcp6

If using systemd, also add this to the service file (e.g. /etc/systemd/system/kea-dhcp6.service):

ExecStartPre=setcap 'cap_net_bind_service=+ep' /opt/kea/sbin/kea-dhcp6

After this step is complete, the admin user should be able to run Kea. Note that the DHCPv4 server by default opens raw sockets. If the network is only using relayed traffic, Kea can be instructed to use regular UDP sockets (refer to dhcp-socket-type parameter in the Interface Configuration section) and the cap_net_raw capability can be skipped.

Note

It is possible to avoid running Kea with root privileges by instructing Kea to use non-privileged (greater than 1024) ports and redirecting traffic. This, however, only works for relayed traffic. This approach in general is considered experimental and has not been tested for deployment in production environments. Use with caution!

To use this approach, configure the server to listen on other non-privileged ports (e.g. 1547 and 1548) by running the process with the -p option in /etc/systemd/system/kea-dhcp4.service:

ExecStart=/opt/kea/sbin/kea-dhcp4 -d -c /etc/kea/kea-dhcp4.conf -p 2067

and /etc/systemd/system/kea-dhcp4.service:

ExecStart=/opt/kea/sbin/kea-dhcp6 -d -c /etc/kea/kea-dhcp6.conf -p 1547

Then configure port redirection with iptables and ip6tables for new ports (e.g. 1547 and 1548). Be sure to replace ens4 with the specific interface name.

iptables -t nat -A PREROUTING -i ens4 -p udp --dport 67 -j REDIRECT --to-port 2067
iptables -t nat -A PREROUTING -i ens4 -p udp --dport 2068 -j REDIRECT --to-port 68
ip6tables -t nat -A PREROUTING -i ens4 -p udp --dport 547 -j REDIRECT --to-port 1547
ip6tables -t nat -A PREROUTING -i ens4 -p udp --dport 1548 -j REDIRECT --to-port 548

3.8. Deprecated Features

This section lists significant features that have been or will be removed. We try to deprecate features before removing them to signal to current users to plan a migration. New users should not rely on deprecated features.

3.8.1. Cassandra (CQL) Support

Cassandra is a non-relational NoSQL database. Kea added support for the CQL lease backend in Kea 1.1.0-beta1 and the CQL host backend in 1.4.0-beta1. This feature never gained much traction with users, particularly compared to the level of interest in and deployments of the alternatives, MySQL and PostgreSQL.

The non-relational nature of Cassandra makes it exceedingly difficult to implement more complex DHCP features, such as the configuration backend. Cassandra also introduces performance degradation, is complicated to set up, and is an ongoing maintenance burden.

Cassandra support is deprecated as of Kea 1.9.9. The feature will function as before in the Kea 2.0.x and 2.1.x series, but will print a warning. The feature will be removed entirely in a future release.

3.8.2. Sysrepo 0.x

Kea versions 1.9.9 and earlier required Sysrepo 0.7.x to run, when optional support for NETCONF was enabled. Kea versions 1.9.10 and later now require Sysrepo 1.4.x and the related libyang 1.x library to run. The earlier Sysrepo versions are no longer supported. The latest Sysrepo 2.x version does not provide C++ bindings, and as such, is not usable for Kea.