2
0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-18 14:00:15 +00:00
Files
kea/doc/guide/install.xml
2018-12-13 15:59:11 +01:00

639 lines
25 KiB
XML

<!--
- Copyright (C) 2014-2018 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, You can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="installation">
<title>Installation</title>
<section xml:id="packages">
<title>Packages</title>
<para>
Some operating systems or software package vendors may provide
ready-to-use, pre-built software packages for Kea. Installing a
pre-built package means you do not need to install the software
required only to build Kea and do not need to <emphasis>make</emphasis>
the software.
</para>
</section>
<section xml:id="install-hierarchy">
<title>Installation Hierarchy</title>
<para>
The following is the directory layout of the complete Kea installation.
(All directory paths are relative to the installation directory):
<itemizedlist>
<listitem>
<simpara>
<filename>bin/</filename>
utility programs.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>etc/kea/</filename>
configuration files.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>include/</filename>
C++ development header files.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>lib/</filename>
libraries.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>lib/hooks</filename>
additional hooks libraries.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>sbin/</filename>
server software and commands used by the system administrator.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>share/kea/</filename>
configuration specifications and examples.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>share/doc/kea/</filename>
this guide, other supplementary documentation, and examples.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>share/man/</filename>
manual pages (online documentation).
</simpara>
</listitem>
<listitem>
<simpara>
<filename>var/kea/</filename>
server identification, lease databases, and log files.
</simpara>
</listitem>
</itemizedlist>
</para>
</section>
<section xml:id="build-requirements">
<title>Building Requirements</title>
<para>
In addition to the run-time requirements (listed in <xref linkend="required-software"/>), building Kea from source code requires
various development include headers and program development tools.
</para>
<note>
<simpara>
Some operating systems have split their distribution packages into
a run-time and a development package. You will need to install
the development package versions, which include header files and
libraries, to build Kea from the source code.
</simpara>
</note>
<para>
Building from source code requires the following software installed
on the system:</para>
<itemizedlist>
<listitem>
<para>Boost C++ Libraries
(<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/">http://www.boost.org/</uri>).
The oldest Boost version used for testing is 1.57 (it may work with
older versions). Boost system library is required. Building boost
header only is no longer recommended.
</para>
</listitem>
<listitem>
<para>
Botan (at least version 1.9) or OpenSSL (at least version 1.0.1).
Note that Botan version 2 or later and OpenSSL version 1.0.2 or
1.1.0 or later are strongly recommended.
</para>
</listitem>
<listitem>
<para>
log4cplus (at least version 1.0.3)
development include headers.
</para>
</listitem>
<!--
TODO
Debian and Ubuntu:
libgmp3-dev and libbz2-dev required for botan too
-->
<listitem>
<para>
A C++ compiler (with C++11 support) and standard development
headers. Kea builds have been tested with GCC g++ 4.7.2 4.7.3
4.8.2 4.8.4 4.8.5 4.9.3 4.9.4 5.3.1 5.4.0 6.3.0 6.3.1
clang-800.0.38 clang-802.0.42 clang-900.0.37
</para>
</listitem>
<listitem>
<para>
The development tools automake, libtool, pkg-config.
</para>
</listitem>
<listitem>
<para>
The MySQL client and the client development libraries, when using
the --with-mysql configuration flag to build the Kea MySQL
database backend. In this case an instance of the MySQL server
running locally or on a machine reachable over a network
is required. Note that
running the unit tests requires a local MySQL server.
</para>
</listitem>
<listitem>
<para>
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 some other machine,
reachable over the network from the machine running Kea, is
required. Note that running the unit tests requires a local
PostgreSQL server.
</para>
</listitem>
<listitem>
<para>
Cpp-driver from DataStax is needed when using the --with-cql
configuration flag to build Kea with Cassandra database backend.
In this case an instance of the Cassandra server running locally
or on some other machine, reachable over the network from the
machine running Kea, is required. Note that running the unit
tests requires a local Cassandra server.
</para>
</listitem>
<listitem>
<para>
FreeRADIUS client library when --with-freeradius configuration flag used.
</para>
</listitem>
<listitem>
<para>
Sysrepo (version 0.7.6 or later) and libyang (version 0.16-r2 or later) when
--with-sysrepo configuration flag used.
</para>
</listitem>
<listitem>
<para>
googletest (version 1.8 or later), when using the --with-gtest configuration
option to build the unit tests.
</para>
</listitem>
<listitem>
<para>
The documentation generation tools elinks, docbook-xsl, libxslt and Doxygen,
if using the --enable-generate-docs configuration option
to create the documentation.
</para>
</listitem>
</itemizedlist>
<para>
Visit ISC's Knowledgebase at
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://kb.isc.org/docs/installing-kea">https://kb.isc.org/docs/installing-kea</uri>
for system-specific installation tips.
</para>
</section>
<section xml:id="install">
<title>Installation from Source</title>
<para>
Kea is open source software written in C++. It is freely available in
source code form from ISC as a downloadable tar file. A copy of the Kea
source code repository is accessible from Gitlab (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gitlab.isc.org/isc-projects/kea">https://gitlab.isc.org/isc-projects/kea</uri>).
Kea may also be available in pre-compiled ready-to-use packages from operating system vendors.
</para>
<section>
<title>Download Tar File</title>
<para>
The Kea release tarballs may be downloaded from:
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://ftp.isc.org/isc/kea/">http://ftp.isc.org/isc/kea/</uri> (using FTP or HTTP).
</para>
</section>
<section>
<title>Retrieve from Git</title>
<para>
Downloading this "bleeding edge" code is recommended only for
developers or advanced users. Using development code in a production
environment is not recommended.
</para>
<note>
<para>
When building from source code retrieved via Git, additional
software will be required: automake (v1.11 or later),
libtoolize, and autoconf (v2.69 or later).
These may need to be installed.
</para>
</note>
<para>
The latest development code is available on Gitlab (see
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gitlab.isc.org/isc-projects/kea">https://gitlab.isc.org/isc-projects/kea</uri>). The Kea source
is public and development is done in the <quote>master</quote>
branch.
</para>
<para>
The code can be checked out from
<filename>https://gitlab.isc.org/isc-projects/kea.git</filename>:
<screen>$ <userinput>git clone https://gitlab.isc.org/isc-projects/kea.git</userinput></screen>
</para>
<para>
The code checked out from the git repository does not include the
generated configure script, Makefile.in files, nor their
related build files.
They can be created by running <command>autoreconf</command>
with the <option>--install</option> switch.
This will run <command>autoconf</command>,
<command>aclocal</command>,
<command>libtoolize</command>,
<command>autoheader</command>,
<command>automake</command>,
and related commands.
</para>
<para>
Write access to the Kea repository is only granted to ISC staff. If you
are a developer planning to contribute to Kea, please check our
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gitlab.isc.org/isc-projects/kea/wikis/contributor's-guide">Contributor's Guide</link>. The
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Kea_doc/doxygen/">Kea Developer's Guide</link> contains more information about the process, as
well as describes the requirements for contributed code to be accepted by ISC.
</para>
</section>
<section xml:id="configure">
<title>Configure Before the Build</title>
<para>
Kea uses the GNU Build System to discover build environment
details.
To generate the makefiles using the defaults, simply run:
<screen>$ <userinput>./configure</userinput></screen>
</para>
<para>
Run <command>./configure</command> with the <option>--help</option>
switch to view the different options. Some commonly-used options are:
<variablelist>
<varlistentry>
<term>--prefix</term>
<listitem>
<simpara>Define the installation location (the
default is <filename>/usr/local</filename>).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-boost-include</term>
<listitem>
<simpara>Define the path to find the Boost headers.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-botan-config</term>
<listitem>
<simpara>Specify the path to the botan-config
script to build with Botan for cryptographic functions.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-mysql</term>
<listitem>
<simpara>
Build Kea with code to allow it to store leases and
host reservations in a MySQL database.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-pgsql</term>
<listitem>
<simpara>
Build Kea with code to allow it to store leases and
host reservations in a PostgreSQL database.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-cql</term>
<listitem>
<simpara>
Build Kea with code to allow it to store leases and
host reservations in a Cassandra (CQL) database.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-gtest, --with-gtest-source</term>
<listitem>
<simpara>Enable the building of the C++ Unit Tests using the
Google Test framework. This option specifies the path to the
gtest source. (If the framework
is not installed on your system, it can be downloaded
from <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/google/googletest">https://github.com/google/googletest</uri>.)
from <ulink url="https://github.com/google/googletest"/>.)
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-benchmark, --with-benchmark-source</term>
<listitem>
<simpara>Enable the building of the database backend
benchmarks using the Google Benchmark framework. This
option specifies the path to the gtest source. (If the
framework is not installed on your system, it can be downloaded
from <ulink url="https://github.com/google/benchmark"/>.)
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-log4cplus</term>
<listitem>
<simpara>Define the path to find the Log4cplus headers
and libraries.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-openssl</term>
<listitem>
<simpara>Replace Botan by the OpenSSL the cryptographic library.
By default <command>configure</command> searches for a valid
Botan installation:
if one is not found, it searches for OpenSSL.
</simpara>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>
For instructions concerning the installation and configuration
of database backends for Kea, see <xref linkend="dhcp-install-configure"/>.
</para>
</note>
</para>
<!-- TODO: lcov -->
<para>
For example, the following command configures Kea to find the
Boost headers in /usr/pkg/include, specifies that PostgreSQL
support should be enabled, and sets the installation location
to /opt/kea:
<screen>$ <userinput>./configure \
--with-boost-include=/usr/pkg/include \
--with-pgsql=/usr/local/bin/pg_config \
--prefix=/opt/kea</userinput></screen>
</para>
<para>
If you have some problems with building Kea using the header-only
Boost code or you'd like to use the Boost system library
(assumed for the sake of this example to be located in /usr/pkg/lib):
<screen>$ <userinput>./configure \
--with-boost-libs=-lboost_system \
--with-boost-lib-dir=/usr/pkg/lib</userinput></screen>
</para>
<para>
If <command>configure</command> fails, it may be due to missing or old
dependencies.
</para>
<para>
If <command>configure</command> succeeds, it displays a report
with the parameters used to build the code. This report is saved into
the file <filename>config.report</filename> and is also embedded into
the executable binaries, e.g., <userinput>kea-dhcp4</userinput>.
</para>
</section>
<section>
<title>Build</title>
<para>
After the configure step is complete, build the executables
from the C++ code and prepare the Python scripts by running the command:
<screen>$ <userinput>make</userinput></screen>
</para>
</section>
<section>
<title>Install</title>
<para>
To install the Kea executables, support files,
and documentation, issue the command:
<screen>$ <userinput>make install</userinput></screen>
</para>
<para>
Do not use any form of parallel or job server options
(such as GNU make's <command>-j</command> option) when
performing this step: doing so may cause errors.
</para>
<note>
<para>The install step may require superuser privileges.</para>
</note>
<para>
If required, run <command>ldconfig</command> as root with
<filename>/usr/local/lib</filename> (or with <replaceable>prefix</replaceable>/lib if
configured with --prefix) in
<filename>/etc/ld.so.conf</filename> (or the relevant linker
cache configuration file for your OS):
<screen>$ <userinput>ldconfig</userinput></screen>
</para>
<note>
<para>
If you do not run <command>ldconfig</command> where it is
required, you may see errors like the following:
<screen>
program: error while loading shared libraries: libkea-something.so.1:
cannot open shared object file: No such file or directory
</screen>
</para>
</note>
</section>
<!-- @todo: tests -->
</section>
<section xml:id="dhcp-install-configure">
<title>DHCP Database Installation and Configuration</title>
<para>
Kea stores its leases in a lease database. The software has been
written in a way that makes it possible to choose which database product
should be used to store the lease information. At present, Kea supports
four database backends: MySQL, PostgreSQL, Cassandra and Memfile. To
limit external dependencies, MySQL, PostgreSQL and Cassandra support are
disabled by default and only Memfile is available. Support for the
optional external database backend must be explicitly included when Kea
is built. This section covers the building of Kea with one of the
optional backends and the creation of the lease database.
</para>
<note>
<simpara>
When unit tests are built with Kea (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
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Kea_doc/doxygen/">Kea Developer's Guide</link>.
</simpara>
</note>
<section>
<title>Building with MySQL Support</title>
<para>
Install MySQL according to the instructions for your system. The client development
libraries must be installed.
</para>
<para>
Build and install Kea as described in <xref linkend="installation"/>, with
the following modification. To enable the MySQL database code, at the
"configure" step (see <xref linkend="configure"/>), the --with-mysql switch
should be specified:
<screen><userinput>./configure [other-options] --with-mysql</userinput></screen>
If MySQL was not installed in the default location, the location of the MySQL
configuration program "mysql_config" should be included with the switch, i.e.
<screen><userinput>./configure [other-options] --with-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
</para>
<para>
See <xref linkend="mysql-database-create"/> for details regarding
MySQL database configuration.
</para>
</section>
<section>
<title>Building with PostgreSQL support</title>
<para>
Install PostgreSQL according to the instructions for your system. The client development
libraries must be installed. Client development libraries are often packaged as "libpq".
</para>
<para>
Build and install Kea as described in <xref linkend="installation"/>, with
the following modification. To enable the PostgreSQL database code, at the
"configure" step (see <xref linkend="configure"/>), the --with-pgsql switch
should be specified:
<screen><userinput>./configure [other-options] --with-pgsql</userinput></screen>
If PostgreSQL was not installed in the default location, the location of the PostgreSQL
configuration program "pg_config" should be included with the switch, i.e.
<screen><userinput>./configure [other-options] --with-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
</para>
<para>
See <xref linkend="pgsql-database-create"/> for details regarding
PostgreSQL database configuration.
</para>
</section>
<section>
<title>Building with CQL (Cassandra) support</title>
<para>
Install Cassandra according to the instructions for your system. The
Cassandra project website contains useful pointers: <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://cassandra.apache.org">http://cassandra.apache.org</uri>.
</para>
<para>
If you have a cpp-driver package available as binary or as source
simply install or build and install the package. Then build
and install Kea as described in <xref linkend="installation"/>:
To enable the Cassandra (CQL) database code, at the "configure"
step (see <xref linkend="configure"/>), do:
<screen><userinput>./configure [other-options] --with-cql=<replaceable>path-to-pkg-config</replaceable></userinput></screen>
Note if <command>pkg-config</command> is at its standard location
(and thus in the shell path) you do not need to supply its path.
If it does not work (e.g. no pkg-config, package not available in
pkg-config with the cassandra name), you can still use
the <command>cql_config</command> script in tools/ as described below.
</para>
<para>
Download and compile cpp-driver from DataStax. For details regarding
dependencies for building cpp-driver, see the project homepage
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/datastax/cpp-driver">https://github.com/datastax/cpp-driver</uri>. In June
2016, the following commands were used:
<screen>
$ <userinput>git clone https://github.com/datastax/cpp-driver</userinput>
$ <userinput>cd cpp-driver</userinput>
$ <userinput>mkdir build</userinput>
$ <userinput>cd build</userinput>
$ <userinput>cmake ..</userinput>
$ <userinput>make</userinput>
</screen>
</para>
<para>
As of June 2016, cpp-driver does not include cql_config script
yet. Work is in progress to contribute such a script to the cpp-driver
project but, until that is complete, intermediate steps need to
be conducted. A cql_config script is present in the tools/ directory
of the Kea sources. Before using it, please create a
cql_config_defines.sh in the same directory (there is an example in
cql_config_define.sh.sample available, you may copy it over to
cql_config_defines.sh and edit path specified in it) and change the
environment variable CPP_DRIVER_PATH to point to the directory, where
cpp-driver sources are located. Make sure that appropriate access
rights are set on this file. It should be executable by the system
user building Kea.
</para>
<para>
Build and install Kea as described in <xref linkend="installation"/>, with
the following modification. To enable the Cassandra (CQL) database code, at the
"configure" step (see <xref linkend="configure"/>), do:
<screen><userinput>./configure [other-options] --with-cql=<replaceable>path-to-cql_config</replaceable></userinput></screen>
</para>
</section>
</section>
</chapter>