mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-04 16:05:17 +00:00
Code Issues Releases Wiki Activity

[4844] Editing pass over first seven chapters of the Kea guide

Browse Source
This commit is contained in:
Stephen Morris
2016-09-18 18:48:37 +01:00
parent 79d4f00ae8
commit a4ca9897d2
7 changed files with 475 additions and 486 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
doc/guide/admin.xml
View File

@@ -16,17 +16,19 @@
the several supported databases. As future versions of Kea the several supported databases. As future versions of Kea
are released, the structure of those databases will change. are released, the structure of those databases will change.
For example, Kea currently only stores lease information For example, Kea currently only stores lease information
and host reservations: in the future, additional and host reservations. Future versions of Kea will store
data - such as subnet definitions - will also be stored. additional data such as subnet definitions: the database
structure will need to be updated to accomdate the extra
information.
</para> </para>
<para> <para>
A given version of Kea expects a particular structure in A given version of Kea expects a particular structure in
the database. It ensures this by checking the version of the the database and checks for this by examining the version of
database it is using. Separate version numbers are maintained for database it is using. Separate version numbers are maintained for
backend databases, independent of the version of Kea itself. It backend databases, independent of the version of Kea itself. It
is possible that the backend database version will stay the same is possible that the backend database version will stay the same
through several Kea revisions. Likewise, it is possible that the through several Kea revisions: similarly, it is possible that the
version of backend database may go up several revisions during a version of backend database may go up several revisions during a
Kea upgrade. Versions for each database are independent, so an Kea upgrade. Versions for each database are independent, so an
increment in the MySQL database version does not imply an increment increment in the MySQL database version does not imply an increment
@@ -70,9 +72,10 @@
<listitem> <listitem>
<simpara> <simpara>
<command>lease-init</command> &mdash; <command>lease-init</command> &mdash;
Initializes a new lease database. Useful during first Initializes a new lease database. This is useful during a new
Kea installation. The database is initialized to the Kea installation. The database is initialized to the
latest version supported by the version of the software. latest version supported by the version of the software being
installed.
</simpara> </simpara>
</listitem> </listitem>
@@ -97,9 +100,10 @@
<simpara> <simpara>
<command>lease-dump</command> &mdash; <command>lease-dump</command> &mdash;
Dumps the contents of the lease database (for MySQL, PostgreSQL or Dumps the contents of the lease database (for MySQL, PostgreSQL or
CQL backends) to CSV text file. The first line of the file contains CQL backends) to a CSV (comma separated values) text file. The first
the column names. This is meant to be used as a diagnostic tool line of the file contains the column names. This is meant to be
that provides a portable, human-readable form of lease data. used as a diagnostic tool, so provides a portable, human-readable
form of the lease data.
</simpara> </simpara>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@@ -118,16 +122,14 @@
<listitem> <listitem>
<simpara> <simpara>
<command>mysql</command> &mdash; <command>mysql</command> &mdash;
Lease information is stored in a MySQL relational Lease information is stored in a MySQL relational database.
database.
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<command>pgsql</command> &mdash; <command>pgsql</command> &mdash;
Lease information is stored in a PostgreSQL relational Lease information is stored in a PostgreSQL relational database.
database.
</simpara> </simpara>
</listitem> </listitem>
@@ -142,7 +144,7 @@
Additional parameters may be needed, depending on your setup Additional parameters may be needed, depending on your setup
and specific operation: username, password and database name or and specific operation: username, password and database name or
the directory where specific files are located. See appropriate the directory where specific files are located. See the appropriate
manual page for details (<command>man 8 kea-admin</command>). manual page for details (<command>man 8 kea-admin</command>).
</para> </para>
</section> </section>
@@ -185,7 +187,7 @@
<row> <row>
<entry>Data format</entry> <entry>Data format</entry>
<entry>coma separated file</entry> <entry>CSV file</entry>
<entry>SQL RMDB</entry> <entry>SQL RMDB</entry>
<entry>SQL RMDB</entry> <entry>SQL RMDB</entry>
<entry>NoSQL database (CQL)</entry> <entry>NoSQL database (CQL)</entry>
@@ -224,14 +226,14 @@
<title>memfile</title> <title>memfile</title>
<para> <para>
Memfile backend is able to store lease information, but is not able to The memfile backend is able to store lease information, but is not able to
store host reservation details. There are no plans to add the store host reservation details: these must be stored in the configuration
reservations storage capability to memfile. Host reservations can be file. (There are no plans to add a host reservations storage capability to
defined in the configuration file. this backend.)
</para> </para>
<para> <para>
There are no special initialization steps necessary No special initialization steps are necessary
for the memfile backend. During the first run, both for the memfile backend. During the first run, both
<command>kea-dhcp4</command> and <command>kea-dhcp6</command> <command>kea-dhcp4</command> and <command>kea-dhcp6</command>
will create an empty lease file if one is not will create an empty lease file if one is not
@@ -267,17 +269,12 @@
<para> <para>
MySQL is able to store leases, host reservations and options defined on MySQL is able to store leases, host reservations and options defined on
a per host basis. a per host basis. This section can be safely ignored
</para>
<para>
The MySQL database must be properly set up if you want Kea to
store information in MySQL. This section can be safely ignored
if you chose to store the data in other backends. if you chose to store the data in other backends.
</para> </para>
<section id="mysql-database-create"> <section id="mysql-database-create">
<title>First Time Creation of Kea Database</title> <title>First Time Creation of the MySQL Database</title>
<para> <para>
If you are setting the MySQL database for the first time, If you are setting the MySQL database for the first time,
@@ -418,7 +415,7 @@ $ <userinput>kea-admin lease-upgrade mysql -u <replaceable>database-user</replac
</para> </para>
<section id="pgsql-database-create"> <section id="pgsql-database-create">
<title>Manually Create the PostgreSQL Database and the Kea User</title> <title>First Time Creation of the PostgreSQL Database</title>
<para> <para>
The first task is to create both the lease database and the The first task is to create both the lease database and the
@@ -458,7 +455,6 @@ postgres=#
<screen> <screen>
postgres=#<userinput> CREATE USER <replaceable>user-name</replaceable> WITH PASSWORD '<replaceable>password</replaceable>';</userinput> postgres=#<userinput> CREATE USER <replaceable>user-name</replaceable> WITH PASSWORD '<replaceable>password</replaceable>';</userinput>
CREATE ROLE CREATE ROLE
postgres=#
postgres=#<userinput> GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput> postgres=#<userinput> GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput>
GRANT GRANT
postgres=# postgres=#
@@ -594,8 +590,8 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac
<para> <para>
Cassandra, or Cassandra Query Language (CQL), is the newest backend Cassandra, or Cassandra Query Language (CQL), is the newest backend
added to Kea. Since it was added recently and has not undergone as much added to Kea. Since it was added recently and has not undergone as much
testing as other backends, it is considered experimental. Please use testing as other backends, it is considered experimental: please use
with caution. CQL backend is currently able to store leases only. The with caution. The CQL backend is currently able to store leases only. The
ability to store host reservations will likely be added some time in the ability to store host reservations will likely be added some time in the
future. future.
</para> </para>
@@ -607,7 +603,7 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac
</para> </para>
<section id="cql-database-create"> <section id="cql-database-create">
<title>First Time Creation of Kea Database</title> <title>First Time Creation of the Cassandra Database</title>
<para> <para>
If you are setting up the CQL database for the first time, you need to If you are setting up the CQL database for the first time, you need to
@@ -713,19 +709,19 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea
</section> <!-- end of CQL sections --> </section> <!-- end of CQL sections -->
<section> <section>
<title>Using read only databases with host reservations</title> <title>Using Read-Only Databases with Host Reservations</title>
<para>If read only database is used for storing host reservations, <para>If a read-only database is used for storing host reservations,
Kea must be explicitly configured to operate on the database in Kea must be explicitly configured to operate on the database in
the read only mode. read-only mode.
Sections <xref linkend="read-only-database-configuration4"/> and Sections <xref linkend="read-only-database-configuration4"/> and
<xref linkend="read-only-database-configuration6"/> describe when <xref linkend="read-only-database-configuration6"/> describe when
such configuration may be reqired and how to configure Kea to such configuration may be reqired and how to configure Kea to
operate using read only host database. operate using a read-only host database.
</para> </para>
</section> </section>
<section> <section>
<title>Limitations related to the use of the SQL databases</title> <title>Limitations Related to the use of SQL Databases</title>
<para> <para>
The lease expiration time is stored in the SQL database for each lease The lease expiration time is stored in the SQL database for each lease
@@ -738,6 +734,8 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea
maximum signed 32-bit number. This effectively means that the current maximum signed 32-bit number. This effectively means that the current
Kea version can't store the leases which expiration time is later than Kea version can't store the leases which expiration time is later than
2147483647 seconds since the beginning of the epoch (around year 2038). 2147483647 seconds since the beginning of the epoch (around year 2038).
This will be fixed when the database support for longer timestamps
is available.
</para> </para>
</section> </section>

