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

Merge branch 'isc-master' into cassandra-host-data-source

Browse Source
This commit is contained in:
Andrei Pavel
2017-08-17 20:30:41 +03:00
parent 42de10a2b4 33dbf01602
commit e37a6c29bb
884 changed files with 116203 additions and 20175 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/guide/Makefile.am
View File

@@ -8,14 +8,14 @@ dist_html_DATA = $(HTMLDOCS) kea-guide.css kea-logo-100x70.png
DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml
DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml logging.xml
DOCBOOK += ddns.xml hooks.xml libdhcp.xml lfc.xml stats.xml ctrl-channel.xml faq.xml
DOCBOOK += classify.xml
DOCBOOK += classify.xml shell.xml agent.xml
EXTRA_DIST = $(DOCBOOK)
DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml
kea-messages.xml:
$(top_srcdir)/tools/system_messages -o $@ \
$(top_builddir)/tools/system_messages -o $@ \
`find $(top_srcdir) -name "*.mes" -print`
# This is not a "man" manual, but reuse this for now for docbook.
@@ -58,7 +58,7 @@ CLEANFILES = kea-guide.pdf kea-messages.pdf
DBLATEX_FLAGS = --xslt-opts=--path --xslt-opts=$(abs_top_builddir)/doc \
-P doc.collab.show=0 -P latex.output.revhistory=0 \
-P term.breakline=1 -P filename.as.url=0 \
-P imagedata.default.scale="maxwidth=50px,maxheigth=35px"
-P imagedata.default.scale="maxwidth=50px,maxheight=35px"
pdf: kea-guide.pdf kea-messages.pdf

69
doc/guide/admin.xml
View File

@@ -18,7 +18,7 @@
For example, Kea currently only stores lease information
and host reservations. Future versions of Kea will store
additional data such as subnet definitions: the database
structure will need to be updated to accomdate the extra
structure will need to be updated to accommodate the extra
information.
</para>
@@ -617,7 +617,7 @@ $ <userinput>kea-admin lease-upgrade pgsql -u <replaceable>database-user</replac
<orderedlist>
<listitem>
<para>
Export CQLSH_HOST environemnt variable:
Export CQLSH_HOST environment variable:
<screen>
$ <userinput>export CQLSH_HOST=localhost</userinput>
</screen>
@@ -716,7 +716,7 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea
read-only mode.
Sections <xref linkend="read-only-database-configuration4"/> and
<xref linkend="read-only-database-configuration6"/> describe when
such configuration may be reqired and how to configure Kea to
such configuration may be required and how to configure Kea to
operate using a read-only host database.
</para>
</section>
@@ -724,20 +724,55 @@ $ <userinput>kea-admin lease-upgrade cql -n <replaceable>database-name</replacea
<section>
<title>Limitations Related to the use of SQL Databases</title>
<para>
The lease expiration time is stored in the SQL database for each lease
as a timestamp value. Kea developers observed that MySQL database doesn't
accept timestamps beyond 2147483647 seconds (maximum signed 32-bit number)
from the beginning of the epoch. At the same time, some versions of PostgreSQL
do accept greater values but the value is altered when it is read back.
For this reason the lease database backends put the restriction for the
maximum timestamp to be stored in the database, which is equal to the
maximum signed 32-bit number. This effectively means that the current
Kea version can't store the leases which expiration time is later than
2147483647 seconds since the beginning of the epoch (around year 2038).
This will be fixed when the database support for longer timestamps
is available.
</para>
<section>
<title>Year 2038 issue</title>
<para>
The lease expiration time is stored in the SQL database for each lease
as a timestamp value. Kea developers observed that MySQL database doesn't
accept timestamps beyond 2147483647 seconds (maximum signed 32-bit number)
from the beginning of the epoch. At the same time, some versions of PostgreSQL
do accept greater values but the value is altered when it is read back.
For this reason the lease database backends put the restriction for the
maximum timestamp to be stored in the database, which is equal to the
maximum signed 32-bit number. This effectively means that the current
Kea version can't store the leases which expiration time is later than
2147483647 seconds since the beginning of the epoch (around year 2038).
This will be fixed when the database support for longer timestamps
is available.
</para>
</section>
<section>
<title>Server Terminates when Database Connection is Lost</title>
<para>
If Kea is configured to use an external database it opens a connection
to the database and requires that this connection is not interrupted.
When the database connection breaks, e.g. as a result of SQL server
restart, DHCP servers will terminate indicating a fatal error. In such
a case, the system administrator is required to start the database and
then "manually" start Kea to resume the service.
</para>
<para>
Although the engineering team is planning to implement some form of
reconnect mechanism in the future, this will mostly be applicable in
cases when the database service is restarted and the connection
down time is relatively short. The DHCP server can't provide its
service as long as the database is down, because it can't store
leases being assigned to the clients. The server will have to
reject any DHCP messages as long as the connection is down and
terminate if the reconnection attempt fails multiple times.
</para>
<para>
Because the database connection is critical for the operation of the
DHCP service, the current behavior is to terminate when that
connection is unavailable to indicate that server is in inconsistent
state and can't serve clients.
</para>
</section>
</section>
</section> <!-- End of Database sections -->

305
doc/guide/agent.xml Normal file
View File

@@ -0,0 +1,305 @@
<?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 "&#x2017;" >
]>
<chapter id="kea-ctrl-agent">
<title>Kea Control Agent</title>
<section 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>.
</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">
<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">
<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">
<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">
<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">
<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>

11
doc/guide/classify.xml
View File

@@ -484,9 +484,12 @@
"relay6[nest]" allows access to the encapsulations used by any DHCPv6
relays that forwarded the packet. The "nest" level specifies the relay
from which to extract the information, with a value of 0 indicating
the relay closest to the DHCPv6 server. If the requested encapsulation
doesn't exist an empty string "" is returned. This expression is
allowed in DHCPv6 only.
the relay closest to the DHCPv6 server. Negative values allow to
specify relays counted from the DHCPv6 client, -1 indicating the
relay closest to the client. In general negative "nest" level is
the same as the number of relays + "nest" level.
If the requested encapsulation doesn't exist an empty string ""
is returned. This expression is allowed in DHCPv6 only.
</para></listitem>
<listitem><para>
@@ -820,7 +823,7 @@ concatenation of the strings</entry></row>
</para>
<para>
To enable the debug statements in the classifciaton system you will
To enable the debug statements in the classification system you will
need to set the severity to "DEBUG" and the debug level to at least 55.
The specific loggers are "kea-dhcp4.eval" and "kea-dhcp6.eval".
</para>

