dist_doc_DATA = $(DOCS)
dist_html_DATA = $(HTMLDOCS) kea-guide.css
-DOCBOOK = kea-guide.xml logging.xml
+DOCBOOK = kea-guide.xml logging.xml config.xml install.xml
EXTRA_DIST = $(DOCBOOK)
DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY mdash "—" >
+]>
+ <chapter id="kea-config">
+ <title>Kea configuration</title>
+
+ <para>Depending on configuration backend chosen (see <xref
+ linkend="dhcp-config-backend"/>), configuration mechanisms are
+ different. The following sections describe details of specific configuration
+ backends. Note that only one configuration backend can be used and its
+ selection is determined during compilation time.</para>
+
+ <section id="bundy-backend">
+ <title>Bundy configuration backend</title>
+ <para>This legacy configuration backend allows Kea to use former BIND10
+ framework. That framework and this Kea configuration backend is no longer
+ supported by ISC. It is currently developed as part of Bundy project (see
+ <ulink url="http://bundy-dns.de">Bundy homepage</ulink>). See Bundy
+ project documentation regarding configuration.</para>
+ </section>
+
+ <section id="json-backend">
+ <title>JSON configuration backend</title>
+ <para>JSON is the default configuration backend and the only one supported
+ as of 0.9 release. It assumes that the servers are started from command
+ line (either directly or using a script, see TODO for details). JSON
+ backend uses certain signals to influence certain behaviors. The
+ configuration file is specified upon startup using -c parameter.</para>
+
+ <section id="json-format">
+ <title>JSON syntax</title>
+ <para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are
+ defined in extended JSON format. The basic JSON is defined in <ulink
+ url="http://tools.ietf.org/html/rfc4627">RFC 4627</ulink>. Kea
+ components use extended JSON, which extends basic format by allowing
+ bash-style comments in the file. Comment lines must have hash (#) in the
+ first column.</para>
+
+ <para>Configuration file consists of a single object (often colloquially
+ called a map) started with a curly bracket. It consists "Dhcp4",
+ "Dhcp6", "DhcpDdns" and/or "Logging" objects. It is possible to define
+ additional elements, but they will be ignored. That principle was chosen
+ to ease configuration management. For example, it is possible to define
+ Dhcp4, Dhcp6 and Logging elements in one configuration file that can be
+ used to start both DHCPv4 and DHCPv6 components. When starting, DHCPv4
+ component will use Dhcp4 object to configure itself and Logging to
+ configure logging parameters, while ignoring Dhcp6 object.</para>
+
+ <para>For example, a very simple configuration for Dhcp6 could look
+ like this:
+<screen>
+{
+
+# DHCPv6 specific configuration starts here.
+"Dhcp6": {
+
+# These are DHCPv6-specific parameters. They will be explained in later sections.
+ "interfaces": [ "eth0" ],
+
+ "preferred-lifetime": 3000,
+ "valid-lifetime": 4000,
+ "renew-timer": 1000,
+ "rebind-timer": 2000,
+
+# The following list defines subnets. Each subnet consists of at
+# least subnet and pool entries.
+ "subnet6": [{
+ "pool": [ "2001:db8:1::/80" ],
+ "subnet": "2001:db8:1::/64"
+ }]
+},
+# DHCPv6 specific configuration ends here.
+
+# Logger parameters (that could be shared among several components) start here.
+"Logging": {
+
+# These are Logger-specific parameters. They will be explained in later sections.
+ "loggers": [{
+ "name": "*",
+ "severity": "DEBUG"
+ }]
+}
+# Logger parameters end here.
+
+}
+</screen>
+ </para>
+
+ <para>
+ More examples are available in the Kea source code in the
+ <filename>doc/examples</filename> directory.
+ </para>
+
+ </section>
+
+
+ <!-- @todo Add a reference here after #3422 is done -->
+ </section>
+
+
+ </chapter>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY mdash "—" >
+]>
+
+ <chapter id="installation">
+ <title>Installation</title>
+
+ <section 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 build-only
+ prerequisites and do not need to <emphasis>make</emphasis> the software.
+ </para>
+
+ <para>
+ FreeBSD ports, NetBSD pkgsrc, and Debian <emphasis>testing</emphasis>
+ package collections provide all the prerequisite packages.
+ </para>
+ </section>
+
+ <section id="install-hierarchy">
+ <title>Install Hierarchy</title>
+ <para>
+ The following is the standard, common layout of the
+ complete Kea installation:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <filename>bin/</filename> —
+ general tools and diagnostic clients.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <!-- @todo: 0.9: update this -->
+ <filename>etc/bind10/</filename> —
+ configuration files.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <filename>lib/</filename> —
+ libraries and python modules.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <!-- @todo 0.9: update this -->
+ <filename>libexec/bind10/</filename> —
+ executables that a user wouldn't normally run directly and
+ are not run independently.
+ These are the BIND 10 and Kea modules which are daemons started by
+ the <command>b10-init</command> master process.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <filename>sbin/</filename> —
+ commands used by the system administrator.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <!-- @todo 0.9: update this -->
+ <filename>share/bind10/</filename> —
+ configuration specifications.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <!-- @todo 0.9: update this -->
+ <filename>share/doc/bind10/</filename> —
+ this guide and other supplementary documentation.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <filename>share/man/</filename> —
+ manual pages (online documentation).
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <!-- @todo 0.9: update this -->
+ <filename>var/bind10/</filename> —
+ data source and configuration databases.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section 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 source code.
+ </simpara>
+ </note>
+
+ <para>
+ Building from source code requires the Boost
+ build-time headers
+ (<ulink url="http://www.boost.org/"/>).
+ At least Boost version 1.35 is required.
+ <!-- TODO: we don't check for this version -->
+ <!-- NOTE: jreed has tested with 1.34, 1.38, and 1.41. -->
+ </para>
+
+ <para>
+ To build Kea, also install the Botan (at least version
+ 1.8) and the log4cplus (at least version 1.0.3)
+ development include headers.
+ <!-- @todo: Add OpenSSL note here once #2406 is merged -->
+ </para>
+
+<!--
+TODO
+Debian and Ubuntu:
+ libgmp3-dev and libbz2-dev required for botan too
+-->
+
+<!-- NOTE: _sqlite3 is only needed at test time; it is already listed
+as a dependency earlier -->
+
+ <para>
+ Building Kea also requires a C++ compiler and
+ standard development headers, make, and pkg-config.
+ Kea builds have been tested with GCC g++ 3.4.3, 4.1.2,
+ 4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
+ <!-- @todo update this list -->
+ </para>
+
+ <para>
+ Visit the user-contributed wiki at <ulink
+ url="http://kea.isc.org/wiki/SystemSpecificNotes" />
+ for system-specific installation tips.
+ </para>
+
+ </section>
+
+ <section id="install">
+ <title>Installation from source</title>
+ <para>
+ Kea is open source software written in C++ (some components of the
+ BIND 10 framework are written in Python).
+ It is freely available in source code form from ISC as a
+ downloadable tar file or via Kea Git code revision control
+ service. (It may also be available in pre-compiled ready-to-use
+ packages from operating system vendors.)
+ </para>
+
+ <section>
+
+ <title>Download Tar File</title>
+ <para>
+ Kea 0.8 is available as a part of BIND10 1.2 release, which is a final
+ release of BIND10 from ISC. This release can be downloaded from:
+ <ulink url="ftp://ftp.isc.org/isc/bind10/"/>. Upcoming Kea 0.9 and all
+ following releases will be shipped as a stand-alone tarball.
+ </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 using source code retrieved via Git, additional
+ software will be required: automake (v1.11 or newer),
+ libtoolize, and autoconf (2.59 or newer).
+ These may need to be installed.
+ </para>
+ </note>
+
+ <para>
+ The latest development code (and temporary experiments
+ and un-reviewed code) is available via the Kea code revision
+ control system. This is powered by Git and all the Kea
+ development is public.
+ The leading development is done in the <quote>master</quote>
+ branch.
+ </para>
+ <para>
+ The code can be checked out from
+ <filename>git://git.kea.isc.org/kea</filename>;
+ for example:
+
+ <screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput></screen>
+ </para>
+
+ <para>
+ When checking out the code from
+ the code version control system, it doesn't 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>
+
+ </section>
+
+
+ <section 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-pythonpath</term>
+ <listitem>
+ <simpara>Define the path to Python 3.x if it is not in the
+ standard execution path. Python 3.x is mandatory for Kea 0.8,
+ but is no longer required for upcoming Kea 0.9.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--with-gtest</term>
+ <listitem>
+ <simpara>Enable building the C++ Unit Tests using the
+ Google Tests framework. Optionally this can define the
+ path to the gtest header files and library.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--without-werror</term>
+ <listitem>
+ <simpara>Disable the default use of the
+ <option>-Werror</option> compiler flag so that
+ compiler warnings aren't build failures.
+ </simpara>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ <note>
+ <para>
+ For additional instructions concerning the building and installation of
+ Kea for various databases, see <xref linkend="dhcp-install-configure"/>.
+ For additional instructions concerning configuration backends, see
+ <xref linkend="dhcp-config-backend" />.
+ </para>
+ </note>
+ </para>
+ <!-- TODO: lcov -->
+
+ <para>
+ For example, the following configures it to
+ find the Boost headers, find the
+ Python interpreter, and sets the installation location:
+
+ <screen>$ <userinput>./configure \
+ --with-boost-include=/usr/pkg/include \
+ --with-dhcp-pgsql=/usr/local/bin/pg_config \
+ --prefix=/opt/kea</userinput></screen>
+ </para>
+
+ <para>
+ If the configure fails, it may be due to missing or old
+ dependencies.
+ </para>
+
+
+ </section>
+
+ <section>
+ <title>Build</title>
+ <para>
+ After the configure step is complete, to build the executables
+ from the C++ code and prepare the Python scripts, run:
+
+ <screen>$ <userinput>make</userinput></screen>
+ </para>
+ </section>
+
+ <section>
+ <title>Install</title>
+ <para>
+ To install the Kea executables, support files,
+ and documentation, run:
+ <screen>$ <userinput>make install</userinput></screen>
+ </para>
+ <para>
+ Please don't 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 ${prefix}/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 id="dhcp-config-backend">
+ <title>Selecting configuration backend</title>
+ <para>Kea 0.9 introduces configuration backends that are switchable during
+ compilation phase. There is a new parameter for configure script:
+ --with-kea-config. It currently supports two values: BIND10 and
+ JSON. This is currently only supported by DHCPv6 component.</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term>BIND10</term>
+ <listitem>
+ <simpara>BIND10 (which is the default value as of April 2014) means
+ that Kea6 is linked with the BIND10 configuration backend that
+ connects to the BIND10 framework and in general works exactly the
+ same as Kea 0.8 and earlier versions. The benefits of that backend
+ are uniform integration with BIND10 framework, easy on-line
+ reconfiguration using bindctl, available RESTful API. On the other
+ hand, it requires the whole heavy BIND10 framework that requires
+ Python3 to be present. That backend is likely to go away with the
+ release of Kea 0.9.</simpara>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>JSON</term>
+ <listitem>
+ <simpara>JSON is a new configuration backend that causes Kea to read
+ JSON configuration file from disk. It does not require any framework
+ and thus is considered more lightweight. It will allow dynamic
+ on-line reconfiguration, but will lack remote capabilities (i.e. no
+ RESTful API). This configuration backend is expected to be the
+ default for upcoming Kea 0.9.</simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ </section>
+
+ <section 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 3 database backends: MySQL,
+ PostgreSQL and Memfile. To limit external dependencies, both MySQL and PostgreSQL
+ support are disabled by default and only Memfile (which is implemented in pure C++)
+ is available. Support for a given database backend must be explicitly included when
+ Kea is built. This section covers the building of Kea with MySQL and/or PostgreSQL
+ and the creation of the lease database.
+ </para>
+ <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"/>), specify the location of the
+ MySQL configuration program "mysql_config" with the "--with-dhcp-mysql" switch,
+ i.e.
+ <screen><userinput>./configure [other-options] --with-dhcp-mysql</userinput></screen>
+ ...if MySQL was installed in the default location, or:
+ <screen><userinput>./configure [other-options] --with-dhcp-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
+ ...if not.
+ </para>
+ </section>
+ <section id="dhcp-mysql-database-create">
+ <title>Create MySQL Database and Kea User</title>
+ <para>
+ The next task is to create both the lease database and the user under which the servers will
+ access it. A number of steps are required:
+ </para>
+ <para>
+ 1. Log into MySQL as "root":
+ <screen>$ <userinput>mysql -u root -p</userinput>
+Enter password:<userinput/>
+ :<userinput/>
+mysql></screen>
+ </para>
+ <para>
+ 2. Create the database:
+ <screen>mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput></screen>
+ ... <replaceable>database-name</replaceable> is the name you have chosen for the database.
+ </para>
+ <para>
+ 3. Create the database tables:
+ <screen>mysql> <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
+mysql> <userinput>SOURCE <replaceable>path-to-bind10</replaceable>/share/bind10/dhcpdb_create.mysql</userinput></screen>
+ </para>
+ <para>
+ 4. Create the user under which BIND 10 will access the database (and give it a password), then grant it access to the database tables:
+ <screen>mysql> <userinput>CREATE USER '<replaceable>user-name</replaceable>'@'localhost' IDENTIFIED BY '<replaceable>password</replaceable>';</userinput>
+mysql> <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<replaceable>user-name</replaceable>'@'localhost';</userinput></screen>
+ </para>
+ <para>
+ 5. Exit MySQL:
+ <screen>mysql> <userinput>quit</userinput>
+Bye<userinput/>
+$</screen>
+ </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"/>), specify the location of the
+ PostgreSQL configuration program "pg_config" with the "--with-dhcp-pgsql" switch,
+ i.e.
+ <screen><userinput>./configure [other-options] --with-dhcp-pgsql</userinput></screen>
+ ...if PostgreSQL was installed in the default location, or:
+ <screen><userinput>./configure [other-options] --with-dhcp-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
+ ...if not.
+ </para>
+ </section>
+ <section id="dhcp-pgsql-database-create">
+ <title>Create PostgreSQL Database and Kea User</title>
+ <para>
+ The next task is to create both the lease database and the user under which the servers will
+ access it. A number of steps are required:
+ </para>
+ <para>
+ 1. Log into PostgreSQL as "root":
+ <screen>$ <userinput>sudo -u postgres psql postgres</userinput>
+Enter password:<userinput/>
+ :<userinput/>
+postgres=#</screen>
+ </para>
+ <para>
+ 2. Create the database:
+<screen>
+postgres=#<userinput> CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
+CREATE DATABASE
+postgres=#
+</screen>
+ ... <replaceable>database-name</replaceable> is the name you have chosen for the database.
+ </para>
+ <para>
+ 3. Create the user under which Kea will access the database (and give it a password), then grant it access to the database:
+<screen>postgres=#<userinput> CREATE USER <replaceable>user-name</replaceable> WITH PASSWORD '<replaceable>password</replaceable>';</userinput>
+CREATE ROLE
+postgres=#
+postgres=#<userinput> GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput>
+GRANT
+postgres=#
+</screen>
+ </para>
+ <para>
+ 4. Exit PostgreSQL:
+ <screen>postgres=# <userinput>\q</userinput>
+Bye<userinput/>
+$</screen>
+ </para>
+ <para>
+ 5. Create the database tables using the new user's credentials.
+ After entering the following command, you will be prompted for the new
+ user's password. When the command completes you will be returned to
+ the shell prompt. You should see output similar to following:
+<screen>$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-bind10</replaceable>/share/bind10/dhcpdb_create.pgsql</userinput>
+Password for user <replaceable>user-name</replaceable>:
+CREATE TABLE
+CREATE INDEX
+CREATE INDEX
+CREATE TABLE
+CREATE INDEX
+CREATE TABLE
+START TRANSACTION
+INSERT 0 1
+INSERT 0 1
+INSERT 0 1
+COMMIT
+CREATE TABLE
+START TRANSACTION
+INSERT 0 1
+COMMIT
+$
+</screen>
+ </para>
+ <para>
+ If instead you encounter an error such as shown below:
+ </para>
+<screen>
+psql: FATAL: no pg_hba.conf entry for host "[local]", user "<replaceable>user-name</replaceable>", database "<replaceable>database-name</replaceable>", SSL off
+</screen>
+ <para>
+ This indicates that the PostgreSQL configuration needs to be modified.
+ Kea uses password authentication when connecting to the database and must
+ have the appropriate entries added to PostgreSQL's pg_hba.conf file. This
+ file is normally located in the primary data directory for your PostgreSQL
+ server. The precise path may vary but the default location for PostgreSQL 9.3
+ on Centos 6.5 is:
+ <filename>/var/lib/pgsql/9.3/data/pg_hba.conf</filename>.
+ Assuming Kea is running on the same host as PostgreSQL, adding lines similar
+ to following should be sufficient to provide password-authenticated access to
+ Kea's database:
+ </para>
+<screen>
+local <replaceable>database-name</replaceable> <replaceable>user-name</replaceable> password
+host <replaceable>database-name</replaceable> <replaceable>user-name</replaceable> 127.0.0.1/32 password
+host <replaceable>database-name</replaceable> <replaceable>user-name</replaceable> ::1/128 password
+</screen>
+ <para>
+ Please consult your PostgreSQL user manual before making these changes as they
+ may expose your other databases that you run on the same system.
+ </para>
+ </section>
+ </section>
+
+ </chapter>
<listitem>
<para>Edit your configuration file for DHCPv4. See doc/examples/kea4
- for set of examples.
+ for a set of examples.
</para>
</listitem>
<listitem>
<para>Edit your configuration file for DHCPv6. See doc/examples/kea6
- for set of examples.
+ for a set of examples.
</para>
</listitem>
</chapter>
- <chapter id="installation">
- <title>Installation</title>
-
- <section 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 build-only
- prerequisites and do not need to <emphasis>make</emphasis> the software.
- </para>
-
- <para>
- FreeBSD ports, NetBSD pkgsrc, and Debian <emphasis>testing</emphasis>
- package collections provide all the prerequisite packages.
- </para>
- </section>
-
- <section id="install-hierarchy">
- <title>Install Hierarchy</title>
- <para>
- The following is the standard, common layout of the
- complete Kea installation:
- <itemizedlist>
- <listitem>
- <simpara>
- <filename>bin/</filename> —
- general tools and diagnostic clients.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <!-- @todo: 0.9: update this -->
- <filename>etc/bind10/</filename> —
- configuration files.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <filename>lib/</filename> —
- libraries and python modules.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <!-- @todo 0.9: update this -->
- <filename>libexec/bind10/</filename> —
- executables that a user wouldn't normally run directly and
- are not run independently.
- These are the BIND 10 and Kea modules which are daemons started by
- the <command>b10-init</command> master process.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <filename>sbin/</filename> —
- commands used by the system administrator.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <!-- @todo 0.9: update this -->
- <filename>share/bind10/</filename> —
- configuration specifications.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <!-- @todo 0.9: update this -->
- <filename>share/doc/bind10/</filename> —
- this guide and other supplementary documentation.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <filename>share/man/</filename> —
- manual pages (online documentation).
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <!-- @todo 0.9: update this -->
- <filename>var/bind10/</filename> —
- data source and configuration databases.
- </simpara>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section 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 source code.
- </simpara>
- </note>
-
- <para>
- Building from source code requires the Boost
- build-time headers
- (<ulink url="http://www.boost.org/"/>).
- At least Boost version 1.35 is required.
- <!-- TODO: we don't check for this version -->
- <!-- NOTE: jreed has tested with 1.34, 1.38, and 1.41. -->
- </para>
-
- <para>
- To build Kea, also install the Botan (at least version
- 1.8) and the log4cplus (at least version 1.0.3)
- development include headers.
- <!-- @todo: Add OpenSSL note here once #2406 is merged -->
- </para>
-
-<!--
-TODO
-Debian and Ubuntu:
- libgmp3-dev and libbz2-dev required for botan too
--->
-
-<!-- NOTE: _sqlite3 is only needed at test time; it is already listed
-as a dependency earlier -->
-
- <para>
- Building Kea also requires a C++ compiler and
- standard development headers, make, and pkg-config.
- Kea builds have been tested with GCC g++ 3.4.3, 4.1.2,
- 4.1.3, 4.2.1, 4.3.2, and 4.4.1; Clang++ 2.8; and Sun C++ 5.10.
- <!-- @todo update this list -->
- </para>
-
- <para>
- Visit the user-contributed wiki at <ulink
- url="http://kea.isc.org/wiki/SystemSpecificNotes" />
- for system-specific installation tips.
- </para>
-
- </section>
-
- <section id="install">
- <title>Installation from source</title>
- <para>
- Kea is open source software written in C++ (some components of the
- BIND 10 framework are written in Python).
- It is freely available in source code form from ISC as a
- downloadable tar file or via Kea Git code revision control
- service. (It may also be available in pre-compiled ready-to-use
- packages from operating system vendors.)
- </para>
-
- <section>
-
- <title>Download Tar File</title>
- <para>
- Kea 0.8 is available as a part of BIND10 1.2 release, which is a final
- release of BIND10 from ISC. This release can be downloaded from:
- <ulink url="ftp://ftp.isc.org/isc/bind10/"/>. Upcoming Kea 0.9 and all
- following releases will be shipped as a stand-alone tarball.
- </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 using source code retrieved via Git, additional
- software will be required: automake (v1.11 or newer),
- libtoolize, and autoconf (2.59 or newer).
- These may need to be installed.
- </para>
- </note>
-
- <para>
- The latest development code (and temporary experiments
- and un-reviewed code) is available via the Kea code revision
- control system. This is powered by Git and all the Kea
- development is public.
- The leading development is done in the <quote>master</quote>
- branch.
- </para>
- <para>
- The code can be checked out from
- <filename>git://git.kea.isc.org/kea</filename>;
- for example:
-
- <screen>$ <userinput>git clone git://git.kea.isc.org/kea</userinput></screen>
- </para>
-
- <para>
- When checking out the code from
- the code version control system, it doesn't 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>
-
- </section>
-
-
- <section 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-pythonpath</term>
- <listitem>
- <simpara>Define the path to Python 3.x if it is not in the
- standard execution path. Python 3.x is mandatory for Kea 0.8,
- but is no longer required for upcoming Kea 0.9.
- </simpara>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--with-gtest</term>
- <listitem>
- <simpara>Enable building the C++ Unit Tests using the
- Google Tests framework. Optionally this can define the
- path to the gtest header files and library.
- </simpara>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>--without-werror</term>
- <listitem>
- <simpara>Disable the default use of the
- <option>-Werror</option> compiler flag so that
- compiler warnings aren't build failures.
- </simpara>
- </listitem>
- </varlistentry>
-
- </variablelist>
- <note>
- <para>
- For additional instructions concerning the building and installation of
- Kea for various databases, see <xref linkend="dhcp-install-configure"/>.
- For additional instructions concerning configuration backends, see
- <xref linkend="dhcp-config-backend" />.
- </para>
- </note>
- </para>
- <!-- TODO: lcov -->
-
- <para>
- For example, the following configures it to
- find the Boost headers, find the
- Python interpreter, and sets the installation location:
-
- <screen>$ <userinput>./configure \
- --with-boost-include=/usr/pkg/include \
- --with-dhcp-pgsql=/usr/local/bin/pg_config \
- --prefix=/opt/kea</userinput></screen>
- </para>
-
- <para>
- If the configure fails, it may be due to missing or old
- dependencies.
- </para>
-
-
- </section>
-
- <section>
- <title>Build</title>
- <para>
- After the configure step is complete, to build the executables
- from the C++ code and prepare the Python scripts, run:
-
- <screen>$ <userinput>make</userinput></screen>
- </para>
- </section>
-
- <section>
- <title>Install</title>
- <para>
- To install the Kea executables, support files,
- and documentation, run:
- <screen>$ <userinput>make install</userinput></screen>
- </para>
- <para>
- Please don't 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 ${prefix}/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 id="dhcp-config-backend">
- <title>Selecting configuration backend</title>
- <para>Kea 0.9 introduces configuration backends that are switchable during
- compilation phase. There is a new parameter for configure script:
- --with-kea-config. It currently supports two values: BIND10 and
- JSON. This is currently only supported by DHCPv6 component.</para>
-
- <variablelist>
-
- <varlistentry>
- <term>BIND10</term>
- <listitem>
- <simpara>BIND10 (which is the default value as of April 2014) means
- that Kea6 is linked with the BIND10 configuration backend that
- connects to the BIND10 framework and in general works exactly the
- same as Kea 0.8 and earlier versions. The benefits of that backend
- are uniform integration with BIND10 framework, easy on-line
- reconfiguration using bindctl, available RESTful API. On the other
- hand, it requires the whole heavy BIND10 framework that requires
- Python3 to be present. That backend is likely to go away with the
- release of Kea 0.9.</simpara>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>JSON</term>
- <listitem>
- <simpara>JSON is a new configuration backend that causes Kea to read
- JSON configuration file from disk. It does not require any framework
- and thus is considered more lightweight. It will allow dynamic
- on-line reconfiguration, but will lack remote capabilities (i.e. no
- RESTful API). This configuration backend is expected to be the
- default for upcoming Kea 0.9.</simpara>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </section>
-
- <section 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 3 database backends: MySQL,
- PostgreSQL and Memfile. To limit external dependencies, both MySQL and PostgreSQL
- support are disabled by default and only Memfile (which is implemented in pure C++)
- is available. Support for a given database backend must be explicitly included when
- Kea is built. This section covers the building of Kea with MySQL and/or PostgreSQL
- and the creation of the lease database.
- </para>
- <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"/>), specify the location of the
- MySQL configuration program "mysql_config" with the "--with-dhcp-mysql" switch,
- i.e.
- <screen><userinput>./configure [other-options] --with-dhcp-mysql</userinput></screen>
- ...if MySQL was installed in the default location, or:
- <screen><userinput>./configure [other-options] --with-dhcp-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
- ...if not.
- </para>
- </section>
- <section id="dhcp-mysql-database-create">
- <title>Create MySQL Database and Kea User</title>
- <para>
- The next task is to create both the lease database and the user under which the servers will
- access it. A number of steps are required:
- </para>
- <para>
- 1. Log into MySQL as "root":
- <screen>$ <userinput>mysql -u root -p</userinput>
-Enter password:<userinput/>
- :<userinput/>
-mysql></screen>
- </para>
- <para>
- 2. Create the database:
- <screen>mysql> <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput></screen>
- ... <replaceable>database-name</replaceable> is the name you have chosen for the database.
- </para>
- <para>
- 3. Create the database tables:
- <screen>mysql> <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
-mysql> <userinput>SOURCE <replaceable>path-to-bind10</replaceable>/share/bind10/dhcpdb_create.mysql</userinput></screen>
- </para>
- <para>
- 4. Create the user under which BIND 10 will access the database (and give it a password), then grant it access to the database tables:
- <screen>mysql> <userinput>CREATE USER '<replaceable>user-name</replaceable>'@'localhost' IDENTIFIED BY '<replaceable>password</replaceable>';</userinput>
-mysql> <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<replaceable>user-name</replaceable>'@'localhost';</userinput></screen>
- </para>
- <para>
- 5. Exit MySQL:
- <screen>mysql> <userinput>quit</userinput>
-Bye<userinput/>
-$</screen>
- </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"/>), specify the location of the
- PostgreSQL configuration program "pg_config" with the "--with-dhcp-pgsql" switch,
- i.e.
- <screen><userinput>./configure [other-options] --with-dhcp-pgsql</userinput></screen>
- ...if PostgreSQL was installed in the default location, or:
- <screen><userinput>./configure [other-options] --with-dhcp-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
- ...if not.
- </para>
- </section>
- <section id="dhcp-pgsql-database-create">
- <title>Create PostgreSQL Database and Kea User</title>
- <para>
- The next task is to create both the lease database and the user under which the servers will
- access it. A number of steps are required:
- </para>
- <para>
- 1. Log into PostgreSQL as "root":
- <screen>$ <userinput>sudo -u postgres psql postgres</userinput>
-Enter password:<userinput/>
- :<userinput/>
-postgres=#</screen>
- </para>
- <para>
- 2. Create the database:
-<screen>
-postgres=#<userinput> CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
-CREATE DATABASE
-postgres=#
-</screen>
- ... <replaceable>database-name</replaceable> is the name you have chosen for the database.
- </para>
- <para>
- 3. Create the user under which Kea will access the database (and give it a password), then grant it access to the database:
-<screen>postgres=#<userinput> CREATE USER <replaceable>user-name</replaceable> WITH PASSWORD '<replaceable>password</replaceable>';</userinput>
-CREATE ROLE
-postgres=#
-postgres=#<userinput> GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput>
-GRANT
-postgres=#
-</screen>
- </para>
- <para>
- 4. Exit PostgreSQL:
- <screen>postgres=# <userinput>\q</userinput>
-Bye<userinput/>
-$</screen>
- </para>
- <para>
- 5. Create the database tables using the new user's credentials.
- After entering the following command, you will be prompted for the new
- user's password. When the command completes you will be returned to
- the shell prompt. You should see output similar to following:
-<screen>$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-bind10</replaceable>/share/bind10/dhcpdb_create.pgsql</userinput>
-Password for user <replaceable>user-name</replaceable>:
-CREATE TABLE
-CREATE INDEX
-CREATE INDEX
-CREATE TABLE
-CREATE INDEX
-CREATE TABLE
-START TRANSACTION
-INSERT 0 1
-INSERT 0 1
-INSERT 0 1
-COMMIT
-CREATE TABLE
-START TRANSACTION
-INSERT 0 1
-COMMIT
-$
-</screen>
- </para>
- <para>
- If instead you encounter an error such as shown below:
- </para>
-<screen>
-psql: FATAL: no pg_hba.conf entry for host "[local]", user "<replaceable>user-name</replaceable>", database "<replaceable>database-name</replaceable>", SSL off
-</screen>
- <para>
- This indicates that the PostgreSQL configuration needs to be modified.
- Kea uses password authentication when connecting to the database and must
- have the appropriate entries added to PostgreSQL's pg_hba.conf file. This
- file is normally located in the primary data directory for your PostgreSQL
- server. The precise path may vary but the default location for PostgreSQL 9.3
- on Centos 6.5 is:
- <filename>/var/lib/pgsql/9.3/data/pg_hba.conf</filename>.
- Assuming Kea is running on the same host as PostgreSQL, adding lines similar
- to following should be sufficient to provide password-authenticated access to
- Kea's database:
- </para>
-<screen>
-local <replaceable>database-name</replaceable> <replaceable>user-name</replaceable> password
-host <replaceable>database-name</replaceable> <replaceable>user-name</replaceable> 127.0.0.1/32 password
-host <replaceable>database-name</replaceable> <replaceable>user-name</replaceable> ::1/128 password
-</screen>
- <para>
- Please consult your PostgreSQL user manual before making these changes as they
- may expose your other databases that you run on the same system.
- </para>
- </section>
- </section>
-
- </chapter>
-
- <chapter id="kea-config">
- <title>Kea configuration</title>
-
- <para>Depending on configuration backend chosen (see <xref
- linkend="dhcp-config-backend"/>), configuration mechanisms are
- different. The following sections describe details of specific configuration
- backends. Note that only one configuration backend can be used and its
- selection is determined during compilation time.</para>
-
- <section id="bundy-backend">
- <title>Bundy configuration backend</title>
- <para>This legacy configuration backend allows Kea to use former BIND10
- framework. That framework and this Kea configuration backend is no longer
- supported by ISC. It is currently developed as part of Bundy project (see
- <ulink url="http://bundy-dns.de">Bundy homepage</ulink>). See Bundy
- project documentation regarding configuration.</para>
- </section>
-
- <section id="json-backend">
- <title>JSON configuration backend</title>
- <para>JSON is the default configuration backend and the only one supported
- as of 0.9 release. It assumes that the servers are started from command
- line (either directly or using a script, see TODO for details). JSON
- backend uses certain signals to influence certain behaviors. The
- configuration file is specified upon startup using -c parameter.</para>
-
- <section id="json-format">
- <title>JSON syntax</title>
- <para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are
- defined in extended JSON format. The basic JSON is defined in <ulink
- url="http://tools.ietf.org/html/rfc4627">RFC 4627</ulink>. Kea
- components use extended JSON, which extends basic format by allowing
- bash-style comments in the file. Comment lines must have hash (#) in the
- first column.</para>
-
- <para>Configuration file consists of a single object (often colloquially
- called a map) started with a curly bracket. It consists "Dhcp4",
- "Dhcp6", "DhcpDdns" and/or "Logging" objects. It is possible to define
- additional elements, but they will be ignored. That principle was chosen
- to ease configuration management. For example, it is possible to define
- Dhcp4, Dhcp6 and Logging elements in one configuration file that can be
- used to start both DHCPv4 and DHCPv6 components. When starting, DHCPv4
- component will use Dhcp4 object to configure itself and Logging to
- configure logging parameters, while ignoring Dhcp6 object.</para>
-
- <para>For example, a very simple configuration for Dhcp6 could look
- like this:
-<screen>
-{
-
-# DHCPv6 specific configuration starts here.
-"Dhcp6": {
-
-# These are DHCPv6-specific parameters. They will be explained in later sections.
- "interfaces": [ "eth0" ],
-
- "preferred-lifetime": 3000,
- "valid-lifetime": 4000,
- "renew-timer": 1000,
- "rebind-timer": 2000,
-
-# The following list defines subnets. Each subnet consists of at
-# least subnet and pool entries.
- "subnet6": [{
- "pool": [ "2001:db8:1::/80" ],
- "subnet": "2001:db8:1::/64"
- }]
-},
-# DHCPv6 specific configuration ends here.
-
-# Logger parameters (that could be shared among several components) start here.
-"Logging": {
-
-# These are Logger-specific parameters. They will be explained in later sections.
- "loggers": [{
- "name": "*",
- "severity": "DEBUG"
- }]
-}
-# Logger parameters end here.
-
-}
-</screen>
- </para>
-
- </section>
-
-
- <!-- @todo Add a reference here after #3422 is done -->
- </section>
-
-
- </chapter>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="install.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml" />
<chapter id="dhcp4">
<title>The DHCPv4 Server</title>
projects / thirdparty / kea.git / commitdiff