23
doc/guide/config.xml
View File

@@ -4,7 +4,7 @@
<!ENTITY mdash "&#x2014;" > <!ENTITY mdash "&#x2014;" >
]> ]>
<chapter id="kea-config"> <chapter id="kea-config">
<title>Kea configuration</title> <title>Kea Configuration</title>
<para>Kea is designed to allow different methods by which it can be <para>Kea is designed to allow different methods by which it can be
configured, each method being implemented by a component known as a configured, each method being implemented by a component known as a
@@ -12,7 +12,7 @@
available, that allowing configuration by means of a JSON file.</para> available, that allowing configuration by means of a JSON file.</para>
<section id="json-backend"> <section id="json-backend">
<title>JSON configuration backend</title> <title>JSON Configuration Backend</title>
<para>JSON is the default configuration backend. <para>JSON is the default configuration backend.
It assumes that the servers are started from the command line It assumes that the servers are started from the command line
(either directly or using a script, e.g. <filename>keactrl</filename>). (either directly or using a script, e.g. <filename>keactrl</filename>).
@@ -20,11 +20,11 @@
configuration file is specified upon startup using the -c parameter.</para> configuration file is specified upon startup using the -c parameter.</para>
<section id="json-format"> <section id="json-format">
<title>JSON syntax</title> <title>JSON Syntax</title>
<para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined <para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined
in an extended JSON format. Basic JSON is defined in <ulink in an extended JSON format. Basic JSON is defined in <ulink
url="http://tools.ietf.org/html/rfc4627">RFC 4627</ulink>. Kea components url="http://tools.ietf.org/html/rfc4627">RFC 4627</ulink>. Kea components
use a slightly modified JSON, in that they allow shell-style use a slightly modified form of JSON in that they allow shell-style
comments in the file: lines with the hash (#) character in the first column comments in the file: lines with the hash (#) character in the first column
are comment lines and are ignored.</para> are comment lines and are ignored.</para>
@@ -38,8 +38,8 @@
Logging object to configure logging parameters; it will ignore the Dhcp6 Logging object to configure logging parameters; it will ignore the Dhcp6
object.</para> object.</para>
<para>For example, a very simple configuration for both DHCPv4 and DHCPv6 <para>A very simple configuration for both DHCPv4 and
could look like this: DHCPv6 could look like this:
<screen> <screen>
# The whole configuration starts here. # The whole configuration starts here.
{ {
@@ -56,8 +56,7 @@
"subnet4": [{ "subnet4": [{
"pools": [ { "pool": "192.0.2.1-192.0.2.200" } ], "pools": [ { "pool": "192.0.2.1-192.0.2.200" } ],
"subnet": "192.0.2.0/24" "subnet": "192.0.2.0/24"
}], }]
...
}, },
# DHCPv4 specific configuration ends here. # DHCPv4 specific configuration ends here.
@@ -73,8 +72,7 @@
"subnet6": [{ "subnet6": [{
"pools": [ { "pool": "2001:db8::/80" } ], "pools": [ { "pool": "2001:db8::/80" } ],
"subnet": "2001:db8::/64" "subnet": "2001:db8::/64"
}], }]
...
}, },
# DHCPv6 specific configuration ends here. # DHCPv6 specific configuration ends here.
@@ -84,8 +82,7 @@
"loggers": [{ "loggers": [{
"name": "*", "name": "*",
"severity": "DEBUG" "severity": "DEBUG"
}], }]
...
} }
# Logger parameters end here. # Logger parameters end here.
@@ -103,7 +100,7 @@
DHCPv6, only subnet6 parameters will be mentioned. It is implied that DHCPv6, only subnet6 parameters will be mentioned. It is implied that
the remaining elements (the global map that holds Dhcp6, Logging and possibly the remaining elements (the global map that holds Dhcp6, Logging and possibly
DhcpDdns) are present, but they are omitted for clarity. Usually, locations DhcpDdns) are present, but they are omitted for clarity. Usually, locations
where extra parameters may appear are denoted with an ellipsis.</para> where extra parameters may appear are denoted by an ellipsis.</para>
</section> </section>
<section> <section>

