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
|
|
|
|
|
|
|
.. _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 cpp-driver from DataStax is needed when using the ``--with-cql``
|
2019-06-06 18:25:46 +02:00
|
|
|
configuration flag to build Kea with the Cassandra database backend.
|
2021-09-22 20:30:24 +03:00
|
|
|
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.
|
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-cql``
|
2019-06-06 18:25:46 +02:00
|
|
|
Build Kea with code to allow it to store leases and host reservations
|
2021-06-24 18:53:14 +00:00
|
|
|
in a Cassandra (CQL) database. Support for Cassandra is now deprecated.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
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
|
|
|
|
2020-05-02 16:43:41 +02:00
|
|
|
- ``--with-benchmark``, ``--with-benchmark-source``
|
2019-06-06 18:25:46 +02:00
|
|
|
Enable the building of the database backend benchmarks using the
|
|
|
|
Google Benchmark framework. This option specifies the path to the
|
2020-11-14 00:00:37 +00:00
|
|
|
gtest source. (If the framework is not installed on the system, it
|
2019-06-17 17:20:36 -04:00
|
|
|
can be downloaded from https://github.com/google/benchmark.)
|
2019-06-06 18:25:46 +02:00
|
|
|
This support is experimental.
|
|
|
|
|
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
|
2019-06-17 17:20:36 -04:00
|
|
|
be used to store the lease information. Kea supports four
|
2021-09-09 15:28:58 +00:00
|
|
|
database backends: MySQL, PostgreSQL, Cassandra[1], and memfile. To limit
|
2019-06-06 18:25:46 +02:00
|
|
|
external dependencies, MySQL, PostgreSQL, and Cassandra support are
|
2019-06-26 16:03:19 -04:00
|
|
|
disabled by default and only memfile is available. Support for the
|
2019-06-06 18:25:46 +02:00
|
|
|
optional external database backend must be explicitly included when Kea
|
|
|
|
is built. This section covers the building of Kea with one of the
|
2021-09-09 15:28:58 +00:00
|
|
|
optional backends and the creation of the lease database.
|
|
|
|
|
|
|
|
[1] As of Kea 1.9.9, support for Cassandra is deprecated.
|
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.
|
|
|
|
|
|
|
|
Building with CQL (Cassandra) Support
|
|
|
|
-------------------------------------
|
|
|
|
|
2021-09-09 15:28:58 +00:00
|
|
|
As of Kea 1.9.9, support for Cassandra is deprecated. It is still
|
2021-09-10 19:34:07 +00:00
|
|
|
available in current versions, but the support will be removed in a future
|
2021-09-09 15:28:58 +00:00
|
|
|
version; new users are encouraged to choose an alternative.
|
2021-06-24 18:53:14 +00:00
|
|
|
|
2020-11-14 00:00:37 +00:00
|
|
|
Install Cassandra according to the instructions for the system. The
|
2019-06-06 18:25:46 +02:00
|
|
|
Cassandra project website contains useful pointers:
|
2019-06-17 17:20:36 -04:00
|
|
|
https://cassandra.apache.org.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2020-11-14 00:00:37 +00:00
|
|
|
If a cpp-driver package is available as binary or as source,
|
2019-06-06 18:25:46 +02:00
|
|
|
simply install or build and install the package. Then build and install
|
2019-06-20 08:37:00 -04:00
|
|
|
Kea as described in :ref:`installation`. To enable the
|
|
|
|
Cassandra (CQL) database code, at the "configure" step (see :ref:`configure`), enter:
|
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-cql=path-to-pkg-config
|
2019-06-06 18:25:46 +02:00
|
|
|
|
2021-09-09 15:28:58 +00:00
|
|
|
If ``pkg-config`` is at its standard location (and thus in the
|
2020-11-14 00:00:37 +00:00
|
|
|
shell path), the path does not need to be specified. If it does not work
|
2019-06-06 18:25:46 +02:00
|
|
|
(e.g. no pkg-config, package not available in pkg-config with the
|
2021-09-09 15:28:58 +00:00
|
|
|
cassandra name), the ``cql_config`` script in the tools/ directory
|
|
|
|
can still be used as described below.
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
Download and compile cpp-driver from DataStax. For details regarding
|
|
|
|
dependencies for building cpp-driver, see the project homepage
|
2021-09-09 15:28:58 +00:00
|
|
|
https://github.com/datastax/cpp-driver.
|
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
|
|
|
|
2020-11-20 16:54:00 +02:00
|
|
|
$ git clone https://github.com/datastax/cpp-driver.git
|
2019-06-06 18:25:46 +02:00
|
|
|
$ cd cpp-driver
|
|
|
|
$ mkdir build
|
|
|
|
$ cd build
|
|
|
|
$ cmake ..
|
|
|
|
$ make
|
|
|
|
|
2021-06-24 18:53:14 +00:00
|
|
|
Kea's cpp-driver does not include the cql_config script. A
|
2019-06-06 18:25:46 +02:00
|
|
|
cql_config script is present in the tools/ directory of the Kea sources.
|
2019-06-17 17:20:36 -04:00
|
|
|
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;
|
2020-11-14 00:00:37 +00:00
|
|
|
copy it over to cql_config_defines.sh and edit the path
|
2019-06-06 18:25:46 +02:00
|
|
|
specified in it) and change the environment variable CPP_DRIVER_PATH to
|
|
|
|
point to the directory where the cpp-driver sources are located. Make
|
2021-09-09 15:28:58 +00:00
|
|
|
sure that appropriate access rights are set on this file; it should be
|
2019-06-06 18:25:46 +02:00
|
|
|
executable by the system user building Kea.
|
|
|
|
|
2019-06-20 08:37:00 -04:00
|
|
|
Build and install Kea as described in :ref:`installation`,
|
2019-06-06 18:25:46 +02:00
|
|
|
with the following modification. To enable the Cassandra (CQL) database
|
2019-06-20 08:37:00 -04:00
|
|
|
code, at the "configure" step (see :ref:`configure`), enter:
|
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-cql=path-to-cql_config
|
2019-06-06 18:25:46 +02:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. 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-09-09 15:28:58 +00:00
|
|
|
This section lists significant features that have been or will be removed. We try to
|
|
|
|
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
|
|
|
|
|
|
|
Cassandra (CQL) Support
|
|
|
|
-----------------------
|
|
|
|
|
2021-06-24 18:55:39 +00:00
|
|
|
Cassandra is a non-relational NoSQL database. Kea added support for the CQL lease backend in
|
2021-06-24 18:53:14 +00:00
|
|
|
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.
|
2021-06-23 18:03:00 +02:00
|
|
|
|
|
|
|
The non-relational nature of Cassandra makes it exceedingly difficult to implement more complex
|
2021-09-10 19:34:07 +00:00
|
|
|
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.
|
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.
|