- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
-
-<chapter id="admin">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="admin">
+ <title>Kea Database Administration</title>
+
- <section id="kea-database-version">
++ <section xml:id="kea-database-version">
+ <title>Databases and Database Version Numbers</title>
- <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
</para>
</section>
- <section xml:id="kea-admin"><info><title>The kea-admin Tool</title></info>
- <section id="kea-admin">
++ <section xml:id="kea-admin">
+ <title>The kea-admin Tool</title>
+
<para>
To manage the databases, Kea provides the
<command>kea-admin</command> tool. It is able to initialize
</para>
</section>
- <section xml:id="supported-databases"><info><title>Supported Databases</title></info>
- <section id="supported-databases">
++ <section xml:id="supported-databases">
+ <title>Supported Databases</title>
+
<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" id="backends">
++ <table frame="all" xml:id="backends">
<title>List of available backends</title>
- <tgroup cols='5'>
- <tgroup cols='2'>
-- <colspec colname='feature'/>
-- <colspec colname='memfile'/>
-- <colspec colname='mysql'/>
-- <colspec colname='pgsql'/>
- <colspec colname='cql' colwidth='1.5*'/>
- <colspec colname='cql'/>
++ <tgroup cols="2">
++ <colspec colname="feature"/>
++ <colspec colname="memfile"/>
++ <colspec colname="mysql"/>
++ <colspec colname="pgsql"/>
++ <colspec colname="cql"/>
<thead>
<row>
<entry>Feature</entry>
present. Necessary disk write permission is required.
</para>
- <section xml:id="memfile-upgrade"><info><title>Upgrading Memfile Lease Files from an Earlier Version of Kea</title></info>
- <section id="memfile-upgrade">
++ <section xml:id="memfile-upgrade">
+ <title>Upgrading Memfile Lease Files from an Earlier Version of Kea</title>
<para>
There are no special steps required to upgrade memfile lease files
from an earlier version of Kea to a new version of Kea.
if you chose to store the data in other backends.
</para>
- <section xml:id="mysql-database-create"><info><title>First Time Creation of the MySQL Database</title></info>
- <section id="mysql-database-create">
++ <section xml:id="mysql-database-create">
+ <title>First Time Creation of the MySQL Database</title>
+
<para>
If you are setting the MySQL database for the first time,
you need to create the database area within MySQL and set up
</para>
</section>
- <section xml:id="mysql-upgrade"><info><title>Upgrading a MySQL Database from an Earlier Version of Kea</title></info>
- <section id="mysql-upgrade">
++ <section xml:id="mysql-upgrade">
+ <title>Upgrading a MySQL Database from an Earlier Version of Kea</title>
+
<para>
Sometimes a new Kea version may use newer database schema, so
there will be a need to upgrade the existing database. This can
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>
- <section id="pgsql-database-create">
++ <section xml:id="pgsql-database-create">
+ <title>First Time Creation of the PostgreSQL Database</title>
+
<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
by <command>kea-admin</command>.)
</para>
</section>
- <section xml:id="pgsql-upgrade"><info><title>Upgrading a PostgreSQL Database from an Earlier Version of Kea</title></info>
- <section id="pgsql-upgrade">
++ <section xml:id="pgsql-upgrade">
+ <title>Upgrading a PostgreSQL Database from an Earlier Version of Kea</title>
<para>
The PostgreSQL database schema can be upgraded using the same tool and
commands as described in <xref linkend="mysql-upgrade"/>, with the
store the data in other backends.
</para>
- <section xml:id="cql-database-create"><info><title>First Time Creation of the Cassandra Database</title></info>
- <section id="cql-database-create">
++ <section xml:id="cql-database-create">
+ <title>First Time Creation of the Cassandra Database</title>
+
<para>
If you are setting up the CQL database for the first time, you need to
create the keyspace area within CQL. This needs to be done manually:
</para>
</section>
- <section xml:id="cql-upgrade"><info><title>Upgrading a CQL Database from an Earlier Version of Kea</title></info>
- <section id="cql-upgrade">
++ <section xml:id="cql-upgrade">
+ <title>Upgrading a CQL Database from an Earlier Version of Kea</title>
+
<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 Database sections -->
--</chapter>
++</chapter>
--- /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "‗" >
-]>
-
-<chapter id="kea-ctrl-agent">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-ctrl-agent">
+ <title>Kea Control Agent</title>
+
- <section id="agent-overview">
++ <section xml:id="agent-overview">
+ <title>Overview</title>
+ <para>Kea Control Agent (CA) is a daemon, first included in Kea 1.2, which
+ exposes a RESTful control interface for managing Kea servers. The daemon
+ can receive control commands over HTTP and either forward these commands
+ to the respective Kea servers or handle these commands on its own. The
+ determination whether the command should be handled by the CA or forwarded
+ is made by checking the value of the 'service' parameter which may be
+ included in the command from the controlling client. The details of the
+ supported commands as well as their structures are provided in
+ <xref linkend="ctrl-channel"/>.</para>
+ <para>Hook libraries can be attached to the CA to provide support for
+ additional commands or custom behavior of existing commands. Such hook
+ libraries must implement callouts for 'control_command_receive' hook point.
+ Details about creating new hook libraries and supported hook points can be
+ found in
- <ulink url="https://jenkins.isc.org/job/Kea_doc/doxygen/">Kea Developer's Guide</ulink>.
++ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Kea_doc/doxygen/">Kea Developer's Guide</link>.
+ </para>
+
+ <para>
+ The CA processes received commands according to the following algorithm:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ Pass command into any installed hooks (regardless of service value(s)).
+ If the command is handled by a hook, return the response.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ If the service specifies one more or services, the CA will forward the
+ command to specified services and return the accumulated responses.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ If service is not specified or is an empty list, the CA will handle
+ the command if it supports it.
+ </simpara>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ </section>
+
- <section id="agent-configuration">
++ <section xml:id="agent-configuration">
+ <title>Configuration</title>
+ <para>The following example demonstrates the basic CA configuration.</para>
+ <para>
+ <screen>
+ {
+ "Control-agent": {
+ "http-host": "10.20.30.40",
+ "http-port": 8080,
+
+ "control-sockets": {
+ "dhcp4": {
+ "socket-type": "unix",
+ "socket-name": "/path/to/the/unix/socket-v4"
+ },
+ "dhcp6": {
+ "socket-type": "unix",
+ "socket-name": "/path/to/the/unix/socket-v4"
+ }
+ },
+
+ "hooks-libraries": [
+ {
+ "library": "/opt/local/control-agent-commands.so",
+ "parameters": {
+ "param1": "foo"
+ }
+ } ]
+ },
+
+ "Logging": {
+ "loggers": [ {
+ "name": "kea-ctrl-agent",
+ "severity": "INFO"
+ } ]
+ }
+ }</screen>
+ </para>
+
+ <para>
+ The <command>http-host</command> and <command>http-port</command>
+ specify an IP address and port to which HTTP service will be bound.
+ In case of the example configuration provided above, the RESTful
+ service will be available under the URL of
+ <command>http://10.20.30.40:8080/</command>. If these parameters
+ are not specified, the default URL is http://127.0.0.1:8000/
+ </para>
+
+ <para>
+ It has been mentioned in the <xref linkend="agent-overview"/> that
+ CA can forward received commands to the specific Kea servers for
+ processing. For example, <command>config-get</command> is sent to
+ retrieve configuration of one of the Kea services. When CA receives
+ this command, including a <command>service</command> parameter
+ indicating that the client desires to retrieve configuration of
+ the DHCPv4 server, the CA will forward this command to this server
+ and then pass the received response back to the client. More about
+ the <command>service</command> parameter and general structure of
+ the commands can be found in <xref linkend="ctrl-channel"/>.
+ </para>
+
+ <para>
+ The CA uses unix domain sockets to forward control commands and receive
+ responses from other Kea services. The <command>dhcp4</command>,
+ <command>dhcp6</command> and <command>d2</command> maps
+ specify the files to which unix domain sockets are bound. In case
+ of the configuration above, the CA will connect to the DHCPv4 server
+ via <filename>/path/to/the/unix/socket-v4</filename> to forward the
+ commands to it. Obviously, the DHCPv4 server must be configured to
+ listen to connections via this same socket. In other words, the command
+ socket configuration for the DHCPv4 server and CA (for this server)
+ must match. Consult the <xref linkend="dhcp4-ctrl-channel"/> and the
+ <xref linkend="dhcp6-ctrl-channel"/> to learn how the socket
+ configuration is specified for the DHCPv4 and DHCPv6 services.
+ </para>
+
+ <warning>
+ <simpara>
+ We have renamed "dhcp4-server", "dhcp6-server" and "d2-server"
+ to "dhcp4", "dhcp6" and "d2" respectively after release of Kea 1.2.
+ If you are migrating from Kea 1.2 you need to tweak your CA config
+ to use this new naming convention. We have made this incompatible
+ change to facilitate future use cases where it will be possible to
+ specify additional values of the "service" parameter to point to
+ the particular instances of the Kea servers, e.g. "dhcp4/3"
+ pointing to the 3rd instance of the DHCPv4 server in the
+ multi-processed configuration. This is not yet supported but the
+ current renaming lays the ground for it.
+ </simpara>
+ </warning>
+
+ <para>
+ Hooks libraries can be attached to the Control Agent just like to
+ DHCPv4 and DHCPv6 servers. It currently supports one hook point
+ 'control_command_receive' which makes it possible to delegate
+ processing of some commands to the hooks library. The
+ <command>hooks-libraries</command> list contains the list of hooks
+ libraries that should be loaded by the CA, along with their configuration
+ information specified with <command>parameters</command>.
+ </para>
+
+ <para>
+ Please consult <xref linkend="logging"/> for the details how to
+ configure logging. The CA's root logger's name is
+ <command>kea-ctrl-agent</command> as given in the example above.
+ </para>
+ </section>
+
- <section id="agent-secure-connection">
++ <section xml:id="agent-secure-connection">
+ <title>Secure Connections</title>
+ <para>
+ Control Agent doesn't natively support secure HTTP connections like
+ SSL or TLS. In order to setup secure connection please use one
+ of the available third party HTTP servers and configure it to run
+ as a reverse proxy to the Control Agent. Kea has been tested with
+ two major HTTP server implentations working as a reverse proxy:
+ Apache2 and nginx. Example configurations including extensive
+ comments are provided in the <filename>doc/examples/https/</filename>
+ directory.
+ </para>
+
+ <para>
+ The reverse proxy forwards HTTP requests received over secure
+ connection to the Control Agent using (not secured) HTTP. Typically,
+ the reverse proxy and the Control Agent are running on the same machine,
+ but it is possible to configure them to run on separate machines as
+ well. In this case, security depends on the protection of the
+ communications between the reverse proxy and the Control Agent.
+ </para>
+
+ <para>Apart from providing the encryption layer for the control channel,
+ a reverse proxy server is also often used for authentication of the
+ controlling clients. In this case, the client must present a valid
+ certificate when it connects via reverse proxy. The proxy server
+ authenticates the client by checking if the presented certificate is
+ signed by the certificate authority used by the server.</para>
+
+ <para>To illustrate this, we provide a sample configuration for the
+ nginx server running as a reverse proxy to the Kea Control Agent.
+ The server enables authentication of the clients using
+ certificates.</para>
+
+ <screen>
+ # The server certificate and key can be generated as follows:
+ #
+ # openssl genrsa -des3 -out kea-proxy.key 4096
+ # openssl req -new -x509 -days 365 -key kea-proxy.key -out kea-proxy.crt
+ #
+ # The CA certificate and key can be generated as follows:
+ #
+ # openssl genrsa -des3 -out ca.key 4096
+ # openssl req -new -x509 -days 365 -key ca.key -out ca.crt
+ #
+ #
+ # The client certificate needs to be generated and signed:
+ #
+ # openssl genrsa -des3 -out kea-client.key 4096
+ # openssl req -new -key kea-client.key -out kea-client.csr
+ # openssl x509 -req -days 365 -in kea-client.csr -CA ca.crt \
+ # -CAkey ca.key -set_serial 01 -out kea-client.crt
+ #
+ # Note that the 'common name' value used when generating the client
+ # and the server certificates must differ from the value used
+ # for the CA certificate.
+ #
+ # The client certificate must be deployed on the client system.
+ # In order to test the proxy configuration with 'curl' run
+ # command similar to the following:
+ #
+ # curl -k --key kea-client.key --cert kea-client.crt -X POST \
+ # -H Content-Type:application/json -d '{ "command": "list-commands" }' \
+ # https://kea.example.org/kea
+ #
+ #
+ #
+ # nginx configuration starts here.
+
+ events {
+ }
+
+ http {
+ # HTTPS server
+ server {
+ # Use default HTTPS port.
+ listen 443 ssl;
+ # Set server name.
+ server_name kea.example.org;
+
+ # Server certificate and key.
+ ssl_certificate /path/to/kea-proxy.crt;
+ ssl_certificate_key /path/to/kea-proxy.key;
+
+ # Certificate Authority. Client certificate must be signed by the CA.
+ ssl_client_certificate /path/to/ca.crt;
+
+ # Enable verification of the client certificate.
+ ssl_verify_client on;
+
+ # For URLs such as https://kea.example.org/kea, forward the
+ # requests to http://127.0.0.1:8080.
+ location /kea {
+ proxy_pass http://127.0.0.1:8080;
+ }
+ }
+ }
+ </screen>
+
+ <note>
+ <simpara>Note that the configuration snippet provided above is for testing
+ purposes only. Consult security policies and best practices of your
+ organization which apply to this setup.</simpara>
+ </note>
+
+ </section>
+
- <section id="agent-limitations">
++ <section xml:id="agent-limitations">
+ <title>Control Agent Limitations</title>
+ <para>
+ Control Agent is a new component, first released in Kea 1.2. In
+ this release it comes with one notable limitation:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ keactrl hasn't been updated to manage the Control Agent (start, stop
+ reload). As a result, the CA must be started directly as described in
+ <xref linkend="agent-launch"/>
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
- <section id="agent-launch">
++ <section xml:id="agent-launch">
+ <title>Starting Control Agent</title>
+ <para>
+ The CA is started by running its binary and specifying the configuration file
+ it should use. For example:
+ <screen>
+ $ ./kea-ctrl-agent -c /usr/local/etc/kea/kea.conf
+ </screen>
+ </para>
+ </section>
+
- <section id="agent-clients">
++ <section xml:id="agent-clients">
+ <title>Connecting to the Control Agent</title>
+ <para>For an example of tool that can take advantage of the
+ RESTful API, see <xref linkend="kea-shell"/>.</para>
+ </section>
-</chapter>
++</chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
-
-<chapter id="classify">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="classify">
+ <title>Client Classification</title>
- <section><info><title>Client Classification Overview</title></info>
+ <section>
+ <title>Client Classification Overview</title>
<para>
In certain cases it is useful to differentiate between different
types of clients and treat them accordingly. Common reasons include:
</note>
</section>
- <section xml:id="classification-using-host-reservations"><info><title>Using Static Host Reservations In Classification</title></info>
- <section id="classification-using-host-reservations">
++ <section xml:id="classification-using-host-reservations">
+ <title>Using Static Host Reservations In Classification</title>
<para>Classes can be statically assigned to the clients using techniques described
in <xref linkend="reservation4-client-classes"/> and
<xref linkend="reservation6-client-classes"/>.
</para>
</section>
- <section xml:id="classification-using-vendor"><info><title>Using Vendor Class Information In Classification</title></info>
- <section id="classification-using-vendor">
++ <section xml:id="classification-using-vendor">
+ <title>Using Vendor Class Information In Classification</title>
<para>
The server checks whether an incoming DHCPv4 packet includes
the vendor class identifier option (60) or an incoming DHCPv6 packet
</para>
</section>
- <section xml:id="classification-using-expressions"><info><title>Using Expressions In Classification</title></info>
- <section id="classification-using-expressions">
++ <section xml:id="classification-using-expressions">
+ <title>Using Expressions In Classification</title>
<para>
The expression portion of classification contains operators and values.
All values are currently strings and operators take a string or strings and
</para>
<para>
- <table frame="all" xml:id="classification-values-list"><info><title>List of Classification Values</title></info>
- <table frame="all" id="classification-values-list">
++ <table frame="all" xml:id="classification-values-list">
+ <title>List of Classification Values</title>
- <tgroup cols='3'>
- <colspec colname='name' />
- <colspec colname='example' />
- <colspec colname='description' />
+ <tgroup cols="3">
+ <colspec colname="name"/>
+ <colspec colname="example"/>
+ <colspec colname="description"/>
<thead>
<row>
<entry>Name</entry>
</itemizedlist>
<para>
- <table frame="all" xml:id="classification-expressions-list"><info><title>List of Classification Expressions</title></info>
- <table frame="all" id="classification-expressions-list">
++ <table frame="all" xml:id="classification-expressions-list">
+ <title>List of Classification Expressions</title>
- <tgroup cols='3'>
- <colspec colname='name' />
- <colspec colname='example' />
- <colspec colname='description' />
+ <tgroup cols="3">
+ <colspec colname="name"/>
+ <colspec colname="example"/>
+ <colspec colname="description"/>
<thead>
<row>
<entry>Name</entry>
The expression for each class is executed on each packet received.
If the expressions are overly complex, the time taken to execute
them may impact the performance of the server. If you need
- complex or time consuming expressions you should write a <link
- linkend='hooks-libraries'>hook</link> to perform the necessary work.
+ complex or time consuming expressions you should write a <link linkend="hooks-libraries">hook</link> to perform the necessary work.
</para> </note>
- <section xml:id="classification-configuring"><info><title>Configuring Classes</title></info>
- <section id="classification-configuring">
++ <section xml:id="classification-configuring">
+ <title>Configuring Classes</title>
<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
</para>
</section>
- <section xml:id="classification-subnets"><info><title>Configuring Subnets With Class Information</title></info>
- <section id="classification-subnets">
++ <section xml:id="classification-subnets">
+ <title>Configuring Subnets With Class Information</title>
<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"
</para></note>
</section>
--</chapter>
++</chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
-<chapter id="kea-config">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-config">
+ <title>Kea Configuration</title>
<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>
- <section id="json">
++ <section xml:id="json">
+ <title>JSON Configuration</title>
<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
The JSON backend uses certain signals to influence Kea. The
configuration file is specified upon startup using the -c parameter.</para>
- <section xml:id="json-format"><info><title>JSON Syntax</title></info>
- <section id="json-format">
++ <section xml:id="json-format">
+ <title>JSON Syntax</title>
<para>Configuration files for DHCPv4, DHCPv6 and DDNS modules are defined
- in an extended JSON format. Basic JSON is defined in <ulink
- url="http://tools.ietf.org/html/rfc7159">RFC 7159</ulink>. Note that Kea
+ 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
particular, the only values allowed for boolean are true or false (all
lowercase). The capitalized versions (True or False) are not accepted.
</section>
--</chapter>
++</chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-<!ENTITY % version SYSTEM "version.ent">
-%version;
-]>
-
- <chapter id="ctrl-channel">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ctrl-channel">
+ <title>Management API</title>
<para>A classic approach to daemon configuration assumes that
the server's configuration is stored in configuration files
Both servers can be instructed to open control sockets, which
is a communication channel. The server is able to receive
commands on that channel, act on them and report back status.
- While the set of commands in Kea 1.1.0 is limited,
+ While the set of commands in Kea 1.2.0 is limited,
the number is expected to grow over time.</para>
- <para>Currently the only supported type of control channel
- is UNIX stream socket. For details how to configure it, see
- <xref linkend="dhcp4-ctrl-channel"/> and <xref linkend="dhcp6-ctrl-channel"/>. It is likely that support
- for other control channel types will be added in the future.
+ <para>The DHCPv4 and DHCPv6 servers receive commands over the
+ unix domain sockets. The details how to configure these sockets,
- see <xref linkend="dhcp4-ctrl-channel" /> and <xref
- linkend="dhcp6-ctrl-channel" />. While it is possible control
++ see <xref linkend="dhcp4-ctrl-channel"/> and <xref linkend="dhcp6-ctrl-channel"/>. While it is possible control
+ the servers directly using unix domain sockets it requires that
+ the controlling client be running on the same machine as
+ the server. In order to connect remotely SSH is usually used to
+ connect to the controlled machine.</para>
+
+ <para>The network administrators usually prefer using some form
+ of a RESTful API to control the servers, rather than using unix
+ domain sockets directly. Therefore, as of Kea 1.2.0 release,
+ Kea includes a new component called Control Agent (or CA) which
+ exposes a RESTful API to the controlling clients and can forward
+ commands to the respective Kea services over the unix domain
+ sockets. The CA configuration has been described in
+ <xref linkend="agent-configuration"/>.</para>
+
+ <para>The HTTP requests received by the CA contain the control
+ commands encapsulated within HTTP requests. Simply speaking,
+ the CA is responsible for stripping the HTTP layer from the
+ received commands and forwarding the commands in a JSON format
+ over the unix domain sockets to respective services. Because the
+ CA receives commands for all services it requires additional
+ "forwarding" information to be included in the client's messages.
+ This "forwarding" information is carried within the
+ <command>service</command> parameter of the received command.
+ If the <command>service</command> parameter is not included or if
+ the parameter is a blank list the CA will assume that the control
+ command is targetted at the CA itself and will try to handle
+ it on its own.
+ </para>
+
+ <para>Control connections over both HTTP and unix domain sockets are
+ guarded with timeouts. The default timeout value is set to 10s
+ and is not configurable. The timeout configuration will be
+ implemented in the future.
</para>
- <section xml:id="ctrl-channel-syntax"><info><title>Data Syntax</title></info>
+ <note>
+ <simpara>Kea 1.2.0 release and earlier had a limitation of 64kB
+ on the maximum size of a command and a response sent over the unix
+ domain socket. This limitation has been removed in Kea 1.3.0
+ release.
+ </simpara>
+ </note>
+
- <section id="ctrl-channel-syntax">
++ <section xml:id="ctrl-channel-syntax">
+ <title>Data Syntax</title>
<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
<command>arguments</command> is a map of additional data values returned by
the server which is specific to the command issued. The map is always present, even
if it contains no data values.</para>
+
+ <note>
+ <simpara>
+ When sending commands via Control Agent, it is possible to specify
+ multiple services at which the command is targetted. CA will forward this
+ command to each service individually. Thus, the CA response to the
+ controlling client will contain an array of individual responses.
+ </simpara>
+ </note>
+
</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
- may have quite varied expectations regarding the client and is even likely to
- be written in languages different than C or C++. Therefore only examples are provided to show
- how one can take advantage of the API.</para>
- <section id="ctrl-channel-client">
++ <section xml:id="ctrl-channel-client">
+ <title>Using the Control Channel</title>
+
+ <para>Kea development team is actively working on providing client applications
+ which can be used to control the servers. These applications are, however, in the
+ early stages of development and as of Kea 1.2.0 release have certain limitations.
+ The easiest way to start playing with the control API is to use common Unix/Linux tools
+ such as <command>socat</command> and <command>curl</command>.</para>
- <para>The easiest way is to use a tool called <command>socat</command>,
- a tool available from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.dest-unreach.org/socat/">socat
- homepage</link>, but it is also widely available in Linux and BSD
- distributions. Once Kea is started, one could connect to the control
- interface using the following command:
+ <para>In order to control the given Kea service via unix domain socket, use
+ <command>socat</command> as follows:
<screen>
$ socat UNIX:/path/to/the/kea/socket -
</screen>
such a simplistic client written in C is available in the Kea Developer's
Guide, chapter Control Channel Overview, section Using Control Channel.</para>
+ <para>In order to use Kea's RESTful API with <command>curl</command> try the
+ following:
+ <screen>
+ $ curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get", "service": [ "dhcp4" ] }' http://ca.example.org:8000/
+ </screen>
+
+ This assumes that the Control Agent is running on host
+ <filename>ca.example.org</filename> and runs RESTful service on port 8000.
+ </para>
+
</section>
- <section xml:id="commands-common"><info><title>Commands Supported by Both the DHCPv4 and DHCPv6 Servers</title></info>
- <section id="commands-common">
++ <section xml:id="commands-common">
+ <title>Commands Supported by Both the DHCPv4 and DHCPv6 Servers</title>
+
- <section id="command-build-report">
++ <section xml:id="command-build-report">
+ <title>build-report</title>
+ <para>
+ The <emphasis>build-report</emphasis> command returns
+ on the control channel what the command line
+ <command>-W</command> argument displays, i.e. the embedded
+ content of the <filename>config.report</filename> file.
+ This command does not take any parameters.
+ </para>
+ <screen>
+ {
+ "command": "build-report"
+ }
+ </screen>
+ </section> <!-- end of command-build-report -->
+
- <section id="command-config-get">
++ <section xml:id="command-config-get">
+ <title>config-get</title>
+
+ <para>The <emphasis>config-get</emphasis> command retrieves the current
+ configuration used by the server. This command does not take any
+ parameters. The configuration returned is roughly equal to the
+ configuration that was loaded using -c command line option during server
+ start-up or later set using config-set command. However, there may be
+ certain differences. Comments are not retained. If the original
+ configuration used file inclusion, the returned configuration will
+ include all parameters from all the included files.</para>
+
+ <para> Note that returned configuration is not redacted, i.e. it will
+ contain database passwords in plain text if those were specified in the
+ original configuration. Care should be taken to not expose the command
+ channel to unprivileged users.</para>
+
+ <para>
+ An example command invocation looks like this:
+ <screen>
+ {
+ "command": "config-get"
+ }
+ </screen>
+ </para>
+ </section> <!-- end of command-config-get -->
+
- <section id="command-config-reload">
++ <section xml:id="command-config-reload">
+ <title>config-reload</title>
+
+ <para>The <emphasis>config-reload</emphasis> command instructs
+ Kea to load again the configuration file that was used
+ previously. This operation is useful if the configuration file
+ has been changed by some external sources. For example, a
+ sysadmin can tweak the configuration file and use this command
+ to force Kea pick up the changes.</para>
+
+ <para>Caution should be taken when mixing this with config-set
+ commands. Kea remembers the location of the configuration file
+ it was started with. This configuration can be significantly
+ changed using config-set command. When config-reload is issued
+ after config-set, Kea will attempt to reload its original
+ configuration from the file, possibly losing all changes
+ introduced using config-set or other commands.</para>
+
+ <para><emphasis>config-reload</emphasis> does not take any parameters.
+ An example command invocation looks like this:
+ <screen>
+ {
+ "command": "config-reload"
+ }
+ </screen>
+ </para>
+ </section> <!-- end of command-config-reload -->
+
+
- <section id="command-config-test">
++ <section xml:id="command-config-test">
+ <title>config-test</title>
+
+ <para>
+ The <emphasis>config-test</emphasis> command instructs the server to check
+ whether the new configuration supplied in the command's arguments can
+ be loaded. The supplied configuration is expected to be the full
+ configuration for the target server along with an optional Logger
+ configuration. As for the <command>-t</command> command some sanity checks
+ are not performed so it is possible a configuration which successfully
+ passes this command will still fail in <command>config-set</command>
+ command or at launch time.
+ The structure of the command is as follows:
+ </para>
+ <screen>
+ {
+ "command": "config-test",
+ "arguments": {
- "<server>": {
++ "<server>": {
+ },
+ "Logging": {
+ }
+ }
+ }
+ </screen>
+ <para>
- where <server> is the configuration element name for a given server
++ where <server> is the configuration element name for a given server
+ such as "Dhcp4" or "Dhcp6". For example:
+ </para>
+ <screen>
+ {
+ "command": "config-test",
+ "arguments": {
+ "Dhcp6": {
+ :
+ },
+ "Logging": {
+ :
+ }
+ }
+ }
+ </screen>
+ <para>
+ The server's response will contain a numeric code, "result" (0 for success,
+ non-zero on failure), and a string, "text", describing the outcome:
+ <screen>
+ {"result": 0, "text": "Configuration seems sane..." }
+
+ or
+
- {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }
++ {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }
+ </screen>
+ </para>
+ </section> <!-- end of command-config-test -->
+
- <section id="command-config-write">
++ <section xml:id="command-config-write">
+ <title>config-write</title>
+
+ <para>The <emphasis>config-write</emphasis> command instructs Kea server
+ to write its current configuration to a file on disk. It takes one
+ optional argument called <emphasis>filename</emphasis> that specifies
+ the name of the file to write configuration to. If not specified, the
+ name used when starting Kea (passed as -c argument) will be
+ used. If relative path is specified, Kea will write its files
+ only in the directory it is running.</para>
+ <para>
+ An example command invocation looks like this:
+ <screen>
+ {
+ "command": "config-write",
+ "arguments": {
+ "filename": "config-modified-2017-03-15.json"
+ }
+ }
+ </screen>
+ </para>
+ </section> <!-- end of command-config-write -->
- <section xml:id="command-leases-reclaim"><info><title>leases-reclaim</title></info>
- <section id="command-leases-reclaim">
++ <section xml:id="command-leases-reclaim">
+ <title>leases-reclaim</title>
<para>
- <emphasis>leases-reclaim</emphasis> command instructs the server to
+ The <emphasis>leases-reclaim</emphasis> command instructs the server to
reclaim all expired leases immediately. The command has the following
JSON syntax:
<screen>
about the processing of expired leases (leases reclamation).</para>
</section>
- <section xml:id="command-list-commands"><info><title>list-commands</title></info>
- <section id="command-libreload">
++ <section xml:id="command-libreload">
+ <title>libreload</title>
+
+ <para>
+ The <emphasis>libreload</emphasis> command will first unload and then
+ load all currently loaded hook libraries. This is primarily intended
+ to allow one or more hook libraries to be replaced with newer versions
+ without requiring Kea servers to be reconfigured or restarted. Note
+ the hook libraries will be passed the same parameter values (if any)
+ they were passed when originally loaded.
+ <screen>
+ {
+ "command": "libreload",
+ "arguments": { }
+ }
+ </screen>
+ </para>
+ <para>
+ The server will respond with a result of 0 indicating success, or 1
+ indicating a failure.
+ </para>
+ </section> <!-- end of command-libreload -->
+
- <section id="command-list-commands">
++ <section xml:id="command-list-commands">
+ <title>list-commands</title>
+
<para>
- The <emphasis>list-commands</emphasis> command retrieves a list of all
- commands supported by the server. It does not take any arguments.
- An example command may look like this:
+ The <emphasis>list-commands</emphasis> command retrieves a list of all
+ commands supported by the server. It does not take any arguments.
+ An example command may look like this:
<screen>
{
"command": "list-commands",
</para>
</section> <!-- end of command-list-commands -->
- <section xml:id="command-shutdown"><info><title>shutdown</title></info>
- <section id="command-config-set">
++ <section xml:id="command-config-set">
+ <title>config-set</title>
+
<para>
- The <emphasis>shutdown</emphasis> command instructs the server to initiate
- its shutdown procedure. It is the equivalent of sending a SIGTERM signal
- to the process. This command does not take any arguments. An example
- command may look like this:
+ The <emphasis>config-set</emphasis> command instructs the server to replace
+ its current configuration with the new configuration supplied in the
+ command's arguments. The supplied configuration is expected to be the full
+ configuration for the target server along with an optional Logger
+ configuration. While optional, the Logger configuration is highly
+ recommended as without it the server will revert to its default logging
+ configuration. The structure of the command is as follows:
+ </para>
<screen>
{
- "command": "shutdown",
- "arguments": { }
+ "command": "config-set",
+ "arguments": {
- "<server>": {
++ "<server>": {
+ },
+ "Logging": {
+ }
+ }
}
</screen>
- where <server> is the configuration element name for a given server
+ <para>
++ where <server> is the configuration element name for a given server
+ such as "Dhcp4" or "Dhcp6". For example:
</para>
+ <screen>
+ {
+ "command": "config-set",
+ "arguments": {
+ "Dhcp6": {
+ :
+ },
+ "Logging": {
+ :
+ }
+ }
+ }
+ </screen>
<para>
- The server will respond with a confirmation that the shutdown procedure
- has been initiated.
+ If the new configuration proves to be invalid the server will retain
+ its current configuration. Please note that the new configuration is
+ retained in memory only. If the server is restarted or a configuration
+ reload is triggered via a signal, the server will use the configuration
+ stored in its configuration file.
+
+ The server's response will contain a numeric code, "result" (0 for success,
+ non-zero on failure), and a string, "text", describing the outcome:
+ <screen>
+ {"result": 0, "text": "Configuration successful." }
+
+ or
+
- {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }
++ {"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }
+ </screen>
+ </para>
+ </section> <!-- end of command-config-set -->
+
- <section id="command-shutdown">
++ <section xml:id="command-shutdown">
+ <title>shutdown</title>
+
+ <para>
+ The <emphasis>shutdown</emphasis> command instructs the server to initiate
+ its shutdown procedure. It is the equivalent of sending a SIGTERM signal
+ to the process. This command does not take any arguments. An example
+ command may look like this:
+ <screen>
+ {
+ "command": "shutdown"
+ }
+ </screen>
+ </para>
+ <para>
+ The server will respond with a confirmation that the shutdown procedure
+ has been initiated.
</para>
</section> <!-- end of command-shutdown -->
- <section id="command-version-get">
++ <section xml:id="command-version-get">
+ <title>version-get</title>
+ <para>
+ The <emphasis>version-get</emphasis> command returns on the control
+ channel what the command line <command>-v</command> argument
+ displays with in arguments the extended version, i.e., what
+ the command line <command>-V</command> argument displays. This command
+ does not take any parameters.
+ </para>
+ <screen>
+ {
+ "command": "version-get"
+ }
+ </screen>
+ </section> <!-- end of command-version-get -->
+
</section> <!-- end of commands supported by both servers -->
- </chapter>
- <section id="agent-commands">
++ <section xml:id="agent-commands">
+ <title>Commands Supported by Control Agent</title>
+ <para>The following commands listed in <xref linkend="commands-common"/>
+ are also supported by the Control Agent, i.e. when the
+ <command>service</command> parameter is blank the commands are handled
+ by the CA and they relate to the CA process itself:
+ <itemizedlist>
+ <listitem>
+ <simpara>build-report</simpara>
+ </listitem>
+ <listitem>
+ <simpara>config-get</simpara>
+ </listitem>
+ <listitem>
+ <simpara>config-test</simpara>
+ </listitem>
+ <listitem>
+ <simpara>config-write</simpara>
+ </listitem>
+ <listitem>
+ <simpara>list-commands</simpara>
+ </listitem>
+ <listitem>
+ <simpara>shutdown</simpara>
+ </listitem>
+ <listitem>
+ <simpara>version-get</simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
- </chapter>
++ </chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
--
- <chapter id="dhcp-ddns-server">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dhcp-ddns-server">
+ <title>The DHCP-DDNS Server</title>
<para>
The DHCP-DDNS Server (kea-dhcp-ddns, known informally as D2) conducts the client side of
- the DDNS protocol (defined in <ulink url="http://tools.ietf.org/html/rfc2136">RFC 2136</ulink>)
+ 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>)
on behalf of the DHCPv4 and DHCPv6
servers (kea-dhcp4 and kea-dhcp6 respectively). The DHCP servers construct
DDNS update requests, known as NameChangeRequests (NCRs), based upon DHCP
rejected. Finally, if there are no reverse DDNS Domains defined, D2 will
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>
- <section id="dhcp-ddns-server-start-stop">
++ <section xml:id="dhcp-ddns-server-start-stop">
+ <title>Starting and Stopping the DHCP-DDNS Server</title>
+
<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
and the process to which the PID belongs is unrelated to Kea. In such a
case it would be necessary to manually delete the PID file.
</para>
- </section> <!-- end start-stop -->
- <section xml:id="d2-configuration"><info><title>Configuring the DHCP-DDNS Server</title></info>
+
+ </section> <!-- end start-stop -->
- <section id="d2-configuration">
++ <section xml:id="d2-configuration">
+ <title>Configuring the DHCP-DDNS Server</title>
<para>
- Before starting <command>kea-dhcp-ddns</command> module for the
- first time, a configuration file needs to be created. The following default
- configuration is a template that can be customised to your requirements.
+ Before starting <command>kea-dhcp-ddns</command> module for the
+ first time, a configuration file needs to be created. The following default
+ configuration is a template that can be customized to your requirements.
<screen>
<userinput>"DhcpDdns": {
"ip-address": "127.0.0.1",
The configuration can be divided as follows, each of which is described
in its own section:
</para>
- <itemizedlist>
- <listitem>
- <simpara>
+ <itemizedlist>
+ <listitem>
+ <simpara>
<emphasis>Global Server Parameters</emphasis> - values which control connectivity and global server behavior
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <emphasis>TSIG Key Info</emphasis> - defines the TSIG keys used for secure traffic with DNS servers
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <emphasis>Forward DDNS</emphasis> - defines the catalog of Forward DDNS Domains
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <emphasis>Reverse DDNS</emphasis> - defines the catalog of Forward DDNS Domains
- </simpara>
- </listitem>
- </itemizedlist>
-
- <section xml:id="d2-server-parameter-config"><info><title>Global Server Parameters</title></info>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <emphasis>TSIG Key Info</emphasis> - defines the TSIG keys used for secure traffic with DNS servers
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <emphasis>Forward DDNS</emphasis> - defines the catalog of Forward DDNS Domains
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <emphasis>Reverse DDNS</emphasis> - defines the catalog of Forward DDNS Domains
+ </simpara>
+ </listitem>
+ </itemizedlist>
- <section id="d2-server-parameter-config">
++ <section xml:id="d2-server-parameter-config">
+ <title>Global Server Parameters</title>
<itemizedlist>
+
<listitem><simpara>
<command>ip-address</command> - IP address on which D2
listens for requests. The default is the local loopback interface at
</note>
</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
- 2845</link>). This configuration section allows the administrator
- to define the set of TSIG keys that may be used in such
- exchanges.</para>
-
- <para>To use TSIG when updating entries in a DNS Domain,
- a key must be defined in the TSIG Key List and referenced by
- name in that domain's configuration entry. When D2 matches a
- change request to a domain, it checks whether the domain has
- a TSIG key associated with it. If so, D2 will use that key to
- sign DNS update messages sent to and verify responses received
- from the domain's DNS server(s). For each TSIG key required by
- the DNS servers that D2 will be working with there must be a
- corresponding TSIG key in the TSIG Key list.</para>
-
- <para>
- As one might gather from the name, the tsig-key section of the
- D2 configuration lists the TSIG keys. Each entry describes a
- TSIG key used by one or more DNS servers to authenticate requests
- and sign responses. Every entry in the list has three parameters:
- <itemizedlist>
- <listitem>
- <simpara>
- <command>name</command> -
- a unique text label used to identify this key within the
- list. This value is used to specify which key (if any) should be
- used when updating a specific domain. So long as it is unique its
- content is arbitrary, although for clarity and ease of maintenance
- it is recommended that it match the name used on the DNS server(s).
- It cannot be blank.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>algorithm</command> -
- specifies which hashing algorithm should be used with this
- key. This value must specify the same algorithm used for the
- key on the DNS server(s). The supported algorithms are listed below:
- <itemizedlist>
- <listitem>
- <command>HMAC-MD5</command>
- </listitem>
- <listitem>
- <command>HMAC-SHA1</command>
- </listitem>
- <listitem>
- <command>HMAC-SHA224</command>
- <section id="d2-tsig-key-list-config">
++ <section xml:id="d2-tsig-key-list-config">
+ <title>TSIG Key List</title>
+ <para>
+ A DDNS protocol exchange can be conducted with or without TSIG
- (defined in <ulink url="http://tools.ietf/org/html/rfc2845">RFC
- 2845</ulink>). This configuration section allows the administrator
++ (defined in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf/org/html/rfc2845">RFC
++ 2845</link>). This configuration section allows the administrator
+ to define the set of TSIG keys that may be used in such
+ exchanges.</para>
+
+ <para>To use TSIG when updating entries in a DNS Domain,
+ a key must be defined in the TSIG Key List and referenced by
+ name in that domain's configuration entry. When D2 matches a
+ change request to a domain, it checks whether the domain has
+ a TSIG key associated with it. If so, D2 will use that key to
+ sign DNS update messages sent to and verify responses received
+ from the domain's DNS server(s). For each TSIG key required by
+ the DNS servers that D2 will be working with there must be a
+ corresponding TSIG key in the TSIG Key list.</para>
+
+ <para>
+ As one might gather from the name, the tsig-key section of the
+ D2 configuration lists the TSIG keys. Each entry describes a
+ TSIG key used by one or more DNS servers to authenticate requests
+ and sign responses. Every entry in the list has three parameters:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>name</command> -
+ a unique text label used to identify this key within the
+ list. This value is used to specify which key (if any) should be
+ used when updating a specific domain. So long as it is unique its
+ content is arbitrary, although for clarity and ease of maintenance
+ it is recommended that it match the name used on the DNS server(s).
+ It cannot be blank.
+ </simpara>
</listitem>
<listitem>
- <command>HMAC-SHA256</command>
+ <simpara>
+ <command>algorithm</command> -
+ specifies which hashing algorithm should be used with this
+ key. This value must specify the same algorithm used for the
+ key on the DNS server(s). The supported algorithms are listed below:
+ <itemizedlist>
+ <listitem>
+ <command>HMAC-MD5</command>
+ </listitem>
+ <listitem>
+ <command>HMAC-SHA1</command>
+ </listitem>
+ <listitem>
+ <command>HMAC-SHA224</command>
+ </listitem>
+ <listitem>
+ <command>HMAC-SHA256</command>
+ </listitem>
+ <listitem>
+ <command>HMAC-SHA384</command>
+ </listitem>
+ <listitem>
+ <command>HMAC-SHA512</command>
+ </listitem>
+ </itemizedlist>
+ This value is not case sensitive.
+ </simpara>
</listitem>
<listitem>
- <command>HMAC-SHA384</command>
+ <simpara>
+ <command>digest-bits</command> -
+ is used to specify the minimum truncated length in bits.
+ The default value 0 means truncation is forbidden, non-zero
+ values must be an integral number of octets, be greater
+ than 80 and the half of the full length. Note in BIND9
+ this parameter is appended after a dash to the algorithm
+ name.
+ </simpara>
</listitem>
<listitem>
- <command>HMAC-SHA512</command>
+ <simpara>
+ <command>secret</command> -
+ is used to specify the shared secret key code for this key. This value is
+ case sensitive and must exactly match the value specified on the DNS server(s).
+ It is a base64-encoded text value.
+ </simpara>
</listitem>
- </itemizedlist>
- This value is not case sensitive.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>digest-bits</command> -
- is used to specify the minimum truncated length in bits.
- The default value 0 means truncation is forbidden, non-zero
- values must be an integral number of octets, be greater
- than 80 and the half of the full length. Note in BIND9
- this parameter is appended after a dash to the algorithm
- name.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>secret</command> -
- is used to specify the shared secret key code for this key. This value is
- case sensitive and must exactly match the value specified on the DNS server(s).
- It is a base64-encoded text value.
- </simpara>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- As an example, suppose that a domain D2 will be updating is
- maintained by a BIND9 DNS server which requires dynamic updates
- to be secured with TSIG. Suppose further that the entry for
- the TSIG key in BIND9's named.conf file looks like this:
+ </itemizedlist>
+ </para>
+ <para>
+ As an example, suppose that a domain D2 will be updating is
+ maintained by a BIND9 DNS server which requires dynamic updates
+ to be secured with TSIG. Suppose further that the entry for
+ the TSIG key in BIND9's named.conf file looks like this:
<screen>
:
key "key.four.example.com." {
...
}
</screen>
- </para>
+ </para>
- <para>These steps would be repeated for each TSIG key needed. Note that
- the same TSIG key can be used with more than one domain.</para>
+
<para>These steps would be repeated for each TSIG key needed. Note that
+ the same TSIG key can be used with more than one domain.</para>
</section>
- <!-- "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
- forward DDNS Domains, which is a list of structures.
+ <!-- "d2-tsig-key-list-config" -->
+
- <section id="d2-forward-ddns-config">
++ <section xml:id="d2-forward-ddns-config">
+ <title>Forward DDNS</title>
+ <para>
+ The Forward DDNS section is used to configure D2's forward update
+ behavior. Currently it contains a single parameter, the catalog of
+ forward DDNS Domains, which is a list of structures.
<screen>
"DhcpDdns": {
<userinput>"forward-ddns": {
}
</screen>
- By default, this list is empty, which will cause the server to ignore
- 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
- address mapping) for that zone. You will need one forward DDNS
- Domain for each zone you wish to service. It may very well
- be that some or all of your zones are maintained by the same
- servers. You will still need one DDNS Domain per zone. Remember
- that matching a request to the appropriate server(s) is done
- by zone and a DDNS Domain only defines a single zone.
- </para>
- <para>
- This section describes how to add Forward DDNS Domains. Repeat these
- steps for each Forward DDNS Domain desired. Each Forward DDNS Domain
- has the following parameters:
- <itemizedlist>
- <listitem>
- <simpara>
- <command>name</command> -
- The fully qualified domain name (or zone) that this DDNS Domain
- can update. This is value used to compare against the request
- FQDN during forward matching. It must be unique within the
- catalog.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>key-name</command> -
- If TSIG is used with this domain's servers, this
- value should be the name of the key from within the TSIG Key List
- to use. If the value is blank (the default), TSIG will not be
- used in DDNS conversations with this domain's servers.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>dns-servers</command> -
- A list of one or more DNS servers which can conduct the server
- side of the DDNS protocol for this domain. The servers
- are used in a first to last preference. In other words, when D2
- begins to process a request for this domain it will pick the
- first server in this list and attempt to communicate with it.
- If that attempt fails, it will move to next one in the list and
- so on until the it achieves success or the list is exhausted.
- </simpara>
- </listitem>
- </itemizedlist>
- To create a new forward DDNS Domain, one must add a new domain
- element and set its parameters:
+ By default, this list is empty, which will cause the server to ignore
+ the forward update portions of requests.
+ </para>
- <section id="add-forward-ddns-domain">
++ <section xml:id="add-forward-ddns-domain">
+ <title>Adding Forward DDNS Domains</title>
+ <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
+ address mapping) for that zone. You will need one forward DDNS
+ Domain for each zone you wish to service. It may very well
+ be that some or all of your zones are maintained by the same
+ servers. You will still need one DDNS Domain per zone. Remember
+ that matching a request to the appropriate server(s) is done
+ by zone and a DDNS Domain only defines a single zone.
+ </para>
+ <para>
+ This section describes how to add Forward DDNS Domains. Repeat these
+ steps for each Forward DDNS Domain desired. Each Forward DDNS Domain
+ has the following parameters:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>name</command> -
+ The fully qualified domain name (or zone) that this DDNS Domain
+ can update. This is value used to compare against the request
+ FQDN during forward matching. It must be unique within the
+ catalog.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>key-name</command> -
+ If TSIG is used with this domain's servers, this
+ value should be the name of the key from within the TSIG Key List
+ to use. If the value is blank (the default), TSIG will not be
+ used in DDNS conversations with this domain's servers.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>dns-servers</command> -
+ A list of one or more DNS servers which can conduct the server
+ side of the DDNS protocol for this domain. The servers
+ are used in a first to last preference. In other words, when D2
+ begins to process a request for this domain it will pick the
+ first server in this list and attempt to communicate with it.
+ If that attempt fails, it will move to next one in the list and
+ so on until the it achieves success or the list is exhausted.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ To create a new forward DDNS Domain, one must add a new domain
+ element and set its parameters:
<screen>
"DhcpDdns": {
"forward-ddns": {
}
</screen>
- It is permissible to add a domain without any servers. If that domain
- should be matched to a request, however, the request will fail. In
- order to make the domain useful though, we must add at least one DNS
- server to it.
- </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.
- </para>
- <para>
- Forward DNS Server entries represent actual DNS servers which
- support the server side of the DDNS protocol. Each Forward DNS Server
- has the following parameters:
- <itemizedlist>
- <listitem>
- <simpara>
- <command>hostname</command> -
- The resolvable host name of the DNS server. This value is not
- yet implemented.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>ip-address</command> -
- The IP address at which the server listens for DDNS requests.
- This may be either an IPv4 or an IPv6 address.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>port</command> -
- The port on which the server listens for DDNS requests. It
- defaults to the standard DNS service port of 53.
- </simpara>
- </listitem>
- </itemizedlist>
- To create a new forward DNS Server, one must add a new server
- element to the domain and fill in its parameters. If for
- example the service is running at "172.88.99.10", then set it as
- follows:
+ It is permissible to add a domain without any servers. If that domain
+ should be matched to a request, however, the request will fail. In
+ order to make the domain useful though, we must add at least one DNS
+ server to it.
+ </para>
+
- <section id="add-forward-dns-servers">
++ <section xml:id="add-forward-dns-servers">
+ <title>Adding Forward DNS Servers</title>
+ <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.
+ </para>
+ <para>
+ Forward DNS Server entries represent actual DNS servers which
+ support the server side of the DDNS protocol. Each Forward DNS Server
+ has the following parameters:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>hostname</command> -
+ The resolvable host name of the DNS server. This value is not
+ yet implemented.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>ip-address</command> -
+ The IP address at which the server listens for DDNS requests.
+ This may be either an IPv4 or an IPv6 address.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>port</command> -
+ The port on which the server listens for DDNS requests. It
+ defaults to the standard DNS service port of 53.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ To create a new forward DNS Server, one must add a new server
+ element to the domain and fill in its parameters. If for
+ example the service is running at "172.88.99.10", then set it as
+ follows:
<screen>
"DhcpDdns": {
"forward-ddns": {
</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
- section. Currently it contains a single parameter, the catalog of
- reverse DDNS Domains, which is a list of structures.
- <section id="d2-reverse-ddns-config">
++ <section xml:id="d2-reverse-ddns-config">
+ <title>Reverse DDNS</title>
+ <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
+ section. Currently it contains a single parameter, the catalog of
+ reverse DDNS Domains, which is a list of structures.
<screen>
"DhcpDdns": {
<userinput>"reverse-ddns": {
...
}
</screen>
- By default, this list is empty, which will cause the server to ignore
- 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
- mapping) for that zone. You will need one reverse DDNS Domain
- for each zone you wish to service. It may very well be that
- some or all of your zones are maintained by the same servers;
- even then, you will still need one DDNS Domain entry for each
- zone. Remember that matching a request to the appropriate
- server(s) is done by zone and a DDNS Domain only defines a
- single zone.
- </para>
- <para>
- This section describes how to add Reverse DDNS Domains. Repeat these
- steps for each Reverse DDNS Domain desired. Each Reverse DDNS Domain
- has the following parameters:
- <itemizedlist>
- <listitem>
- <simpara>
- <command>name</command> -
- The fully qualified reverse zone that this DDNS Domain
- can update. This is the value used during reverse matching
- which will compare it with a reversed version of the request's
- lease address. The zone name should follow the appropriate
- standards: for example, to to support the IPv4 subnet 172.16.1,
- the name should be. "1.16.172.in-addr.arpa.". Similarly,
- to support an IPv6 subnet of 2001:db8:1, the name should be
- "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa."
- Whatever the name, it must be unique within the catalog.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>key-name</command> -
- If TSIG should be used with this domain's servers, then this
- value should be the name of that key from the TSIG Key List.
- If the value is blank (the default), TSIG will not be
- used in DDNS conversations with this domain's servers. Currently
- this value is not used as TSIG has not been implemented.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>dns-servers</command> -
- a list of one or more DNS servers which can conduct the server
- side of the DDNS protocol for this domain. Currently the servers
- are used in a first to last preference. In other words, when D2
- begins to process a request for this domain it will pick the
- first server in this list and attempt to communicate with it.
- If that attempt fails, it will move to next one in the list and
- so on until the it achieves success or the list is exhausted.
- </simpara>
- </listitem>
- </itemizedlist>
- To create a new reverse DDNS Domain, one must add a new domain element
- and set its parameters. For example, to support subnet 2001:db8:1::,
- the following configuration could be used:
+ By default, this list is empty, which will cause the server to ignore
+ the reverse update portions of requests.
+ </para>
- <section id="add-reverse-ddns-domain">
++ <section xml:id="add-reverse-ddns-domain">
+ <title>Adding Reverse DDNS Domains</title>
+ <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
+ mapping) for that zone. You will need one reverse DDNS Domain
+ for each zone you wish to service. It may very well be that
+ some or all of your zones are maintained by the same servers;
+ even then, you will still need one DDNS Domain entry for each
+ zone. Remember that matching a request to the appropriate
+ server(s) is done by zone and a DDNS Domain only defines a
+ single zone.
+ </para>
+ <para>
+ This section describes how to add Reverse DDNS Domains. Repeat these
+ steps for each Reverse DDNS Domain desired. Each Reverse DDNS Domain
+ has the following parameters:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>name</command> -
+ The fully qualified reverse zone that this DDNS Domain
+ can update. This is the value used during reverse matching
+ which will compare it with a reversed version of the request's
+ lease address. The zone name should follow the appropriate
+ standards: for example, to to support the IPv4 subnet 172.16.1,
+ the name should be. "1.16.172.in-addr.arpa.". Similarly,
+ to support an IPv6 subnet of 2001:db8:1, the name should be
+ "1.0.0.0.8.B.D.0.1.0.0.2.ip6.arpa."
+ Whatever the name, it must be unique within the catalog.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>key-name</command> -
+ If TSIG should be used with this domain's servers, then this
+ value should be the name of that key from the TSIG Key List.
+ If the value is blank (the default), TSIG will not be
+ used in DDNS conversations with this domain's servers. Currently
+ this value is not used as TSIG has not been implemented.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>dns-servers</command> -
+ a list of one or more DNS servers which can conduct the server
+ side of the DDNS protocol for this domain. Currently the servers
+ are used in a first to last preference. In other words, when D2
+ begins to process a request for this domain it will pick the
+ first server in this list and attempt to communicate with it.
+ If that attempt fails, it will move to next one in the list and
+ so on until the it achieves success or the list is exhausted.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ To create a new reverse DDNS Domain, one must add a new domain element
+ and set its parameters. For example, to support subnet 2001:db8:1::,
+ the following configuration could be used:
<screen>
"DhcpDdns": {
"reverse-ddns": {
}
</screen>
- It is permissible to add a domain without any servers. If that domain
- should be matched to a request, however, the request will fail. In
- order to make the domain useful though, we must add at least one DNS
- server to it.
- </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.
- </para>
- <para>
- Reverse DNS Server entries represents a actual DNS servers which
- support the server side of the DDNS protocol. Each Reverse DNS Server
- has the following parameters:
- <itemizedlist>
- <listitem>
- <simpara>
- <command>hostname</command> -
- The resolvable host name of the DNS server. This value is
- currently ignored.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>ip-address</command> -
- The IP address at which the server listens for DDNS requests.
- </simpara>
- </listitem>
- <listitem>
- <simpara>
- <command>port</command> -
- The port on which the server listens for DDNS requests. It
- defaults to the standard DNS service port of 53.
- </simpara>
- </listitem>
- </itemizedlist>
- To create a new reverse DNS Server, one must first add a new server
- element to the domain and fill in its parameters. If for
- example the service is running at "172.88.99.10", then set it as
- follows:
+ It is permissible to add a domain without any servers. If that domain
+ should be matched to a request, however, the request will fail. In
+ order to make the domain useful though, we must add at least one DNS
+ server to it.
+ </para>
+
- <section id="add-reverse-dns-servers">
++ <section xml:id="add-reverse-dns-servers">
+ <title>Adding Reverse DNS Servers</title>
+ <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.
+ </para>
+ <para>
+ Reverse DNS Server entries represents a actual DNS servers which
+ support the server side of the DDNS protocol. Each Reverse DNS Server
+ has the following parameters:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>hostname</command> -
+ The resolvable host name of the DNS server. This value is
+ currently ignored.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>ip-address</command> -
+ The IP address at which the server listens for DDNS requests.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>port</command> -
+ The port on which the server listens for DDNS requests. It
+ defaults to the standard DNS service port of 53.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ To create a new reverse DNS Server, one must first add a new server
+ element to the domain and fill in its parameters. If for
+ example the service is running at "172.88.99.10", then set it as
+ follows:
<screen>
"DhcpDdns": {
"reverse-ddns": {
</section> <!-- "d2-reverse-ddns-config" -->
- <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"/>
- <colspec colname="fservers"/>
- <colspec colname="rservers"/>
- <thead>
- <row>
- <entry>Domain</entry>
- <entry>Subnet</entry>
- <entry>Forward DNS Servers</entry>
- <entry>Reverse DNS Servers</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>four.example.com</entry>
- <entry>192.0.2.0/24</entry>
- <entry>172.16.1.5, 172.16.2.5</entry>
- <entry>172.16.1.5, 172.16.2.5</entry>
- </row>
- <row>
- <entry>six.example.com</entry>
- <entry>2001:db8:1::/64</entry>
- <entry>3001:1::50</entry>
- <entry>3001:1::51</entry>
- </row>
- <row>
- <entry>example.com</entry>
- <entry>192.0.0.0/16</entry>
- <entry>172.16.2.5</entry>
- <entry>172.16.2.5</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- <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"/>
- <colspec colname="servers"/>
- <thead>
- <row>
- <entry>#</entry>
- <entry>DDNS Domain Name</entry>
- <entry>DNS Servers</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>1.</entry>
- <entry>four.example.com.</entry>
- <entry>172.16.1.5, 172.16.2.5</entry>
- </row>
- <row>
- <entry>2.</entry>
- <entry>six.example.com.</entry>
- <entry>3001:1::50</entry>
- </row>
- <row>
- <entry>3.</entry>
- <entry>example.com.</entry>
- <entry>172.16.2.5</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- As discussed earlier, FQDN to domain matching is based on the longest
- match. The FQDN, "myhost.four.example.com.", will match the first
- domain ("four.example.com") while "admin.example.com." will match the
- third domain ("example.com"). The
- FQDN, "other.example.net." will fail to match any domain and would
- be rejected.
- </para>
- <para>
- The following example configuration specified the Forward DDNS Domains.
- <section id="d2-example-config">
++ <section xml:id="d2-example-config">
+ <title>Example DHCP-DDNS Server Configuration</title>
+ <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>
+ <title>Our example network</title>
- <tgroup cols='4' align='left'>
- <colspec colname='domain'/>
- <colspec colname='subnet'/>
- <colspec colname='fservers'/>
- <colspec colname='rservers'/>
++ <tgroup cols="4" align="left">
++ <colspec colname="domain"/>
++ <colspec colname="subnet"/>
++ <colspec colname="fservers"/>
++ <colspec colname="rservers"/>
+ <thead>
+ <row>
+ <entry>Domain</entry>
+ <entry>Subnet</entry>
+ <entry>Forward DNS Servers</entry>
+ <entry>Reverse DNS Servers</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>four.example.com</entry>
+ <entry>192.0.2.0/24</entry>
+ <entry>172.16.1.5, 172.16.2.5</entry>
+ <entry>172.16.1.5, 172.16.2.5</entry>
+ </row>
+ <row>
+ <entry>six.example.com</entry>
+ <entry>2001:db8:1::/64</entry>
+ <entry>3001:1::50</entry>
+ <entry>3001:1::51</entry>
+ </row>
+ <row>
+ <entry>example.com</entry>
+ <entry>192.0.0.0/16</entry>
+ <entry>172.16.2.5</entry>
+ <entry>172.16.2.5</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <para>
+ We need to construct three forward DDNS Domains:
+ <table>
+ <title>Forward DDNS Domains Needed</title>
- <tgroup cols='3' align='left'>
- <colspec colname='num'/>
- <colspec colname='name'/>
- <colspec colname='servers'/>
++ <tgroup cols="3" align="left">
++ <colspec colname="num"/>
++ <colspec colname="name"/>
++ <colspec colname="servers"/>
+ <thead>
+ <row>
+ <entry>#</entry>
+ <entry>DDNS Domain Name</entry>
+ <entry>DNS Servers</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>1.</entry>
+ <entry>four.example.com.</entry>
+ <entry>172.16.1.5, 172.16.2.5</entry>
+ </row>
+ <row>
+ <entry>2.</entry>
+ <entry>six.example.com.</entry>
+ <entry>3001:1::50</entry>
+ </row>
+ <row>
+ <entry>3.</entry>
+ <entry>example.com.</entry>
+ <entry>172.16.2.5</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ As discussed earlier, FQDN to domain matching is based on the longest
+ match. The FQDN, "myhost.four.example.com.", will match the first
+ domain ("four.example.com") while "admin.example.com." will match the
+ third domain ("example.com"). The
+ FQDN, "other.example.net." will fail to match any domain and would
+ be rejected.
+ </para>
+ <para>
+ The following example configuration specified the Forward DDNS Domains.
<screen><userinput>
"DhcpDdns": {
"forward-ddns": {
}</userinput>
</screen>
- </para>
- <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"/>
- <colspec colname="DDNS Domain DNS Servers"/>
- <thead>
- <row>
- <entry>#</entry>
- <entry>DDNS Domain Name</entry>
- <entry>DNS Servers</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>1.</entry>
- <entry>2.0.192.in-addr.arpa.</entry>
- <entry>172.16.1.5, 172.16.2.5</entry>
- </row>
- <row>
- <entry>2.</entry>
- <entry>1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa.</entry>
- <entry>3001:1::50</entry>
- </row>
- <row>
- <entry>3.</entry>
- <entry>0.182.in-addr.arpa.</entry>
- <entry>172.16.2.5</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- An address of "192.0.2.150" will match the first domain,
- "2001:db8:1::10" will match the second domain, and "192.0.50.77"
- the third domain.
- </para>
- <para>
- These Reverse DDNS Domains are specified as follows:
+ </para>
+ <para>
+ Similarly, we need to construct the three reverse DDNS Domains:
+ <table>
+ <title>Reverse DDNS Domains Needed</title>
- <tgroup cols='3' align='left'>
- <colspec colname='num'/>
- <colspec colname='DDNS Domain name'/>
- <colspec colname='DDNS Domain DNS Servers'/>
++ <tgroup cols="3" align="left">
++ <colspec colname="num"/>
++ <colspec colname="DDNS Domain name"/>
++ <colspec colname="DDNS Domain DNS Servers"/>
+ <thead>
+ <row>
+ <entry>#</entry>
+ <entry>DDNS Domain Name</entry>
+ <entry>DNS Servers</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>1.</entry>
+ <entry>2.0.192.in-addr.arpa.</entry>
+ <entry>172.16.1.5, 172.16.2.5</entry>
+ </row>
+ <row>
+ <entry>2.</entry>
+ <entry>1.0.0.0.8.d.b.0.1.0.0.2.ip6.arpa.</entry>
+ <entry>3001:1::50</entry>
+ </row>
+ <row>
+ <entry>3.</entry>
+ <entry>0.182.in-addr.arpa.</entry>
+ <entry>172.16.2.5</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ An address of "192.0.2.150" will match the first domain,
+ "2001:db8:1::10" will match the second domain, and "192.0.50.77"
+ the third domain.
+ </para>
+ <para>
+ These Reverse DDNS Domains are specified as follows:
<screen><userinput>
"DhcpDdns": {
}</userinput>
</screen>
- </para>
- </section> <!-- end of "d2-example" -->
-
+ </para>
+ </section> <!-- end of "d2-example" -->
</section> <!-- end of section "d2-configuration" -->
-
- <section><info><title>DHCP-DDNS Server Limitations</title></info>
+ <section>
+ <title>DHCP-DDNS Server Limitations</title>
<para>The following are the current limitations of the DHCP-DDNS Server.</para>
<itemizedlist>
- <listitem>
- <simpara>
- Requests received from the DHCP servers are placed in a
- queue until they are processed. Currently all queued requests
- are lost when the server shuts down.
- </simpara>
- </listitem>
+ <listitem>
+ <simpara>
+ Requests received from the DHCP servers are placed in a
+ queue until they are processed. Currently all queued requests
+ are lost when the server shuts down.
+ </simpara>
+ </listitem>
</itemizedlist>
</section>
- </chapter>
- </chapter> <!-- DHCP-DDNS Server -->
++ </chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
-
- <chapter id="dhcp4">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dhcp4">
+ <title>The DHCPv4 Server</title>
+
- <section id="dhcp4-start-stop">
++ <section xml:id="dhcp4-start-stop">
+ <title>Starting and Stopping the DHCPv4 Server</title>
- <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"/>).
</para>
</section>
- <section xml:id="dhcp4-configuration"><info><title>DHCPv4 Server Configuration</title></info>
-
- <section><info><title>Introduction</title></info>
-
- <section id="dhcp4-configuration">
++ <section xml:id="dhcp4-configuration">
+ <title>DHCPv4 Server Configuration</title>
+ <section>
+ <title>Introduction</title>
<para>
This section explains how to configure the DHCPv4 server using the
Kea configuration backend. (Kea configuration using any other
<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>
+ <title>Memfile - Basic Storage for Leases</title>
- <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
+ 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
than a database. As well as requiring less administration, an
advantage of using a file for storage is that it
file used by the server to record lease updates. There are also other files
being created as a side effect of the lease file cleanup. The detailed
description of the LFC is located on the Kea wiki:
- <ulink url="http://kea.isc.org/wiki/LFCDesign"/>.
+ <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>
-<section id="database-configuration4">
++<section xml:id="database-configuration4">
+ <title>Lease Database Configuration</title>
+
<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
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="hosts4-storage"><info><title>Hosts Storage</title></info>
-<section id="hosts4-storage">
++<section xml:id="hosts4-storage">
+ <title>Hosts Storage</title>
<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
from the configuration file are checked first and external storage is checked
later, if necessary.</para>
- <section xml:id="hosts-database-configuration4"><info><title>DHCPv4 Hosts Database Configuration</title></info>
-<section id="hosts-database-configuration4">
++<section xml:id="hosts-database-configuration4">
+ <title>DHCPv4 Hosts Database Configuration</title>
+
<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.
"". (This is also the default.)</para>
</section>
- <section xml:id="read-only-database-configuration4"><info><title>Using Read-Only Databases for Host Reservations</title></info>
-<section id="read-only-database-configuration4">
++<section xml:id="read-only-database-configuration4">
+ <title>Using Read-Only Databases for Host Reservations</title>
<para>
In some deployments the database user whose name is specified in the database backend
configuration may not have write privileges to the database. This is often
</section>
- <section xml:id="dhcp4-interface-configuration"><info><title>Interface Configuration</title></info>
-<section id="dhcp4-interface-configuration">
++<section xml:id="dhcp4-interface-configuration">
+ <title>Interface Configuration</title>
<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:
supported on the particular OS, the server will issue a warning and
fall back to use IP/UDP sockets.</para>
</note>
+
+ <para>Interfaces are re-detected at each reconfiguration. This behavior
+ can be disabled by setting <command>re-detect</command> value to
+ <userinput>false</userinput>, for instance:
+
+ <screen>
+ "Dhcp4": {
+ "interfaces-config": {
+ "interfaces": [ <userinput>"eth1", "eth3"</userinput> ],
+ "re-detect": <userinput>false</userinput>
+ },
+ ...
+ }
+ </screen>
+ Note interfaces are not re-detected during <command>config-test</command>.
+ </para>
+
</section>
- <section xml:id="dhcpinform-unicast-issues"><info><title>Issues with Unicast Responses to DHCPINFORM</title></info>
-<section id="dhcpinform-unicast-issues">
++<section xml:id="dhcpinform-unicast-issues">
+ <title>Issues with Unicast Responses to DHCPINFORM</title>
<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
</para>
</section>
- <section xml:id="ipv4-subnet-id"><info><title>IPv4 Subnet Identifier</title></info>
-<section id="ipv4-subnet-id">
++<section xml:id="ipv4-subnet-id">
+ <title>IPv4 Subnet Identifier</title>
<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.
id -->
</section>
- <section xml:id="dhcp4-address-config"><info><title>Configuration of IPv4 Address Pools</title></info>
-<section id="dhcp4-address-config">
++<section xml:id="dhcp4-address-config">
+ <title>Configuration of IPv4 Address Pools</title>
<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.
</para>
</section>
- <section xml:id="dhcp4-std-options"><info><title>Standard DHCPv4 Options</title></info>
- <section id="dhcp4-std-options">
++ <section xml:id="dhcp4-std-options">
+ <title>Standard DHCPv4 Options</title>
<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
...
]
}
- </screen>
+ </screen>
+ Note that only one of name or code is required, you don't need to
+ specify both. Space has a default value of "dhcp4", so you can skip this
+ as well if you define a regular (not encapsulated) DHCPv4 option.
+ Finally, csv-format defaults to true, so it too can be skipped, unless
+ you want to specify the option value as hexstring. Therefore the
+ above example can be simplified to:
+ <screen>
+ "Dhcp4": {
+ "option-data": [
+ {
+ <userinput>"name": "domain-name-servers",
+ "data": "192.0.2.1, 192.0.2.2"</userinput>
+ },
+ ...
+ ]
+ }
+ </screen>
+ Defined options are added to response when the client requests them
+ at a few exceptions which are always added. To enforce the addition
+ of a particular option set the always-send flag to true as in:
+ <screen>
+ "Dhcp4": {
+ "option-data": [
+ {
+ <userinput>"name": "domain-name-servers",
+ "data": "192.0.2.1, 192.0.2.2",
+ "always-send": true</userinput>
+ },
+ ...
+ ]
+ }
+ </screen>
+ The effect is the same as if the client added the option code in the
+ Parameter Request List option (or its equivalent for vendor
+ options) so in:
+ <screen>
+ "Dhcp4": {
+ "option-data": [
+ {
+ <userinput>"name": "domain-name-servers",
+ "data": "192.0.2.1, 192.0.2.2",
+ "always-send": true</userinput>
+ },
+ ...
+ ],
+ "subnet4": [
+ {
+ "subnet": "192.0.3.0/24",
+ "option-data": [
+ {
+ <userinput>"name": "domain-name-servers",
+ "data": "192.0.3.1, 192.0.3.2"</userinput>
+ },
+ ...
+ ],
+ ...
+ },
+ ...
+ ],
+ ...
+ }
+ </screen>
+ The Domain Name Servers option is always added to responses
+ (the always-send is "sticky") but the value is the subnet one
+ when the client is localized in the subnet.
</para>
<para>
- The <command>name</command> parameter specifies the
- option name. For a list of currently supported names, see
- <xref linkend="dhcp4-std-options-list"/> below.
- The <command>code</command> parameter specifies the option code, which must match one of the
- values from that list. The next line specifies the option space, which must always
- be set to "dhcp4" as these are standard DHCPv4 options. For
- other option spaces, including custom option spaces, see <xref linkend="dhcp4-option-spaces"/>. The next line specifies the format in
- which the data will be entered: use of CSV (comma
- separated values) is recommended. The sixth line gives the actual value to
- be sent to clients. Data is specified as normal text, with
- values separated by commas if more than one value is
- allowed.
+ The <command>name</command> parameter specifies the option name. For a
- list of currently supported names, see <xref
- linkend="dhcp4-std-options-list"/> below. The <command>code</command>
++ list of currently supported names, see <xref linkend="dhcp4-std-options-list"/> below. The <command>code</command>
+ parameter specifies the option code, which must match one of the values
+ from that list. The next line specifies the option space, which must
+ always be set to "dhcp4" as these are standard DHCPv4 options. For other
- option spaces, including custom option spaces, see <xref
- linkend="dhcp4-option-spaces"/>. The next line specifies the format in
++ option spaces, including custom option spaces, see <xref linkend="dhcp4-option-spaces"/>. The next line specifies the format in
+ which the data will be entered: use of CSV (comma separated values) is
+ recommended. The sixth line gives the actual value to be sent to
+ clients. Data is specified as normal text, with values separated by commas
+ if more than one value is allowed.
</para>
<para>
structures. "Type" designates the format of the data: the meanings of
the various types is given in <xref linkend="dhcp-types"/>.
</para>
- For example, the string "foo,bar" would be represented as:
+
+ <para>When a data field is a string, and that string contains the comma
+ (,; U+002C) character, the comma must be escaped with a double reverse solidus
+ character (\; U+005C). This double escape is required, because both the
+ routine splitting CSV data into fields and JSON use the same escape
+ character: a single escape (\,) would make the JSON invalid.
++ For example, the string "foo,bar" would be represented as:
+ <screen>
+ "Dhcp4": {
+ "subnet4": [
+ {
+ "pools": [
+ {
+ <userinput>"option-data": [
+ {
+ "name": "boot-file-name",
+ "data": "foo\\,bar"
+ }
+ ]</userinput>
+ },
+ ...
+ ],
+ ...
+ },
+ ...
+ ],
+ ...
+ }
+ </screen>
+ </para>
<para>
Some options are designated as arrays, which means that more than one
value is allowed in such an option. For example the option time-servers
</para>
<para>
- <table frame="all" xml:id="dhcp4-std-options-list"><info><title>List of standard DHCPv4 options</title></info>
-
- <table frame="all" id="dhcp4-std-options-list">
++ <table frame="all" xml:id="dhcp4-std-options-list">
+ <title>List of standard DHCPv4 options</title>
- <tgroup cols='5'>
- <colspec colname='name'/>
- <colspec colname='code' align='center'/>
- <colspec colname='type' align='center'/>
- <colspec colname='array' align='center'/>
- <colspec colname='always-returned' align='center'/>
+ <tgroup cols="5">
+ <colspec colname="name"/>
+ <colspec colname="code" align="center"/>
+ <colspec colname="type" align="center"/>
+ <colspec colname="array" align="center"/>
+ <colspec colname="always-returned" align="center"/>
<thead>
<row>
<entry>Name</entry>
</para>
<para>
- <table frame="all" xml:id="dhcp-types"><info><title>List of standard DHCP option types</title></info>
-
- <table frame="all" id="dhcp-types">
++ <table frame="all" xml:id="dhcp-types">
+ <title>List of standard DHCP option types</title>
- <tgroup cols='2'>
- <colspec colname='name'/>
- <colspec colname='meaning'/>
+ <tgroup cols="2">
+ <colspec colname="name"/>
+ <colspec colname="meaning"/>
<thead>
<row><entry>Name</entry><entry>Meaning</entry></row>
</thead>
<row><entry>ipv4-address</entry><entry>IPv4 address in the usual dotted-decimal notation (e.g. 192.0.2.1)</entry></row>
<row><entry>ipv6-address</entry><entry>IPv6 address in the usual colon notation (e.g. 2001:db8::1)</entry></row>
<row><entry>ipv6-prefix</entry><entry>IPv6 prefix and prefix length specified using CIDR notation, e.g. 2001:db8:1::/64. This data type is used to represent an 8-bit field conveying a prefix length and the variable length prefix value</entry></row>
- <row><entry>psid</entry><entry>PSID and PSID length separated by a slash, e.g. 3/4 specifies PSID=3 and PSID length=4. In the wire format it is represented by an 8-bit field carrying PSID length (in this case equal to 4) and the 16-bits long PSID value field (in this case equal to "0011000000000000b" using binary notation). Allowed values for a PSID length are 0 to 16. See <ulink url="http://tools.ietf.org/html/rfc7597">RFC 7597</ulink> for the details about the PSID wire representation</entry></row>
+ <row><entry>psid</entry><entry>PSID and PSID length separated by a slash, e.g. 3/4 specifies PSID=3 and PSID length=4. In the wire format it is represented by an 8-bit field carrying PSID length (in this case equal to 4) and the 16-bits long PSID value field (in this case equal to "0011000000000000b" using binary notation). Allowed values for a PSID length are 0 to 16. See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7597">RFC 7597</link> for the details about the PSID wire representation</entry></row>
<row><entry>record</entry><entry>Structured data that may comprise any types (except "record" and "empty")</entry></row>
<row><entry>string</entry><entry>Any text</entry></row>
+ <row><entry>tuple</entry><entry>A length encoded as a 8 (16 for DHCPv6) bit unsigned integer followed by a string of this length</entry></row>
<row><entry>uint8</entry><entry>8 bit unsigned integer with allowed values 0 to 255</entry></row>
<row><entry>uint16</entry><entry>16 bit unsigned integer with allowed values 0 to 65535</entry></row>
<row><entry>uint32</entry><entry>32 bit unsigned integer with allowed values 0 to 4294967295</entry></row>
</para>
</section>
- <section xml:id="dhcp4-custom-options"><info><title>Custom DHCPv4 options</title></info>
- <section id="dhcp4-custom-options">
++ <section xml:id="dhcp4-custom-options">
+ <title>Custom DHCPv4 options</title>
<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
<command>"1"</command>. Future versions of Kea will accept all those values
for all boolean parameters.</para>
</note>
+ <note>
+ <para>Numbers can be specified in decimal or hexadecimal format.
+ The hexadecimal format can be either plain (e.g. abcd) or
+ prefixed with 0x (e.g. 0xabcd).
+ </para>
+ </note>
</section>
- <section xml:id="dhcp4-vendor-opts"><info><title>DHCPv4 Vendor Specific Options</title></info>
- <section id="dhcp4-vendor-opts">
++ <section xml:id="dhcp4-vendor-opts">
+ <title>DHCPv4 Vendor Specific Options</title>
<para>
Currently there are two option spaces defined for the DHCPv4 daemon:
"dhcp4" (for the top level DHCPv4 options) and
</para>
</section>
- <section xml:id="dhcp4-option-spaces"><info><title>Nested DHCPv4 Options (Custom Option Spaces)</title></info>
- <section id="dhcp4-option-spaces">
++ <section xml:id="dhcp4-option-spaces">
+
+ <title>Nested DHCPv4 Options (Custom Option Spaces)</title>
<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
</para>
</section>
- <section xml:id="dhcp4-option-data-defaults"><info><title>Unspecified Parameters for DHCPv4 Option Configuration</title></info>
- <section id="dhcp4-option-data-defaults">
++ <section xml:id="dhcp4-option-data-defaults">
+ <title>Unspecified Parameters for DHCPv4 Option Configuration</title>
<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
</listitem>
</itemizedlist>
</para>
+
</section>
- <section xml:id="dhcp4-stateless-configuration"><info><title>Stateless Configuration of DHCPv4 Clients</title></info>
- <section id="dhcp4-stateless-configuration">
++ <section xml:id="dhcp4-stateless-configuration">
+ <title>Stateless Configuration of DHCPv4 Clients</title>
<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.
</para>
</section>
- <section xml:id="dhcp4-client-classifier"><info><title>Client Classification in DHCPv4</title></info>
- <section id="dhcp4-client-classifier">
++ <section xml:id="dhcp4-client-classifier">
+ <title>Client Classification in DHCPv4</title>
<para>
The DHCPv4 server includes support for client classification. For a deeper
discussion of the classification process see <xref linkend="classify"/>.
}</screen>
</para>
</section>
-
</section>
- <section xml:id="dhcp4-ddns-config"><info><title>DDNS for DHCPv4</title></info>
- <section id="dhcp4-ddns-config">
++ <section xml:id="dhcp4-ddns-config">
+ <title>DDNS for DHCPv4</title>
<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
</itemizedlist>
</para>
- <section xml:id="dhcpv4-d2-io-config"><info><title>DHCP-DDNS Server Connectivity</title></info>
- <section id="dhcpv4-d2-io-config">
++ <section xml:id="dhcpv4-d2-io-config">
+ <title>DHCP-DDNS Server Connectivity</title>
<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
</screen>
</para>
</section>
-
- <section xml:id="dhcpv4-d2-rules-config"><info><title>When Does the kea-dhcp4 Server Generate DDNS Requests?</title></info>
- <section id="dhcpv4-d2-rules-config">
++ <section xml:id="dhcpv4-d2-rules-config">
+ <title>When Does the kea-dhcp4 Server Generate DDNS Requests?</title>
<para>kea-dhcp4 follows the behavior prescribed for DHCP servers in
- <ulink url="http://tools.ietf.org/html/rfc4702">RFC 4702</ulink>.
+ <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
making of when and what to update and forwards that information to D2 in
the form of NCRs. Carrying out the actual DNS updates and dealing with
will respect the FQDN N and S flags specified by the client as shown
in the following table:
</para>
- <table xml:id="fqdn-flag-table"><info><title>Default FQDN Flag Behavior</title></info>
-
- <table id="fqdn-flag-table">
++ <table xml:id="fqdn-flag-table">
+ <title>Default FQDN Flag Behavior</title>
- <tgroup cols='4' align='left'>
- <colspec colname='cflags'/>
- <colspec colname='meaning'/>
- <colspec colname='response'/>
- <colspec colname='sflags'/>
+ <tgroup cols="4" align="left">
+ <colspec colname="cflags"/>
+ <colspec colname="meaning"/>
+ <colspec colname="response"/>
+ <colspec colname="sflags"/>
<thead>
<row>
<entry>Client Flags:N-S</entry>
</para>
</section>
- <section xml:id="dhcpv4-fqdn-name-generation"><info><title>kea-dhcp4 name generation for DDNS update requests</title></info>
- <section id="dhcpv4-fqdn-name-generation">
++ <section xml:id="dhcpv4-fqdn-name-generation">
+ <title>kea-dhcp4 name generation for DDNS update requests</title>
<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
</para>
</section>
- <section xml:id="dhcp4-next-server"><info><title>Next Server (siaddr)</title></info>
- <section id="dhcp4-next-server">
++ <section xml:id="dhcp4-next-server">
+ <title>Next Server (siaddr)</title>
<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
</screen>
</section>
- <section xml:id="dhcp4-echo-client-id"><info><title>Echoing Client-ID (RFC 6842)</title></info>
- <section id="dhcp4-echo-client-id">
++ <section xml:id="dhcp4-echo-client-id">
+ <title>Echoing Client-ID (RFC 6842)</title>
<para>The original DHCPv4 specification
- (<ulink url="http://tools.ietf.org/html/rfc2131">RFC 2131</ulink>)
+ (<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc2131">RFC 2131</link>)
states that the DHCPv4
server must not send back client-id options when responding to
clients. However, in some cases that confused clients that did
</screen>
</section>
- <section xml:id="dhcp4-match-client-id"><info><title>Using Client Identifier and Hardware Address</title></info>
- <section id="dhcp4-match-client-id">
++ <section xml:id="dhcp4-match-client-id">
+ <title>Using Client Identifier and Hardware Address</title>
<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:
assumed to belong to another client and the new lease will be
allocated.
</para>
+
</section>
- <section xml:id="dhcp4-dhcp4o6-config"><info><title>DHCPv4-over-DHCPv6: DHCPv4 Side</title></info>
- <section id="dhcp4-dhcp4o6-config">
++ <section xml:id="dhcp4-dhcp4o6-config">
+ <title>DHCPv4-over-DHCPv6: DHCPv4 Side</title>
<para>
The support of DHCPv4-over-DHCPv6 transport is described in
- <ulink url="http://tools.ietf.org/html/rfc7341">RFC 7341</ulink>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7341">RFC 7341</link>
and is implemented using cooperating DHCPv4 and DHCPv6 servers.
This section is about the configuration of the DHCPv4 side
(the DHCPv6 side is described in <xref linkend="dhcp6-dhcp4o6-config"/>).
<!-- 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>
- <section id="host-reservation-v4">
++ <section xml:id="host-reservation-v4">
+ <title>Host Reservation in DHCPv4</title>
+
<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
+ address for exclusive use by a given client (host) ‐ the returning client will
receive the same address from the server every time, and other clients will
generally not receive that address.
Another example when the host reservations are applicable is when a host
could be used by someone else (i.e. there is a reservation for it). That
additional check incurs additional overhead.</para>
- <section xml:id="reservation4-types"><info><title>Address Reservation Types</title></info>
- <section id="reservation4-types">
++ <section xml:id="reservation4-types">
+ <title>Address Reservation Types</title>
+
<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
possible.</para>
</section>
- <section xml:id="reservation4-conflict"><info><title>Conflicts in DHCPv4 Reservations</title></info>
- <section id="reservation4-conflict">
++ <section xml:id="reservation4-conflict">
+ <title>Conflicts in DHCPv4 Reservations</title>
<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
</para>
</section>
- <section xml:id="reservation4-hostname"><info><title>Reserving a Hostname</title></info>
- <section id="reservation4-hostname">
++ <section xml:id="reservation4-hostname">
+ <title>Reserving a Hostname</title>
<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
</para>
</section>
- <section xml:id="reservation4-options"><info><title>Including Specific DHCPv4 Options in Reservations</title></info>
- <section id="reservation4-options">
++ <section xml:id="reservation4-options">
+ <title>Including Specific DHCPv4 Options in Reservations</title>
<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
- (see <xref linkend="dhcp4-vendor-opts" />). The following
+ options. These can be standard options (see <xref linkend="dhcp4-std-options"/>), custom options (see <xref linkend="dhcp4-custom-options"/>) or vendor specific options
+ (see <xref linkend="dhcp4-vendor-opts"/>). The following
example demonstrates how standard options can be defined.</para>
<screen>
if there are options defined with the same type on global, subnet, class and
host level, the host specific values will be used.
</para>
+
</section>
- <section xml:id="reservation4-message-fields"><info><title>Reserving Next Server, Server Hostname and Boot File Name</title></info>
- <section id="reservation4-message-fields">
++ <section xml:id="reservation4-message-fields">
+ <title>Reserving Next Server, Server Hostname and Boot File Name</title>
<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
them can be omitted.</para>
</section>
- <section xml:id="reservation4-client-classes"><info><title>Reserving Client Classes in DHCPv4</title></info>
- <section id="reservation4-client-classes">
++ <section xml:id="reservation4-client-classes">
+ <title>Reserving Client Classes in DHCPv4</title>
<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
with classification using expressions.</para>
</section>
- <section xml:id="reservations4-mysql-pgsql-cql"><info><title>Storing Host Reservations in MySQL, PostgreSQL or CQL (Cassandra)</title></info>
- <section id="reservations4-mysql-pgsql">
++ <section xml:id="reservations4-mysql-pgsql">
+ <title>Storing Host Reservations in MySQL or PostgreSQL</title>
+
<para>
- It is possible to store host reservations in MySQL, PostgreSQL or Cassandra. See
+ It is possible to store host reservations in MySQL or PostgreSQL database. See
<xref linkend="hosts4-storage"/> for information on how to configure Kea to use
- reservations stored in MySQL, PostgreSQL or Cassandra. Kea does not provide any dedicated
+ reservations stored in MySQL or PostgreSQL. Kea does not provide any dedicated
- tools for managing reservations in a database. The Kea wiki <ulink
- url="http://kea.isc.org/wiki/HostReservationsHowTo" /> 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>
arbitrarily set to 4096 bytes.</simpara></note>
</section>
- <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 id="reservations4-cql">
++ <section xml:id="reservations4-cql">
+ <title>Storing host reservations in CQL (Cassandra)</title>
+ <para>Kea currently does not support storing reservations in
+ Cassandra (CQL).</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>
- <section id="reservations4-tuning">
++ <section xml:id="reservations4-tuning">
+ <title>Fine Tuning DHCPv4 Host Reservation</title>
+
<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
</section>
<!-- end of host reservations section -->
- <section xml:id="dhcp4-serverid"><info><title>Server Identifier in DHCPv4</title></info>
- <section id="dhcp4-serverid">
++ <section xml:id="dhcp4-serverid">
+ <title>Server Identifier in DHCPv4</title>
<para>
The DHCPv4 protocol uses a "server identifier" to allow clients
to discriminate between several servers present on the same link: this
</para>
</section>
- <section xml:id="dhcp4-subnet-selection"><info><title>How the DHCPv4 Server Selects a Subnet for the Client</title></info>
- <section id="dhcp4-subnet-selection">
++ <section xml:id="dhcp4-subnet-selection">
+ <title>How the DHCPv4 Server Selects a Subnet for the Client</title>
<para>
The DHCPv4 server differentiates between the directly connected clients,
clients trying to renew leases and clients sending their messages through
depending on the classes to which the client belongs.</para>
</note>
- <section xml:id="dhcp4-relay-override"><info><title>Using a Specific Relay Agent for a Subnet</title></info>
- <section id="dhcp4-relay-override">
++ <section xml:id="dhcp4-relay-override">
+ <title>Using a Specific Relay Agent for a Subnet</title>
<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
</screen>
</para>
+ <para>If "relay" is specified, the "ip-address" parameter within
+ it is mandatory.</para>
+
</section>
- <section xml:id="dhcp4-srv-example-client-class-relay"><info><title>Segregating IPv4 Clients in a Cable Network</title></info>
- <section id="dhcp4-srv-example-client-class-relay">
++ <section xml:id="dhcp4-srv-example-client-class-relay">
+ <title>Segregating IPv4 Clients in a Cable Network</title>
<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>
- <section id="dhcp4-decline">
++ <section xml:id="dhcp4-decline">
+ <title>Duplicate Addresses (DHCPDECLINE Support)</title>
+
<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
potential for major issues, we decided not to decrease assigned addresses
immediately after receiving DHCPDECLINE, but to do it later when we
recover the address back to the available pool.</para>
+
</section>
- <section xml:id="dhcp4-stats"><info><title>Statistics in the DHCPv4 Server</title></info>
- <section id="dhcp4-stats">
++ <section xml:id="dhcp4-stats">
+ <title>Statistics in the DHCPv4 Server</title>
<note>
<para>This section describes DHCPv4-specific statistics. For a general
- overview and usage of statistics, see <xref linkend="stats" />.</para>
+ overview and usage of statistics, see <xref linkend="stats"/>.</para>
</note>
<para>
The DHCPv4 server supports the following statistics:
</para>
- <table frame="all" xml:id="dhcp4-statistics"><info><title>DHCPv4 Statistics</title></info>
-
- <table frame="all" id="dhcp4-statistics">
++ <table frame="all" xml:id="dhcp4-statistics">
+ <title>DHCPv4 Statistics</title>
- <tgroup cols='3'>
- <colspec colname='statistic' align='center'/>
- <colspec colname='type' align='center'/>
- <colspec colname='description' align='left'/>
+ <tgroup cols="3">
+ <colspec colname="statistic" align="center"/>
+ <colspec colname="type" align="center"/>
+ <colspec colname="description" align="left"/>
<thead>
<row>
<entry>Statistic</entry>
</table>
</section>
- <section xml:id="dhcp4-ctrl-channel"><info><title>Management API for the DHCPv4 Server</title></info>
- <section id="dhcp4-ctrl-channel">
++ <section xml:id="dhcp4-ctrl-channel">
+ <title>Management API for the DHCPv4 Server</title>
<para>
The management API allows the issuing of specific
management commands, such as statistics retrieval, reconfiguration or shutdown.
<para>
Communication over control channel is conducted using JSON structures.
- See the Control Channel section in the Kea Developer's Guide for more details.
+ See the Control Channel section in the Kea Developer's Guide for more
+ details.
+ </para>
+
+ <para>The DHCPv4 server supports the following operational commands:
+ <itemizedlist>
+ <listitem>build-report</listitem>
+ <listitem>config-get</listitem>
+ <listitem>config-reload</listitem>
+ <listitem>config-set</listitem>
+ <listitem>config-test</listitem>
+ <listitem>config-write</listitem>
+ <listitem>leases-reclaim</listitem>
+ <listitem>list-commands</listitem>
+ <listitem>shutdown</listitem>
+ <listitem>version-get</listitem>
+ </itemizedlist>
+ as described in <xref linkend="commands-common"/>. In addition,
+ it supports the following statistics related commands:
+ <itemizedlist>
+ <listitem>statistic-get</listitem>
+ <listitem>statistic-reset</listitem>
+ <listitem>statistic-remove</listitem>
+ <listitem>statistic-get-all</listitem>
+ <listitem>statistic-reset-all</listitem>
+ <listitem>statistic-remove-all</listitem>
+ </itemizedlist>
+ as described here <xref linkend="command-stats"/>.
</para>
- <para>The DHCPv4 server supports <command>statistic-get</command>,
- <command>statistic-reset</command>, <command>statistic-remove</command>,
- <command>statistic-get-all</command>, <command>statistic-reset-all</command>
- and <command>statistic-remove-all</command>, specified in
- <xref linkend="command-stats"/>. It also supports
- <command>list-commands</command> and <command>shutdown</command>,
- specified in <xref linkend="command-list-commands"/> and
- <xref linkend="command-shutdown"/>, respectively.</para>
</section>
- <section xml:id="dhcp4-std"><info><title>Supported DHCP Standards</title></info>
- <section id="dhcp4-std">
++ <section xml:id="dhcp4-std">
+ <title>Supported DHCP Standards</title>
<para>The following standards are currently supported:</para>
<itemizedlist>
<listitem>
</para>
</section>
- <section xml:id="dhcp4-limit"><info><title>DHCPv4 Server Limitations</title></info>
- <section id="dhcp4-limit">
++ <section xml:id="dhcp4-limit">
+ <title>DHCPv4 Server Limitations</title>
<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
</section> -->
-- </chapter>
++ </chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
-
- <chapter id="dhcp6">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="dhcp6">
+ <title>The DHCPv6 Server</title>
+
- <section id="dhcp6-start-stop">
++ <section xml:id="dhcp6-start-stop">
+ <title>Starting and Stopping the DHCPv6 Server</title>
- <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"/>).
</para>
</section>
- <section xml:id="dhcp6-configuration"><info><title>DHCPv6 Server Configuration</title></info>
-
- <section><info><title>Introduction</title></info>
-
- <section id="dhcp6-configuration">
++ <section xml:id="dhcp6-configuration">
+ <title>DHCPv6 Server Configuration</title>
+ <section>
+ <title>Introduction</title>
<para>
This section explains how to configure the DHCPv6 server using the
Kea configuration backend. (Kea configuration using any other
<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>
+ <title>Memfile - Basic Storage for Leases</title>
- <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
+ 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
than a database. As well as requiring less administration, an
advantage of using a file for storage is that it
file used by the server to record lease updates. There are also other files
being created as a side effect of the lease file cleanup. The detailed
description of the LFC is located on the Kea wiki:
- <ulink url="http://kea.isc.org/wiki/LFCDesign"/>.
+ <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>
-<section id="database-configuration6">
++<section xml:id="database-configuration6">
+ <title>Lease Database Configuration</title>
+
<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>
-<section id="hosts6-storage">
++<section xml:id="hosts6-storage">
+ <title>Hosts Storage</title>
<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
from the configuration file are checked first and external storage is checked
later, if necessary.</para>
- <section xml:id="hosts-database-configuration6"><info><title>DHCPv6 Hosts Database Configuration</title></info>
-<section id="hosts-database-configuration6">
++<section xml:id="hosts-database-configuration6">
+ <title>DHCPv6 Hosts Database Configuration</title>
+
<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.
"". (This is also the default.)</para>
</section>
- <section xml:id="read-only-database-configuration6"><info><title>Using Read-Only Databases for Host Reservations</title></info>
-<section id="read-only-database-configuration6">
++<section xml:id="read-only-database-configuration6">
+ <title>Using Read-Only Databases for Host Reservations</title>
<para>
In some deployments the database user whose name is specified in the database backend
configuration may not have write privileges to the database. This is often
</section>
- <section xml:id="dhcp6-interface-selection"><info><title>Interface Selection</title></info>
+
-<section id="dhcp6-interface-selection">
++<section xml:id="dhcp6-interface-selection">
+ <title>Interface Selection</title>
<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:
It is anticipated that this will form of usage only be used where it is desired to
temporarily override a list of interface names and listen on all interfaces.
</para>
+
+ <para>As for the DHCPv4 server binding to specific addresses and
+ disabling re-detection of interfaces are supported. But
+ <command>dhcp-socket-type</command> is not because DHCPv6 uses
+ UDP/IPv6 sockets only. The following example shows how to disable the
+ interface detection:
+ </para>
+
+ <screen>
+ "Dhcp6": {
+ "interfaces-config": {
+ "interfaces": [ <userinput>"eth1", "eth3"</userinput> ],
+ "re-detect": <userinput>false</userinput>
+ },
+ ...
+ }
+ </screen>
+
</section>
- <section xml:id="ipv6-subnet-id"><info><title>IPv6 Subnet Identifier</title></info>
- <section id="ipv6-subnet-id">
++ <section xml:id="ipv6-subnet-id">
+ <title>IPv6 Subnet Identifier</title>
<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.
id -->
</section>
- <section xml:id="dhcp6-unicast"><info><title>Unicast Traffic Support</title></info>
- <section id="dhcp6-unicast">
++ <section xml:id="dhcp6-unicast">
+ <title>Unicast Traffic Support</title>
<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
</para>
</section>
- <section xml:id="dhcp6-address-config"><info><title>Subnet and Address Pool</title></info>
- <section id="dhcp6-address-config">
++ <section xml:id="dhcp6-address-config">
+ <title>Subnet and Address Pool</title>
<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
</para>
</section>
- <section><info><title>Subnet and Prefix Delegation Pools</title></info>
+ <section>
+ <title>Subnet and Prefix Delegation Pools</title>
<para>
Subnets may also be configured to delegate prefixes, as defined in
- <ulink url="http://tools.ietf.org/html/rfc3633">RFC 3633</ulink>. A
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc3633">RFC 3633</link>. A
subnet may have one or more prefix delegation pools. Each pool has a
prefixed address, which is specified as a prefix
(<command>prefix</command>) and a prefix length
...
}</screen>
</para>
+
</section>
- <section xml:id="pd-exclude-option"><info><title>Prefix Exclude Option</title></info>
- <section id="pd-exclude-option">
++ <section xml:id="pd-exclude-option">
+ <title>Prefix Exclude Option</title>
<para>
For each delegated prefix the delegating router may choose to exclude
a single prefix out of the delegated prefix as specified in the
</screen>
</section>
- <section xml:id="dhcp6-std-options"><info><title>Standard DHCPv6 Options</title></info>
- <section id="dhcp6-std-options">
++ <section xml:id="dhcp6-std-options">
+ <title>Standard DHCPv6 Options</title>
<para>
One of the major features of a DHCPv6 server is to provide configuration
options to clients. Although there are several options that require
which was not assigned by IANA) are listed in
<xref linkend="dhcp6-exp-options-list"/>.
</para>
- "EST5EDT4,M3.2.0/02:00,M11.1.0/02:00" would be
+ <para>When a data field is a string, and that string contains
+ the comma (,; U+002C) character, the comma must be escaped with a
+ reverse solidus character (\; U+005C). This double escape is
+ required, because both the routine splitting CSV data into fields
+ and JSON use the same escape character: a single escape (\,) would
+ make the JSON invalid. For example, the string
++ "EST5EDT4,M3.2.0/02:00,M11.1.0/02:00" would be
+ represented as:
+ <screen>
+ "Dhcp6": {
+ "subnet6": [
+ {
+ "pools": [
+ {
+ <userinput>"option-data": [
+ {
+ "name": "new-posix-timezone",
+ "data": "EST5EDT4\,M3.2.0/02:00\,M11.1.0/02:00"
+ }
+ ]</userinput>
+ },
+ ...
+ ],
+ ...
+ },
+ ...
+ ],
+ ...
+ }
+ </screen>
+ </para>
<para>
Some options are designated as arrays, which means that more than one
value is allowed in such an option. For example the option dns-servers
<para>
- <table frame="all" xml:id="dhcp6-std-options-list"><info><title>List of Standard DHCPv6 Options</title></info>
-
- <table frame="all" id="dhcp6-std-options-list">
++ <table frame="all" xml:id="dhcp6-std-options-list">
+ <title>List of Standard DHCPv6 Options</title>
- <tgroup cols='4'>
- <colspec colname='name'/>
- <colspec colname='code' align='center'/>
- <colspec colname='type' align='center'/>
- <colspec colname='array' align='center'/>
+ <tgroup cols="4">
+ <colspec colname="name"/>
+ <colspec colname="code" align="center"/>
+ <colspec colname="type" align="center"/>
+ <colspec colname="array" align="center"/>
<thead>
<row><entry>Name</entry><entry>Code</entry><entry>Type</entry><entry>Array?</entry></row>
</thead>
</para>
<para>
- <table frame="all" xml:id="dhcp6-exp-options-list"><info><title>List of Experimental DHCPv6 Options</title></info>
-
- <table frame="all" id="dhcp6-exp-options-list">
++ <table frame="all" xml:id="dhcp6-exp-options-list">
+ <title>List of Experimental DHCPv6 Options</title>
- <tgroup cols='4'>
- <colspec colname='name'/>
- <colspec colname='code' align='center'/>
- <colspec colname='type' align='center'/>
- <colspec colname='array' align='center'/>
+ <tgroup cols="4">
+ <colspec colname="name"/>
+ <colspec colname="code" align="center"/>
+ <colspec colname="type" align="center"/>
+ <colspec colname="array" align="center"/>
<thead>
<row><entry>Name</entry><entry>Code</entry><entry>Type</entry><entry>Array?</entry></row>
</thead>
</para>
</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
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7598">RFC 7598</link>.
- The following sections provide configuration examples of these
- options.
- </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 Lightweight 4over6 Container option.
- These options only contain encapsulated options specified below.
- They do not include any data fields.
- </para>
-
- <para>
- In order to configure the server to send specific container option
- along with all encapsulated options, the container option must be
- included in the server configuration as shown below:
- <screen>
- "Dhcp6": {
- ...
- "option-data": [
- {
- "name": "s46-cont-mape"
- } ],
- ...
- }
- </screen>
-
- This configuration will cause the server to include MAP-E Container
- option to the client. Use "s46-cont-mapt" or "s46-cont-lw" for the
- MAP-T Container and S46 Lightweight 4over6 Container options
- respectively.
- </para>
-
- <para>
- All remaining softwire options described below are included in one
- of the container options. Thus, they have to be included in appropriate
- option spaces by selecting a "space" name, which specifies in which
- option they are supposed to be included.
- </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).
- <screen>
- {
- "space": "s46-cont-mape-options",
- "name": "s46-rule",
- "data": "128, 0, 24, 192.0.2.0, 2001:db8:1::/64"
- }
- </screen>
- Other possible "space" value is "s46-cont-mapt-options".
- </para>
-
- <para>
- The S46 Rule option conveys a number of parameters:
-
- <itemizedlist>
- <listitem>
- <simpara><command>flags</command>, an unsigned 8 bits integer, with
- currently only the most significant bit specified. It denotes whether
- the rule can be used for forwarding (128) or not (0).
- </simpara>
- </listitem>
-
- <listitem>
- <simpara><command>ea-len</command>, an 8 bits long Embedded Address length. Allowed values
- range from 0 to 48.</simpara>
- </listitem>
-
- <listitem>
- <simpara><command>IPv4 prefix length</command>, 8 bits long; expresses the prefix length of the
- Rule IPv4 prefix specified in the ipv4-prefix field. Allowed
- values range from 0 to 32.</simpara>
- </listitem>
-
- <listitem>
- <simpara><command>IPv4 prefix</command>, a fixed-length 32-bit field that specifies the IPv4
- prefix for the S46 rule. The bits in the prefix after prefix4-len
- number of bits are reserved and MUST be initialized to zero by the
- sender and ignored by the receiver.</simpara>
- </listitem>
-
- <listitem>
- <simpara><command>IPv6 prefix</command> in prefix/length notation that specifies the IPv6 domain
- prefix for the S46 rule. The field is padded on the right with zero
- bits up to the nearest octet boundary when prefix6-len is not evenly
- divisible by 8.</simpara>
- </listitem>
-
- </itemizedlist>
- </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
- Container option and not permitted in the MAP-T and
- S46 Lightweight 4over6 Container options.
- <screen>
- {
- "space": "s46-cont-mape-options",
- "name": "s46-br",
- "data": "2001:db8:cafe::1",
- }
- </screen>
- Other possible "space" value is "s46-cont-lw-options".
- </para>
- </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
- container option and not permitted in the MAP-E and S46
- Lightweight 4over6 Container options.
- <screen>
- {
- "space": "s46-cont-mapt-options",
- "name": "s46-dmr",
- "data": "2001:db8:cafe::/64",
- }
- </screen>
- This option must not be included in other containers.
- </para>
- </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).
- The IPv6 prefix field is used by the CE to identify the
- correct prefix to use for the tunnel source.
- <screen>
- {
- "space": "s46-cont-lw",
- "name": "s46-v4v6bind",
- "data": "192.0.2.3, 2001:db8:1:cafe::/64"
- }
- </screen>
- This option must not be included in other containers.
- </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
- <screen>
- {
- "space": "s46-rule-options",
- "name": "s46-portparams",
- "data": "2, 3/4",
- }
- </screen>
- Other possible "space" value is "s46-v4v6bind" to include
- this option in the S46 IPv4/IPv6 Address Binding option.
- </para>
- <para>
- Note that the second value in the example above specifies the
- PSID and PSID length fields in the format of PSID/PSID length.
- This is equivalent to the values of PSID-len=4 and
- PSID=12288 conveyed in the S46 Port Parameters option.
- </para>
- </section>
-
- </section>
-
- <section xml:id="dhcp6-custom-options"><info><title>Custom DHCPv6 Options</title></info>
- <section id="dhcp6-custom-options">
++ <section xml:id="dhcp6-custom-options">
+ <title>Custom DHCPv6 Options</title>
<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
<command>"1"</command>. Future versions of Kea will accept all those values
for all boolean parameters.</para>
</note>
+
</section>
- <section xml:id="dhcp6-vendor-opts"><info><title>DHCPv6 Vendor-Specific Options</title></info>
- <section id="dhcp6-vendor-opts">
++ <section xml:id="dhcp6-vendor-opts">
+ <title>DHCPv6 Vendor-Specific Options</title>
<para>
Currently there are two option spaces defined for the DHCPv6
daemon: "dhcp6" (for top level DHCPv6 options) and "vendor-opts-space",
</para>
</section>
- <section xml:id="dhcp6-option-spaces"><info><title>Nested DHCPv6 Options (Custom Option Spaces)</title></info>
- <section id="dhcp6-option-spaces">
++ <section xml:id="dhcp6-option-spaces">
+ <title>Nested DHCPv6 Options (Custom Option Spaces)</title>
<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
</para>
</section>
- <section xml:id="dhcp6-option-data-defaults"><info><title>Unspecified Parameters for DHCPv6 Option Configuration</title></info>
- <section id="dhcp6-option-data-defaults">
++ <section xml:id="dhcp6-option-data-defaults">
+ <title>Unspecified Parameters for DHCPv6 Option Configuration</title>
<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>
- <section id="dhcp6-config-subnets">
++ <section xml:id="dhcp6-config-subnets">
+ <title>IPv6 Subnet Selection</title>
<para>
The DHCPv6 server may receive requests from local (connected to the
same subnet as the server) and remote (connecting via relays) clients.
</para>
</section>
- <section xml:id="dhcp6-rapid-commit"><info><title>Rapid Commit</title></info>
- <section id="dhcp6-rapid-commit">
++ <section xml:id="dhcp6-rapid-commit">
+ <title>Rapid Commit</title>
<para>The Rapid Commit option, described in
- <ulink url="http://tools.ietf.org/html/rfc3315">RFC 3315</ulink>, is supported
+ <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
all subnets. It can be enabled for a particular subnet using the
<command>rapid-commit</command> parameter as shown below:
</para>
</section>
- <section xml:id="dhcp6-relays"><info><title>DHCPv6 Relays</title></info>
- <section id="dhcp6-relays">
++ <section xml:id="dhcp6-relays">
+ <title>DHCPv6 Relays</title>
<para>
A DHCPv6 server with multiple subnets defined must select the
appropriate subnet when it receives a request from a client. For clients
</para>
</section>
- <section xml:id="dhcp6-rsoo"><info><title>Relay-Supplied Options</title></info>
- <section id="dhcp6-rsoo">
++ <section xml:id="dhcp6-rsoo">
+ <title>Relay-Supplied Options</title>
- <para><ulink url="http://tools.ietf.org/html/rfc6422">RFC 6422</ulink>
+ <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
insert options when relaying messages from the client to the server. The
it could also work for custom options, but due to the nature of the parser
code this may be unreliable and should be avoided.
</para>
+
</section>
- <section xml:id="dhcp6-client-classifier"><info><title>Client Classification in DHCPv6</title></info>
- <section id="dhcp6-client-classifier">
++ <section xml:id="dhcp6-client-classifier">
+ <title>Client Classification in DHCPv6</title>
+
<para>
The DHCPv6 server includes support for client classification. For a deeper
discussion of the classification process see <xref linkend="classify"/>.
</screen>
</para>
</section>
-
</section>
- <section xml:id="dhcp6-ddns-config"><info><title>DDNS for DHCPv6</title></info>
- <section id="dhcp6-ddns-config">
++ <section xml:id="dhcp6-ddns-config">
+ <title>DDNS for DHCPv6</title>
<para>
As mentioned earlier, kea-dhcp6 can be configured to generate requests to
the DHCP-DDNS server (referred to here as "D2") to update
</itemizedlist>
</para>
- <section xml:id="dhcpv6-d2-io-config"><info><title>DHCP-DDNS Server Connectivity</title></info>
+
- <section id="dhcpv6-d2-io-config">
++ <section xml:id="dhcpv6-d2-io-config">
+ <title>DHCP-DDNS Server Connectivity</title>
<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
</screen>
</para>
</section>
-
- <section xml:id="dhcpv6-d2-rules-config"><info><title>When Does kea-dhcp6 Generate a DDNS Request?</title></info>
- <section id="dhcpv6-d2-rules-config">
++ <section xml:id="dhcpv6-d2-rules-config">
+ <title>When Does kea-dhcp6 Generate a DDNS Request?</title>
<para>kea-dhcp6 follows the behavior prescribed for DHCP servers in
- <ulink url="http://tools.ietf.org/html/rfc4704">RFC 4704</ulink>.
+ <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
decision making of when and what to update and forwards that
information to D2 in the form of NCRs. Carrying out the actual
By default kea-dhcp6 will respect the FQDN N and S flags specified by the client
as shown in the following table:
</para>
- <table xml:id="dhcp6-fqdn-flag-table"><info><title>Default FQDN Flag Behavior</title></info>
-
- <table id="dhcp6-fqdn-flag-table">
++ <table xml:id="dhcp6-fqdn-flag-table">
+ <title>Default FQDN Flag Behavior</title>
- <tgroup cols='4' align='left'>
- <colspec colname='cflags'/>
- <colspec colname='meaning'/>
- <colspec colname='response'/>
- <colspec colname='sflags'/>
+ <tgroup cols="4" align="left">
+ <colspec colname="cflags"/>
+ <colspec colname="meaning"/>
+ <colspec colname="response"/>
+ <colspec colname="sflags"/>
<thead>
<row>
<entry>Client Flags:N-S</entry>
}
</screen>
</section>
-
- <section xml:id="dhcpv6-fqdn-name-generation"><info><title>kea-dhcp6 Name Generation for DDNS Update Requests</title></info>
- <section id="dhcpv6-fqdn-name-generation">
++ <section xml:id="dhcpv6-fqdn-name-generation">
+ <title>kea-dhcp6 Name Generation for DDNS Update Requests</title>
<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
</para>
</section>
- <section xml:id="dhcp6-dhcp4o6-config"><info><title>DHCPv4-over-DHCPv6: DHCPv6 Side</title></info>
- <section id="dhcp6-dhcp4o6-config">
++ <section xml:id="dhcp6-dhcp4o6-config">
+ <title>DHCPv4-over-DHCPv6: DHCPv6 Side</title>
<para>
The support of DHCPv4-over-DHCPv6 transport is described in
- <ulink url="http://tools.ietf.org/html/rfc7341">RFC 7341</ulink>
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7341">RFC 7341</link>
and is implemented using cooperating DHCPv4 and DHCPv6 servers.
This section is about the configuration of the DHCPv6 side
(the DHCPv4 side is described in <xref linkend="dhcp4-dhcp4o6-config"/>).
<!-- 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>
- <section id="host-reservation-v6">
++ <section xml:id="host-reservation-v6">
+ <title>Host Reservation in DHCPv6</title>
+
<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
+ address or/and prefix for exclusive use by a given client (host) ‐ returning
client will get the same address or/and prefix every time and other clients will
never get that address. Note that there may be cases when the
new reservation has been made for the client for the address or prefix being
could be used by someone else (i.e. if there is a reservation for it). That
additional check incurs additional overhead.</para>
- <section xml:id="reservation6-types"><info><title>Address/Prefix Reservation Types</title></info>
- <section id="reservation6-types">
++ <section xml:id="reservation6-types">
+ <title>Address/Prefix Reservation Types</title>
+
<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
possible.</para>
</section>
- <section xml:id="reservation6-conflict"><info><title>Conflicts in DHCPv6 Reservations</title></info>
- <section id="reservation6-conflict">
++ <section xml:id="reservation6-conflict">
+ <title>Conflicts in DHCPv6 Reservations</title>
<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
</para>
</section>
- <section xml:id="reservation6-hostname"><info><title>Reserving a Hostname</title></info>
- <section id="reservation6-hostname">
++ <section xml:id="reservation6-hostname">
+ <title>Reserving a Hostname</title>
<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
</para>
</section>
- <section xml:id="reservation6-options"><info><title>Including Specific DHCPv6 Options in Reservations</title></info>
- <section id="reservation6-options">
++ <section xml:id="reservation6-options">
+ <title>Including Specific DHCPv6 Options in Reservations</title>
<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
- (see <xref linkend="dhcp6-vendor-opts" />). The following
+ options. These can be standard options (see <xref linkend="dhcp6-std-options"/>), custom options (see <xref linkend="dhcp6-custom-options"/>) or vendor specific options
+ (see <xref linkend="dhcp6-vendor-opts"/>). The following
example demonstrates how standard options can be defined.</para>
<screen>
</section>
- <section xml:id="reservation6-client-classes"><info><title>Reserving Client Classes in DHCPv6</title></info>
- <section id="reservation6-client-classes">
++ <section xml:id="reservation6-client-classes">
+ <title>Reserving Client Classes in DHCPv6</title>
<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
with classification using expressions.</para>
</section>
- <section xml:id="reservations6-mysql-pgsql-cql"><info><title>Storing Host Reservations in MySQL, PostgreSQL or CQL (Cassandra)</title></info>
- <section id="reservations6-mysql-pgsql">
++ <section xml:id="reservations6-mysql-pgsql">
+ <title>Storing Host Reservations in MySQL or PostgreSQL</title>
+
<para>
- 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
- 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 or PostgreSQL. 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 <ulink
- url="http://kea.isc.org/wiki/HostReservationsHowTo" /> 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>
arbitrarily set to 4096 bytes.</simpara></note>
</section>
- <section xml:id="reservations6-cql"><info><title>Storing Host Reservations in CQL (Cassandra)</title></info>
- <section id="reservations6-cql">
++ <section xml:id="reservations6-cql">
+ <title>Storing Host Reservations in CQL (Cassandra)</title>
<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>
- <section id="reservations6-tuning">
++ <section xml:id="reservations6-tuning">
+ <title>Fine Tuning DHCPv6 Host Reservation</title>
+
<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
</section>
<!-- end of host reservations section -->
- <section xml:id="dhcp6-serverid"><info><title>Server Identifier in DHCPv6</title></info>
- <section id="dhcp6-serverid">
++ <section xml:id="dhcp6-serverid">
+ <title>Server Identifier in DHCPv6</title>
<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.
identifier is explicitly specified in the configuration.</para>
</section>
- <section xml:id="stateless-dhcp6"><info><title>Stateless DHCPv6 (Information-Request Message)</title></info>
- <section id="stateless-dhcp6">
++ <section xml:id="stateless-dhcp6">
+ <title>Stateless DHCPv6 (Information-Request Message)</title>
<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,
even if it is not used.</para>
</section>
- <section xml:id="dhcp6-rfc7550"><info><title>Support for RFC 7550</title></info>
- <section id="dhcp6-rfc7550">
++ <section xml:id="dhcp6-rfc7550">
+ <title>Support for RFC 7550</title>
- <para>The <ulink url="http://tools.ietf.org/html/rfc7550">RFC 7550</ulink>
+ <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
between the clients and servers.</para>
</para>
</section>
- <section xml:id="dhcp6-relay-override"><info><title>Using Specific Relay Agent for a Subnet</title></info>
- <section id="dhcp6-relay-override">
++ <section xml:id="dhcp6-relay-override">
+ <title>Using Specific Relay Agent for a Subnet</title>
<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
}
</screen>
</para>
+
+ <para>If "relay" is specified, the "ip-address" parameter within
+ it is mandatory.</para>
+
</section>
- <section xml:id="dhcp6-client-class-relay"><info><title>Segregating IPv6 Clients in a Cable Network</title></info>
- <section id="dhcp6-client-class-relay">
++ <section xml:id="dhcp6-client-class-relay">
+ <title>Segregating IPv6 Clients in a Cable Network</title>
<para>
In certain cases, it is useful to mix relay address information,
introduced in <xref linkend="dhcp6-relay-override"/> with client
</para>
</section>
- <section xml:id="mac-in-dhcpv6"><info><title>MAC/Hardware Addresses in DHCPv6</title></info>
- <section id="mac-in-dhcpv6">
++ <section xml:id="mac-in-dhcpv6">
+ <title>MAC/Hardware Addresses in DHCPv6</title>
<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
which is the default.</para>
</section>
- <section xml:id="dhcp6-decline"><info><title>Duplicate Addresses (DECLINE Support)</title></info>
- <section id="dhcp6-decline">
++ <section xml:id="dhcp6-decline">
+ <title>Duplicate Addresses (DECLINE Support)</title>
+
<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
the available pool.</para>
</section>
- <section xml:id="dhcp6-stats"><info><title>Statistics in the DHCPv6 Server</title></info>
- <section id="dhcp6-stats">
++ <section xml:id="dhcp6-stats">
+ <title>Statistics in the DHCPv6 Server</title>
<note>
<para>This section describes DHCPv6-specific statistics. For a general
- overview and usage of statistics, see <xref linkend="stats" />.</para>
+ overview and usage of statistics, see <xref linkend="stats"/>.</para>
</note>
<para>
The DHCPv6 server supports the following statistics:
</para>
- <table frame="all" xml:id="dhcp6-statistics"><info><title>DHCPv6 Statistics</title></info>
-
- <table frame="all" id="dhcp6-statistics">
++ <table frame="all" xml:id="dhcp6-statistics">
+ <title>DHCPv6 Statistics</title>
- <tgroup cols='3'>
- <colspec colname='statistic' align='center'/>
- <colspec colname='type' align='center'/>
- <colspec colname='description' align='left'/>
+ <tgroup cols="3">
+ <colspec colname="statistic" align="center"/>
+ <colspec colname="type" align="center"/>
+ <colspec colname="description" align="left"/>
<thead>
<row>
<entry>Statistic</entry>
</table>
</section>
- <section xml:id="dhcp6-ctrl-channel"><info><title>Management API for the DHCPv6 Server</title></info>
- <section id="dhcp6-ctrl-channel">
++ <section xml:id="dhcp6-ctrl-channel">
+ <title>Management API for the DHCPv6 Server</title>
<para>
The management API allows the issuing of specific
management commands, such as statistics retrieval, reconfiguration or shutdown.
</para>
</section>
- <section xml:id="dhcp6-std"><info><title>Supported DHCPv6 Standards</title></info>
- <section id="dhcp6-std">
++ <section xml:id="dhcp6-std">
+ <title>Supported DHCPv6 Standards</title>
<para>The following standards are currently
supported:</para>
<itemizedlist>
<listitem>
<simpara><emphasis>Issues and Recommendations with Multiple
Stateful DHCPv6 Options</emphasis>,
- <ulink url="http://tools.ietf.org/html/rfc7550">RFC
- 7550</ulink>: All recommendations related to the DHCPv6 server
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7550">RFC
+ 7550</link>: All recommendations related to the DHCPv6 server
operation are supported.</simpara>
</listitem>
- <listitem>
- <simpara><emphasis>DHCPv6 Options for Configuration of Softwire
- Address and Port-Mapped Clients</emphasis>,
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://tools.ietf.org/html/rfc7598">RFC
- 7598</link>: All options specified in this specification are
- supported by the DHCPv6 server.</simpara>
- </listitem>
</itemizedlist>
</section>
- <section xml:id="dhcp6-limit"><info><title>DHCPv6 Server Limitations</title></info>
- <section id="dhcp6-limit">
++ <section xml:id="dhcp6-limit">
+ <title>DHCPv6 Server Limitations</title>
<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
</section> -->
-- </chapter>
++ </chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
-
-<chapter id="faq">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="faq">
+ <title>Frequently Asked Questions</title>
<para>This chapter contains a number of frequently asked questions and
troubleshooting tips. It currently lacks content, but it is expected to grow
at least 2 years. If you have something short term, please consider putting
it in the known issues list. -->
- <section xml:id="faq-generic"><info><title>General Frequently Asked Questions</title></info>
- <section id="faq-generic">
++ <section xml:id="faq-generic">
+ <title>General Frequently Asked Questions</title>
+
- <section id="q1-generic">
++ <section xml:id="q1-generic">
+ <title>Where did the Kea name came from?</title>
- <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 <ulink url="https://lists.isc.org/pipermail/kea-users/2014-October/000032.html" />
+ 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>
- <section id="q2-generic">
++ <section xml:id="q2-generic">
+ <title>Feature X is not supported yet. When/if will it be available?</title>
+
<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 id="faq-dhcp4">
++ <section xml:id="faq-dhcp4">
+ <title>Frequently Asked Questions about DHCPv4</title>
+
+ <section iq="q1-dhcp4">
+ <title>I set up a firewall, but the Kea server still receives the traffic. Why?</title>
- <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 id="faq-dhcp6">
++ <section xml:id="faq-dhcp6">
+ <title>Frequently Asked Questions about DHCPv6</title>
+
+ <section iq="q1-dhcp6">
+ <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>
- <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>
+
- </chapter>
++ </chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
--
- <section xml:id="hooks-libraries-introduction"><info><title>Introduction</title></info>
- <chapter id="hooks-libraries">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="hooks-libraries">
+ <title>Hooks Libraries</title>
- <section id="hooks-libraries-introduction">
++ <section xml:id="hooks-libraries-introduction">
+ <title>Introduction</title>
<para>
Although Kea offers a lot of flexibility, there may be cases where
- its behavior needs customisation. To accommodate this possibility,
+ its behavior needs customization. To accommodate this possibility,
Kea includes the idea of "Hooks". This feature lets Kea load one
or more dynamically-linked libraries (known as "hooks libraries")
and, at various points in its processing ("hook points"), call
<para>
The next section describes how to configure hooks libraries. If you
are interested in writing your own hooks library, information can be
- found in the <ulink url="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/">Kea
- Developer's Guide</ulink>.
+ found in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/">Kea
+ Developer's Guide</link>.
</para>
</section> <!-- end Introduction -->
-
- <section><info><title>Configuring Hooks Libraries</title></info>
+ <section>
+ <title>Configuring Hooks Libraries</title>
<para>
The hooks libraries for a given process are configured using the
<command>hooks-libraries</command> keyword in the
<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>
-
- <table frame="all" id="hook-libs">
++ <table frame="all" xml:id="hook-libs">
+ <title>List of available hooks libraries</title>
- <tgroup cols='3'>
- <colspec colname='name' />
- <colspec colname='avail' />
- <colspec colname='description' />
+ <tgroup cols="3">
+ <colspec colname="name"/>
+ <colspec colname="avail"/>
+ <colspec colname="description"/>
<thead>
<row>
<entry>Name</entry>
</para>
<para>As with any other hooks libraries provided by ISC, internals of the
- user_chk code are well documented. You can take a look at the <ulink
- url="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/d8/db2/libdhcp_user_chk.html">Kea Developer's Guide section dedicated to the user_chk library</ulink>
+ user_chk code are well documented. You can take a look at the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/d8/db2/libdhcp_user_chk.html">Kea Developer's Guide section dedicated to the user_chk library</link>
that discusses how the code works internally. That, together with
- our general entries in <ulink
- url="https://jenkins.isc.org/job/Fedora20_32_doxygen_doc/doxygen/">Hooks
- Framework section</ulink> should give you some pointers how to extend
+ 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>
+ </section>
+ <section>
+ <title>legal_log: Forensic Logging Hooks</title>
<para>
This section describes the forensic log hooks library. This library
provides hooks that record a detailed log of lease assignments
</screen>
</para>
</section>
-
- <section xml:id="forensic-log-configuration"><info><title>Configuring the Forensic Log Hooks</title></info>
- <section id="forensic-log-configuration">
++ <section xml:id="forensic-log-configuration">
+ <title>Configuring the Forensic Log Hooks</title>
<para>
To use this functionality the hook library must be included in the
configuration of the desired DHCP server modules. The legal_log
</itemizedlist>
</para>
</section>
- <section id="flex-id">
+ </section>
+
- initially used for client classification only. See <xref
- linkend="classification-using-expressions" /> for detailed description
++ <section xml:id="flex-id">
+ <title>flex_id: Flexible Identifiers for Host Reservations</title>
+ <para>
+ This section describes a hook application dedicated to generate
+ flexible identifiers for host reservation. Kea software provides a way
+ to handle host reservations that include addresses, prefixes, options,
+ client classes and other features. The reservation can be based on
+ hardware address, DUID, circuit-id or client-id in DHCPv4 and using
+ hardware address or DUID in DHCPv6. However, there are sometimes
+ scenario where the reservation is more complex, e.g. uses other
+ options that mentioned above, uses part of specific options or perhaps
+ even a combination of several options and fields to uniquely identify
+ a client. Those scenarios are addressed by the Flexible Identifiers
+ hook application.</para>
+
+ <para>Currently this library is only available to ISC customers with a
+ support contract.</para>
+
+ <para>The library allows for defining an expression, using notation
- <section id="host-cmds">
++ initially used for client classification only. See <xref linkend="classification-using-expressions"/> for detailed description
+ of the syntax available. One notable difference is that for client
+ classification the expression currently has to evaluate to either true
+ or false, while the flexible identifier expression is expected to
+ evaluate to a string that will be used as identifier. It is a valid case
+ for the expression to evaluate to empty string (e.g. in cases where a
+ client does not sent specific options). This expression is then
+ evaluated for each incoming packet. This evaluation generates an
+ identifier that is used to identify the client. In particular, there may
+ be host reservations that are tied to specific values of the flexible
+ identifier.</para>
+
+ <para>
+ The library can be loaded in similar way as other hook libraries. It
+ takes one mandatory parameter identifier-expression:
+ <screen>
+ "Dhcp6": { <userinput>
+ "hooks-libraries": [
+ {
+ "library": "/path/libdhcp_flex_id.so",
+ "parameters": {
+ "identifier-expression": "<userinput>expression</userinput>"
+ }
+ },
+ ...
+ ] </userinput>
+ }
+ </screen>
+ </para>
+
+ <para>
+ The flexible identifier library supports both DHCPv4 and DHCPv6.
+ </para>
+
+ <para>
+ EXAMPLE: Let's consider a case of an IPv6 network that has an
+ independent interface for each of the connected customers. Customers
+ are able to plug in whatever device they want, so any type of
+ identifier (e.g. a client-id) is unreliable. Therefore the operator
+ may decide to use an option inserted by a relay agent to differentiate
+ between clients. In this particular deployment, the operator verified
+ that the interface-id is unique for each customer facing
+ interface. Therefore it is suitable for usage as reservation. However,
+ only the first 6 bytes of the interface-id are interesting, because
+ remaining bytes are either randomly changed or not unique between
+ devices. Therefore the customer decided to use first 6 bytes of the
+ interface-id option inserted by the relay agent. After adding "flex-id"
+ host-reservation-identifiers goal can be achieved by using the
+ following configuration:
+ <screen>
+ "Dhcp6": {
+ "subnet6": [{ ..., // subnet definition starts here
+ "reservations": [
+ <userinput>"flex-id": "'port1234'"</userinput>, // value of the first 8 bytes of the interface-id
+ "ip-addresses": [ "2001:db8::1" ]
+ ],
+ }], // end of subnet definitions
+ "host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers
+ "hooks-libraries": [
+ {
+ "library": "/path/libdhcp_flex_id.so",
+ "parameters": {
+ "identifier-expression": "<userinput>substring(relay6[0].option[18].hex,0,8)</userinput>"
+ }
+ },
+ ...
+ ]
+ }
+ </screen>
+ </para>
+
+ <para>
+ NOTE: Care should be taken when adjusting the expression. If the
+ expression changes, then all the flex-id values may change, possibly
+ rendering all reservations based on flex-id unusable until they're
+ manually updated. Therefore it is strongly recommended to start with
+ the expression and a handful reservations, adjust the expression as
+ needed and only after it was confirmed the expression does exactly
+ what is expected out of it go forward with host reservations on any
+ broader scale.
+ </para>
+
+ <para>
+ flex-id values in host reservations can be specified in two
+ ways. First, they can be expressed as hex string, e.g. bar string
+ can be represented as 626174. Alternatively, it can be expressed
+ as quoted value (using double and single quotes), e.g. "'bar'".
+ The former is more convenient for printable characters, while hex
+ string values are more convenient for non-printable characters.
+ </para>
+ <screen>
+ "Dhcp6": {
+ "subnet6": [{ ..., // subnet definition starts here
+ "reservations": [
+ <userinput>"flex-id": "01:02:03:04:05:06"</userinput>, // value of the first 8 bytes of the interface-id
+ "ip-addresses": [ "2001:db8::1" ]
+ ],
+ }], // end of subnet definitions
+ "host-reservation-identifiers": ["duid", "flex-id"], // add "flex-id" to reservation identifiers
+ "hooks-libraries": [
+ {
+ "library": "/path/libdhcp_flex_id.so",
+ "parameters": {
+ "identifier-expression": "<userinput>vendor[4491].option[1026].hex</userinput>"
+ }
+ },
+ ...
+ ]
+ }
+ </screen>
+ </section>
+
- <xref linkend="hosts-database-configuration4"/> and <xref
- linkend="hosts-database-configuration6"/>) and it must not operate in
++ <section xml:id="host-cmds">
+ <title>host_cmds: Host Commands</title>
+ <para>
+ This section describes a hook application that offers a number of new
+ commands used to query and manipulate host reservations. Kea provides
+ a way to store host reservations in a database. In many larger
+ deployments it is useful to be able to manage that information while
+ the server is running. This library provides management commands for
+ adding, querying and deleting host reservations in a safe way without
+ restarting the server. In particular, it validates the parameters, so
+ an attempt to insert incorrect data e.g. add a host with conflicting
+ identifier in the same subnet will be rejected. Those commands are
+ exposed via command channel (JSON over unix sockets) and Control Agent
+ (JSON over RESTful interface). Additional commands and capabilities
+ related to host reservations will be added in the future.
+ </para>
+
+ <para>Currently this library is only available to ISC customers with a
+ support contract.</para>
+
+ <para>
+ Currently three commands are supported: reservation-add (which adds
+ new host reservation), reservation-get (which returns existing
+ reservation if specified criteria are matched) and reservation-del
+ (which attempts to delete a reservation matching specified
+ criteria). To use commands that change the reservation information
+ (currently these are reservation-add and reservation-del, but this
+ rule applies to other commands that may be implemented in the future),
+ hosts database must be specified (see hosts-database description in
-<ulink url="http://kea.isc.org/wiki/ControlAPIRequirements">Control API
-Requirements </ulink> document.</para>
++ <xref linkend="hosts-database-configuration4"/> and <xref linkend="hosts-database-configuration6"/>) and it must not operate in
+ read-only mode. If the hosts-database is not specified or is running
+ in read-only mode, the host_cmds library will load, but any attempts
+ to use reservation-add or reservation-del will fail.
+ </para>
+
+ <para>
+ Additional host reservation commands are planned in the future. For
+ a description of envisaged commands, see
- IPv4 reservations, see <xref linkend="host-reservation-v4"/> and <xref
- linkend="host-reservation-v6"/>. There is one notable addition. A
++<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/ControlAPIRequirements">Control API
++Requirements </link> document.</para>
+
+ <para>
+ All commands are using JSON syntax. They can be issued either using
+ control channel (see <xref linkend="ctrl-channel"/>) or via Control
+ Agent (see <xref linkend="kea-ctrl-agent"/>).
+ </para>
+
+ <para>
+ The library can be loaded in similar way as other hook libraries. It
+ does not take any parameters. It supports both DHCPv4 and DHCPv6
+ servers.
+ <screen>
+ "Dhcp6": { <userinput>
+ "hooks-libraries": [
+ {
+ "library": "/path/libdhcp_host_cmds.so"
+ }
+ ...
+ ] </userinput>
+ }
+ </screen>
+ </para>
+
+ <section>
+ <title>reservation-add command</title>
+ <para>
+ <command>reservation-add</command> allows insertion of a new host. It
+ takes a set of arguments that vary depending on the nature of the host
+ reservation. Any parameters allowed in the configuration file that
+ pertain to host reservation are permitted here. For details regarding
- <section id="lease-cmds">
++ IPv4 reservations, see <xref linkend="host-reservation-v4"/> and <xref linkend="host-reservation-v6"/>. There is one notable addition. A
+ <command>subnet-id</command> must be specified. This parameter is
+ mandatory, because reservations specified in the configuration file
+ are always defined within a subnet, so the subnet they belong to is
+ clear. This is not the case with reservation-add, therefore the
+ subnet-id must be specified explicitly. An example command can be as
+ simple as:
+ <screen>{
+ "command": "reservation-add",
+ "arguments": {
+ <userinput>"reservation": {
+ "subnet-id": 1,
+ "hw-address": "1a:1b:1c:1d:1e:1f",
+ "ip-address": "192.0.2.202"
+ }</userinput>
+ }
+ }</screen> but can also take many more parameters, for example:
+
+ <screen>
+ {
+ "command": "reservation-add",
+ "arguments": {
+ <userinput>"reservation":
+ {
+ "subnet-id":1,
+ "client-id": "01:0a:0b:0c:0d:0e:0f",
+ "ip-address": "192.0.2.205",
+ "next-server": "192.0.2.1",
+ "server-hostname": "hal9000",
+ "boot-file-name": "/dev/null",
+ "option-data": [
+ {
+ "name": "domain-name-servers",
+ "data": "10.1.1.202,10.1.1.203"
+ }
+ ],
+ "client-classes": [ "special_snowflake", "office" ]
+ }</userinput>
+ }
+ }</screen>
+
+ Here is an example of complex IPv6 reservation:
+ <screen>
+ {
+ "command": "reservation-add",
+ "arguments": {
+ <userinput>"reservation":
+ {
+ "subnet-id":1,
+ "duid": "01:02:03:04:05:06:07:08:09:0A",
+ "ip-addresses": [ "2001:db8:1:cafe::1" ],
+ "prefixes": [ "2001:db8:2:abcd::/64" ],
+ "hostname": "foo.example.com",
+ "option-data": [
+ {
+ "name": "vendor-opts",
+ "data": "4491"
+ },
+ {
+ "name": "tftp-servers",
+ "space": "vendor-4491",
+ "data": "3000:1::234"
+ }
+ ]
+ }</userinput>
+ }
+ }</screen>
+ </para>
+
+ <para>
+ The command returns a status that indicates either a success (result
+ 0) or a failure (result 1). Failed command always includes text
+ parameter that explains the cause of failure. Example results:
+ <screen>{ "result": 0, "text": "Host added." }</screen> Example failure:
+ <screen>{ "result": 1, "text": "Mandatory 'subnet-id' parameter missing." }</screen>
+ </para>
+
+ <para>
+ As <command>reservation-add</command> is expected to store the host,
+ hosts-database parameter must be specified in your configuration and
+ the database must not run in read-only mode. In the future versions
+ it will be possible to modify the reservations read from a
+ configuration file. Please contact ISC if you are interested in this
+ functionality.
+ </para>
+ </section>
+
+ <section>
+ <title>reservation-get command</title>
+ <para><command>reservation-get</command> can be used to query the host
+ database and retrieve existing reservations. There are two types of
+ parameters this command supports: (subnet-id, address) or (subnet-id,
+ identifier-type, identifier). The first type of query is used when the
+ address (either IPv4 or IPv6) is known, but the details of the
+ reservation aren't. One common use case of this type of query is to
+ find out whether a given address is reserved or not. The second query
+ uses identifiers. For maximum flexibility, Kea stores the host
+ identifying information as a pair of values: type and the actual
+ identifier. Currently supported identifiers are "hw-address", "duid",
+ "circuit-id", "client-id" and "flex-id", but additional types may be
+ added in the future. If any new identifier types are defined in the
+ future, reservation-get command will support them
+ automatically.</para>
+
+ <para>
+ An example command for getting a host reservation by (subnet-id,
+ address) pair looks as follows:
+ <screen>
+ {
+ "command": "reservation-get",
+ "arguments": {
+ "subnet-id": 1,
+ "ip-address": "192.0.2.202"
+ }
+ }</screen>
+
+ An example query by (subnet-id, identifier-type, identifier) looks as follows:
+ <screen>
+ {
+ "command": "reservation-get",
+ "arguments":
+ "subnet-id": 4,
+ "identifier-type": "hw-address",
+ "identifier": "01:02:03:04:05:06"
+ }
+ }</screen>
+
+ </para>
+ <para><command>reservation-get</command> typically returns result 0
+ when the query was conducted properly. In particular, 0 is returned
+ when the host was not found. If the query was successful a number
+ of host parameters will be returned. An example of a query that
+ did not find the host looks as follows:
+ <screen>{ "result": 0, "text": "Host not found." }</screen>
+
+ An example result returned when the host was found:
+ <screen>{
+ "arguments": {
+ "boot-file-name": "bootfile.efi",
+ "client-classes": [
+
+ ],
+ "hostname": "somehost.example.org",
+ "hw-address": "01:02:03:04:05:06",
+ "ip-address": "192.0.2.100",
+ "next-server": "192.0.0.2",
+ "option-data": [
+
+ ],
+ "server-hostname": "server-hostname.example.org"
+ },
+ "result": 0,
+ "text": "Host found."
+ }</screen>
+
+ An example result returned when the query was malformed:<screen>
+ { "result": 1, "text": "No 'ip-address' provided and 'identifier-type'
+ is either missing or not a string." }</screen>
+ </para>
+
+ </section>
+
+ <section>
+ <title>reservation-del command</title>
+ <para><command>reservation-del</command> can be used to delete a
+ reservation from the host database. There are two types of parameters
+ this command supports: (subnet-id, address) or (subnet-id,
+ identifier-type, identifier). The first type of query is used when the
+ address (either IPv4 or IPv6) is known, but the details of the
+ reservation aren't. One common use case of this type of query is to
+ remove a reservation (e.g. you want a specific address to no longer be
+ reserved). The second query uses identifiers. For maximum flexibility,
+ Kea stores the host identifying information as a pair of values: type
+ and the actual identifier. Currently supported identifiers are
+ "hw-address", "duid", "circuit-id", "client-id" and "flex-id", but
+ additional types may be added in the future. If any new identifier
+ types are defined in the future, reservation-get command will support
+ them automatically.</para>
+
+ <para>
+ An example command for deleting a host reservation by (subnet-id,
+ address) pair looks as follows:
+ <screen>
+ {
+ "command": "reservation-del",
+ "arguments": {
+ "subnet-id": 1,
+ "ip-address": "192.0.2.202"
+ }
+ }</screen>
+
+ An example deletion by (subnet-id, identifier-type, identifier) looks as follows:
+ <screen>
+ {
+ "command": "reservation-del",
+ "arguments":
+ "subnet-id": 4,
+ "identifier-type": "hw-address",
+ "identifier": "01:02:03:04:05:06"
+ }
+ }</screen>
+ </para>
+ <para>
+ <command>reservation-del</command> returns result 0 when the host
+ deletion was successful or 1 if it was not. A descriptive text is
+ provided in case of error. Example results look as follows:
+ <screen>
+ {
+ "result": 1,
+ "text": "Host not deleted (not found)."
+ }</screen>
+
+ <screen>
+ {
+ "result": 0,
+ "text": "Host deleted."
+ }</screen>
+
+ <screen>
+ {
+ "result": 1,
+ "text": "Unable to delete a host because there is no hosts-database
+ configured."
+ }</screen>
+ </para>
+ </section>
+ </section>
+
+ <!-- ================================================================= -->
+ <!-- === lease_cmds ================================================== -->
+ <!-- ================================================================= -->
+
-specified: type (set to value of "IA_PD") and a prefix
++ <section xml:id="lease-cmds">
+ <title>lease_cmds: Lease Commands</title>
+ <para>
+ This section describes the hook library that offers a number of new
+ commands used to manage leases. Kea provides a way to store lease
+ information in several backends (memfile, MySQL, PostgreSQL and
+ Cassandra). This library provides a unified interface that can
+ manipulate leases in an unified, safe way. In particular, it allows
+ things previously impossible: manipulate leases in memfile while Kea
+ is running, sanity check changes, check lease existence and remove all
+ leases belonging to specific subnet. It can also catch more obscure
+ errors, like adding a lease with subnet-id that does not exist in the
+ configuration or configuring a lease to use an address that is outside
+ of the subnet to which it is supposed to belong.
+ </para>
+
+ <para>There are many use cases when an administrative command may be
+ useful: during migration between servers (possibly even between
+ different vendors), when a certain network is being retired, when a
+ device has been disconnected and the sysadmin knows for sure that it
+ will not be coming back. The "get" queries may be useful for automating
+ certain management and monitoring tasks. They can also act as
+ preparatory steps for lease updates and removals.</para>
+
+ <para>
+ This library provides the following commands:
+ <itemizedlist>
+ <listitem>
+ <para><command>lease4-add</command> - adds new IPv4 lease;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease6-add</command> - adds new IPv6 lease;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease4-get</command> - checks if an IPv4 lease with
+ the specified parameters exists and returns it if it does;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease6-get</command> - checks if an IPv6 lease with
+ the specified parameters exists and returns it if it does;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease4-del</command> - attempts to delete an IPv4
+ lease with the specified parameters;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease6-del</command> - attempts to delete an IPv6
+ lease with the specified parameters;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease4-update</command> - updates an IPv4 lease;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease6-update</command> - updates an IPv6 lease;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease4-wipe</command> - removes all leases from a
+ specific IPv4 subnet;</para>
+ </listitem>
+ <listitem>
+ <para><command>lease6-wipe</command> - removes all leases from a
+ specific IPv6 subnet;</para>
+ </listitem>
+ </itemizedlist>
+
+ </para>
+
+ <para>Lease commands library is part of the open source code and is
+ available to every Kea user.</para>
+
+ <para>
+ All commands are using JSON syntax. They can be issued either using
+ control channel (see <xref linkend="ctrl-channel"/>) or via Control
+ Agent (see <xref linkend="kea-ctrl-agent"/>).
+ </para>
+
+ <para>
+ The library can be loaded in the same way as other hook libraries. It
+ does not take any parameters. It supports both DHCPv4 and DHCPv6
+ servers.
+ <screen>
+ "Dhcp6": { <userinput>
+ "hooks-libraries": [
+ {
+ "library": "/path/libdhcp_lease_cmds.so"
+ }
+ ...
+ ] </userinput>
+ }
+ </screen>
+ </para>
+
+ <section>
+ <title>lease4-add, lease6-add commands</title>
+ <para>
+ <command>lease4-add</command> and <command>lease6-add</command>
+ commands allow creation of a new lease. Typically Kea creates a lease
+ on its own, when it first sees a new device. However, sometimes it may
+ be convenient to create the lease administratively. The
+ <command>lease4-add</command> command requires at least three
+ parameters: an IPv4 address, a subnet-id and an identifier: hardware
+ (MAC) address. The simplest successful call might look as follows:
+ <screen>
+ {
+ "command": "lease4-add",
+ "arguments": {
+ "subnet-id": 44,
+ "ip-address": "192.0.2.202",
+ "hw-address": "1a:1b:1c:1d:1e:1f"
+ }
+ }
+ </screen>
+ </para>
+
+ <para><command>lease6-add</command> command requires four
+ paramaters: an IPv6 address, a subnet-id, and IAID value
+ (identity association identifier, a value sent by clients) and
+ a DUID:
+ <screen>
+ {
+ "command": "lease6-add",
+ "arguments": {
+ "subnet-id": 66,
+ "ip-address": "2001:db8::3",
+ "duid": "1a:1b:1c:1d:1e:1f:20:21:22:23:24",
+ "iaid": 1234
+ }
+ }</screen>
+
+ <command>lease6-add</command> can be also used to add leases for IPv6
+ prefixes. In this case there are two parameters that must be
- <section id="subnet-cmds">
++specified: type (set to value of "IA_PD") and a prefix
+ length. The actual prefix is set using ip-address field. For example,
+ to configure a lease for prefix 2001:db8:abcd::/48, the following
+ command can be used:
+
+ <screen>
+ {
+ "command": "lease6-add",
+ "arguments": {
+ "subnet-id": 66,
+ "type": "IA_PD",
+ "ip-address": "2001:db8:abcd::",
+ "prefix-len": 48,
+ "duid": "1a:1b:1c:1d:1e:1f:20:21:22:23:24",
+ "iaid": 1234
+ }
+ }</screen>
+
+ The commands can take a number of additional optional parameters:
+ <itemizedlist>
+ <listitem>
+ <para><command>valid-lft</command> - specifies the lifetime of the
+ lease, expressed in seconds. If not specified, the value
+ configured in the subnet related to specified subnet-id is
+ used.</para>
+ </listitem>
+ <listitem>
+ <para><command>expire</command> - timestamp of the lease
+ expiration time, expressed in unix format (seconds since 1 Jan
+ 1970). If not specified, the default value is now + valid
+ lifetime.</para>
+ </listitem>
+ <listitem>
+ <para><command>fqdn-fwd</command> - specifies whether the lease
+ should be marked as if forward DNS update was conducted. Note this
+ only affects the lease parameter and the actual DNS update will
+ not be conducted at the lease insertion time. If configured, a DNS
+ update to remove the A or AAAA records will be conducted when the
+ lease is removed due to expiration or being released by a
+ client. If not specifed, the default value is false. Hostname
+ parameter must be specified in fqdn-fwd is set to true.</para>
+ </listitem>
+ <listitem>
+ <para><command>fqdn-rev</command> - specifies whether the lease
+ should be marked as if reverse DNS update was conducted. Note this
+ only affects the lease parameter and the actual DNS update will
+ not be conducted at the lease insertion time. If configured, a DNS
+ update to remove the PTR record will be conducted when the lease
+ is removed due to expiration or being released by a client. If not
+ specifed, the default value is false. Hostname parameter must be
+ specified in fqdn-fwd is set to true.</para>
+ </listitem>
+ <listitem>
+ <para><command>hostname</command> - specifies the hostname to be
+ associated with this lease. Its value must be non-empty if either
+ fqdn-fwd or fwdn-rev are set to true. If not specified, the
+ default value is an empty string.</para>
+ </listitem>
+ <listitem>
+ <para><command>hw-address</command> - hardware (MAC) address can
+ be optionally specified for IPv6 lease. It is mandatory parameter
+ for IPv4 lease.</para>
+ </listitem>
+ <listitem>
+ <para><command>client-id</command> - client identifier is an
+ optional parameter that can be specified for IPv4 lease.</para>
+ </listitem>
+ <listitem>
+ <para><command>preferred-lft</command> - Preferred lifetime is an
+ optional parameter for IPv6 leases. If not specified, the value
+ configured for the subnet corresponding to the specified subnet-id
+ is used. This parameter is not used in IPv4.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Here's an example of more complex lease addition:
+
+ <screen>
+ {
+ "command": "lease6-add",
+ "arguments": {
+ "subnet-id": 66,
+ "ip-address": "2001:db8::3",
+ "duid": "01:02:03:04:05:06:07:08",
+ "iaid": 1234,
+ "hw-address": "1a:1b:1c:1d:1e:1f",
+ "preferred-lft": 500,
+ "valid-lft": 1000,
+ "expire": 12345678,
+ "fqdn-fwd": true,
+ "fqdn-rev": true,
+ "hostname": "urania.example.org"
+ }
+ }
+ </screen>
+ </para>
+
+ <para>
+ The command returns a status that indicates either a success (result
+ 0) or a failure (result 1). Failed command always includes text
+ parameter that explains the cause of failure. Example results:
+ <screen>{ "result": 0, "text": "Lease added." }</screen> Example failure:
+ <screen>{ "result": 1, "text": "missing parameter 'ip-address' (<string>:3:19)" }</screen>
+ </para>
+
+
+ <section>
+ <title>lease4-get, lease6-get commands</title>
+ <para><command>lease4-get</command> or <command>lease6-get</command>
+ can be used to query the lease database and retrieve existing
+ leases. There are two types of parameters the
+ <command>lease4-get</command> supports: (address) or (subnet-id,
+ identifier-type, identifier). There are two types for
+ <command>lease6-get</command>: (address,type) or (subnet-id,
+ identifier-type, identifier, IAID, type). The first type of query is
+ used when the address (either IPv4 or IPv6) is known, but the details
+ of the lease aren't. One common use case of this type of query is to
+ find out whether a given address is being used or not. The second
+ query uses identifiers. For maximum flexibility, Kea stores the host
+ identifying information as a pair of values: type and the actual
+ identifier. Currently supported identifiers are "hw-address", "duid",
+ "circuit-id", "client-id" and "flex-id", but additional types may be
+ added in the future. If any new identifier types are defined in the
+ future, reservation-get command will support them
+ automatically.</para>
+
+ <para>
+ An example <command>lease4-get</command> command for getting a lease
+ by an IPv4 address looks as follows:
+ <screen>
+ {
+ "command": "lease4-get",
+ "arguments": {
+ "ip-address": "192.0.2.1"
+ }
+ }
+ </screen>
+ </para>
+
+ <para>An example of the <command>lease6-get</command> query
+ looks as follows:
+ <screen>
+ {
+ "command": "lease6-get",
+ "arguments": {
+ "ip-address": "2001:db8:1234:ab::",
+ "type": "IA_PD"
+ }
+ }</screen>
+ </para>
+
+ <para>An example query by (subnet-id, identifier-type,
+ identifier) for IPv4 lease looks as follows:
+ <screen>
+ {
+ "command": "lease4-get",
+ "arguments": {
+ "identifier-type": "hw-address",
+ "identifier": "08:08:08:08:08:08",
+ "subnet-id": 44
+ }
+ }</screen>
+
+ </para>
+
+ <para>An example query by (subnet-id, identifier-type,
+ identifier, iaid, type) for IPv6 lease looks as follows:
+ <screen>
+ {
+ "command": "lease4-get",
+ "arguments": {
+ "identifier-type": "duid",
+ "identifier": "08:08:08:08:08:08",
+ "iaid": 1234567,
+ "type": "IA_NA",
+ "subnet-id": 44
+ }
+ }</screen>
+ The type is an optional parameter. Supported values are: IA_NA
+ (non-temporary address) and IA_PD (IPv6 prefix) are supported.
+ If not specified, IA_NA is assumed.
+ </para>
+
+ <para><command>leaseX-get</command> returns a result that indicates a
+ result of the operation and lease details, if found. It has one of the
+ following values: 0 (success), 1 (error) or 2 (empty). The empty
+ result means that a query has been completed properly, but the object
+ (a lease in this case) has not been found. The lease parameters, if
+ found, are returned as arguments.
+ </para>
+
+ <para>
+ An example result returned when the host was found:
+ <screen>{
+ "arguments": {
+ "client-id": "42:42:42:42:42:42:42:42",
+ "cltt": 12345678,
+ "fqdn-fwd": false,
+ "fqdn-rev": true,
+ "hostname": "myhost.example.com.",
+ "hw-address": "08:08:08:08:08:08",
+ "ip-address": "192.0.2.1",
+ "state": 0,
+ "subnet-id": 44,
+ "valid-lft": 3600
+ },
+ "result": 0,
+ "text": "IPv4 lease found."
+ }</screen>
+ </para>
+
+ </section>
+
+ <section>
+ <title>lease4-del, lease6-del commands</title>
+ <para><command>leaseX-del</command> can be used to delete a lease from
+ the lease database. There are two types of parameters this command
+ supports, similar to leaseX-get commands: (address) for both v4 and
+ v6, (subnet-id, identifier-type, identifier) for v4 and (subnet-id,
+ identifier-type, identifier, type, IAID) for v6. The first type of
+ query is used when the address (either IPv4 or IPv6) is known, but the
+ details of the lease are not. One common use case of this type of query
+ is to remove a lease (e.g. you want a specific address to no longer be
+ used, no matter who may use it). The second query uses
+ identifiers. For maximum flexibility, this interface uses identifiers
+ as a pair of values: type and the actual identifier. Currently
+ supported identifiers are "hw-address" and "duid", but additional
+ types may be added in the future. </para>
+
+ <para>
+ An example command for deleting a host reservation by address looks
+ as follows:
+ <screen>
+ {
+ "command": "lease4-del",
+ "arguments": {
+ "ip-address": "192.0.2.202"
+ }
+ }</screen>
+
+ An example IPv4 lease deletion by (subnet-id, identifier-type, identifier) looks
+ as follows:
+
+ <screen>{
+ "command": "lease4-del",
+ "arguments": {
+ "identifier": "08:08:08:08:08:08",
+ "identifier-type": "hw-address",
+ "subnet-id": 44
+ }
+ }</screen>
+ </para>
+
+ <para><command>leaseX-get</command> returns a result that
+ indicates a outcome of the operation. It has one of the
+ following values: 0 (success), 1 (error) or 2 (empty). The
+ empty result means that a query has been completed properly,
+ but the object (a lease in this case) has not been found.
+ </para>
+ </section>
+
+ <section>
+ <title>lease4-update, lease6-update commands</title>
+ <para><command>lease4-update</command> and
+ <command>lease6-update</command> commands can be used to update
+ existing leases. Since all lease database backends are indexed by IP
+ addresses, it is not possible to update an address. All other fields
+ may be updated. If an address needs to be changed, please use
+ <command>leaseX-del</command> followed by
+ <command>leaseX-add</command> commands.</para>
+
+ <para>To use <command>leaseX-update</command> the lease must
+ be present in the lease database. If the lease is not there,
+ an error will be returned. Please use
+ <command>leaseX-add</command> to add new leases. You may
+ check if a lease is present using
+ <command>leaseX-get</command>, if needed.</para>
+
+ <para>
+ An example command updating IPv6 lease looks as follows:
+ <screen>{
+ "command": "lease4-update",
+ "arguments": {
+ "ip-address": "192.0.2.1",
+ "hostname": "newhostname.example.org",
+ "hw-address": "1a:1b:1c:1d:1e:1f",
+ "subnet-id": 44
+ }
+ }</screen>
+ </para>
+
+ <para>
+ An example command updating IPv6 lease looks as follows:
+ <screen>{
+ "command": "lease6-update",
+ "arguments": {
+ "ip-address": "2001:db8::1",
+ "duid": "88:88:88:88:88:88:88:88",
+ "iaid": 7654321,
+ "hostname": "newhostname.example.org",
+ "subnet-id": 66
+ }
+ }</screen>
+ </para>
+ </section>
+
+ <section>
+ <title>lease4-wipe, lease6-wipe commands</title>
+ <para><command>lease4-wipe</command> and
+ <command>lease6-wipe</command> are designed to remove all
+ leases associated with a given subnet. This administrative
+ task is expected to be used when existing subnet is being
+ retired. Note that the leases are not properly expired,
+ there are no DNS updates conducted, no log messages and
+ hooks are not called for leases being removed.</para>
+
+ <para>An example of <command>lease4-wipe</command> looks as follows:
+ <screen>{
+ "command": "lease4-wipe",
+ "arguments": {
+ "subnet-id": 44
+ }
+ }</screen>
+ </para>
+
+ <para>An example of <command>lease6-wipe</command> looks as follows:
+ <screen>{
+ "command": "lease6-wipe",
+ "arguments": {
+ "subnet-id": 66
+ }
+ }</screen>
+ </para>
+
+ <para>The commands return a textual description of the
+ number of leases removed and 0 (success) status code if any
+ leases were removed and 2 (empty) if there were no
+ leases. Status code 1 (error) may be returned in case the
+ parameeters are incorrect or some other exception is
+ encountered.</para>
+
+ <para>Note: not all backends support this command.</para>
+ </section>
+ </section>
+ </section>
+
- <itemizedlist mark='bullet'>
++ <section xml:id="subnet-cmds">
+ <title>subnet_cmds: Subnet Commands</title>
+ <para>
+ This section describes a hook application that offers a number of new
+ commands used to query and manipulate subnet configurations in Kea.
+ This application is very useful in deployments with a large number of
+ subnets being managed by the DHCP servers and when the subnets are
+ frequently updated. The commands offer lightweight approach for
+ manipulating subnets without a need to fully reconfigure the server
+ and without affecting existing servers' configurations.
+ </para>
+
+ <para>Currently this library is only available to ISC customers with a
+ support contract.</para>
+
+ <para>The following commands are currently supported:
++ <itemizedlist mark="bullet">
+ <listitem>
+ <simpara><command>subnet4-list/subnet6-list</command>: lists all configured subnets
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>subnet4-get/subnet6-get</command>: retrieves detailed information about a selected subnet
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>subnet4-add/subnet6-add</command>: adds new subnet into server's configuration
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>subnet4-del/subnet6-del</command>: removes a subnet from the server's configuration
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <section>
+ <title>subnet4-list command</title>
+ <para>
+ This command is used to list all currently configured subnets. The
+ subnets are returned in a brief form, i.e. a subnet identifier
+ and subnet prefix is included for each subnet. In order to retrieve
+ the detailed information about the subnet the
+ <command>subnet4-get</command> should be used.
+ </para>
+ <para>
+ This command has the simple structure:
+ <screen>
+ {
+ "command": "subnet4-list"
+ }
+ </screen>
+ </para>
+ <para>
+ The list of subnets returned as a result of this command is returned
+ in the following format:
+ <screen>
+ {
+ "result": 0,
+ "text": "2 IPv4 subnets found",
+ "arguments": {
+ "subnets": [
+ {
+ "id": 10,
+ "subnet": "10.0.0.0/8"
+ },
+ {
+ "id": 100,
+ "subnet": "192.0.2.0/24"
+ }
+ ]
+ }
+ </screen>
+ </para>
+ <para>
+ If no IPv4 subnets are found, an error code is returned along with
+ the error description.
+ </para>
+ </section>
+
+ <section>
+ <title>subnet6-list command</title>
+ <para>
+ This command is used to list all currently configured subnets. The
+ subnets are returned in a brief form, i.e. a subnet identifier
+ and subnet prefix is included for each subnet. In order to retrieve
+ the detailed information about the subnet the
+ <command>subnet6-get</command> should be used.
+ </para>
+ <para>
+ This command has the simple structure:
+ <screen>
+ {
+ "command": "subnet6-list"
+ }
+ </screen>
+ </para>
+ <para>
+ The list of subnets returned as a result of this command is returned
+ in the following format:
+ <screen>
+ {
+ "result": 0,
+ "text": "2 IPv6 subnets found",
+ "arguments": {
+ "subnets": [
+ {
+ "id": 11,
+ "subnet": "2001:db8:1::/64"
+ },
+ {
+ "id": 233,
+ "subnet": "3000::/16"
+ }
+ ]
+ }
+ </screen>
+ </para>
+ <para>
+ If no IPv6 subnets are found, an error code is returned along with
+ the error description.
+ </para>
+ </section>
+
+ <section>
+ <title>subnet4-get command</title>
+ <para>This command is used to retrieve detailed information about the
+ specified subnet. This command usually follows the
+ <command>subnet4-list</command>, which is used to discover available
+ subnets with their respective subnet identifiers and prefixes. Any of
+ those parameters can be then used in <command>subnet4-get</command>
+ to fetch subnet information:
+ <screen>
+ {
+ "command": "subnet4-get",
+ "arguments": {
+ "id": 10
+ }
+ }</screen>
+
+ or
+
+ <screen>
+ {
+ "command": "subnet4-get",
+ "arguments": {
+ "subnet": "10.0.0.0/8"
+ }
+ }
+ </screen>
+ </para>
+
+ <para>
+ If the subnet exists the response will be similar to this:
+ <screen>
+ {
+ "result": 0,
+ "text": "Info about IPv4 subnet 10.0.0.0/8 (id 10) returned",
+ "arguments": {
+ "subnets": [
+ {
+ "subnet": "10.0.0.0/8",
+ "id": 1,
+ "option-data": [
+ ....
+ ]
+ ...
+ }
+ ]
+ }
+ }
+ </screen>
+ </para>
+ </section>
+
+ <section>
+ <title>subnet6-get command</title>
+ <para>This command is used to retrieve detailed information about the
+ specified subnet. This command usually follows the
+ <command>subnet6-list</command>, which is used to discover available
+ subnets with their respective subnet identifiers and prefixes. Any of
+ those parameters can be then used in <command>subnet6-get</command>
+ to fetch subnet information:
+ <screen>
+ {
+ "command": "subnet6-get",
+ "arguments": {
+ "id": 11
+ }
+ }
+ </screen>
+
+ or
+
+ <screen>
+ {
+ "command": "subnet6-get",
+ "arguments": {
+ "subnet": "2001:db8:1::/64"
+ }
+ }</screen>
+
+ If the subnet exists the response will be similar to this:
+ <screen>
+ {
+ "result": 0,
+ "text": "Info about IPv6 subnet 2001:db8:1::/64 (id 11) returned",
+ "arguments": {
+ "subnets": [
+ {
+ "subnet": "2001:db8:1::/64",
+ "id": 1,
+ "option-data": [
+ ...
+ ]
+ ....
+ }
+ ]
+ }
+ }
+ </screen>
+ </para>
+ </section>
+
+ <section>
+ <title>subnet4-add</title>
+ <para>
+ This command is used to create and add new subnet to the existing
+ server configuration. This operation has no impact on other
+ subnets. The subnet identifier must be specified and must be
+ unique among all subnets. If the identifier or a subnet prefix is
+ not unique an error is reported and the subnet is not added.
+ </para>
+ <para>
+ The subnet information within this command has the same structure
+ as the subnet information in the server configuration file with the
+ exception that static host reservations must not be specified
+ within <command>subnet4-add</command>. The commands described in
+ <xref linkend="host-cmds"/> should be used to add, remove and
+ modify static reservations.
+ <screen>
+ {
+ "command": "subnet4-add",
+ "arguments": {
+ "subnets": [ {
+ "id": 123,
+ "subnet": "10.20.30.0/24",
+ ...
+ } ]
+ }
+ }
+ </screen>
+ </para>
+
+ <para>
+ The response to this command has the following structure:
+ <screen>
+ {
+ "result": 0,
+ "text": "IPv4 subnet added",
+ "arguments": {
+ "subnets": [
+ {
+ "id": 123,
+ "subnet": "10.20.30.0/24"
+ }
+ ]
+ }
+ }
+ </screen>
+ </para>
+ </section>
+
+ <section>
+ <title>subnet6-add</title>
+ <para>
+ This command is used to create and add new subnet to the existing
+ server configuration. This operation has no impact on other
+ subnets. The subnet identifier must be specified and must be
+ unique among all subnets. If the identifier or a subnet prefix is
+ not unique an error is reported and the subnet is not added.
+ </para>
+ <para>
+ The subnet information within this command has the same structure
+ as the subnet information in the server configuration file with the
+ exception that static host reservations must not be specified
+ within <command>subnet6-add</command>. The commands described in
+ <xref linkend="host-cmds"/> should be used to add, remove and
+ modify static reservations.
+ <screen>
+ {
+ "command": "subnet6-add",
+ "arguments": {
+ "subnet6": [ {
+ "id": 234,
+ "subnet": "2001:db8:1::/64",
+ ...
+ } ]
+ }
+ }
+ </screen>
+ </para>
+
+ <para>
+ The response to this command has the following structure:
+ <screen>
+ {
+ "result": 0,
+ "text": "IPv6 subnet added",
+ "arguments": {
+ "subnet6": [
+ {
+ "id": 234,
+ "subnet": "2001:db8:1::/64"
+ }
+ ]
+ }
+ }
+ </screen>
+ </para>
+
+ <para>
+ It is recommended, but not mandatory to specify subnet
+ id. If not specified, Kea will try to assign the next
+ subnet-id value. This automatic ID value generator is
+ simple. It returns a previously automatically assigned value
+ increased by 1. This works well, unless you manually create
+ a subnet with a value bigger than previously used. For
+ example, if you call subnet4-add five times, each without
+ id, Kea will assign IDs: 1,2,3,4 and 5 and it will work just
+ fine. However, if you try to call subnet4-add five times,
+ with the first subnet having subnet-id of value 3 and
+ remaining ones having no subnet-id, it will fail. The first
+ command (with explicit value) will use subnet-id 3, the
+ second command will create a subnet with id of 1, the third
+ will use value of 2 and finally the fourth will have the
+ subnet-id value auto-generated as 3. However, since there is
+ already a subnet with that id, it will fail.
+ </para>
+ <para>
+ The general recommendation is to either: never use explicit
+ values (so the auto-generated values will always work) or
+ always use explicit values (so the auto-generation is never
+ used). You can mix those two approaches only if you
+ understand how the internal automatic subnet-id generation works.
+ </para>
+
+ </section>
+
+ <section>
+ <title>subnet4-del command</title>
+ <para>
+ This command is used to remove a subnet from the server's configuration.
+ This command has no effect on other configured subnets but removing
+ a subnet has certain implications which the server's administrator
+ should be aware of.
+ </para>
+ <para>
+ In most cases the server has assigned some leases to the clients
+ belonging to the subnet. The server may also be configured with
+ static host reservations which are associated with this subnet.
+ The current implementation of the <command>subnet4-del</command>
+ removes neither the leases nor host reservations associated with
+ a subnet. This is the safest approach because the server doesn't
+ loose track of leases assigned to the clients from this subnet.
+ However, removal of the subnet may still cause configuration
+ errors and conflicts. For example: after removal of the subnet,
+ the server administrator may add a new subnet with the ID used
+ previously for the removed subnet. This means that the existing
+ leases and static reservations will be in conflict with this
+ new subnet. Thus, we recommend that this command is used with extreme
+ caution.
+ </para>
+
+ <para>The command has the following structure:
+ <screen>
+ {
+ "command": "subnet4-del",
+ "arguments": {
+ "id": 123
+ }
+ }
+ </screen>
+ </para>
+ <para>
+ The example successful response may look like this:
+ <screen>
+ {
+ "result": 0,
+ "text": "IPv4 subnet 192.0.2.0/24 (id 123) deleted",
+ "arguments": {
+ "subnets": [
+ {
+ "id": 123,
+ "subnet": "192.0.2.0/24"
+ }
+ ]
+ }
+ }
+ </screen>
+ </para>
+ </section>
+
+ <section>
+ <title>subnet6-del command</title>
+ <para>
+ This command is used to remove a subnet from the server's configuration.
+ This command has no effect on other configured subnets but removing
+ a subnet has certain implications which the server's administrator
+ should be aware of.
+ </para>
+ <para>
+ In most cases the server has assigned some leases to the clients
+ belonging to the subnet. The server may also be configured with
+ static host reservations which are associated with this subnet.
+ The current implementation of the <command>subnet6-del</command>
+ removes neither the leases nor host reservations associated with
+ a subnet. This is the safest approach because the server doesn't
+ loose track of leases assigned to the clients from this subnet.
+ However, removal of the subnet may still cause configuration
+ errors and conflicts. For example: after removal of the subnet,
+ the server administrator may add a new subnet with the ID used
+ previously for the removed subnet. This means that the existing
+ leases and static reservations will be in conflict with this
+ new subnet. Thus, we recommend that this command is used with extreme
+ caution.
+ </para>
+
+ <para>The command has the following structure:
+ <screen>
+ {
+ "command": "subnet6-del",
+ "arguments": {
+ "id": 234
+ }
+ }
+ </screen>
+ </para>
+ <para>
+ The example successful response may look like this:
+ <screen>
+ {
+ "result": 0,
+ "text": "IPv6 subnet 2001:db8:1::/64 (id 234) deleted",
+ "subnets": [
+ {
+ "id": 234,
+ "subnet": "2001:db8:1::/64"
+ }
+ ]
+ }
+ </screen>
+ </para>
</section>
</section>
+ </section> <!-- end of subnet commands -->
- <section xml:id="user-context"><info><title>User contexts</title></info>
- <section id="user-context">
++ <section xml:id="user-context">
+ <title>User contexts</title>
<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
</para>
</section>
- </chapter>
+
+
- </chapter> <!-- hooks-libraries -->
++ </chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
-
- <chapter id="installation">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="installation">
+ <title>Installation</title>
+
- <section id="packages">
++ <section xml:id="packages">
+ <title>Packages</title>
- <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
</para>
</section>
- <section xml:id="install-hierarchy"><info><title>Installation Hierarchy</title></info>
- <section id="install-hierarchy">
++ <section xml:id="install-hierarchy">
+ <title>Installation Hierarchy</title>
<para>
The following is the directory layout of the complete Kea installation.
(All directory paths are relative to the installation directory):
</para>
</section>
- <section xml:id="build-requirements"><info><title>Building Requirements</title></info>
- <section id="build-requirements">
++ <section xml:id="build-requirements">
+ <title>Building Requirements</title>
+
<para>
- In addition to the run-time requirements (listed in <xref
- linkend="required-software"/>), building Kea from source code requires
+ In addition to the run-time requirements (listed in <xref linkend="required-software"/>), building Kea from source code requires
various development include headers and program development tools.
</para>
<para>
Visit the user-contributed wiki at
- <ulink url="http://kea.isc.org/wiki/SystemSpecificNotes" />
+ <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/wiki/SystemSpecificNotes">http://kea.isc.org/wiki/SystemSpecificNotes</uri>
for system-specific installation tips.
</para>
+
</section>
- <section xml:id="install"><info><title>Installation from Source</title></info>
- <section id="install">
++ <section xml:id="install">
+ <title>Installation from Source</title>
<para>
Kea is open source software written in C++. It is freely available in
source code form from ISC as a downloadable tar file. A copy of the Kea
in pre-compiled ready-to-use packages from operating system vendors.
</para>
- <section><info><title>Download Tar File</title></info>
+ <section>
+
+ <title>Download Tar File</title>
<para>
The Kea release tarballs may be downloaded from:
- <ulink url="http://ftp.isc.org/isc/kea/"/> (using FTP or HTTP).
+ <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).
</para>
</section>
are a developer planning to contribute to Kea, please fork our Github
repository and use the "pull request" mechanism to request integration of
your code. Please consult
- <ulink url="https://help.github.com/articles/fork-a-repo/"/> for help on
+ <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 <ulink url="http://git.kea.isc.org/~tester/kea/doxygen/">Kea
- Developer's Guide</ulink> contains more information about the process, as
++ 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>
- <section xml:id="configure"><info><title>Configure Before the Build</title></info>
+
- <section id="configure">
++ <section xml:id="configure">
+ <title>Configure Before the Build</title>
<para>
Kea uses the GNU Build System to discover build environment
details.
</section>
- <section xml:id="dhcp-config-backend"><info><title>Selecting the Configuration Backend</title></info>
- <section id="dhcp-config-backend">
++ <section xml:id="dhcp-config-backend">
+ <title>Selecting the Configuration Backend</title>
<para>Kea 0.9 introduced configuration backends that are
switchable during the compilation phase. Only one backend, JSON,
is currently supported.
</listitem>
</varlistentry>
</variablelist>
+
</section>
- <section xml:id="dhcp-install-configure"><info><title>DHCP Database Installation and Configuration</title></info>
- <section id="dhcp-install-configure">
++ <section xml:id="dhcp-install-configure">
+ <title>DHCP Database Installation and Configuration</title>
<para>
Kea stores its leases in a lease database. The software has been
written in a way that makes it possible to choose which database product
</para>
</section>
- <section><info><title>Building with PostgreSQL support</title></info>
+ <section>
+ <title>Building with PostgreSQL support</title>
<para>
Install PostgreSQL according to the instructions for your system. The client development
- libraries must be installed. Client development libraries are often packaged as "libpq".
+ libraries must be installed. Client development libraries are often packaged as "libpq".
</para>
<para>
Build and install Kea as described in <xref linkend="installation"/>, with
</para>
</section>
- <section><info><title>Building with CQL (Cassandra) support</title></info>
+ <section>
+ <title>Building with CQL (Cassandra) support</title>
<para>
Install Cassandra according to the instructions for your system. The
- Cassandra project website contains useful pointers: <ulink
- url="http://cassandra.apache.org" />.
+ 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>.
</para>
<para>
Download and compile cpp-driver from DataStax. For details regarding
</section>
</section>
-- </chapter>
++ </chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-<!ENTITY % version SYSTEM "version.ent">
-%version;
-]>
--
- <chapter id="intro">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="intro">
+ <title>Introduction</title>
<para>
Kea is the next generation of DHCP software developed by ISC.
It supports both DHCPv4 and DHCPv6 protocols along with their
</para>
<para>
- This guide covers Kea version &__VERSION__;.
+ This guide covers Kea version .
</para>
- <section><info><title>Supported Platforms</title></info>
+ <section>
+ <title>Supported Platforms</title>
<para>
Kea is officially supported on Red Hat Enterprise Linux,
- CentOS, Fedora and FreeBSD systems. It is also likely to work on many
- other platforms: Kea 1.1.0 builds have been tested on (in no
- particular order) Red Hat Enteprise Linux 6.4, Debian GNU/Linux 7,
+ CentOS, Fedora and FreeBSD systems. It is also likely to work on many
+ other platforms: Kea 1.1.0 builds have been tested on (in no
+ particular order) Red Hat Enterprise Linux 6.4, Debian GNU/Linux 7,
Ubuntu 12.04, Ubuntu 14.04, Ubuntu 16.04, Fedora Linux 19,
Fedora 20, Fedora 22, CentOS Linux 7, NetBSD 6, FreeBSD 10.3,
OpenBSD 5.7, OpenBSD 6.0, OS X 10.10, OS X 10.11.
<para>There are currently no plans to port Kea to Windows platforms.</para>
</section>
- <section xml:id="required-software"><info><title>Required Software at Run-time</title></info>
- <section id="required-software">
++ <section xml:id="required-software">
+ <title>Required Software at Run-time</title>
+
<para>
Running Kea uses various extra software which may
not be provided in the default installation of some operating systems,
</itemizedlist>
</section>
- <section xml:id="kea_software"><info><title>Kea Software</title></info>
- <section id="kea_software">
++ <section xml:id="kea_software">
+ <title>Kea Software</title>
<para>
Kea is modular. Part of this modularity is
accomplished using multiple cooperating processes which, together,
<listitem>
<simpara>
- <command>kea-lfc</command> —
+ <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>
<!-- TODO point to this -->
</para>
-- </chapter>
++ </chapter>
- <!-- Converted by db4-upgrade version 1.0 -->
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-<!ENTITY % version SYSTEM "version.ent">
-%version;
-]>
-
-<!--
- - Copyright (C) 2010-2017 Internet Systems Consortium, Inc. ("ISC")
- -
- - This Source Code Form is subject to the terms of the Mozilla Public
- - License, v. 2.0. If a copy of the MPL was not distributed with this
- - file, You can obtain one at http://mozilla.org/MPL/2.0/.
--->
-
-<book>
++<!-- Converted by db4-upgrade version 1.1 -->
+<book xmlns="http://docbook.org/ns/docbook" version="5.0">
<?xml-stylesheet href="kea-guide.css" type="text/css"?>
- <info><title>
- <bookinfo>
++ <info>
+
+ <title>
<inlinemediaobject>
<imageobject>
<imagedata fileref="kea-logo-100x70.png" align="left"/>
</title>
<releaseinfo>This is the reference guide for Kea version
- &__VERSION__;.</releaseinfo>
+ .</releaseinfo>
<copyright>
- <year>2010-2016</year><holder>Internet Systems Consortium, Inc.</holder>
+ <year>2010-2017</year><holder>Internet Systems Consortium, Inc.</holder>
</copyright>
- This is the reference guide for Kea version &__VERSION__;.
+ <abstract>
+
+ <para>
+ Kea is an open source implementation of the Dynamic Host Configuration
+ Protocol (DHCP) servers, developed and maintained by Internet Systems
+ Consortium (ISC).
+ </para>
+
+ <para>
- Kea, can be found at <ulink url="http://kea.isc.org/docs"/>.
++ This is the reference guide for Kea version .
+ The most up-to-date version of this document (in PDF, HTML,
+ and plain text formats), along with other documents for
- </bookinfo>
++ Kea, can be found at <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://kea.isc.org/docs">http://kea.isc.org/docs</uri>.
+ </para> </abstract>
+
+ </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="intro.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="quickstart.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="quickstart.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="install.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="install.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="admin.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="admin.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="keactrl.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="keactrl.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="agent.xml" />
++ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="agent.xml"/>
+
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp4-srv.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp4-srv.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp6-srv.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp6-srv.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lease-expiration.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lease-expiration.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ddns.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ddns.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lfc.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lfc.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="classify.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="classify.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hooks.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hooks.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stats.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stats.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ctrl-channel.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ctrl-channel.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="libdhcp.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="libdhcp.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="shell.xml" />
++ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="shell.xml"/>
+
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="faq.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="faq.xml"/>
- <chapter xml:id="acknowledgments"><info><title>Acknowledgments</title></info>
- <chapter id="acknowledgments">
++ <chapter xml:id="acknowledgments">
+ <title>Acknowledgments</title>
+
<para>Kea is primarily designed, developed, and maintained by
Internet Systems Consortium, Inc. It is an open source project
and contributions are welcomed.</para>
within the BIND 10 framework. Hence, Kea development would not be
possible without the generous support of past BIND 10 project sponsors.</para>
- <para><ulink url="http://jprs.co.jp/">JPRS</ulink> and
- <ulink url="http://cira.ca/">CIRA</ulink> were Patron Level
+ <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://jprs.co.jp/">JPRS</link> and
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://cira.ca/">CIRA</link> were Patron Level
BIND 10 sponsors.</para>
- <para><ulink url="https://www.afnic.fr/">AFNIC</ulink>,
- <ulink url="https://www.cnnic.net.cn/">CNNIC</ulink>,
- <ulink url="https://www.nic.cz/">CZ.NIC</ulink>,
- <ulink url="http://www.denic.de/">DENIC eG</ulink>,
- <ulink url="https://www.google.com/">Google</ulink>,
- <ulink url="https://www.ripe.net/">RIPE NCC</ulink>,
- <ulink url="https://registro.br/">Registro.br</ulink>,
- <ulink url="https://nzrs.net.nz/">.nz Registry Services</ulink>, and
- <ulink url="https://www.tcinet.ru/">Technical Center of Internet</ulink>
+ <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.afnic.fr/">AFNIC</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.cnnic.net.cn/">CNNIC</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.nic.cz/">CZ.NIC</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.denic.de/">DENIC eG</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.google.com/">Google</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.ripe.net/">RIPE NCC</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://registro.br/">Registro.br</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://nzrs.net.nz/">.nz Registry Services</link>, and
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.tcinet.ru/">Technical Center of Internet</link>
were past BIND 10 sponsors.</para>
- <para><ulink url="https://www.afilias.info/">Afilias</ulink>,
- <ulink url="https://www.iis.se/">IIS.SE</ulink>,
- <ulink url="http://www.nominet.org.uk/">Nominet</ulink>, and
- <ulink url="https://www.sidn.nl/">SIDN</ulink> were founding
+ <para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.afilias.info/">Afilias</link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iis.se/">IIS.SE</link>,
+ <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> -->
--</book>
++</book>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
-
- <chapter id="keactrl">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="keactrl">
+ <title>Managing Kea with keactrl</title>
- <section xml:id="keactrl-overview"><info><title>Overview</title></info>
- <section id="keactrl-overview">
++ <section xml:id="keactrl-overview">
+ <title>Overview</title>
<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
- also provides the means for checking the current status of the servers
- and determining the configuration files in use.
+ <command>kea-dhcp6</command>, <command>kea-dhcp-ddns</command> and
+ <command>kea-ctrl-agent</command>). It also provides the means for
+ checking the current status of the servers and determining the
+ configuration files in use.
</para>
</section>
- <section xml:id="keactrl-usage"><info><title>Command Line Options</title></info>
- <section id="keactrl-usage">
++ <section xml:id="keactrl-usage">
+ <title>Command Line Options</title>
<para><command>keactrl</command> is run as follows:
<screen>
keactrl <command> [-c keactrl-config-file] [-s server[,server,..]]
</para>
</section>
- <section xml:id="keactrl-config-file"><info><title>The keactrl Configuration File</title></info>
- <section id="keactrl-config-file">
++ <section xml:id="keactrl-config-file">
+ <title>The keactrl Configuration File</title>
<para>
Depending on requirements, not all of the available servers need
be run. The keactrl configuration file sets which servers are
</note>
</section>
- <section xml:id="keactrl-commands"><info><title>Commands</title></info>
- <section id="keactrl-commands">
++ <section xml:id="keactrl-commands">
+ <title>Commands</title>
<para>The following commands are supported by <command>keactrl</command>:
<itemizedlist>
<listitem><simpara>
</para>
</section>
- <section xml:id="keactrl-overriding-servers"><info><title>Overriding the Server Selection</title></info>
- <section id="keactrl-overriding-servers">
++ <section xml:id="keactrl-overriding-servers">
+ <title>Overriding the Server Selection</title>
<para>
The optional <command>-s</command> switch allows
the selection of the servers to which <command>keactrl</command>
</itemizedlist>
</para>
</section>
-- </chapter>
++ </chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
-<chapter id="lease-expiration">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="lease-expiration">
+ <title>Lease Expiration in DHCPv4 and DHCPv6</title>
<para>The primary role of the DHCP server is to assign addresses and/or
delegate prefixes to DHCP clients. These addresses and prefixes are
DHCPv6 server configuration.
</para>
- <section xml:id="lease-reclamation"><info><title>Lease Reclamation</title></info>
- <section id="lease-reclamation">
++ <section xml:id="lease-reclamation">
+ <title>Lease Reclamation</title>
<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:
hooks libraries.</para>
</section>
- <section xml:id="lease-reclaim-config"><info><title>Configuring Lease Reclamation</title></info>
- <section id="lease-reclaim-config">
++ <section xml:id="lease-reclaim-config">
+ <title>Configuring Lease Reclamation</title>
<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
periodic reclamation of the expired leases.</para>
</section>
- <section xml:id="lease-affinity"><info><title>Configuring Lease Affinity</title></info>
- <section id="lease-affinity">
++ <section xml:id="lease-affinity">
+ <title>Configuring Lease Affinity</title>
<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
process may impact server responsiveness.</para>
</section>
- <section xml:id="lease-reclamation-defaults"><info><title>Default Configuration Values for Leases Reclamation</title></info>
- <section id="lease-reclamation-defaults">
++ <section xml:id="lease-reclamation-defaults">
+ <title>Default Configuration Values for Leases Reclamation</title>
<para>The following list presents all configuration parameters
pertaining to processing expired leases with their default values:</para>
<command>expired-leases-processing</command> map may be omitted entirely
in the configuration, in which case the default values are used for all
parameters listed above.</para>
+
</section>
- <section xml:id="leases-reclamation-using-command"><info><title>Reclaiming Expired Leases with Command</title></info>
- <section id="leases-reclamation-using-command">
++ <section xml:id="leases-reclamation-using-command">
+ <title>Reclaiming Expired Leases with Command</title>
<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
command.</para>
</section>
--</chapter>
++</chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
-
- <chapter id="kea-lfc">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-lfc">
+ <title>The LFC process</title>
- <section xml:id="kea-lfc-overview"><info><title>Overview</title></info>
- <section id="kea-lfc-overview">
++ <section xml:id="kea-lfc-overview">
+ <title>Overview</title>
<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
</para>
</section>
- <section xml:id="kea-lfc-usage"><info><title>Command Line Options</title></info>
- <section id="kea-lfc-usage">
++ <section xml:id="kea-lfc-usage">
+ <title>Command Line Options</title>
<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
</para>
</section>
-- </chapter>
++ </chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
--
- <chapter id="libdhcp">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="libdhcp">
+ <title>The libdhcp++ Library</title>
<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>
- <section id="iface-detect">
++ <section xml:id="iface-detect">
+ <title>Interface detection and Socket handling</title>
<para>Both the DHCPv4 and DHCPv6 components share network
interface detection routines. Interface detection is
currently supported on Linux, all BSD family (FreeBSD, NetBSD,
</section>
-->
-- </chapter>
++ </chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
-
- <!-- Note: Please use the following terminology:
- - daemon - one process (e.g. kea-dhcp4)
- - component - one piece of code within a daemon (e.g. libdhcp or hooks)
- - server - currently equal to daemon, but the difference will be more
- prominent once we add client or relay support
- - logger - one instance of isc::log::Logger
- - structure - an element in config file (e.g. "Dhcp4")
-
- Do not use:
- - module => daemon
- -->
-
-<chapter id="logging">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="logging">
+ <title>Logging</title>
- <section><info><title>Logging Configuration</title></info>
+ <section>
+ <title>Logging Configuration</title>
<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>
- <section><info><title>maxsize (integer)</title></info>
+ <section>
+ <title>maxsize (integer)</title>
<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
- renamed and a new file opened. (For example, a ".1" is appended to
- the name — if a ".1" file exists, it is renamed ".2", etc.)
+ Only relevant when the destination is a file. This is maximum size
+ in bytes that a log file may reach. When the maximum size is
+ reached, the file is renamed and a new file opened. For example,
- a ".1" is appended to the name — if a ".1" file exists, it
++ a ".1" is appended to the name — if a ".1" file exists, it
+ is renamed ".2", etc. This is referred to as rotation.
</para>
<para>
- If this is set to 0 or omitted, no maximum file size is used.
+ The default value is 10240000 (10MB). The smallest value that may
+ be specified without disabling rotation is 204800. Any value less than
+ this, including 0, disables rotation.
</para>
-
<note>
<simpara>
Due to a limitation of the underlying logging library (log4cplus),
</section>
- <section xml:id="logging-message-format"><info><title>Logging Message Format</title></info>
- <section id="logging-message-format">
++ <section xml:id="logging-message-format">
+ <title>Logging Message Format</title>
<para>
Each message written to the configured logging destinations comprises a
number of components that identify the origin of the message and, if the
</para>
</section>
- <section xml:id="logging-during-startup"><info><title>Logging During Kea Startup</title></info>
- <section id="logging-during-startup">
++ <section xml:id="logging-during-startup">
+ <title>Logging During Kea Startup</title>
<para>
The logging configuration is specified in the configuration file.
However, when Kea starts, the file is not read until some way into the
</variablelist>
</section>
</section>
-
--</chapter>
++</chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-<!ENTITY % version SYSTEM "version.ent">
-%version;
-]>
-
- <chapter id="quickstart">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="quickstart">
+ <title>Quick Start</title>
<para>
This section describes the basic steps needed to get Kea up and running.
respective chapters in the Kea guide.
</para>
- <section xml:id="quick-start"><info><title>Quick Start Guide for DHCPv4 and DHCPv6 Services</title></info>
- <orderedlist inheritnum="ignore" continuation="restarts">
- <section id="quick-start">
++ <section xml:id="quick-start">
+ <title>Quick Start Guide for DHCPv4 and DHCPv6 Services</title>
+
+ <orderedlist>
+
<listitem>
<simpara>
- Install required run-time and build dependencies. See <xref
- linkend="build-requirements"/> for details.
+ Install required run-time and build dependencies. See <xref linkend="build-requirements"/> for details.
</simpara>
</listitem>
in <xref linkend="keactrl"/>.</para>
</section>
- <section xml:id="quick-start-direct-run"><info><title>Running the Kea Servers Directly</title></info>
- <section id="quick-start-direct-run">
++ <section xml:id="quick-start-direct-run">
+ <title>Running the Kea Servers Directly</title>
<para>The Kea servers can be started directly, without the need to use the
<command>keactrl</command>. To start the DHCPv4 server run the following
command:
</para>
</section>
-- </chapter>
++ </chapter>
--- /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "‗" >
-]>
-
-<chapter id="kea-shell">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-shell">
+ <title>The Kea Shell</title>
+
- <section id="shell-overview">
++ <section xml:id="shell-overview">
+ <title>Overview</title>
+ <para>Kea 1.2.0 introduced the Control Agent (CA, see <xref linkend="kea-ctrl-agent"/>) that
+ provides a RESTful control interface over HTTP. That API is typically expected to be used by
+ various IPAMs and similar management systems. Nevertheless, there may be cases when you want
+ to send a command to the CA directly. The Kea Shell provides a way to do this. It is a simple
+ command-line, scripting-friendly text client that is able connect to the CA, send it commands
+ with parameters, retrieve the responses and display them.</para>
+
+ <para>As the primary purpose of the Kea Shell is as a tool in scripting environment,
+ it is not interactive. However, with simple tricks it can be run manually.
+ </para>
+ </section>
+
- <section id="shell-usage">
++ <section xml:id="shell-usage">
+ <title>Shell Usage</title>
+ <para><command>kea-shell</command> is run as follows:
+ <screen>
+ kea-shell [--host hostname] [--port number] [--timeout seconds] [--service service-name] [command]
+ </screen>
+ where:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>--host <replaceable>hostname</replaceable></command> specifies the hostname
+ of the CA. If not specified, "localhost" is used.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>--port <replaceable>number</replaceable></command> specifies the TCP port
+ on which the CA listens. If not specified, 8000 is used.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>--timeout <replaceable>seconds</replaceable></command> specifies the
+ timeout (in seconds) for the connection. If not given, 10 seconds is used.
+ </simpara>
+ </listitem>
+
+ <listitem>
+ <simpara>
+ <command>--service <replaceable>service-name</replaceable></command> specifies the
+ target of a command. If not given, CA will be used as target. May be used more
+ than once to specify multiple targets.
+ </simpara>
+ </listitem>
+
+
+ <listitem>
+ <simpara>
+ <command>command</command> specifies the command to be sent. If not specified,
+ <command>list-commands</command> command is used.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+
+ <para>Other switches are:</para>
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ <command>-h</command> prints a help message.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ <command>-v</command> prints the software version.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Once started, the shell reads parameters for the command from standard input, which are
+ expected to be in JSON format. When all have been read, the shell establishes a connection
+ with the CA using HTTP, sends the command and awaits a response. Once that is received,
+ it is printed on standard output.
+ </para>
+
+ <para>
+ For a list of available commands, see <xref linkend="ctrl-channel"/>. Additional commands
+ may be provided by hook libraries. If unsure which commands are supported, use the
+ <command>list-commands</command> command. It will instruct the CA to return a list of
+ all supported commands.
+ </para>
+
+ <para>The following shows a simple example of usage:
+ <screen>
+ $ <userinput>kea-shell --host 192.0.2.1 --port 8001 --service dhcp4 list-commands</userinput>
+ ^D
+ </screen>
+ After the command line is entered, the program waits for command parameters to be entered.
+ Since <command>list-commands</command> does not take any
+ arguments, CTRL-D (represented in the above example by "^D") is pressed to indicate end
+ of file (and so terminate the parameter input). The Shell will then contact
+ the CA and print out the list of available commands returned for the service named <command>dhcp4</command>.
+ </para>
+
+ <para>It is envisaged that Kea Shell will be most frequently used in scripts. The next example
+ shows a simple scripted execution. It sends the command "config-write" to the CA
+ (<command> --service </command> parameter hasn't been used), along
+ with the parameters specified in param.json. The result will be stored in result.json.
+ <screen>
+ $ cat param.json
+ "filename": "my-config-file.json"
-$ <userinput>cat param.json | kea-shell --host 192.0.2.1 config-write > result.json</userinput>
++$ <userinput>cat param.json | kea-shell --host 192.0.2.1 config-write > result.json</userinput>
+ </screen>
+ </para>
+
+ <para>Kea Shell requires Python to to be installed on the system. It was tested with
+ Python 2.7 and various versions
+ of Python 3, up to 3.5. Since not every Kea deployment uses this feature and there are
+ deployments that do not have Python, the Kea Shell is not enabled by default. To use it,
+ you must specify <command>--enable-shell</command> to when running "configure" during the
+ installation of Kea.</para>
+
+ <para>The Kea Shell is intended to serve more as a demonstration of the RESTful interface
+ capabilities (and, perhaps, an illustration for people interested in integrating their
+ management evironments with Kea) than as a serious management client. Do not expect it
+ to be significantly expanded in the future. It is, and will remain, a simple tool.</para>
+ </section>
-</chapter>
++</chapter>
- <!-- 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>
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY mdash "—" >
-]>
-
-<chapter id="stats">
++<!-- Converted by db4-upgrade version 1.1 -->
++<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="stats">
+ <title>Statistics</title>
+
+ <section>
+ <title>Statistics Overview</title>
- <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
</para>
</section>
- <section xml:id="stats-lifecycle"><info><title>Statistics Lifecycle</title></info>
- <section id="stats-lifecycle">
++ <section xml:id="stats-lifecycle">
+ <title>Statistics Lifecycle</title>
<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
</para>
</section>
- <section xml:id="command-stats"><info><title>Commands for Manipulating Statistics</title></info>
- <section id="command-stats">
++ <section xml:id="command-stats">
+ <title>Commands for Manipulating Statistics</title>
<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
sending commands to Kea, see <xref linkend="ctrl-channel"/>.
</para></note>
- <section xml:id="command-statistic-get"><info><title>statistic-get command</title></info>
- <section id="command-statistic-get">
++ <section xml:id="command-statistic-get">
+ <title>statistic-get command</title>
+
<para>
<emphasis>statistic-get</emphasis> command retrieves a single
statistic. It takes a single string parameter called
</para>
</section> <!-- end of command-statistic-get -->
- <section xml:id="command-statistic-reset"><info><title>statistic-reset command</title></info>
- <section id="command-statistic-reset">
++ <section xml:id="command-statistic-reset">
+ <title>statistic-reset command</title>
+
<para>
<emphasis>statistic-reset</emphasis> command sets the specified statistic
to its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time
</para>
</section> <!-- end of command-statistic-reset -->
- <section xml:id="command-statistic-remove"><info><title>statistic-remove command</title></info>
- <section id="command-statistic-remove">
++ <section xml:id="command-statistic-remove">
+ <title>statistic-remove command</title>
+
<para>
<emphasis>statistic-remove</emphasis> command attempts to delete a single
statistic. It takes a single string parameter called
</para>
</section> <!-- end of command-statistic-reset -->
- <section xml:id="command-statistic-get-all"><info><title>statistic-get-all command</title></info>
- <section id="command-statistic-get-all">
++ <section xml:id="command-statistic-get-all">
+ <title>statistic-get-all command</title>
+
<para>
<emphasis>statistic-get-all</emphasis> command retrieves all statistics
recorded. An example command may look like this:
</para>
</section> <!-- end of command-statistic-get-all -->
- <section xml:id="command-statistic-reset-all"><info><title>statistic-reset-all command</title></info>
- <section id="command-statistic-reset-all">
++ <section xml:id="command-statistic-reset-all">
+ <title>statistic-reset-all command</title>
+
<para>
<emphasis>statistic-reset</emphasis> command sets all statistics to
their neutral values: 0 for integer, 0.0 for float, 0h0m0s0us for time
</para>
</section> <!-- end of command-statistic-reset-all -->
- <section xml:id="command-statistic-remove-all"><info><title>statistic-remove-all command</title></info>
- <section id="command-statistic-remove-all">
++ <section xml:id="command-statistic-remove-all">
+ <title>statistic-remove-all command</title>
+
<para>
<emphasis>statistic-remove-all</emphasis> command attempts to delete all
statistics. An example command may look like this:
and the text field will contain the error description.
</para>
</section> <!-- end of command-statistic-remove-all -->
+
</section>
--</chapter>
++</chapter>
- <!-- Converted by db4-upgrade version 1.0 -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!--
- - Copyright (C) 2014-2016 Internet Systems Consortium, Inc. ("ISC")
- -
- - This Source Code Form is subject to the terms of the Mozilla Public
- - License, v. 2.0. If a copy of the MPL was not distributed with this
- - file, You can obtain one at http://mozilla.org/MPL/2.0/.
--->
-
-<refentry>
- <refentryinfo>
++<!-- Converted by db4-upgrade version 1.1 -->
+<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
+ <info>
<productname>ISC Kea</productname>
<date>Sep. 28, 2016</date>
<edition>1.1.0</edition>
<citetitle>Kea Administrator Guide</citetitle>.
</para>
- </refsection>
+ </refsect1>
-</refentry>
+</refentry>
--- /dev/null
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!--
- - Copyright (C) 2016-2017 Internet Systems Consortium, Inc. ("ISC")
- -
- - This Source Code Form is subject to the terms of the Mozilla Public
- - License, v. 2.0. If a copy of the MPL was not distributed with this
- - file, You can obtain one at http://mozilla.org/MPL/2.0/.
--->
-
-<refentry>
-
- <refentryinfo>
++<!-- Converted by db4-upgrade version 1.1 -->
++<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
++
++ <info>
+ <productname>ISC Kea</productname>
+ <date>Sep. 28, 2016</date>
+ <edition>1.1.0</edition>
- <author>
- <contrib>The Kea software has been written by a number of
++ <author><personname/><contrib>The Kea software has been written by a number of
+ engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
+ Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
+ Wlodek Wencel and Shawn Routhier. That list is roughly in the
+ chronological order in which the authors made their first
+ contribution. For a complete list of authors and
- contributors, see AUTHORS file.</contrib>
- <orgname>Internet Systems Consortium, Inc.</orgname>
- </author>
- </refentryinfo>
++ contributors, see AUTHORS file.</contrib><orgname>Internet Systems Consortium, Inc.</orgname></author>
++ </info>
+
+ <refmeta>
+ <refentrytitle>kea-ctrl-agent</refentrytitle>
+ <manvolnum>8</manvolnum>
+ <refmiscinfo class="manual">Kea</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kea-ctrl-agent</refname>
+ <refpurpose>Control Agent process in Kea</refpurpose>
+ </refnamediv>
+
+ <docinfo>
+ <copyright>
+ <year>2016</year>
+ <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
+ </copyright>
+ </docinfo>
+
+ <refsynopsisdiv>
- <cmdsynopsis>
++ <cmdsynopsis sepchar=" ">
+ <command>kea-ctrl-agent</command>
- <arg><option>-v</option></arg>
- <arg><option>-V</option></arg>
- <arg><option>-W</option></arg>
- <arg><option>-d</option></arg>
- <arg><option>-c<replaceable class="parameter">config-file</replaceable></option></arg>
- <arg><option>-t<replaceable class="parameter">config-file</replaceable></option></arg>
++ <arg choice="opt" rep="norepeat"><option>-v</option></arg>
++ <arg choice="opt" rep="norepeat"><option>-V</option></arg>
++ <arg choice="opt" rep="norepeat"><option>-W</option></arg>
++ <arg choice="opt" rep="norepeat"><option>-d</option></arg>
++ <arg choice="opt" rep="norepeat"><option>-c<replaceable class="parameter">config-file</replaceable></option></arg>
++ <arg choice="opt" rep="norepeat"><option>-t<replaceable class="parameter">config-file</replaceable></option></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+
+ <refsect1>
+ <title>DESCRIPTION</title>
+ <para>
+ The <command>kea-ctrl-agent</command> provides a REST service for
+ controlling Kea services. The received HTTP requests are decapsulated
+ and forwarded to the respective Kea services in JSON format. Received
+ JSON responses are encapsulated within HTTP responses and returned to
+ the controlling entity. Some commands may be handled by the Control
+ Agent directly, and not forwarded to any Kea service.
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>ARGUMENTS</title>
+
+ <para>The arguments are as follows:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-v</option></term>
+ <listitem><para>
+ Display the version.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-V</option></term>
+ <listitem><para>
+ Display the extended version.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-W</option></term>
+ <listitem><para>
+ Display the configuration report.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-d</option></term>
+ <listitem><para>
+ Verbose mode sets the logging level to debug. This is primarily
+ for development purposes in stand-alone mode.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-c</option></term>
+ <listitem><para>
+ Configuration file including the configuration for the Control Agent
+ server. It may also contain configuration entries for other Kea
+ services.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-t</option></term>
+ <listitem><para>
+ Check the syntax of the configuration file and report the
+ first error if any. Note that not all parameters are
+ completely checked, in particular, service and client
+ sockets are not opened, and hook libraries are not loaded.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>DOCUMENTATION</title>
+ <para>Kea comes with an extensive Kea User's Guide documentation
+ that covers all aspects of running the Kea software -
+ compilation, installation, configuration, configuration examples
+ and many more. Kea also features a Kea Messages Manual, which
+ lists all possible messages Kea can print with a brief
+ description for each of them. Both documents are typically
+ available in various formats (txt, html, pdf) with your Kea
+ distribution. The on-line version is available at
+ http://kea.isc.org/docs/.</para>
+ <para>
+ Kea source code is documented in the Kea Developer's Guide. It's
+ on-line version is available at http://kea.isc.org. Please
+ follow Developer's Guide link.
+ </para>
+ <para>
+ Kea project website is available at: http://kea.isc.org.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>MAILING LISTS AND SUPPORT</title>
+ <para>
+ There are two mailing lists available for Kea project. kea-users
+ (kea-users at lists.isc.org) is intended for Kea users, while kea-dev
+ (kea-dev at lists.isc.org) is intended for Kea developers, prospective
+ contributors and other advanced users. Both lists are available at
+ http://lists.isc.org. The community provides best effort type of support
+ on both of those lists.
+ </para>
+ <para>
+ ISC provides professional support for Kea services. See
+ https://www.isc.org/kea/ for details.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>HISTORY</title>
+ <para>
+ The <command>kea-ctrl-agent</command> was first coded in December 2016
+ by Marcin Siodelski.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>kea-dhcp4</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>kea-dhcp6</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>kea-dhcp-ddns</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>kea-admin</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>keactrl</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>perfdhcp</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>kea-lfc</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citetitle>Kea Administrator's Guide</citetitle>.
+
+ </para>
+ </refsect1>
+
-</refentry><!--
- - Local variables:
- - mode: sgml
- - End:
--->
++</refentry>
- <!-- Converted by db4-upgrade version 1.0 -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!--
- - Copyright (C) 2013-2017 Internet Systems Consortium, Inc. ("ISC")
- -
- - This Source Code Form is subject to the terms of the Mozilla Public
- - License, v. 2.0. If a copy of the MPL was not distributed with this
- - file, You can obtain one at http://mozilla.org/MPL/2.0/.
--->
-
-<refentry>
-
- <refentryinfo>
++<!-- Converted by db4-upgrade version 1.1 -->
+<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
+
+ <info>
<productname>ISC Kea</productname>
<date>Sep. 28, 2016</date>
<edition>1.1.0</edition>
</docinfo>
<refsynopsisdiv>
- <cmdsynopsis>
+ <cmdsynopsis sepchar=" ">
<command>kea-dhcp-ddns</command>
- <arg><option>-v</option></arg>
- <arg><option>-V</option></arg>
- <arg><option>-W</option></arg>
- <arg><option>-d</option></arg>
- <arg><option>-c<replaceable class="parameter">config-file</replaceable></option></arg>
- <arg><option>-t<replaceable class="parameter">config-file</replaceable></option></arg>
+ <arg choice="opt" rep="norepeat"><option>-v</option></arg>
+ <arg choice="opt" rep="norepeat"><option>-V</option></arg>
+ <arg choice="opt" rep="norepeat"><option>-W</option></arg>
+ <arg choice="opt" rep="norepeat"><option>-d</option></arg>
- <arg choice="opt" rep="norepeat"><option>-s</option></arg>
++ <arg choice="opt" rep="norepeat"><option>-c<replaceable class="parameter">config-file</replaceable></option></arg>
++ <arg choice="opt" rep="norepeat"><option>-t<replaceable class="parameter">config-file</replaceable></option></arg>
</cmdsynopsis>
</refsynopsisdiv>
<citetitle>Kea Administrator's Guide</citetitle>.
</para>
- </refsection>
+ </refsect1>
-</refentry><!--
- - Local variables:
- - mode: sgml
- - End:
--->
+</refentry>
- <!-- Converted by db4-upgrade version 1.0 -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!--
- - Copyright (C) 2011-2017 Internet Systems Consortium, Inc. ("ISC")
- -
- - This Source Code Form is subject to the terms of the Mozilla Public
- - License, v. 2.0. If a copy of the MPL was not distributed with this
- - file, You can obtain one at http://mozilla.org/MPL/2.0/.
--->
-
-<refentry>
-
- <refentryinfo>
++<!-- Converted by db4-upgrade version 1.1 -->
+<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
+
+ <info>
<productname>ISC Kea</productname>
<date>Sep. 28, 2016</date>
<edition>1.1.0</edition>
</docinfo>
<refsynopsisdiv>
- <cmdsynopsis>
+ <cmdsynopsis sepchar=" ">
<command>kea-dhcp4</command>
- <arg><option>-v</option></arg>
- <arg><option>-V</option></arg>
- <arg><option>-W</option></arg>
- <arg><option>-d</option></arg>
- <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
- <arg><option>-t <replaceable class="parameter">config-file</replaceable></option></arg>
- <arg><option>-p <replaceable class="parameter">port-number</replaceable></option></arg>
+ <arg choice="opt" rep="norepeat"><option>-v</option></arg>
+ <arg choice="opt" rep="norepeat"><option>-V</option></arg>
+ <arg choice="opt" rep="norepeat"><option>-W</option></arg>
+ <arg choice="opt" rep="norepeat"><option>-d</option></arg>
- <arg choice="opt" rep="norepeat"><option>-c<replaceable class="parameter">config-file</replaceable></option></arg>
- <arg choice="opt" rep="norepeat"><option>-p<replaceable class="parameter">port-number</replaceable></option></arg>
++ <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
++ <arg choice="opt" rep="norepeat"><option>-t <replaceable class="parameter">config-file</replaceable></option></arg>
++ <arg choice="opt" rep="norepeat"><option>-p <replaceable class="parameter">port-number</replaceable></option></arg>
</cmdsynopsis>
</refsynopsisdiv>
<citetitle>Kea Administrator's Guide</citetitle>.
</para>
- </refsection>
+ </refsect1>
-</refentry><!--
- - Local variables:
- - mode: sgml
- - End:
--->
+</refentry>
- <!-- Converted by db4-upgrade version 1.0 -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!--
- - Copyright (C) 2011-2017 Internet Systems Consortium, Inc. ("ISC")
- -
- - This Source Code Form is subject to the terms of the Mozilla Public
- - License, v. 2.0. If a copy of the MPL was not distributed with this
- - file, You can obtain one at http://mozilla.org/MPL/2.0/.
--->
-
-<refentry>
-
- <refentryinfo>
++<!-- Converted by db4-upgrade version 1.1 -->
+<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
+
+ <info>
<productname>ISC Kea</productname>
<date>Sep. 28, 2016</date>
<edition>1.1.0</edition>
</docinfo>
<refsynopsisdiv>
- <cmdsynopsis>
+ <cmdsynopsis sepchar=" ">
<command>kea-dhcp6</command>
- <arg><option>-v</option></arg>
- <arg><option>-V</option></arg>
- <arg><option>-W</option></arg>
- <arg><option>-d</option></arg>
- <arg><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
- <arg><option>-t <replaceable class="parameter">config-file</replaceable></option></arg>
- <arg><option>-p <replaceable class="parameter">port-number</replaceable></option></arg>
+ <arg choice="opt" rep="norepeat"><option>-v</option></arg>
+ <arg choice="opt" rep="norepeat"><option>-V</option></arg>
+ <arg choice="opt" rep="norepeat"><option>-W</option></arg>
+ <arg choice="opt" rep="norepeat"><option>-d</option></arg>
- <arg choice="opt" rep="norepeat"><option>-c<replaceable class="parameter">config-file</replaceable></option></arg>
- <arg choice="opt" rep="norepeat"><option>-p<replaceable class="parameter">port-number</replaceable></option></arg>
++ <arg choice="opt" rep="norepeat"><option>-c <replaceable class="parameter">config-file</replaceable></option></arg>
++ <arg choice="opt" rep="norepeat"><option>-t <replaceable class="parameter">config-file</replaceable></option></arg>
++ <arg choice="opt" rep="norepeat"><option>-p <replaceable class="parameter">port-number</replaceable></option></arg>
</cmdsynopsis>
</refsynopsisdiv>
<citetitle>Kea Administrator's Guide</citetitle>.
</para>
- </refsection>
+ </refsect1>
-</refentry><!--
- - Local variables:
- - mode: sgml
- - End:
--->
+</refentry>
- <!-- Converted by db4-upgrade version 1.0 -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!--
- - Copyright (C) 2014-2017 Internet Systems Consortium, Inc. ("ISC")
- -
- - This Source Code Form is subject to the terms of the Mozilla Public
- - License, v. 2.0. If a copy of the MPL was not distributed with this
- - file, You can obtain one at http://mozilla.org/MPL/2.0/.
--->
-
-<refentry>
- <refentryinfo>
++<!-- Converted by db4-upgrade version 1.1 -->
+<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
+ <info>
<productname>ISC Kea</productname>
<date>Sep. 28, 2016</date>
<edition>1.1.0</edition>
<citetitle>Kea Administrator's Guide</citetitle>.
</para>
- </refsection>
+ </refsect1>
-</refentry>
+</refentry>
- <!-- Converted by db4-upgrade version 1.0 -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!--
- - Copyright (C) 2015-2016 Internet Systems Consortium, Inc. ("ISC")
- -
- - This Source Code Form is subject to the terms of the Mozilla Public
- - License, v. 2.0. If a copy of the MPL was not distributed with this
- - file, You can obtain one at http://mozilla.org/MPL/2.0/.
--->
-
-<refentry>
-
- <refentryinfo>
++<!-- Converted by db4-upgrade version 1.1 -->
+<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
+
+ <info>
<productname>ISC Kea</productname>
<date>Sep. 28, 2016</date>
<edition>1.1.0</edition>
<citetitle>Kea Administrator's Guide</citetitle>.
</para>
- </refsection>
+ </refsect1>
-</refentry><!--
- - Local variables:
- - mode: sgml
- - End:
--->
+</refentry>
- <!-- Converted by db4-upgrade version 1.0 -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!--
- - Copyright (C) 2014-2016 Internet Systems Consortium, Inc. ("ISC")
- -
- - This Source Code Form is subject to the terms of the Mozilla Public
- - License, v. 2.0. If a copy of the MPL was not distributed with this
- - file, You can obtain one at http://mozilla.org/MPL/2.0/.
--->
-
-<refentry>
-
- <refentryinfo>
++<!-- Converted by db4-upgrade version 1.1 -->
+<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
+
+ <info>
<productname>ISC Kea</productname>
<date>Sep. 28, 2016</date>
<edition>1.1.0</edition>
<citetitle>Kea Administrator's Guide</citetitle>.
</para>
- </refsection>
+ </refsect1>
-</refentry>
+</refentry>
--- /dev/null
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!--
- - Copyright (C) 2017 Internet Systems Consortium, Inc. ("ISC")
- -
- - This Source Code Form is subject to the terms of the Mozilla Public
- - License, v. 2.0. If a copy of the MPL was not distributed with this
- - file, You can obtain one at http://mozilla.org/MPL/2.0/.
--->
-
-<refentry>
-
- <refentryinfo>
++<!-- Converted by db4-upgrade version 1.1 -->
++<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
++
++ <info>
+ <productname>ISC Kea</productname>
- <date>2017 Mar 8</date>
++ <date>0008-03-2017</date>
+ <edition>1.2.0</edition>
- <author>
- <contrib>The Kea software has been written by a number of
++ <author><personname/><contrib>The Kea software has been written by a number of
+ engineers working for ISC: Tomek Mrugalski, Stephen Morris, Marcin
+ Siodelski, Thomas Markwalder, Francis Dupont, Jeremy C. Reed,
+ Wlodek Wencel and Shawn Routhier. That list is roughly in the
+ chronological order in which the authors made their first
+ contribution. For a complete list of authors and
- contributors, see AUTHORS file.</contrib>
- <orgname>Internet Systems Consortium, Inc.</orgname>
- </author>
- </refentryinfo>
++ contributors, see AUTHORS file.</contrib><orgname>Internet Systems Consortium, Inc.</orgname></author>
++ </info>
+
+ <refmeta>
+ <refentrytitle>kea-shell</refentrytitle>
+ <manvolnum>8</manvolnum>
+ <refmiscinfo class="manual">Kea</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>kea-shell</refname>
+ <refpurpose>Text client for Control Agent process</refpurpose>
+ </refnamediv>
+
+ <docinfo>
+ <copyright>
+ <year>2017</year>
+ <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
+ </copyright>
+ </docinfo>
+
+ <refsynopsisdiv>
- <cmdsynopsis>
++ <cmdsynopsis sepchar=" ">
+ <command>kea-shell</command>
- <arg><option>-h</option></arg>
- <arg><option>-v</option></arg>
- <arg><option>--host</option></arg>
- <arg><option>--port</option></arg>
- <arg><option>--timeout</option></arg>
- <arg><option>--service</option></arg>
- <arg><option>command</option></arg>
++ <arg choice="opt" rep="norepeat"><option>-h</option></arg>
++ <arg choice="opt" rep="norepeat"><option>-v</option></arg>
++ <arg choice="opt" rep="norepeat"><option>--host</option></arg>
++ <arg choice="opt" rep="norepeat"><option>--port</option></arg>
++ <arg choice="opt" rep="norepeat"><option>--timeout</option></arg>
++ <arg choice="opt" rep="norepeat"><option>--service</option></arg>
++ <arg choice="opt" rep="norepeat"><option>command</option></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+
+ <refsect1>
+ <title>DESCRIPTION</title>
+ <para>
+ The <command>kea-shell</command> provides a REST client for the
+ Kea Control Agent (CA). It takes command as a command-line parameter
+ that is being sent to CA with proper JSON
+ encapsulation. Optional arguments may be specified on the
+ standard input. The request it sent of HTTP and a response is
+ retrieved. That response is displayed out on the standard output.
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>ARGUMENTS</title>
+
+ <para>The arguments are as follows:</para>
+
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-h</option></term>
+ <listitem><para>
+ Displays help regarding command line parameters.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-v</option></term>
+ <listitem><para>
+ Display the version.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--host</option></term>
+ <listitem><para>
+ Specifies the host to connect to. Control Agent must be
+ running at specified host. If not specified, 127.0.0.1 is used.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--port</option></term>
+ <listitem><para>
+ Specifies the TCP port to connect to. Control Agent must be
+ listening at specified port. If not specified, 8000 is used.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--timeout</option></term>
+ <listitem><para>
+ Specifies the connection timeout in seconds. If not
+ specified, 10 (seconds) is used.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--service</option></term>
+ <listitem><para>
+ Specifies the service that is the target of a command. If not
+ specified, Control Agent will be targeted. May be used more than
+ once to specify multiple targets.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>command</option></term>
+ <listitem><para>
+ Specifies the command to be sent to CA. If not
+ specified, "list-commands" is used.
+ </para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>DOCUMENTATION</title>
+ <para>Kea comes with an extensive Kea User's Guide documentation
+ that covers all aspects of running the Kea software -
+ compilation, installation, configuration, configuration examples
+ and many more. Kea also features a Kea Messages Manual, which
+ lists all possible messages Kea can print with a brief
+ description for each of them. Both documents are typically
+ available in various formats (txt, html, pdf) with your Kea
+ distribution. The on-line version is available at
+ http://kea.isc.org/docs/.</para>
+ <para>
+ Kea source code is documented in the Kea Developer's Guide. It's
+ on-line version is available at http://kea.isc.org. Please
+ follow Developer's Guide link.
+ </para>
+ <para>
+ Kea project website is available at: http://kea.isc.org.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>MAILING LISTS AND SUPPORT</title>
+ <para>
+ There are two mailing lists available for Kea project. kea-users
+ (kea-users at lists.isc.org) is intended for Kea users, while kea-dev
+ (kea-dev at lists.isc.org) is intended for Kea developers, prospective
+ contributors and other advanced users. Both lists are available at
+ http://lists.isc.org. The community provides best effort type of support
+ on both of those lists.
+ </para>
+ <para>
+ ISC provides professional support for Kea services. See
+ https://www.isc.org/kea/ for details.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>HISTORY</title>
+ <para>
+ The <command>kea-shell</command> was first coded in March 2017
+ by Tomek Mrugalski.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>kea-ctrl-agent</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>kea-dhcp4</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>kea-dhcp6</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>kea-dhcp-ddns</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>kea-admin</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>keactrl</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>perfdhcp</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citerefentry>
+ <refentrytitle>kea-lfc</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>,
+
+ <citetitle>Kea Administrator's Guide</citetitle>.
+
+ </para>
+ </refsect1>
+
-</refentry><!--
- - Local variables:
- - mode: sgml
- - End:
--->
++</refentry>
- <!-- Converted by db4-upgrade version 1.0 -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
- [<!ENTITY mdash "—">]>
-<!--
- - Copyright (C) 2012-2016 Internet Systems Consortium, Inc. ("ISC")
- -
- - This Source Code Form is subject to the terms of the Mozilla Public
- - License, v. 2.0. If a copy of the MPL was not distributed with this
- - file, You can obtain one at http://mozilla.org/MPL/2.0/.
--->
++<!-- Converted by db4-upgrade version 1.1 -->
+<refentry xmlns="http://docbook.org/ns/docbook" version="5.0">
-<refentry>
-
- <refentryinfo>
- <date>July 1, 2014</date>
- </refentryinfo>
+ <info>
+ <date>2014-07-01</date>
+ </info>
<refmeta>
<refentrytitle>kea-sockcreator</refentrytitle>
removed. The socket creator server binary was renamed to
kea-sockcreator in July 2014.
</para>
- </refsection>
+ </refsect1>
-</refentry><!--
- - Local variables:
- - mode: sgml
- - End:
--->
+</refentry>
projects / thirdparty / kea.git / commitdiff
