2019-07-01 14:25:43 -04:00
|
|
|
.. _installation:
|
2019-06-26 16:03:19 -04:00
|
|
|
|
2019-06-06 18:25:46 +02:00
|
|
|
************
|
|
|
|
Installation
|
|
|
|
************
|
|
|
|
|
|
|
|
Packages
|
|
|
|
========
|
|
|
|
|
2021-06-25 09:41:51 +02:00
|
|
|
ISC publishes native RPM, deb, and APK packages, along with the tarballs
|
|
|
|
with the source code. The packages are available on
|
2021-06-24 18:53:14 +00:00
|
|
|
`Cloudsmith <https://cloudsmith.io/~isc/repos/>`_ at
|
2020-11-14 00:00:37 +00:00
|
|
|
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
|
2020-03-20 17:53:08 +01:00
|
|
|
go to https://cloudsmith.io/~isc/repos, choose the repository of
|
2021-09-09 15:28:58 +00:00
|
|
|
interest, and then click the ``Set Me Up`` button for detailed
|
2020-03-20 17:53:08 +01:00
|
|
|
instructions.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2022-10-07 05:51:34 -07:00
|
|
|
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
|
2022-10-12 13:19:05 -07:00
|
|
|
Cloudsmith repository for Kea release 2.3.1 is to install the ``isc-kea``
|
2022-10-07 05:51:34 -07:00
|
|
|
metapackage. This metapackage is included on all supported distros and will
|
|
|
|
install all of the services offered by the Kea software suite.
|
|
|
|
|
|
|
|
If you would only like to install specific components offered by Kea, this
|
|
|
|
can be accomplished by installing any of the following packages:
|
|
|
|
|
|
|
|
- ``isc-kea-dhcp4`` — Kea DHCPv4 server package
|
|
|
|
|
|
|
|
- ``isc-kea-dhcp6`` — Kea DHCPv6 server package
|
|
|
|
|
|
|
|
- ``isc-kea-dhcp-ddns`` — Kea DHCP DDNS server
|
|
|
|
|
|
|
|
- ``isc-kea-ctrl-agent`` — Kea Control Agent for remote configuration
|
|
|
|
|
|
|
|
- ``isc-kea-admin`` — Kea Database administration tools
|
|
|
|
|
|
|
|
- ``isc-kea-hooks`` — Kea open-source DHCP hooks
|
|
|
|
|
|
|
|
Kea Premium hook packages are not included in the ``isc-kea-hooks`` package.
|
|
|
|
If you have access to the premium hooks, the packages will have the
|
|
|
|
``isc-kea-premium-`` prefix.
|
|
|
|
|
|
|
|
Once installed, the services can be managed through your distribution's
|
|
|
|
service manager. The services will be 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 in order to maintain compatibility in pre-existing scripts. A
|
|
|
|
systemd service alias is used to allow users to refer to them with shorter
|
|
|
|
names. In order to call ``systemctl enable`` on these services, you must
|
|
|
|
use the real service names, which are: ``isc-kea-dhcp4-server``,
|
|
|
|
``isc-kea-dhcp6-server``, ``isc-kea-dhcp-ddns-server``, and
|
|
|
|
``isc-kea-ctrl-agent``.
|
|
|
|
|
2022-10-12 13:19:05 -07:00
|
|
|
Caveats for Upgrading Kea Packages
|
|
|
|
----------------------------------
|
|
|
|
|
|
|
|
To upgrade to Kea 2.3.2 or later on Debian and Ubuntu systems, you need to
|
|
|
|
run ``apt dist-upgrade``, instead of the usual ``apt upgrade``. This is only
|
|
|
|
required to upgrade from an earlier version of Kea to a version greater than
|
|
|
|
2.3.2. Once this upgrade has been done, you can upgrade to later versions
|
|
|
|
normally using ``apt upgrade`` on Debian and Ubuntu systems.
|
|
|
|
|
|
|
|
After upgrading to Kea 2.3.2 or later, it is possible that some Kea packages
|
|
|
|
are removed from Debian and Ubuntu systems. This was an unavoidable side
|
|
|
|
effect of overhauling our distribution packaging in 2.3.1 and 2.3.2. In order
|
|
|
|
to ensure that the upgrade goes as smoothly as possible, pay attention to
|
|
|
|
which packages are being removed and installed by the upgrade transaction,
|
|
|
|
and ensure that all of the packages that your deployment requires get
|
|
|
|
reinstalled.
|
|
|
|
|
|
|
|
Specifically, there is a possibility for the following packages to be removed
|
|
|
|
during upgrade depending on which packages were originally installed:
|
2022-10-17 13:04:08 -07:00
|
|
|
|
2022-10-12 13:26:44 -07:00
|
|
|
- ``isc-kea-dhcp4``
|
2022-10-17 13:04:08 -07:00
|
|
|
|
2022-10-12 13:26:44 -07:00
|
|
|
- ``isc-kea-dhcp6``
|
2022-10-17 13:04:08 -07:00
|
|
|
|
2022-10-12 13:26:44 -07:00
|
|
|
- ``isc-kea-dhcp-ddns``
|
2022-10-17 13:04:08 -07:00
|
|
|
|
2022-10-12 13:26:44 -07:00
|
|
|
- ``isc-kea-hooks``
|
2022-10-12 13:19:05 -07:00
|
|
|
|
|
|
|
If your goal is to have the entire Kea software suite installed, it is
|
|
|
|
recommended that you simply ``apt install isc-kea`` after upgrading, which
|
2022-11-25 23:51:51 +02:00
|
|
|
will install all of the relevant subpackages that make up Kea.
|
2022-10-12 13:19:05 -07:00
|
|
|
|
|
|
|
This upgrade path hiccup is not present on RPM and Alpine systems, however
|
|
|
|
if you experience issues with upgrading past 2.3.1, please inform us on the
|
|
|
|
Kea Users mailing list, or contact customer support if you have a support
|
|
|
|
contract with ISC.
|
|
|
|
|
2019-06-06 18:25:46 +02:00
|
|
|
.. _install-hierarchy:
|
|
|
|
|
|
|
|
Installation Hierarchy
|
|
|
|
======================
|
|
|
|
|
|
|
|
The following is the directory layout of the complete Kea installation.
|
2021-09-09 15:28:58 +00:00
|
|
|
(All directory paths are relative to the installation directory.)
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
- ``etc/kea/`` — configuration files.
|
|
|
|
|
|
|
|
- ``include/`` — C++ development header files.
|
|
|
|
|
|
|
|
- ``lib/`` — libraries.
|
|
|
|
|
|
|
|
- ``lib/kea/hooks`` — additional hooks libraries.
|
|
|
|
|
2020-11-20 16:54:00 +02:00
|
|
|
- ``sbin/`` — server software and commands used by the system administrator.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2021-09-09 15:28:58 +00:00
|
|
|
- ``share/doc/kea/`` — this guide, other supplementary documentation, and examples.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2020-11-20 16:54:00 +02:00
|
|
|
- ``share/kea/`` — API command examples and database schema scripts.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
- ``share/man/`` — manual pages (online documentation).
|
|
|
|
|
2020-11-20 16:54:00 +02:00
|
|
|
- ``var/lib/kea/`` — server identification and lease database files.
|
2019-07-18 13:13:59 +02:00
|
|
|
|
|
|
|
- ``var/log/`` - log files.
|
|
|
|
|
2020-11-20 16:54:00 +02:00
|
|
|
- ``var/run/kea`` - PID file and logger lock file.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
.. _build-requirements:
|
|
|
|
|
2019-06-17 17:20:36 -04:00
|
|
|
Build Requirements
|
2020-11-20 16:54:00 +02:00
|
|
|
==================
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2021-12-13 16:00:32 +00:00
|
|
|
In addition to the runtime requirements (listed in
|
2019-06-20 08:37:00 -04:00
|
|
|
:ref:`required-software`), building Kea from source code requires
|
2019-06-06 18:25:46 +02:00
|
|
|
various development include headers and program development tools.
|
|
|
|
|
2019-07-01 14:20:05 -04:00
|
|
|
.. note::
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
Some operating systems have split their distribution packages into a
|
2021-12-13 16:00:32 +00:00
|
|
|
runtime and a development package. The
|
2019-06-06 18:25:46 +02:00
|
|
|
development package versions, which include header files and
|
2020-11-14 00:00:37 +00:00
|
|
|
libraries, must be installed to build Kea from the source code.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
Building from source code requires the following software installed on
|
|
|
|
the system:
|
|
|
|
|
2019-06-17 17:20:36 -04:00
|
|
|
- Boost C++ libraries (https://www.boost.org/). The oldest Boost version
|
2021-09-09 15:28:58 +00:00
|
|
|
used for testing is 1.57 (although Kea may also work with older
|
2019-06-06 18:25:46 +02:00
|
|
|
versions). The Boost system library must also be installed.
|
2021-09-09 15:28:58 +00:00
|
|
|
Installing a header-only version of Boost is not recommended.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2021-02-24 14:37:44 +01:00
|
|
|
- OpenSSL (at least version 1.0.2) or Botan (at least version 2).
|
2021-09-09 15:28:58 +00:00
|
|
|
OpenSSL version 1.1.1 or later is strongly recommended.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
- log4cplus (at least version 1.0.3) development include headers.
|
|
|
|
|
|
|
|
- A C++ compiler (with C++11 support) and standard development headers.
|
2019-06-17 17:20:36 -04:00
|
|
|
The Kea build has been checked with GCC g++ 4.8.5 and some later versions,
|
2019-06-06 18:25:46 +02:00
|
|
|
and Clang 800.0.38 and some later versions.
|
|
|
|
|
2019-06-17 17:20:36 -04:00
|
|
|
- The development tools automake, libtool, and pkg-config.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
- The MySQL client and the client development libraries, when using the
|
2021-09-09 15:28:58 +00:00
|
|
|
``--with-mysql`` configuration flag to build the Kea MySQL database
|
2021-09-22 20:30:24 +03:00
|
|
|
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.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2021-09-22 20:30:24 +03:00
|
|
|
- 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.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2021-09-22 20:30:24 +03:00
|
|
|
- The FreeRADIUS client library is required to connect to a RADIUS server.
|
2021-09-09 15:28:58 +00:00
|
|
|
This is specified using the ``--with-freeradius`` configuration switch.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2021-09-22 20:30:24 +03:00
|
|
|
- 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
|
2021-09-09 15:28:58 +00:00
|
|
|
sources, the configure switches that can be used are ``--with-libyang`` and
|
2021-09-22 20:30:24 +03:00
|
|
|
``--with-sysrepo`` without any parameters. If these dependencies were
|
|
|
|
installed in custom paths, point the switches to them.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2021-09-22 20:30:24 +03:00
|
|
|
- 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``
|
2019-06-06 18:25:46 +02:00
|
|
|
configuration option to build the unit tests.
|
|
|
|
|
2019-07-20 09:12:42 +02:00
|
|
|
- The documentation generation tools `Sphinx <https://www.sphinx-doc.org/>`_,
|
2021-09-09 15:28:58 +00:00
|
|
|
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
|
2020-09-25 11:37:00 +02:00
|
|
|
only HTML documents.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
Visit ISC's Knowledgebase at https://kb.isc.org/docs/installing-kea for
|
|
|
|
system-specific installation tips.
|
|
|
|
|
|
|
|
.. _install:
|
|
|
|
|
2020-11-17 17:13:45 +00:00
|
|
|
Installation From Source
|
2019-06-06 18:25:46 +02:00
|
|
|
========================
|
|
|
|
|
|
|
|
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
|
2020-11-14 00:00:37 +00:00
|
|
|
GitLab repository at https://gitlab.isc.org/isc-projects/kea. This
|
2019-06-06 18:25:46 +02:00
|
|
|
section describes how to build Kea from the source code.
|
|
|
|
|
|
|
|
Download Tar File
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
The Kea release tarballs may be downloaded from:
|
2020-11-20 16:54:00 +02:00
|
|
|
https://downloads.isc.org/isc/kea/.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2020-11-14 00:00:37 +00:00
|
|
|
Retrieve From Git
|
2019-06-06 18:25:46 +02:00
|
|
|
-----------------
|
|
|
|
|
2021-09-09 15:28:58 +00:00
|
|
|
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.
|
|
|
|
|
2019-06-06 18:25:46 +02:00
|
|
|
Downloading this "bleeding edge" code is recommended only for developers
|
|
|
|
or advanced users. Using development code in a production environment is
|
|
|
|
not recommended.
|
|
|
|
|
2019-07-01 14:20:05 -04:00
|
|
|
.. note::
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-06-17 17:20:36 -04:00
|
|
|
When building from source code retrieved via git, additional software
|
2021-09-09 15:28:58 +00:00
|
|
|
is required: automake (v1.11 or later), libtoolize, and autoconf
|
2019-06-06 18:25:46 +02:00
|
|
|
(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``:
|
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
.. code-block:: console
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
$ git clone https://gitlab.isc.org/isc-projects/kea.git
|
|
|
|
|
|
|
|
The code checked out from the git repository does not include the
|
2021-09-09 15:28:58 +00:00
|
|
|
generated configure script or the Makefile.in files, nor their related build
|
2019-06-06 18:25:46 +02:00
|
|
|
files. They can be created by running ``autoreconf`` with the
|
|
|
|
``--install`` switch. This will run ``autoconf``, ``aclocal``,
|
|
|
|
``libtoolize``, ``autoheader``, ``automake``, and related commands.
|
|
|
|
|
2020-11-14 00:00:37 +00:00
|
|
|
Write access to the Kea repository is only granted to ISC staff.
|
2020-11-17 17:13:45 +00:00
|
|
|
Developers planning to contribute to Kea should check our
|
2019-06-20 17:08:06 -04:00
|
|
|
`Contributor's
|
|
|
|
Guide <https://gitlab.isc.org/isc-projects/kea/blob/master/contributors-guide.md>`__.
|
|
|
|
The `Kea Developer's
|
2021-07-28 14:36:24 +02:00
|
|
|
Guide <https://reports.kea.isc.org/dev_guide/>`__ contains more
|
2020-11-14 00:00:37 +00:00
|
|
|
information about the process, and describes the requirements for
|
2019-06-06 18:25:46 +02:00
|
|
|
contributed code to be accepted by ISC.
|
|
|
|
|
|
|
|
.. _configure:
|
|
|
|
|
|
|
|
Configure Before the Build
|
|
|
|
--------------------------
|
|
|
|
|
|
|
|
Kea uses the GNU Build System to discover build environment details. To
|
|
|
|
generate the makefiles using the defaults, simply run:
|
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
.. code-block:: console
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
$ ./configure
|
|
|
|
|
|
|
|
Run ``./configure`` with the ``--help`` switch to view the different
|
2019-06-17 17:20:36 -04:00
|
|
|
options. Some commonly used options are:
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--prefix``
|
2019-06-06 18:25:46 +02:00
|
|
|
Define the installation location (the default is ``/usr/local``).
|
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--with-mysql``
|
2019-06-06 18:25:46 +02:00
|
|
|
Build Kea with code to allow it to store leases and host reservations
|
|
|
|
in a MySQL database.
|
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--with-pgsql``
|
2019-06-06 18:25:46 +02:00
|
|
|
Build Kea with code to allow it to store leases and host reservations
|
|
|
|
in a PostgreSQL database.
|
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--with-log4cplus``
|
2019-06-06 18:25:46 +02:00
|
|
|
Define the path to find the Log4cplus headers and libraries. Normally
|
|
|
|
this is not necessary.
|
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--with-boost-include``
|
2019-06-06 18:25:46 +02:00
|
|
|
Define the path to find the Boost headers. Normally this is not
|
|
|
|
necessary.
|
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--with-botan-config``
|
2019-06-06 18:25:46 +02:00
|
|
|
Specify the path to the botan-config script to build with Botan for
|
2019-06-17 17:20:36 -04:00
|
|
|
cryptographic functions. It is preferable to use OpenSSL (see below).
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--with-openssl``
|
2021-09-09 15:28:58 +00:00
|
|
|
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.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--enable-shell``
|
2019-06-20 08:37:00 -04:00
|
|
|
Build the optional ``kea-shell`` tool (more in :ref:`kea-shell`).
|
2019-06-06 18:25:46 +02:00
|
|
|
The default is to not build it.
|
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--with-site-packages``
|
2021-09-09 15:28:58 +00:00
|
|
|
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
|
2021-06-08 09:47:22 +00:00
|
|
|
introduced a separate directory for packages installed from DEB. Such
|
2021-09-09 15:28:58 +00:00
|
|
|
Python packages are expected to be installed in
|
2021-06-17 13:08:56 +00:00
|
|
|
``/usr/lib/python3/dist-packages``.
|
2019-08-15 16:14:21 +02:00
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--enable-perfdhcp``
|
2019-06-06 18:25:46 +02:00
|
|
|
Build the optional ``perfdhcp`` DHCP benchmarking tool. The default
|
|
|
|
is to not build it.
|
|
|
|
|
2020-08-13 11:30:28 +02:00
|
|
|
- ``--with-freeradius``
|
2020-11-12 12:08:17 +00:00
|
|
|
Build the optional ``RADIUS`` hook. This option specifies the path to the
|
2021-09-09 15:28:58 +00:00
|
|
|
patched version of the FreeRADIUS client. This feature is available in
|
|
|
|
the subscriber-only version of Kea, and requires the subscription-only RADIUS hook.
|
2020-08-13 11:30:28 +02:00
|
|
|
|
|
|
|
- ``--with-freeradius-dictionary``
|
2021-09-09 15:28:58 +00:00
|
|
|
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.
|
2020-08-13 11:30:28 +02:00
|
|
|
|
2020-11-14 00:00:37 +00:00
|
|
|
If the RADIUS options are not available, ensure that the RADIUS hook sources are in
|
2020-08-13 11:30:28 +02:00
|
|
|
the ``premium`` directory and rerun ``autoreconf -i``.
|
|
|
|
|
2019-07-01 14:20:05 -04:00
|
|
|
.. note::
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
For instructions concerning the installation and configuration of
|
2019-06-20 08:37:00 -04:00
|
|
|
database backends for Kea, see :ref:`dhcp-install-configure`.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2021-09-10 19:34:07 +00:00
|
|
|
There are many options that are typically not necessary for
|
2019-06-06 18:25:46 +02:00
|
|
|
regular users. However, they may be useful for package maintainers,
|
2019-06-17 17:20:36 -04:00
|
|
|
developers, or people who want to extend Kea code or send patches:
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--with-gtest``, ``--with-gtest-source``
|
2021-09-09 15:28:58 +00:00
|
|
|
Enable the building of C++ unit tests using the Google Test
|
2019-06-06 18:25:46 +02:00
|
|
|
framework. This option specifies the path to the gtest source. (If
|
2020-11-14 00:00:37 +00:00
|
|
|
the framework is not installed on the system, it can be downloaded
|
2019-06-17 17:20:36 -04:00
|
|
|
from https://github.com/google/googletest.)
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--enable-generate-docs``
|
2021-09-09 15:28:58 +00:00
|
|
|
Enable the rebuilding of Kea documentation. ISC publishes Kea
|
2020-11-14 00:00:37 +00:00
|
|
|
documentation for each release; however, in some cases it may be
|
|
|
|
desirable to rebuild it: for example, to change something in the
|
2021-09-09 15:28:58 +00:00
|
|
|
docs, or to generate new ones from git sources that are not yet
|
|
|
|
released.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--enable-generate-parser``
|
2021-09-09 15:28:58 +00:00
|
|
|
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
|
2019-06-06 18:25:46 +02:00
|
|
|
requiring installation of unnecessary dependencies for users.
|
2021-09-09 15:28:58 +00:00
|
|
|
However, if anything in the parsers is changed (such as adding a new
|
2020-11-14 00:00:37 +00:00
|
|
|
parameter), flex and bison are required to regenerate
|
|
|
|
parsers. This option permits that.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--enable-generate-messages``
|
2019-06-06 18:25:46 +02:00
|
|
|
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
|
2020-11-14 00:00:37 +00:00
|
|
|
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.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2021-09-09 15:28:58 +00:00
|
|
|
As an example, the following command configures Kea to find the Boost
|
2019-06-06 18:25:46 +02:00
|
|
|
headers in /usr/pkg/include, specifies that PostgreSQL support should be
|
|
|
|
enabled, and sets the installation location to /opt/kea:
|
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
.. code-block:: console
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
$ ./configure \
|
|
|
|
--with-boost-include=/usr/pkg/include \
|
|
|
|
--with-pgsql=/usr/local/bin/pg_config \
|
|
|
|
--prefix=/opt/kea
|
|
|
|
|
2020-11-14 00:00:37 +00:00
|
|
|
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:
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
.. code-block:: console
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
$ ./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.
|
|
|
|
|
2021-09-09 15:28:58 +00:00
|
|
|
When ``configure`` succeeds, it displays a report with the parameters used
|
2019-06-06 18:25:46 +02:00
|
|
|
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``.
|
|
|
|
|
|
|
|
Build
|
|
|
|
-----
|
|
|
|
|
|
|
|
After the configure step is complete, build the executables from the C++
|
|
|
|
code and prepare the Python scripts by running the command:
|
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
.. code-block:: console
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
$ make
|
|
|
|
|
|
|
|
Install
|
|
|
|
-------
|
|
|
|
|
|
|
|
To install the Kea executables, support files, and documentation, issue
|
|
|
|
the command:
|
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
.. code-block:: console
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
$ 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.
|
|
|
|
|
2019-07-01 14:20:05 -04:00
|
|
|
.. note::
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
The install step may require superuser privileges.
|
|
|
|
|
|
|
|
If required, run ``ldconfig`` as root with ``/usr/local/lib`` (or with
|
2021-09-09 15:28:58 +00:00
|
|
|
prefix/lib if configured with ``--prefix``) in ``/etc/ld.so.conf`` (or the
|
2020-11-14 00:00:37 +00:00
|
|
|
relevant linker cache configuration file for the OS):
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
.. code-block:: console
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
$ ldconfig
|
|
|
|
|
2019-07-01 14:20:05 -04:00
|
|
|
.. note::
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2020-11-14 00:00:37 +00:00
|
|
|
If ``ldconfig`` is not run where required, users may see
|
2019-06-06 18:25:46 +02:00
|
|
|
errors like the following:
|
|
|
|
|
|
|
|
::
|
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
program: error while loading shared libraries: libkea-something.so.1:
|
|
|
|
cannot open shared object file: No such file or directory
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
|
2020-07-16 22:22:46 +02:00
|
|
|
Cross-Building
|
|
|
|
--------------
|
|
|
|
|
2020-11-14 00:00:37 +00:00
|
|
|
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
|
2020-07-16 22:22:46 +02:00
|
|
|
(the ``host`` system).
|
|
|
|
|
|
|
|
It is outside of the scope of common administrator operations and requires
|
2020-11-17 17:13:45 +00:00
|
|
|
some developer skills, but the Developer Guide explains how to do that
|
2020-11-14 00:00:37 +00:00
|
|
|
using an x86_64 Linux system to build Kea for a Raspberry Pi box running
|
2020-07-16 22:22:46 +02:00
|
|
|
Raspbian: `Kea Cross-Compiling Example
|
2021-07-28 14:36:24 +02:00
|
|
|
<https://reports.kea.isc.org/dev_guide/de/d9a/crossCompile.html>`__.
|
2020-07-16 22:22:46 +02:00
|
|
|
|
2019-06-06 18:25:46 +02:00
|
|
|
.. _dhcp-install-configure:
|
|
|
|
|
|
|
|
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
|
2022-06-20 14:37:31 +02:00
|
|
|
be used to store the lease information. Kea supports three
|
2022-03-30 12:46:28 +03:00
|
|
|
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.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-07-01 14:20:05 -04:00
|
|
|
.. note::
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2021-09-09 15:28:58 +00:00
|
|
|
When unit tests are built with Kea (i.e. the ``--with-gtest`` configuration
|
2019-06-06 18:25:46 +02:00
|
|
|
option is specified), the databases must be manually pre-configured
|
|
|
|
for the unit tests to run. The details of this configuration can be
|
2019-06-20 17:08:06 -04:00
|
|
|
found in the `Kea Developer's
|
2021-07-28 14:36:24 +02:00
|
|
|
Guide <https://reports.kea.isc.org/dev_guide/>`__.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
Building with MySQL Support
|
|
|
|
---------------------------
|
|
|
|
|
2020-11-14 00:00:37 +00:00
|
|
|
Install MySQL according to the instructions for the system. The client
|
2019-06-06 18:25:46 +02:00
|
|
|
development libraries must be installed.
|
|
|
|
|
2019-06-20 08:37:00 -04:00
|
|
|
Build and install Kea as described in :ref:`installation`,
|
2021-09-22 20:30:24 +03:00
|
|
|
with the following modification. To enable the MySQL database code, at the
|
|
|
|
"configure" step (see :ref:`configure`), the ``--with-mysql`` switch should be
|
|
|
|
specified:
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
.. code-block:: console
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
$ ./configure [other-options] --with-mysql
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
If MySQL was not installed in the default location, the location of the
|
|
|
|
MySQL configuration program "mysql_config" should be included with the
|
2021-09-09 15:28:58 +00:00
|
|
|
switch:
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
.. code-block:: console
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
$ ./configure [other-options] --with-mysql=path-to-mysql_config
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-06-20 08:37:00 -04:00
|
|
|
See :ref:`mysql-database-create` for details regarding MySQL
|
2019-06-06 18:25:46 +02:00
|
|
|
database configuration.
|
|
|
|
|
|
|
|
Building with PostgreSQL support
|
|
|
|
--------------------------------
|
|
|
|
|
2020-11-14 00:00:37 +00:00
|
|
|
Install PostgreSQL according to the instructions for the system. The
|
2019-06-06 18:25:46 +02:00
|
|
|
client development libraries must be installed. Client development
|
|
|
|
libraries are often packaged as "libpq".
|
|
|
|
|
2019-06-20 08:37:00 -04:00
|
|
|
Build and install Kea as described in :ref:`installation`,
|
2021-09-22 20:30:24 +03:00
|
|
|
with the following modification. To enable the PostgreSQL database code, at the
|
|
|
|
"configure" step (see :ref:`configure`), the ``--with-pgsql`` switch should be
|
|
|
|
specified:
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
.. code-block:: console
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
$ ./configure [other-options] --with-pgsql
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
If PostgreSQL was not installed in the default location, the location of
|
|
|
|
the PostgreSQL configuration program "pg_config" should be included with
|
2021-09-09 15:28:58 +00:00
|
|
|
the switch:
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
.. code-block:: console
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-07-15 08:32:02 +02:00
|
|
|
$ ./configure [other-options] --with-pgsql=path-to-pg_config
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2019-06-20 08:37:00 -04:00
|
|
|
See :ref:`pgsql-database-create` for details regarding PostgreSQL
|
2019-06-06 18:25:46 +02:00
|
|
|
database configuration.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. include:: hammer.rst
|
2020-02-21 14:48:34 +01:00
|
|
|
|
2021-04-22 15:25:34 +02:00
|
|
|
.. _non-root:
|
|
|
|
|
2020-11-20 16:54:00 +02:00
|
|
|
Running Kea From a Non-root Account on Linux
|
|
|
|
============================================
|
2020-02-21 14:48:34 +01:00
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
useradd admin
|
|
|
|
|
2021-06-08 09:47:22 +00:00
|
|
|
Then, change the binaries' ownership and group to the new user. Note that
|
2020-11-20 16:54:00 +02:00
|
|
|
the specific path may be different. Please refer to the ``--prefix``
|
2021-09-09 15:28:58 +00:00
|
|
|
parameter passed to the configure script:
|
2020-02-21 14:48:34 +01:00
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
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
|
|
|
|
|
2020-11-14 00:00:37 +00:00
|
|
|
If using systemd, modify its service file
|
2020-02-21 14:48:34 +01:00
|
|
|
(e.g. /etc/systemd/system/kea-dhcp6.service):
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
User=admin
|
|
|
|
Group=admin
|
|
|
|
|
2021-06-08 09:47:22 +00:00
|
|
|
The most important step is to set the capabilities of the binaries. Refer to `man capabilities` to get
|
2020-02-21 14:48:34 +01:00
|
|
|
more information.
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
2021-01-22 19:06:15 +02:00
|
|
|
setcap 'cap_net_bind_service,cap_net_raw=+ep' /opt/kea/sbin/kea-dhcp4
|
2020-02-21 14:48:34 +01:00
|
|
|
setcap 'cap_net_bind_service=+ep' /opt/kea/sbin/kea-dhcp6
|
|
|
|
|
2021-09-09 15:28:58 +00:00
|
|
|
If using systemd, also add this to the service file
|
2021-01-22 19:06:15 +02:00
|
|
|
(e.g. /etc/systemd/system/kea-dhcp6.service):
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
2021-01-22 19:54:17 +02:00
|
|
|
ExecStartPre=setcap 'cap_net_bind_service=+ep' /opt/kea/sbin/kea-dhcp6
|
2021-01-22 19:06:15 +02:00
|
|
|
|
2021-09-09 15:28:58 +00:00
|
|
|
After this step is complete, the admin user should be able to run Kea. Note that the DHCPv4 server by
|
2020-11-14 00:00:37 +00:00
|
|
|
default opens raw sockets. If the network is only using relayed traffic, Kea can be instructed to
|
2020-02-21 14:48:34 +01:00
|
|
|
use regular UDP sockets (refer to ``dhcp-socket-type`` parameter in the
|
|
|
|
:ref:`dhcp4-interface-configuration` section) and the ``cap_net_raw`` capability can be skipped.
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
2021-09-09 15:28:58 +00:00
|
|
|
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!
|
2020-02-21 14:48:34 +01:00
|
|
|
|
2021-09-10 19:34:07 +00:00
|
|
|
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``:
|
2020-02-21 14:48:34 +01:00
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
ExecStart=/opt/kea/sbin/kea-dhcp4 -d -c /etc/kea/kea-dhcp4.conf -p 2067
|
|
|
|
|
|
|
|
and ``/etc/systemd/system/kea-dhcp4.service``:
|
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
ExecStart=/opt/kea/sbin/kea-dhcp6 -d -c /etc/kea/kea-dhcp6.conf -p 1547
|
|
|
|
|
2021-09-09 15:28:58 +00:00
|
|
|
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.
|
2020-02-21 14:48:34 +01:00
|
|
|
|
|
|
|
.. code-block:: console
|
|
|
|
|
|
|
|
iptables -t nat -A PREROUTING -i ens4 -p udp --dport 67 -j REDIRECT --to-port 2067
|
2020-02-24 16:10:41 +01:00
|
|
|
iptables -t nat -A PREROUTING -i ens4 -p udp --dport 2068 -j REDIRECT --to-port 68
|
2020-02-21 14:48:34 +01:00
|
|
|
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
|
2021-06-23 18:03:00 +02:00
|
|
|
|
|
|
|
.. _deprecated:
|
|
|
|
|
|
|
|
Deprecated Features
|
|
|
|
===================
|
|
|
|
|
2021-12-14 21:14:41 +02:00
|
|
|
This section lists significant features that have been or will be removed. We try to
|
2021-09-09 15:28:58 +00:00
|
|
|
deprecate features before removing them to signal
|
2021-06-24 18:53:14 +00:00
|
|
|
to current users to plan a migration. New users should not rely on deprecated features.
|
2021-06-23 18:03:00 +02:00
|
|
|
|
2021-07-22 15:49:15 +02:00
|
|
|
Sysrepo 0.x
|
|
|
|
-----------
|
|
|
|
|
2021-07-22 23:02:54 +03:00
|
|
|
Kea versions 1.9.9 and earlier required Sysrepo 0.7.x to run, when optional support for NETCONF was
|
2021-09-09 15:28:58 +00:00
|
|
|
enabled. Kea versions 1.9.10 and later now require Sysrepo 1.4.x and the related libyang 1.x library to
|
2021-07-22 23:02:54 +03:00
|
|
|
run. The earlier Sysrepo versions are no longer supported. The latest Sysrepo 2.x version does not
|
2021-09-09 15:28:58 +00:00
|
|
|
provide C++ bindings, and as such, is not usable for Kea.
|
2023-01-20 09:40:19 +01:00
|
|
|
libreload command
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
The libreload 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 upcoming 2.4 versions will produce a warning when this command
|
|
|
|
is used. It will be removed some time in 2.5 timeframe.
|