mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-31 05:55:28 +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
are released, the structure of those databases will change.
For example, Kea currently only stores lease information
and host reservations: in the future, additional
data - such as subnet definitions - will also be stored.
and host reservations. Future versions of Kea will store
additional data such as subnet definitions: the database
structure will need to be updated to accomdate the extra
information.
</para>
<para>
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
backend databases, independent of the version of Kea itself. It
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
Kea upgrade. Versions for each database are independent, so an
increment in the MySQL database version does not imply an increment
@@ -70,9 +72,10 @@
<listitem>
<simpara>
<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
latest version supported by the version of the software.
latest version supported by the version of the software being
installed.
</simpara>
</listitem>
@@ -97,9 +100,10 @@
<simpara>
<command>lease-dump</command> &mdash;
Dumps the contents of the lease database (for MySQL, PostgreSQL or
CQL backends) to CSV text file. The first line of the file contains
the column names. This is meant to be used as a diagnostic tool
that provides a portable, human-readable form of lease data.
CQL backends) to a CSV (comma separated values) text file. The first
line of the file contains the column names. This is meant to be
used as a diagnostic tool, so provides a portable, human-readable
form of the lease data.
</simpara>
</listitem>
</itemizedlist>
@@ -118,16 +122,14 @@
<listitem>
<simpara>
<command>mysql</command> &mdash;
Lease information is stored in a MySQL relational
database.
Lease information is stored in a MySQL relational database.
</simpara>
</listitem>
<listitem>
<simpara>
<command>pgsql</command> &mdash;
Lease information is stored in a PostgreSQL relational
database.
Lease information is stored in a PostgreSQL relational database.
</simpara>
</listitem>
@@ -142,7 +144,7 @@
Additional parameters may be needed, depending on your setup
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>).
</para>
</section>
@@ -185,7 +187,7 @@
<row>
<entry>Data format</entry>
<entry>coma separated file</entry>
<entry>CSV file</entry>
<entry>SQL RMDB</entry>
<entry>SQL RMDB</entry>
<entry>NoSQL database (CQL)</entry>
@@ -224,14 +226,14 @@
<title>memfile</title>
<para>
Memfile backend is able to store lease information, but is not able to
store host reservation details. There are no plans to add the
reservations storage capability to memfile. Host reservations can be
defined in the configuration file.
The memfile backend is able to store lease information, but is not able to
store host reservation details: these must be stored in the configuration
file. (There are no plans to add a host reservations storage capability to
this backend.)
</para>
<para>
There are no special initialization steps necessary
No special initialization steps are necessary
for the memfile backend. During the first run, both
<command>kea-dhcp4</command> and <command>kea-dhcp6</command>
will create an empty lease file if one is not
@@ -267,17 +269,12 @@
<para>
MySQL is able to store leases, host reservations and options defined on
a per host basis.
</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
a per host basis. This section can be safely ignored
if you chose to store the data in other backends.
</para>
<section id="mysql-database-create">
<title>First Time Creation of Kea Database</title>
<title>First Time Creation of the MySQL Database</title>
<para>
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>
<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>
The first task is to create both the lease database and the
@@ -458,7 +455,6 @@ postgres=#
<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=#
@@ -594,8 +590,8 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac
<para>
Cassandra, or Cassandra Query Language (CQL), is the newest backend
added to Kea. Since it was added recently and has not undergone as much
testing as other backends, it is considered experimental. Please use
with caution. CQL backend is currently able to store leases only. The
testing as other backends, it is considered experimental: please use
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
future.
</para>
@@ -607,7 +603,7 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac
</para>
<section id="cql-database-create">
<title>First Time Creation of Kea Database</title>
<title>First Time Creation of the Cassandra Database</title>
<para>
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>
<title>Using read only databases with host reservations</title>
<para>If read only database is used for storing host reservations,
<title>Using Read-Only Databases with Host Reservations</title>
<para>If a read-only database is used for storing host reservations,
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
<xref linkend="read-only-database-configuration6"/> describe when
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>
</section>
<section>
<title>Limitations related to the use of the SQL databases</title>
<title>Limitations Related to the use of SQL Databases</title>
<para>
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
Kea version can't store the leases which expiration time is later than
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>
</section>

23
doc/guide/config.xml
View File