18
doc/guide/config.xml
View File

@@ -37,27 +37,23 @@
<itemizedlist>
<listitem>
<simpara>shell comments: any text after the hash (#)
character is ignored. Dhcp6 allows # in any column, while
Dhcp4 and Ddns require hash to be in the first
column.</simpara>
character is ignored. Both Dhcp4 and Dhcp6 allow # in any column,
while Ddns requires hash to be in the first column.</simpara>
</listitem>
<listitem>
<simpara>C comments: any text after the double slashes (//)
character is ignored. We're in a process of
migrating the configuation parsers and currently only Dhcp6
supports this feature.</simpara>
character is ignored. Both Dhcp4 and Dhcp6 supports this
feature.</simpara>
</listitem>
<listitem>
<simpara>Multiline comments: any text between /* and */ is
ignored. This commenting can span multiple lines. We're in a
process of migrating the configuation parsers and currently
only Dhcp6 supports this feature.</simpara>
ignored. This commenting can span multiple lines. Both Dhcp4 and
Dhcp6 supports this feature.</simpara>
</listitem>
<listitem>
<simpara>File inclusion: JSON files can include other JSON
files. This can be done by using &lt;?include
"file.json"?&gt;. We're in a process of migrating the
configuation parsers and currently only Dhcp6 supports this
"file.json"?&gt;. Both Dhcp4 and Dhcp6 supports this
feature.</simpara>
</listitem>
</itemizedlist>

489
doc/guide/ctrl-channel.xml
View File

@@ -24,16 +24,56 @@
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
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>
<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">
<title>Data Syntax</title>
<para>Communication over the control channel is conducted using JSON
@@ -44,29 +84,103 @@
<screen>
{
"command": "foo",
"service": [ "dhcp4" ]
"arguments": {
"param1": "value1",
"param2": "value2",
...
"param1": "value1",
"param2": "value2",
...
}
}
</screen>
The same command sent over the RESTful interface to the CA will have
the following structure.
<screen>
POST / HTTP/1.1\r\n
Content-Type: application/json\r\n
Content-Length: 147\r\n\r\n
{
"command": "foo",
"service": [ "dhcp4" ]
"arguments": {
"param1": "value1",
"param2": "value2",
...
}
}
</screen>
<command>command</command> is the name of command to execute and
is mandatory. <command>arguments</command> is a map of parameters
required to carry out the given command. The exact content and
format of the map is command specific.</para>
<para>The server will process the incoming command and then send a
response of the form:
<para>
<command>service</command> is a list of the servers at which the control
command is targetted. In the example above, the control command is
targetted at the DHCPv4 server. In most cases, the CA will simply forward this
command to the DHCPv4 server for processing via unix domain socket.
Sometimes, the command including a service value may also be processed by the
CA, if the CA is running a hooks library which handles such command for the
given server. As an example, the hooks library attached to the CA
may perform some operations on the database (like adding host reservations,
modifying leases etc.). An advantage of performing DHCPv4 specific
administrative operations in the CA rather than forwarding it to
the DHCPv4 server is the ability to perform these operations without
disrupting the DHCPv4 service (DHCPv4 server doesn't have to stop
processing DHCP messages to apply changes to the database). Nevertheless,
these situations are rather rare and, in most cases, when the
<command>service</command> parameter contains a name of the service
the commands are simply forwarded by the CA. The forwarded command
includes the <command>service</command> parameter but this parameter
is ignored by the receiving server. This parameter is only meaningful
to the CA.
</para>
<para>
If the command received by the CA does not include a <command>service</command>
parameter or this list is empty, the CA will simply process this message
on its own. For example, the <command>config-get</command> command which
doesn't include service parameter will return Control Agent's own
configuration. The <command>config-get</command> including a service
value "dhcp4" will be forwarded to the DHCPv4 server and will return
DHCPv4 server's configuration and so on.
</para>
<para>
The following list contains a mapping of the values carried within the
<command>service</command> parameter to the servers to which the commands
are forwarded:
<itemizedlist>
<listitem>
<simpara><command>dhcp4</command> - the command is forwarded to the
<command>kea-dhcp4</command> server,</simpara>
</listitem>
<listitem>
<simpara><command>dhcp6</command> - the command is forwarded to the
<command>kea-dhcp6</command> server,</simpara>
</listitem>
<listitem>
<simpara><command>d2</command> - the command is forwarded to the
<command>kea-d2</command> server.</simpara>
</listitem>
</itemizedlist>
</para>
<para>The server processing the incoming command will send a response of
the form:
<screen>
{
"result": 0|1,
"text": "textual description",
"arguments": {
"argument1": "value1",
"argument2": "value2",
...
"argument1": "value1",
"argument2": "value2",
...
}
}
</screen>
@@ -79,23 +193,29 @@
<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 id="ctrl-channel-client">
<title>Using the Control Channel</title>
<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>
<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 <ulink url="http://www.dest-unreach.org/socat/">socat
homepage</ulink>, 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>
@@ -108,15 +228,175 @@ will be sent to Kea and the responses received from Kea printed to standard outp
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 id="commands-common">
<title>Commands Supported by Both the DHCPv4 and DHCPv6 Servers</title>
<section 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">
<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">
<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">
<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": {
"&#60;server&#62;": {
},
"Logging": {
}
}
}
</screen>
<para>
where &#60;server&#62; 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 (&#60;string&#62;:16:26)" }
</screen>
</para>
</section> <!-- end of command-config-test -->
<section 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 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>
@@ -140,13 +420,36 @@ will be sent to Kea and the responses received from Kea printed to standard outp
about the processing of expired leases (leases reclamation).</para>
</section>
<section 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">
<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",
@@ -155,33 +458,139 @@ will be sent to Kea and the responses received from Kea printed to standard outp
</screen>
</para>
<para>
The server will respond with a list of all supported commands. The
arguments element will be a list of strings. Each string will convey
one supported command.
The server will respond with a list of all supported commands. The
arguments element will be a list of strings. Each string will convey
one supported command.
</para>
</section> <!-- end of command-list-commands -->
<section id="command-config-set">
<title>config-set</title>
<para>
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": "config-set",
"arguments": {
"&#60;server&#62;": {
},
"Logging": {
}
}
}
</screen>
<para>
where &#60;server&#62; 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>
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 (&#60;string&#62;:16:26)" }
</screen>
</para>
</section> <!-- end of command-config-set -->
<section 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:
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",
"arguments": { }
"command": "shutdown"
}
</screen>
</para>
<para>
The server will respond with a confirmation that the shutdown procedure
has been initiated.
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">
<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 -->
<section 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>

