<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="admin"><info><title>Kea Database Administration</title></info>
-
<section xml:id="kea-database-version"><info><title>Databases and Database Version Numbers</title></info>
-
-
<para>
Kea supports storing leases and host reservations (i.e. static
assignments of addresses, prefixes and options) in one of
For example, Kea currently only stores lease information
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
+ structure will need to be updated to accommodate the extra
information.
</para>
</section>
<section xml:id="kea-admin"><info><title>The kea-admin Tool</title></info>
-
-
<para>
To manage the databases, Kea provides the
<command>kea-admin</command> tool. It is able to initialize
<listitem>
<simpara>
<command>lease-init</command> —
- Initializes a new lease database. This is useful during a new
+ 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 being
installed.
</section>
<section xml:id="supported-databases"><info><title>Supported Databases</title></info>
-
-
<para>The following table presents the capabilities of available
backends. Please refer to the specific sections dedicated to each backend to
better understand their capabilities and limitations. Choosing the right
backend may be essential for success or failure of your deployment.</para>
<para>
- <table frame="all" xml:id="backends"><info><title>List of available backends</title></info>
-
- <tgroup cols="2">
- <colspec colname="feature"/>
- <colspec colname="memfile"/>
- <colspec colname="mysql"/>
- <colspec colname="pgsql"/>
- <colspec colname="cql"/>
+ <table frame="all" id="backends">
+ <title>List of available backends</title>
+ <tgroup cols='5'>
+ <colspec colname='feature'/>
+ <colspec colname='memfile'/>
+ <colspec colname='mysql'/>
+ <colspec colname='pgsql'/>
+ <colspec colname='cql' colwidth='1.5*'/>
<thead>
<row>
<entry>Feature</entry>
<entry>Memfile</entry>
<entry>MySQL</entry>
<entry>PostgreSQL</entry>
- <entry>CQL(Cassandra)</entry>
+ <entry>CQL (Cassandra)</entry>
</row>
</thead>
<tbody>
<entry>no</entry>
<entry>yes</entry>
<entry>yes</entry>
- <entry>no</entry>
+ <entry>yes</entry>
</row>
<row>
<entry>no</entry>
<entry>yes</entry>
<entry>yes</entry>
- <entry>no</entry>
+ <entry>yes</entry>
</row>
</tbody>
</para>
<section><info><title>memfile</title></info>
-
-
<para>
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
</para>
<section xml:id="memfile-upgrade"><info><title>Upgrading Memfile Lease Files from an Earlier Version of Kea</title></info>
-
<para>
There are no special steps required to upgrade memfile lease files
from an earlier version of Kea to a new version of Kea.
</section>
<section><info><title>MySQL</title></info>
-
-
<para>
MySQL is able to store leases, host reservations and options defined on
a per host basis. This section can be safely ignored
</para>
<section xml:id="mysql-database-create"><info><title>First Time Creation of the MySQL Database</title></info>
-
-
<para>
If you are setting the MySQL database for the first time,
you need to create the database area within MySQL and set up
</section>
<section xml:id="mysql-upgrade"><info><title>Upgrading a MySQL Database from an Earlier Version of Kea</title></info>
-
-
<para>
Sometimes a new Kea version may use newer database schema, so
there will be a need to upgrade the existing database. This can
</section> <!-- end of MySQL sections -->
<section><info><title>PostgreSQL</title></info>
-
-
<para>
+ PostgreSQL is able to store leases, host reservations and options
+ defined on a per host basis.
A PostgreSQL database must be set up if you want Kea to store
lease and other information in PostgreSQL. This step can be
safely ignored if you are using other database backends.
</para>
<section xml:id="pgsql-database-create"><info><title>First Time Creation of the PostgreSQL Database</title></info>
-
-
<para>
The first task is to create both the lease database and the
user under which the servers will access it. A number of steps
</section>
<section><info><title>Initialize the PostgreSQL Database Using kea-admin</title></info>
-
<para>
If you elected not to create the tables manually, you can do
so now by running the <command>kea-admin</command> tool:
</para>
</section>
<section xml:id="pgsql-upgrade"><info><title>Upgrading a PostgreSQL Database from an Earlier Version of Kea</title></info>
-
<para>
The PostgreSQL database schema can be upgraded using the same tool and
commands as described in <xref linkend="mysql-upgrade"/>, with the
</section> <!-- end of PostgreSQL sections -->
<section><info><title>CQL (Cassandra)</title></info>
-
-
<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. 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.
+ 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>
<para>
</para>
<section xml:id="cql-database-create"><info><title>First Time Creation of the Cassandra Database</title></info>
-
-
<para>
If you are setting up the CQL database for the first time, you need to
create the keyspace area within CQL. This needs to be done manually:
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
<para>
- Export CQLSH_HOST environemnt variable:
+ Export CQLSH_HOST environment variable:
<screen>
$ <userinput>export CQLSH_HOST=localhost</userinput>
</screen>
</section>
<section xml:id="cql-upgrade"><info><title>Upgrading a CQL Database from an Earlier Version of Kea</title></info>
-
-
<para>
Sometimes a new Kea version may use newer database schema, so
there will be a need to upgrade the existing database. This can
</section> <!-- end of CQL sections -->
<section><info><title>Using Read-Only Databases with Host Reservations</title></info>
-
<para>If a read-only database is used for storing host reservations,
Kea must be explicitly configured to operate on the database in
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
+ such configuration may be required and how to configure Kea to
operate using a read-only host database.
</para>
</section>
<section><info><title>Limitations Related to the use of SQL Databases</title></info>
-
-
<para>
The lease expiration time is stored in the SQL database for each lease
as a timestamp value. Kea developers observed that MySQL database doesn't
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="classify"><info><title>Client Classification</title></info>
-
<section><info><title>Client Classification Overview</title></info>
-
<para>
In certain cases it is useful to differentiate between different
types of clients and treat them accordingly. Common reasons include:
</section>
<section xml:id="classification-using-host-reservations"><info><title>Using Static Host Reservations In Classification</title></info>
-
<para>Classes can be statically assigned to the clients using techniques described
in <xref linkend="reservation4-client-classes"/> and
<xref linkend="reservation6-client-classes"/>.
</section>
<section xml:id="classification-using-vendor"><info><title>Using Vendor Class Information In Classification</title></info>
-
<para>
The server checks whether an incoming DHCPv4 packet includes
the vendor class identifier option (60) or an incoming DHCPv6 packet
</section>
<section xml:id="classification-using-expressions"><info><title>Using Expressions In Classification</title></info>
-
<para>
The expression portion of classification contains operators and values.
All values are currently strings and operators take a string or strings and
<para>
<table frame="all" xml:id="classification-values-list"><info><title>List of Classification Values</title></info>
-
<tgroup cols="3">
<colspec colname="name"/>
<colspec colname="example"/>
<para>
<table frame="all" xml:id="classification-expressions-list"><info><title>List of Classification Expressions</title></info>
-
<tgroup cols="3">
<colspec colname="name"/>
<colspec colname="example"/>
</para>
<section><info><title>Logical operators</title></info>
-
The Not, And and Or logical operators are the common operators. Not
has the highest precedence and Or the lowest. And and Or are (left)
associative, parentheses around a logical expression can be used
</section>
<section><info><title>Substring</title></info>
-
The substring operator "substring(value, start, length)" accepts both positive and
negative values for the starting position and the length. For "start", a value of
0 is the first byte in the string while -1 is the last byte. If the starting
</screen>
</section>
<section><info><title>Concat</title></info>
-
The concat function "concat(string1, string2)" returns the
concatenation of its two arguments. For instance:
<screen>
</para> </note>
<section xml:id="classification-configuring"><info><title>Configuring Classes</title></info>
-
<para>
A class contains three items: a name, a test expression and option data.
The name must exist and must be unique amongst all classes. The test
</section>
<section xml:id="classification-subnets"><info><title>Configuring Subnets With Class Information</title></info>
-
<para>
In certain cases it beneficial to restrict access to certain subnets
only to clients that belong to a given class, using the "client-class"
</section>
<section><info><title>Using Classes</title></info>
-
<para>
Currently classes can be used for two functions. They can supply options
to the members of the class and they can be used to choose a subnet from which an
</section>
<section><info><title>Classes and Hooks</title></info>
-
<para>
You may use a hook to classify your packets. This may be useful if the
expression would either be complex or time consuming and be easier or
</section>
<section><info><title>Debugging Expressions</title></info>
-
<para>
While you are constructing your classification expressions you may
find it useful to enable logging see <xref linkend="logging"/> for
</para>
<para>
- To enable the debug statements in the classifciaton system you will
+ To enable the debug statements in the classification system you will
need to set the severity to "DEBUG" and the debug level to at least 55.
The specific loggers are "kea-dhcp4.eval" and "kea-dhcp6.eval".
</para>
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-config"><info><title>Kea Configuration</title></info>
-
<para>Kea is using JSON structures to handle configuration. Previously
we there was a concept of other configuration backends, but that never was
implemented and the idea was abandoned.</para>
<section xml:id="json"><info><title>JSON Configuration</title></info>
-
<para>JSON is notation used throughout the Kea project. The most obvious
usage is for configuration file, but it is also used for sending commands
over Management API (see <xref linkend="ctrl-channel"/>) and for
configuration file is specified upon startup using the -c parameter.</para>
<section xml:id="json-format"><info><title>JSON Syntax</title></info>
-
<para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined
in an extended JSON format. Basic JSON is defined in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7159">RFC 7159</link>. Note that Kea
1.2 introduces a new parser that is better at following the JSON spec. In
<itemizedlist>
<listitem>
<simpara>shell comments: any text after the hash (#)
- character is ignored. Dhcp6 allows # in any column, while
- Dhcp4 and Ddns require hash to be in the first
- column.</simpara>
+ character is ignored. Both Dhcp4 and Dhcp6 allow # in any column,
+ while Ddns requires hash to be in the first column.</simpara>
</listitem>
<listitem>
<simpara>C comments: any text after the double slashes (//)
- character is ignored. We're in a process of
- migrating the configuation parsers and currently only Dhcp6
- supports this feature.</simpara>
+ character is ignored. Both Dhcp4 and Dhcp6 supports this
+ feature.</simpara>
</listitem>
<listitem>
<simpara>Multiline comments: any text between /* and */ is
- ignored. This commenting can span multiple lines. We're in a
- process of migrating the configuation parsers and currently
- only Dhcp6 supports this feature.</simpara>
+ ignored. This commenting can span multiple lines. Both Dhcp4 and
+ Dhcp6 supports this feature.</simpara>
</listitem>
<listitem>
<simpara>File inclusion: JSON files can include other JSON
files. This can be done by using <?include
- "file.json"?>. We're in a process of migrating the
- configuation parsers and currently only Dhcp6 supports this
+ "file.json"?>. Both Dhcp4 and Dhcp6 supports this
feature.</simpara>
</listitem>
</itemizedlist>
</section>
<section><info><title>Simplified Notation</title></info>
-
-
<para>It is sometimes convenient to refer to a specific element in the
configuration hierarchy. Each hierarchy level is separated by a slash.
If there is an array, a specific instance within that array is referenced by
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ctrl-channel"><info><title>Management API</title></info>
-
<para>A classic approach to daemon configuration assumes that
the server's configuration is stored in configuration files
</para>
<section xml:id="ctrl-channel-syntax"><info><title>Data Syntax</title></info>
-
<para>Communication over the control channel is conducted using JSON
structures. If configured, Kea will open a socket and listen
for incoming connections. A process connecting to this socket
</section>
<section xml:id="ctrl-channel-client"><info><title>Using the Control Channel</title></info>
-
-
<para>Kea does not currently provide a client for using the control channel. The primary
reason for this is the expectation is that the entity using the control channel
is typically an IPAM or similar network management/monitoring software which
configuration file. Text passed to <command>socat</command>
will be sent to Kea and the responses received from Kea printed to standard output.</para>
- <para>It is also easy to open UNIX socket programmatically. An example of
+ <para>It is also easy to open UNIX socket programatically. An example of
such a simplistic client written in C is available in the Kea Developer's
Guide, chapter Control Channel Overview, section Using Control Channel.</para>
</section>
<section xml:id="commands-common"><info><title>Commands Supported by Both the DHCPv4 and DHCPv6 Servers</title></info>
-
-
<section xml:id="command-leases-reclaim"><info><title>leases-reclaim</title></info>
-
<para>
<emphasis>leases-reclaim</emphasis> command instructs the server to
reclaim all expired leases immediately. The command has the following
</section>
<section xml:id="command-list-commands"><info><title>list-commands</title></info>
-
-
<para>
The <emphasis>list-commands</emphasis> command retrieves a list of all
commands supported by the server. It does not take any arguments.
</section> <!-- end of command-list-commands -->
<section xml:id="command-shutdown"><info><title>shutdown</title></info>
-
-
<para>
The <emphasis>shutdown</emphasis> command instructs the server to initiate
its shutdown procedure. It is the equivalent of sending a SIGTERM signal
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dhcp-ddns-server"><info><title>The DHCP-DDNS Server</title></info>
-
+
<para>
The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts the client side of
the DDNS protocol (defined in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc2136">RFC 2136</link>)
simply disregard the reverse update portion of requests.
</para>
<section xml:id="dhcp-ddns-server-start-stop"><info><title>Starting and Stopping the DHCP-DDNS Server</title></info>
-
-
<para>
<command>kea-dhcp-ddns</command> is the Kea DHCP-DDNS server
and, due to the nature of DDNS, it is run alongside either the
</section> <!-- end start-stop -->
<section xml:id="d2-configuration"><info><title>Configuring the DHCP-DDNS Server</title></info>
-
<para>
Before starting <command>kea-dhcp-ddns</command> module for the
first time, a configuration file needs to be created. The following default
</listitem>
</itemizedlist>
<section xml:id="d2-server-parameter-config"><info><title>Global Server Parameters</title></info>
-
<itemizedlist>
<listitem><simpara>
</section> <!-- "d2-server-parameter-config" -->
<section xml:id="d2-tsig-key-list-config"><info><title>TSIG Key List</title></info>
-
<para>
A DDNS protocol exchange can be conducted with or without TSIG
(defined in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf/org/html/rfc2845">RFC
<!-- "d2-tsig-key-list-config" -->
<section xml:id="d2-forward-ddns-config"><info><title>Forward DDNS</title></info>
-
<para>
The Forward DDNS section is used to configure D2's forward update
behavior. Currently it contains a single parameter, the catalog of
the forward update portions of requests.
</para>
<section xml:id="add-forward-ddns-domain"><info><title>Adding Forward DDNS Domains</title></info>
-
<para>
A forward DDNS Domain maps a forward DNS zone to a set of
DNS servers which maintain the forward DNS data (i.e. name to
</para>
<section xml:id="add-forward-dns-servers"><info><title>Adding Forward DNS Servers</title></info>
-
<para>
This section describes how to add DNS servers to a Forward DDNS Domain.
Repeat them for as many servers as desired for a each domain.
</section> <!-- "d2-forward-ddns-config" -->
<section xml:id="d2-reverse-ddns-config"><info><title>Reverse DDNS</title></info>
-
<para>
The Reverse DDNS section is used to configure D2's reverse update
behavior, and the concepts are the same as for the forward DDNS
the reverse update portions of requests.
</para>
<section xml:id="add-reverse-ddns-domain"><info><title>Adding Reverse DDNS Domains</title></info>
-
<para>
A reverse DDNS Domain maps a reverse DNS zone to a set of DNS
servers which maintain the reverse DNS data (address to name
</para>
<section xml:id="add-reverse-dns-servers"><info><title>Adding Reverse DNS Servers</title></info>
-
<para>
This section describes how to add DNS servers to a Reverse DDNS Domain.
Repeat them for as many servers as desired for each domain.
</section> <!-- "d2-reverse-ddns-config" -->
- <section xml:id="d2-exmaple-config"><info><title>Example DHCP-DDNS Server Configuration</title></info>
-
+ <section xml:id="d2-example-config"><info><title>Example DHCP-DDNS Server Configuration</title></info>
<para>
This section provides an example DHCP-DDNS server configuration based
on a small example network. Let's suppose our example network has
three domains, each with their own subnet.
<table><info><title>Our example network</title></info>
-
<tgroup cols="4" align="left">
<colspec colname="domain"/>
<colspec colname="subnet"/>
<para>
We need to construct three forward DDNS Domains:
<table><info><title>Forward DDNS Domains Needed</title></info>
-
<tgroup cols="3" align="left">
<colspec colname="num"/>
<colspec colname="name"/>
<para>
Similarly, we need to construct the three reverse DDNS Domains:
<table><info><title>Reverse DDNS Domains Needed</title></info>
-
<tgroup cols="3" align="left">
<colspec colname="num"/>
<colspec colname="DDNS Domain name"/>
</section> <!-- end of "d2-example" -->
</section> <!-- end of section "d2-configuration" -->
<section><info><title>DHCP-DDNS Server Limitations</title></info>
-
<para>The following are the current limitations of the DHCP-DDNS Server.</para>
<itemizedlist>
<listitem>
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dhcp4"><info><title>The DHCPv4 Server</title></info>
-
<section xml:id="dhcp4-start-stop"><info><title>Starting and Stopping the DHCPv4 Server</title></info>
-
-
<para>
It is recommended that the Kea DHCPv4 server be started and stopped
using <command>keactrl</command> (described in <xref linkend="keactrl"/>).
</section>
<section xml:id="dhcp4-configuration"><info><title>DHCPv4 Server Configuration</title></info>
-
+
<section><info><title>Introduction</title></info>
-
<para>
This section explains how to configure the DHCPv4 server using the
Kea configuration backend. (Kea configuration using any other
</section>
<section><info><title>Lease Storage</title></info>
-
<para>All leases issued by the server are stored in the lease database.
Currently there are four database backends available: memfile (which is the
default backend), MySQL, PostgreSQL and Cassandra.</para>
-<section><info><title>Memfile - Basic Storage for Leases</title></info>
-
+<section><info><title>Memfile - Basic Storage for Leases</title></info>
<para>The server is able to store lease data in different repositories. Larger
deployments may elect to store leases in a database. <xref linkend="database-configuration4"/> describes this option. In typical
smaller deployments though, the server will store lease information in a CSV file rather
description of the LFC is located on the Kea wiki:
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/LFCDesign">http://kea.isc.org/wiki/LFCDesign</uri>.
</para>
-
</section>
<section xml:id="database-configuration4"><info><title>Lease Database Configuration</title></info>
-
-
<note>
<para>Lease database access information must be configured for the DHCPv4 server,
even if it has already been configured for the DHCPv6 server. The servers
</section>
<section xml:id="hosts4-storage"><info><title>Hosts Storage</title></info>
-
<para>Kea is also able to store information about host reservations in the
database. The hosts database configuration uses the same syntax as the lease
database. In fact, a Kea server opens independent connections for each
purpose, be it lease or hosts information. This arrangement gives the most
flexibility. Kea can be used to keep leases and host reservations
separately, but can also point to the same database. Currently the
- supported hosts database types are MySQL and PostgreSQL. The Cassandra
- backend does not support host reservations yet.</para>
+ supported hosts database types are MySQL, PostgreSQL and CQL (Cassandra).</para>
<para>Please note that usage of hosts storage is optional. A user can define
all host reservations in the configuration file. That is the recommended way
later, if necessary.</para>
<section xml:id="hosts-database-configuration4"><info><title>DHCPv4 Hosts Database Configuration</title></info>
-
-
<para>Hosts database configuration is controlled through the Dhcp4/hosts-database
parameters. If enabled, the type of the database must be set to "mysql" or
"postgresql". Other hosts backends may be added in later versions of Kea.
</section>
<section xml:id="dhcp4-interface-configuration"><info><title>Interface Configuration</title></info>
-
<para>The DHCPv4 server has to be configured to listen on specific network
interfaces. The simplest network interface configuration tells the server to
listen on all available interfaces:
</section>
<section xml:id="dhcpinform-unicast-issues"><info><title>Issues with Unicast Responses to DHCPINFORM</title></info>
-
<para>The use of UDP sockets has certain benefits in deployments
where the server receives only relayed traffic; these benefits are
mentioned in <xref linkend="dhcp4-interface-configuration"/>. From
</section>
<section xml:id="ipv4-subnet-id"><info><title>IPv4 Subnet Identifier</title></info>
-
<para>
The subnet identifier is a unique number associated with a particular subnet.
In principle, it is used to associate clients' leases with their respective subnets.
</section>
<section xml:id="dhcp4-address-config"><info><title>Configuration of IPv4 Address Pools</title></info>
-
<para>
The main role of a DHCPv4 server is address assignment. For this, the server has to
be configured with at least one subnet and one pool of dynamic addresses for it to manage.
</section>
<section xml:id="dhcp4-std-options"><info><title>Standard DHCPv4 Options</title></info>
-
<para>
One of the major features of the DHCPv4 server is to provide configuration
options to clients. Most of the options are sent by the server only if the
<para>
<table frame="all" xml:id="dhcp4-std-options-list"><info><title>List of standard DHCPv4 options</title></info>
-
<tgroup cols="5">
<colspec colname="name"/>
<colspec colname="code" align="center"/>
<para>
<table frame="all" xml:id="dhcp4-std-options-list-part2"><info><title>List of standard DHCPv4 options (continued)</title></info>
-
<tgroup cols="5">
<colspec colname="name"/>
<colspec colname="code" align="center"/>
</para>
<para>
<table frame="all" xml:id="dhcp-types"><info><title>List of standard DHCP option types</title></info>
-
<tgroup cols="2">
<colspec colname="name"/>
<colspec colname="meaning"/>
</section>
<section xml:id="dhcp4-custom-options"><info><title>Custom DHCPv4 options</title></info>
-
<para>Kea supports custom (non-standard) DHCPv4 options. Assume
that we want to define a new DHCPv4 option called "foo" which
will have a code 222 and will convey a single unsigned 32 bit
</section>
<section xml:id="dhcp4-vendor-opts"><info><title>DHCPv4 Vendor Specific Options</title></info>
-
<para>
Currently there are two option spaces defined for the DHCPv4 daemon:
"dhcp4" (for the top level DHCPv4 options) and
</section>
<section xml:id="dhcp4-option-spaces"><info><title>Nested DHCPv4 Options (Custom Option Spaces)</title></info>
-
-
<para>It is sometimes useful to define a completely new option
space. This is the case when user creates new option in the
standard option space ("dhcp4") and wants this option
</section>
<section xml:id="dhcp4-option-data-defaults"><info><title>Unspecified Parameters for DHCPv4 Option Configuration</title></info>
-
<para>In many cases it is not required to specify all parameters for
an option configuration and the default values may be used. However, it is
important to understand the implications of not specifying some of them
</section>
<section xml:id="dhcp4-stateless-configuration"><info><title>Stateless Configuration of DHCPv4 Clients</title></info>
-
<para>The DHCPv4 server supports the stateless client configuration whereby the
client has an IP address configured (e.g. using manual configuration) and only
contacts the server to obtain other configuration parameters, e.g. addresses of DNS servers.
</section>
<section xml:id="dhcp4-client-classifier"><info><title>Client Classification in DHCPv4</title></info>
-
<para>
The DHCPv4 server includes support for client classification. For a deeper
discussion of the classification process see <xref linkend="classify"/>.
</para></note>
<section><info><title>Setting Fixed Fields in Classification</title></info>
-
<para>
It is possible to specify that clients belonging to a particular class
should receive packets with specific values in certain fixed fields.
</section>
<section><info><title>Using Vendor Class Information in Classification</title></info>
-
<para>
The server checks whether an incoming packet includes the vendor class identifier
option (60). If it does, the content of that option is prepended with
</section>
<section><info><title>Defining and Using Custom Classes</title></info>
-
<para>
The following example shows how to configure a class using an expression
and a subnet that makes use of the class. This configuration defines the
</section>
<section xml:id="dhcp4-ddns-config"><info><title>DDNS for DHCPv4</title></info>
-
<para>
As mentioned earlier, kea-dhcp4 can be configured to generate requests to the
DHCP-DDNS server (referred to here as "D2" ) to update DNS entries. These requests are known as
</para>
<section xml:id="dhcpv4-d2-io-config"><info><title>DHCP-DDNS Server Connectivity</title></info>
-
<para>
In order for NCRs to reach the D2 server, kea-dhcp4 must be able
to communicate with it. kea-dhcp4 uses the following configuration
</para>
</section>
<section xml:id="dhcpv4-d2-rules-config"><info><title>When Does the kea-dhcp4 Server Generate DDNS Requests?</title></info>
-
<para>kea-dhcp4 follows the behavior prescribed for DHCP servers in
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc4702">RFC 4702</link>.
It is important to keep in mind that kea-dhcp4 provides the initial decision
in the following table:
</para>
<table xml:id="fqdn-flag-table"><info><title>Default FQDN Flag Behavior</title></info>
-
<tgroup cols="4" align="left">
<colspec colname="cflags"/>
<colspec colname="meaning"/>
</section>
<section xml:id="dhcpv4-fqdn-name-generation"><info><title>kea-dhcp4 name generation for DDNS update requests</title></info>
-
<para>Each NameChangeRequest must of course include the fully qualified domain
name whose DNS entries are to be affected. kea-dhcp4 can be configured to
supply a portion or all of that name based upon what it receives from
</section>
<section xml:id="dhcp4-next-server"><info><title>Next Server (siaddr)</title></info>
-
<para>In some cases, clients want to obtain configuration from a TFTP server.
Although there is a dedicated option for it, some devices may use the siaddr field
in the DHCPv4 packet for that purpose. That specific field can be configured
</section>
<section xml:id="dhcp4-echo-client-id"><info><title>Echoing Client-ID (RFC 6842)</title></info>
-
<para>The original DHCPv4 specification
(<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc2131">RFC 2131</link>)
states that the DHCPv4
</section>
<section xml:id="dhcp4-match-client-id"><info><title>Using Client Identifier and Hardware Address</title></info>
-
<para>The DHCP server must be able to identify the client (and distinguish it from
other clients) from which it receives the message. There are many reasons
why this identification is required and the most important ones are:
</section>
<section xml:id="dhcp4-dhcp4o6-config"><info><title>DHCPv4-over-DHCPv6: DHCPv4 Side</title></info>
-
<para>
The support of DHCPv4-over-DHCPv6 transport is described in
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7341">RFC 7341</link>
<!-- Host reservation is a large topic. There will be many subsections,
so it should be a section on its own. -->
<section xml:id="host-reservation-v4"><info><title>Host Reservation in DHCPv4</title></info>
-
-
<para>There are many cases where it is useful to provide a configuration on
a per host basis. The most obvious one is to reserve a specific, static
address for exclusive use by a given client (host) ‐ the returning client will
additional check incurs additional overhead.</para>
<section xml:id="reservation4-types"><info><title>Address Reservation Types</title></info>
-
-
<para>In a typical scenario there is an IPv4 subnet defined,
e.g. 192.0.2.0/24, with certain part of it dedicated for dynamic allocation
by the DHCPv4 server. That dynamic part is referred to as a dynamic pool or
</section>
<section xml:id="reservation4-conflict"><info><title>Conflicts in DHCPv4 Reservations</title></info>
-
<para>As the reservations and lease information are stored separately,
conflicts may arise. Consider the following series of events. The server
has configured the dynamic pool of addresses from the range of 192.0.2.10 to
</section>
<section xml:id="reservation4-hostname"><info><title>Reserving a Hostname</title></info>
-
<para>When the reservation for a client includes the <command>hostname</command>,
the server will return this hostname to the client in
the Client FQDN or Hostname options. The server responds with the Client
</section>
<section xml:id="reservation4-options"><info><title>Including Specific DHCPv4 Options in Reservations</title></info>
-
<para>Kea 1.1.0 introduced the ability to specify options on a
per host basis. The options follow the same rules as any other
options. These can be standard options (see <xref linkend="dhcp4-std-options"/>), custom options (see <xref linkend="dhcp4-custom-options"/>) or vendor specific options
</section>
<section xml:id="reservation4-message-fields"><info><title>Reserving Next Server, Server Hostname and Boot File Name</title></info>
-
<para>BOOTP/DHCPv4 messages include "siaddr", "sname" and "file" fields.
Even though, DHCPv4 includes corresponding options, such as option 66 and
option 67, some clients may not support these options. For this reason, server
</section>
<section xml:id="reservation4-client-classes"><info><title>Reserving Client Classes in DHCPv4</title></info>
-
<para><xref linkend="classification-using-expressions"/> explains how
to configure the server to assign classes to a client based on the content
of the options that this client sends to the server. Host reservations
</screen>
- <para>Static class assignments, as shown above, can be used in conjuction
+ <para>Static class assignments, as shown above, can be used in conjunction
with classification using expressions.</para>
</section>
- <section xml:id="reservations4-mysql-pgsql"><info><title>Storing Host Reservations in MySQL or PostgreSQL</title></info>
-
-
+ <section xml:id="reservations4-mysql-pgsql"><info><title>Storing Host Reservations in MySQL, PostgreSQL or CQL (Cassandra)</title></info>
<para>
- It is possible to store host reservations in MySQL or PostgreSQL database. See
+ It is possible to store host reservations in MySQL, PostgreSQL or Cassandra. See
<xref linkend="hosts4-storage"/> for information on how to configure Kea to use
- reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated
+ reservations stored in MySQL, PostgreSQL or Cassandra. Kea does not provide any dedicated
tools for managing reservations in a database. The Kea wiki <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/HostReservationsHowTo">http://kea.isc.org/wiki/HostReservationsHowTo</uri> provides detailed
information and examples of how reservations can be inserted into the
database.
arbitrarily set to 4096 bytes.</simpara></note>
</section>
- <section xml:id="reservations4-cql"><info><title>Storing host reservations in CQL (Cassandra)</title></info>
-
- <para>Kea currently does not support storing reservations in
- Cassandra (CQL).</para>
+ <section xml:id="reservations4-pgsql"><info><title>Storing host reservations in PostgreSQL</title></info>
+ <para>
+ It is possible to store host reservations in PostgreSQL. See <xref linkend="hosts4-storage"/> for information on how to configure Kea to
+ use reservations stored in PostgreSQL. Kea does not provide any
+ dedicated tools for managing PostgreSQL reservations. See Kea wiki
+ <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/HostReservationsHowTo">http://kea.isc.org/wikiHostReservationsHowTo</uri> for
+ detailed information and examples of how reservations can be inserted
+ into the database.
+ </para>
</section>
+ <section xml:id="reservations4-cql"><info><title>Storing host reservations in Cassandra CQL</title></info>
+ <para>
+ It is possible to store host reservations in Cassandra CQL. See <xref linkend="hosts4-storage"/> for information on how to configure Kea to
+ use reservations stored in Cassandra CQL. Kea does not provide any
+ dedicated tools for managing Cassandra CQL reservations. See Kea wiki
+ <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/HostReservationsHowTo">http://kea.isc.org/wiki/HostReservationsHowTo</uri>
+ detailed information and examples of how reservations can be inserted
+ into the database.
+ </para>
+ </section>
<section xml:id="reservations4-tuning"><info><title>Fine Tuning DHCPv4 Host Reservation</title></info>
-
-
<para>The host reservation capability introduces additional restrictions for the
allocation engine (the component of Kea that selects an address for a client)
during lease selection and renewal. In particular, three
<!-- end of host reservations section -->
<section xml:id="dhcp4-serverid"><info><title>Server Identifier in DHCPv4</title></info>
-
<para>
The DHCPv4 protocol uses a "server identifier" to allow clients
to discriminate between several servers present on the same link: this
</section>
<section xml:id="dhcp4-subnet-selection"><info><title>How the DHCPv4 Server Selects a Subnet for the Client</title></info>
-
<para>
The DHCPv4 server differentiates between the directly connected clients,
clients trying to renew leases and clients sending their messages through
</note>
<section xml:id="dhcp4-relay-override"><info><title>Using a Specific Relay Agent for a Subnet</title></info>
-
<para>
A relay has to have an interface connected to the link on which
the clients are being configured. Typically the relay has an IPv4
</section>
<section xml:id="dhcp4-srv-example-client-class-relay"><info><title>Segregating IPv4 Clients in a Cable Network</title></info>
-
<para>
In certain cases, it is useful to mix relay address information,
introduced in <xref linkend="dhcp4-relay-override"/> with client
</section>
<section xml:id="dhcp4-decline"><info><title>Duplicate Addresses (DHCPDECLINE Support)</title></info>
-
-
<para>The DHCPv4 server is configured with a certain pool of addresses
that it is expected to hand out to the DHCPv4 clients. It is
assumed that the server is authoritative and has complete jurisdiction
</section>
<section xml:id="dhcp4-stats"><info><title>Statistics in the DHCPv4 Server</title></info>
-
<note>
<para>This section describes DHCPv4-specific statistics. For a general
overview and usage of statistics, see <xref linkend="stats"/>.</para>
The DHCPv4 server supports the following statistics:
</para>
<table frame="all" xml:id="dhcp4-statistics"><info><title>DHCPv4 Statistics</title></info>
-
<tgroup cols="3">
<colspec colname="statistic" align="center"/>
<colspec colname="type" align="center"/>
</section>
<section xml:id="dhcp4-ctrl-channel"><info><title>Management API for the DHCPv4 Server</title></info>
-
<para>
The management API allows the issuing of specific
management commands, such as statistics retrieval, reconfiguration or shutdown.
</section>
<section xml:id="dhcp4-std"><info><title>Supported DHCP Standards</title></info>
-
<para>The following standards are currently supported:</para>
<itemizedlist>
<listitem>
</section>
<section><info><title>User context in IPv4 pools</title></info>
-
<para>
Kea allows loading hook libraries that sometimes could benefit from
additional parameters. If such a parameter is specific to the whole
</section>
<section xml:id="dhcp4-limit"><info><title>DHCPv4 Server Limitations</title></info>
-
<para>These are the current limitations of the DHCPv4 server
software. Most of them are reflections of the current stage of
development and should be treated as <quote>not implemented
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dhcp6"><info><title>The DHCPv6 Server</title></info>
-
<section xml:id="dhcp6-start-stop"><info><title>Starting and Stopping the DHCPv6 Server</title></info>
-
-
<para>
It is recommended that the Kea DHCPv6 server be started and stopped
using <command>keactrl</command> (described in <xref linkend="keactrl"/>).
</section>
<section xml:id="dhcp6-configuration"><info><title>DHCPv6 Server Configuration</title></info>
-
+
<section><info><title>Introduction</title></info>
-
<para>
This section explains how to configure the DHCPv6 server using the
Kea configuration backend. (Kea configuration using any other
</section>
<section><info><title>Lease Storage</title></info>
-
<para>All leases issued by the server are stored in the lease database.
Currently there are four database backends available: memfile (which is the
default backend), MySQL, PostgreSQL and Cassandra.</para>
-<section><info><title>Memfile - Basic Storage for Leases</title></info>
-
+<section><info><title>Memfile - Basic Storage for Leases</title></info>
<para>The server is able to store lease data in different repositories. Larger
deployments may elect to store leases in a database. <xref linkend="database-configuration6"/> describes this option. In typical
smaller deployments though, the server will store lease information in a CSV file rather
description of the LFC is located on the Kea wiki:
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/LFCDesign">http://kea.isc.org/wiki/LFCDesign</uri>.
</para>
-
</section>
<section xml:id="database-configuration6"><info><title>Lease Database Configuration</title></info>
-
-
<note>
<para>Lease database access information must be configured for the DHCPv6 server,
even if it has already been configured for the DHCPv4 server. The servers
If there is no password to the account, set the password to the empty string
"". (This is also the default.)</para>
</section>
+
</section>
<section xml:id="hosts6-storage"><info><title>Hosts Storage</title></info>
-
<para>Kea is also able to store information about host reservations in the
database. The hosts database configuration uses the same syntax as the lease
database. In fact, a Kea server opens independent connections for each
later, if necessary.</para>
<section xml:id="hosts-database-configuration6"><info><title>DHCPv6 Hosts Database Configuration</title></info>
-
-
<para>Hosts database configuration is controlled through the Dhcp6/hosts-database
parameters. If enabled, the type of the database must be set to "mysql" or
"postgresql". Other hosts backends may be added in later version of Kea.
<section xml:id="dhcp6-interface-selection"><info><title>Interface Selection</title></info>
-
<para>The DHCPv6 server has to be configured to listen on specific network
interfaces. The simplest network interface configuration instructs the server to
listen on all available interfaces:
</section>
<section xml:id="ipv6-subnet-id"><info><title>IPv6 Subnet Identifier</title></info>
-
<para>
The subnet identifier is a unique number associated with a particular subnet.
In principle, it is used to associate clients' leases with their respective subnets.
</section>
<section xml:id="dhcp6-unicast"><info><title>Unicast Traffic Support</title></info>
-
<para>
When the DHCPv6 server starts, by default it listens to the DHCP traffic
sent to multicast address ff02::1:2 on each interface that it is
</section>
<section xml:id="dhcp6-address-config"><info><title>Subnet and Address Pool</title></info>
-
<para>
The main role of a DHCPv6 server is address assignment. For this,
the server has to be configured with at least one subnet and one pool of dynamic
</section>
<section><info><title>Subnet and Prefix Delegation Pools</title></info>
-
<para>
Subnets may also be configured to delegate prefixes, as defined in
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc3633">RFC 3633</link>. A
</section>
<section xml:id="pd-exclude-option"><info><title>Prefix Exclude Option</title></info>
-
<para>
For each delegated prefix the delegating router may choose to exclude
a single prefix out of the delegated prefix as specified in the
</section>
<section xml:id="dhcp6-std-options"><info><title>Standard DHCPv6 Options</title></info>
-
<para>
One of the major features of a DHCPv6 server is to provide configuration
options to clients. Although there are several options that require
<para>
<table frame="all" xml:id="dhcp6-std-options-list"><info><title>List of Standard DHCPv6 Options</title></info>
-
<tgroup cols="4">
<colspec colname="name"/>
<colspec colname="code" align="center"/>
<row><entry>s46-br</entry><entry>90</entry><entry>ipv6-address</entry><entry>false</entry></row>
<row><entry>s46-dmr</entry><entry>91</entry><entry>ipv6-prefix</entry><entry>false</entry></row>
<row><entry>s46-v4v6bind</entry><entry>92</entry><entry>record (ipv4-address, ipv6-prefix)</entry><entry>false</entry></row>
-<row><entry>s46-portparams</entry><entry>93</entry><entry>record(uint8, psid)</entry><entry>false</entry></row>
+<row><entry>s46-portparams</entry><entry>93</entry><entry>record (uint8, psid)</entry><entry>false</entry></row>
<row><entry>s46-cont-mape</entry><entry>94</entry><entry>empty</entry><entry>false</entry></row>
<row><entry>s46-cont-mapt</entry><entry>95</entry><entry>empty</entry><entry>false</entry></row>
<row><entry>s46-cont-lw</entry><entry>96</entry><entry>empty</entry><entry>false</entry></row>
<para>
<table frame="all" xml:id="dhcp6-exp-options-list"><info><title>List of Experimental DHCPv6 Options</title></info>
-
<tgroup cols="4">
<colspec colname="name"/>
<colspec colname="code" align="center"/>
</section>
<section xml:id="s46-options"><info><title>Common Softwire46 Options</title></info>
-
<para>
Softwire46 options are involved in IPv4 over IPv6 provisioning by
means of tunneling or translation as specified in the
</para>
<section xml:id="s46-containers"><info><title>Softwire46 Container Options</title></info>
-
<para>
S46 container options group rules and optional port parameters
for a specified domain. There are three container options specified
in the "dhcp6" (top level) option space: MAP-E Container option,
- MAP-T Container option and S46 Lieghtweight 4over6 Container option.
+ MAP-T Container option and S46 Lightweight 4over6 Container option.
These options only contain encapsulated options specified below.
They do not include any data fields.
</para>
</section>
<section><info><title>S46 Rule Option</title></info>
-
<para>
The S46 Rule option is used for conveying the Basic Mapping Rule (BMR)
and Forwarding Mapping Rule (FMR).
</para>
</section>
<section><info><title>S46 BR Option</title></info>
-
<para>
The S46 BR option is used to convey the IPv6 address of the
Border Relay. This option is mandatory in the MAP-E
</section>
<section><info><title>S46 DMR Option</title></info>
-
<para>
The S46 DMR option is used to convey values for the Default
Mapping Rule (DMR). This option is mandatory in the MAP-T
</section>
<section><info><title>S46 IPv4/IPv6 Address Binding option.</title></info>
-
<para>
The S46 IPv4/IPv6 Address Binding option may be used to specify
the full or shared IPv4 address of the Customer Edge (CE).
</para>
</section>
<section><info><title>S46 Port Parameters</title></info>
-
<para>
The S46 Port Parameters option specifies optional port set
information that MAY be provided to CEs
</section>
<section xml:id="dhcp6-custom-options"><info><title>Custom DHCPv6 Options</title></info>
-
<para>It is possible to define options in addition to the standard ones.
Assume that we want to define a new DHCPv6 option called "foo" which will have
code 100 and which will convey a single unsigned 32 bit integer value. We can define
</section>
<section xml:id="dhcp6-vendor-opts"><info><title>DHCPv6 Vendor-Specific Options</title></info>
-
<para>
Currently there are two option spaces defined for the DHCPv6
daemon: "dhcp6" (for top level DHCPv6 options) and "vendor-opts-space",
</section>
<section xml:id="dhcp6-option-spaces"><info><title>Nested DHCPv6 Options (Custom Option Spaces)</title></info>
-
<para>It is sometimes useful to define completely new option
spaces. This is useful if the user wants their new option to
convey sub-options that use a separate numbering scheme, for
</section>
<section xml:id="dhcp6-option-data-defaults"><info><title>Unspecified Parameters for DHCPv6 Option Configuration</title></info>
-
<para>In many cases it is not required to specify all parameters for
an option configuration and the default values can be used. However, it is
important to understand the implications of not specifying some of them
</section>
<section xml:id="dhcp6-config-subnets"><info><title>IPv6 Subnet Selection</title></info>
-
<para>
The DHCPv6 server may receive requests from local (connected to the
same subnet as the server) and remote (connecting via relays) clients.
</section>
<section xml:id="dhcp6-rapid-commit"><info><title>Rapid Commit</title></info>
-
<para>The Rapid Commit option, described in
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc3315">RFC 3315</link>, is supported
by the Kea DHCPv6 server. However, support is disabled by default for
</section>
<section xml:id="dhcp6-relays"><info><title>DHCPv6 Relays</title></info>
-
<para>
A DHCPv6 server with multiple subnets defined must select the
appropriate subnet when it receives a request from a client. For clients
</section>
<section xml:id="dhcp6-rsoo"><info><title>Relay-Supplied Options</title></info>
-
<para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc6422">RFC 6422</link>
defines a mechanism called Relay-Supplied DHCP Options. In certain cases relay
agents are the only entities that may have specific information. They can
</section>
<section xml:id="dhcp6-client-classifier"><info><title>Client Classification in DHCPv6</title></info>
-
-
<para>
The DHCPv6 server includes support for client classification. For a deeper
discussion of the classification process see <xref linkend="classify"/>.
</para></note>
<section><info><title>Defining and Using Custom Classes</title></info>
-
<para>
The following example shows how to configure a class using an expression
and a subnet making use of that class. This configuration defines the
</section>
<section xml:id="dhcp6-ddns-config"><info><title>DDNS for DHCPv6</title></info>
-
<para>
As mentioned earlier, kea-dhcp6 can be configured to generate requests to
the DHCP-DDNS server (referred to here as "D2") to update
<section xml:id="dhcpv6-d2-io-config"><info><title>DHCP-DDNS Server Connectivity</title></info>
-
<para>
In order for NCRs to reach the D2 server, kea-dhcp6 must be able
to communicate with it. kea-dhcp6 uses the following configuration
</para>
</section>
<section xml:id="dhcpv6-d2-rules-config"><info><title>When Does kea-dhcp6 Generate a DDNS Request?</title></info>
-
<para>kea-dhcp6 follows the behavior prescribed for DHCP servers in
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc4704">RFC 4704</link>.
It is important to keep in mind that kea-dhcp6 provides the initial
as shown in the following table:
</para>
<table xml:id="dhcp6-fqdn-flag-table"><info><title>Default FQDN Flag Behavior</title></info>
-
<tgroup cols="4" align="left">
<colspec colname="cflags"/>
<colspec colname="meaning"/>
</screen>
</section>
<section xml:id="dhcpv6-fqdn-name-generation"><info><title>kea-dhcp6 Name Generation for DDNS Update Requests</title></info>
-
<para>Each NameChangeRequest must of course include the fully qualified
domain name whose DNS entries are to be affected. kea-dhcp6 can be
configured to supply a portion or all of that name based upon what it
</section>
<section xml:id="dhcp6-dhcp4o6-config"><info><title>DHCPv4-over-DHCPv6: DHCPv6 Side</title></info>
-
<para>
The support of DHCPv4-over-DHCPv6 transport is described in
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7341">RFC 7341</link>
<!-- Host reservation is a large topic. There will be many subsections,
so it should be a section on its own. -->
<section xml:id="host-reservation-v6"><info><title>Host Reservation in DHCPv6</title></info>
-
-
<para>There are many cases where it is useful to provide a configuration on
a per host basis. The most obvious one is to reserve specific, static IPv6
address or/and prefix for exclusive use by a given client (host) ‐ returning
additional check incurs additional overhead.</para>
<section xml:id="reservation6-types"><info><title>Address/Prefix Reservation Types</title></info>
-
-
<para>In a typical scenario there is an IPv6 subnet defined with a certain
part of it dedicated for dynamic address allocation by the DHCPv6
server. There may be an additional address space defined for prefix
</section>
<section xml:id="reservation6-conflict"><info><title>Conflicts in DHCPv6 Reservations</title></info>
-
<para>As reservations and lease information are stored separately,
conflicts may arise. Consider the following series of events. The server
has configured the dynamic pool of addresses from the range of 2001:db8::10
</section>
<section xml:id="reservation6-hostname"><info><title>Reserving a Hostname</title></info>
-
<para>When the reservation for the client includes the <command>hostname</command>,
the server will assign this hostname to the client and send
it back in the Client FQDN, if the client sent the FQDN option to the
</section>
<section xml:id="reservation6-options"><info><title>Including Specific DHCPv6 Options in Reservations</title></info>
-
<para>Kea 1.1.0 introduced the ability to specify options on a
per host basis. The options follow the same rules as any other
options. These can be standard options (see <xref linkend="dhcp6-std-options"/>), custom options (see <xref linkend="dhcp6-custom-options"/>) or vendor specific options
</section>
<section xml:id="reservation6-client-classes"><info><title>Reserving Client Classes in DHCPv6</title></info>
-
<para>The <xref linkend="classification-using-expressions"/> explains how
to configure the server to assign classes to a client based on the content
of the options that this client sends to the server. Host reservations
}
</screen>
- <para>Static class assignments, as shown above, can be used in conjuction
+ <para>Static class assignments, as shown above, can be used in conjunction
with classification using expressions.</para>
</section>
- <section xml:id="reservations6-mysql-pgsql"><info><title>Storing Host Reservations in MySQL or PostgreSQL</title></info>
-
-
+ <section xml:id="reservations6-mysql-pgsql-cql"><info><title>Storing Host Reservations in MySQL, PostgreSQL or CQL (Cassandra)</title></info>
<para>
- It is possible to store host reservations in MySQL or PostgreSQL. See <xref linkend="hosts6-storage"/> for information on how to configure Kea to use
+ It is possible to store host reservations in MySQL, PostgreSQL or Cassandra. See
+ <xref linkend="hosts6-storage"/> for information on how to configure Kea to use
reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated
- tools for managing reservations in a database. The Kea wiki <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/HostReservationsHowTo">http://kea.isc.org/wiki/HostReservationsHowTo</uri> provides detailed
+ tools for managing reservations in a database. The Kea wiki
+ <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/HostReservationsHowTo">http://kea.isc.org/wiki/HostReservationsHowTo</uri>
+ provides detailed
information and examples of how reservations can be inserted into the
database.
</para>
</section>
<section xml:id="reservations6-cql"><info><title>Storing Host Reservations in CQL (Cassandra)</title></info>
-
<para>Kea currently does not support storing reservations in
Cassandra (CQL).</para>
</section>
<section xml:id="reservations6-tuning"><info><title>Fine Tuning DHCPv6 Host Reservation</title></info>
-
-
<para>The host reservation capability introduces additional restrictions for the
allocation engine (the component of Kea that selects an address for a client)
during lease selection and renewal. In particular, three
<!-- end of host reservations section -->
<section xml:id="dhcp6-serverid"><info><title>Server Identifier in DHCPv6</title></info>
-
<para>The DHCPv6 protocol uses a "server identifier" (also known
as a DUID) for clients to be able to discriminate between several
servers present on the same link.
</section>
<section xml:id="stateless-dhcp6"><info><title>Stateless DHCPv6 (Information-Request Message)</title></info>
-
<para>Typically DHCPv6 is used to assign both addresses and options. These
assignments (leases) have state that changes over time, hence
their name, stateful. DHCPv6 also supports a stateless mode,
</section>
<section xml:id="dhcp6-rfc7550"><info><title>Support for RFC 7550</title></info>
-
<para>The <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7550">RFC 7550</link>
introduced some changes to the DHCPv6 protocol to resolve a few issues
with the coexistence of multiple stateful options in the messages sent
</section>
<section xml:id="dhcp6-relay-override"><info><title>Using Specific Relay Agent for a Subnet</title></info>
-
<para>
The relay has to have an interface connected to the link on which
the clients are being configured. Typically the relay has a global IPv6
</section>
<section xml:id="dhcp6-client-class-relay"><info><title>Segregating IPv6 Clients in a Cable Network</title></info>
-
<para>
In certain cases, it is useful to mix relay address information,
introduced in <xref linkend="dhcp6-relay-override"/> with client
</section>
<section xml:id="mac-in-dhcpv6"><info><title>MAC/Hardware Addresses in DHCPv6</title></info>
-
<para>MAC/hardware addresses are available in DHCPv4 messages
from the clients and administrators
frequently use that information to perform certain tasks, like per host
</section>
<section xml:id="dhcp6-decline"><info><title>Duplicate Addresses (DECLINE Support)</title></info>
-
-
<para>The DHCPv6 server is configured with a certain pool of
addresses that it is expected to hand out to the DHCPv6 clients.
It is assumed that the server is authoritative and has complete
</section>
<section xml:id="dhcp6-stats"><info><title>Statistics in the DHCPv6 Server</title></info>
-
<note>
<para>This section describes DHCPv6-specific statistics. For a general
overview and usage of statistics, see <xref linkend="stats"/>.</para>
The DHCPv6 server supports the following statistics:
</para>
<table frame="all" xml:id="dhcp6-statistics"><info><title>DHCPv6 Statistics</title></info>
-
<tgroup cols="3">
<colspec colname="statistic" align="center"/>
<colspec colname="type" align="center"/>
</section>
<section xml:id="dhcp6-ctrl-channel"><info><title>Management API for the DHCPv6 Server</title></info>
-
<para>
The management API allows the issuing of specific
management commands, such as statistics retrieval, reconfiguration or shutdown.
<section><info><title>User context in IPv6 pools</title></info>
-
<para>
Kea allows loading hook libraries that sometimes could benefit from
additional parameters. If such a parameter is specific to the whole
</section>
<section xml:id="dhcp6-std"><info><title>Supported DHCPv6 Standards</title></info>
-
<para>The following standards are currently
supported:</para>
<itemizedlist>
</section>
<section xml:id="dhcp6-limit"><info><title>DHCPv6 Server Limitations</title></info>
-
<para> These are the current limitations of the DHCPv6 server
software. Most of them are reflections of the early stage of
development and should be treated as <quote>not implemented
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="faq"><info><title>Frequently Asked Questions</title></info>
-
<para>This chapter contains a number of frequently asked questions and
troubleshooting tips. It currently lacks content, but it is expected to grow
it in the known issues list. -->
<section xml:id="faq-generic"><info><title>General Frequently Asked Questions</title></info>
-
<section xml:id="q1-generic"><info><title>Where did the Kea name came from?</title></info>
-
-
<para>Kea is the name of a high mountain parrot living in New Zealand.
See this <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://lists.isc.org/pipermail/kea-users/2014-October/000032.html">https://lists.isc.org/pipermail/kea-users/2014-October/000032.html</uri>
for an extended answer.</para>
-
</section>
<section xml:id="q2-generic"><info><title>Feature X is not supported yet. When/if will it be available?</title></info>
-
-
<para>Kea is developed by a small team of engineers. Our resources are
limited, so we need to prioritize requests. The complexity of a new
feature (how difficult it is to implement a feature and how likely it
</section>
<section xml:id="faq-dhcp4"><info><title>Frequently Asked Questions about DHCPv4</title></info>
-
<section iq="q1-dhcp4"><info><title>I set up a firewall, but the Kea server still receives the traffic. Why?</title></info>
-
-
<para>Any DHCPv4 server must be able to receive from and send traffic to
hosts that don't have an IPv4 address assigned yet. That is typically not
possible with regular UDP sockets, therefore the Kea DHCPv4 server uses raw
</section> <!-- end of DHCPv4 FAQ section -->
<section xml:id="faq-dhcp6"><info><title>Frequently Asked Questions about DHCPv6</title></info>
-
<section iq="q1-dhcp6"><info><title>Kea DHCPv6 doesn't seem to get incoming traffic. I checked with tcpdump (or other traffic
capture software) that the incoming traffic is reaching the box. What's wrong?</title></info>
-
-
<para>Please check whether your OS has any IPv6 filtering rules. Many
operating systems are shipped with firewalls that discard incoming IPv6
traffic by default. In particular, many Linux distributions do that. Please
</section> <!-- end of DHCPv6 FAQ section -->
-
</chapter>
\ No newline at end of file
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="hooks-libraries"><info><title>Hooks Libraries</title></info>
-
+
<section xml:id="hooks-libraries-introduction"><info><title>Introduction</title></info>
-
+
<para>
Although Kea offers a lot of flexibility, there may be cases where
its behavior needs customisation. To accommodate this possibility,
Developer's Guide</link>.
</para>
</section> <!-- end Introduction -->
+
<section><info><title>Configuring Hooks Libraries</title></info>
-
<para>
The hooks libraries for a given process are configured using the
<command>hooks-libraries</command> keyword in the
</section>
<section><info><title>Available Hooks Libraries</title></info>
-
<para>
As described above, the hooks functionality provides a way to customize
a Kea server without modifying the core code. ISC has chosen to take
<para>Currently the following libraries are available or planned from ISC:
<table frame="all" xml:id="hook-libs"><info><title>List of available hooks libraries</title></info>
-
<tgroup cols="3">
<colspec colname="name"/>
<colspec colname="avail"/>
listed there, please send a note to the kea-users or kea-dev
mailing lists and someone will update it.
</para>
+
<section><info><title>user_chk: Checking User Access</title></info>
-
<para>
The user_chk library is the first hooks library published by ISC. It
attempts to serve several purposes:
</itemizedlist>
</para>
<para>
- Once loaded, the library allows segregating incomings requests into
+ Once loaded, the library allows segregating incoming requests into
known and unknown clients. For known clients, the packets are
processed mostly as usual, except it is possible to override certain
options being sent. That can be done on a per host basis. Clients
is "HW_ADDR" for IPv4 users or "DUID" for IPv6
users</para></listitem>
<listitem><para><command>id</command>, whose value is
- either the hardware address or the DUID from the equest
+ either the hardware address or the DUID from the request
formatted as a string of hex digits, with or without
":" delimiters.</para></listitem>
</itemizedlist>
our general entries in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/">Hooks
Framework section</link> should give you some pointers how to extend
this library and perhaps even write your own from scratch.</para>
-
</section>
+
<section><info><title>Forensic Logging Hooks</title></info>
-
<para>
This section describes the forensic log hooks library. This library
- povides hooks that record a detailed log of lease assignments
+ provides hooks that record a detailed log of lease assignments
and renewals into a set of log files. Currently this library
is only available to ISC customers with a support contract.
</para>
features those users who don't need to log this information can
leave it out and avoid any performance penalties.
</para>
+
<section><info><title>Log File Naming</title></info>
-
<para>
The names for the log files have the following form:
</para>
be distinct. See the examples in <xref linkend="forensic-log-configuration"/>.
</para></note>
</section>
+
<section><info><title>DHCPv4 Log Entries</title></info>
-
<para>
For DHCPv4 the library creates entries based on DHCPREQUEST messages
and corresponding DHCPv4 leases intercepted by lease4_select
</screen>
</para>
</section>
+
<section><info><title>DHCPv6 Log Entries</title></info>
-
<para>
For DHCPv6 the library creates entries based on lease management
actions intercepted by the lease6_select (for new leases), lease6_renew
</screen>
</para>
</section>
+
<section xml:id="forensic-log-configuration"><info><title>Configuring the Forensic Log Hooks</title></info>
-
<para>
To use this functionality the hook library must be included in the
configuration of the desired DHCP server modules. The legal_log
</section>
</section>
</section>
+
<section xml:id="user-context"><info><title>User contexts</title></info>
-
<para>Hook libraries can have their own configuration parameters. That is
convenient if the parameter applies to the whole library. However,
sometimes it is very useful if certain configuration entities are extended
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="installation"><info><title>Installation</title></info>
-
<section xml:id="packages"><info><title>Packages</title></info>
-
-
<para>
Some operating systems or software package vendors may provide
ready-to-use, pre-built software packages for Kea. Installing a
</section>
<section xml:id="install-hierarchy"><info><title>Installation Hierarchy</title></info>
-
<para>
The following is the directory layout of the complete Kea installation.
(All directory paths are relative to the installation directory):
</section>
<section xml:id="build-requirements"><info><title>Building Requirements</title></info>
-
-
<para>
In addition to the run-time requirements (listed in <xref linkend="required-software"/>), building Kea from source code requires
various development include headers and program development tools.
<listitem>
<para>
The MySQL client and the client development libraries, when using
- the --with-dhcp-mysql configuration flag to build the Kea MySQL
+ the --with-mysql configuration flag to build the Kea MySQL
database backend. In this case an instance of the MySQL server
running locally or on a machine reachable over a network
is required. Note that
<listitem>
<para>
The PostgreSQL client and the client development libraries, when
- using the --with-dhcp-pgsql configuration flag to build the Kea
+ using the --with-pgsql configuration flag to build the Kea
PostgreSQL database backend. In this case an instance of the
PostgreSQL server running locally or on some other machine,
reachable over the network from the machine running Kea, is
</section>
<section xml:id="install"><info><title>Installation from Source</title></info>
-
<para>
Kea is open source software written in C++. It is freely available in
source code form from ISC as a downloadable tar file. A copy of the Kea
</para>
<section><info><title>Download Tar File</title></info>
-
-
<para>
The Kea release tarballs may be downloaded from:
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://ftp.isc.org/isc/kea/">http://ftp.isc.org/isc/kea/</uri> (using FTP or HTTP).
</section>
<section><info><title>Retrieve from Git</title></info>
-
<para>
Downloading this "bleeding edge" code is recommended only for
developers or advanced users. Using development code in a production
your code. Please consult
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://help.github.com/articles/fork-a-repo/">https://help.github.com/articles/fork-a-repo/</uri> for help on
how to fork a Github repository.
- The <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://git.kea.isc.org/~tester/kea/doxygen/">Kea
+ The <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://git.kea.isc.org/~tester/kea/doxygen/">Kea
Developer's Guide</link> contains more information about the process, as
well as describing the requirements for contributed code to be accepted by ISC.
</para>
<section xml:id="configure"><info><title>Configure Before the Build</title></info>
-
<para>
Kea uses the GNU Build System to discover build environment
details.
</varlistentry>
<varlistentry>
- <term>--with-dhcp-mysql</term>
+ <term>--with-mysql</term>
<listitem>
<simpara>
Build Kea with code to allow it to store leases (and access
</varlistentry>
<varlistentry>
- <term>--with-dhcp-pgsql</term>
+ <term>--with-pgsql</term>
<listitem>
<simpara>
Build Kea with code to allow it to store leases (and access
<screen>$ <userinput>./configure \
--with-boost-include=/usr/pkg/include \
- --with-dhcp-pgsql=/usr/local/bin/pg_config \
+ --with-pgsql=/usr/local/bin/pg_config \
--prefix=/opt/kea</userinput></screen>
</para>
</section>
<section><info><title>Build</title></info>
-
<para>
After the configure step is complete, build the executables
from the C++ code and prepare the Python scripts by running the command:
</section>
<section><info><title>Install</title></info>
-
<para>
To install the Kea executables, support files,
and documentation, issue the command:
</section>
<section xml:id="dhcp-config-backend"><info><title>Selecting the Configuration Backend</title></info>
-
<para>Kea 0.9 introduced configuration backends that are
switchable during the compilation phase. Only one backend, JSON,
is currently supported.
</section>
<section xml:id="dhcp-install-configure"><info><title>DHCP Database Installation and Configuration</title></info>
-
<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
</note>
<section><info><title>Building with MySQL Support</title></info>
-
<para>
Install MySQL according to the instructions for your system. The client development
libraries must be installed.
<para>
Build and install Kea as described in <xref linkend="installation"/>, with
the following modification. To enable the MySQL database code, at the
- "configure" step (see <xref linkend="configure"/>), the --with-dhcp-mysql switch
+ "configure" step (see <xref linkend="configure"/>), the --with-mysql switch
should be specified:
- <screen><userinput>./configure [other-options] --with-dhcp-mysql</userinput></screen>
+ <screen><userinput>./configure [other-options] --with-mysql</userinput></screen>
If MySQL was not installed in the default location, the location of the MySQL
configuration program "mysql_config" should be included with the switch, i.e.
- <screen><userinput>./configure [other-options] --with-dhcp-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
+ <screen><userinput>./configure [other-options] --with-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
</para>
<para>
See <xref linkend="mysql-database-create"/> for details regarding
</section>
<section><info><title>Building with PostgreSQL support</title></info>
-
<para>
Install PostgreSQL according to the instructions for your system. The client development
libraries must be installed. Client development libraries are often packaged as "libpq".
<para>
Build and install Kea as described in <xref linkend="installation"/>, with
the following modification. To enable the PostgreSQL database code, at the
- "configure" step (see <xref linkend="configure"/>), the --with-dhcp-pgsql switch
+ "configure" step (see <xref linkend="configure"/>), the --with-pgsql switch
should be specified:
- <screen><userinput>./configure [other-options] --with-dhcp-pgsql</userinput></screen>
+ <screen><userinput>./configure [other-options] --with-pgsql</userinput></screen>
If PostgreSQL was not installed in the default location, the location of the PostgreSQL
configuration program "pg_config" should be included with the switch, i.e.
- <screen><userinput>./configure [other-options] --with-dhcp-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
+ <screen><userinput>./configure [other-options] --with-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
</para>
<para>
See <xref linkend="pgsql-database-create"/> for details regarding
</section>
<section><info><title>Building with CQL (Cassandra) support</title></info>
-
<para>
Install Cassandra according to the instructions for your system. The
Cassandra project website contains useful pointers: <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://cassandra.apache.org">http://cassandra.apache.org</uri>.
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="intro"><info><title>Introduction</title></info>
-
+
<para>
Kea is the next generation of DHCP software developed by ISC.
It supports both DHCPv4 and DHCPv6 protocols along with their
</para>
<section><info><title>Supported Platforms</title></info>
-
<para>
Kea is officially supported on Red Hat Enterprise Linux,
CentOS, Fedora and FreeBSD systems. It is also likely to work on many
</section>
<section xml:id="required-software"><info><title>Required Software at Run-time</title></info>
-
-
<para>
Running Kea uses various extra software which may
not be provided in the default installation of some operating systems,
</section>
<section xml:id="kea_software"><info><title>Kea Software</title></info>
-
<para>
Kea is modular. Part of this modularity is
accomplished using multiple cooperating processes which, together,
<command>kea-lfc</command> —
This process removes redundant information from the files used
to provide persistent storage for the memfile data base backend.
- While it can be run standalone, it is normally run as and when
+ While it can be run standalone, it is normally run as and when
required by the Kea DHCP servers.
</simpara>
</listitem>
Kea Administrator Reference Manual
</title>
-
-
<releaseinfo>This is the reference guide for Kea version
.</releaseinfo>
<year>2010-2016</year><holder>Internet Systems Consortium, Inc.</holder>
</copyright>
-
-
</info>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="intro.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="faq.xml"/>
<chapter xml:id="acknowledgments"><info><title>Acknowledgments</title></info>
-
-
<para>Kea is primarily designed, developed, and maintained by
Internet Systems Consortium, Inc. It is an open source project
and contributions are welcomed.</para>
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.nominet.org.uk/">Nominet</link>, and
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.sidn.nl/">SIDN</link> were founding
sponsors of the BIND 10 project.</para>
-
</chapter>
-
<!-- TODO: Add bibliography section (mostly RFCs, probably) -->
-
<!-- TODO: how to help: run unit tests, join lists, review trac tickets -->
<!-- <index> <title>Index</title> </index> -->
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="keactrl"><info><title>Managing Kea with keactrl</title></info>
-
<section xml:id="keactrl-overview"><info><title>Overview</title></info>
-
<para>keactrl is a shell script which controls the startup, shutdown
and reconfiguration of the Kea servers (<command>kea-dhcp4</command>,
<command>kea-dhcp6</command> and <command>kea-dhcp-ddns</command>). It
</section>
<section xml:id="keactrl-usage"><info><title>Command Line Options</title></info>
-
<para><command>keactrl</command> is run as follows:
<screen>
keactrl <command> [-c keactrl-config-file] [-s server[,server,..]]
</section>
<section xml:id="keactrl-config-file"><info><title>The keactrl Configuration File</title></info>
-
<para>
Depending on requirements, not all of the available servers need
be run. The keactrl configuration file sets which servers are
</section>
<section xml:id="keactrl-commands"><info><title>Commands</title></info>
-
<para>The following commands are supported by <command>keactrl</command>:
<itemizedlist>
<listitem><simpara>
</section>
<section xml:id="keactrl-overriding-servers"><info><title>Overriding the Server Selection</title></info>
-
<para>
The optional <command>-s</command> switch allows
the selection of the servers to which <command>keactrl</command>
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="lease-expiration"><info><title>Lease Expiration in DHCPv4 and DHCPv6</title></info>
-
<para>The primary role of the DHCP server is to assign addresses and/or
delegate prefixes to DHCP clients. These addresses and prefixes are
</para>
<section xml:id="lease-reclamation"><info><title>Lease Reclamation</title></info>
-
<para>Lease reclamation is the process through which an expired lease
becomes available for assignment to the same or different client.
This process involves the following steps for each reclaimed lease:
</section>
<section xml:id="lease-reclaim-config"><info><title>Configuring Lease Reclamation</title></info>
-
<para>Kea can be configured to periodically detect and reclaim expired
leases. During this process the lease entries in the database are
modified or removed. While this is happening the server will not process incoming DHCP
</section>
<section xml:id="lease-affinity"><info><title>Configuring Lease Affinity</title></info>
-
<para>Suppose that a laptop goes to a sleep mode after a period of user
inactivity. While the laptop is in sleep mode, its DHCP client will not
renew leases obtained from the server and these leases will eventually
</section>
<section xml:id="lease-reclamation-defaults"><info><title>Default Configuration Values for Leases Reclamation</title></info>
-
<para>The following list presents all configuration parameters
pertaining to processing expired leases with their default values:</para>
</section>
<section xml:id="leases-reclamation-using-command"><info><title>Reclaiming Expired Leases with Command</title></info>
-
<para>The <emphasis>leases-reclaim</emphasis> command can be used to trigger
leases reclamation at any time. Please consult the
<xref linkend="command-leases-reclaim"/> for the details about using this
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-lfc"><info><title>The LFC process</title></info>
-
<section xml:id="kea-lfc-overview"><info><title>Overview</title></info>
-
<para><command>kea-lfc</command> is a service process that removes
redundant information from the files used to provide persistent storage
for the memfile data base backend. This service is written to run as a
- stand alone process.
+ stand alone process.
</para>
<para>While <command>kea-lfc</command> can be started externally, there is
usually no need to do this. <command>kea-lfc</command> is run on a periodic
</section>
<section xml:id="kea-lfc-usage"><info><title>Command Line Options</title></info>
-
<para><command>kea-lfc</command> is run as follows:
<screen>
kea-lfc [-4 | -6] -c config-file -p pid-file -x previous-file -i copy-file -o output-file -f finish-file
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="libdhcp"><info><title>The libdhcp++ Library</title></info>
-
+
<para>
libdhcp++ is a library written in C++ that handles
many DHCP-related tasks, including:
<!-- TODO: point to doxygen docs -->
<section xml:id="iface-detect"><info><title>Interface detection and Socket handling</title></info>
-
<para>Both the DHCPv4 and DHCPv6 components share network
interface detection routines. Interface detection is
currently supported on Linux, all BSD family (FreeBSD, NetBSD,
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="logging"><info><title>Logging</title></info>
-
<section><info><title>Logging Configuration</title></info>
-
<para>
During its operation Kea may produce many messages. They differ in
severity (some are more important than others) and source (some are
</para>
<section><info><title>Loggers</title></info>
-
<para>
Within Kea, a message is logged through an entity called a
"logger". Different components log messages through different
runtime) are responsible for creating the loggers used by those
libraries. Such loggers should have unique names, different
from the logger names used by Kea. In this way the
- messages output by the hooks library can be distingued from
+ messages output by the hooks library can be distinguished from
messages issued by the core Kea code. Unique names also allow
the loggers to be configured independently of loggers used
by Kea. Whenever it makes sense, a hook library can use multiple
</para>
<section><info><title>name (string)</title></info>
-
<para>
Each logger in the system has a name, the name being that of the
component binary file using it to log messages. For instance, if you
packet drops, you must create configuration entry for the
logger called <quote>kea-dhcp4.bad-packets</quote> and specify
severity DEBUG for this logger. All other configuration
- parameters may be omited for this logger if the logger should
+ parameters may be omitted for this logger if the logger should
use the default values specified in the root logger's
configuration.
</para>
</section>
<section><info><title>severity (string)</title></info>
-
<para>
This specifies the category of messages logged. Each message is
logged with an associated severity which may be one of the following
</section>
<section><info><title>debuglevel (integer)</title></info>
-
<para>
When a logger's severity is set to DEBUG, this value specifies what
level of debug messages should be printed. It ranges from 0 (least
</section>
<section><info><title>output_options (list)</title></info>
-
<para>
Each logger can have zero or more <option>output_options</option>.
These specify where log messages are sent. These are explained in
</para>
<section><info><title>output (string)</title></info>
-
<para>
This value determines the type of output. There are several special
values allowed here: <command>stdout</command> (messages are printed
</section>
<section><info><title>flush (true of false)</title></info>
-
<para>
Flush buffers after each log message. Doing this will reduce
performance but will ensure that if the program terminates
</section>
<section><info><title>maxsize (integer)</title></info>
-
<para>
Only relevant when destination is file, this is maximum file size of
output files in bytes. When the maximum size is reached, the file is
</section>
<section><info><title>maxver (integer)</title></info>
-
<para>
Maximum number of old log files to keep around when rolling the
output file. Only relevant when <option>output</option> is
</section>
<section><info><title>Example Logger Configurations</title></info>
-
<para>
In this example we want to set the global logging to write to the
console using standard output.
</section>
<section xml:id="logging-message-format"><info><title>Logging Message Format</title></info>
-
<para>
Each message written to the configured logging destinations comprises a
number of components that identify the origin of the message and, if the
</section>
<section xml:id="logging-during-startup"><info><title>Logging During Kea Startup</title></info>
-
<para>
The logging configuration is specified in the configuration file.
However, when Kea starts, the file is not read until some way into the
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="quickstart"><info><title>Quick Start</title></info>
-
<para>
This section describes the basic steps needed to get Kea up and running.
</para>
<section xml:id="quick-start"><info><title>Quick Start Guide for DHCPv4 and DHCPv6 Services</title></info>
-
-
<orderedlist inheritnum="ignore" continuation="restarts">
<listitem>
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>)
+ <filename>[kea-install-dir]/var/kea/kea-dhcp6.log</filename>)
for the details of the error.
</para>
</listitem>
</section>
<section xml:id="quick-start-direct-run"><info><title>Running the Kea Servers Directly</title></info>
-
<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:
<!-- Converted by db4-upgrade version 1.0 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="stats"><info><title>Statistics</title></info>
-
<section><info><title>Statistics Overview</title></info>
-
-
<para>Both Kea DHCP servers support statistics gathering.
A working DHCP server encounters various events
that can cause certain statistics to be collected. For
</section>
<section xml:id="stats-lifecycle"><info><title>Statistics Lifecycle</title></info>
-
<para>
It is useful to understand how the Statistics Manager module works. When
the server starts operation, the manager is empty and does not have any
</section>
<section xml:id="command-stats"><info><title>Commands for Manipulating Statistics</title></info>
-
<para>
There are several commands defined that can be used for accessing (-get),
resetting to zero or neutral value (-reset) or even removing a statistic
</para></note>
<section xml:id="command-statistic-get"><info><title>statistic-get command</title></info>
-
-
<para>
<emphasis>statistic-get</emphasis> command retrieves a single
statistic. It takes a single string parameter called
</section> <!-- end of command-statistic-get -->
<section xml:id="command-statistic-reset"><info><title>statistic-reset command</title></info>
-
-
<para>
<emphasis>statistic-reset</emphasis> command sets the specified statistic
to its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time
</section> <!-- end of command-statistic-reset -->
<section xml:id="command-statistic-remove"><info><title>statistic-remove command</title></info>
-
-
<para>
<emphasis>statistic-remove</emphasis> command attempts to delete a single
statistic. It takes a single string parameter called
</section> <!-- end of command-statistic-reset -->
<section xml:id="command-statistic-get-all"><info><title>statistic-get-all command</title></info>
-
-
<para>
<emphasis>statistic-get-all</emphasis> command retrieves all statistics
recorded. An example command may look like this:
</section> <!-- end of command-statistic-get-all -->
<section xml:id="command-statistic-reset-all"><info><title>statistic-reset-all command</title></info>
-
-
<para>
<emphasis>statistic-reset</emphasis> command sets all statistics to
their neutral values: 0 for integer, 0.0 for float, 0h0m0s0us for time
</section> <!-- end of command-statistic-reset-all -->
<section xml:id="command-statistic-remove-all"><info><title>statistic-remove-all command</title></info>
-
-
<para>
<emphasis>statistic-remove-all</emphasis> command attempts to delete all
statistics. An example command may look like this:
projects / thirdparty / kea.git / commitdiff
