mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-01 14:35:29 +00:00
Code Issues Releases Wiki Activity

[3418] Several clean-ups in sections 1...3

Browse Source
This commit is contained in:
Tomek Mrugalski
2014-06-10 16:23:24 +02:00
parent 4692766fed
commit fd1b16a445
1 changed files with 94 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
doc/guide/kea-guide.xml
View File

@@ -26,8 +26,7 @@
<?xml-stylesheet href="bind10-guide.css" type="text/css"?> <?xml-stylesheet href="bind10-guide.css" type="text/css"?>
<bookinfo> <bookinfo>
<title>Kea Guide</title> <title>Kea Administrator Reference Manual</title>
<subtitle>Administrator Reference for Kea</subtitle>
<copyright> <copyright>
<year>2010-2014</year><holder>Internet Systems Consortium, Inc.</holder> <year>2010-2014</year><holder>Internet Systems Consortium, Inc.</holder>
@@ -40,7 +39,6 @@
Consortium (ISC). Consortium (ISC).
</para> </para>
<!-- TODO: The VERSION needs to be updated -->
<para> <para>
This is the reference guide for Kea version &__VERSION__;. This is the reference guide for Kea version &__VERSION__;.
The most up-to-date version of this document (in PDF, HTML, The most up-to-date version of this document (in PDF, HTML,
@@ -53,18 +51,12 @@
</bookinfo> </bookinfo>
<!-- todo: Preface is now empty, but leave it around now
<preface>
<title>Preface</title>
</preface>
-->
<chapter id="intro"> <chapter id="intro">
<title>Introduction</title> <title>Introduction</title>
<para> <para>
Kea is the next generation of DHCP servers developed by ISC. Kea is the next generation of DHCP servers developed by ISC.
It supports both DHCPv4 and DHCPv6 protocols along with their It supports both DHCPv4 and DHCPv6 protocols along with their
extensions (e.g. prefix delegation). It also supports the dynamic extensions, e.g. prefix delegation and dynamic updates to DNS.
updates to DNS.
</para> </para>
<para> <para>
@@ -87,7 +79,7 @@
paragraphs. The term "BIND 10" in the context of this document means paragraphs. The term "BIND 10" in the context of this document means
"BIND 10 libraries and applications which are necessary for Kea to run "BIND 10 libraries and applications which are necessary for Kea to run
and configure". The term "Kea" means "the collection of binaries and libraries and configure". The term "Kea" means "the collection of binaries and libraries
which, as a whole, implement the DHCP protocols. which, as a whole, implement the DHCP protocols".
</simpara> </simpara>
</note> </note>
@@ -96,20 +88,18 @@
</para> </para>
<section> <section>
<!-- todo: revisit (maybe extend) the list of supported platforms -->
<title>Supported Platforms</title> <title>Supported Platforms</title>
<para> <para>
Kea builds have been tested on (in no particular order) Kea is officially supported on RedHat Enterprise Linux,
CentOS, Fedora and FreeBSD systems. It is also likely to work on many
other platforms: builds have been tested on (in no particular order)
Debian GNU/Linux 6 and unstable, Ubuntu 9.10, NetBSD 5, Debian GNU/Linux 6 and unstable, Ubuntu 9.10, NetBSD 5,
Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3, Solaris 10 and 11, FreeBSD 7 and 8, CentOS Linux 5.3,
MacOS 10.6 and 10.7, and OpenBSD 5.1. MacOS 10.6 and 10.7, and OpenBSD 5.1. Non supported systems
(especially non-Linux) are likely to have issues with directly
It has been tested on Sparc, i386, and amd64 hardware connected DHCPv4 clients.
platforms.
It is planned for Kea to build, install and run on
Windows and standard Unix-type platforms.
</para> </para>
<para>There are currently no plans to port Kea to Windows platforms.</para>
</section> </section>
<section id="required-software"> <section id="required-software">
@@ -125,41 +115,56 @@
</para> </para>
<para> <para>
Kea was developed as a collection of applications within Kea was developed as a collection of applications within BIND
BIND 10 framework and it still relies on the remaining parts 10 framework and it still relies on the remaining parts of
of this framework. In particular, the servers' configuration this framework. In particular, the servers' configuration and
and startup are still facilitated by the modules which originate startup are still facilitated by the modules which originate
in BIND 10. These modules require at least Python 3.1 to run. in BIND 10. These modules require at least Python 3.1 to run.
They also work with Python 3.2 They also work with Python 3.2, 3.3 or 3.4 (<ulink
(<ulink url="http://www.python.org/"/>)). The dependency url="http://www.python.org/"/>). The dependency on Python will
on Python will be removed once a replacing configuration be removed once a replacing configuration and startup
and startup mechanisms are developed for Kea. At this point mechanisms are developed and released as Kea 0.9. At this
Kea will be written in pure C++. point Kea will be written in pure C++.
</para> </para>
<para> <para>
Kea uses the Botan crypto library for C++ Kea uses the Botan crypto library for C++
(<ulink url="http://botan.randombit.net/"/>). (<ulink url="http://botan.randombit.net/"/>).
It requires at least Botan version 1.8. It requires at least Botan version 1.8.
<!-- @todo 0.9/#2406: Add info about OpenSSL here -->
</para> </para>
<para> <para>
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 at least log4cplus version 1.0.3.
<!-- TODO: It is recommended to use at least version .... --> </para>
<para>
Kea can use MySQL headers and libraries to build MySQL database backend
that can be used to store leases. This is an optional dependency. When
it is missing, Kea will lack the ability to store leases in MySQL
database.
</para>
<para>
Kea can use PostgreSQL headers and libraries to build PostgreSQL
database backend that can be used to store leases. This is an optional
dependency. When it is missing, Kea will lack the ability to store
leases in PostgreSQL database.
</para> </para>
</section> </section>
<section id="starting_stopping"> <section id="starting_stopping">
<title>Starting and Stopping the Server</title> <title>Starting and Stopping the Server</title>
<!-- @todo: Rewrite this section as part of #3422-->
<para> <para>
Kea is modular. Part of this modularity is Kea is modular. Part of this modularity is
accomplished using multiple cooperating processes which, together, accomplished using multiple cooperating processes which, together,
provide the server functionality. provide the server functionality.
</para> </para>
<!-- todo: Rename processes here, once they are renamed in the source --> <!-- @todo: Rename processes here, once they are renamed in the source -->
<para> <para>
At first, running many different processes may seem confusing. At first, running many different processes may seem confusing.
However, these processes are started by running a single However, these processes are started by running a single
@@ -261,6 +266,7 @@
<section id="managing_once_running"> <section id="managing_once_running">
<title>Managing BIND 10</title> <title>Managing BIND 10</title>
<!-- @todo: Rewrite this section as part of #3422 -->
<para> <para>
Once BIND 10 is running, a few commands are used to interact Once BIND 10 is running, a few commands are used to interact
@@ -330,20 +336,20 @@ var/
<title>Quick start</title> <title>Quick start</title>
<para> <para>
This quickly covers the standard steps for installing This quickly covers the standard steps for installing and deploying Kea.
and deploying Kea. For further details, full customizations, and troubleshooting, see the
For further details, full customizations, and troubleshooting, respective chapters in the Kea guide.
see the respective chapters in the Kea guide.
</para> </para>
<section id="quick-start-dhcp6"> <section id="quick-start">
<title>Quick start guide for DHCPv6 service</title> <title>Quick start guide for DHCPv4 and DHCPv6 services</title>
<orderedlist> <orderedlist>
<listitem> <listitem>
<simpara> <simpara>
Install required run-time and build dependencies. Install required run-time and build dependencies. See <xref
linkend="build-requirements"/> for details.
</simpara> </simpara>
</listitem> </listitem>
@@ -360,7 +366,7 @@ var/
<para>Go into the source and run configure: <para>Go into the source and run configure:
<screen>$ <userinput>cd kea</userinput> <screen>$ <userinput>cd kea</userinput>
$ <userinput>autoreconf --install</userinput> $ <userinput>autoreconf --install</userinput>
$ <userinput>./configure</userinput></screen> $ <userinput>./configure [your extra parameters]</userinput></screen>
</para> </para>
</listitem> </listitem>
@@ -378,39 +384,35 @@ $ <userinput>./configure</userinput></screen>
</listitem> </listitem>
<listitem> <listitem>
<para>Change directory to the install prefix (by default <para>Edit your configuration file for DHCPv4. See doc/examples/kea4
<filename>/usr/local/</filename>): for set of examples.
<screen>$ <userinput>cd /usr/local/</userinput></screen>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para>Create a user for yourself: <para>Start Kea DHCPv4 server (as root):
<screen>$ <userinput>sbin/b10-cmdctl-usermgr add root</userinput></screen> <screen># <userinput>b10-dhcp4 -c /path/to/your/kea4/config/file.json</userinput></screen>
and enter a newly chosen password when prompted.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para>Start the server (as root): <para>Test it; for example, use the
<screen>$ <userinput>sbin/bind10</userinput></screen> <ulink url="http://www.isc.org/downloads/DHCP/">ISC DHCP client</ulink>
to send DHCPv4 queries to the server and verify that the client receives a
configuration from the server:
<screen>$ <userinput>dhclient -4 eth0</userinput></screen>
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para>DHCP components are not started in the default <para>Edit your configuration file for DHCPv6. See doc/examples/kea6
configuration. In another console, enable the DHCPv6 for set of examples.
service (by using the <command>bindctl</command> utility </para>
to configure the <command>b10-dhcp6</command> component to </listitem>
run): <screen>$ <userinput>bin/bindctl</userinput></screen>
(Login with the username and password you used above to create a user.) <listitem>
<screen> <para>Start Kea DHCPv6 server (as root):
&gt; <userinput>config add Init/components b10-dhcp6</userinput> <screen># <userinput>b10-dhcp6 -c /path/to/your/kea6/config/file.json</userinput></screen>
<!-- todo: Should the kind be needed or dispensable? -->
&gt; <userinput>config set Init/components/b10-dhcp6/kind dispensable</userinput>
&gt; <userinput>config commit</userinput>
&gt; <userinput>quit</userinput>
</screen>
</para> </para>
</listitem> </listitem>
@@ -419,9 +421,11 @@ $ <userinput>./configure</userinput></screen>
<ulink url="http://www.isc.org/downloads/DHCP/">ISC DHCP client</ulink> <ulink url="http://www.isc.org/downloads/DHCP/">ISC DHCP client</ulink>
to send DHCPv6 queries to the server and verify that the client receives a to send DHCPv6 queries to the server and verify that the client receives a
configuration from the server: configuration from the server:
<screen>$ <userinput>dhclient -6</userinput></screen> <screen>$ <userinput>dhclient -6 eth0</userinput></screen>
</para> </para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</section> </section>
@@ -435,17 +439,15 @@ $ <userinput>./configure</userinput></screen>
<title>Packages</title> <title>Packages</title>
<para> <para>
Some operating systems or software package vendors may Some operating systems or software package vendors may provide
provide ready-to-use, pre-built software packages for Kea. ready-to-use, pre-built software packages for Kea. Installing a
Installing a pre-built package means you do not need to pre-built package means you do not need to install build-only
install build-only prerequisites and do not need to prerequisites and do not need to <emphasis>make</emphasis> the software.
<emphasis>make</emphasis> the software.
</para> </para>
<para> <para>
FreeBSD ports, NetBSD pkgsrc, and Debian FreeBSD ports, NetBSD pkgsrc, and Debian <emphasis>testing</emphasis>
<emphasis>testing</emphasis> package collections provide package collections provide all the prerequisite packages.
all the prerequisite packages.
</para> </para>
</section> </section>
@@ -463,6 +465,7 @@ $ <userinput>./configure</userinput></screen>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<!-- @todo: 0.9: update this -->
<filename>etc/bind10/</filename> &mdash; <filename>etc/bind10/</filename> &mdash;
configuration files. configuration files.
</simpara> </simpara>
@@ -475,6 +478,7 @@ $ <userinput>./configure</userinput></screen>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<!-- @todo 0.9: update this -->
<filename>libexec/bind10/</filename> &mdash; <filename>libexec/bind10/</filename> &mdash;
executables that a user wouldn't normally run directly and executables that a user wouldn't normally run directly and
are not run independently. are not run independently.
@@ -490,12 +494,14 @@ $ <userinput>./configure</userinput></screen>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<!-- @todo 0.9: update this -->
<filename>share/bind10/</filename> &mdash; <filename>share/bind10/</filename> &mdash;
configuration specifications. configuration specifications.
</simpara> </simpara>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<!-- @todo 0.9: update this -->
<filename>share/doc/bind10/</filename> &mdash; <filename>share/doc/bind10/</filename> &mdash;
this guide and other supplementary documentation. this guide and other supplementary documentation.
</simpara> </simpara>
@@ -508,6 +514,7 @@ $ <userinput>./configure</userinput></screen>
</listitem> </listitem>
<listitem> <listitem>
<simpara> <simpara>
<!-- @todo 0.9: update this -->
<filename>var/bind10/</filename> &mdash; <filename>var/bind10/</filename> &mdash;
data source and configuration databases. data source and configuration databases.
</simpara> </simpara>
@@ -520,10 +527,9 @@ $ <userinput>./configure</userinput></screen>
<title>Building Requirements</title> <title>Building Requirements</title>
<para> <para>
In addition to the run-time requirements (listed in In addition to the run-time requirements (listed in <xref
<xref linkend="required-software"/>), building Kea linkend="required-software"/>), building Kea from source code requires
from source code requires various development include headers and various development include headers and program development tools.
program development tools.
</para> </para>
<note> <note>
@@ -548,6 +554,7 @@ $ <userinput>./configure</userinput></screen>
To build Kea, also install the Botan (at least version To build Kea, also install the Botan (at least version
1.8) and the log4cplus (at least version 1.0.3) 1.8) and the log4cplus (at least version 1.0.3)
development include headers. development include headers.
<!-- @todo: Add OpenSSL note here once #2406 is merged -->
</para> </para>
<!-- <!--
@@ -564,6 +571,7 @@ as a dependency earlier -->
standard development headers, make, and pkg-config. standard development headers, make, and pkg-config.
Kea builds have been tested with GCC g++ 3.4.3, 4.1.2, 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. 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>
<para> <para>
@@ -589,9 +597,10 @@ as a dependency earlier -->
<title>Download Tar File</title> <title>Download Tar File</title>
<para> <para>
Kea 0.8 is available as a part of BIND10 1.2 release, which is Kea 0.8 is available as a part of BIND10 1.2 release, which is a final
a final release of BIND10 from ISC. This release can be downloaded release of BIND10 from ISC. This release can be downloaded from:
from: <ulink url="ftp://ftp.isc.org/isc/bind10/"/>. <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> </para>
</section> </section>
@@ -680,8 +689,9 @@ as a dependency earlier -->
<varlistentry> <varlistentry>
<term>--with-pythonpath</term> <term>--with-pythonpath</term>
<listitem> <listitem>
<simpara>Define the path to Python 3.1 if it is not in the <simpara>Define the path to Python 3.x if it is not in the
standard execution path. standard execution path. Python 3.x is mandatory for Kea 0.8,
but is no longer required for upcoming Kea 0.9.
</simpara> </simpara>
</listitem> </listitem>
</varlistentry> </varlistentry>
@@ -725,8 +735,8 @@ as a dependency earlier -->
<screen>$ <userinput>./configure \ <screen>$ <userinput>./configure \
--with-boost-include=/usr/pkg/include \ --with-boost-include=/usr/pkg/include \
--with-pythonpath=/usr/pkg/bin/python3.1 \ --with-dhcp-pgsql=/usr/local/bin/pg_config \
--prefix=/opt/bind10</userinput></screen> --prefix=/opt/kea</userinput></screen>
</para> </para>
<para> <para>
@@ -782,18 +792,10 @@ as a dependency earlier -->
</note> </note>
</section> </section>
<!-- TODO: tests --> <!-- @todo: tests -->
</section> </section>
<!--
<section id="install.troubleshooting">
<title>Troubleshooting</title>
<para>
</para>
</section>
-->
</chapter> </chapter>
<chapter id="bind10"> <chapter id="bind10">