561
doc/guide/dhcp4-srv.xml
View File

File diff suppressed because it is too large Load Diff

224
doc/guide/install.xml
View File

@@ -13,22 +13,30 @@
<para> <para>
Some operating systems or software package vendors may provide Some operating systems or software package vendors may provide
ready-to-use, pre-built software packages for Kea. Installing a ready-to-use, pre-built software packages for Kea. Installing a
pre-built package means you do not need to install build-only pre-built package means you do not need to install the software
prerequisites and do not need to <emphasis>make</emphasis> the software. required only to build Kea and do not need to <emphasis>make</emphasis>
the software.
</para> </para>
<para> <para>
FreeBSD ports, NetBSD pkgsrc, and Debian <emphasis>testing</emphasis> FreeBSD ports, NetBSD pkgsrc, and Debian
package collections provide all the prerequisite packages. <emphasis>testing</emphasis> package collections provide all the
prerequisite packages.
</para> </para>
</section> </section>
<section id="install-hierarchy"> <section id="install-hierarchy">
<title>Install Hierarchy</title> <title>Installation Hierarchy</title>
<para> <para>
The following is the directory layout of the complete Kea installation The following is the directory layout of the complete Kea installation.
(all directories paths are relative to the installation directory): (All directory paths are relative to the installation directory):
<itemizedlist> <itemizedlist>
<listitem>
<simpara>
<filename>bin/</filename> &mdash;
utility programs.
</simpara>
</listitem>
<listitem> <listitem>
<simpara> <simpara>
<filename>etc/kea/</filename> &mdash; <filename>etc/kea/</filename> &mdash;
@@ -142,7 +150,7 @@ Debian and Ubuntu:
<listitem> <listitem>
<para> <para>
The development tools: automake, libtool, pkg-config. The development tools automake, libtool, pkg-config.
</para> </para>
</listitem> </listitem>
@@ -151,8 +159,8 @@ Debian and Ubuntu:
The MySQL client and the client development libraries, when using The MySQL client and the client development libraries, when using
the --with-dhcp-mysql configuration flag to build the Kea MySQL the --with-dhcp-mysql configuration flag to build the Kea MySQL
database backend. In this case an instance of the MySQL server database backend. In this case an instance of the MySQL server
running locally or on some other machine, reachable over the running locally or on a machine reachable over a network
network from the machine running Kea, is required. Note that is required. Note that
running the unit tests requires a local MySQL server. running the unit tests requires a local MySQL server.
</para> </para>
</listitem> </listitem>
@@ -171,23 +179,24 @@ Debian and Ubuntu:
<listitem> <listitem>
<para> <para>
googletest (version 1.6 or later), when using --with-gtest configuration option. googletest (version 1.6 or later), when using the --with-gtest configuration
option to build the unit tests.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Documentation generating tools: elinks, docbook-xsl, libxslt and Doxygen, The documentation generation tools elinks, docbook-xsl, libxslt and Doxygen,
when generating documentation using the --enable-generate-docs if using the --enable-generate-docs configuration option
configuration option. to create the documentation.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para> <para>
Visit the user-contributed wiki at <ulink Visit the user-contributed wiki at
url="http://kea.isc.org/wiki/SystemSpecificNotes" /> <ulink url="http://kea.isc.org/wiki/SystemSpecificNotes" />
for system-specific installation tips. for system-specific installation tips.
</para> </para>
@@ -196,11 +205,11 @@ Debian and Ubuntu:
<section id="install"> <section id="install">
<title>Installation from Source</title> <title>Installation from Source</title>
<para> <para>
Kea is open source software written in C++. Kea is open source software written in C++. It is freely available in
It is freely available in source code form from ISC as a source code form from ISC as a downloadable tar file. A copy of the Kea
downloadable tar file or via Kea Git code revision control source code repository is accessible from Github (<ulink
service. (It may also be available in pre-compiled ready-to-use url="https://github.com/isc-projects/kea"/>). Kea may also be available
packages from operating system vendors.) in pre-compiled ready-to-use packages from operating system vendors.
</para> </para>
<section> <section>
@@ -224,15 +233,15 @@ Debian and Ubuntu:
<para> <para>
When building from source code retrieved via Git, additional When building from source code retrieved via Git, additional
software will be required: automake (v1.11 or later), software will be required: automake (v1.11 or later),
libtoolize, and autoconf (2.59 or later). libtoolize, and autoconf (v2.59 or later).
These may need to be installed. These may need to be installed.
</para> </para>
</note> </note>
<para> <para>
The latest development code is available on Github (see The latest development code is available on Github (see
<ulink url="https://github.com/isc-projects/kea"/>). The Kea development <ulink url="https://github.com/isc-projects/kea"/>). The Kea source
is public and the leading development is done in the <quote>master</quote> is public and development is done in the <quote>master</quote>
branch. branch.
</para> </para>
<para> <para>
@@ -243,7 +252,7 @@ Debian and Ubuntu:
</para> </para>
<para> <para>
The code checked out from the git repository doesn't include the The code checked out from the git repository does not include the
generated configure script, Makefile.in files, nor their generated configure script, Makefile.in files, nor their
related build files. related build files.
They can be created by running <command>autoreconf</command> They can be created by running <command>autoreconf</command>
@@ -257,24 +266,22 @@ Debian and Ubuntu:
</para> </para>
<para> <para>
The write access to Kea repository is only granted to ISC staff. If you Write access to the Kea repository is only granted to ISC staff. If you
are a developer planning to contribute to Kea, please fork our Github are a developer planning to contribute to Kea, please fork our Github
repository and use the "pull request" mechanism to request integration of repository and use the "pull request" mechanism to request integration of
your code into our repository. Please consult your code. Please consult
<ulink url="https://help.github.com/articles/fork-a-repo/"/> for help <ulink url="https://help.github.com/articles/fork-a-repo/"/> for help on
how to fork a Github repository. how to fork a Github repository.
<ulink url="http://git.kea.isc.org/~tester/kea/doxygen/"> The <ulink url="http://git.kea.isc.org/~tester/kea/doxygen/">Kea
Kea Developer's Guide</ulink> contains information and guidelines for Developer's Guide</ulink> contains more information about the process, as
the contributors about the process of integrating the code via well as describing the requirements for contributed code to be accepted by ISC.
pull requests. It also contains the requirements for the contributed
code to be accepted by ISC.
</para> </para>
</section> </section>
<section id="configure"> <section id="configure">
<title>Configure before the build</title> <title>Configure Before the Build</title>
<para> <para>
Kea uses the GNU Build System to discover build environment Kea uses the GNU Build System to discover build environment
details. details.
@@ -304,41 +311,42 @@ Debian and Ubuntu:
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term>--with-boost-libs</term>
<listitem>
<simpara>Specify Boost libraries to link with (this option
exists only to provide a way to enforce such a list:
usually this should not be used).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-boost-lib-dir</term>
<listitem>
<simpara>Specify the path to Boost libraries to link with
(usually there should be no reason to specify this option).
</simpara>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term>--with-botan-config</term> <term>--with-botan-config</term>
<listitem> <listitem>
<simpara>Specify the path to the botan-config <simpara>Specify the path to the botan-config
script to build with Botan for the crypto code. script to build with Botan for cryptographic functions.
</simpara> </simpara>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>--with-gtest</term> <term>--with-dhcp-mysql</term>
<listitem>
<simpara>
Build Kea with code to allow it to store leases (and access
host reservations) in a MySQL database.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-dhcp-pgsql</term>
<listitem>
<simpara>
Build Kea with code to allow it to store leases (and access
host reservations) in a PostgreSQL database.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-gtest-source</term>
<listitem> <listitem>
<simpara>Enable the building of the C++ Unit Tests using the <simpara>Enable the building of the C++ Unit Tests using the
Google Test framework. Optionally this can define the Google Test framework. This option specifies the path to the
path to the gtest header files and library. (If the framework gtest source. (If the framework
is not already installed on your system, it can be downloaded is not installed on your system, it can be downloaded
from <ulink url="https://code.google.com/p/googletest"/>.) from <ulink url="https://code.google.com/p/googletest"/>.)
</simpara> </simpara>
</listitem> </listitem>
@@ -356,19 +364,10 @@ Debian and Ubuntu:
<varlistentry> <varlistentry>
<term>--with-openssl</term> <term>--with-openssl</term>
<listitem> <listitem>
<simpara>Replace Botan by OpenSSL for the crypto library. <simpara>Replace Botan by the OpenSSL the cryptographic library.
The default is to try to find a working Botan then By default <command>configure</command> searches for a valid
OpenSSL only if Botan is not found. Botan installation:
</simpara> if one is not found, it searches for OpenSSL.
</listitem>
</varlistentry>
<varlistentry>
<term>--without-werror</term>
<listitem>
<simpara>Disable the default use of the
<option>-Werror</option> compiler flag so that
compiler warnings do not result in build failures.
</simpara> </simpara>
</listitem> </listitem>
</varlistentry> </varlistentry>
@@ -376,9 +375,9 @@ Debian and Ubuntu:
</variablelist> </variablelist>
<note> <note>
<para> <para>
For additional instructions concerning the building and installation of For instructions concerning the installation and configuration
Kea for various databases, see <xref linkend="dhcp-install-configure"/>. of database backends for Kea, see <xref linkend="dhcp-install-configure"/>.
For additional instructions concerning the configuration backends, see For information concerning the configuration backends, see
<xref linkend="dhcp-config-backend" />. <xref linkend="dhcp-config-backend" />.
</para> </para>
</note> </note>
@@ -399,8 +398,8 @@ Debian and Ubuntu:
<para> <para>
If you have some problems with building Kea using the header-only If you have some problems with building Kea using the header-only
Boost error code or you'd like to use the Boost system library Boost code or you'd like to use the Boost system library
(e.g., located in /usr/pkg/lib): (assumed for the sake of this example to be located in /usr/pkg/lib):
<screen>$ <userinput>./configure \ <screen>$ <userinput>./configure \
--with-boost-libs=-lboost_system \ --with-boost-libs=-lboost_system \
@@ -408,15 +407,15 @@ Debian and Ubuntu:
</para> </para>
<para> <para>
If the configure fails, it may be due to missing or old If <command>configure</command> fails, it may be due to missing or old
dependencies. dependencies.
</para> </para>
<para> <para>
<userinput>./configure</userinput> when it succeeds displays a report If <command>configure</command> succeeds, it displays a report
with the building parameters. This report is saved into with the parameters used to build the code. This report is saved into
<filename>config.report</filename> and embedded into executable the file <filename>config.report</filename> and is also embedded into
binaries, e.g., <userinput>kea-dhcp4</userinput>. the executable binaries, e.g., <userinput>kea-dhcp4</userinput>.
</para> </para>
</section> </section>
@@ -426,7 +425,6 @@ Debian and Ubuntu:
<para> <para>
After the configure step is complete, build the executables After the configure step is complete, build the executables
from the C++ code and prepare the Python scripts by running the command: from the C++ code and prepare the Python scripts by running the command:
<screen>$ <userinput>make</userinput></screen> <screen>$ <userinput>make</userinput></screen>
</para> </para>
</section> </section>
@@ -448,7 +446,7 @@ Debian and Ubuntu:
</note> </note>
<para> <para>
If required, run <command>ldconfig</command> as root with If required, run <command>ldconfig</command> as root with
<filename>/usr/local/lib</filename> (or with ${prefix}/lib if <filename>/usr/local/lib</filename> (or with <replaceable>prefix</replaceable>/lib if
configured with --prefix) in configured with --prefix) in
<filename>/etc/ld.so.conf</filename> (or the relevant linker <filename>/etc/ld.so.conf</filename> (or the relevant linker
cache configuration file for your OS): cache configuration file for your OS):
@@ -472,7 +470,7 @@ Debian and Ubuntu:
<section id="dhcp-config-backend"> <section id="dhcp-config-backend">
<title>Selecting the Configuration Backend</title> <title>Selecting the Configuration Backend</title>
<para>Kea 0.9 has introduced configuration backends that are <para>Kea 0.9 introduced configuration backends that are
switchable during the compilation phase. Only one backend, JSON, switchable during the compilation phase. Only one backend, JSON,
is currently supported. is currently supported.
</para> </para>
@@ -483,10 +481,10 @@ Debian and Ubuntu:
<term>JSON</term> <term>JSON</term>
<listitem> <listitem>
<simpara>JSON is the new default configuration backend <simpara>JSON is the new default configuration backend
that causes Kea to read JSON configuration files from that allows Kea to read JSON configuration files from
disk. It does not require any framework and thus is disk. It does not require any framework and thus is
considered more lightweight. It will allow dynamic considered more lightweight. It will allow dynamic
on-line reconfiguration, but will lack remote capabilities on-line reconfiguration, but lacks remote capabilities
(i.e. no RESTful API).</simpara> (i.e. no RESTful API).</simpara>
</listitem> </listitem>
</varlistentry> </varlistentry>
@@ -497,19 +495,20 @@ Debian and Ubuntu:
<section id="dhcp-install-configure"> <section id="dhcp-install-configure">
<title>DHCP Database Installation and Configuration</title> <title>DHCP Database Installation and Configuration</title>
<para> <para>
Kea stores its leases in a lease database. The software has been written in Kea stores its leases in a lease database. The software has been
a way that makes it possible to choose which database product should be used to written in a way that makes it possible to choose which database product
store the lease information. At present, Kea supports three database backends: MySQL, should be used to store the lease information. At present, Kea supports
PostgreSQL and Memfile. To limit external dependencies, both MySQL and PostgreSQL four database backends: MySQL, PostgreSQL, Cassandra and Memfile. To
support are disabled by default and only Memfile limit external dependencies, MySQL, PostgreSQL and Cassandra support are
is available. Support for the optional external database backend must be explicitly included when disabled by default and only Memfile is available. Support for the
Kea is built. This section covers the building of Kea with MySQL and/or PostgreSQL optional external database backend must be explicitly included when Kea
and the creation of the lease database. is built. This section covers the building of Kea with one of the
optional backends and the creation of the lease database.
</para> </para>
<note> <note>
<simpara> <simpara>
When unit tests are built with Kea (--with-gtest configuration option is specified), 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 databases must be manually pre-configured for the unit tests to run.
The details of this configuration can be found in the The details of this configuration can be found in the
<ulink url="http://git.kea.isc.org/~tester/kea/doxygen">Kea Developer's <ulink url="http://git.kea.isc.org/~tester/kea/doxygen">Kea Developer's
@@ -526,10 +525,11 @@ Debian and Ubuntu:
<para> <para>
Build and install Kea as described in <xref linkend="installation"/>, with Build and install Kea as described in <xref linkend="installation"/>, with
the following modification. To enable the MySQL database code, at the the following modification. To enable the MySQL database code, at the
"configure" step (see <xref linkend="configure"/>), do: "configure" step (see <xref linkend="configure"/>), the --with-dhcp-mysql switch
should be specified:
<screen><userinput>./configure [other-options] --with-dhcp-mysql</userinput></screen> <screen><userinput>./configure [other-options] --with-dhcp-mysql</userinput></screen>
Or specify the location of the MySQL configuration program If MySQL was not installed in the default location, the location of the MySQL
"mysql_config" if MySQL was not installed in the default location: configuration program "mysql_config" should be included with the switch, i.e.
<screen><userinput>./configure [other-options] --with-dhcp-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen> <screen><userinput>./configure [other-options] --with-dhcp-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
</para> </para>
<para> <para>
@@ -547,11 +547,11 @@ Debian and Ubuntu:
<para> <para>
Build and install Kea as described in <xref linkend="installation"/>, with Build and install Kea as described in <xref linkend="installation"/>, with
the following modification. To enable the PostgreSQL database code, at the the following modification. To enable the PostgreSQL database code, at the
"configure" step (see <xref linkend="configure"/>), do: "configure" step (see <xref linkend="configure"/>), the --with-dhcp-pgsql switch
should be specified:
<screen><userinput>./configure [other-options] --with-dhcp-pgsql</userinput></screen> <screen><userinput>./configure [other-options] --with-dhcp-pgsql</userinput></screen>
Or specify the location of the PostgreSQL configuration If PostgreSQL was not installed in the default location, the location of the PostgreSQL
program "pg_config" if PostgreSQL was not installed in configuration program "pg_config" should be included with the switch, i.e.
the default location:
<screen><userinput>./configure [other-options] --with-dhcp-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen> <screen><userinput>./configure [other-options] --with-dhcp-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
</para> </para>
<para> <para>
@@ -564,13 +564,13 @@ Debian and Ubuntu:
<title>Building with CQL (Cassandra) support</title> <title>Building with CQL (Cassandra) support</title>
<para> <para>
Install Cassandra according to the instructions for your system. The Install Cassandra according to the instructions for your system. The
Cassandra project webpage contains useful pointers: <ulink Cassandra project website contains useful pointers: <ulink
url="http://cassandra.apache.org/download/" />. url="http://cassandra.apache.org" />.
</para> </para>
<para> <para>
Download and compile cpp-driver from DataStax. For details regarding Download and compile cpp-driver from DataStax. For details regarding
dependencies for building cpp-driver, see the project homepage dependencies for building cpp-driver, see the project homepage
<ulink url="https://github.com/datastax/cpp-driver" />. As of June <ulink url="https://github.com/datastax/cpp-driver" />. In June
2016, the following commands were used: 2016, the following commands were used:
<screen> <screen>
$ <userinput>git clone https://github.com/datastax/cpp-driver</userinput> $ <userinput>git clone https://github.com/datastax/cpp-driver</userinput>
@@ -582,15 +582,15 @@ $ <userinput>make</userinput>
</para> </para>
<para> <para>
As of June 2016, cpp-driver does not include cql_config script As of June 2016, cpp-driver does not include cql_config script
yet. There is a work in progress to contribute such a script to yet. Work is in progress to contribute such a script to the
cpp-driver project. Until such contribution is accepted, there are cpp-driver project but, until that is complete,
intermediate steps that need to be conducted. The cql_config intermediate steps that need to be conducted. A cql_config script is present in the
script and cql_config_defines.sh are temporarily stored in
tools/ directory of the Kea sources. Before using it, please tools/ directory of the Kea sources. Before using it, please
edit cql_config_defines.sh: change CPP_DRIVER_PATH to the directory, edit cql_config_defines.sh in the same directory and change the
where cpp-driver sources are located. If cpp-driver sources already environment variable CPP_DRIVER_PATH to point to the directory,
where cpp-driver sources are located. (If the cpp-driver sources already
provide cql_config script please use that rather than the version provide cql_config script please use that rather than the version
from Kea sources. from Kea sources.)
</para> </para>
<para> <para>
Build and install Kea as described in <xref linkend="installation"/>, with Build and install Kea as described in <xref linkend="installation"/>, with