1179
doc/guide/ddns.xml
View File

File diff suppressed because it is too large Load Diff

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

@@ -42,6 +42,18 @@
ports other than the standard ones will not be able to
handle regular DHCPv4 queries.</simpara>
</listitem>
<listitem>
<simpara>
<command>-t <replaceable>file</replaceable></command> -
specifies the configuration file to be tested. Kea-dhcp4
will attempt to load it, and will conduct sanity
checks. Note that certain checks are possible only while
running the actual server. The actual status is reported
with exit code (0 = configuration looks ok, 1 = error
encountered). Kea will print out log messages to standard
output and error to standard error when testing
configuration.</simpara>
</listitem>
<listitem>
<simpara>
<command>-v</command> - prints out the Kea version and exits.
@@ -183,7 +195,7 @@ opening curly bracket (or brace). Each configuration consists of
one or more objects. In this specific example, we have only one
object, called Dhcp4. This is a simplified configuration, as usually
there will be additional objects, like <command>Logging</command> or
<command>DhcpDns</command>, but we omit them now for clarity. The Dhcp4
<command>DhcpDdns</command>, but we omit them now for clarity. The Dhcp4
configuration starts with the <command>"Dhcp4": {</command> line
and ends with the corresponding closing brace (in the above example,
the brace after the last comment). Everything defined between those
@@ -459,6 +471,11 @@ be followed by a comma and another object definition.</para>
For Cassandra:
<screen>
"Dhcp4": { "lease-database": { <userinput>"contact_points": ""</userinput>, ... }, ... }
</screen>
Should the database use a port different than default, it may be
specified as well:
<screen>
"Dhcp4": { "lease-database": { <userinput>"port" : 12345</userinput>, ... }, ... }
</screen>
Should the database be located on a different system, you may need to specify a longer interval
for the connection timeout:
@@ -468,6 +485,17 @@ be followed by a comma and another object definition.</para>
The default value of five seconds should be more than adequate for local connections.
If a timeout is given though, it should be an integer greater than zero.
</para>
<para>
Note that host parameter is used by MySQL and PostgreSQL
backends. Cassandra has a concept of contact points that could be
used to contact the cluster, instead of a single IP or
hostname. It takes a list of comma separated IP addresses. This may be specified as:
<screen>
"Dhcp4": { "lease-database": { <userinput>"contact-points" : "192.0.2.1,192.0.2.2"</userinput>, ... }, ... }
</screen>
</para>
<para>Finally, the credentials of the account under which the server will
access the database should be set:
<screen>
@@ -526,6 +554,12 @@ If a timeout is given though, it should be an integer greater than zero.
<screen>
"Dhcp4": { "hosts-database": { <userinput>"host" : ""</userinput>, ... }, ... }
</screen>
Should the database use a port different than default, it may be
specified as well:
<screen>
"Dhcp4": { "hosts-database": { <userinput>"port" : 12345</userinput>, ... }, ... }
</screen>
</para>
<para>Finally, the credentials of the account under which the server will
access the database should be set:
@@ -696,6 +730,23 @@ temporarily override a list of interface names and listen on all 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 id="dhcpinform-unicast-issues">
@@ -934,22 +985,86 @@ temporarily override a list of interface names and listen on all interfaces.
...
]
}
</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
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.
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>
@@ -1018,15 +1133,86 @@ temporarily override a list of interface names and listen on all interfaces.
</screen>
</para>
<para>
In some cases it is useful to associate some options with an
address pool from which a client is assigned a lease. Pool
specific option values override subnet specific and global
option values. The server's administrator must not try to
prioritize assignment of pool specific options by trying to
order pools declarations in the server configuration. Future
Kea releases may change the order in which options are
assigned from the pools without any notice.
</para>
<para>
The following configuration snippet demonstrates how to specify the
DNS servers option, which will be assigned to a client only if the
client obtains an address from the given pool:
<screen>
"Dhcp4": {
"subnet4": [
{
"pools": [
{
"pool": "192.0.2.1 - 192.0.2.200",
<userinput>"option-data": [
{
"name": "domain-name-servers",
"data": "192.0.2.3"
},
...
]</userinput>,
...
},
...
],
...
},
...
],
...
}
</screen>
</para>
<para>
The currently supported standard DHCPv4 options are
listed in <xref linkend="dhcp4-std-options-list"/>
and <xref linkend="dhcp4-std-options-list-part2"/>.
listed in <xref linkend="dhcp4-std-options-list"/>.
The "Name" and "Code"
are the values that should be used as a name in the option-data
structures. "Type" designates the format of the data: the meanings of
the various types is given in <xref linkend="dhcp-types"/>.
</para>
<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 &quot;foo,bar&quot; 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
@@ -1112,32 +1298,6 @@ This rather belong to the DDNS configuration
<row><entry>default-tcp-ttl</entry><entry>37</entry><entry>uint8</entry><entry>false</entry><entry>false</entry></row>
<row><entry>tcp-keepalive-interval</entry><entry>38</entry><entry>uint32</entry><entry>false</entry><entry>false</entry></row>
<row><entry>tcp-keepalive-garbage</entry><entry>39</entry><entry>boolean</entry><entry>false</entry><entry>false</entry></row>
</tbody>
</tgroup>
</table>
</para>
<para>
<table frame="all" id="dhcp4-std-options-list-part2">
<title>List of standard DHCPv4 options (continued)</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'/>
<thead>
<row>
<entry>Name</entry>
<entry>Code</entry>
<entry>Type</entry>
<entry>Array?</entry>
<entry>Returned if not requested?</entry>
</row>
</thead>
<tbody>
<row><entry>nis-domain</entry><entry>40</entry><entry>string</entry><entry>false</entry><entry>false</entry></row>
<row><entry>nis-servers</entry><entry>41</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
<row><entry>ntp-servers</entry><entry>42</entry><entry>ipv4-address</entry><entry>true</entry><entry>false</entry></row>
@@ -1203,7 +1363,7 @@ It is merely echoed by the server
<row><entry>client-ndi</entry><entry>94</entry><entry>record (uint8, uint8, uint8)</entry><entry>false</entry><entry>false</entry></row>
<row><entry>uuid-guid</entry><entry>97</entry><entry>record (uint8, binary)</entry><entry>false</entry><entry>false</entry></row>
<row><entry>subnet-selection</entry><entry>118</entry><entry>ipv4-address</entry><entry>false</entry><entry>false</entry></row>
<row><entry>domain-search</entry><entry>119</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
<row><entry>domain-search</entry><entry>119</entry><entry>fqdn</entry><entry>true</entry><entry>false</entry></row>
<row><entry>vivco-suboptions</entry><entry>124</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
<row><entry>vivso-suboptions</entry><entry>125</entry><entry>binary</entry><entry>false</entry><entry>false</entry></row>
</tbody>
@@ -1231,9 +1391,13 @@ It is merely echoed by the server
<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>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>
<row><entry>int8</entry><entry>8 bit signed integer with allowed values -128 to 127</entry></row>
<row><entry>int16</entry><entry>16 bit signed integer with allowed values -32768 to 32767</entry></row>
<row><entry>int32</entry><entry>32 bit signed integer with allowed values -2147483648 to 2147483647</entry></row>
</tbody>
</tgroup>
</table>
@@ -1360,6 +1524,12 @@ It is merely echoed by the server
<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 id="dhcp4-vendor-opts">
@@ -1589,22 +1759,12 @@ It is merely echoed by the server
</listitem>
<listitem>
<simpara><command>csv-format</command> - if this value is not specified
and the definition for the particular option exists, the server will assume
that the option data is specified as a list of comma separated values to be
assigned to individual fields of the DHCP option. If the definition
does not exist for this option, the server will assume that the data
parameter contains the option payload in the binary format (represented
as a string of hexadecimal digits). Note that not specifying this
parameter doesn't imply that it defaults to a fixed value, but
the configuration data interpretation also depends on the presence
of the option definition. An administrator must be aware if the
definition for the particular option exists when this parameter
is not specified. It is generally recommended to not specify this
parameter only for the options for which the definition exists, e.g.
standard options. Setting <command>csv-format</command> to an explicit
value will cause the server to strictly check the format of the option
data specified.
<simpara><command>csv-format</command> - if this value is not
specified the server will assume that the option data is specified as
a list of comma separated values to be assigned to individual fields
of the DHCP option. This behavior has changed in Kea 1.2. Older
versions used additional logic to determine whether the csv-format
should be true or false. That is no longer the case.
</simpara>
</listitem>
</itemizedlist>
@@ -2195,9 +2355,10 @@ It is merely echoed by the server
<note>
Note that formerly, this parameter was a boolean and permitted only values
of <command>true</command> and <command>false</command>. Boolean values
will still be accepted but may eventually be deprecated. A value of
<command>true</command> equates to <command>when-present</command>,
<command>false</command> equates to <command>never</command>.
have been deprecated and are no longer accepted. If you are currently using
booleans, you must replace them with the desired mode name. A value of
<command>true</command> maps to <command>"when-present"</command>, while
<command>false</command> maps to <command>"never"</command>.
</note>
For example, To instruct kea-dhcp4 to always generate the FQDN for a
@@ -2431,7 +2592,7 @@ It is merely echoed by the server
indicates that the server will use the "client identifier" for lease
lookups and "chaddr" if the first lookup returns no results. The
<command>false</command> means that the server will only
use the "chaddr" to search for client"s lease. Whether the DHCID for
use the "chaddr" to search for client's lease. Whether the DHCID for
DNS updates is generated from the "client identifier" or "chaddr" is
controlled through the same parameter accordingly.</para>
@@ -2508,7 +2669,7 @@ It is merely echoed by the server
With DHCPv4-over-DHCPv6 the DHCPv4 server does not have access
to several of the identifiers it would normally use to select a
subnet. In order to address this issue three new configuration
entires have been added. The presence of any of these allows the
entries have been added. The presence of any of these allows the
subnet to be used with DHCPv4-over-DHCPv6. These entries are:
<itemizedlist>
<listitem>
@@ -2649,12 +2810,12 @@ It is merely echoed by the server
0a:0b:0c:0d:0e:0f. (Note that if you plan to do DNS updates, it
is strongly recommended for the hostnames to be unique.) The third
example reserves address 192.0.3.203 to a client whose request
would be relayed by a relay agent that inserts a circuid-it option
would be relayed by a relay agent that inserts a circuit-it option
with the value 'charter950'. The fourth entry reserves address
192.0.2.204 for a client that uses a client identifier with value
01:11:22:33:44:55:66.</para>
<para>The above example is used for ilustrational purposes only
<para>The above example is used for illustrational purposes only
and in actual deployments it is recommended to use as few types as possible
(preferably just one). See <xref linkend="reservations4-tuning"/> for a detailed
discussion of this point.</para>
@@ -2980,7 +3141,7 @@ It is merely echoed by the server
</screen>
<para>Static class assignments, as shown above, can be used in conjuction
<para>Static class assignments, as shown above, can be used in conjunction
with classification using expressions.</para>
</section>
@@ -3214,6 +3375,9 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
</screen>
</para>
<para>If "relay" is specified, the "ip-address" parameter within
it is mandatory.</para>
</section>
<section id="dhcp4-srv-example-client-class-relay">
@@ -3561,7 +3725,25 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
separately. This statistic is reset during reconfiguration event.
</entry>
</row>
<row>
<entry>reclaimed-leases</entry>
<entry>integer</entry>
<entry>This statistic is the number of expired leases that have
been reclaimed since server startup. It is incremented each time
an expired lease is reclaimed and is reset when the server is
reconfigured.
</entry>
</row>
<row>
<entry>subnet[id].reclaimed-leases</entry>
<entry>integer</entry>
<entry>This statistic is the number of expired leases associated
with a given subnet (<emphasis>id</emphasis> is the subnet-id)
that have been reclaimed since server startup. It is incremented
each time an expired lease is reclaimed and is reset when the
server is reconfigured.
</entry>
</row>
<row>
<entry>declined-addresses</entry>
<entry>integer</entry>
@@ -3660,17 +3842,36 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
<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 id="dhcp4-std">

