mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-22 01:49:48 +00:00
Code Issues Releases Wiki Activity

Converting from docbook to sphinx: fixing links, making content/grammar corrections as needed

Browse Source
This commit is contained in:
Suzanne Goldlust 2019-06-28 17:57:37 -04:00 committed by Michal Nowikowski
parent 0228c239c1
commit 87220ab1ef
22 changed files with 1534 additions and 1587 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
doc/guide/admin.rst
View File

@ -28,11 +28,11 @@ PostgreSQL.
Backend versions are specified in a major.minor format. The minor number
is increased when there are backwards-compatible changes introduced; for
example, the addition of a new index. It is desirable but not mandatory
to apply such a change; you can run an older backend version if you want
to. (Although, in the example given, running without the new index may
to apply such a change; running an older backend version is possible.
(Although, in the example given, running without the new index may
introduce a performance penalty.) On the other hand, the
major number is increased when an incompatible change is introduced; for
example, an extra column is added to a table. If you try to run Kea on a
example, an extra column is added to a table. If Kea is run on a
backend that is too old (as signified by a mismatched backend major
version number), Kea will refuse to run; administrative action will be
required to upgrade the backend.
@ -80,7 +80,7 @@ supported types are:
- ``cql`` — Information is stored in an Apache Cassandra database.
Additional parameters may be needed, depending on your setup and
Additional parameters may be needed, depending on the setup and
specific operation: username, password, and database name or the
directory where specific files are located. See the appropriate manual
page for details (``man 8 kea-admin``).
@ -93,7 +93,7 @@ Supported Backends
The following table presents the capabilities of available backends.
Please refer to the specific sections dedicated to each backend to
better understand their capabilities and limitations. Choosing the right
backend may be essential for the success of your deployment.
backend may be essential for the success of the deployment.
.. table:: List of available backends
@ -152,9 +152,8 @@ newer versions of Kea, it can also be used for downgrading should the
need arise. When upgrading, any values not present in the original lease
files will be assigned appropriate default values. When downgrading, any
data present in the files but not in the server's schema will be
dropped. If you wish to convert the files manually prior to starting the
servers, you may do so by running the LFC process yourself. See
:ref:`kea-lfc` for more information.
dropped. To convert the files manually prior to starting the
servers, run the LFC process. See :ref:`kea-lfc` for more information.
.. _mysql-database:
@ -164,17 +163,17 @@ MySQL
MySQL is able to store leases, host reservations, options defined on a
per-host basis, and a subset of the server configuration parameters
(serving as a configuration backend). This section can be safely ignored
if you choose to store the data in other backends.
if the data will be stored in other backends.
.. _mysql-database-create:
First-Time Creation of the MySQL Database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are setting the MySQL database for the first time, you need to
create the database area within MySQL and set up the MySQL user ID under
which Kea will access the database. This needs to be done manually;
``kea-admin`` cannot do this for you.
When setting up the MySQL database for the first time, the
database area must be created within MySQL, and the MySQL user ID under
which Kea will access the database must be set up. This needs to be done manually,
rather than via ``kea-admin``.
To create the database:
@ -192,7 +191,7 @@ To create the database:
mysql> CREATE DATABASE database-name;
(database-name is the name you have chosen for the database.)
(database-name is the name chosen for the database.)
3. Create the user under which Kea will access the database (and give it
a password), then grant it access to the database tables:
@ -202,12 +201,12 @@ To create the database:
mysql> CREATE USER 'user-name'@'localhost' IDENTIFIED BY 'password';
mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost';
(user-name and password are the user ID and password you are using to
(user-name and password are the user ID and password being used to
allow Kea access to the MySQL instance. All apostrophes in the
command lines above are required.)
4. At this point, you may elect to create the database tables.
(Alternatively, you can exit MySQL and create the tables using the
4. At this point, administrators may elect to create the database tables.
(Alternatively, the tables can be created by exiting MySQL and using the
``kea-admin`` tool, as explained below.) To do this:
::
@ -215,7 +214,7 @@ To create the database:
mysql> CONNECT database-name;
mysql> SOURCE path-to-kea/share/kea/scripts/mysql/dhcpdb_create.mysql
(path-to-kea is the location where you installed Kea.)
(path-to-kea is the location where Kea is installed.)
5. Exit MySQL:
@ -225,17 +224,17 @@ To create the database:
Bye
$
If you elected not to create the tables in Step 4, you can do so now by
running the ``kea-admin`` tool:
If the tables were not created in Step 4, run the ``kea-admin`` tool
to create them now:
::
$ kea-admin lease-init mysql -u database-user -p database-password -n database-name
Do not do this if you did create the tables in Step 4. ``kea-admin``
Do not do this if the tables were created in Step 4. ``kea-admin``
implements rudimentary checks; it will refuse to initialize a database
that contains any existing tables. If you want to start from scratch,
you must remove all data manually. (This process is a manual operation
that contains any existing tables. To start from scratch,
all must be removed data manually. (This process is a manual operation
on purpose, to avoid possibly irretrievable mistakes by ``kea-admin``.)
.. _mysql-upgrade:
@ -273,8 +272,8 @@ PostgreSQL
----------
PostgreSQL is able to store leases, host reservations, and options
defined on a per-host basis. This step can be safely ignored if you are
using other database backends.
defined on a per-host basis. This step can be safely ignored if
other database backends will be used.
.. _pgsql-database-create:
@ -300,7 +299,7 @@ which the servers will access it. A number of steps are required:
CREATE DATABASE
postgres=#
(database-name is the name you have chosen for the database.)
(database-name is the name chosen for the database.)
3. Create the user under which Kea will access the database (and give it
a password), then grant it access to the database:
@ -321,13 +320,13 @@ which the servers will access it. A number of steps are required:
Bye
$
5. At this point you are ready to create the database tables. This can
be done using the ``kea-admin`` tool as explained in the next section
5. At this point, create the database tables either
using the ``kea-admin`` tool, as explained in the next section
(recommended), or manually. To create the tables manually, enter the
following command. Note that PostgreSQL will prompt you to enter the
new user's password you specified in Step 3. When the command
completes, you will be returned to the shell prompt. You should see
output similar to the following:
following command. Note that PostgreSQL will prompt the administrator to enter the
new user's password that was specified in Step 3. When the command
completes, Kea will return to the shell prompt. The
output should be similar to the following:
::
@ -350,19 +349,19 @@ which the servers will access it. A number of steps are required:
COMMIT
$
(path-to-kea is the location where you installed Kea.)
(path-to-kea is the location where Kea is installed.)
If instead you encounter an error like:
If instead an error is encountered, such as:
::
psql: FATAL: no pg_hba.conf entry for host "[local]", user "user-name", database "database-name", SSL off
... you will need to alter the PostgreSQL configuration. Kea uses
... the PostgreSQL configuration will need to be altered. Kea uses
password authentication when connecting to the database and must have
the appropriate entries added to PostgreSQL's pg_hba.conf file. This
file is normally located in the primary data directory for your
PostgreSQL server. The precise path may vary depending on your
file is normally located in the primary data directory for the
PostgreSQL server. The precise path may vary depending on the
operating system and version, but the default location for PostgreSQL
9.3 on Centos 6.5 is: ``/var/lib/pgsql/9.3/data/pg_hba.conf``.
@ -378,25 +377,25 @@ which the servers will access it. A number of steps are required:
These edits are primarily intended as a starting point, and are not a
definitive reference on PostgreSQL administration or database
security. Please consult your PostgreSQL user manual before making
these changes, as they may expose other databases that you run. It
security. Please consult the PostgreSQL user manual before making
these changes, as they may expose other databases that are running. It
may be necessary to restart PostgreSQL in order for the changes to
take effect.
Initialize the PostgreSQL Database Using kea-admin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you elected not to create the tables manually, you can do so now by
If the tables were not created manually, do so now by
running the ``kea-admin`` tool:
::
$ kea-admin lease-init pgsql -u database-user -p database-password -n database-name
Do not do this if you already created the tables manually. ``kea-admin``
Do not do this if the tables were already created manually. ``kea-admin``
implements rudimentary checks; it will refuse to initialize a database
that contains any existing tables. If you want to start from scratch,
you must remove all data manually. (This process is a manual operation
that contains any existing tables. To start from scratch,
all data must be removed manually. (This process is a manual operation
on purpose, to avoid possibly irretrievable mistakes by ``kea-admin``.)
.. _pgsql-upgrade:
@ -431,18 +430,18 @@ development was contributed by Deutsche Telekom. The Cassandra backend
is able to store leases, host reservations, and options defined on a
per-host basis.
Cassandra must be properly set up if you want Kea to store information
in it. This section can be safely ignored if you choose to store the
data in other backends.
Cassandra must be properly set up if Kea is to store information
in it. This section can be safely ignored if the
data will be stored in other backends.
.. _cql-database-create:
First-Time Creation of the Cassandra Database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are setting up the Cassandra database for the first time, you
need to create the keyspace area within it. This needs to be done
manually; ``kea-admin`` cannot do this for you.
When setting up the Cassandra database for the first time,
the keyspace area within it must be created. This needs to be done
manually; it cannot be performed by ``kea-admin``.
To create the database:
@ -465,29 +464,29 @@ To create the database:
cql> CREATE KEYSPACE keyspace-name WITH replication = {'class' : 'SimpleStrategy','replication_factor' : 1};
(keyspace-name is the name you have chosen for the keyspace)
(keyspace-name is the name chosen for the keyspace.)
4. At this point, you may elect to create the database tables.
(Alternatively, you can exit Cassandra and create the tables using
4. At this point, the database tables can be created.
(It is also possible to exit Cassandra and create the tables using
the ``kea-admin`` tool, as explained below.) To do this:
::
cqslh -k keyspace-name -f path-to-kea/share/kea/scripts/cql/dhcpdb_create.cql
(path-to-kea is the location where you installed Kea)
(path-to-kea is the location where Kea is installed.)
If you elected not to create the tables in Step 4, you can do so now by
If the tables were not created in Step 4, do so now by
running the ``kea-admin`` tool:
::
$ kea-admin lease-init cql -n database-name
Do not do this if you did create the tables in Step 4. ``kea-admin``
Do not do this if the tables were created in Step 4. ``kea-admin``
implements rudimentary checks; it will refuse to initialize a database
that contains any existing tables. If you want to start from scratch,
you must remove all data manually. (This process is a manual operation
that contains any existing tables. To start from scratch,
all data must be removed manually. (This process is a manual operation
on purpose, to avoid possibly irretrievable mistakes by ``kea-admin``.)
.. _cql-upgrade:

10
doc/guide/agent.rst
View File

@ -6,8 +6,8 @@ The Kea Control Agent
.. _agent-overview:
Overview
========
Overview of the Kea Control Agent
=================================
The Kea Control Agent (CA) is a daemon which exposes a RESTful control
interface for managing Kea servers. The daemon can receive control
@ -132,7 +132,7 @@ configuration itself.
Hooks libraries can be loaded by the Control Agent in the same way as
they are loaded by the DHCPv4 and DHCPv6 servers. The CA currently
supports one hook point - 'control_command_receive' - which makes it
supports one hook point - "control_command_receive" - which makes it
possible to delegate processing of some commands to the hooks library.
The ``hooks-libraries`` list contains the list of hooks libraries that
should be loaded by the CA, along with their configuration information
@ -193,12 +193,12 @@ server enables authentication of the clients using certificates.
# 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
# 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 a
# In order to test the proxy configuration with "curl", run a
# command similar to the following:
#
# curl -k --key kea-client.key --cert kea-client.crt -X POST \

1447
doc/guide/api.rst
View File

File diff suppressed because it is too large Load Diff

20
doc/guide/classify.rst
View File

@ -129,20 +129,20 @@ value is obtained is unspecified.
.. _classification-using-vendor:
Built-in Client Classes
======================
=======================
Some classes are built-in, so they do not need to be defined. The main
example uses Vendor Class information: the server checks whether an
incoming DHCPv4 packet includes the vendor class identifier option (60)
or an incoming DHCPv6 packet includes the vendor class option (16). If
it does, the content of that option is prepended with "VENDOR_CLASS_"
it does, the content of that option is prepended with "VENDOR_CLASS\_"
and the result is interpreted as a class. For example, modern cable
modems send this option with value "docsis3.0", so the packet belongs to
class "VENDOR_CLASS_docsis3.0".
The "HA_" prefix is used by the High Availability hooks library to
The "HA\_" prefix is used by the High Availability hooks library to
designate certain servers to process DHCP packets as a result of load
balancing. The class name is constructed by prepending the "HA_" prefix
balancing. The class name is constructed by prepending the "HA\_" prefix
to the name of the server which should process the DHCP packet. This
server uses an appropriate pool or subnet to allocate IP addresses
(and/or prefixes), based on the assigned client classes. The details can
@ -154,7 +154,7 @@ particular client. By convention, built-in classes' names begin with all
capital letters.
Currently recognized built-in class names are ALL, KNOWN and UNKNOWN, and the
prefixes VENDOR_CLASS_, HA_, AFTER_, and EXTERNAL_. Although the AFTER\_
prefixes VENDOR_CLASS\_, HA\_, AFTER\_, and EXTERNAL\_. Although the AFTER\_
prefix is a provision for an as-yet-unwritten hook, the EXTERNAL\_
prefix can be freely used; built-in classes are implicitly defined so
they never raise warnings if they do not appear in the configuration.
@ -339,8 +339,8 @@ Notes:
- "member('foobar')" checks whether the packet belongs to the client
class "foobar". To avoid dependency loops, the configuration file
parser verifies whether client classes were already defined or are
built-in, i.e., beginning by "VENDOR_CLASS_", "AFTER__" (for the
to-come "after" hook) and "EXTERNAL_" or equal to "ALL", "KNOWN",
built-in, i.e., beginning by "VENDOR_CLASS\_", "AFTER\_" (for the
to-come "after" hook) and "EXTERNAL\_" or equal to "ALL", "KNOWN",
"UNKNOWN", etc.
"known" and "unknown" are shorthand for "member('KNOWN')" and "not
@ -523,7 +523,7 @@ digits separated by the separator, e.g ':', '-', '' (empty separator).
the expressions are overly complex, the time taken to execute them
may impact the performance of the server. Administrators who need complex or
time-consuming expressions should consider writing a
`hook <#hooks-libraries>`__ to perform the necessary work.
:ref:`hook <hooks-libraries>` to perform the necessary work.
.. _classification-configuring:
@ -816,7 +816,7 @@ expression would be complex or time-consuming to write, and could be
better or more easily written as code. Once the hook has added the proper class name
to the packet, the rest of the classification system will work as expected
in choosing a subnet and selecting options. For a description of hooks,
see :ref:`hooks-libraries>`__; for information on configuring classes,
see :ref:`hooks-libraries`; for information on configuring classes,
see :ref:`classification-configuring` and :ref:`classification-subnets`.
Debugging Expressions
@ -833,7 +833,7 @@ The specific loggers are "kea-dhcp4.eval" and "kea-dhcp6.eval".
To understand the logging statements, it is essential to understand a bit
about how expressions are evaluated; for a more complete description,
refer to the design document at
https://gitlab.isc.org/isc-projects/kea/wikis/design%20documents. In
https://gitlab.isc.org/isc-projects/kea/wikis/designs/Design-documents. In
brief, there are two structures used during the evaluation of an
expression: a list of tokens which represent the expressions, and a value
stack which represents the values being manipulated.

2
doc/guide/config.rst
View File

@ -28,7 +28,7 @@ JSON Syntax
-----------
Configuration files for the DHCPv4, DHCPv6, DDNS, Control Agent, and
Netconf modules are defined in an extended JSON format. Basic JSON is
NETCONF modules are defined in an extended JSON format. Basic JSON is
defined in `RFC 7159 <https://tools.ietf.org/html/rfc7159>`__ and `ECMA
404 <https://www.ecma-international.org/publications/standards/Ecma-404.htm>`__.
In particular, the only boolean values allowed are true or false (all

166
doc/guide/ctrl-channel.rst
View File

@ -12,28 +12,28 @@ traffic is not handled. Another risk is that if the new configuration is
invalid for any reason, the server may refuse to start, which will
further extend the downtime period until the issue is resolved.
To avoid such problems, the DHCPv4, DHCPv6 and D2 servers in Kea include
To avoid such problems, the DHCPv4, DHCPv6, and D2 servers in Kea include
support for a mechanism that allows online reconfiguration without
requiring server shutdown. Both servers can be instructed to open
control sockets, which is a communications channel. The server is able
to receive commands on that channel, act on them, and report back
status.
The DHCPv4, DHCPv6 and D2 servers receive commands over the UNIX domain
sockets. The details how to configure these sockets, see
`??? <#dhcp4-ctrl-channel>`__ and `??? <#dhcp6-ctrl-channel>`__. While
it is possible to control the servers directly using unix domain sockets
it requires that the controlling client be running on the same machine
The DHCPv4, DHCPv6, and D2 servers receive commands over the UNIX domain
sockets. For details on how to configure these sockets, see
:ref:`dhcp4-ctrl-channel` and :ref:`dhcp6-ctrl-channel`. While
it is possible to control the servers directly using UNIX domain sockets,
that requires that the controlling client be running on the same machine
as the server. SSH is usually used to connect remotely to the controlled
machine.
Network administrators usually prefer using some form of a RESTful API
to control the servers, rather than using UNIX domain sockets directly.
Therefore, Kea includes a component called Control Agent (or CA), which
Therefore, Kea includes a component called the 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
`??? <#agent-configuration>`__.
The CA configuration is described in
:ref:`agent-configuration`.
The HTTP requests received by the CA contain the control commands
encapsulated within HTTP requests. Simply speaking, the CA is
@ -48,7 +48,7 @@ will assume that the control command is targeted at the CA itself and
will try to handle it on its own.
Control connections over both HTTP and UNIX domain sockets are guarded
with timeouts. The default timeout value is set to 10s and is not
with timeouts. The default timeout value is set to 10 seconds and is not
configurable.
.. _ctrl-channel-syntax:
@ -92,8 +92,8 @@ following structure:
}
``command`` is the name of the command to execute and is mandatory.
``arguments`` is a map of parameters required to carry out the given
command. The exact content and format of the map is command-specific.
``arguments`` is a map of the parameters required to carry out the given
command. The exact content and format of the map are command-specific.
``service`` is a list of the servers at which the control command is
targeted. In the example above, the control command is targeted at the
@ -118,7 +118,7 @@ If the command received by the CA does not include a ``service``
parameter or this list is empty, the CA simply processes this message on
its own. For example, a ``config-get`` command which includes no service
parameter returns the Control Agent's own configuration. The
``config-get`` with a service value "dhcp4" is forwarded to the DHCPv4
``config-get`` command with a service value "dhcp4" is forwarded to the DHCPv4
server and returns the DHCPv4 server's configuration.
The following list shows the mapping of the values carried within the
@ -167,7 +167,7 @@ that depends on the specific command.
**Note**
When sending commands via Control Agent, it is possible to specify
When sending commands via the Control Agent, it is possible to specify
multiple services at which the command is targeted. CA forwards this
command to each service individually. Thus, the CA response to the
controlling client contains an array of individual responses.
@ -180,7 +180,7 @@ Using the Control Channel
The easiest way to start interacting with the control API is to use
common UNIX/Linux tools such as ``socat`` and ``curl``.
In order to control the given Kea service via UNIX domain socket, use
In order to control the given Kea service via a UNIX domain socket, use
``socat`` in interactive mode as follows:
::
@ -188,7 +188,7 @@ In order to control the given Kea service via UNIX domain socket, use
$ socat UNIX:/path/to/the/kea/socket -
or in batch mode, include the "ignoreeof" option as shown below to
ensure socat waits long enough for the server to respond:
ensure ``socat`` waits long enough for the server to respond:
::
@ -202,10 +202,11 @@ the specific server directly and bypasses the Control Agent.
It is also easy to open a UNIX socket programmatically. An example of a
simple client written in C is available in the Kea Developer's Guide, in
the Control Channel Overview chapter, in the Using Control Channel
the Control Channel Overview chapter, in the
`Using Control Channel <https://jenkins.isc.org/job/Kea_doc/doxygen/d2/d96/ctrlSocket.html#ctrlSocketClient>`__
section.
To use Kea's RESTful API with ``curl``, you may use the following:
To use Kea's RESTful API with ``curl``, use the following:
::
@ -221,10 +222,10 @@ Commands Supported by Both the DHCPv4 and DHCPv6 Servers
.. _command-build-report:
build-report
------------
The build-report Command
------------------------
The *build-report* command returns on the control channel what the
The ``build-report`` command returns on the control channel what the
command line ``-W`` argument displays, i.e. the embedded content of the
``config.report`` file. This command does not take any parameters.
@ -236,14 +237,14 @@ command line ``-W`` argument displays, i.e. the embedded content of the
.. _command-config-get:
config-get
----------
The config-get Command
----------------------
The *config-get* command retrieves the current configuration used by the
The ``config-get`` 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 the
-c command line option during server start-up or later set using
config-set command. However, there may be certain differences, as
-c command line option during server start-up or later set using the
``config-set`` command. However, there may be certain differences, as
comments are not retained. If the original configuration used file
inclusion, the returned configuration will include all parameters from
all the included files.
@ -263,23 +264,23 @@ An example command invocation looks like this:
.. _command-config-reload:
config-reload
-------------
The config-reload Command
-------------------------
The *config-reload* command instructs Kea to load again the
The ``config-reload`` 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 source; for
example, a sysadmin can tweak the configuration file and use this
command to force Kea pick up the changes.
Caution should be taken when mixing this with config-set commands. Kea
Caution should be taken when mixing this with ``config-set`` commands. Kea
remembers the location of the configuration file it was started with,
and this configuration can be significantly changed using config-set
command. When config-reload is issued after config-set, Kea will attempt
and this configuration can be significantly changed using the ``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.
changes introduced using ``config-set`` or other commands.
*config-reload* does not take any parameters. An example command
``config-reload`` does not take any parameters. An example command
invocation looks like this:
::
@ -290,14 +291,14 @@ invocation looks like this:
.. _command-config-test:
config-test
-----------
The config-test Command
-----------------------
The *config-test* command instructs the server to check whether the new
The ``config-test`` 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
``-t`` command, some sanity checks are not performed so it is possible a
``-t`` command, some sanity checks are not performed, so it is possible a
configuration which successfully passes this command will still fail in
the ``config-set`` command or at launch time. The structure of the
command is as follows:
@ -340,12 +341,12 @@ outcome:
.. _command-config-write:
config-write
------------
The config-write Command
------------------------
The *config-write* command instructs the Kea server to write its current
configuration to a file on disk. It takes one optional argument called
*filename* that specifies the name of the file to write the
The ``config-write`` command instructs the Kea server to write its current
configuration to a file on disk. It takes one optional argument, called
"filename", that specifies the name of the file to write the
configuration to. If not specified, the name used when starting Kea
(passed as a -c argument) will be used. If a relative path is specified,
Kea will write its files only in the directory it is running.
@ -363,10 +364,10 @@ An example command invocation looks like this:
.. _command-leases-reclaim:
leases-reclaim
--------------
The leases-reclaim Command
--------------------------
The *leases-reclaim* command instructs the server to reclaim all expired
The ``leases-reclaim`` command instructs the server to reclaim all expired
leases immediately. The command has the following JSON syntax:
::
@ -378,23 +379,23 @@ leases immediately. The command has the following JSON syntax:
}
}
The *remove* boolean parameter is mandatory and indicates whether the
The ``remove`` boolean parameter is mandatory and indicates whether the
reclaimed leases should be removed from the lease database (if true), or
left in the *expired-reclaimed* state (if false). The latter facilitates
left in the "expired-reclaimed" state (if false). The latter facilitates
lease affinity, i.e. the ability to re-assign an expired lease to the
same client which used this lease before. See `??? <#lease-affinity>`__
for the details. Also, see `??? <#lease-reclamation>`__ for general
information about the processing of expired leases (leases reclamation).
same client that used this lease before. See :ref:`lease-affinity`
for the details. Also, see :ref:`lease-reclamation` for general
information about the processing of expired leases (lease reclamation).
.. _command-libreload:
libreload
---------
The libreload Command
---------------------
The *libreload* command first unloads and then loads 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 that the hook libraries
The ``libreload`` command first unloads and then loads all currently
loaded hooks libraries. This is primarily intended to allow one or more
hooks libraries to be replaced with newer versions without requiring Kea
servers to be reconfigured or restarted. Note that the hooks libraries
are passed the same parameter values (if any) that were passed when they
originally loaded.
@ -410,10 +411,10 @@ or 1, indicating failure.
.. _command-list-commands:
list-commands
-------------
The list-commands Command
-------------------------
The *list-commands* command retrieves a list of all commands supported
The ``list-commands`` command retrieves a list of all commands supported
by the server. It does not take any arguments. An example command may
look like this:
@ -430,10 +431,10 @@ command.
.. _command-config-set:
config-set
----------
The config-set Command
----------------------
The *config-set* command instructs the server to replace its current
The ``config-set`` 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
@ -483,10 +484,10 @@ string, "text", describing the outcome:
.. _command-shutdown:
shutdown
--------
The shutdown Command
--------------------
The *shutdown* command instructs the server to initiate its shutdown
The ``shutdown`` 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:
@ -502,18 +503,18 @@ been initiated.
.. _command-dhcp-disable:
dhcp-disable
------------
The dhcp-disable Command
------------------------
The *dhcp-disable* command globally disables the DHCP service. The
The ``dhcp-disable`` command globally disables the DHCP service. The
server continues to operate, but it drops all received DHCP messages.
This command is useful when the server's maintenance requires that the
server temporarily stop allocating new leases and renew existing leases.
It is also useful in failover-like configurations during a
synchronization of the lease databases at startup, or recovery after a
failure. The optional parameter *max-period* specifies the time in
failure. The optional parameter "max-period" specifies the time in
seconds after which the DHCP service should be automatically re-enabled,
if the *dhcp-enable* command is not sent before this time elapses.
if the ``dhcp-enable`` command is not sent before this time elapses.
::
@ -526,10 +527,10 @@ if the *dhcp-enable* command is not sent before this time elapses.
.. _command-dhcp-enable:
dhcp-enable
-----------
The dhcp-enable Command
-----------------------
The *dhcp-enable* command globally enables the DHCP service.
The ``dhcp-enable`` command globally enables the DHCP service.
::
@ -539,10 +540,10 @@ The *dhcp-enable* command globally enables the DHCP service.
.. _command-version-get:
version-get
-----------
The version-get Command
-----------------------
The *version-get* command returns extended information about the Kea
The ``version-get`` command returns extended information about the Kea
version. It is the same information available via the ``-V``
command-line argument. This command does not take any parameters.
@ -552,8 +553,8 @@ command-line argument. This command does not take any parameters.
"command": "version-get"
}
Commands Supported by D2 Server
===============================
Commands Supported by the D2 Server
===================================
The D2 server supports only a subset of DHCPv4 / DHCPv6 server commands:
@ -577,11 +578,10 @@ The D2 server supports only a subset of DHCPv4 / DHCPv6 server commands:
.. _agent-commands:
Commands Supported by Control Agent
===================================
Commands Supported by the Control Agent
=======================================
The following commands listed in `Commands Supported by Both the DHCPv4
and DHCPv6 Servers <#commands-common>`__ are also supported by the
The following commands listed in :ref:`commands-common` are also supported by the
Control Agent, i.e. when the ``service`` parameter is blank, the
commands are handled by the CA and they relate to the CA process itself:

6
doc/guide/dhcp4-srv.rst
View File

@ -717,8 +717,8 @@ For additional Cassandra-specific parameters, see
.. _read-only-database-configuration4:
Using Read-Only Databases for Host Reservations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using Read-Only Databases for Host Reservations with DHCPv4
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In some deployments the database user whose name is specified in the
database backend configuration may not have write privileges to the
@ -2062,7 +2062,7 @@ The definition used to decode a VSI option is:
2. If none, the global definition;
3. If none, the last-resort definition described in the next section
3. If none, the last-resort definition described in the next section,
:ref:`dhcp4-vendor-opts` (backward-compatible with previous Kea versions).
..

6
doc/guide/dhcp6-srv.rst
View File

@ -663,8 +663,8 @@ For additional Cassandra-specific parameters, see
.. _read-only-database-configuration6:
Using Read-Only Databases for Host Reservations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using Read-Only Databases for Host Reservations with DHCPv6
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In some deployments the database user whose name is specified in the
database backend configuration may not have write privileges to the
@ -2378,7 +2378,7 @@ servers set to 2001:db8:0::1 and 2001:db8:2::1.
}
This example shows a configuration using an automatically generated
"VENDOR_CLASS_" class. The administrator of the network has decided that
"VENDOR_CLASS\_" class. The administrator of the network has decided that
addresses in the range 2001:db8:1::1 to 2001:db8:1::ffff are to be
managed by the DHCP6 server and that only clients belonging to the
eRouter1.0 client class are allowed to use that pool.

6
doc/guide/hammer.rst
View File

@ -52,7 +52,7 @@ or in VirtualBox. To list of supported systems, use the
freebsd:
- 11.2: virtualbox
- 12.0: virtualbox
It is also possible to run the build locally, in the current system (if the OS
is supported).
@ -108,7 +108,7 @@ using SSH, invoke:
./hammer.py ssh -p virtualbox -s freebsd -r 12.0
It is possible to speed up subsequent Hammer builds. To achieve this
Hammer employs :ref:`ccache <https://ccache.samba.org/>`. During
Hammer employs `ccache <https://ccache.samba.org/>`__. During
compilation, ccache stores objects in a shared folder. In subsequent runs,
instead of doing an actual compilation, ccache returns the stored earlier
objects. The cache with these objects for reuse needs to be stored outside of VM
@ -119,7 +119,7 @@ operating system.
::
./hammer.py build -p lxc -s ubuntu -r 18.04 --ccache-dir ~/kea-ccache
..

2
doc/guide/hooks-ha.rst
View File

@ -957,7 +957,7 @@ the Kea source at: ``src/lib/config/timeouts.h``.
Pausing HA State Machine
------------------------
The high-availability state machine includes many different states
The high availability state machine includes many different states
described in detail in :ref:`ha-server-states`. The server
enters each state when certain conditions are met, most often taking
into account the partner server's state. In some states the server

78
doc/guide/hooks-host-cache.rst
View File

@ -4,8 +4,8 @@ host_cache: Caching Host Reservations
=====================================
Some database backends, such as RADIUS, are considered slow and may take
a long time to respond. Since Kea in general is synchronous, the backend
performance directly affects the DHCP performance. To minimize the
a long time to respond. Since Kea in general is synchronous, backend
performance directly affects DHCP performance. To minimize the
impact and improve performance, the Host Cache library provides a way to
cache information from the database locally. This includes negative
caching, i.e. the ability to remember that there is no client
@ -13,19 +13,19 @@ information in the database.
**Note**
This library may only be loaded by the ``kea-dhcp4`` or the
This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process.
In principle, this hook library can be used with any backend that may
introduce performance degradation (MySQL, PostgreSQL, Cassandra,
In principle, this hooks library can be used with any backend that may
introduce performance degradation (MySQL, PostgreSQL, Cassandra, or
RADIUS). Host Cache must be loaded for the RADIUS accounting mechanism
to work.
The Host Cache hook library is currently very simple. It takes only one
optional parameter ("maximum") that defines the maximum number of hosts
The Host Cache hooks library is currently very simple. It takes only one
optional parameter ("maximum"), which defines the maximum number of hosts
to be cached. If not specified, the default value of 0 is used, which
means there is no limit. The hook library can be loaded the same way as
any other hook library; for example, this configuration could be used:
means there is no limit. This hooks library can be loaded the same way as
any other hooks library; for example, this configuration could be used:
::
@ -46,15 +46,15 @@ any other hook library; for example, this configuration could be used:
Once loaded, the Host Cache hook library provides a number of new
commands which can be used either over the control channel (see
`??? <#ctrl-channel-client>`__) or the REST API (see
`??? <#agent-overview>`__). An example REST API client is described in
`??? <#shell-overview>`__. The following sections describe the commands
:ref:`ctrl-channel-client`) or the RESTful API (see
:ref:`agent-overview`). An example RESTful API client is described in
:ref:`shell-overview`. The following sections describe the commands
available.
.. _command-cache-flush:
cache-flush Command
-------------------
The cache-flush Command
-----------------------
This command allows removal of a specified number of cached host
entries. It takes one parameter, which defines the number of hosts to be
@ -67,14 +67,14 @@ removed. An example usage looks as follows:
"arguments": 1000
}
This command will remove 1000 hosts. If you want to delete all cached
This command will remove 1000 hosts. To delete all cached
hosts, please use cache-clear instead. The hosts are stored in FIFO
order, so the oldest entries are always removed.
.. _command-cache-clear:
cache-clear Command
-------------------
The cache-clear Command
-----------------------
This command allows removal of all cached host entries. An example usage
looks as follows:
@ -85,13 +85,13 @@ looks as follows:
"command": "cache-clear"
}
This command will remove all hosts. If you want to delete only a certain
This command will remove all hosts. To delete only a certain
number of cached hosts, please use cache-flush instead.
.. _command-cache-size:
cache-size Command
------------------
The cache-size Command
----------------------
This command returns the number of host entries. An example usage looks
as follows:
@ -104,8 +104,8 @@ as follows:
.. _command-cache-write:
cache-write Command
-------------------
The cache-write Command
-----------------------
In general, the cache content is considered a runtime state and the
server can be shut down or restarted as usual; the cache will then be
@ -114,8 +114,8 @@ useful to store the contents of the cache. One such case is RADIUS,
where the cached hosts also retain additional cached RADIUS attributes;
there is no easy way to obtain this information again, because renewing
clients send their packet to the DHCP server directly. Another use case
is when you want to restart the server and for performance reasons you
want it to start with a hot (populated) cache.
is when an administrator wants to restart the server and, for performance reasons,
wants it to start with a hot (populated) cache.
This command allows writing the contents of the in-memory cache to a
file on disk. It takes one parameter, which defines the filename. An
@ -134,8 +134,8 @@ processed by any other tool that is able to understand JSON format.
.. _command-cache-load:
cache-load Command
------------------
The cache-load Command
----------------------
See the previous section for a discussion of use cases where it may be
useful to write and load contents of the host cache to disk.
@ -157,8 +157,8 @@ processed by any other tool that is able to understand JSON format.
.. _command-cache-get:
cache-get Command
-----------------
The cache-get Command
---------------------
This command is similar to cache-write, but instead of writing the cache
contents to disk, it returns the contents to whoever sent the command.
@ -178,8 +178,8 @@ may be large.
.. _command-cache-get-by-id:
cache-get-by-id Command
-----------------------
The cache-get-by-id Command
---------------------------
This command is similar to cache-get, but instead of returning the whole
content it returns only the entries matching the given identifier.
@ -201,14 +201,14 @@ address.
.. _command-cache-insert:
cache-insert Command
--------------------
The cache-insert Command
------------------------
This command may be used to manually insert a host into the cache; there
are very few use cases when this command could be useful. This command
are very few use cases when this command might be useful. This command
expects its arguments to follow the usual syntax for specifying host
reservations (see `??? <#host-reservation-v4>`__ or
`??? <#host-reservation-v6>`__), with one difference: the subnet-id
reservations (see :ref:`host-reservation-v4` or
:ref:`host-reservation-v6`), with one difference: the subnet-id
value must be specified explicitly.
An example command that will insert an IPv4 host into the host cache
@ -262,15 +262,15 @@ looks as follows:
.. _command-cache-remove:
cache-remove Command
--------------------
The cache-remove Command
------------------------
Sometimes it is useful to remove a single entry from the host cache. A
good use case is a situation where the device is up, Kea has already
provided configuration, and the host entry is in cache. As a result of
administrative action (e.g. customer hasn't paid their bills or has
administrative action (e.g. the customer hasn't paid their bills or has
perhaps been upgraded to better service), the information in the backend
(e.g. MySQL or RADIUS) is being updated. However, since cache is in use,
(e.g. MySQL or RADIUS) is being updated. However, since the cache is in use,
Kea does not notice the change as the cached values are used. The
cache-remove command can solve this problem by removing a cached entry
after administrative changes.

114
doc/guide/hooks-radius.rst
View File

@ -20,7 +20,7 @@ intends to fulfill.
This library may only be loaded by the ``kea-dhcp4`` or the
``kea-dhcp6`` process.
The major feature of the hook library is the ability to use RADIUS
The major feature of this hooks library is the ability to use RADIUS
authorization. When a DHCP packet is received, the Kea server sends an
Access-Request to the RADIUS server and waits for a response. The server
then sends back either an Access-Accept with specific client attributes,
@ -32,10 +32,10 @@ effectively means RADIUS can act as an address-reservation database.
The second case supported is the ability to assign clients to specific
pools based on a RADIUS response. In this case, the RADIUS server sends
back an Access-Accept with Framed-Pool (IPv4) or Framed-IPv6-Pool
back an Access-Accept with a Framed-Pool (IPv4) or Framed-IPv6-Pool
(IPv6). In both cases, Kea interprets those attributes as client
classes. With the addition of the ability to limit access to pools to
specific classes (see `??? <#classification-pools>`__), RADIUS can be
specific classes (see :ref:`classification-pools`), RADIUS can be
used to force the client to be assigned a dynamic address from a
specific pool. Furthermore, the same mechanism can be used to control
what kind of options the client will get if there are DHCP options
@ -51,7 +51,7 @@ on CentOS 7.0. Other systems may differ slightly.
STEP 1: Install dependencies
Several tools are needed to build dependencies and Kea itself. The
Several tools are needed to build the dependencies and Kea itself. The
following commands should install them:
::
@ -59,11 +59,11 @@ following commands should install them:
$ sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
$ sudo yum install gcc-g++ openssl-devel log4cplus-devel wget git
STEP 2: FreeRADIUS installation
STEP 2: Install FreeRADIUS
The Kea RADIUS hook library uses the FreeRADIUS client library to
The Kea RADIUS hooks library uses the FreeRADIUS client library to
conduct RADIUS communication. Unfortunately, the standard 1.1.7 release
available from the project website http://freeradius.org/sub_projects/
available from the project website https://freeradius.org/sub_projects/
has several serious deficiencies; ISC engineers observed a segmentation
fault during testing. Also, the base version of the library does not
offer asynchronous transmissions, which are essential for effective
@ -83,11 +83,11 @@ version, please use the following steps:
$ make
$ sudo make install
You may pass additional parameters to the configure script, if you need
to. Once installed, the FreeRADIUS client will be installed in
Additional parameters may be passed to the configure script, if needed.
Once installed, the FreeRADIUS client will be installed in
/usr/local. This is the default path where Kea will be looking for it.
You may install it in a different directory; if you choose to do so,
make sure you add that path to the configure script when compiling Kea.
It can be installed in a different directory; if so,
make sure to add that path to the configure script when compiling Kea.
STEP 3: Install recent BOOST version
@ -159,10 +159,10 @@ Once this is done, verify that the Kea sources look similar to this:
drwxr-xr-x 10 thomson staff 340 Apr 26 19:04 src
drwxr-xr-x 14 thomson staff 476 Apr 26 19:04 tools
The makefiles must be regenerated using autoreconf.
The makefiles must be regenerated using ``autoreconf``.
The next step is to configure Kea, and there are several essential steps
necessary here. Running autoreconf -if is necessary to compile the
necessary here. Running ``autoreconf -if`` is necessary to compile the
premium package that contains RADIUS. Also, the --with-freeradius option
is necessary to tell Kea where the FreeRADIUS client sources can be
found. Also, since the non-standard Boost is used, the path to it must
@ -268,7 +268,7 @@ the following:
Kea-shell: no
Perfdhcp: no
Please make sure that your compilation has the following:
Please make sure that the compilation includes the following:
- RADIUS listed in Included Hooks;
- FreeRADIUS client directories printed and pointing to the right
@ -276,9 +276,9 @@ Please make sure that your compilation has the following:
- Boost version at least 1.65.1. The versions available in CentOS 7
(1.48 and and 1.53) are too old.
Once your configuration is complete, compile Kea using make. If your
system has more than one core, it is recommended that you use the "-j N"
option to speed up the build.
Once the configuration is complete, compile Kea using make. If the
system has more than one core, using the "-j N"
option is recommended to speed up the build.
::
@ -291,7 +291,7 @@ RADIUS Hook Configuration
-------------------------
The RADIUS hook is a library that has to be loaded by either DHCPv4 or
DHCPv6 Kea servers. Unlike some other available hook libraries, this one
DHCPv6 Kea servers. Unlike some other available hooks libraries, this one
takes many parameters. For example, this configuration could be used:
::
@ -320,28 +320,28 @@ takes many parameters. For example, this configuration could be used:
}
} ]
RADIUS is a complicated environment. As such, it's not really possible
to provide a default configuration that would work out of the box.
RADIUS is a complicated environment. As such, it is not feasible
to provide a default configuration that works for everyone.
However, we do have one example that showcases some of the more common
features. Please see doc/examples/kea4/hooks-radius.json in your Kea
features. Please see doc/examples/kea4/hooks-radius.json in the Kea
sources.
The RADIUS hook library supports the following global configuration
flags, which correspond to FreeRADIUS client library options:
- ``bindaddr`` (default "*") specifies the address to be used by the
hook library in communication with RADIUS servers. The "*" special
- ``bindaddr`` (default "*") - specifies the address to be used by the
hooks library in communication with RADIUS servers. The "*" special
value tells the kernel to choose the address.
- ``canonical-mac-address`` (default false) specifies whether MAC
- ``canonical-mac-address`` (default false) - specifies whether MAC
addresses in attributes follow the canonical RADIUS format (lowercase
pairs of hexadecimal digits separated by '-').
- ``client-id-pop0`` (default false), used with flex-id, removes the
- ``client-id-pop0`` (default false) - used with flex-id, removes the
leading zero (or pair of zeroes in DHCPv6) type in client-id (aka
duid in DHCPv6). Implied by client-id-printable.
- ``client-id-printable`` (default false) checks whether the
- ``client-id-printable`` (default false) - checks whether the
client-id/duid content is printable and uses it as is instead of in
hexadecimal. Implies client-id-pop0 and extract-duid as 0 and 255 are
not printable.
@ -353,42 +353,42 @@ flags, which correspond to FreeRADIUS client library options:
use locks or atomics, it is recommended that you do not use this
feature when running in this mode.
- ``dictionary`` (default set by configure at build time) is the
- ``dictionary`` (default set by configure at build time) - is the
attribute and value dictionary. Note that it is a critical parameter.
- ``extract-duid`` (default true) extracts the embedded duid from an
- ``extract-duid`` (default true) - extracts the embedded duid from an
RFC 4361-compliant DHCPv4 client-id. Implied by client-id-printable.
- ``identifier-type4`` (default client-id) specifies the identifier
- ``identifier-type4`` (default client-id) - specifies the identifier
type to build the User-Name attribute. It should be the same as the
host identifier, and when the flex-id hook library is used the
replace-client-id must be set to true; client-id will be used with
client-id-pop0.
- ``identifier-type6`` (default duid) specifies the identifier type to
- ``identifier-type6`` (default duid) - specifies the identifier type to
build the User-Name attribute. It should be the same as the host
identifier, and when the flex-id hook library is used the
replace-client-id must be set to true; duid will be used with
client-id-pop0.
- ``realm`` (default "") is the default realm.
- ``realm`` (default "") - is the default realm.
- ``reselect-subnet-address`` (default false) uses the Kea reserved
- ``reselect-subnet-address`` (default false) - uses the Kea reserved
address/RADIUS Framed-IP-Address or Framed-IPv6-Address to reselect
subnets where the address is not in the subnet range.
- ``reselect-subnet-pool`` (default false) uses the Kea
- ``reselect-subnet-pool`` (default false) - uses the Kea
client-class/RADIUS Frame-Pool to reselect subnets where no available
pool can be found.
- ``retries`` (default 3) is the number of retries before trying the
- ``retries`` (default 3) - is the number of retries before trying the
next server. Note that it is not supported for asynchronous
communication.
- ``session-history`` (default "") is the name of the file providing
- ``session-history`` (default "") - is the name of the file providing
persistent storage for accounting session history.
- ``timeout`` (default 10) is the number of seconds during which a
- ``timeout`` (default 10) - is the number of seconds during which a
response is awaited.
When ``reselect-subnet-pool`` or ``reselect-subnet-address`` is set to
@ -398,54 +398,54 @@ does not match, another subnet is selected among matching subnets.
Two services are supported:
- ``access`` - the authentication service
- ``access`` - the authentication service.
- ``accounting`` - the accounting service
- ``accounting`` - the accounting service.
Configuration of services is divided into two parts:
- servers that define RADIUS servers the library is expected to
- Servers that define RADIUS servers that the library is expected to
contact. Each server may have the following items specified:
- ``name``, which specifies the IP address of the server (it is
- ``name`` - specifies the IP address of the server (it is
possible to use a name which will be resolved, but it is not
recommended).
- ``port`` (default RADIUS authentication or accounting service),
which specifies the UDP port of the server. Note that the
- ``port`` (default RADIUS authentication or accounting service) -
specifies the UDP port of the server. Note that the
FreeRADIUS client library by default uses ports 1812
(authorization) and 1813 (accounting). Some server implementations
use 1645 (authorization) and 1646 (accounting). You may use the
"port" parameter to adjust as needed.
use 1645 (authorization) and 1646 (accounting). The
"port" parameter may be used to adjust as needed.
- ``secret``, which authenticates messages.
- ``secret`` - authenticates messages.
There may be up to eight servers. Note that when no server is
specified, the service is disabled.
- attributes which define additional information that the Kea server
- Attributes which define additional information that the Kea server
will send to a RADIUS server. The parameter must be identified either
by a name or type. Its value can be specified in one of three
possible ways: data (which defines a plain text value), raw (which
defines the value in hex), or expr (which defines an expression,
which will be evaluated for each incoming packet independently).
- ``name`` of the attribute.
- ``name`` - the name of the attribute.
- ``type`` of the attribute. Either the type or the name must be
- ``type`` - the type of the attribute. Either the type or the name must be
provided, and the attribute must be defined in the dictionary.
- ``data`` is the first of three ways to specify the attribute
- ``data`` - the first of three ways to specify the attribute
content. The data entry is parsed by the FreeRADIUS library, so
values defined in the dictionary of the attribute may be used.
- ``raw`` is the second of three ways to specify the attribute
- ``raw`` - the second of three ways to specify the attribute
content; it specifies the content in hexadecimal. Note that it
does not work with integer-content attributes (date, integer, and
IPv4 address); a string-content attribute (string, IPv6 address,
and IPv6 prefix) is required.
- ``expr`` is the last way to specify the attribute content. It
- ``expr`` - the last way to specify the attribute content. It
specifies an evaluation expression which must return a not-empty
string when evaluated with the DHCP query packet. Currently this
is restricted to the access service.
@ -485,7 +485,7 @@ following snippet could be used:
"data": "mysecretpassword"
},
{
// It's also possible to specify an attribute using its type,
// It is also possible to specify an attribute using its type,
// rather than a name. 77 is Connect-Info. The value is specified
// using hex. Again, this is a static value. It will be sent the
// same for every packet and to every server.
@ -519,8 +519,8 @@ following snippet could be used:
}
For the RADIUS hook library to operate properly in DHCPv4, it is
necessary to also load the Host Cache hook library. The reason for this
For the RADIUS hooks library to operate properly in DHCPv4,
the Host Cache hooks library must also be loaded. The reason for this
is somewhat complex. In a typical deployment, the DHCP clients send
their packets via DHCP relay which inserts certain Relay Agent
Information options, such as circuit-id or remote-id. The values of
@ -528,16 +528,16 @@ those options are then used by the Kea DHCP server to formulate the
necessary attributes in the Access-Request message sent to the RADIUS
server. However, once the DHCP client gets its address, it then renews
by sending packets directly to the DHCP server. As a result, the relays
are not able to insert their RAI options and the DHCP server can't send
are not able to insert their RAI options, and the DHCP server cannot send
the Access-Request queries to the RADIUS server by using just the
information from incoming packets. Kea needs to keep the information
received during the initial Discover/Offer exchanges and use it again
later when sending accounting messages.
This mechanism is implemented based on user context in host
reservations. (See `??? <#user-context>`__ for details about user
reservations. (See :ref:`user-context` for details about user
context). The host cache mechanism allows the information retrieved by
RADIUS to be stored and later used for sending accounting and access
queries to the RADIUS server. In other words, the host-cache mechanism
is mandatory, unless you do not want RADIUS communication for messages
is mandatory, unless administrators do not want RADIUS communication for messages
other than Discover and the first Request from each client.

68
doc/guide/hooks-stat-cmds.rst
View File

@ -19,68 +19,68 @@ for retrieving these statistics.
**Note**
This library may only be loaded by the ``kea-dhcp4`` or the
This library may only be loaded by the ``kea-dhcp4`` or
``kea-dhcp6`` process.
The commands currently provided by this library are:
- ``stat-lease4-get`` - fetches DHCPv4 lease statistics
- ``stat-lease4-get`` - fetches DHCPv4 lease statistics.
- ``stat-lease6-get`` - fetches DHCPv6 lease statistics
- ``stat-lease6-get`` - fetches DHCPv6 lease statistics.
The Stat commands library is part of the open source code and is
The stat commands library is part of the open source code and is
available to every Kea user.
All commands use JSON syntax and can be issued directly to the servers
via either the control channel (see `??? <#ctrl-channel>`__) or the
Control Agent (see `??? <#kea-ctrl-agent>`__).
via either the control channel (see :ref:`ctrl-channel`) or the
Control Agent (see :ref:`kea-ctrl-agent`).
This library may be loaded by both kea-dhcp4 and kea-dhcp6 servers. It
This library may be loaded by both the kea-dhcp4 and kea-dhcp6 servers. It
is loaded in the same way as other libraries and currently has no
parameters:
::
"Dhcp6": {
"Dhcp6": {
"hooks-libraries": [
{
"library": "/path/libdhcp_stat_cmds.so"
}
...
]
]
}
In a deployment with multiple Kea DHCP servers sharing a common lease
storage, it may be loaded by any or all of the servers. However, one
storage, this hooks library may be loaded by any or all of the servers. However, one
thing to keep in mind is that a server's response to a
stat-lease{4/6}-get command will only contain data for subnets known to
stat-lease[46]-get command will only contain data for subnets known to
that server. In other words, if a subnet does not appear in a server's
configuration, Kea will not retrieve statistics for it.
.. _command-stat-lease4-get:
stat-lease4-get, stat-lease6-get Commands
-----------------------------------------
The stat-lease4-get, stat-lease6-get Commands
---------------------------------------------
The ``stat-lease4-get`` and ``stat-lease6-get`` commands fetch lease
statistics for a range of known subnets. The range of subnets is
determined through the use of optional command input parameters:
- ``subnet-id`` - The ID of the subnet for which lease statistics
- ``subnet-id`` - the ID of the subnet for which lease statistics
should be fetched. Use this to get statistics for a single subnet. If
the subnet does not exist, the command result code is 3 (i.e.
CONTROL_RESULT_EMPTY).
- ``subnet-range`` - A pair of subnet IDs which describe an inclusive
- ``subnet-range`` - a pair of subnet IDs which describe an inclusive
range of subnets for which statistics should be retrieved. The range
may include one or more IDs that correspond to no subnet: in this
may include one or more IDs that correspond to no subnet; in this
case, the command will only output lease statistics for those that
exist. However, if the range does not include any known subnets, the
command result code is 3 (i.e. CONTROL_RESULT_EMPTY).
- ``first-subnet-id`` - The ID of the first subnet in the range.
- ``first-subnet-id`` - the ID of the first subnet in the range.
- ``last-subnet-id`` - The ID of the last subnet in the range.
- ``last-subnet-id`` - the ID of the last subnet in the range.
The use of subnet-id and subnet-range are mutually exclusive. If no
parameters are given, the result will contain data for all known
@ -130,10 +130,10 @@ The response to either command will contain three elements:
- ``0`` - the command was successful;
- ``1`` - an error occurred, an explanation will be the "text"
element;
- ``1`` - an error occurred, and an explanation will be the "text"
element; or
- ``2`` - the fetch found no matching data
- ``2`` - the fetch found no matching data.
- ``text`` - an explanation of the command outcome. When the command
succeeds it will contain the command name along with the number of
@ -143,48 +143,48 @@ The response to either command will contain three elements:
the element "result-set", which is patterned after SQL statement
responses:
- ``columns`` - a list of text column labels The columns returned
- ``columns`` - a list of text column labels. The columns returned
for DHCPv4 are:
- ``subnet-id`` - ID of the subnet.
- ``subnet-id`` - the ID of the subnet.
- ``total-addresses`` - total number of addresses available for
- ``total-addresses`` - the total number of addresses available for
DHCPv4 management in the subnet. In other words, this is the
sum of all addresses in all the configured pools in the subnet.
- ``assigned-addresses`` - number of addresses in the subnet that
- ``assigned-addresses`` - the number of addresses in the subnet that
are currently assigned to a client.
- ``declined-addresses`` - number of addresses in the subnet that
- ``declined-addresses`` - the number of addresses in the subnet that
are currently declined and are thus unavailable for assignment.
- The columns returned for DHCPv6 are:
- ``subnet-id`` - ID of the subnet.
- ``subnet-id`` - the ID of the subnet.
- ``total-nas`` - number of NA addresses available for DHCPv6
- ``total-nas`` - the number of NA addresses available for DHCPv6
management in the subnet. In other words, this is the sum of
all the NA addresses in the all configured NA pools in the
all the NA addresses in all the configured NA pools in the
subnet.
- ``assigned-nas`` - number of NA addresses in a the subnet that
- ``assigned-nas`` - the number of NA addresses in the subnet that
are currently assigned to a client.
- ``declined-nas`` - number of NA addresses that are currently
- ``declined-nas`` - the number of NA addresses that are currently
declined and are thus unavailable for assignment.
- ``total-pds`` - total number of prefixes available of DHCPv6
- ``total-pds`` - the total number of prefixes available of DHCPv6
management in the subnet. In other words, this is the sum of
all prefixes in all the configured prefix pools in the subnet.
- ``assigned-pds`` - number of prefixes in the subnet that are
- ``assigned-pds`` - the number of prefixes in the subnet that are
currently assigned to a client.
- ``rows`` - a list of rows, one per subnet ID. Each row contains a
data value corresponding to and in the same order as each column
listed in "columns" for a given subnet.
- ``timestamp`` - textual date and time the data was fetched,
- ``timestamp`` - the textual date and time the data were fetched,
expressed as GMT.
The response to a DHCPv4 command might look as follows:

66
doc/guide/hooks.rst
View File

@ -61,7 +61,7 @@ refer to :ref:`installation` for a general overview of the installation process.
ISC provides several additional premium hooks in the form of packages, which
follow a similar installation procedure but with several additional steps.
For your convenience, the premium hooks installation procedure is described in this section.
For our users' convenience, the premium hooks installation procedure is described in this section.
1. Download the package; detailed instructions are provided separately on how
to get it. The package will be a file with a name similar to
@ -80,7 +80,7 @@ Unpack this tarball:
$ tar zxvf kea-KEAVERSION.tar.gz
This will unpack the tarball into the kea-KEAVERSION subdirectory of
your current working directory.
the current working directory.
3. Unpack the Kea premium tarball into the directory into which Kea was
unpacked. Once Kea KEAVERSION has been unpacked into a kea-KEAVERSION
@ -97,9 +97,9 @@ directory named "premium". Regardless of the name of the package, the
directory will always be called "premium", although its contents will vary
depending on the premium package.
4. Run autoreconf tools. This step is necessary to update Kea's build
4. Run ``autoreconf`` tools. This step is necessary to update Kea's build
script to include the additional directory. If this tool is not already
available on the system, install the automake and autoconf
available on the system, install the ``automake`` and ``autoconf``
tools. To generate the configure script, please use:
::
@ -920,17 +920,15 @@ can be achieved by using the following configuration:
]
}
**Note**
Note that care should be taken when adjusting the expression. If the expression
changes, then all the ``flex-id`` values may change, possibly rendering
all reservations based on ``flex-id`` unusable until they are manually updated.
It is strongly recommended that administrators start with the expression and a
handful of reservations, and then adjust the expression as needed. Once
the expression is confirmed to do what is desired of it, host reservations
can be deployed on a broader scale.
Care should be taken when adjusting the expression. If the expression
changes, then all the ``flex-id`` values may change, possibly rendering
all reservations based on ``flex-id`` unusable until they are manually updated.
It is strongly recommended that administrators start with the expression and a
handful of reservations, and then adjust the expression as needed. Once
the expression is confirmed to do what is desired of it, host reservations
can be deployed on a broader scale.
flex-id values in host reservations can be specified in two ways. First,
``flex-id`` values in host reservations can be specified in two ways. First,
they can be expressed as a hex string, e.g. bar string can be represented
as 626174. Alternatively, it can be expressed as a quoted value (using
double and single quotes), e.g. "'bar'". The former is more convenient
@ -1235,8 +1233,8 @@ Example failure:
As ``reservation-add`` is expected to store the host, the hosts-databases
parameter must be specified in the configuration and databases must not
run in read-only mode. In future versions of Kea, it will be possible to
modify the reservations read from a configuration file. Please contact
ISC if you are interested in this functionality.
modify the reservations read from a configuration file. Interested parties are
encouraged to contact ISC for more information on developing this functionality.
.. _command-reservation-get:
@ -1388,12 +1386,12 @@ may be disruptive. Use with caution. For larger deployments, please
consider using ``reservation-get-page`` instead (see
:ref:`command-reservation-get-page`).
For a reference, see :ref:`ref-reservation-get-all`.
For a reference, see :ref:`command-reservation-get-all`.
.. _command-reservation-get-page:
reservation-get-page command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The reservation-get-page command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``reservation-get-page`` can be used to query the host database and
retrieve all reservations in a specified subnet by pages. This command
@ -1517,8 +1515,6 @@ users retrieve larger host reservations lists in smaller chunks. For
small deployments with few reservations, it is easier to use
``reservation-get-all`` (see :ref:`command-reservation-get-all`.
For a reference, see :ref:`ref-reservation-get-page`.
**Note**
Currently ``reservation-get-page`` is not supported by the Cassandra
@ -2519,35 +2515,35 @@ both the command and the response.
.. _user-context:
User contexts
User Contexts
=============
Hook libraries can have their own configuration parameters. That is
Hooks libraries can have their own configuration parameters, which is
convenient if the parameter applies to the whole library. However,
sometimes it is very useful if certain configuration entities are
extended with additional configuration data. This is where the concept
of user contexts comes in. A sysadmin can define an arbitrary set of
data and attach it to Kea structures, as long as the data is specified
as JSON map. In particular, it is possible to define fields that are
integers, strings, boolean, lists and maps. It is possible to define
sometimes it is very useful to extend certain configuration entities
with additional configuration data. This is where the concept
of user contexts comes in. A system administrator can define an arbitrary set of
data and attach it to Kea structures, as long as the data are specified
as a JSON map. In particular, it is possible to define fields that are
integers, strings, boolean, lists, or maps. It is possible to define
nested structures of arbitrary complexity. Kea does not use that data on
its own, simply stores and makes it available for the hook libraries.
its own; it simply stores it and makes it available for the hooks libraries.
Another use case for user contexts may be storing comments and other
information that will be retained by Kea. Regular comments are discarded
when configuration is loaded, but user contexts are retained. This is
useful if you want your comments to survive config-set, config-get
operations for example.
when the configuration is loaded, but user contexts are retained. This is
useful if administrators want their comments to survive config-set or config-get
operations, for example.
If user context is supported in a given context, the parser translates
"comment" entries into user context with a "comment" entry. The pretty
print of a configuration does the opposite operation and puts "comment"
entries at the beginning of maps as it seems to be the common usage.
entries at the beginning of maps, as that seems to be the common usage.
As of Kea 1.3, the structures that allow user contexts are pools of all
types (addresses and prefixes) and subnets. Kea 1.4 extended user
context support to the global scope, interfaces config, shared networks,
subnets, client classes, option datas and definitions, host
reservations, control socket, dhcp ddns, loggers and server id. These
are supported in both DHCPv4 and DHCPv6 at the exception of server id
are supported in both DHCPv4 and DHCPv6, with the exception of server id
which is DHCPv6 only.

4
doc/guide/intro.rst
View File

@ -74,7 +74,7 @@ software separately. (For the build requirements, also see :ref:`build-requireme
kea-netconf agent. This Kea module is built optionally and requires
Sysrepo software when used. Building Kea with NETCONF support
requires many dependencies to be installed, which are described in
more detail in :ref: `netconf-install`.
more detail in :ref:`netconf-install`.
.. _kea_software:
@ -110,7 +110,7 @@ The following software is included with Kea:
- ``kea-ctrl-agent`` — Kea Control Agent (CA) is a daemon that exposes
a RESTful control interface for managing Kea servers.
- ``kea-netconf`` - Kea-netconf is an agent that provides a
- ``kea-netconf`` - kea-netconf is an agent that provides a
YANG/NETCONF interface for the Kea environment.
- ``kea-shell`` — This simple text client uses the REST interface to

4
doc/guide/keactrl.rst
View File

@ -248,8 +248,8 @@ take effect. This limitation will be removed in a future release.
NETCONF is an optional feature that is disabled by default and can be
enabled during compilation. If Kea was compiled without NETCONF
support, keactrl will do its best to not bother the user with
information about it. The netconf entries will still be present in
the keactrl.conf file, but netconf status will not be shown and other
information about it. The NETCONF entries will still be present in
the keactrl.conf file, but NETCONF status will not be shown and other
commands will ignore it.
**Note**

2
doc/guide/lease-expiration.rst
View File

@ -39,6 +39,8 @@ Although all configuration examples in this section are provided for the
DHCPv4 server, the same parameters may be used for DHCPv6 server
configuration.
.. _lease-reclamation:
Lease Reclamation
=================

791
doc/guide/logging.rst
View File

@ -9,15 +9,15 @@ Logging Configuration
During its operation Kea may produce many messages. They differ in
severity (some are more important than others) and source (different
components (e.g. hooks) produce different messages). It is useful to
understand which log messages are critical and which are not, and
configure your logging appropriately. For example, debug-level messages
components, like hooks, produce different messages). It is useful to
understand which log messages are critical and which are not, and to
configure logging appropriately. For example, debug-level messages
can be safely ignored in a typical deployment. They are, however, very
useful when debugging a problem.
The logging system in Kea is configured through the loggers entry in the
server section of your configuration file. In previous Kea releases this
entry was in an independent Logging section, this is still supported for
entry was in an independent Logging section; this is still supported for
backward compatibility.
Loggers
@ -31,7 +31,7 @@ messages pertaining to different logical functions of the component. For
example, the DHCPv4 server uses one logger for messages about packet
reception and transmission, another logger for messages related to lease
allocation, and so on. Some of the libraries used by the Kea server,
e.g. libdhcpsrv, use their own loggers.
such as libdhcpsrv, use their own loggers.
Users implementing hooks libraries (code attached to the server at
runtime) are responsible for creating the loggers used by those
@ -43,15 +43,14 @@ loggers used by Kea. Whenever it makes sense, a hooks library can use
multiple loggers to log messages pertaining to different logical parts
of the library.
In the server section of a configuration file you can specify the
In the server section of a configuration file the
configuration for zero or more loggers (including loggers used by the
proprietary hooks libraries). If there are no loggers specified, the
proprietary hooks libraries) can be specified. If there are no loggers specified, the
code will use default values; these cause Kea to log messages of INFO
severity or greater to standard output. There is a small time window
after Kea has been started but before it has read its configuration;
logging in this short period can be controlled using environment
variables. For details, see `Logging During Kea
Startup <#logging-during-startup>`__.
variables. For details, see :ref:`logging-during-startup`.
The three main elements of a logger configuration are: ``name`` (the
component that is generating the messages), ``severity`` (what to log),
@ -59,16 +58,16 @@ and ``output_commands`` (where to log). There is also a ``debuglevel``
element, which is only relevant if debug-level logging has been
selected.
name (string)
~~~~~~~~~~~~~
The name (string) Logger
~~~~~~~~~~~~~~~~~~~~~~~~
Each logger in the system has a name: that of the component binary file
using it to log messages. For instance, if you want to configure logging
for the DHCPv4 server, you add an entry for a logger named “kea-dhcp4”.
using it to log messages. For instance, to configure logging
for the DHCPv4 server, add an entry for a logger named “kea-dhcp4”.
This configuration will then be used by the loggers in the DHCPv4
server, and all the libraries used by it (unless a library defines its
server and all the libraries used by it, unless a library defines its
own logger and there is a specific logger configuration that applies to
that logger).
that logger.
When tracking down an issue with the server's operation, use of DEBUG
logging is required to obtain the verbose output needed for problem
@ -85,10 +84,10 @@ required minimum.
The loggers are associated with a particular library or binary of Kea.
However, each library or binary may (and usually does) include multiple
loggers. For example, the DHCPv4 server binary contains separate loggers
for packet parsing, for dropped packets, for callouts, etc.
for packet parsing, dropped packets, callouts, etc.
The loggers form a hierarchy. For each program in Kea, there is a "root"
logger, named after the program (e.g. the root logger for kea-dhcp (the
logger, named after the program (e.g. the root logger for kea-dhcp, the
DHCPv4 server) is named kea-dhcp4. All other loggers are children of
this logger and are named accordingly, e.g. the allocation engine in the
DHCPv4 server logs messages using a logger called
@ -101,9 +100,9 @@ configuration file and so applies to all loggers. If an entry is made
for a given logger, any attributes specified override those of the root
logger, whereas any not specified are inherited from it.
To illustrate this, suppose you are using the DHCPv4 server with the
To illustrate this, suppose we are using the DHCPv4 server with the
root logger “kea-dhcp4” logging at the INFO level. In order to enable
DEBUG verbosity for DHCPv4 packet drops, you must create a configuration
DEBUG verbosity for DHCPv4 packet drops, we must create a configuration
entry for the logger called “kea-dhcp4.bad-packets” and specify severity
DEBUG for this logger. All other configuration parameters may be omitted
for this logger if the logger should use the default values specified in
@ -121,348 +120,347 @@ will be logged according to the configuration set by the second entry.
Currently defined loggers are defined in the following table. The
"Software Package" column of this table specifies whether the particular
loggers belong to the core Kea code (open source Kea binaries and
libraries), or hook libraries (open source or premium).
libraries), or hooks libraries (open source or premium).
.. table:: List of loggers supported by Kea servers and hooks libraries
shipped with Kea and premium packages
.. table:: List of Loggers Supported by Kea Servers and Hooks Libraries Shipped With Kea and Premium Packages
+-----------------------+-----------------------+-----------------------+
| Logger Name | Software Package | Description |
+=======================+=======================+=======================+
| ``kea-ctrl-agent`` | core | The root logger for |
| | | the Control Agent |
| | | exposing the RESTful |
| | | control API. All |
| | | components used by |
| | | the Control Agent |
| | | inherit the settings |
| | | from this logger. |
+-----------------------+-----------------------+-----------------------+
| ``kea-ctrl-agent.http | core | A logger which |
| `` | | outputs log messages |
| | | related to receiving, |
| | | parsing, and sending |
| | | HTTP messages. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4`` | core | The root logger for |
| | | the DHCPv4 server. |
| | | All components used |
| | | by the DHCPv4 server |
| | | inherit the settings |
| | | from this logger. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp6`` | core | The root logger for |
| | | the DHCPv6 server. |
| | | All components used |
| | | by the DHCPv6 server |
| | | inherit the settings |
| | | from this logger. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.alloc-eng | core | Used by the lease |
| ine``, | | allocation engine, |
| ``kea-dhcp6.alloc-eng | | which is responsible |
| ine`` | | for managing leases |
| | | in the lease |
| | | database, i.e. |
| | | creating, modifying, |
| | | and removing DHCP |
| | | leases as a result of |
| | | processing messages |
| | | from the clients. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.bad-packe | core | Used by the DHCP |
| ts``, | | servers for logging |
| ``kea-dhcp6.bad-packe | | inbound client |
| ts`` | | packets that were |
| | | dropped or to which |
| | | the server responded |
| | | with a DHCPNAK. It |
| | | allows administrators |
| | | to configure a |
| | | separate log output |
| | | that contains only |
| | | packet drop and |
| | | reject entries. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.callouts` | core | Used to log messages |
| `, | | pertaining to the |
| ``kea-dhcp6.callouts` | | callouts registration |
| ` | | and execution for the |
| | | particular hook |
| | | point. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.commands` | core | Used to log messages |
| `, | | relating to the |
| ``kea-dhcp6.commands` | | handling of commands |
| ` | | received by the DHCP |
| | | server over the |
| | | command channel. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.database` | core | Used to log messages |
| `, | | relating to general |
| ``kea-dhcp6.database` | | operations on the |
| ` | | relational databases |
| | | and Cassandra. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.ddns``, | core | Used by the DHCP |
| ``kea-dhcp6.ddns`` | | server to log |
| | | messages related to |
| | | the Client FQDN and |
| | | Hostname option |
| | | processing. It also |
| | | includes log messages |
| | | related to the |
| | | relevant DNS updates. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.dhcp4`` | core | Used by the DHCPv4 |
| | | server daemon to log |
| | | basic operations. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.dhcpsrv`` | core | The base loggers for |
| , | | the libkea-dhcpsrv |
| ``kea-dhcp6.dhcpsrv`` | | library. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.eval``, | core | Used to log messages |
| ``kea-dhcp6.eval`` | | relating to the |
| | | client classification |
| | | expression evaluation |
| | | code. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.host-cach | libdhcp_host_cache | This logger is used |
| e-hooks``, | premium hook library | to log messages |
| ``kea-dhcp6.host-cach | | related to the |
| e-hooks`` | | operation of the Host |
| | | Cache Hook Library. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.flex-id-h | libdhcp_flex_id | This logger is used |
| ooks``, | premium hook library | to log messages |
| ``kea-dhcp6.flex-id-h | | related to the |
| ooks`` | | operation of the |
| | | Flexible Identifiers |
| | | Hook Library. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.ha-hooks` | libdhcp_ha hook | This logger is used |
| `, | library | to log messages |
| ``kea-dhcp6.ha-hooks` | | related to the |
| ` | | operation of the High |
| | | Availability Hook |
| | | Library. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.hooks``, | core | Used to log messages |
| ``kea-dhcp6.hooks`` | | related to the |
| | | management of hooks |
| | | libraries, e.g. |
| | | registration and |
| | | deregistration of the |
| | | libraries, and to the |
| | | initialization of the |
| | | callouts execution |
| | | for various hook |
| | | points within the |
| | | DHCP server. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.host-cmds | libdhcp_host_cmds | This logger is used |
| -hooks``, | premium hook library | to log messages |
| ``kea-dhcp6.host-cmds | | related to the |
| -hooks`` | | operation of the Host |
| | | Cmds hooks library. |
| | | In general, these |
| | | will pertain to the |
| | | loading and unloading |
| | | of the library and |
| | | the execution of |
| | | commands by the |
| | | library. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.hosts``, | core | Used within the |
| ``kea-dhcp6.hosts`` | | libdhcpsrv, it logs |
| | | messages related to |
| | | the management of the |
| | | DHCP host |
| | | reservations, i.e. |
| | | retrieval of the |
| | | reservations and |
| | | adding new |
| | | reservations. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.lease-cmd | libdhcp_lease_cmds | This logger is used |
| s-hooks``, | hook library | to log messages |
| ``kea-dhcp6.lease-cmd | | related to the |
| s-hooks`` | | operation of the |
| | | Lease Cmds hooks |
| | | library. In general, |
| | | these will pertain to |
| | | the loading and |
| | | unloading of the |
| | | library and the |
| | | execution of commands |
| | | by the library. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.leases``, | core | Used by the DHCP |
| ``kea-dhcp6.leases`` | | server to log |
| | | messages related to |
| | | lease allocation. The |
| | | messages include |
| | | detailed information |
| | | about the allocated |
| | | or offered leases, |
| | | errors during the |
| | | lease allocation, |
| | | etc. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.legal-log | libdhcp_legal_log | This logger is used |
| -hooks``, | premium hook library | to log messages |
| ``kea-dhcp6.legal-log | | related to the |
| -hooks`` | | operation of the |
| | | Forensic Logging |
| | | Hooks Library. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.options`` | core | Used by the DHCP |
| , | | server to log |
| ``kea-dhcp4.options`` | | messages related to |
| | | the processing of |
| | | options in the DHCP |
| | | messages, i.e. |
| | | parsing options, |
| | | encoding options into |
| | | on-wire format, and |
| | | packet classification |
| | | using options |
| | | contained in the |
| | | received packets. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.packets`` | core | This logger is mostly |
| , | | used to log messages |
| ``kea-dhcp6.packets`` | | related to |
| | | transmission of the |
| | | DHCP packets, i.e. |
| | | packet reception and |
| | | the sending of a |
| | | response. Such |
| | | messages include |
| | | information about the |
| | | source and |
| | | destination IP |
| | | addresses and |
| | | interfaces used to |
| | | transmit packets. The |
| | | logger is also used |
| | | to log messages |
| | | related to subnet |
| | | selection, as this |
| | | selection is usually |
| | | based on the IP |
| | | addresses, relay |
| | | addresses, and/or |
| | | interface names, |
| | | which can be |
| | | retrieved from the |
| | | received packet even |
| | | before the DHCP |
| | | message carried in |
| | | the packet is parsed. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.radius-ho | libdhcp_radius | This logger is used |
| oks``, | premium hook library | to log messages |
| ``kea-dhcp6.radius-ho | | related to the |
| oks`` | | operation of the |
| | | Radius Hook Library. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.stat-cmds | libdhcp_stat_cmds | This logger is used |
| -hooks``, | hook library | to log messages |
| ``kea-dhcp6.stat-cmds | | related to the |
| -hooks`` | | operation of the |
| | | Statistics Commands |
| | | hooks library. In |
| | | general, these will |
| | | pertain to loading |
| | | and unloading the |
| | | library and the |
| | | execution of commands |
| | | by the library. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.subnet-cm | libdhcp_subnet_cmds | This logger is used |
| ds-hooks``, | hook library | to log messages |
| ``kea-dhcp6.subnet-cm | | related to the |
| ds-hooks`` | | operation of the |
| | | Subnet Commands hooks |
| | | library. In general, |
| | | these will pertain to |
| | | loading and unloading |
| | | the library and the |
| | | execution of commands |
| | | by the library. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp4.mysql-cb- | libdhcp_mysql_cb_hook | This logger is used |
| hooks``, | s | to log messages |
| ``kea-dhcp6.mysql-cb- | hook library | related to the |
| hooks`` | | operation of the |
| | | MySQL Configuration |
| | | Backend hooks |
| | | library. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp-ddns`` | core | The root logger for |
| | | the kea-dhcp-ddns |
| | | daemon. All |
| | | components used by |
| | | this daemon inherit |
| | | the settings from |
| | | this logger unless |
| | | there are |
| | | configurations for |
| | | more specialized |
| | | loggers.. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp-ddns.dctl` | core | The logger used by |
| ` | | the kea-dhcp-ddns |
| | | daemon for logging |
| | | basic information |
| | | about the process, |
| | | received signals, and |
| | | triggered |
| | | reconfigurations. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp-ddns.dhcpd | core | The logger used by |
| dns`` | | the kea-dhcp-ddns |
| | | daemon for logging |
| | | events related to |
| | | DDNS operations. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp-ddns.dhcp- | core | Used by the |
| to-d2`` | | kea-dhcp-ddns daemon |
| | | for logging |
| | | information about |
| | | events dealing with |
| | | receiving messages |
| | | from the DHCP servers |
| | | and adding them to |
| | | the queue for |
| | | processing. |
+-----------------------+-----------------------+-----------------------+
| ``kea-dhcp-ddns.d2-to | core | Used by the |
| -dns`` | | kea-dhcp-ddns daemon |
| | | for logging |
| | | information about |
| | | events dealing with |
| | | sending and receiving |
| | | messages with the DNS |
| | | servers. |
+-----------------------+-----------------------+-----------------------+
| ``kea-netconf`` | core | The root logger for |
| | | the Netconf agent. |
| | | All components used |
| | | by Netconf inherit |
| | | the settings from |
| | | this logger if there |
| | | is no specialized |
| | | logger provided. |
+-----------------------+-----------------------+-----------------------+
+----------------------------------+------------------------+-----------------------+
| Logger Name | Software Package | Description |
+==================================+========================+=======================+
| ``kea-ctrl-agent`` | core | The root logger for |
| | | the Control Agent |
| | | exposing the RESTful |
| | | control API. All |
| | | components used by |
| | | the Control Agent |
| | | inherit the settings |
| | | from this logger. |
+----------------------------------+------------------------+-----------------------+
| ``kea-ctrl-agent.http`` | core | A logger which |
| | | outputs log messages |
| | | related to receiving, |
| | | parsing, and sending |
| | | HTTP messages. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4`` | core | The root logger for |
| | | the DHCPv4 server. |
| | | All components used |
| | | by the DHCPv4 server |
| | | inherit the settings |
| | | from this logger. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp6`` | core | The root logger for |
| | | the DHCPv6 server. |
| | | All components used |
| | | by the DHCPv6 server |
| | | inherit the settings |
| | | from this logger. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.alloc-engine``, | core | Used by the lease |
| ``kea-dhcp6.alloc-engine`` | | allocation engine, |
| | | which is responsible |
| | | for managing leases |
| | | in the lease |
| | | database, i.e. |
| | | creating, modifying, |
| | | and removing DHCP |
| | | leases as a result of |
| | | processing messages |
| | | from clients. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.bad-packets``, | core | Used by the DHCP |
| ``kea-dhcp6.bad-packets`` | | servers for logging |
| | | inbound client |
| | | packets that were |
| | | dropped or to which |
| | | the server responded |
| | | with a DHCPNAK. It |
| | | allows administrators |
| | | to configure a |
| | | separate log output |
| | | that contains only |
| | | packet drop and |
| | | reject entries. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.callouts``, | core | Used to log messages |
| ``kea-dhcp6.callouts`` | | pertaining to the |
| | | callouts registration |
| | | and execution for the |
| | | particular hook |
| | | point. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.commands``, | core | Used to log messages |
| ``kea-dhcp6.commands`` | | relating to the |
| | | handling of commands |
| | | received by the DHCP |
| | | server over the |
| | | command channel. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.database``, | core | Used to log messages |
| ``kea-dhcp6.database`` | | relating to general |
| | | operations on the |
| | | relational databases |
| | | and Cassandra. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.ddns``, | core | Used by the DHCP |
| ``kea-dhcp6.ddns`` | | server to log |
| | | messages related to |
| | | Client FQDN and |
| | | Hostname option |
| | | processing. It also |
| | | includes log messages |
| | | related to the |
| | | relevant DNS updates. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.dhcp4`` | core | Used by the DHCPv4 |
| | | server daemon to log |
| | | basic operations. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.dhcpsrv``, | core | The base loggers for |
| ``kea-dhcp6.dhcpsrv`` | | the libkea-dhcpsrv |
| | | library. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.eval``, | core | Used to log messages |
| ``kea-dhcp6.eval`` | | relating to the |
| | | client classification |
| | | expression evaluation |
| | | code. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.host-cache-hooks``, | libdhcp_host_cache | This logger is used |
| ``kea-dhcp6.host-cache-hooks`` | premium hook library | to log messages |
| | | related to the |
| | | operation of the Host |
| | | Cache hooks library. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.flex-id-hooks``, | libdhcp_flex_id | This logger is used |
| ``kea-dhcp6.flex-id-hooks`` | premium hook library | to log messages |
| | | related to the |
| | | operation of the |
| | | Flexible Identifiers |
| | | hooks library. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.ha-hooks``, | libdhcp_ha hook | This logger is used |
| ``kea-dhcp6.ha-hooks`` | library | to log messages |
| | | related to the |
| | | operation of the High |
| | | Availability hooks |
| | | library. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.hooks``, | core | Used to log messages |
| ``kea-dhcp6.hooks`` | | related to the |
| | | management of hooks |
| | | libraries, e.g. |
| | | registration and |
| | | deregistration of the |
| | | libraries, and to the |
| | | initialization of the |
| | | callouts execution |
| | | for various hook |
| | | points within the |
| | | DHCP server. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.host-cmds-hooks``, | libdhcp_host_cmds | This logger is used |
| ``kea-dhcp6.host-cmds-hooks`` | premium hook library | to log messages |
| | | related to the |
| | | operation of the Host |
| | | Commands hooks |
| | | library. In general, |
| | | these will pertain to |
| | | the loading and |
| | | unloading of the |
| | | library and the |
| | | execution of commands |
| | | by the library. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.hosts``, | core | Used within the |
| ``kea-dhcp6.hosts`` | | libdhcpsrv, it logs |
| | | messages related to |
| | | the management of |
| | | DHCP host |
| | | reservations, i.e. |
| | | retrieving |
| | | reservations and |
| | | adding new |
| | | reservations. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.lease-cmds-hooks``, | libdhcp_lease_cmds | This logger is used |
| ``kea-dhcp6.lease-cmds-hooks`` | hook library | to log messages |
| | | related to the |
| | | operation of the |
| | | Lease Commands hooks |
| | | library. In general, |
| | | these will pertain to |
| | | the loading and |
| | | unloading of the |
| | | library and the |
| | | execution of commands |
| | | by the library. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.leases``, | core | Used by the DHCP |
| ``kea-dhcp6.leases`` | | server to log |
| | | messages related to |
| | | lease allocation. The |
| | | messages include |
| | | detailed information |
| | | about the allocated |
| | | or offered leases, |
| | | errors during the |
| | | lease allocation, |
| | | etc. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.legal-log-hooks``, | libdhcp_legal_log | This logger is used |
| ``kea-dhcp6.legal-log-hooks`` | premium hook library | to log messages |
| | | related to the |
| | | operation of the |
| | | Forensic Logging |
| | | hooks library. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.options``, | core | Used by the DHCP |
| ``kea-dhcp4.options`` | | server to log |
| | | messages related to |
| | | the processing of |
| | | options in the DHCP |
| | | messages, i.e. |
| | | parsing options, |
| | | encoding options into |
| | | on-wire format, and |
| | | packet classification |
| | | using options |
| | | contained in the |
| | | received packets. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.packets``, | core | This logger is mostly |
| ``kea-dhcp6.packets`` | | used to log messages |
| | | related to |
| | | transmission of the |
| | | DHCP packets, i.e. |
| | | packet reception and |
| | | the sending of a |
| | | response. Such |
| | | messages include |
| | | information about the |
| | | source and |
| | | destination IP |
| | | addresses and |
| | | interfaces used to |
| | | transmit packets. The |
| | | logger is also used |
| | | to log messages |
| | | related to subnet |
| | | selection, as this |
| | | selection is usually |
| | | based on the IP |
| | | addresses, relay |
| | | addresses, and/or |
| | | interface names, |
| | | which can be |
| | | retrieved from the |
| | | received packet even |
| | | before the DHCP |
| | | message carried in |
| | | the packet is parsed. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.radius-hooks``, | libdhcp_radius | This logger is used |
| ``kea-dhcp6.radius-hooks`` | premium hook library | to log messages |
| | | related to the |
| | | operation of the |
| | | RADIUS hooks library. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.stat-cmds-hooks``, | libdhcp_stat_cmds | This logger is used |
| ``kea-dhcp6.stat-cmds-hooks`` | hook library | to log messages |
| | | related to the |
| | | operation of the |
| | | Statistics Commands |
| | | hooks library. In |
| | | general, these will |
| | | pertain to loading |
| | | and unloading the |
| | | library and the |
| | | execution of commands |
| | | by the library. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.subnet-cmds-hooks``, | libdhcp_subnet_cmds | This logger is used |
| ``kea-dhcp6.subnet-cmds-hooks`` | hook library | to log messages |
| | | related to the |
| | | operation of the |
| | | Subnet Commands hooks |
| | | library. In general, |
| | | these will pertain to |
| | | loading and unloading |
| | | the library and the |
| | | execution of commands |
| | | by the library. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp4.mysql-cb-hooks``, | libdhcp_mysql_cb_hooks | This logger is used |
| ``kea-dhcp6.mysql-cb-hooks`` | hook library | to log messages |
| | | related to the |
| | | operation of the |
| | | MySQL Configuration |
| | | Backend hooks |
| | | library. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp-ddns`` | core | The root logger for |
| | | the kea-dhcp-ddns |
| | | daemon. All |
| | | components used by |
| | | this daemon inherit |
| | | the settings from |
| | | this logger unless |
| | | there are |
| | | configurations for |
| | | more specialized |
| | | loggers. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp-ddns.dctl`` | core | The logger used by |
| | | the kea-dhcp-ddns |
| | | daemon for logging |
| | | basic information |
| | | about the process, |
| | | received signals, and |
| | | triggered |
| | | reconfigurations. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp-ddns.dhcpddns`` | core | The logger used by |
| | | the kea-dhcp-ddns |
| | | daemon for logging |
| | | events related to |
| | | DDNS operations. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp-ddns.dhcp-to-d2`` | core | Used by the |
| | | kea-dhcp-ddns daemon |
| | | for logging |
| | | information about |
| | | events dealing with |
| | | receiving messages |
| | | from the DHCP servers |
| | | and adding them to |
| | | the queue for |
| | | processing. |
+----------------------------------+------------------------+-----------------------+
| ``kea-dhcp-ddns.d2-to-dns`` | core | Used by the |
| | | kea-dhcp-ddns daemon |
| | | for logging |
| | | information about |
| | | events dealing with |
| | | sending and receiving |
| | | messages to and from |
| | | the DNS servers. |
+----------------------------------+------------------------+-----------------------+
| ``kea-netconf`` | core | The root logger for |
| | | the NETCONF agent. |
| | | All components used |
| | | by NETCONF inherit |
| | | the settings from |
| | | this logger if there |
| | | is no specialized |
| | | logger provided. |
+----------------------------------+------------------------+-----------------------+
Note that user-defined hook libraries should not use any of the loggers
mentioned above, but should instead define new loggers with names that
correspond to the libraries using them. Suppose that the user created
the library called “libdhcp-packet-capture” to dump packets received and
transmitted by the server to the file. An appropriate name for the
correspond to the libraries using them. Suppose that a user created
a library called “libdhcp-packet-capture” to dump packets received and
transmitted by the server to a file. An appropriate name for the
logger could be ``kea-dhcp4.packet-capture-hooks``. (Note that the hook
library implementer only specifies the second part of this name, i.e.
“packet-capture”. The first part is a root-logger name and is prepended
@ -472,11 +470,11 @@ from the root logger, something that can be overridden by an entry in
the configuration file.
The easiest way to find a logger name is to configure all logging to go
to a single destination and look for specific logger names. See `Logging
Message Format <#logging-message-format>`__ for details.
to a single destination and look there for specific logger names. See
:ref:`logging-message-format` for details.
severity (string)
~~~~~~~~~~~~~~~~~
The severity (string) Logger
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This specifies the category of messages logged. Each message is logged
with an associated severity, which may be one of the following (in
@ -504,56 +502,56 @@ logger are inhibited.
**Note**
The keactrl tool, described in `??? <#keactrl>`__, can be configured
The ``keactrl`` tool, described in :ref:`keactrl`, can be configured
to start the servers in verbose mode. If this is the case, the
settings of the logging severity in the configuration file will have
no effect, i.e. the servers will use a logging severity of DEBUG
no effect; the servers will use a logging severity of DEBUG
regardless of the logging settings specified in the configuration
file. If you need to control severity via the configuration file,
file. To control severity via the configuration file,
please make sure that the ``kea_verbose`` value is set to "no" within
the keactrl configuration.
the ``keactrl`` configuration.
debuglevel (integer)
~~~~~~~~~~~~~~~~~~~~
The debuglevel (integer) Logger
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When a logger's severity is set to DEBUG, this value specifies what
level of debug messages should be printed. It ranges from 0 (least
verbose) to 99 (most verbose). If severity for the logger is not DEBUG,
this value is ignored.
output_options (list)
~~~~~~~~~~~~~~~~~~~~~
The output_options (list) Logger
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each logger can have zero or more ``output_options``. These specify
where log messages are sent and are explained in detail below.
output (string)
^^^^^^^^^^^^^^^
The output (string) Option
^^^^^^^^^^^^^^^^^^^^^^^^^^
This value determines the type of output. There are several special
values allowed here: ``stdout`` (messages are printed on standard
output), ``stderr`` (messages are printed on stderr), ``syslog``
(messages are logged to syslog using default name), ``syslog:name``
(messages are logged to syslog using specified name). Any other value is
(messages are logged to syslog using the default name), ``syslog:name``
(messages are logged to syslog using a specified name). Any other value is
interpreted as a filename to which messages should be written.
flush (true of false)
^^^^^^^^^^^^^^^^^^^^^
The flush (true of false) Option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Flush buffers after each log message. Doing this will reduce performance
but will ensure that if the program terminates abnormally, all messages
up to the point of termination are output. The default is "true".
maxsize (integer)
^^^^^^^^^^^^^^^^^
The maxsize (integer) Option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Only relevant when the destination is a file. This is the maximum size
This option is only relevant when the destination is a file; this is the maximum size
in bytes that a log file may reach. When the maximum size is reached,
the file is renamed and a new file opened. For example, a ".1" is
appended to the name — if a ".1" file exists, it is renamed ".2", etc.
appended to the name; if a ".1" file exists, it is renamed ".2", etc.
This is referred to as rotation.
The default value is 10240000 (10MB). The smallest value that may be
The default value is 10240000 (10MB). The smallest value that can be
specified without disabling rotation is 204800. Any value less than
this, including 0, disables rotation.
@ -561,18 +559,18 @@ this, including 0, disables rotation.
Due to a limitation of the underlying logging library (log4cplus),
rolling over the log files (from ".1" to ".2", etc) may show odd
results; there can be multiple small files at the timing of roll
over. This can happen when multiple processes try to roll over the
results; there can be multiple small files at the timing of rollover.
This can happen when multiple processes try to roll over the
files simultaneously. Version 1.1.0 of log4cplus solved this problem,
so if this version or later of log4cplus is used to build Kea, the
issue should not occur. Even for older versions, it is normally
expected to happen rarely unless the log messages are produced very
frequently by multiple different processes.
maxver (integer)
^^^^^^^^^^^^^^^^
The maxver (integer) Option
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Only relevant when the destination is a file and rotation is enabled
This option is only relevant when the destination is a file and rotation is enabled
(i.e. maxsize is large enough). This is the 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
@ -582,7 +580,7 @@ maxver rotated files. The minimum and default value is 1.
Example Logger Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In this example we want to set the Server logging to write to the
In this example we want to set the server logging to write to the
console using standard output.
::
@ -602,7 +600,7 @@ console using standard output.
}
In this second example, we want to store debug log messages in a file
that is at most 2MB and keep up to 8 copies of old logfiles. Once the
that is at most 2MB and keep up to eight copies of old logfiles. Once the
logfile grows to 2MB, it will be renamed and a new file will be created.
::
@ -625,6 +623,8 @@ logfile grows to 2MB, it will be renamed and a new file will be created.
]
}
.. _logging-message-format:
Logging Message Format
----------------------
@ -658,15 +658,14 @@ INFO
process generating the message (in this case, ``kea-dhcp4``) and the
component within the program from which the message originated
(``dhcpsrv``, which is the name of the common library used by DHCP
server implementations). The number after the slash is a process id
(pid).
server implementations). The number after the slash is a process ID
(PID).
DHCPSRV_MEMFILE_DB
The message identification. Every message in Kea has a unique
identification, which can be used as an index into the `Kea Messages
Manual <kea-messages.html>`__
(https://jenkins.isc.org/job/Kea_doc/messages/kea-messages.html) from
which more information can be obtained.
identification, which can be used as an index to the `Kea Messages
Manual <https://jenkins.isc.org/job/Kea_doc/messages/kea-messages.html>`__,
where more information can be obtained.
opening memory file lease database: type=memfile universe=4
A brief description. Within this text, information relating to the
@ -680,7 +679,7 @@ Logging During Kea Startup
--------------------------
The logging configuration is specified in the configuration file.
However, when Kea starts, the file is not read until partway into the
However, when Kea starts, the configuration file is not read until partway into the
initialization process. Prior to that, the logging settings are set to
default values, although it is possible to modify some aspects of the
settings by means of environment variables. Note that in the absence of
@ -693,14 +692,14 @@ of logging during startup:
KEA_LOCKFILE_DIR
Specifies a directory where the logging system should create its lock
file. If not specified, it is prefix/var/run/kea, where prefix
file. If not specified, it is prefix/var/run/kea, where "prefix"
defaults to /usr/local. This variable must not end with a slash.
There is one special value: "none", which instructs Kea to not create
There is one special value: "none", which instructs Kea not to create
a lock file at all. This may cause issues if several processes log to
the same file.
KEA_LOGGER_DESTINATION
Specifies logging output. There are several special values.
Specifies logging output. There are several special values:
stdout
Log to standard output.

116
doc/guide/netconf.rst
View File

@ -38,20 +38,16 @@ packages, the installation procedure is much simpler on Ubuntu.
Installing NETCONF on Ubuntu 18.04
----------------------------------
For detailed installation instructions see the `
Ubuntu installation notes page <
Ubuntu installation notes page>`__.
For detailed installation instructions, see the `Ubuntu installation notes page <https://gitlab.isc.org/isc-projects/kea/wikis/docs/ubuntu-installation-notes>`__.
.. _netconf-centos-install:
Installing NETCONF on CentOS 7.5
--------------------------------
For detailed installation instructions see the `
CentOS installation notes page <
CentOS installation notes page>`__.
For detailed installation instructions, see the `CentOS installation notes page <https://gitlab.isc.org/isc-projects/kea/wikis/docs/centos-installation-notes>`__.
CentOS 7.5's gcc compiler (version 4.8.5) is very old. Some sysrepo
CentOS 7.5's gcc compiler (version 4.8.5) is very old. Some Sysrepo
dependencies require at least version 4.9, which unfortunately means
that a new compiler has to be installed. Also, many of the Sysrepo
dependencies are not avalable in CentOS as packages, so for the time
@ -61,10 +57,8 @@ Quick Sysrepo Overview
======================
This section offers a rather brief overview of a subset of available
functions in Sysrepo. For more complete information, see the Sysrepo
homepage. You may also want to take a look at the `
notes made during a series of IETF Hackathons <
notes made during a series of IETF Hackathons>`__.
functions in Sysrepo. For more complete information, see the `Sysrepo
homepage <https://www.sysrepo.org>`__.
In YANG, configurations and state data are described in the YANG syntax
in module files named: ``"module-name"``\ ``[@"revision"]``.yang
@ -73,7 +67,7 @@ The revision part is optional and has YYYY-MM-DD format. An alternate
XML syntax YIN is defined but less user-friendly. Top-level modules are
named in Kea models (a short version of schema models).
List currently installed YANG modules:
To list the currently installed YANG modules:
::
@ -106,7 +100,7 @@ model, a similar initiative in the past for DHCPv4 failed. Therefore,
Kea uses its own dedicated models for DHCPv4 and DHCPv6 but partially
supports the IETF model for DHCPv6. Those three models have extra
modules as dependencies. The dependency modules are also provided in
``src/share/yang/modules`` in sources and ``share/kea/yang/modules``
``src/share/yang/modules`` in sources and in ``share/kea/yang/modules``
after installation.
To install modules from sources, do the following:
@ -120,7 +114,7 @@ To install modules from sources, do the following:
...
Note that the first -s parameter specifies the location of the YANG
schema repository; you can check it with sysrepoctl -l. This is a
schema repository; it can be verified with sysrepoctl -l. This is a
parameter that is configured during Sysrepo compilation and is detected
by the Kea configuration under the SYSREPO_REPO name.
@ -151,8 +145,8 @@ The installation should look similar to the following:
Notifying sysrepo about the change...
Install operation completed successfully.
You can confirm whether the models are imported correctly by using
sysrepoctl -l
It is possible to confirm whether the models are imported correctly by using
sysrepoctl -l:
::
@ -188,7 +182,7 @@ by:
If the module is used (i.e. imported) by other modules, it can be
uninstalled only after those modules have finished using it.
Installation and uninstallation must be done in dependency order and
reverse dependency order accordingly.
reverse-dependency order accordingly.
.. _netconf-models:
@ -197,7 +191,7 @@ Supported YANG Models
The only currently supported models are ``kea-dhcp4-server`` and
``kea-dhcp6-server``. There is partial support for
``ietf-dhcpv6-server``, but the primary focus of testing was on Kea DHCP
``ietf-dhcpv6-server``, but the primary focus of testing has been on Kea DHCP
servers. Several other models (``kea-dhcp-ddns`` and ``kea-ctrl-agent``)
are currently not supported.
@ -215,9 +209,9 @@ The NETCONF agent follows this algorithm:
sessions with the startup and running datastores.
- Check that used (not essential) and required (essential) modules are
installed in the sysrepo repository at the right revision. If an
essential module, i.e. a module where the configuration schema for a
managed server is defined, is not installed, raise a fatal error.
installed in the Sysrepo repository at the right revision. If an
essential module - that is, a module where the configuration schema for a
managed server is defined - is not installed, raise a fatal error.
- For each managed server, get the YANG configuration from the startup
datastore, translate it to JSON, and load it onto the server being
@ -234,27 +228,27 @@ The NETCONF agent follows this algorithm:
Configuration
=============
The behavior described in `Using the NETCONF Agent <#using-netconf>`__
The behavior described in :ref:`using-netconf`
is controlled by a few configuration flags, which can be set in the
global scope or in a specific managed-server scope. In the second case,
the value defined in the managed-server scope takes precedence. These
flags are:
- The ``boot-update`` controls the initial configuration phase; when
- ``boot-update`` - controls the initial configuration phase; when
true (the default), the initial configuration retrieved from the
classic Kea server JSON configuration file is loaded first, and then
the startup YANG model is loaded. This setting lets administrators
define a control socket in the local JSON file and then download the
configuration from YANG. When set to false, this phase is skipped.
- The ``subscribe-changes`` command controls the module change
- ``subscribe-changes`` - controls the module change
subscription; when true (the default), a module change callback is
subscribed, but when false the phase is skipped and running
configuration updates are disabled. When set to true, the running
datastore is used to subscribe for changes.
- The ``validate-changes`` command controls how Kea monitors changes in
the Sysrepo configuration. Sysrepo offers two stages where Kea could
- ``validate-changes`` - controls how Kea monitors changes in
the Sysrepo configuration. Sysrepo offers two stages where Kea can
interact: validation and application. At the validation (or
SR_EV_VERIFY event, in the Sysrepo naming convention) stage, Kea
retrieves the newly committed configuration and verifies it. If the
@ -284,14 +278,14 @@ making them manageable. For instance, for the DHCPv4 server:
Note the alternative to boot with full configurations does not allow
easy tracking of changes or synchronization between the JSON and YANG
configuration sources; therefore, that setup is not really compatible
with the YANG / NETCONF configuration management paradigm, where
with the YANG/NETCONF configuration management paradigm, where
everything should be performed in YANG.
With module change subscriptions enabled, the kea-netconf daemon will
monitor any configuration changes as they appear in the Sysrepo. Such
changes can be done using the ``sysrepocfg`` tool or remotely using any
NETCONF client. For details, please see the Sysrepo documentation or
`Step-by-Step NETCONF Agent Operation Example <#operation-example>`__.
:ref:`operation-example`.
Those tools can be used to modify YANG configurations in the running
datastore. Note that committed configurations are only updated in the
running datastore; to keep them between server reboots they must be
@ -302,7 +296,7 @@ true) and the running configuration has changed (e.g. using
``sysrepocfg`` or any NETCONF client), the callback validates the
modified configuration (if ``validate-changes`` was not set to false)
and runs a second time to apply the new configuration. If the validation
fails, the callback is still called again but with an ABORT (vs APPLY)
fails, the callback is still called again but with an ABORT (vs. APPLY)
event with rollback changes.
The returned code of the callback on an APPLY event is ignored, as it is
@ -311,18 +305,18 @@ too late to refuse a bad configuration.
There are four ways in which a modified YANG configuration could
possibly be incorrect:
1. It can be non-compliant with the schema, e.g. unknown entry, missing
mandatory entry, value with a bad type, or not matching a constraint.
1. It can be non-compliant with the schema, e.g. an unknown entry, missing a
mandatory entry, a value with a bad type, or not matching a constraint.
2. It can fail to be translated from YANG to JSON, e.g. invalid user
2. It can fail to be translated from YANG to JSON, e.g. an invalid user
context.
3. It can fail Kea server sanity checks, e.g. out-of-subnet-pool range
or unsupported database type.
3. It can fail Kea server sanity checks, e.g. an out-of-subnet-pool range
or an unsupported database type.
4. The syntax is correct and passes server sanity checks but the
4. The syntax may be correct and pass server sanity checks but the
configuration fails to run, e.g. the configuration specifies database
credentials, but the database refuses connection.
credentials but the database refuses the connection.
The first case is handled by Sysrepo. The second and third cases are
handled by kea-netconf in the validation phase (if not disabled by
@ -337,29 +331,30 @@ agent).
Each managed server entry contains optionally:
- ``boot-update``, ``subscribe-changes``, and ``validate-changes``
- ``boot-update``, ``subscribe-changes``, and ``validate-changes`` -
control flags.
- ``model`` specifies the YANG model / module name. For each service,
- ``model`` - specifies the YANG model / module name. For each service,
the default is the corresponding Kea YANG model, e.g. for ``"dhcp4"``
it is ``"kea-dhcp4-server"``.
- ``control-socket`` specifies the control socket for managing the
- ``control-socket`` - specifies the control socket for managing the
service configuration.
A control socket is specified by:
- ``socket-type``: the socket type is either ``stdout`` (the default;
- ``socket-type`` - the socket type is either ``stdout``, ``unix``, or ``http``.
``stdout`` is the default;
it is not really a socket, but it allows ``kea-netconf`` to run in
debugging mode where everything is printed on stdout. Can be also
useful to redirect commands easily.), ``unix`` (standard direct
server control channel, which uses UNIX sockets), and ``http`` (using
a control agent, which accepts HTTP connections).
debugging mode where everything is printed on stdout, and it can also be
used to redirect commands easily. ``unix`` is the standard direct
server control channel, which uses UNIX sockets, and ``http`` uses
a control agent, which accepts HTTP connections.
- ``socket-name``: the local socket name for the ``unix`` socket type
- ``socket-name`` - the local socket name for the ``unix`` socket type
(default empty string).
- ``socket-url``: the HTTP URL for the ``http`` socket type (default
- ``socket-url`` - the HTTP URL for the ``http`` socket type (default
``http://127.0.0.1:8000/``).
User contexts can store arbitrary data as long as they are in valid JSON
@ -374,14 +369,14 @@ servers or agents; however, currently no hook points are defined. The
should be loaded by kea-netconf, along with their configuration
information specified with ``parameters``.
Please consult `??? <#logging>`__ for the details on how to configure
Please consult :ref:`logging` for details on how to configure
logging. The NETCONF agent's root logger's name is ``kea-netconf``, as
given in the example above.
.. _netconf-example:
kea-netconf Configuration Example
=================================
A kea-netconf Configuration Example
===================================
The following example demonstrates the basic NETCONF configuration. More
examples are available in the ``doc/examples/netconf`` directory in the
@ -395,7 +390,7 @@ Kea sources.
"Netconf":
{
// Control flags can be defined in the global scope or
// in a managed server scope. Precedence are:
// in a managed server scope. Precedences are:
// - use the default value (true)
// - use the global value
// - use the local value.
@ -409,7 +404,7 @@ Kea sources.
// "stdout" which outputs the configuration on the standard output,
// "unix" which uses the local control channel supported by the
// "dhcp4" and "dhcp6" servers ("d2" support is not yet available),
// and "http" which uses the Control agent "ca" to manage itself or
// and "http" which uses the Control Agent "ca" to manage itself or
// to forward commands to "dhcp4" or "dhcp6".
"managed-servers":
{
@ -448,7 +443,7 @@ Kea sources.
}
},
// Of course the Control Agent (nicknamed CA) supports HTTP.
// Of course the Control Agent (CA) supports HTTP.
"ca":
{
"model": "kea-ctrl-agent",
@ -478,7 +473,7 @@ Kea sources.
}
],
// Similar to other Kea components, Netconf also uses logging.
// Similar to other Kea components, NETCONF also uses logging.
"loggers": [
{
"name": "kea-netconf",
@ -540,8 +535,8 @@ kea-netconf accepts the following command-line switches:
.. _operation-example:
Step-by-Step NETCONF Agent Operation Example
============================================
A Step-by-Step NETCONF Agent Operation Example
==============================================
**Note**
@ -639,7 +634,7 @@ The following is the example ``netconf.json`` configuration for
}
}
Note that in production you should not need to log at the DEBUG level.
Note that in production there should not be a need to log at the DEBUG level.
The Kea NETCONF agent is launched by:
@ -730,7 +725,7 @@ configuration file:
</control-socket>
</config>
is directly rejected by ``sysrepocfg``:
It is directly rejected by ``sysrepocfg``:
::
@ -788,7 +783,7 @@ server and fails to validate as in this ``BAD-config.xml`` file:
In the last case, the misconfiguration is detected too late and the
change must be reverted in Sysrepo, e.g. using the startup datastore as
a backup. For this reason, please use the ``sysrepocfg`` ``--permanent``
/ ``-p`` option (or a similar feature of NETCONF clients) with care.
/ ``-p`` option (or any similar feature of NETCONF clients) with care.
.. _operation-example-2pools:
@ -956,6 +951,5 @@ Finally, any of the previous examples can be replayed using
# sysrepocfg -d running -f xml -e vi kea-dhcp6-server
or, of course, using a NETCONF client like ``netopeer2-cli`` from the `
Netopeer2 <
Netopeer2>`__ NETCONF Toolset.
or, of course, using a NETCONF client like ``netopeer2-cli`` from the
`Netopeer2 <https://github.com/CESNET/Netopeer2>`__ NETCONF Toolset.

4
doc/guide/quickstart.rst
View File

@ -6,7 +6,7 @@ Quick Start
This section describes the basic steps needed to get Kea up and running.
For further details, full customizations, and troubleshooting, see the
respective chapters in the Kea Administrator Reference Manual (ARM).
respective chapters elsewhere in this Kea Administrator Reference Manual (ARM).
.. _quick-start:
@ -98,7 +98,7 @@ Quick Start Guide for DHCPv4 and DHCPv6 Services
For instructions specific to your system, please read the
`system-specific notes <https://kb.isc.org/docs/installing-kea>`__,
available in the `Kea section of ISC's
available in the Kea section of `ISC's
Knowledgebase <https://kb.isc.org/docs>`__.
The details of ``keactrl`` script usage can be found in

29
doc/guide/shell.rst
View File

@ -6,20 +6,20 @@ The Kea Shell
.. _shell-overview:
Overview
========
Overview of the Kea Shell
=========================
Kea 1.2.0 introduced the Control Agent (CA, see
`??? <#kea-ctrl-agent>`__), which provides a RESTful control interface
:ref:`kea-ctrl-agent`), which 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 an
administrator wants to send a command to the CA directly. The Kea shell
administrator wants to send a command to the CA directly, and the Kea shell
provides a way to do this. It is a simple command-line,
scripting-friendly, text client that is able to connect to the CA, send
it commands with parameters, retrieve the responses, and display them.
As the primary purpose of the Kea shell is as a tool in a scripting
environment, it is not interactive. However, with simple tricks it can
environment, it is not interactive. However, following simple guidelines it can
be run manually.
Shell Usage
@ -55,9 +55,9 @@ where:
Other switches are:
- ``-h`` prints a help message.
- ``-h`` - prints a help message.
- ``-v`` prints the software version.
- ``-v`` - prints the software version.
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,
@ -65,10 +65,9 @@ the shell establishes a connection with the CA using HTTP, sends the
command, and awaits a response. Once that is received, it is displayed
on standard output.
For a list of available commands, see `??? <#ctrl-channel>`__;
additional commands may be provided by hook libraries. If you are unsure
which commands are supported, use the ``list-commands`` command. It will
instruct the CA to return a list of all supported commands.
For a list of available commands, see :ref:`ctrl-channel`;
additional commands may be provided by hooks libraries. For a list of
all supported commands from the CA, use the ``list-commands`` command.
The following shows a simple example of usage:
@ -86,7 +85,7 @@ returned for the service named ``dhcp4``.
It is envisaged that the 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 (the ``--service`` parameter hasn't
the command "config-write" to the CA (the ``--service`` parameter has not
been used), along with the parameters specified in param.json. The
result will be stored in result.json.
@ -105,7 +104,7 @@ servers, the default empty path in the URL is not enough, so the
$ kea-shell --host 192.0.2.1 --port 8001 --path kea ...
Kea shell requires Python to to be installed on the system. It has been
The Kea shell requires Python to to be installed on the system. It has been
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
@ -115,6 +114,6 @@ during the installation of Kea.
The Kea shell is intended to serve more as a demonstration of the
RESTful interface's capabilities (and, perhaps, an illustration for
people interested in integrating their management environments 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
than as a serious management client. It is not likely to be
significantly expanded in the future; it is, and will remain, a simple
tool.

67
doc/guide/stats.rst
View File

@ -10,10 +10,10 @@ Statistics Overview
Both Kea DHCP servers support statistics gathering. A working DHCP
server encounters various events that can cause certain statistics to be
collected. For example, a DHCPv4 server may receive a packet
(pkt4-received statistic increases by one) that after parsing is
(the pkt4-received statistic increases by one) that after parsing is
identified as a DHCPDISCOVER (pkt4-discover-received). The server
processes it and decides to send a DHCPOFFER representing its answer
(pkt4-offer-sent and pkt4-sent statistics increase by one). Such events
(the pkt4-offer-sent and pkt4-sent statistics increase by one). Such events
happen frequently, so it is not uncommon for the statistics to have
values in the high thousands. They can serve as an easy and powerful
tool for observing a server's and a network's health. For example, if
@ -24,7 +24,7 @@ There are four types of statistics:
- *integer* - this is the most common type. It is implemented as a
64-bit integer (int64_t in C++), so it can hold any value between
-2^63 to 2^63 -1.
-2^63 to 2^63-1.
- *floating point* - this type is intended to store floating-point
precision. It is implemented as a C++ double type.
@ -38,15 +38,14 @@ There are four types of statistics:
During normal operation, the DHCPv4 and DHCPv6 servers gather
statistics. For a list of DHCPv4 and DHCPv6 statistics, see
`??? <#dhcp4-stats>`__ and `??? <#dhcp6-stats>`__, respectively.
:ref:`dhcp4-stats` and :ref:`dhcp6-stats`, respectively.
To extract data from the statistics module, the control channel can be
used. See `??? <#ctrl-channel>`__ for details. It is possible to
used. See :ref:`ctrl-channel` for details. It is possible to
retrieve a single statistic or all statistics, reset statistics (i.e.
set to neutral value, typically zero), or even remove completely a
single statistic or all statistics. See section `Commands for
Manipulating Statistics <#command-stats>`__ for a list of
statistics-oriented commands.
set to a neutral value, typically zero), or even completely remove a
single statistic or all statistics. See the section :ref:`command-stats`
for a list of statistics-oriented commands.
.. _stats-lifecycle:
@ -55,7 +54,7 @@ Statistics Lifecycle
It is useful to understand how the Statistics Manager module works. When
the server starts operation, the manager is empty and contains no
statistics. When ``statistic-get-all`` is executed, an empty list is
statistics. If the ``statistic-get-all`` command is executed at that point, an empty list is
returned. Once the server performs an operation that causes a statistic
to change, the related statistic will be created. In general, once a
statistic is recorded even once, it is kept in the manager until
@ -74,8 +73,8 @@ the near future. For example, a misconfigured device in a network may
cause clients to report duplicate addresses, so the server will report
increasing values of pkt4-decline-received. Once the problem is found
and the device is removed, the system administrator may want to remove
the pkt4-decline-received statistic, so it won't be reported anymore. If
a duplicate address is detected ever again, the server will add this
the pkt4-decline-received statistic, so it will not be reported anymore. If
a duplicate address is ever detected again, the server will add this
statistic back.
.. _command-stats:
@ -84,14 +83,14 @@ Commands for Manipulating Statistics
====================================
There are several commands defined that can be used for accessing
(-get), resetting to zero or neutral value (-reset), or even removing a
(-get), resetting to zero or a neutral value (-reset), or removing a
statistic completely (-remove). The difference between reset and remove
is somewhat subtle. The reset command sets the value of the statistic to
zero or a neutral value, so after this operation, the statistic will
have a value of 0 (integer), 0.0 (float), 0h0m0s0us (duration), or ""
(string). When requested, a statistic with the values mentioned will be
returned. ``Remove`` removes a statistic completely, so the statistic
will not be reported anymore. Please note that the server code may add
will no longer be reported. Please note that the server code may add
it back if there is a reason to record it.
**Note**
@ -99,14 +98,14 @@ it back if there is a reason to record it.
The following sections describe commands that can be sent to the
server; the examples are not fragments of a configuration file. For
more information on sending commands to Kea, see
`??? <#ctrl-channel>`__.
:ref:`ctrl-channel`.
.. _command-statistic-get:
statistic-get Command
---------------------
The statistic-get Command
-------------------------
The *statistic-get* command retrieves a single statistic. It takes a
The ``statistic-get`` command retrieves a single statistic. It takes a
single-string parameter called ``name``, which specifies the statistic
name. An example command may look like this:
@ -127,10 +126,10 @@ the status code will still indicate success (0).
.. _command-statistic-reset:
statistic-reset Command
-----------------------
The statistic-reset Command
---------------------------
The *statistic-reset* command sets the specified statistic to its
The ``statistic-reset`` command sets the specified statistic to its
neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time
duration, and "" for string type. It takes a single-string parameter
called ``name``, which specifies the statistic name. An example command
@ -153,10 +152,10 @@ and the text field contains the error description.
.. _command-statistic-remove:
statistic-remove Command
------------------------
The statistic-remove Command
----------------------------
The *statistic-remove* command attempts to delete a single statistic. It
The ``statistic-remove`` command attempts to delete a single statistic. It
takes a single-string parameter called ``name``, which specifies the
statistic name. An example command may look like this:
@ -177,10 +176,10 @@ and the text field contains the error description.
.. _command-statistic-get-all:
statistic-get-all Command
-------------------------
The statistic-get-all Command
-----------------------------
The *statistic-get-all* command retrieves all statistics recorded. An
The ``statistic-get-all`` command retrieves all statistics recorded. An
example command may look like this:
::
@ -196,10 +195,10 @@ when the total number of statistics is zero).
.. _command-statistic-reset-all:
statistic-reset-all Command
---------------------------
The statistic-reset-all Command
-------------------------------
The *statistic-reset* command sets all statistics to their neutral
The ``statistic-reset`` command sets all statistics to their neutral
values: 0 for integer, 0.0 for float, 0h0m0s0us for time duration, and
"" for string type. An example command may look like this:
@ -217,10 +216,10 @@ field contains the error description.
.. _command-statistic-remove-all:
statistic-remove-all Command
----------------------------
The statistic-remove-all Command
--------------------------------
The *statistic-remove-all* command attempts to delete all statistics. An
The ``statistic-remove-all`` command attempts to delete all statistics. An
example command may look like this:
::
@ -233,4 +232,4 @@ example command may look like this:
If the removal of all statistics is successful, the server responds with
a status of 0, indicating success, and an empty parameters field. If an
error is encountered, the server returns a status code of 1 (error) and
the text field will contain the error description.
the text field contains the error description.