35
doc/guide/intro.xml
View File

@@ -55,13 +55,13 @@
<listitem> <listitem>
<simpara> <simpara>
Kea supports two crypto libraries: Botan and OpenSSL. Only one of them Kea supports two cryptographic libraries: Botan and OpenSSL. Only one of
is required to be installed during compilation. Kea uses the Botan them is required to be installed during compilation. If using Botan, Kea
crypto library for C++ (<ulink url="http://botan.randombit.net/"/>), requires the Botan cryptographic library for C++ (<ulink
version 1.8, 1.9 or 1.10. As an alternative to Botan, Kea can use the url="http://botan.randombit.net/"/>), version 1.8, 1.9 or 1.10. If
OpenSSL crypto library (<ulink url="http://www.openssl.org/"/>), OpenSSL is used, (<ulink url="http://www.openssl.org/"/>), then Kea
version 1.0.*. Support for later versions of Botan and OpenSSL will requires the OpenSSL C++ library version 1.0.*. Support for later
be added in future releases of Kea. versions of Botan and OpenSSL will be added in future releases of Kea.
</simpara> </simpara>
</listitem> </listitem>
@@ -69,7 +69,7 @@
<simpara> <simpara>
Kea uses the log4cplus C++ logging library Kea uses the log4cplus C++ logging library
(<ulink url="http://log4cplus.sourceforge.net/"/>). (<ulink url="http://log4cplus.sourceforge.net/"/>).
It requires at least log4cplus version 1.0.3. It requires log4cplus version 1.0.3 or later.
</simpara> </simpara>
</listitem> </listitem>
@@ -123,7 +123,7 @@
<listitem> <listitem>
<simpara> <simpara>
<command>kea-dhcp4</command> &mdash; <command>kea-dhcp4</command> &mdash;
DHCPv4 server process. The DHCPv4 server process.
This process responds to DHCPv4 queries from clients. This process responds to DHCPv4 queries from clients.
</simpara> </simpara>
</listitem> </listitem>
@@ -131,7 +131,7 @@
<listitem> <listitem>
<simpara> <simpara>
<command>kea-dhcp6</command> &mdash; <command>kea-dhcp6</command> &mdash;
DHCPv6 server process. The DHCPv6 server process.
This process responds to DHCPv6 queries from clients. This process responds to DHCPv6 queries from clients.
</simpara> </simpara>
</listitem> </listitem>
@@ -139,9 +139,9 @@
<listitem> <listitem>
<simpara> <simpara>
<command>kea-dhcp-ddns</command> &mdash; <command>kea-dhcp-ddns</command> &mdash;
DHCP-DDNS process. The DHCP Dynamic DNS process.
This process acts as an intermediary between the DHCP servers This process acts as an intermediary between the DHCP servers
and DNS server. It receives name update requests from the DHCP and DNS servers. It receives name update requests from the DHCP
servers and sends DNS Update messages to the DNS servers. servers and sends DNS Update messages to the DNS servers.
</simpara> </simpara>
</listitem> </listitem>
@@ -149,7 +149,7 @@
<listitem> <listitem>
<simpara> <simpara>
<command>kea-admin</command> &mdash; <command>kea-admin</command> &mdash;
A tool useful for database backend maintenance (creating new A useful tool for database backend maintenance (creating a new
database, checking versions, upgrading etc.) database, checking versions, upgrading etc.)
</simpara> </simpara>
</listitem> </listitem>
@@ -159,17 +159,16 @@
<command>kea-lfc</command> &mdash; <command>kea-lfc</command> &mdash;
This process removes redundant information from the files used This process removes redundant information from the files used
to provide persistent storage for the memfile data base backend. to provide persistent storage for the memfile data base backend.
The service is written to run as a stand alone process. While it While it can be run standalone, it is normally run as and when
can be started externally it should be started by the Kea DHCP required by the Kea DHCP servers.
servers.
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<command>perfdhcp</command> &mdash; <command>perfdhcp</command> &mdash;
DHCP benchmarking tool which simulates multiple clients to A DHCP benchmarking tool which simulates multiple clients to
test both DHCPv4 and DHCPv6 servers performance. test both DHCPv4 and DHCPv6 server performance.
</simpara> </simpara>
</listitem> </listitem>