@@ -4,7 +4,7 @@
<!ENTITY mdash "&#x2014;" >
]>
<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
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>
<section id="json-backend">
<title>JSON configuration backend</title>
<title>JSON Configuration Backend</title>
<para>JSON is the default configuration backend.
It assumes that the servers are started from the command line
(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>
<section id="json-format">
<title>JSON syntax</title>
<title>JSON Syntax</title>
<para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined
in an extended JSON format. Basic JSON is defined in <ulink
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
are comment lines and are ignored.</para>
@@ -38,8 +38,8 @@
Logging object to configure logging parameters; it will ignore the Dhcp6
object.</para>
<para>For example, a very simple configuration for both DHCPv4 and DHCPv6
could look like this:
<para>A very simple configuration for both DHCPv4 and
DHCPv6 could look like this:
<screen>
# The whole configuration starts here.
{
@@ -56,8 +56,7 @@
"subnet4": [{
"pools": [ { "pool": "192.0.2.1-192.0.2.200" } ],
"subnet": "192.0.2.0/24"
}],
...
}]
},
# DHCPv4 specific configuration ends here.
@@ -73,8 +72,7 @@
"subnet6": [{
"pools": [ { "pool": "2001:db8::/80" } ],
"subnet": "2001:db8::/64"
}],
...
}]
},
# DHCPv6 specific configuration ends here.
@@ -84,8 +82,7 @@
"loggers": [{
"name": "*",
"severity": "DEBUG"
}],
...
}]
}
# Logger parameters end here.
@@ -103,7 +100,7 @@
DHCPv6, only subnet6 parameters will be mentioned. It is implied that
the remaining elements (the global map that holds Dhcp6, Logging and possibly
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>

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

File diff suppressed because it is too large Load Diff

228
doc/guide/install.xml
View File

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

35
doc/guide/intro.xml
View File

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

3
doc/guide/keactrl.xml
View File

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

39
doc/guide/quickstart.xml
View File

@@ -7,16 +7,16 @@
]>
<chapter id="quickstart">
<title>Quick start</title>
<title>Quick Start</title>
<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
respective chapters in the Kea guide.
</para>
<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>
@@ -54,8 +54,9 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
</listitem>
<listitem>
<para>Install it (by default the installation prefix is <filename>/usr/local/</filename>,
so you likely need root privileges for that step):
<para>Install it (by default it will be placed in
<filename>/usr/local/</filename>,
so it is likely that you will need root privileges for this step):
<screen># <userinput>make install</userinput></screen>
</para>
</listitem>
@@ -64,7 +65,8 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
<para>Edit the configuration file which by default is installed in
<filename>[kea-install-dir]/etc/kea/kea.conf</filename> and contains
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>
@@ -81,10 +83,11 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
<listitem>
<para>Verify that Kea server(s) are running:
<screen># <userinput>keactrl status</userinput></screen>
If the server status is "inactive" may indicate a configuration
error. Please check a log file (by default located in
<filename>[kea-install-dir]/var/kea/kea.log</filename>) for the
details of the error.
A server status of "inactive" may indicate a configuration
error. Please check the log file (by default named
<filename>[kea-install-dir]/var/kea/kea-dhcp4.log</filename> or
<filename>[kea-install-dir]/var/kea/kea-dhcp6.log</filename>)
for the details of the error.
</para>
</listitem>
@@ -99,15 +102,15 @@ $ <userinput>./configure [your extra parameters]</userinput></screen>
<listitem>
<para>
Stop running server(s):
Stop running the server(s):
<screen># <userinput>keactrl stop</userinput></screen>
</para>
</listitem>
</orderedlist>
<para>
For more system specific installation procedures, you may want to visit
<ulink url="http://kea.isc.org/wiki/SystemSpecificNotes">System specific notes</ulink>,
available on <ulink url="http://kea.isc.org/">Kea homepage</ulink>.
For instructions specific to your system, please read the
<ulink url="http://kea.isc.org/wiki/SystemSpecificNotes">system specific notes</ulink>,
available on the <ulink url="http://kea.isc.org/">Kea web site</ulink>.
</para>
<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 id="quick-start-direct-run">
<title>Running Kea servers directly</title>
<para>Kea servers can be started directly (without a need to use
<command>keactrl</command>). To start DHCPv4 server run the following
<title>Running the Kea Servers Directly</title>
<para>The Kea servers can be started directly, without the need to use the
<command>keactrl</command>. To start the DHCPv4 server run the following
command:
<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>
</para>
</section>