.. _kea-admin:
-The ``kea-admin`` Tool
-======================
+The :iscman:`kea-admin` Tool
+============================
-To manage the databases, Kea provides the ``kea-admin`` tool. It can
+To manage the databases, Kea provides the :iscman:`kea-admin` tool. It can
initialize a new backend, check its version number, perform a backend
upgrade, and dump lease data to a text file.
-``kea-admin`` takes two mandatory parameters: ``command`` and
+:iscman:`kea-admin` takes two mandatory parameters: ``command`` and
``backend``. Additional, non-mandatory options may be specified. The
currently supported commands are:
storage capability to this backend.)
No special initialization steps are necessary for the memfile backend.
-During the first run, both ``kea-dhcp4`` and ``kea-dhcp6`` create
+During the first run, both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` create
an empty lease file if one is not present. Necessary disk-write
permission is required.
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``.
+rather than via :iscman:`kea-admin`.
To create the database:
mysql> quit
Bye
- Then use the ``kea-admin`` tool to create the database.
+ Then use the :iscman:`kea-admin` tool to create the database.
.. code-block:: console
$ kea-admin db-init mysql -u database-user -p database-password -n database-name
While it is possible to create the database from within the MySQL client, we recommend
- using the ``kea-admin`` tool as it performs some necessary validations to ensure Kea can
+ using the :iscman:`kea-admin` tool as it performs some necessary validations to ensure Kea can
access the database at runtime. Among those checks is verification that the schema does not contain
any pre-existing tables; any pre-existing tables must be removed
manually. An additional check examines the user's ability to create functions and
mysql> quit
Bye
-If the tables were not created in Step 4, run the ``kea-admin`` tool
+If the tables were not created in Step 4, run the :iscman:`kea-admin` tool
to create them now:
.. code-block:: console
$ kea-admin db-init mysql -u database-user -p database-password -n database-name
-Do not do this if the tables were created in Step 4. ``kea-admin``
+Do not do this if the tables were created in Step 4. :iscman:`kea-admin`
implements rudimentary checks; it will refuse to initialize a database
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 accidentally irretrievable mistakes by ``kea-admin``.)
+on purpose, to avoid accidentally irretrievable mistakes by :iscman:`kea-admin`.)
.. _mysql-upgrade:
$
5. At this point, create the database tables either
- using the ``kea-admin`` tool, as explained in the next section
+ using the :iscman:`kea-admin` tool, as explained in the next section
(recommended), or manually. To create the tables manually, enter the
following command. PostgreSQL will prompt the administrator to enter the
new user's password that was specified in Step 3. When the command
may be necessary to restart PostgreSQL for the changes to
take effect.
-Initialize the PostgreSQL Database Using ``kea-admin``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Initialize the PostgreSQL Database Using :iscman:`kea-admin`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the tables were not created manually, do so now by
-running the ``kea-admin`` tool:
+running the :iscman:`kea-admin` tool:
.. code-block:: console
$ kea-admin db-init pgsql -u database-user -p database-password -n database-name
-Do not do this if the tables were already created manually. ``kea-admin``
+Do not do this if the tables were already created manually. :iscman:`kea-admin`
implements rudimentary checks; it will refuse to initialize a database
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 accidentally irretrievable mistakes by ``kea-admin``.)
+on purpose, to avoid accidentally irretrievable mistakes by :iscman:`kea-admin`.)
.. _pgsql-upgrade:
specified with ``parameters``.
Please consult :ref:`logging` for the details on how to configure
-logging. The CA's root logger's name is ``kea-ctrl-agent``, as given in
+logging. The CA's root logger's name is :iscman:`kea-ctrl-agent`, as given in
the example above.
.. _agent-secure-connection:
mutually authenticated, but there is no proof they are the same as
for the HTTP authentication.
-The ``kea-shell`` tool also supports TLS.
+The :iscman:`kea-shell` tool also supports TLS.
.. _agent-launch:
Starting and Stopping the Control Agent
=======================================
-``kea-ctrl-agent`` accepts the following command-line switches:
+:iscman:`kea-ctrl-agent` accepts the following command-line switches:
- ``-c file`` - specifies the configuration file.
verbosity, e.g. when debugging.
- ``-t file`` - specifies the configuration file to be tested.
- ``kea-netconf`` attempts to load it and conducts sanity checks;
+ :iscman:`kea-netconf` attempts to load it and conducts sanity checks;
certain checks are possible only while running the actual server. The
actual status is reported with exit code (0 = configuration appears valid,
1 = error encountered). Kea prints out log messages to standard
output and error to standard error when testing the configuration.
-- ``-v`` - displays the version of ``kea-ctrl-agent`` and exits.
+- ``-v`` - displays the version of :iscman:`kea-ctrl-agent` and exits.
-- ``-V`` - displays the extended version information for ``kea-ctrl-agent``
+- ``-V`` - displays the extended version information for :iscman:`kea-ctrl-agent`
and exits. The listing includes the versions of the libraries
dynamically linked to Kea.
$ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf
-It can be started by ``keactrl`` as well (see :ref:`keactrl`).
+It can be started by :iscman:`keactrl` as well (see :ref:`keactrl`).
.. _agent-clients:
.. note::
An existing database schema must be upgraded to the latest schema
- required by the particular Kea version using the ``kea-admin`` tool,
+ required by the particular Kea version using the :iscman:`kea-admin` tool,
as described in :ref:`kea-admin`.
The ``cb_cmds`` premium hook library, which is available to ISC's paid support
communicating between DHCP servers and the DDNS update daemon.
Typical usage assumes that the servers are started from the command
-line, either directly or using a script, e.g. ``keactrl``. The
+line, either directly or using a script, e.g. :iscman:`keactrl`. The
configuration file is specified upon startup using the ``-c`` parameter.
.. _json-format:
packets to process, how to store them, and the order in which they are
processed by the server.
-The default packet queue implementation for both ``kea-dhcp4`` and ``kea-dhcp6``
+The default packet queue implementation for both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`
is a simple ring buffer. Once it reaches capacity, new packets get added
to the back of the queue by discarding packets from the front of the
queue. Rather than always discarding the newest packets, Kea now always
``isc::dhcp::PacketQueueMgr``, described in the
`Kea Developer's Guide <https://reports.kea.isc.org/dev_guide/index.html>`__.)
-Packet queue behavior is configured in both ``kea-dhcp4`` and ``kea-dhcp6``
+Packet queue behavior is configured in both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`
servers through an optional, top-level, configuration element,
``dhcp-queue-control``. Omitting this element disables packet queueing:
exists so that custom implementations can be registered (via a hook
library) and then selected. There is a default packet queue
implementation that is pre-registered during server start up:
- "kea-ring4" for ``kea-dhcp4`` and "kea-ring6" for ``kea-dhcp6``.
+ "kea-ring4" for :iscman:`kea-dhcp4` and "kea-ring6" for :iscman:`kea-dhcp6`.
- ``capacity`` - this is the maximum number of packets the
queue can hold before packets are discarded. The optimal value for
this is extremely site-dependent. The default value is 64 for both
"kea-ring4" and "kea-ring6".
-The following example enables the default packet queue for ``kea-dhcp4``,
+The following example enables the default packet queue for :iscman:`kea-dhcp4`,
with a queue capacity of 250 packets:
::
...
}
-The following example enables the default packet queue for ``kea-dhcp6``,
+The following example enables the default packet queue for :iscman:`kea-dhcp6`,
with a queue capacity of 300 packets:
::
``service`` parameter to the servers to which the commands are
forwarded:
-- ``dhcp4`` - the command is forwarded to the ``kea-dhcp4`` server.
+- ``dhcp4`` - the command is forwarded to the :iscman:`kea-dhcp4` server.
-- ``dhcp6`` - the command is forwarded to the ``kea-dhcp6`` server.
+- ``dhcp6`` - the command is forwarded to the :iscman:`kea-dhcp6` server.
-- ``d2`` - the command is forwarded to the ``kea-dhcp-ddns`` server.
+- ``d2`` - the command is forwarded to the :iscman:`kea-dhcp-ddns` server.
The server processing the incoming command sends a response of the
form:
*********************
Database Connectivity
*********************
-The Kea servers (``kea-dhcp4`` and ``kea-dhcp6``) can be configured to use a variety of
+The Kea servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`) can be configured to use a variety of
database backends for leases, hosts, and configuration. They can be
configured to support automatic recovery when connectivity is lost, via
the ``on-fail`` parameter. (The ``reconnect-wait-time`` and
Overview
========
-The DHCP-DDNS Server (``kea-dhcp-ddns``, known informally as D2) conducts
+The DHCP-DDNS Server (:iscman:`kea-dhcp-ddns`, known informally as D2) conducts
the client side of the Dynamic DNS protocol (DDNS, defined in `RFC
2136 <https://tools.ietf.org/html/rfc2136>`__) on behalf of the DHCPv4
-and DHCPv6 servers (``kea-dhcp4`` and ``kea-dhcp6`` respectively). The DHCP
+and DHCPv6 servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` respectively). The DHCP
servers construct DDNS update requests, known as NameChangeRequests
(NCRs), based on DHCP lease change events and then post them to D2. D2
attempts to match each request to the appropriate DNS server(s) and
Conflict resolution can be indirectly enabled or disabled via
the configuration parameter ``ddns-use-conflict-resolution``, supported
-by both ``kea-dhcp4`` and ``kea-dhcp6``. These servers use this parameter to
+by both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`. These servers use this parameter to
set a flag within each NameChangeRequest they send that tells D2
whether conflict resolution should be employed for that request.
By default, conflict resolution is enabled. For more details, please refer
Starting and Stopping the DHCP-DDNS Server
==========================================
-``kea-dhcp-ddns`` is the Kea DHCP-DDNS server and, due to the nature of
+:iscman:`kea-dhcp-ddns` is the Kea DHCP-DDNS server and, due to the nature of
DDNS, it runs alongside either the DHCPv4 or DHCPv6 component (or both).
Like other parts of Kea, it is a separate binary that can be run on its
-own or through ``keactrl`` (see :ref:`keactrl`). In normal
-operation, controlling ``kea-dhcp-ddns`` with ``keactrl`` is
+own or through :iscman:`keactrl` (see :ref:`keactrl`). In normal
+operation, controlling :iscman:`kea-dhcp-ddns` with :iscman:`keactrl` is
recommended; however, it is also possible to run the DHCP-DDNS server
directly. It accepts the following command-line switches:
it is embedded in the executable binary.
- ``-t file`` - specifies the configuration file to be tested.
- ``kea-dhcp-ddns`` attempts to load it and conducts sanity checks.
+ :iscman:`kea-dhcp-ddns` attempts to load it and conducts sanity checks.
Certain checks are possible only while running the actual
server. The actual status is reported with an exit code (0 =
configuration looks okay, 1 = error encountered). Kea prints out log
Configuring the DHCP-DDNS Server
================================
-Before starting the ``kea-dhcp-ddns`` module for the first time, a
+Before starting the :iscman:`kea-dhcp-ddns` module for the first time, a
configuration file must be created. The following default configuration
is a template that can be customized to individual requirements.
=======================================
It is recommended that the Kea DHCPv4 server be started and stopped
-using ``keactrl`` (described in :ref:`keactrl`); however, it is also
-possible to run the server directly via the ``kea-dhcp4`` command, which accepts
+using :iscman:`keactrl` (described in :ref:`keactrl`); however, it is also
+possible to run the server directly via the :iscman:`kea-dhcp4` command, which accepts
the following command-line switches:
- ``-c file`` - specifies the configuration file. This is the only
as a DHCPv4 server sending responses to ports other than the standard
ones is not able to handle regular DHCPv4 queries.
-- ``-t file`` - specifies a configuration file to be tested. ``kea-dhcp4``
+- ``-t file`` - specifies a configuration file to be tested. :iscman:`kea-dhcp4`
loads it, checks it, and exits. During the test, log messages are
printed to standard output and error messages to standard error. The
result of the test is reported through the exit code (0 =
comprehensive; certain checks are possible only when running the
server.
-- ``-T file`` - specifies a configuration file to be tested. ``kea-dhcp4``
+- ``-T file`` - specifies a configuration file to be tested. :iscman:`kea-dhcp4`
loads it, checks it, and exits. It performs extra checks beyond what ``-t``
offers, such as establishing database connections (for the lease backend,
host reservations backend, configuration backend, and forensic logging
According to `RFC 2131 <https://tools.ietf.org/html/rfc2131>`__,
servers should send values for T1 and T2 that are 50% and 87.5% of the
-lease lifetime, respectively. By default, ``kea-dhcp4`` does not send
+lease lifetime, respectively. By default, :iscman:`kea-dhcp4` does not send
either value; it can be configured to send values that are either specified
explicitly or that are calculated as percentages of the lease time. The
server's behavior is governed by a combination of configuration
Support for Long Options
------------------------
-The ``kea-dhcp4`` server partially supports long options (RFC3396).
+The :iscman:`kea-dhcp4` server partially supports long options (RFC3396).
Since Kea 2.1.6, the server accepts configuring long options and sub-options
(longer than 255 bytes). The options and sub-options are stored internally
in their unwrapped form and they can be processed as usual using the parser
DDNS for DHCPv4
---------------
-As mentioned earlier, ``kea-dhcp4`` can be configured to generate requests
-to the DHCP-DDNS server, ``kea-dhcp-ddns``, (referred to herein as "D2") to
+As mentioned earlier, :iscman:`kea-dhcp4` can be configured to generate requests
+to the DHCP-DDNS server, :iscman:`kea-dhcp-ddns`, (referred to herein as "D2") to
update DNS entries. These requests are known as NameChangeRequests or
NCRs. Each NCR contains the following information:
1. Connectivity Parameters
- These are parameters which specify where and how ``kea-dhcp4`` connects to
+ These are parameters which specify where and how :iscman:`kea-dhcp4` connects to
and communicates with D2. These parameters can only be specified
- within the top-level ``dhcp-ddns`` section in the ``kea-dhcp4``
+ within the top-level ``dhcp-ddns`` section in the :iscman:`kea-dhcp4`
configuration. The connectivity parameters are listed below:
- ``enable-updates``
...
}
-There are two parameters which determine if ``kea-dhcp4``
+There are two parameters which determine if :iscman:`kea-dhcp4`
can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates``
-parameter, which now only controls whether ``kea-dhcp4`` connects to D2;
+parameter, which now only controls whether :iscman:`kea-dhcp4` connects to D2;
and the new behavioral parameter, ``ddns-send-updates``, which determines
whether DDNS updates are enabled at a given level (i.e. global, shared-network,
or subnet). The following table shows how the two parameters function
for servers with numerous clients that renew often.
The second parameter added in Kea 1.9.1 is ``ddns-use-conflict-resolution``.
-The value of this parameter is passed by ``kea-dhcp4`` to D2 with each DNS update
+The value of this parameter is passed by :iscman:`kea-dhcp4` to D2 with each DNS update
request. When ``true`` (the default value), D2 employs conflict resolution,
as described in `RFC 4703 <https://tools.ietf.org/html/rfc4703>`__, when
attempting to fulfill the update request. When ``false``, D2 simply attempts
specific use cases. The best way to avoid unwanted DNS entries is to
always ensure lease changes are processed through Kea, whether they are
released, expire, or are deleted via the ``lease-del4`` command, prior to
- reassigning either FQDNs or IP addresses. Doing so causes ``kea-dhcp4``
+ reassigning either FQDNs or IP addresses. Doing so causes :iscman:`kea-dhcp4`
to generate DNS removal requests to D2.
The DNS entries Kea creates contain a value for TTL (time to live).
-The ``kea-dhcp4`` server calculates that value based on
+The :iscman:`kea-dhcp4` server calculates that value based on
`RFC 4702, Section 5 <https://tools.ietf.org/html/rfc4702#section-5>`__,
which suggests that the TTL value be 1/3 of the lease's lifetime, with
a minimum value of 10 minutes.
DHCP-DDNS Server Connectivity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-For NCRs to reach the D2 server, ``kea-dhcp4`` must be able to communicate
-with it. ``kea-dhcp4`` uses the following configuration parameters to
+For NCRs to reach the D2 server, :iscman:`kea-dhcp4` must be able to communicate
+with it. :iscman:`kea-dhcp4` uses the following configuration parameters to
control this communication:
-- ``enable-updates`` - Enables connectivity to ``kea-dhcp-ddns`` such that DDNS
+- ``enable-updates`` - Enables connectivity to :iscman:`kea-dhcp-ddns` such that DDNS
updates can be constructed and sent.
It must be ``true`` for NCRs to be generated and sent to D2.
It defaults to ``false``.
- ``server-port`` - This is the port on which D2 listens for requests. The default
value is ``53001``.
-- ``sender-ip`` - This is the IP address which ``kea-dhcp4`` uses to send requests to
- D2. The default value is blank, which instructs ``kea-dhcp4`` to select a
+- ``sender-ip`` - This is the IP address which :iscman:`kea-dhcp4` uses to send requests to
+ D2. The default value is blank, which instructs :iscman:`kea-dhcp4` to select a
suitable address.
-- ``sender-port`` - This is the port which ``kea-dhcp4`` uses to send requests to D2.
- The default value of ``0`` instructs ``kea-dhcp4`` to select a suitable port.
+- ``sender-port`` - This is the port which :iscman:`kea-dhcp4` uses to send requests to D2.
+ The default value of ``0`` instructs :iscman:`kea-dhcp4` to select a suitable port.
- ``max-queue-size`` - This is the maximum number of requests allowed to queue
while waiting to be sent to D2. This value guards against requests
they can be delivered. If the number of requests queued for
transmission reaches this value, DDNS updating is turned off
until the queue backlog has been sufficiently reduced. The intent is
- to allow the ``kea-dhcp4`` server to continue lease operations without
+ to allow the :iscman:`kea-dhcp4` server to continue lease operations without
running the risk that its memory usage grows without limit. The
default value is ``1024``.
- ``ncr-format`` - This specifies the packet format to use when sending requests to D2.
Currently only JSON format is supported.
-By default, ``kea-dhcp-ddns`` is assumed to be running on the same machine
-as ``kea-dhcp4``, and all of the default values mentioned above should be
+By default, :iscman:`kea-dhcp-ddns` is assumed to be running on the same machine
+as :iscman:`kea-dhcp4`, and all of the default values mentioned above should be
sufficient. If, however, D2 has been configured to listen on a different
address or port, these values must be altered accordingly. For example,
if D2 has been configured to listen on 192.168.1.10 port 900, the
.. _dhcpv4-d2-rules-config:
-When Does the ``kea-dhcp4`` Server Generate a DDNS Request?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When Does the :iscman:`kea-dhcp4` Server Generate a DDNS Request?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``kea-dhcp4`` server follows the behavior prescribed for DHCP servers in
+The :iscman:`kea-dhcp4` server follows the behavior prescribed for DHCP servers in
`RFC 4702 <https://tools.ietf.org/html/rfc4702>`__. It is important to keep
-in mind that ``kea-dhcp4`` makes the initial decision of when and what to
+in mind that :iscman:`kea-dhcp4` makes the initial decision of when and what to
update and forwards that information to D2 in the form of NCRs. Carrying
out the actual DNS updates and dealing with such things as conflict
resolution are within the purview of D2 itself
-(see :ref:`dhcp-ddns-server`). This section describes when ``kea-dhcp4``
+(see :ref:`dhcp-ddns-server`). This section describes when :iscman:`kea-dhcp4`
generates NCRs and the configuration parameters that can be used to
influence this decision. It assumes that both the connectivity parameter
``enable-updates`` and the behavioral parameter ``ddns-send-updates``,
are ``true``.
-In general, ``kea-dhcp4`` generates DDNS update requests when:
+In general, :iscman:`kea-dhcp4` generates DDNS update requests when:
1. A new lease is granted in response to a DHCPREQUEST;
single DDNS request - to remove its entries will be made.
As for the first case, the decisions involved when granting a new lease are
-more complex. When a new lease is granted, ``kea-dhcp4`` generates a
+more complex. When a new lease is granted, :iscman:`kea-dhcp4` generates a
DDNS update request if the DHCPREQUEST contains either the FQDN option
(code 81) or the Host Name option (code 12). If both are present, the
-server uses the FQDN option. By default, ``kea-dhcp4`` respects the
+server uses the FQDN option. By default, :iscman:`kea-dhcp4` respects the
FQDN N and S flags specified by the client as shown in the following
table:
The first row in the table above represents "client delegation." Here
the DHCP client states that it intends to do the forward DNS updates and
-the server should do the reverse updates. By default, ``kea-dhcp4``
+the server should do the reverse updates. By default, :iscman:`kea-dhcp4`
honors the client's wishes and generates a DDNS request to the D2 server
to update only reverse DNS data. The parameter
``ddns-override-client-update`` can be used to instruct the server to
override client delegation requests. When this parameter is ``true``,
-``kea-dhcp4`` disregards requests for client delegation and generates a
+:iscman:`kea-dhcp4` disregards requests for client delegation and generates a
DDNS request to update both forward and reverse DNS data. In this case,
the N-S-O flags in the server's response to the client will be 0-1-1
respectively.
(Note that the flag combination N=1, S=1 is prohibited according to `RFC
4702 <https://tools.ietf.org/html/rfc4702>`__. If such a combination is
-received from the client, the packet will be dropped by ``kea-dhcp4``.)
+received from the client, the packet will be dropped by :iscman:`kea-dhcp4`.)
To override client delegation, set the following values in the
configuration file:
The third row in the table above describes the case in which the client
requests that no DNS updates be done. The parameter
``ddns-override-no-update`` can be used to instruct the server to disregard
-the client's wishes. When this parameter is ``true``, ``kea-dhcp4``
-generates DDNS update requests to ``kea-dhcp-ddns`` even if the client
+the client's wishes. When this parameter is ``true``, :iscman:`kea-dhcp4`
+generates DDNS update requests to :iscman:`kea-dhcp-ddns` even if the client
requests that no updates be done. The N-S-O flags in the server's
response to the client will be 0-1-1.
...
}
-The ``kea-dhcp4`` server always generates DDNS update requests if the
+The :iscman:`kea-dhcp4` server always generates DDNS update requests if the
client request only contains the Host Name option. In addition, it includes
an FQDN option in the response to the client with the FQDN N-S-O flags
set to 0-1-0, respectively. The domain name portion of the FQDN option
.. _dhcpv4-fqdn-name-generation:
-``kea-dhcp4`` Name Generation for DDNS Update Requests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+:iscman:`kea-dhcp4` Name Generation for DDNS Update Requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each NameChangeRequest must of course include the fully qualified domain
-name whose DNS entries are to be affected. ``kea-dhcp4`` can be configured
+name whose DNS entries are to be affected. :iscman:`kea-dhcp4` can be configured
to supply a portion or all of that name, based on what it receives
from the client in the DHCPREQUEST.
must replace them with the desired mode name. A value of ``true``
maps to ``when-present``, while ``false`` maps to ``never``.
-For example, to instruct ``kea-dhcp4`` to always generate the FQDN for a
+For example, to instruct :iscman:`kea-dhcp4` to always generate the FQDN for a
client, set the parameter ``ddns-replace-client-name`` to ``always`` as
follows:
...
}
-When generating a name, ``kea-dhcp4`` constructs the name in the format:
+When generating a name, :iscman:`kea-dhcp4` constructs the name in the format:
``[ddns-generated-prefix]-[address-text].[ddns-qualifying-suffix].``
Some DHCP clients may provide values in the Host Name
option (option code 12) or FQDN option (option code 81) that contain
-undesirable characters. It is possible to configure ``kea-dhcp4`` to
+undesirable characters. It is possible to configure :iscman:`kea-dhcp4` to
sanitize these values. The most typical use case is ensuring that only
characters that are permitted by RFC 1035 be included: A-Z, a-z, 0-9,
and "-". This may be accomplished with the following two parameters:
After enabling multi-threading, the number of threads is set by the ``thread-pool-size``
parameter. Results from our experiments show that the best settings for
-``kea-dhcp4`` are:
+:iscman:`kea-dhcp4` are:
- ``thread-pool-size``: 4 when using ``memfile`` for storing leases.
Temporary Allocation on DHCPDISCOVER
------------------------------------
-By default, ``kea-dhcp4`` does not allocate or store a lease when offering an address
-to a client in response to a DHCPDISCOVER. In general, ``kea-dhcp4`` can fulfill client
+By default, :iscman:`kea-dhcp4` does not allocate or store a lease when offering an address
+to a client in response to a DHCPDISCOVER. In general, :iscman:`kea-dhcp4` can fulfill client
demands faster by deferring lease allocation and storage until it receives DHCPREQUESTs
-for them. Release 2.3.6 added a new parameter to ``kea-dhcp4``, ``offer-lifetime``, which
+for them. Release 2.3.6 added a new parameter to :iscman:`kea-dhcp4`, ``offer-lifetime``, which
(when not zero) instructs the server to allocate and persist a lease when generating a
DHCPOFFER. In addition:
- Lease caching, if enabled, is honored.
-- In sites running multiple instances of ``kea-dhcp4`` against a single, shared lease store, races
+- In sites running multiple instances of :iscman:`kea-dhcp4` against a single, shared lease store, races
for given address values are lost during DHCPDISCOVER processing rather than during DHCPREQUEST
processing. Servers that lose the race for the address simply do not respond to the client,
rather than NAK them. The client in turn simply retries its DHCPDISCOVER. This should reduce
}
Here ``offer-lifetime`` has been configured to be 60 seconds, with a ``valid-lifetime``
-of 2000 seconds. This instructs ``kea-dhcp4`` to persist leases for 60 seconds when
+of 2000 seconds. This instructs :iscman:`kea-dhcp4` to persist leases for 60 seconds when
sending them back in DHCPOFFERs, and then extend them to 2000 seconds when clients
DHCPREQUEST them.
- *The Dynamic Host Configuration Protocol (DHCP) Client Fully
Qualified Domain Name (FQDN) Option*, `RFC 4702
<https://tools.ietf.org/html/rfc4702>`__: The Kea server is able to handle
- the Client FQDN option. Also, it is able to use the ``kea-dhcp-ddns``
+ the Client FQDN option. Also, it is able to use the :iscman:`kea-dhcp-ddns`
component to initiate appropriate DNS Update operations.
- *Resolution of Fully Qualified Domain Name (FQDN) Conflicts among Dynamic
=======================================
It is recommended that the Kea DHCPv6 server be started and stopped
-using ``keactrl`` (described in :ref:`keactrl`); however, it is also
-possible to run the server directly via the ``kea-dhcp6`` command, which accepts
+using :iscman:`keactrl` (described in :ref:`keactrl`); however, it is also
+possible to run the server directly via the :iscman:`kea-dhcp6` command, which accepts
the following command-line switches:
- ``-c file`` - specifies the configuration file. This is the only
as a DHCPv6 server sending responses to ports other than the standard
ones is not able to handle regular DHCPv6 queries.
-- ``-t file`` - specifies a configuration file to be tested. ``kea-dhcp6``
+- ``-t file`` - specifies a configuration file to be tested. :iscman:`kea-dhcp6`
loads it, checks it, and exits. During the test, log messages are
printed to standard output and error messages to standard error. The
result of the test is reported through the exit code (0 =
comprehensive; certain checks are possible only when running the
server.
-- ``-T file`` - specifies a configuration file to be tested. ``kea-dhcp6``
+- ``-T file`` - specifies a configuration file to be tested. :iscman:`kea-dhcp6`
loads it, checks it, and exits. It performs extra checks beyond what ``-t``
offers, such as establishing database connections (for the lease backend,
host reservations backend, configuration backend, and forensic logging
DDNS for DHCPv6
---------------
-As mentioned earlier, ``kea-dhcp6`` can be configured to generate requests
-to the DHCP-DDNS server, ``kea-dhcp-ddns``, (referred to herein as "D2") to
+As mentioned earlier, :iscman:`kea-dhcp6` can be configured to generate requests
+to the DHCP-DDNS server, :iscman:`kea-dhcp-ddns`, (referred to herein as "D2") to
update DNS entries. These requests are known as NameChangeRequests or
NCRs. Each NCR contains the following information:
1. Connectivity Parameters
- These are parameters which specify where and how ``kea-dhcp6`` connects to
+ These are parameters which specify where and how :iscman:`kea-dhcp6` connects to
and communicates with D2. These parameters can only be specified
- within the top-level ``dhcp-ddns`` section in the ``kea-dhcp6``
+ within the top-level ``dhcp-ddns`` section in the :iscman:`kea-dhcp6`
configuration. The connectivity parameters are listed below:
- ``enable-updates``
...
}
-There are two parameters which determine if ``kea-dhcp6``
+There are two parameters which determine if :iscman:`kea-dhcp6`
can generate DDNS requests to D2: the existing ``dhcp-ddns:enable-updates``
-parameter, which now only controls whether ``kea-dhcp6`` connects to D2;
+parameter, which now only controls whether :iscman:`kea-dhcp6` connects to D2;
and the new behavioral parameter, ``ddns-send-updates``, which determines
whether DDNS updates are enabled at a given level (i.e. global, shared-network,
or subnet). The following table shows how the two parameters function
for servers with numerous clients that renew often.
The second parameter added in Kea 1.9.1 is ``ddns-use-conflict-resolution``.
-The value of this parameter is passed by ``kea-dhcp6`` to D2 with each DNS update
+The value of this parameter is passed by :iscman:`kea-dhcp6` to D2 with each DNS update
request. When ``true`` (the default value), D2 employs conflict resolution,
as described in `RFC 4703 <https://tools.ietf.org/html/rfc4703>`__, when
attempting to fulfill the update request. When ``false``, D2 simply attempts
specific use cases. The best way to avoid unwanted DNS entries is to
always ensure lease changes are processed through Kea, whether they are
released, expire, or are deleted via the ``lease-del6`` command, prior to
- reassigning either FQDNs or IP addresses. Doing so causes ``kea-dhcp6``
+ reassigning either FQDNs or IP addresses. Doing so causes :iscman:`kea-dhcp6`
to generate DNS removal requests to D2.
The DNS entries Kea creates contain a value for TTL (time to live).
-``kea-dhcp6`` calculates that value based on
+:iscman:`kea-dhcp6` calculates that value based on
`RFC 4702, Section 5 <https://tools.ietf.org/html/rfc4702#section-5>`__,
which suggests that the TTL value be 1/3 of the lease's lifetime, with
a minimum value of 10 minutes.
DHCP-DDNS Server Connectivity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-For NCRs to reach the D2 server, ``kea-dhcp6`` must be able to communicate
-with it. ``kea-dhcp6`` uses the following configuration parameters to
+For NCRs to reach the D2 server, :iscman:`kea-dhcp6` must be able to communicate
+with it. :iscman:`kea-dhcp6` uses the following configuration parameters to
control this communication:
-- ``enable-updates`` - Enables connectivity to ``kea-dhcp-ddns`` such that DDNS
+- ``enable-updates`` - Enables connectivity to :iscman:`kea-dhcp-ddns` such that DDNS
updates can be constructed and sent.
It must be ``true`` for NCRs to be generated and sent to D2.
It defaults to ``false``.
- ``server-port`` - This is the port on which D2 listens for requests. The default
value is ``53001``.
-- ``sender-ip`` - This is the IP address which ``kea-dhcp6`` uses to send requests to
- D2. The default value is blank, which instructs ``kea-dhcp6`` to select a
+- ``sender-ip`` - This is the IP address which :iscman:`kea-dhcp6` uses to send requests to
+ D2. The default value is blank, which instructs :iscman:`kea-dhcp6` to select a
suitable address.
-- ``sender-port`` - This is the port which ``kea-dhcp6`` uses to send requests to D2.
- The default value of ``0`` instructs ``kea-dhcp6`` to select a suitable port.
+- ``sender-port`` - This is the port which :iscman:`kea-dhcp6` uses to send requests to D2.
+ The default value of ``0`` instructs :iscman:`kea-dhcp6` to select a suitable port.
- ``max-queue-size`` - This is the maximum number of requests allowed to queue
while waiting to be sent to D2. This value guards against requests
they can be delivered. If the number of requests queued for
transmission reaches this value, DDNS updating is turned off
until the queue backlog has been sufficiently reduced. The intent is
- to allow the ``kea-dhcp4`` server to continue lease operations without
+ to allow the :iscman:`kea-dhcp4` server to continue lease operations without
running the risk that its memory usage grows without limit. The
default value is ``1024``.
- ``ncr-format`` - This specifies the packet format to use when sending requests to D2.
Currently only JSON format is supported.
-By default, ``kea-dhcp-ddns`` is assumed to be running on the same machine
-as ``kea-dhcp6``, and all of the default values mentioned above should be
+By default, :iscman:`kea-dhcp-ddns` is assumed to be running on the same machine
+as :iscman:`kea-dhcp6`, and all of the default values mentioned above should be
sufficient. If, however, D2 has been configured to listen on a different
address or port, these values must be altered accordingly. For example, if
D2 has been configured to listen on 2001:db8::5 port 900, the following
.. _dhcpv6-d2-rules-config:
-When Does the ``kea-dhcp6`` Server Generate a DDNS Request?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When Does the :iscman:`kea-dhcp6` Server Generate a DDNS Request?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ``kea-dhcp6`` server follows the behavior prescribed for DHCP servers in
+The :iscman:`kea-dhcp6` server follows the behavior prescribed for DHCP servers in
`RFC 4704 <https://tools.ietf.org/html/rfc4704>`__. It is important to keep
-in mind that ``kea-dhcp6`` makes the initial decision of when and what to
+in mind that :iscman:`kea-dhcp6` makes the initial decision of when and what to
update and forwards that information to D2 in the form of NCRs. Carrying
out the actual DNS updates and dealing with such things as conflict
resolution are within the purview of D2 itself
-(see :ref:`dhcp-ddns-server`). This section describes when ``kea-dhcp6``
+(see :ref:`dhcp-ddns-server`). This section describes when :iscman:`kea-dhcp6`
generates NCRs and the configuration parameters that can be used to
influence this decision. It assumes that the ``enable-updates``
parameter is ``true``.
.. note::
- Currently the interface between ``kea-dhcp6`` and D2 only supports
+ Currently the interface between :iscman:`kea-dhcp6` and D2 only supports
requests which update DNS entries for a single IP address. If a lease
- grants more than one address, ``kea-dhcp6`` creates the DDNS update
+ grants more than one address, :iscman:`kea-dhcp6` creates the DDNS update
request for only the first of these addresses.
-In general, ``kea-dhcp6`` generates DDNS update requests when:
+In general, :iscman:`kea-dhcp6` generates DDNS update requests when:
1. A new lease is granted in response to a DHCPREQUEST;
single DDNS request - to remove its entries will be made.
As for the first case, the decisions involved when granting a new lease are
-more complex. When a new lease is granted, ``kea-dhcp6`` generates a
+more complex. When a new lease is granted, :iscman:`kea-dhcp6` generates a
DDNS update request only if the DHCPREQUEST contains the FQDN option
-(code 39). By default, ``kea-dhcp6`` respects the FQDN N and S flags
+(code 39). By default, :iscman:`kea-dhcp6` respects the FQDN N and S flags
specified by the client as shown in the following table:
.. table:: Default FQDN flag behavior
The first row in the table above represents "client delegation." Here
the DHCP client states that it intends to do the forward DNS updates and
-the server should do the reverse updates. By default, ``kea-dhcp6``
+the server should do the reverse updates. By default, :iscman:`kea-dhcp6`
honors the client's wishes and generates a DDNS request to D2 to update
only reverse DNS data. The parameter ``ddns-override-client-update`` can be
used to instruct the server to override client delegation requests. When
-this parameter is ``true``, ``kea-dhcp6`` disregards requests for client
+this parameter is ``true``, :iscman:`kea-dhcp6` disregards requests for client
delegation and generates a DDNS request to update both forward and
reverse DNS data. In this case, the N-S-O flags in the server's response
to the client will be 0-1-1 respectively.
(Note that the flag combination N=1, S=1 is prohibited according to `RFC
4702 <https://tools.ietf.org/html/rfc4702>`__. If such a combination is
-received from the client, the packet will be dropped by ``kea-dhcp6``.)
+received from the client, the packet will be dropped by :iscman:`kea-dhcp6`.)
To override client delegation, set the following values in the
configuration file:
The third row in the table above describes the case in which the client
requests that no DNS updates be done. The parameter
``ddns-override-no-update`` can be used to instruct the server to disregard
-the client's wishes. When this parameter is ``true``, ``kea-dhcp6``
-generates DDNS update requests to ``kea-dhcp-ddns`` even if the client
+the client's wishes. When this parameter is ``true``, :iscman:`kea-dhcp6`
+generates DDNS update requests to :iscman:`kea-dhcp-ddns` even if the client
requests that no updates be done. The N-S-O flags in the server's response to
the client will be 0-1-1.
...
}
-The ``kea-dhcp6`` server always generates DDNS update requests if the
+The :iscman:`kea-dhcp6` server always generates DDNS update requests if the
client request only contains the Host Name option. In addition, it includes
an FQDN option in the response to the client with the FQDN N-S-O flags
set to 0-1-0, respectively. The domain name portion of the FQDN option
.. _dhcpv6-fqdn-name-generation:
-``kea-dhcp6`` Name Generation for DDNS Update Requests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+:iscman:`kea-dhcp6` Name Generation for DDNS Update Requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Each NameChangeRequest must of course include the fully qualified
-domain name whose DNS entries are to be affected. ``kea-dhcp6`` can be
+domain name whose DNS entries are to be affected. :iscman:`kea-dhcp6` can be
configured to supply a portion or all of that name, based upon what it
receives from the client in the DHCPREQUEST.
desired mode name. A value of ``true`` maps to ``when-present``, while
``false`` maps to ``never``.
-For example, to instruct ``kea-dhcp6`` to always generate the FQDN for a
+For example, to instruct :iscman:`kea-dhcp6` to always generate the FQDN for a
client, set the parameter ``ddns-replace-client-name`` to ``always`` as
follows:
...
}
-When qualifying a partial name, ``kea-dhcp6`` constructs the name in the
+When qualifying a partial name, :iscman:`kea-dhcp6` constructs the name in the
format:
``[candidate-name].[ddns-qualifying-suffix].``
``some-computer.example.com.``
-When generating the entire name, ``kea-dhcp6`` constructs the name in
+When generating the entire name, :iscman:`kea-dhcp6` constructs the name in
the format:
``[ddns-generated-prefix]-[address-text].[ddns-qualifying-suffix].``
Some DHCP clients may provide values in the name
component of the FQDN option (option code 39) that contain undesirable
-characters. It is possible to configure ``kea-dhcp6`` to sanitize these
+characters. It is possible to configure :iscman:`kea-dhcp6` to sanitize these
values. The most typical use case is ensuring that only characters that
are permitted by RFC 1035 be included: A-Z, a-z, 0-9, and "-". This may be
accomplished with the following two parameters:
After enabling multi-threading, the number of threads is set by the ``thread-pool-size``
parameter. Results from our experiments show that the best settings for
-``kea-dhcp6`` are:
+:iscman:`kea-dhcp6` are:
- ``thread-pool-size``: 4 when using ``memfile`` for storing leases.
in `RFC 4741 <https://tools.ietf.org/html/rfc4741>`__. It uses the YANG modeling language,
defined in `RFC 6020 <https://tools.ietf.org/html/rfc6020>`__, to provide a uniform way
of handling the configuration syntax of various networking devices. Kea provides optional
-support for a YANG/NETCONF interface with the ``kea-netconf`` agent.
+support for a YANG/NETCONF interface with the :iscman:`kea-netconf` agent.
.. _netconf-install:
.. note::
- ``kea-netconf`` may be compatible with later versions of libyang and
+ :iscman:`kea-netconf` may be compatible with later versions of libyang and
Sysrepo, but only the versions listed above have been thoroughly
tested by ISC.
The 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 has been on Kea DHCP
-servers. Other models (``kea-dhcp-ddns`` and ``kea-ctrl-agent``)
+servers. Other models (:iscman:`kea-dhcp-ddns` and :iscman:`kea-ctrl-agent`)
are currently not supported.
.. _using-netconf:
}
}
-With module change subscriptions enabled, the ``kea-netconf`` daemon
+With module change subscriptions enabled, the :iscman:`kea-netconf` daemon
monitors 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
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
+handled by :iscman:`kea-netconf` in the validation phase (if not disabled by
setting ``validate-changes`` to ``true``). The last case causes the
application phase to fail without a sensible report to Sysrepo.
- ``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
+ it is not really a socket, but it allows :iscman:`kea-netconf` to run in
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; ``http`` uses
Hook libraries can be loaded by the NETCONF agent just as with other
servers or agents; however, currently no hook points are defined. The
``hooks-libraries`` list contains the list of hook libraries that
-should be loaded by ``kea-netconf``, along with their configuration
+should be loaded by :iscman:`kea-netconf`, along with their configuration
information specified with ``parameters``.
Please consult :ref:`logging` for details on how to configure
-logging. The name of the NETCONF agent's main logger is ``kea-netconf``, as
+logging. The name of the NETCONF agent's main logger is :iscman:`kea-netconf`, as
given in the example above.
.. _netconf-example:
-A ``kea-netconf`` Configuration Example
----------------------------------------
+A :iscman:`kea-netconf` Configuration Example
+---------------------------------------------
The following example demonstrates the basic NETCONF configuration. More
examples are available in the ``doc/examples/netconf`` directory in the
Starting and Stopping the NETCONF Agent
---------------------------------------
-``kea-netconf`` accepts the following command-line switches:
+:iscman:`kea-netconf` accepts the following command-line switches:
- ``-c file`` - specifies the configuration file.
verbosity, e.g. when debugging.
- ``-t file`` - specifies the configuration file to be tested.
- ``kea-netconf`` attempts to load it and conducts sanity checks;
+ :iscman:`kea-netconf` attempts to load it and conducts sanity checks;
certain checks are possible only while running the actual server. The
actual status is reported with exit code (0 = configuration appears valid,
1 = error encountered). Kea prints out log messages to standard
output and error to standard error when testing the configuration.
-- ``-v`` - displays the version of ``kea-netconf`` and exits.
+- ``-v`` - displays the version of :iscman:`kea-netconf` and exits.
-- ``-V`` - displays the extended version information for ``kea-netconf``
+- ``-V`` - displays the extended version information for :iscman:`kea-netconf`
and exits. The listing includes the versions of the libraries
dynamically linked to Kea.
# ip -6 addr add 2001:db8::1/64 dev eth1
The Kea DHCPv6 server must be launched with the configuration specifying
-a control socket used to receive control commands. The ``kea-netconf``
+a control socket used to receive control commands. The :iscman:`kea-netconf`
process uses this socket to communicate with the DHCPv6 server, i.e. it
pushes translated configurations to that server using control commands.
The following is an example control socket specification for the Kea
# echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea-dhcp6-ctrl.sock '-,ignoreeof'
The following is the example ``netconf.json`` configuration for
-``kea-netconf``, to manage the Kea DHCPv6 server:
+:iscman:`kea-netconf`, to manage the Kea DHCPv6 server:
.. code-block:: json
# kea-netconf -d -c netconf.json
-Now that both ``kea-netconf`` and ``kea-dhcp6`` are running, it is
+Now that both :iscman:`kea-netconf` and :iscman:`kea-dhcp6` are running, it is
possible to populate updates to the configuration to the DHCPv6 server.
The following is the configuration extracted from ``startup.xml``:
$ sysrepocfg -d startup -f xml -m kea-dhcp6-server --edit=startup.xml
-``kea-netconf`` pushes the configuration found in the Sysrepo startup
+:iscman:`kea-netconf` pushes the configuration found in the Sysrepo startup
datastore to all Kea servers during its initialization phase, after it
subscribes to module changes in the Sysrepo running datastore. This
action copies the configuration from the startup datastore to the
.. note::
- ``kea-netconf`` fetches the entire configuration from any Sysrepo datastore in a
+ :iscman:`kea-netconf` fetches the entire configuration from any Sysrepo datastore in a
single ``get-config`` NETCONF operation. Prior to Kea 2.3.2, a ``get-config`` operation
was done for each leaf and leaf-list node. Because of the significant changes,
- ``kea-netconf`` is considered experimental.
+ :iscman:`kea-netconf` is considered experimental.
.. _operation-example-errors:
$ sysrepocfg -d running -f xml -m kea-dhcp6-server --edit=BAD-schema.xml
-In the second case, the configuration is rejected by ``kea-netconf``.
+In the second case, the configuration is rejected by :iscman:`kea-netconf`.
For example, consider this ``BAD-translator.xml`` file:
.. code-block:: xml
Migrating YANG Data From a Prior Sysrepo Version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-1. Shut down ``kea-netconf``. This ensures that backups for both datastores
+1. Shut down :iscman:`kea-netconf`. This ensures that backups for both datastores
are done at the same configuration state and that no change happens between exporting them.
2. Make data backups for all YANG modules, with one XML for each datastore.
size of 300 octets are padded to this size.
This open source library is loaded
-similarly to other hook libraries by the ``kea-dhcp4`` process, and
+similarly to other hook libraries by the :iscman:`kea-dhcp4` process, and
it takes no parameters.
::
.. note::
- This library can only be loaded by the ``kea-dhcp4`` process,
+ This library can only be loaded by the :iscman:`kea-dhcp4` process,
as there is no BOOTP protocol for IPv6.
.. note::
.. note::
- This library may only be loaded by the ``kea-dhcp4`` or
- ``kea-dhcp6`` process.
+ This library may only be loaded by the :iscman:`kea-dhcp4` or
+ :iscman:`kea-dhcp6` process.
.. note::
.. note::
- This library can only be loaded by the ``kea-dhcp4`` or
- ``kea-dhcp6`` process.
+ This library can only be loaded by the :iscman:`kea-dhcp4` or
+ :iscman:`kea-dhcp6` process.
.. note::
.. note::
- This library can only be loaded by the ``kea-dhcp4`` or
- ``kea-dhcp6`` process.
+ This library can only be loaded by the :iscman:`kea-dhcp4` or
+ :iscman:`kea-dhcp6` process.
The Class Commands hook library is currently available only to ISC
customers with a paid support contract.
The DDNS Tuning hook library is only available to ISC customers with a paid
support contract.
-The library, which was added in Kea 2.1.5, can be loaded by the ``kea-dhcp4``
-and ``kea-dhcp6`` daemons by adding it to the ``hooks-libraries`` element of the
+The library, which was added in Kea 2.1.5, can be loaded by the :iscman:`kea-dhcp4`
+and :iscman:`kea-dhcp6` daemons by adding it to the ``hooks-libraries`` element of the
server's configuration:
.. code-block:: javascript
DHCPv4 Host-Name Generation
---------------------------
-With this library installed, the behavior for ``kea-dhcp4`` when forming host names in
+With this library installed, the behavior for :iscman:`kea-dhcp4` when forming host names in
response to a client query (e.g. DISCOVER, REQUEST) is as follows:
1. If a host name is supplied via a host reservation, use it with the DDNS
DHCPv6 Host-Name Generation
---------------------------
-With this library installed, the behavior for ``kea-dhcp6`` when forming host names in
+With this library installed, the behavior for :iscman:`kea-dhcp6` when forming host names in
response to a client query (e.g. SOLICIT, REQUEST, RENEW, REBIND) is as follows:
1. If the client supplied an FQDN option (option 39), use the domain name value
The ``ddns-tuning`` library also provides the ability to skip DDNS updates on a
per-client basis. The library recognizes a special client class, "SKIP_DDNS"; when a
-client is matched to this class, the Kea servers (``kea-dhcp4`` and ``kea-dhcp6``) do not
-send DDNS update requests (NCRs) to ``kea-dhcp-ddns``. A common use case would be
+client is matched to this class, the Kea servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`) do not
+send DDNS update requests (NCRs) to :iscman:`kea-dhcp-ddns`. A common use case would be
to skip DDNS updates for fixed-address host reservations. This is done easily by
simply assigning the class to the host reservation as shown below:
The ``ddns-tuning`` library notes the presence of the "SKIP_DDNS" class in the
client's class list each time the client requests, renews, or releases its lease,
-and instructs ``kea-dhcp4`` to bypass sending DDNS updates. A similar workflow is
-supported for ``kea-dhcp6``:
+and instructs :iscman:`kea-dhcp4` to bypass sending DDNS updates. A similar workflow is
+supported for :iscman:`kea-dhcp6`:
.. code-block:: javascript
.. note::
- This library can only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
+ This library can only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6`
process.
The ``flex_id`` library allows the definition of an expression, using notation initially
on the server where the hook library is loaded.
Similar to other hook libraries, the ``flex_option`` library can be loaded
-by either the ``kea-dhcp4`` or `kea-dhcp6``
+by either the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6`
process. It takes a mandatory ``options`` parameter with a list of
per-option parameter maps, with ``code``, ``name``, ``add``, ``supersede``, and
``remove`` actions. Action entries take a string value representing an
``gss-tsig``: Sign DNS Updates With GSS-TSIG
============================================
-This hook library allows the ``kea-dhcp-ddns`` server to use
+This hook library allows the :iscman:`kea-dhcp-ddns` server to use
GSS-TSIG to sign DNS updates. For a full discussion of GSS-TSIG in Kea,
please see :ref:`gss-tsig`.
.. note::
- This library can only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` process.
+ This library can only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6` process.
High Availability (HA) of the DHCP service is provided by running multiple
cooperating server instances. If any of these instances becomes unavailable for
HA peer communication consists of specialized API commands sent between HA peers.
Prior to Kea 1.9.7, each peer had to be paired with a local instance of
-``kea-ctrl-agent`` in order to exchange commands. The agent received HA commands
+:iscman:`kea-ctrl-agent` in order to exchange commands. The agent received HA commands
via HTTP, communicated via Linux socket with the local peer to carry out the
command, and then sent the response back to the requesting peer via HTTP. To
send HA commands, each peer opened its own HTTP client connection to the URL of
- ``enable-multi-threading`` - enables or disables multi-threading HA peer
communication (HA+MT). Kea core multi-threading must be enabled for HA+MT to
- operate. When ``false``, the server relies on ``kea-ctrl-agent`` for
+ operate. When ``false``, the server relies on :iscman:`kea-ctrl-agent` for
communication with its peer, and uses single-threaded HTTP client processing.
The default is ``true``.
- ``http-dedicated-listener`` - enables or disables the creation of a dedicated,
internal HTTP listener through which the server receives HA messages from its
- peers. The internal listener replaces the role of ``kea-ctrl-agent`` traffic,
+ peers. The internal listener replaces the role of :iscman:`kea-ctrl-agent` traffic,
allowing peers to send their HA commands directly to each other. The listener
listens on the peer's ``url``. When ``false``, the server
- relies on ``kea-ctrl-agent``. This parameter has been provided largely for
+ relies on :iscman:`kea-ctrl-agent`. This parameter has been provided largely for
flexibility and testing; running HA+MT without dedicated listeners enabled
will substantially limit HA throughput. The default is ``true``.
.. note::
- This library can only be loaded by the ``kea-dhcp4`` or
- ``kea-dhcp6`` process.
+ This library can only be loaded by the :iscman:`kea-dhcp4` or
+ :iscman:`kea-dhcp6` process.
In principle, this hook library can be used with any backend that may
introduce performance degradation (MySQL, PostgreSQL or RADIUS). Host Cache
.. note::
- This library can only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
+ This library can only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6`
process.
Currently, the following commands are supported:
.. note::
- This library can only be loaded by the ``kea-dhcp4`` or the
- ``kea-dhcp6`` process.
+ This library can only be loaded by the :iscman:`kea-dhcp4` or the
+ :iscman:`kea-dhcp6` process.
There are many situations where an administrative command may be useful;
for example, during migration between servers or different vendors, when
Another parameter called ``update-ddns``, when ``true``, instructs the server to
-queue a request to ``kea-dhcp-ddns`` to remove DNS entries after the lease is
+queue a request to :iscman:`kea-dhcp-ddns` to remove DNS entries after the lease is
successfully deleted if:
- DDNS updating is enabled (i.e. ``"dhcp-ddns":{ "enable-updates": true }``).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``lease4-resend-ddns`` and ``lease6-resend-ddns`` can be used to generate
-a request to ``kea-dhcp-ddns`` to update the DNS entries for an existing
+a request to :iscman:`kea-dhcp-ddns` to update the DNS entries for an existing
lease. The desired lease is selected by a single parameter, ``"ip-address"``.
For an update request to be generated, DDNS updating must be enabled
and DNS entries must have already been made (or attempted) for the lease.
A successful result does not mean that DNS has been successfully updated; it
indicates that a request to update DNS has been successfully created and
-queued for transmission to ``kea-dhcp-ddns``.
+queued for transmission to :iscman:`kea-dhcp-ddns`.
Here's an example of a result returned when the lease was found:
.. note::
- This library can only be loaded by the ``kea-dhcp4`` or
- ``kea-dhcp6`` process.
+ This library can only be loaded by the :iscman:`kea-dhcp4` or
+ :iscman:`kea-dhcp6` process.
Kea version 2.3.4 added support for DHCPv6 Bulk Leasequery
(`RFC 5460 <https://tools.ietf.org/html/rfc5460>`__);
.. note::
- This library may only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
+ This library may only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6`
process.
In many legal jurisdictions, companies - especially ISPs - must record
To use this functionality, the hook library must be included in the
configuration of the desired DHCP server modules. The ``legal_log`` library
can save logs to a text file or to a database (created using
-``kea-admin``; see :ref:`mysql-database-create` and :ref:`pgsql-database-create`).
+:iscman:`kea-admin`; see :ref:`mysql-database-create` and :ref:`pgsql-database-create`).
The library is installed alongside the Kea libraries in
``[kea-install-dir]/var/lib/kea``, where ``kea-install-dir`` is determined
by the ``--prefix`` option of the configure script; it defaults to
-``/usr/local``. Assuming the default value, ``kea-dhcp4`` can be configured to load
+``/usr/local``. Assuming the default value, :iscman:`kea-dhcp4` can be configured to load
the ``legal_log`` library like this:
.. code-block:: json
}
}
-For ``kea-dhcp6``, the configuration is:
+For :iscman:`kea-dhcp6`, the configuration is:
.. code-block:: json
Configuration
~~~~~~~~~~~~~
-The following examples are for ``kea-dhcp6``, but they apply equally to
-``kea-dhcp4``. The wildcards ``"<limit-type>"`` and ``"<limit-value>"`` need to be replaced
+The following examples are for :iscman:`kea-dhcp6`, but they apply equally to
+:iscman:`kea-dhcp4`. The wildcards ``"<limit-type>"`` and ``"<limit-value>"`` need to be replaced
with the respective keys and values for each limit type described in the sections following this
one.
-The library can be loaded by both ``kea-dhcp4`` and ``kea-dhcp6`` servers by adding its path in the
+The library can be loaded by both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` servers by adding its path in the
``"hooks-libraries"`` element of the server's configuration.
.. code-block:: json
.. note::
- This library can only be loaded by the ``kea-dhcp4`` or the
- ``kea-dhcp6`` process.
+ This library can only be loaded by the :iscman:`kea-dhcp4` or the
+ :iscman:`kea-dhcp6` process.
The major feature of this hook library is the ability to use RADIUS
authorization. When a DHCP packet is received, the Kea server sends an
packet-processing hook points.
The library, which was added in Kea 1.9.5, can be loaded in a
-similar way to other hook libraries by the ``kea-dhcp4`` and
-``kea-dhcp6`` processes.
+similar way to other hook libraries by the :iscman:`kea-dhcp4` and
+:iscman:`kea-dhcp6` processes.
.. code-block:: json
multiple Kea servers that use a shared lease backend. The in-memory
statistics kept by individual servers only track lease changes made by
that server; thus, in a deployment with multiple servers (e.g. two
-``kea-dhcp6`` servers using the same PostgreSQL database for lease storage),
+:iscman:`kea-dhcp6` servers using the same PostgreSQL database for lease storage),
these statistics are incomplete. The MySQL and PostgreSQL backends in
Kea track lease allocation changes as they occur via database triggers.
Additionally, all the lease backends were extended to support
.. note::
- This library can only be loaded by the ``kea-dhcp4`` or
- ``kea-dhcp6`` process.
+ This library can only be loaded by the :iscman:`kea-dhcp4` or
+ :iscman:`kea-dhcp6` process.
The commands provided by this library are:
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 the ``kea-dhcp4`` and ``kea-dhcp6`` servers. It
+This library may be loaded by both the :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` servers. It
is loaded in the same way as other libraries and currently has no
parameters:
can result in a large response.
The following command fetches lease statistics for all known subnets
-from a ``kea-dhcp4`` server:
+from a :iscman:`kea-dhcp4` server:
::
}
The following command fetches lease statistics for subnet ID 10 from a
-``kea-dhcp6`` server:
+:iscman:`kea-dhcp6` server:
::
}
The following command fetches lease statistics for all subnets with IDs
-in the range 10 through 50 from a ``kea-dhcp4`` server:
+in the range 10 through 50 from a :iscman:`kea-dhcp4` server:
.. code-block:: json
.. note::
- This library can only be loaded by the ``kea-dhcp4`` or ``kea-dhcp6``
+ This library can only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6`
process.
The following commands are currently supported:
instead of removing the ``hooks-libraries`` item, change it to an
empty list.
-At the moment, only the ``kea-dhcp4`` and ``kea-dhcp6`` processes support
+At the moment, only the :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` processes support
hook libraries.
.. _order-of-configuration-hooks:
The following table provides a list of hook libraries currently available
from ISC. It is important to pay attention to which libraries may be
loaded by which Kea processes. It is a common mistake to configure the
-``kea-ctrl-agent`` process to load libraries that should, in fact, be
-loaded by the ``kea-dhcp4`` or ``kea-dhcp6`` processes. If a library
+:iscman:`kea-ctrl-agent` process to load libraries that should, in fact, be
+loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6` processes. If a library
from ISC does not work as expected, please make sure that it has been
loaded by the correct process per the table below.
| | customers | Leasequery as described in RFC 4388; and for DHCPv6 |
| | | Leasequery as described in RFC 5007. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+
- | :ref:`Limits <hooks-limits>` | ISC support | With this hook library, ``kea-dhcp4`` and ``kea-dhcp6`` |
- | | customers | servers can apply a limit to the rate at which packets |
- | | | receive a response. The limit can be applied per-client |
- | | | class or per-subnet. |
+ | :ref:`Limits <hooks-limits>` | ISC support | With this hook library, :iscman:`kea-dhcp4` and |
+ | | customers | :iscman:`kea-dhcp6` servers can apply a limit to the rate at |
+ | | | which packets receive a response. The limit can be applied |
+ | | | per-client class or per-subnet. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+
| :ref:`MySQL Configuration Backend <hooks-cb-mysql>` | Kea open | This hook library is an implementation of the Kea |
| | source | Configuration Backend for MySQL. It uses a MySQL database as |
``isc-kea-premium-`` prefix.
Once installed, the services can be managed through the distribution's
-service manager. The services are named: ``kea-dhcp4``, ``kea-dhcp6``,
-``kea-dhcp-ddns``, and ``kea-ctrl-agent``.
+service manager. The services are named: :iscman:`kea-dhcp4`, :iscman:`kea-dhcp6`,
+:iscman:`kea-dhcp-ddns`, and :iscman:`kea-ctrl-agent`.
.. note::
The real service names on Debian and Ubuntu follow the names of the older
found, Kea searches for OpenSSL. Normally this is not necessary.
- ``--enable-shell``
- Build the optional ``kea-shell`` tool (more in :ref:`kea-shell`).
+ Build the optional :iscman:`kea-shell` tool (more in :ref:`kea-shell`).
The default is to not build it.
- ``--with-site-packages``
- Only useful when ``kea-shell`` is enabled, this switch causes the kea-shell
+ Only useful when :iscman:`kea-shell` is enabled, this switch causes the kea-shell
Python packages to be installed in the specified directory. This is
mostly useful for Debian-related distributions. While most systems store
Python packages in ``${prefix}/usr/lib/pythonX/site-packages``, Debian
``/usr/lib/python3/dist-packages``.
- ``--enable-perfdhcp``
- Build the optional ``perfdhcp`` DHCP benchmarking tool. The default
+ Build the optional :iscman:`perfdhcp` DHCP benchmarking tool. The default
is to not build it.
- ``--with-freeradius``
When ``configure`` succeeds, it displays a report with the parameters used
to build the code. This report is saved into the file ``config.report``
-and is also embedded into the executable binaries, e.g., ``kea-dhcp4``.
+and is also embedded into the executable binaries, e.g., :iscman:`kea-dhcp4`.
Build
-----
cooperating processes which, together, provide the server functionality.
The following software is included with Kea:
-- ``keactrl`` — This tool starts, stops, reconfigures, and reports the status of
+- :iscman:`keactrl` — This tool starts, stops, reconfigures, and reports the status of
the Kea servers.
-- ``kea-dhcp4`` — The DHCPv4 server process. This process responds to
+- :iscman:`kea-dhcp4` — The DHCPv4 server process. This process responds to
DHCPv4 queries from clients.
-- ``kea-dhcp6`` — The DHCPv6 server process. This process responds to
+- :iscman:`kea-dhcp6` — The DHCPv6 server process. This process responds to
DHCPv6 queries from clients.
-- ``kea-dhcp-ddns`` — The DHCP Dynamic DNS process. This process acts
+- :iscman:`kea-dhcp-ddns` — The DHCP Dynamic DNS process. This process acts
as an intermediary between the DHCP servers and external DNS servers. It
receives name update requests from the DHCP servers and sends DNS
update messages to the DNS servers.
-- ``kea-admin`` — This is a useful tool for database backend maintenance
+- :iscman:`kea-admin` — This is a useful tool for database backend maintenance
(creating a new database, checking versions, upgrading, etc.).
-- ``kea-lfc`` — This process removes redundant information from the
+- :iscman:`kea-lfc` — This process removes redundant information from the
files used to provide persistent storage for the memfile database
backend. While it can be run standalone, it is normally run as and
when required by the Kea DHCP servers.
-- ``kea-ctrl-agent`` — The Kea Control Agent (CA) is a daemon that exposes
+- :iscman:`kea-ctrl-agent` — The 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
+- :iscman:`kea-netconf` - kea-netconf is an agent that provides a
YANG/NETCONF interface for configuring Kea.
-- ``kea-shell`` — This simple text client uses the REST interface to
+- :iscman:`kea-shell` — This simple text client uses the REST interface to
connect to the Kea Control Agent.
-- ``perfdhcp`` — This is a DHCP benchmarking tool which simulates multiple
+- :iscman:`perfdhcp` — This is a DHCP benchmarking tool which simulates multiple
clients to test both DHCPv4 and DHCPv6 server performance.
The tools and modules are covered in full detail in this guide. In
.. _keactrl:
-*****************************
-Managing Kea with ``keactrl``
-*****************************
+***********************************
+Managing Kea with :iscman:`keactrl`
+***********************************
.. _keactrl-overview:
Overview
========
-``keactrl`` is a shell script which controls the startup, shutdown, and
-reconfiguration of the Kea servers (``kea-dhcp4``, ``kea-dhcp6``,
-``kea-dhcp-ddns``, ``kea-ctrl-agent``, and ``kea-netconf``). It also
+:iscman:`keactrl` is a shell script which controls the startup, shutdown, and
+reconfiguration of the Kea servers (:iscman:`kea-dhcp4`, :iscman:`kea-dhcp6`,
+:iscman:`kea-dhcp-ddns`, :iscman:`kea-ctrl-agent`, and :iscman:`kea-netconf`). It also
provides the means for checking the current status of the servers and
determining the configuration files in use.
-``keactrl`` is available only when Kea is built from sources. When installing
+:iscman:`keactrl` is available only when Kea is built from sources. When installing
Kea using native packages, the native ``systemd`` scripts are provided. See
:ref:`systemd` Section for details.
Command Line Options
====================
-``keactrl`` is run as follows:
+:iscman:`keactrl` is run as follows:
.. code-block:: console
``<command>`` is one of the commands described in :ref:`keactrl-commands`.
The optional ``-c keactrl-config-file`` switch allows specification of
-an alternate ``keactrl`` configuration file. (``--ctrl-config`` is a
-synonym for ``-c``.) In the absence of ``-c``, ``keactrl`` uses the
+an alternate :iscman:`keactrl` configuration file. (``--ctrl-config`` is a
+synonym for ``-c``.) In the absence of ``-c``, :iscman:`keactrl` uses the
default configuration file ``[kea-install-dir]/etc/kea/keactrl.conf``.
The optional ``-s server[,server,...]`` switch selects the servers to
which the command is issued. (``--server`` is a synonym for ``-s``.) If
-absent, the command is sent to all servers enabled in the ``keactrl``
+absent, the command is sent to all servers enabled in the :iscman:`keactrl`
configuration file. If multiple servers are specified, they should be
separated by commas with no intervening spaces.
.. _keactrl-config-file:
-The ``keactrl`` Configuration File
-==================================
+The :iscman:`keactrl` Configuration File
+========================================
Depending on the administrator's requirements, it may not be
necessary to run all of the available servers.
-The ``keactrl`` configuration file sets which servers are enabled and
+The :iscman:`keactrl` configuration file sets which servers are enabled and
which are disabled. The default configuration file is
``[kea-install-dir]/etc/kea/keactrl.conf``, but this can be overridden
on a per-command basis using the ``-c`` switch.
the appropriate values when Kea is installed.
Setting the ``dhcp4``, ``dhcp6``, ``dhcp_ddns``, ``ctrl_agent``, and ``netconf``
-parameters set to "yes" configures ``keactrl`` to manage (start,
-reconfigure) all servers, i.e. ``kea-dhcp4``, ``kea-dhcp6``,
-``kea-dhcp-ddns``, ``kea-ctrl-agent``, and ``kea-netconf``. When any of
-these parameters is set to "no", ``keactrl`` ignores the
+parameters set to "yes" configures :iscman:`keactrl` to manage (start,
+reconfigure) all servers, i.e. :iscman:`kea-dhcp4`, :iscman:`kea-dhcp6`,
+:iscman:`kea-dhcp-ddns`, :iscman:`kea-ctrl-agent`, and :iscman:`kea-netconf`. When any of
+these parameters is set to "no", :iscman:`keactrl` ignores the
corresponding server when starting or reconfiguring Kea. Some daemons
(dhcp_ddns and netconf) are disabled by default.
-By default, Kea servers managed by ``keactrl`` are located in
+By default, Kea servers managed by :iscman:`keactrl` are located in
``[kea-install-dir]/sbin``. This should work for most installations. If
the default location needs to be altered, the paths
specified with the ``dhcp4_srv``, ``dhcp6_srv``, ``dhcp_ddns_srv``,
Commands
========
-The following commands are supported by ``keactrl``:
+The following commands are supported by :iscman:`keactrl`:
- ``start`` - starts the selected servers.
- ``status`` - returns the status of the servers (active or inactive)
and the names of the configuration files in use.
-- ``version`` - prints out the version of the ``keactrl`` tool itself,
+- ``version`` - prints out the version of the :iscman:`keactrl` tool itself,
together with the versions of the Kea daemons.
-Typical output from ``keactrl`` when starting the servers looks similar
+Typical output from :iscman:`keactrl` when starting the servers looks similar
to the following:
.. code-block:: console
INFO/keactrl: Starting kea-netconf -c /usr/local/etc/kea/kea-netconf.conf -d
Kea's servers create PID files upon startup. These files are used by
-``keactrl`` to determine whether a given server is running. If one or more
+:iscman:`keactrl` to determine whether a given server is running. If one or more
servers are running when the start command is issued, the output
looks similar to the following:
be left over as remnants following a system crash. It is possible,
though highly unlikely, that upon system restart the PIDs they contain
may actually refer to processes unrelated to Kea. This condition will
-cause ``keactrl`` to decide that the servers are running, when in fact they
-are not. In such a case the PID files listed in the ``keactrl`` output
+cause :iscman:`keactrl` to decide that the servers are running, when in fact they
+are not. In such a case the PID files listed in the :iscman:`keactrl` output
must be manually deleted.
The following command stops all servers:
As already mentioned, the reconfiguration of each Kea server is
triggered by the SIGHUP signal. The ``reload`` command sends the SIGHUP
-signal to any servers that are enabled in the ``keactrl`` configuration
+signal to any servers that are enabled in the :iscman:`keactrl` configuration
file and that are currently running. When a server receives the SIGHUP signal
it rereads its configuration file and, if the new configuration is
valid, uses the new configuration.
If any of the servers are not running, an informational message is
displayed as in the ``reload`` command output below.
-``kea-netconf`` does not support the SIGHUP signal. If its
+:iscman:`kea-netconf` does not support the SIGHUP signal. If its
configuration has changed, please stop and restart it for the change to
take effect.
NETCONF is an optional feature that is disabled by default and can be
enabled during compilation. If Kea was compiled without NETCONF
- support, ``keactrl`` does not provide
+ support, :iscman:`keactrl` does not provide
information about it. The NETCONF entries are still present in
the ``keactrl.conf`` file, but NETCONF status is not shown and other
commands ignore it.
.. note::
- Currently ``keactrl`` does not report configuration failures when the
+ Currently :iscman:`keactrl` does not report configuration failures when the
server is started or reconfigured. To check if the server's
configuration succeeded, the Kea log must be examined for errors. By
default, the log is written to the `syslog` file.
===============================
The optional ``-s`` switch allows the selection of the server(s) to which
-the ``keactrl`` command is issued. For example, the following instructs
-``keactrl`` to stop the ``kea-dhcp4`` and ``kea-dhcp6`` servers and
-leave the ``kea-dhcp-ddns`` and ``kea-ctrl-agent`` running:
+the :iscman:`keactrl` command is issued. For example, the following instructs
+:iscman:`keactrl` to stop the :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` servers and
+leave the :iscman:`kea-dhcp-ddns` and :iscman:`kea-ctrl-agent` running:
.. code-block:: console
$ keactrl stop -s dhcp4,dhcp6
-Similarly, the following starts only the ``kea-dhcp4`` and
-``kea-dhcp-ddns`` servers, but not ``kea-dhcp6`` or ``kea-ctrl-agent``.
+Similarly, the following starts only the :iscman:`kea-dhcp4` and
+:iscman:`kea-dhcp-ddns` servers, but not :iscman:`kea-dhcp6` or :iscman:`kea-ctrl-agent`.
.. code-block:: console
Note that the behavior of the ``-s`` switch with the ``start`` and
``reload`` commands is different from its behavior with the ``stop``
-command. On ``start`` and ``reload``, ``keactrl`` checks whether the
+command. On ``start`` and ``reload``, :iscman:`keactrl` checks whether the
servers given as parameters to the ``-s`` switch are enabled in the
-``keactrl`` configuration file; if not, the server is ignored. For
+:iscman:`keactrl` configuration file; if not, the server is ignored. For
``stop``, however, this check is not made; the command is applied to all
listed servers, regardless of whether they have been enabled in the
file.
The following keywords can be used with the ``-s`` command-line option:
-- ``dhcp4`` for ``kea-dhcp4``.
+- ``dhcp4`` for :iscman:`kea-dhcp4`.
-- ``dhcp6`` for ``kea-dhcp6``.
+- ``dhcp6`` for :iscman:`kea-dhcp6`.
-- ``dhcp_ddns`` for ``kea-dhcp-ddns``.
+- ``dhcp_ddns`` for :iscman:`kea-dhcp-ddns`.
-- ``ctrl_agent`` for ``kea-ctrl-agent``.
+- ``ctrl_agent`` for :iscman:`kea-ctrl-agent`.
-- ``netconf`` for ``kea-netconf``.
+- ``netconf`` for :iscman:`kea-netconf`.
- ``all`` for all servers (default).
Native Packages and ``systemd``
===============================
-``keactrl`` is a script that was developed to assist in managing Kea processes.
+:iscman:`keactrl` is a script that was developed to assist in managing Kea processes.
However, all modern operating systems have their own process-management scripts,
such as ``systemd``. In general, these native scripts should be used,
as they have several advantages. ``systemd`` scripts handle processes in a uniform
service.
Thus, it is recommended to use ``systemctl`` commands if they are available. Native
-Kea packages do not provide ``keactrl``; ``systemctl`` service definitions are
+Kea packages do not provide :iscman:`keactrl`; ``systemctl`` service definitions are
provided instead. Consult the system documentation for details.
Briefly, here are example commands to check status, start, stop, and restart various Kea daemons:
Overview
========
-``kea-lfc`` is a service process that removes redundant information from
+:iscman:`kea-lfc` is a service process that removes redundant information from
the files used to provide persistent storage for the memfile database
backend. This service is written to run as a standalone process.
-While ``kea-lfc`` can be started externally, there is usually no need to
-do so. ``kea-lfc`` is run on a periodic basis by the Kea DHCP servers.
+While :iscman:`kea-lfc` can be started externally, there is usually no need to
+do so. :iscman:`kea-lfc` is run on a periodic basis by the Kea DHCP servers.
The process operates on a set of files, using them to receive input and
output of the lease entries and to indicate what stage the process is
Command-Line Options
====================
-``kea-lfc`` is run as follows:
+:iscman:`kea-lfc` is run as follows:
::
The ``-c`` argument specifies the configuration file. This is required,
but is not currently used by the process.
-The ``-p`` argument specifies the PID file. When the ``kea-lfc`` process
+The ``-p`` argument specifies the PID file. When the :iscman:`kea-lfc` process
starts, it attempts to determine whether another instance of the process
is already running by examining the PID file. If one is already running,
the new process is terminated; if one is not running, Kea writes its PID
into the PID file.
-The other filenames specify where the ``kea-lfc`` process should look
+The other filenames specify where the :iscman:`kea-lfc` process should look
for input, write its output, and perform its bookkeeping:
-- ``previous`` — when ``kea-lfc`` starts, this is the result of any
- previous run of ``kea-lfc``. When ``kea-lfc`` finishes, it is the
- result of this run. If ``kea-lfc`` is interrupted before completing,
+- ``previous`` — when :iscman:`kea-lfc` starts, this is the result of any
+ previous run of :iscman:`kea-lfc`. When :iscman:`kea-lfc` finishes, it is the
+ result of this run. If :iscman:`kea-lfc` is interrupted before completing,
this file may not exist.
-- ``input`` — before the DHCP server invokes ``kea-lfc``, it moves
- the current lease file here and then calls ``kea-lfc`` with this file.
+- ``input`` — before the DHCP server invokes :iscman:`kea-lfc`, it moves
+ the current lease file here and then calls :iscman:`kea-lfc` with this file.
-- ``output`` — this is the temporary file where ``kea-lfc`` writes the
+- ``output`` — this is the temporary file where :iscman:`kea-lfc` writes the
leases. Once the file has finished writing, it is moved to the
``finish`` file (see below).
-- ``finish`` — this is another temporary file ``kea-lfc`` uses for
- bookkeeping. When ``kea-lfc`` completes writing the ``output`` file, it
- moves the contents to the file of this name. After ``kea-lfc`` finishes deleting the
+- ``finish`` — this is another temporary file :iscman:`kea-lfc` uses for
+ bookkeeping. When :iscman:`kea-lfc` completes writing the ``output`` file, it
+ moves the contents to the file of this name. After :iscman:`kea-lfc` finishes deleting the
other files (``previous`` and ``input``), it moves this file to the ``previous``
- lease file. By moving the files in this fashion, ``kea-lfc`` and
+ lease file. By moving the files in this fashion, :iscman:`kea-lfc` and
the DHCP server processes can determine the correct file to use even
if one of the processes is interrupted before completing its task.
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-dhcp4``, the
-DHCPv4 server, is named ``kea-dhcp4``). All other loggers are children of
+logger, named after the program (e.g. the root logger for :iscman:`kea-dhcp4`, the
+DHCPv4 server, is named :iscman:`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
``kea-dhcp4.alloc-engine``.
logger, whereas any not specified are inherited from it.
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
+root logger :iscman:`kea-dhcp4` logging at the INFO level. In order to enable
DEBUG verbosity for DHCPv4 packet drops, we must create a configuration
entry for the logger with ``"name": "kea-dhcp4.bad-packets”``,
``"severity": "DEBUG"``, and an explicit debug level. All other configuration
If there are multiple logger specifications in the configuration that
might match a particular logger, the specification with the more
specific logger name takes precedence. For example, if there are entries
-for both ``kea-dhcp4`` and ``kea-dhcp4.dhcpsrv``, the main DHCPv4 server
+for both :iscman:`kea-dhcp4` and ``kea-dhcp4.dhcpsrv``, the main DHCPv4 server
program — and all libraries it uses other than the ``dhcpsrv`` library
(libdhcpsrv) — logs messages according to the configuration in the
-first entry (``kea-dhcp4``). Messages generated by the ``dhcpsrv`` library
+first entry (:iscman:`kea-dhcp4`). Messages generated by the ``dhcpsrv`` library
are logged according to the configuration set by the second entry.
Currently defined loggers are listed in the following table. The
| | | library. |
+----------------------------------+------------------------+--------------------------------+
| ``kea-dhcp-ddns`` | core | The root logger for |
- | | | the ``kea-dhcp-ddns`` |
+ | | | the :iscman:`kea-dhcp-ddns` |
| | | daemon. All |
| | | components used by |
| | | this daemon inherit |
| | | loggers. |
+----------------------------------+------------------------+--------------------------------+
| ``kea-dhcp-ddns.dctl`` | core | Used by |
- | | | the ``kea-dhcp-ddns`` |
+ | | | the :iscman:`kea-dhcp-ddns` |
| | | daemon to log |
| | | basic information |
| | | about the process, |
| | | reconfigurations. |
+----------------------------------+------------------------+--------------------------------+
| ``kea-dhcp-ddns.dhcpddns`` | core | Used by |
- | | | the ``kea-dhcp-ddns`` |
+ | | | the :iscman:`kea-dhcp-ddns` |
| | | daemon to log |
| | | events related to |
| | | DDNS operations. |
+----------------------------------+------------------------+--------------------------------+
| ``kea-dhcp-ddns.dhcp-to-d2`` | core | Used by the |
- | | | ``kea-dhcp-ddns`` daemon |
+ | | | :iscman:`kea-dhcp-ddns` daemon |
| | | to log |
| | | information about |
| | | events dealing with |
| | | processing. |
+----------------------------------+------------------------+--------------------------------+
| ``kea-dhcp-ddns.d2-to-dns`` | core | Used by the |
- | | | ``kea-dhcp-ddns`` daemon |
+ | | | :iscman:`kea-dhcp-ddns` daemon |
| | | to log |
| | | information about |
| | | events dealing with |
.. note::
- The ``keactrl`` tool, described in :ref:`keactrl`, can be configured
+ The :iscman:`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 have
no effect; the servers use a logging severity of DEBUG
regardless of the logging settings specified in the configuration
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 :iscman:`keactrl` configuration.
.. _debuglevel:
- ``%c``
The log source. This includes two elements: the Kea process generating the
- message, in this case, ``kea-dhcp4``; and the component within the program
+ message, in this case, :iscman:`kea-dhcp4`; and the component within the program
from which the message originated, ``dhcpsrv`` (e.g. the name of the
library used by DHCP server implementations).
# service kea-dhcp6 restart
.. note::
- ``keactrl`` is not available in packages, as similar functionality is provided
+ :iscman:`keactrl` is not available in packages, as similar functionality is provided
by the native systemctl scripts.
7. On CentOS, Fedora, and Alpine, the service must be enabled at boot
available in the Kea section of `ISC's
Knowledgebase <https://kb.isc.org/docs>`__.
-The details of ``keactrl`` script usage can be found in :ref:`keactrl`.
+The details of :iscman:`keactrl` script usage can be found in :ref:`keactrl`.
Once Kea services are up and running, consider deploying a dashboard solution
to monitor running services. For more details, see :ref:`stork`.
================================
The Kea servers can be started directly, without the need to use
-``keactrl`` or ``systemctl``. To start the DHCPv4 server run the following command:
+:iscman:`keactrl` or ``systemctl``. To start the DHCPv4 server run the following command:
.. code-block:: console
servers or accessed over the internal network; and a Stork monitoring system.
This modular architecture allows the administrator to minimize the attack surface
by minimizing the code that is loaded and running.
-For example, ``kea-dhcp-ddns`` should not be run unless DNS updates are required.
-Similarly, ``kea-lfc`` is never triggered (and can be safely removed or never installed) if memfile is not used.
+For example, :iscman:`kea-dhcp-ddns` should not be run unless DNS updates are required.
+Similarly, :iscman:`kea-lfc` is never triggered (and can be safely removed or never installed) if memfile is not used.
Potential Kea security issues can be minimized by running only those processes required in the local environment.
Limiting Application Permissions
Securing Kea Administrative Access
----------------------------------
-The three primary Kea daemons (``kea-dhcp4``, ``kea-dhcp6`` and ``kea-dhcp-ddns``) all support a control
+The three primary Kea daemons (:iscman:`kea-dhcp4`, :iscman:`kea-dhcp6` and :iscman:`kea-dhcp-ddns`) all support a control
channel, which is implemented as a UNIX socket. The control channel, which opens a UNIX socket, is disabled by default;
however, many configuration examples have it enabled, as it is a very popular feature. To
read from or write to this socket, root access is generally required, although if Kea is configured
Shell Usage
===========
-``kea-shell`` is run as follows:
+:iscman:`kea-shell` is run as follows:
.. code-block:: console
TLS Support
===========
-Since Kea 1.9.6, ``kea-shell`` supports HTTPS connections. The TLS/HTTPS
+Since Kea 1.9.6, :iscman:`kea-shell` supports HTTPS connections. The TLS/HTTPS
support requires Python 3. The additional command-line arguments are:
- ``--ca`` specifies the file or directory name of the Certification
projects / thirdparty / kea.git / commitdiff