3
doc/guide/keactrl.xml
View File

@@ -139,8 +139,7 @@ kea_verbose=no
<section id="keactrl-commands"> <section id="keactrl-commands">
<title>Commands</title> <title>Commands</title>
<para>The following commands are supported by <command>keactrl</command> <para>The following commands are supported by <command>keactrl</command>:
to perform specific operations on the Kea servers:
<itemizedlist> <itemizedlist>
<listitem><simpara> <listitem><simpara>
<command>start</command> - starts selected servers. <command>start</command> - starts selected servers.

39
doc/guide/quickstart.xml
View File

@@ -7,16 +7,16 @@
]> ]>
<chapter id="quickstart"> <chapter id="quickstart">
<title>Quick start</title> <title>Quick Start</title>
<para> <para>
This quickly covers the standard steps for installing and deploying Kea. This section describes the basic steps needed to get Kea up and running.
For further details, full customizations, and troubleshooting, see the For further details, full customizations, and troubleshooting, see the
respective chapters in the Kea guide. respective chapters in the Kea guide.
</para> </para>
<section id="quick-start"> <section id="quick-start">
<title>Quick start guide for DHCPv4 and DHCPv6 services</title> <title>Quick Start Guide for DHCPv4 and DHCPv6 Services</title>
<orderedlist> <orderedlist>
@@ -54,8 +54,9 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
</listitem> </listitem>
<listitem> <listitem>
<para>Install it (by default the installation prefix is <filename>/usr/local/</filename>, <para>Install it (by default it will be placed in
so you likely need root privileges for that step): <filename>/usr/local/</filename>,
so it is likely that you will need root privileges for this step):
<screen># <userinput>make install</userinput></screen> <screen># <userinput>make install</userinput></screen>
</para> </para>
</listitem> </listitem>
@@ -64,7 +65,8 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
<para>Edit the configuration file which by default is installed in <para>Edit the configuration file which by default is installed in
<filename>[kea-install-dir]/etc/kea/kea.conf</filename> and contains <filename>[kea-install-dir]/etc/kea/kea.conf</filename> and contains
configuration for all Kea services. Configuration choices for DHCPv4 configuration for all Kea services. Configuration choices for DHCPv4
and DHCPv6 services are described in <xref linkend="dhcp4-configuration"/> and <xref linkend="dhcp6-configuration"/>, respectively.</para> and DHCPv6 services are described in <xref linkend="dhcp4-configuration"/> and <xref linkend="dhcp6-configuration"/>:w
respectively.</para>
</listitem> </listitem>
<listitem> <listitem>
@@ -81,10 +83,11 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
<listitem> <listitem>
<para>Verify that Kea server(s) are running: <para>Verify that Kea server(s) are running:
<screen># <userinput>keactrl status</userinput></screen> <screen># <userinput>keactrl status</userinput></screen>
If the server status is "inactive" may indicate a configuration A server status of "inactive" may indicate a configuration
error. Please check a log file (by default located in error. Please check the log file (by default named
<filename>[kea-install-dir]/var/kea/kea.log</filename>) for the <filename>[kea-install-dir]/var/kea/kea-dhcp4.log</filename> or
details of the error. <filename>[kea-install-dir]/var/kea/kea-dhcp6.log</filename>)
for the details of the error.
</para> </para>
</listitem> </listitem>
@@ -99,15 +102,15 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
<listitem> <listitem>
<para> <para>
Stop running server(s): Stop running the server(s):
<screen># <userinput>keactrl stop</userinput></screen> <screen># <userinput>keactrl stop</userinput></screen>
</para> </para>
</listitem> </listitem>
</orderedlist> </orderedlist>
<para> <para>
For more system specific installation procedures, you may want to visit For instructions specific to your system, please read the
<ulink url="http://kea.isc.org/wiki/SystemSpecificNotes">System specific notes</ulink>, <ulink url="http://kea.isc.org/wiki/SystemSpecificNotes">system specific notes</ulink>,
available on <ulink url="http://kea.isc.org/">Kea homepage</ulink>. available on the <ulink url="http://kea.isc.org/">Kea web site</ulink>.
</para> </para>
<para>The details of <command>keactrl</command> script usage can be found <para>The details of <command>keactrl</command> script usage can be found
@@ -115,12 +118,12 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
</section> </section>
<section id="quick-start-direct-run"> <section id="quick-start-direct-run">
<title>Running Kea servers directly</title> <title>Running the Kea Servers Directly</title>
<para>Kea servers can be started directly (without a need to use <para>The Kea servers can be started directly, without the need to use the
<command>keactrl</command>). To start DHCPv4 server run the following <command>keactrl</command>. To start the DHCPv4 server run the following
command: command:
<screen># <userinput>kea-dhcp4 -c /path/to/your/kea4/config/file.json</userinput></screen> <screen># <userinput>kea-dhcp4 -c /path/to/your/kea4/config/file.json</userinput></screen>
And, to start the DHCPv6 server run the following command: Similarly, to start the DHCPv6 server run the following command:
<screen># <userinput>kea-dhcp6 -c /path/to/your/kea6/config/file.json</userinput></screen> <screen># <userinput>kea-dhcp6 -c /path/to/your/kea6/config/file.json</userinput></screen>
</para> </para>
</section> </section>