487
doc/guide/dhcp6-srv.xml
View File

@@ -42,6 +42,18 @@
ports other than the standard ones will not be able to
handle regular DHCPv6 queries.</simpara>
</listitem>
<listitem>
<simpara>
<command>-t <replaceable>file</replaceable></command> -
specifies the configuration file to be tested. Kea-dhcp6
will attempt to load it, and will conduct sanity
checks. Note that certain checks are possible only while
running the actual server. The actual status is reported
with exit code (0 = configuration looks ok, 1 = error
encountered). Kea will print out log messages to standard
output and error to standard error when testing
configuration.</simpara>
</listitem>
<listitem>
<simpara>
<command>-v</command> - prints out the Kea version and exits.
@@ -184,7 +196,7 @@ opening curly bracket (or brace). Each configuration consists of
one or more objects. In this specific example, we have only one
object, called Dhcp6. This is a simplified configuration, as usually
there will be additional objects, like <command>Logging</command> or
<command>DhcpDns</command>, but we omit them now for clarity. The Dhcp6
<command>DhcpDdns</command>, but we omit them now for clarity. The Dhcp6
configuration starts with the <command>"Dhcp6": {</command> line
and ends with the corresponding closing brace (in the above example,
the brace after the last comment). Everything defined between those
@@ -454,6 +466,11 @@ be followed by a comma and another object definition.</para>
For Cassandra:
<screen>
"Dhcp6": { "lease-database": { <userinput>"contact_points": ""</userinput>, ... }, ... }
</screen>
Should the database use a port different than default, it may be
specified as well:
<screen>
"Dhcp4": { "lease-database": { <userinput>"port" : 12345</userinput>, ... }, ... }
</screen>
Should the database be located on a different system, you may need to specify a longer interval
for the connection timeout:
@@ -463,6 +480,17 @@ be followed by a comma and another object definition.</para>
The default value of five seconds should be more than adequate for local connections.
If a timeout is given though, it should be an integer greater than zero.
</para>
<para>
Note that host parameter is used by MySQL and PostgreSQL
backends. Cassandra has a concept of contact points that could be
used to contact the cluster, instead of a single IP or
hostname. It takes a list of comma separated IP addresses. This may be specified as:
<screen>
"Dhcp4": { "lease-database": { <userinput>"contact-points" : "192.0.2.1,192.0.2.2"</userinput>, ... }, ... }
</screen>
</para>
<para>Finally, the credentials of the account under which the server will
access the database should be set:
<screen>
@@ -521,6 +549,9 @@ If a timeout is given though, it should be an integer greater than zero.
the DHCPv6 server. In this case, set the value to the empty string:
<screen>
"Dhcp6": { "hosts-database": { <userinput>"host" : ""</userinput>, ... }, ... }
</screen>
<screen>
"Dhcp4": { "hosts-database": { <userinput>"port" : 12345</userinput>, ... }, ... }
</screen>
</para>
<para>Finally, the credentials of the account under which the server will
@@ -605,6 +636,24 @@ for MySQL and PostgreSQL databases.</para></note>
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 id="ipv6-subnet-id">
@@ -962,9 +1011,73 @@ temporarily override a list of interface names and listen on all interfaces.
</para>
<para>
Most of the parameters in the "option-data" structure are optional and
can be omitted in some circumstances as discussed in the
<xref linkend="dhcp6-option-data-defaults"/>.
Most of the parameters in the "option-data" structure are
optional and can be omitted in some circumstances as discussed
in the <xref linkend="dhcp6-option-data-defaults"/>. Only one
of name or code is required, so you don't need to specify
both. Space has a default value of "dhcp6", so you can skip
this as well if you define a regular (not encapsulated) DHCPv6
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>
"Dhcp6": {
"option-data": [
{
<userinput>"name": "dns-servers",
"data": "2001:db8::cafe, 2001:db8::babe"</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>
"Dhcp6": {
"option-data": [
{
<userinput>"name": "dns-servers",
"data": "2001:db8::cafe, 2001:db8::babe",
"always-send": true</userinput>
},
...
]
}
</screen>
The effect is the same as if the client added the option code in the
Option Request Option (or its equivalent for vendor options) so in:
<screen>
"Dhcp6": {
"option-data": [
{
<userinput>"name": "dns-servers",
"data": "2001:db8::cafe, 2001:db8::babe",
"always-send": true</userinput>
},
...
],
"subnet6": [
{
"subnet": "2001:db8:1::/64",
"option-data": [
{
<userinput>"name": "dns-servers",
"data": "2001:db8:1::cafe, 2001:db8:1::babe"</userinput>
},
...
],
...
},
...
],
...
}
</screen>
The DNS 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>
@@ -1060,6 +1173,37 @@ temporarily override a list of interface names and listen on all interfaces.
which was not assigned by IANA) are listed in
<xref linkend="dhcp6-exp-options-list"/>.
</para>
<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
&quot;EST5EDT4,M3.2.0/02:00,M11.1.0/02:00&quot; 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
@@ -1151,7 +1295,7 @@ temporarily override a list of interface names and listen on all interfaces.
<row><entry>lq-relay-data</entry><entry>47</entry><entry>record (ipv6-address, binary)</entry><entry>false</entry></row>
<row><entry>lq-client-link</entry><entry>48</entry><entry>ipv6-address</entry><entry>true</entry></row>
<row><entry>bootfile-url</entry><entry>59</entry><entry>string</entry><entry>false</entry></row>
<row><entry>bootfile-param</entry><entry>60</entry><entry>binary</entry><entry>false</entry></row>
<row><entry>bootfile-param</entry><entry>60</entry><entry>tuple</entry><entry>true</entry></row>
<row><entry>client-arch-type</entry><entry>61</entry><entry>uint16</entry><entry>true</entry></row>
<row><entry>nii</entry><entry>62</entry><entry>record (uint8, uint8, uint8)</entry><entry>false</entry></row>
<row><entry>aftr-name</entry><entry>64</entry><entry>fqdn</entry><entry>false</entry></row>
@@ -1161,14 +1305,6 @@ temporarily override a list of interface names and listen on all interfaces.
<row><entry>client-linklayer-addr</entry><entry>79</entry><entry>binary</entry><entry>false</entry></row>
<!-- <row><entry>dhcpv4-message</entry><entry>87</entry><entry>binary</entry><entry>false</entry></row> -->
<row><entry>dhcp4o6-server-addr</entry><entry>88</entry><entry>ipv6-address</entry><entry>true</entry></row>
<row><entry>s46-rule</entry><entry>89</entry><entry>record (uint8, uint8, uint8, ipv4-address, ipv6-prefix)</entry><entry>false</entry></row>
<row><entry>s46-br</entry><entry>90</entry><entry>ipv6-address</entry><entry>false</entry></row>
<row><entry>s46-dmr</entry><entry>91</entry><entry>ipv6-prefix</entry><entry>false</entry></row>
<row><entry>s46-v4v6bind</entry><entry>92</entry><entry>record (ipv4-address, ipv6-prefix)</entry><entry>false</entry></row>
<row><entry>s46-portparams</entry><entry>93</entry><entry>record (uint8, psid)</entry><entry>false</entry></row>
<row><entry>s46-cont-mape</entry><entry>94</entry><entry>empty</entry><entry>false</entry></row>
<row><entry>s46-cont-mapt</entry><entry>95</entry><entry>empty</entry><entry>false</entry></row>
<row><entry>s46-cont-lw</entry><entry>96</entry><entry>empty</entry><entry>false</entry></row>
</tbody>
</tgroup>
</table>
@@ -1196,187 +1332,6 @@ temporarily override a list of interface names and listen on all interfaces.
</para>
</section>
<section id="s46-options">
<title>Common Softwire46 Options</title>
<para>
Softwire46 options are involved in IPv4 over IPv6 provisioning by
means of tunneling or translation as specified in the
<ulink url="http://tools.ietf.org/html/rfc7598">RFC 7598</ulink>.
The following sections provide configuration examples of these
options.
</para>
<section id="s46-containers">
<title>Softwire46 Container Options</title>
<para>
S46 container options group rules and optional port parameters
for a specified domain. There are three container options specified
in the "dhcp6" (top level) option space: MAP-E Container option,
MAP-T Container option and S46 Lieghtweight 4over6 Container option.
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>
<title>S46 Rule Option</title>
<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>
<title>S46 BR Option</title>
<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>
<title>S46 DMR Option</title>
<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>
<title>S46 IPv4/IPv6 Address Binding option.</title>
<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>
<title>S46 Port Parameters</title>
<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 id="dhcp6-custom-options">
<title>Custom DHCPv6 Options</title>
<para>It is possible to define options in addition to the standard ones.
@@ -1730,22 +1685,12 @@ should include options from the isc option space:
</listitem>
<listitem>
<simpara><command>csv-format</command> - if this value is not specified
and the definition for the particular option exists, the server will assume
that the option data is specified as a list of comma separated values to be
assigned to individual fields of the DHCP option. If the definition
does not exist for this option, the server will assume that the data
parameter contains the option payload in the binary format (represented
as a string of hexadecimal digits). Note that not specifying this
parameter doesn't imply that it defaults to a fixed value, but
the configuration data interpretation also depends on the presence
of the option definition. An administrator must be aware if the
definition for the particular option exists when this parameter
is not specified. It is generally recommended to not specify this
parameter only for the options for which the definition exists, e.g.
standard options. Setting <command>csv-format</command> to an explicit
value will cause the server to strictly check the format of the option
data specified.
<simpara><command>csv-format</command> - if this value is not
specified the server will assume that the option data is specified as
a list of comma separated values to be assigned to individual fields
of the DHCP option. This behavior has changed in Kea 1.2. Older
versions used additional logic to determine whether the csv-format
should be true or false. That is no longer the case.
</simpara>
</listitem>
</itemizedlist>
@@ -2390,9 +2335,10 @@ should include options from the isc option space:
<note>
Note that formerly, this parameter was a boolean and permitted only values
of <command>true</command> and <command>false</command>. Boolean values
will still be accepted but may eventually be deprecated. A value of
<command>true</command> equates to <command>when-present</command>,
<command>false</command> equates to <command>never</command>.
have been deprecated and are no longer accepted. If you are currently using
booleans, you must replace them with the desired mode name. A value of
<command>true</command> maps to <command>"when-present"</command>, while
<command>false</command> maps to <command>"never"</command>.
</note>
For example, To instruct kea-dhcp6 to always generate the FQDN for a
@@ -2616,7 +2562,7 @@ should include options from the isc option space:
},
{
"hw-address": "00:01:02:03:04:05",
"ip-addresses": [ "2001:db8:1::101, 2001:db8:1::102" ]
"ip-addresses": [ "2001:db8:1::101", "2001:db8:1::102" ]
},
{
"duid": "01:02:03:04:05:06:07:08:09:0A",
@@ -2847,7 +2793,7 @@ should include options from the isc option space:
<userinput>"option-data": [
{
"name": "vendor-opts",
"data": 4491"
"data": 4491
},
{
"name": "tftp-servers",
@@ -2912,7 +2858,7 @@ should include options from the isc option space:
}
</screen>
<para>Static class assignments, as shown above, can be used in conjuction
<para>Static class assignments, as shown above, can be used in conjunction
with classification using expressions.</para>
</section>
@@ -3422,6 +3368,9 @@ If not specified, the default value is:
</screen>
</para>
<para>If "relay" is specified, the "ip-address" parameter within
it is mandatory.</para>
</section>
<section id="dhcp6-client-class-relay">
@@ -3512,7 +3461,8 @@ If not specified, the default value is:
When not specified, a special value of "any" is used, which
instructs the server to attempt to use all the methods in sequence and use
value returned by the first one that succeeds.</para>
value returned by the first one that succeeds. If specified, it
has to have at least one value.</para>
<para>Supported methods are:
<itemizedlist>
@@ -3846,7 +3796,7 @@ If not specified, the default value is:
statistic is expected to grow if there are devices
that are using DHCPv4-over-DHCPv6. DHCPv4-QUERY
messages are used by DHCPv4 clients on an IPv6 only
line which encapsulatesi the requests over DHCPv6.
line which encapsulates the requests over DHCPv6.
</entry>
</row>
@@ -3973,6 +3923,27 @@ If not specified, the default value is:
</entry>
</row>
<row>
<entry>reclaimed-leases</entry>
<entry>integer</entry>
<entry> This statistic is the number of expired leases that have been
reclaimed since server startup. It is incremented each time an expired
lease is reclaimed (it counts both NA and PD reclamations) and is reset
when the server is reconfigured.
</entry>
</row>
<row>
<entry>subnet[id].reclaimed-leases</entry>
<entry>integer</entry>
<entry>This statistic is the number of expired leases associated with
a given subnet (<emphasis>"id"</emphasis> is the subnet-id) that have
been reclaimed since server startup. It is incremented each time an expired
lease is reclaimed (it counts both NA and PD reclamations) and is reset
when the server is reconfigured.
</entry>
</row>
<row>
<entry>declined-addresses</entry>
<entry>integer</entry>
@@ -4074,14 +4045,32 @@ If not specified, the default value is:
See the Control Channel section in the Kea Developer's Guide for more details.
</para>
<para>The DHCPv6 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>
<para>The DHCPv6 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>
</section>
<section>
@@ -4094,20 +4083,18 @@ If not specified, the default value is:
different for each pool.
</para>
<para>
Let's consider a lightweight 4over6 deployment as an example. It is an
IPv6 transition technology that allows mapping IPv6 prefix into full
or parts of IPv4 addresses. In DHCP context, these are certain
parameters that are supposed to be delivered to clients in form of
additional options. Values of those options are correlated to
delegated prefixes, so it is reasonable to keep those parameters
together with the PD pool. On the other hand, lightweight 4over6 is
not a commonly used feature, so it is not a part of the base Kea
code. The solution to this problem is to use user context. For each PD
pool that is expected to be used for lightweight 4over6, user context
with extra parameters is defined. Those extra parameters will be used
by hook library that would be loaded only when dynamic calculation of
the lightweight 4over6 option is actually needed. An example
configuration looks as follows:
Let's consider an example where certain parameters are supposed
to be delivered to clients in form of additional options,
and the values of those options are correlated to delegated
prefixes. It seems reasonable to keep those parameters with
the the definition of the PD pool. On the other hand, this
functionality is is not part of the base Kea code so Kea will
not understand any hook-specific keywords in that definition.
The solution to this problem is to use user context. For
each PD pool that is expected to be used with this feature,
a "user context" is defined. This is a structure that holds the
parameters used by the hook library when it is loaded.
An example configuration could look as follows:
<screen>
"Dhcp4": {
"subnet6": [ {
@@ -4117,10 +4104,9 @@ If not specified, the default value is:
"prefix-len": 56,
"delegated-len": 64,
<userinput>"user-context": {
"lw4over6-sharing-ratio": 64,
"lw4over6-v4-pool": "192.0.2.0/24",
"lw4over6-sysports-exclude": true,
"lw4over6-bind-prefix-len": 56
"threshold-percent": 85,
"v4-network": "192.168.0.0/16",
"v4-overflow": "10.0.0.0/16"
}</userinput>
} ],
"subnet": "2001:db8::/32"
@@ -4130,9 +4116,9 @@ If not specified, the default value is:
</para>
<para>
It should be noted that Kea will not use any information in the user
context, but will simply store and make it available to the hook
libraries. It is up to the hook library to extract that information
Kea does not interpret or use the content of the user context:
it just stores it, making it available to the hook
libraries. It is up to each hook library to extract the information
and make use of it.
</para>
<para>
@@ -4213,13 +4199,6 @@ If not specified, the default value is:
7550</ulink>: 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>,
<ulink url="http://tools.ietf.org/html/rfc7598">RFC
7598</ulink>: All options specified in this specification are
supported by the DHCPv6 server.</simpara>
</listitem>
</itemizedlist>
</section>

1473
doc/guide/hooks.xml
View File

File diff suppressed because it is too large Load Diff

2
doc/guide/intro.xml
View File

@@ -31,7 +31,7 @@
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,
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.

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

@@ -7,7 +7,7 @@
]>
<!--
- Copyright (C) 2010-2016 Internet Systems Consortium, Inc. ("ISC")
- 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
@@ -32,7 +32,7 @@
&__VERSION__;.</releaseinfo>
<copyright>
<year>2010-2016</year><holder>Internet Systems Consortium, Inc.</holder>
<year>2010-2017</year><holder>Internet Systems Consortium, Inc.</holder>
</copyright>
<abstract>
@@ -64,6 +64,8 @@
<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="dhcp4-srv.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp6-srv.xml" />
@@ -86,6 +88,8 @@
<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="faq.xml" />
<chapter id="acknowledgments">

61
doc/guide/keactrl.xml
View File

@@ -11,9 +11,10 @@
<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>
@@ -66,19 +67,20 @@ keactrl &lt;command&gt; [-c keactrl-config-file] [-s server[,server,..]]
<screen>
# This is a configuration file for keactrl script which controls
# the startup, shutdown, reconfiguration and gathering the status
# of the Kea servers.
# of the Kea's processes.
# prefix holds the location where the Kea is installed.
prefix=/usr/local
prefix=@prefix@
# Location of Kea configuration file.
kea_config_file=${prefix}/etc/kea/kea.conf
kea_config_file=@sysconfdir@/@PACKAGE@/kea.conf
# Location of Kea binaries.
exec_prefix=${prefix}
dhcp4_srv=${exec_prefix}/sbin/kea/kea-dhcp4
dhcp6_srv=${exec_prefix}/sbin/kea/kea-dhcp6
dhcp_ddns_srv=${exec_prefix}/sbin/kea/kea-dhcp-ddns
exec_prefix=@exec_prefix@
dhcp4_srv=@sbindir@/kea-dhcp4
dhcp6_srv=@sbindir@/kea-dhcp6
dhcp_ddns_srv=@sbindir@/kea-dhcp-ddns
ctrl_agent_srv=@sbindir@/kea-ctrl-agent
# Start DHCPv4 server?
dhcp4=yes
@@ -87,7 +89,10 @@ dhcp4=yes
dhcp6=yes
# Start DHCP DDNS server?
dhcp_ddns=yes
dhcp_ddns=no
# Start Control Agent?
ctrl_agent=yes
# Be verbose?
kea_verbose=no
@@ -95,12 +100,13 @@ kea_verbose=no
</para>
<para>
The <parameter>dhcp4</parameter>, <parameter>dhcp6</parameter> and
<parameter>dhcp_ddns</parameter> parameters set to "yes" configure
<command>keactrl</command> to manage (start, reconfigure) all servers,
i.e. <command>kea-dhcp4</command>, <command>kea-dhcp6</command> and
<command>kea-dhcp-ddns</command>. When any of these parameters is set to
"no" the <command>keactrl</command> will ignore
The <parameter>dhcp4</parameter>, <parameter>dhcp6</parameter>,
<parameter>dhcp_ddns</parameter> and <parameter>ctrl_agent</parameter>
parameters set to "yes" configure <command>keactrl</command> to manage
(start, reconfigure) all servers, i.e. <command>kea-dhcp4</command>,
<command>kea-dhcp6</command>, <command>kea-dhcp-ddns</command> and
<command>kea-ctrl-agent</command>. When any of these parameters is set
to "no" the <command>keactrl</command> will ignore
the corresponding server when starting or reconfiguring Kea.
</para>
@@ -110,8 +116,8 @@ kea_verbose=no
should work for most installations. If the default
location needs to be altered for any reason, the paths
specified with the <parameter>dhcp4_srv</parameter>,
<parameter>dhcp6_srv</parameter> and <parameter>dhcp_ddns_srv</parameter>
parameters should be modified.
<parameter>dhcp6_srv</parameter>, <parameter>dhcp_ddns_srv</parameter>
and <parameter>ctrl_agent_srv</parameter> parameters should be modified.
</para>
<para>
@@ -165,6 +171,7 @@ kea_verbose=no
INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea.conf -d
INFO/keactrl: Starting kea-dhcp6 -c /usr/local/etc/kea/kea.conf -d
INFO/keactrl: Starting kea-dhcp-ddns -c /usr/local/etc/kea/kea.conf -d
INFO/keactrl: Starting kea-ctrl-agent -c /usr/local/etc/kea/kea.conf -d
</screen>
</para>
@@ -177,6 +184,7 @@ INFO/keactrl: Starting kea-dhcp-ddns -c /usr/local/etc/kea/kea.conf -d
INFO/keactrl: kea-dhcp4 appears to be running, see: PID 10918, PID file: /usr/local/var/kea/kea.kea-dhcp4.pid.
INFO/keactrl: kea-dhcp6 appears to be running, see: PID 10924, PID file: /usr/local/var/kea/kea.kea-dhcp6.pid.
INFO/keactrl: kea-dhcp-ddns appears to be running, see: PID 10930, PID file: /usr/local/var/kea/kea.kea-dhcp-ddns.pid.
INFO/keactrl: kea-ctrl-agent appears to be running, see: PID 10931, PID file: /usr/local/var/kea/kea.kea-ctrl-agent.pid.
</screen>
During normal shutdowns these PID files are deleted. They may, however,
be left over as remnants following a system crash. It is possible,
@@ -193,6 +201,7 @@ INFO/keactrl: kea-dhcp-ddns appears to be running, see: PID 10930, PID file: /us
INFO/keactrl: Stopping kea-dhcp4...
INFO/keactrl: Stopping kea-dhcp6...
INFO/keactrl: Stopping kea-dhcp-ddns...
INFO/keactrl: Stopping kea-ctrl-agent...
</screen>
Note that the <command>stop</command> will attempt to stop all servers
regardless of whether they are "enabled" in the <filename>keactrl.conf</filename>.
@@ -203,6 +212,7 @@ INFO/keactrl: Stopping kea-dhcp-ddns...
INFO/keactrl: kea-dhcp4 isn't running.
INFO/keactrl: kea-dhcp6 isn't running.
INFO/keactrl: kea-dhcp-ddns isn't running.
INFO/keactrl: kea-ctrl-agent isn't running.
</screen>
</para>
@@ -219,6 +229,7 @@ INFO/keactrl: kea-dhcp-ddns isn't running.
INFO/keactrl: Reloading kea-dhcp4...
INFO/keactrl: Reloading kea-dhcp6...
INFO/keactrl: Reloading kea-dhcp-ddns...
INFO/keactrl: Reloading kea-ctrl-agent...
</screen>
If any of the servers are not running, an informational message
is displayed as in the <command>reload</command> command output below.
@@ -227,6 +238,7 @@ INFO/keactrl: Reloading kea-dhcp-ddns...
INFO/keactrl: kea-dhcp4 isn't running.
INFO/keactrl: kea-dhcp6 isn't running.
INFO/keactrl: kea-dhcp-ddns isn't running.
INFO/keactrl: kea-ctrl-agent isn't running.
</screen>
</para>
@@ -247,6 +259,7 @@ INFO/keactrl: kea-dhcp-ddns isn't running.
DHCPv4 server: active
DHCPv6 server: inactive
DHCP DDNS: active
Control Agent: active
Kea configuration file: /usr/local/etc/kea/kea.conf
keactrl configuration file: /usr/local/etc/kea/keactrl.conf
</screen>
@@ -261,7 +274,8 @@ keactrl configuration file: /usr/local/etc/kea/keactrl.conf
command is issued. For example, the following
instructs <command>keactrl</command> to stop the
<command>kea-dhcp4</command> and <command>kea-dhcp6</command> servers
and leave the <command>kea-dhcp-ddns</command> server running:
and leave the <command>kea-dhcp-ddns</command> and
<command>kea-ctrl-agent</command> running:
<screen>
<userinput>$ keactrl stop -s dhcp4,dhcp6</userinput>
</screen>
@@ -270,8 +284,8 @@ keactrl configuration file: /usr/local/etc/kea/keactrl.conf
<para>
Similarly, the following
will only start the <command>kea-dhcp4</command> and
<command>kea-dhcp-ddns</command> servers and not
<command>kea-dhcp6</command>.
<command>kea-dhcp-ddns</command> servers and not:
<command>kea-dhcp6</command>, <command>kea-ctrl-agent</command>.
<screen>
<userinput>$ keactrl start -s dhcp4,dhcp_ddns</userinput>
</screen>
@@ -302,6 +316,9 @@ keactrl configuration file: /usr/local/etc/kea/keactrl.conf
<listitem><simpara>
<command>dhcp_ddns</command> for <command>kea-dhcp-ddns.</command>
</simpara></listitem>
<listitem><simpara>
<command>ctrl_agent</command> for <command>kea-ctrl-agent.</command>
</simpara></listitem>
<listitem><simpara>
<command>all</command> for all servers (default).
</simpara></listitem>

44
doc/guide/logging.xml
View File

@@ -61,7 +61,7 @@
runtime) are responsible for creating the loggers used by those
libraries. Such loggers should have unique names, different
from the logger names used by Kea. In this way the
messages output by the hooks library can be distingued from
messages output by the hooks library can be distinguished from
messages issued by the core Kea code. Unique names also allow
the loggers to be configured independently of loggers used
by Kea. Whenever it makes sense, a hook library can use multiple
@@ -150,7 +150,7 @@
packet drops, you must create configuration entry for the
logger called <quote>kea-dhcp4.bad-packets</quote> and specify
severity DEBUG for this logger. All other configuration
parameters may be omited for this logger if the logger should
parameters may be omitted for this logger if the logger should
use the default values specified in the root logger's
configuration.
</para>
@@ -181,6 +181,22 @@
Currently defined loggers are:
</para>
<itemizedlist>
<listitem>
<simpara>
<command>kea-ctrl-agent</command> - the root logger for the
Control Agent exposing RESTful control API. All components used
by the Control Agent inherit the settings from this logger.
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-ctrl-agent.http</command> - a logger which outputs
log messages related to receiving, parsing and sending HTTP
messages.
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-dhcp4</command> - the root logger for the DHCPv4
@@ -612,15 +628,17 @@
<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 &mdash; 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 &mdash; 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),
@@ -639,9 +657,13 @@
<section>
<title>maxver (integer)</title>
<para>
Maximum number of old log files to keep around when rolling the
output file. Only relevant when <option>output</option> is
<quote>file</quote>.
Only relevant when the destination is file and rotation is enabled
(i.e. maxsize is large enough). This is maximum number of rotated
versions that will be kept. Once that number of files has been
reached, the oldest file, "log-name.maxver", will be discarded
each time the log rotates. In other words, at most there will be
the active log file plus maxver rotated files. The minimum and
default value is 1.
</para>
</section>
</section>

134
doc/guide/shell.xml Normal file
View File

@@ -0,0 +1,134 @@
<?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 "&#x2017;" >
]>
<chapter id="kea-shell">
<title>The Kea Shell</title>
<section 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">
<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>
</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>