kea Installation
From:     https://kea.readthedocs.io/en/latest/arm/install.html


3. Installation 3.1 Packages 3.1.1 From Cloudsmith 3.1.2 Upgrade Caveats
3.2 Heirarchy 3.3 Build Requirements 3.4 Install From Source 3.4.1 Downlad Tar File
3.4.2 Retrieve From Git 3.4.3 Config Before Build 3.4.4 Build 3.4.5 Install
3.4.6 Cross Building 3.5 DB Install & Config 3.5.1 Build With Mysql 3.5.2 Build With Postgres
3.6 Hammer Building Tool 3.7 Run From Usr Acct 3.8 Deprecated Features 3.8.1 Sysrepo
3.8.2 Libreload Cmd 





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.1.1. Installation From Cloudsmith Packages

ISC provides Kea packages for Alpine, CentOS, Debian, Fedora, RHEL, and
Ubuntu. The recommended method for installing Kea on any of these systems,
from the Cloudsmith repository for Kea release 2.3.1 or later, is to
install
the isc-kea metapackage. This metapackage is included on all supported
distros and installs all of the services offered by the Kea software suite.

Specific Kea components can be installed individually, with any of the
following packages:

Kea Premium hook packages are not included in the isc-kea-hooks package.
For
ISC customers with access to the premium hooks, those packages have the isc
-kea-premium- prefix.

Once installed, the services can be managed through the distribution's
service manager. The services are named: kea-dhcp4, kea-dhcp6, kea-dhcp
-ddns, and kea-ctrl-agent.

Note
The real service names on Debian and Ubuntu follow the names of the older
packages, to maintain compatibility with pre-existing scripts. A systemd
service alias is used to allow users to refer to them with shorter names.
Calling systemctl enable on these services requires the real service names,
which are: isc-kea-dhcp4-server, isc-kea-dhcp6-server, isc-kea-dhcp-ddns
-server, and isc-kea-ctrl-agent.




3.1.2. Caveats When Upgrading Kea Packages

To upgrade to Kea 2.3.2 or later from an earlier version of Kea on Debian
and Ubuntu systems, run apt dist-upgrade instead of the usual apt upgrade.
Once this upgrade has been completed, it is possible to upgrade to later
versions normally using apt upgrade on Debian and Ubuntu systems.

Users may notice differences in the packages distributed in Kea versions
prior to 2.3.2 and those distributed with 2.3.2 and later. As a result of
an
overhaul of our package design with that release, some packages were
renamed
or removed. To ensure that upgrades go as smoothly as possible, pay
attention to which packages are being removed and installed by the upgrade
transaction, and ensure that all required packages are reinstalled.

Specifically, there is a possibility for the following packages to be
removed during the upgrade, depending on which packages were originally
installed:

To install the entire Kea software suite, simply run apt install isc-kea
after upgrading, which will install all of the relevant subpackages that
make up Kea.

This upgrade path issue does not apply to RPM and Alpine systems; however,
customers with ISC support contracts who experience difficulties with
upgrading past 2.3.1 are invited to open a ticket in their support queue.
Other users are encouraged to describe their situation on the kea-users
mailing list for best-effort support from other list members.




3.2. Installation Hierarchy

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





3.3. Build Requirements

In addition to the runtime requirements (listed in Required Software at
Runtime), 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
runtime
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:

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: htt
ps://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:


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:


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 three database backends:
MySQL,
PostgreSQL and memfile. To limit external dependencies, MySQL and
PostgreSQL
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.

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.6. Hammer Building Tool

Hammer 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. Administrators who decide to use
it should 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, the Hammer dependencies must be installed: Vagrant and either
VirtualBox or LXC. Hammer can install Vagrant and the required Vagrant
plugins using the command:

./hammer.py ensure-hammer-deps

VirtualBox and LXC must 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 the --with (-w) and --without
(-x) options. By default, the build command builds Kea with documentation,
installs it locally, and runs 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, native-pkg, radius, shell,
and forge.

Note

If building 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, a system can be prepared 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 via 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 must be stored outside of
VM
or LXC. To indicate the folder, the --ccache-dir parameter for Hammer must
be included. 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. Sysrepo 0.x or 1.x

Kea 2.3.2 introduced support for Sysrepo 2.x. Unfortunately, Sysrepo
continues to undergo major changes that are backward-incompatible, and Kea
versions 2.3.2 do not support Sysrepo earlier than versions 2.x.




3.8.2. libreload command

The libreload command was deprecated in Kea 2.3.4. The code to handle this
command is still there, but there are reports of it being buggy and not
really usable. Kea 2.3 and 2.4 versions will produce a warning when this
command is used, and it will be removed entirely sometime in the 2.5
branch.