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

Resolve "Editorial review of the ARM prior to 2.6 release"

Browse Source
This commit is contained in:
Suzanne Goldlust 2024-05-16 20:09:54 +00:00 committed by Thomas Markwalder
parent 3f7db23b61
commit 7730a1d60d
36 changed files with 1124 additions and 1143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
doc/sphinx/arm/admin.rst
View File

@ -48,11 +48,11 @@ upgrade, and dump lease data to a text file.
``backend``. Additional, non-mandatory options may be specified. The
currently supported commands are:
- ``db-init`` — initializes a new database schema. This is useful
during a new Kea installation. The database is initialized to the
latest version supported by the version of the software being installed.
Called automatically on startup or reconfiguration of Kea DHCP servers if
required.
- ``db-init`` — initializes a new database schema, which is useful
during a new Kea installation. The new database is updated to
match the Kea version being installed. :iscman:`kea-admin` is
automatically invoked with this command if a missing schema is
detected during startup or reconfiguration of Kea DHCP servers.
- ``db-version`` — reports the database backend version number. This
is not necessarily equal to the Kea version number, as each backend

24
doc/sphinx/arm/classify.rst
View File

@ -503,12 +503,12 @@ Notes:
+-----------------------+-------------------------+-----------------------+
| Lcase | lcase('LoWeR') | Converts the value of |
| | | a string expression |
| | | to lower case e.g. |
| | | to lower case, e.g. |
| | | 'lower' |
+-----------------------+-------------------------+-----------------------+
| Ucase | ucase('uPpEr') | Converts the value of |
| | | a string expression |
| | | to upper case e.g. |
| | | to upper case, e.g. |
| | | 'UPPER' |
+-----------------------+-------------------------+-----------------------+
| Split | split('foo.bar', '.', 2)| Return the second |
@ -759,11 +759,11 @@ domain name servers.
...
}
The next example shows a client class being defined for use by the DHCPv6
server. In it the class named "Client_enterprise" is defined. It is
The next example shows a client class named "Client_enterprise" being defined
for use by the DHCPv6 server. It is
comprised of all clients whose client identifiers start with the given
hex string (which would indicate a DUID based on an enterprise ID of
``0x0002AABBCCDD``). Members of this class will be given 2001:db8:0::1 and
hex string, which would indicate a DUID based on an enterprise ID of
``0x0002AABBCCDD``. Members of this class will be given 2001:db8:0::1 and
2001:db8:2::1 as their domain name servers.
::
@ -1138,17 +1138,17 @@ Client classes in Kea follow the order in which they are specified in the
configuration (vs. alphabetical order). Required classes follow the order in
which they are required.
When determining which client-class information (comprising of
options, lease lifetimes or DHCPv4 field values) that is part of class
definitions, to include in the response, the server examines the union of
When determining which client-class information (comprised of
options, lease lifetimes, or DHCPv4 field values) is part of the class
definitions to be included in the response, the server examines the union of
options from all of the assigned classes. If two or more classes include the
same class information, the value from the first assigned class is used.
``ALL`` is always the first class, hence the class with the highest
``ALL`` is always the first class, i.e. the class with the highest
priority, and matching required classes are last, so they have the
lowest priority.
Optons defined in classes override any global options, and in turn will be
overridden by options defined for an individual subnet, shared network, pool or
Options defined in classes override any global options, and in turn are
overridden by options defined for an individual subnet, shared network, pool, or
reservation.
On the other hand, lease lifetimes and DHCPv4 field values defined at class

22
doc/sphinx/arm/config-backend.rst
View File

@ -19,14 +19,14 @@ manage and fetch the configuration information from the MySQL database.
The PostgreSQL Configuration Backend is the logic implemented within
:ischooklib:`libdhcp_pgsql_cb.so`, which provides a complete set of functions to
manage and fetch the configuration information from the PostgreSQL database.
From herein, the term "database" is used to refer to either a MySQL or
From here on, the term "database" is used to refer to either a MySQL or
PostgreSQL database.
In small deployments, e.g. those comprising a single DHCP server
instance with limited and infrequently changing number of subnets, it
may be impractical to use the CB as a configuration repository because
it requires additional third-party software to be installed and
configured - in particular the database server, client and libraries.
configured - in particular the database server, client, and libraries.
Once the number of DHCP servers and/or the number of managed subnets in the
network grows, the usefulness of the CB becomes obvious.
@ -56,7 +56,7 @@ entire configuration to the new server when a common database is used.
Using the database as a configuration repository for Kea servers also
brings other benefits, such as:
- the ability to use database specific tools to access the configuration
- the ability to use database-specific tools to access the configuration
information;
- the ability to create customized statistics based on the information
@ -163,13 +163,13 @@ in two independent configuration sources.
CB Components
-------------
To use a MySQL configuration backend you must compile
:ischooklib:`libdhcp_mysql_cb.so` and configure the DHCP servers to load it.
To use a MySQL configuration backend, :ischooklib:`libdhcp_mysql_cb.so`
must be compiled and the DHCP servers must be configured to load it.
It is compiled when the ``--with-mysql`` configuration switch is used during the Kea build.
The MySQL C client libraries must be installed, as explained in :ref:`dhcp-install-configure`.
To use a PostgreSQL configuration backend you must compile :ischooklib:`libdhcp_pgsql_cb.so`
and configure the DHCP servers to load it. It is compiled when
To use a PostgreSQL configuration backend, :ischooklib:`libdhcp_pgsql_cb.so` must
be compiled and the DHCP servers must be configured to load it. It is compiled when
the ``--with-pgsql`` configuration switch is used during the Kea build. The PostgreSQL
C client libraries must be installed, as explained in :ref:`dhcp-install-configure`.
@ -183,8 +183,8 @@ C client libraries must be installed, as explained in :ref:`dhcp-install-configu
servers' configuration information within the database. This library can
be attached to both DHCPv4 and DHCPv6 server instances. While it is
possible to manage the configuration information without :ischooklib:`libdhcp_cb_cmds.so`
with commonly available tools, such as MySQL Workbench or
the command-line MySQL client, or by directly working with the database;
using commonly available tools, such as MySQL Workbench or
the command-line MySQL client, or by directly working with the database,
these avenues are neither recommended nor supported.
The DHCPv4 and DHCPv6 server-specific configurations of the CB, as well as
@ -220,7 +220,7 @@ servers in the database.
Commands which contain the logical server `all` are applied to all servers
connecting to the database. The `all` server cannot be
deleted or modified, and it is not returned among other servers
as a result of the :isccmd:`remote-server4-get-all`, :isccmd:`remote-server6-get-all` commands.
as a result of the :isccmd:`remote-server4-get-all` and :isccmd:`remote-server6-get-all` commands.
In most cases, there are no server tags defined in the configuration
database; all connecting servers get the same configuration
@ -242,7 +242,7 @@ servers.
To differentiate between different Kea server configurations, a
list of the server tags used by the servers must be stored in the
database. For the DHCPv4 and DHCPv6 servers, it can be done using the
database. For the DHCPv4 and DHCPv6 servers, this can be done using the
:isccmd:`remote-server4-set` and :isccmd:`remote-server6-set` commands. The
server tags can then be used to associate the configuration information with
the servers. However, it is important to note that some DHCP

14
doc/sphinx/arm/config.rst
View File

@ -174,17 +174,17 @@ syntax and its top-level element is a map (i.e. the data must be enclosed in
curly brackets). However, some hook libraries may expect specific formatting;
please consult the specific hook library documentation for details.
In a sense the user-context mechanism has superseded the JSON comment
capabilities; ISC encourages administrators to use user-context instead of
the older mechanisms. To promote this way of storing comments, Kea compared
converts JSON comments to user-context on the fly.
The user-context mechanism has superseded the JSON comment
capabilities; ISC encourages administrators to use user context instead of
the older mechanisms. To promote this way of storing comments, Kea
converts JSON comments to user context on the fly.
However, if the configuration uses the old JSON
comment, the :isccmd:`config-get` command returns a slightly modified
configuration. It is not uncommon for a call for :isccmd:`config-set` followed by a
comment method, the :isccmd:`config-get` command returns a slightly modified
configuration. It is not uncommon for a call for :isccmd:`config-set` followed by
:isccmd:`config-get` to receive a slightly different structure.
The best way to avoid this problem is simply to abandon JSON comments and
use user-context.
use user context.
Kea supports user contexts at the following levels: global scope,
interfaces configuration, shared networks,

71
doc/sphinx/arm/ctrl-channel.rst
View File

@ -352,9 +352,9 @@ returned is roughly equal to the configuration that was loaded using the
:isccmd:`config-set` command. However, there may be certain differences, as
comments are not retained. If the original configuration used file
inclusion, the returned configuration includes all parameters from
all included files. Starting with 2.4.0, the successful response also
contains a SHA-256 digest that can be used to easily determine if a
configuration has changed or not.
all included files. In Kea 2.4.0 and later, the successful response also
contains a SHA-256 digest that can be used to easily determine whether a
configuration has changed.
.. warning::
@ -400,9 +400,9 @@ And the server's response:
}
}
Starting with 2.4.0, also ``config-set`` and ``config-get`` return the SHA-256 hash
of the new or current configuration. This may be used to later determine if a configuration
has changed or not.
In Kea 2.4.0 and later, ``config-set`` and ``config-get`` also return the SHA-256 hash
of the new or current configuration. This may be used to determine whether a configuration
has changed.
.. isccmd:: config-reload
.. _command-config-reload:
@ -414,9 +414,9 @@ The :isccmd:`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 system administrator can tweak the configuration file and use this
command to force Kea pick up the changes.
command to force Kea to pick up the changes.
Caution should be taken when mixing this with the :isccmd:`config-set` command. Kea
Care should be taken when using this in conjunction with the :isccmd:`config-set` command. Kea
remembers the location of the configuration file it was started with,
and this configuration can be significantly changed using the :isccmd:`config-set`
command. When :isccmd:`config-reload` is issued after :isccmd:`config-set`, Kea attempts
@ -550,7 +550,7 @@ 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. The hook libraries
are passed the same parameter values (if any) that were passed when they
originally loaded.
were originally loaded.
::
@ -643,9 +643,9 @@ string, ``text``, describing the outcome:
{"result": 1, "text": "unsupported parameter: BOGUS (<string>:16:26)" }
Starting with 2.4.0, the successful response from a DHCPv4, DHCPv6, or DHCP-DDNS daemons
also contain a SHA-256 digest of the newly set configuration. The digest can be used to easily
determine if a configuration has changed or not.
In Kea 2.4.0 and later, the successful response from a DHCPv4, DHCPv6, or DHCP-DDNS daemon
also contains a SHA-256 digest of the newly set configuration. The digest can be used to easily
determine whether a configuration has changed.
.. isccmd:: shutdown
.. _command-shutdown:
@ -654,7 +654,7 @@ The ``shutdown`` Command
------------------------
The :isccmd:`shutdown` command instructs the server to initiate its shutdown
procedure. It is the equivalent of sending a ``SIGTERM`` signal to the
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:
@ -714,24 +714,24 @@ if the :isccmd:`dhcp-enable` command is not sent before this time elapses.
Since Kea 1.9.4, there is an additional ``origin`` parameter that specifies the
command source. A server administrator should typically omit this parameter
because the default value "user" indicates that the administrator sent the
command. In Kea 2.5.5 thru 2.5.7 this parameter was also used in communication
command. In Kea 2.5.5 through 2.5.7, this parameter was also used in communication
between the HA partners to specify the identifier of an HA service sending the command
in a numeric format. However, due to the compatibility issues with the older
Kea versions that did not properly parse the numeric values, it was necessary
in a numeric format. However, due to compatibility issues with older
Kea versions that did not properly parse numeric values, it was necessary
to introduce the new parameter, ``origin-id``, in Kea 2.5.8.
It holds a numeric value representing the origin of the command. The same value
can still be passed using the ``origin`` parameter, but it can cause the
aforementioned compatibility issues between the HA partners running different
Kea versions. Therefore, new Kea versions favor using ``origin-id`` in communication
between the HA partners. The ``origin`` parameter can still be used, but the
``origin-id`` takes precedence. Overall, it is recommended that both parameters be
omitted from the user commands.
aforementioned compatibility issues between HA partners running different
Kea versions; if both are used, ``origin-id`` takes precedence. New Kea versions
favor using ``origin-id`` in communication between the HA partners, but
overall, it is recommended that both parameters be
omitted and the default value used.
The following codes represent the supported origins in numeric format:
- ``1`` - a user command, same as specifying ``"origin": "user"``,
- ``2000``, ``2001``, ``2002`` etc. - origins specified by HA partners where
- ``1`` - a user command; the same as specifying ``"origin": "user"``.
- ``2000``, ``2001``, ``2002``, etc. - origins specified by HA partners where
the increments above ``2000`` are distinct HA service identifiers used when
the partners have many relationships.
@ -748,7 +748,7 @@ In the following example:
}
}
the effective origin will be ``2002`` which indicates it is an HA partner
the effective origin is ``2002``, which indicates it is an HA partner
sending the command for the service with ID of ``2``. The ``origin``
parameter will be ignored in this case.
@ -763,24 +763,23 @@ The :isccmd:`dhcp-enable` command globally enables the DHCP service.
Since Kea 1.9.4, there is an additional ``origin`` parameter that specifies the
command source. A server administrator should typically omit this parameter
because the default value "user" indicates that the administrator sent the
command. In Kea 2.5.5 thru 2.5.7 this parameter was also used in communication
command. In Kea 2.5.5 through 2.5.7, this parameter was also used in communication
between the HA partners to specify the identifier of an HA service sending the command
in a numeric format. However, due to the compatibility issues with the older
Kea versions that did not properly parse the numeric values, it was necessary
in a numeric format. However, due to compatibility issues with older
Kea versions that did not properly parse numeric values, it was necessary
to introduce the new parameter, ``origin-id``, in Kea 2.5.8.
It holds a numeric value representing the origin of the command. The same value
can still be passed using the ``origin`` parameter, but it can cause the
aforementioned compatibility issues between the HA partners running different
Kea versions. Therefore, new Kea versions favor using ``origin-id`` in communication
between the HA partners. The ``origin`` parameter can still be used, but the
``origin-id`` takes precedence. Overall, it is recommended that both parameters be
omitted from the user commands.
aforementioned compatibility issues between HA partners running different
Kea versions.; if both are used, ``origin-id`` takes precedence. New Kea versions
favor using ``origin-id`` in communication between the HA partners, but
overall, it is recommended that both
The following codes represent the supported origins in numeric format:
- ``1`` - a user command, same as specifying ``"origin": "user"``,
- ``2000``, ``2001``, ``2002`` etc. - origins specified by HA partners where
- ``1`` - a user command; the same as specifying ``"origin": "user"``.
- ``2000``, ``2001``, ``2002``, etc. - origins specified by HA partners where
the increments above ``2000`` are distinct HA service identifiers used when
the partners have many relationships.
@ -796,7 +795,7 @@ In the following example:
}
}
the effective origin will be ``2002`` which indicates it is an HA partner
the effective origin is ``2002``, which indicates it is an HA partner
sending the command for the service with ID of ``2``. The ``origin``
parameter will be ignored in this case.
@ -880,7 +879,7 @@ The ``version-get`` Command
---------------------------
The :isccmd:`version-get` command returns extended information about the Kea
version. It is the same information available via the ``-V``
version; it is the same information available via the ``-V``
command-line argument. This command does not take any parameters.
::

18
doc/sphinx/arm/database-connectivity.rst
View File

@ -25,8 +25,8 @@ If ``retry-on-startup`` is set to ``true``, the server will start reconnection
attempts even at server startup or on reconfigure events, and will honor the
action specified in the ``on-fail`` parameter.
Database connection retries are not attempted on startup if the
:ischooklib:`libdhcp_limits.so` is loaded because the hook library requires a
valid connection to the database to check if JSON format is supported and to
:ischooklib:`libdhcp_limits.so` is loaded, because the hook library requires a
valid connection to the database to check whether JSON format is supported and to
recount class limits.
During dynamic reconfiguration, all backends are disconnected and then
@ -61,16 +61,16 @@ If connectivity to all backends is restored, the server returns to normal
operations. If the connection cannot be restored and the server is configured
to exit, it issues a fatal error before shutdown.
For Kea DHCP servers to work with database backends, the schema has to be
created and has to have the version specific to the version of the running Kea
server. If the version check fails on a database backend that is not configured
as readonly, Kea attempts to initialize the schema.
For Kea DHCP servers to work with database backends, the database schema must be
created and must match the version of the Kea
server. If the version check fails and the database backend is not configured
as read-only, Kea attempts to initialize the schema.
.. note::
Schema upgrades are not attempted to not accidentally remove the
opportunity for prior administrative actions that users may be interested in,
like, for example, backing up the database or temporarily shutting off running
Kea does not automatically attempt to upgrade an existing schema; doing so
might deprive users of the opportunity to take precautions, such as
backing up the database or temporarily shutting off running
Kea servers that are currently operating on the database.
The connection to the database server can optionally be protected by TLS.

17
doc/sphinx/arm/ddns.rst
View File

@ -12,19 +12,18 @@ Overview
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 (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` respectively).
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
carries out the necessary conversation with those servers to update the
DNS data.
For the ability to generate host names procedurally, based on an expression, and
for the ability to skip DDNS updates on a per-client basis, or fine-tuning
various DNS update aspects, the :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` can
load the premium hook library `libdhcp_ddns_tuning.so` which is available from
ISC. Please refer to :ref:`hooks-ddns-tuning` documentation for the
configuration options.
The Kea hook library :ischooklib:`libdhcp_ddns_tuning.so` provides the ability
for both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` to generate host names
procedurally based on an expression, to skip DDNS updates on a per-client basis,
or to fine-tune various DNS update aspects. Please refer to the :ref:`hooks-ddns-tuning`
documentation for the configuration options.
.. _dhcp-ddns-dns-server-selection:
@ -410,8 +409,8 @@ Every entry in the list has three parameters:
key. This value is case-sensitive and must exactly match the value
specified on the DNS server(s). It is a base64-encoded text value.
- ``secret-file`` - since Kea 2.5.8 a more secure alternative is supported:
specify a file name where the secret can be found, i.e. the base64-encoded
- ``secret-file`` - since Kea 2.5.8, this more secure alternative is supported.
This value specifies the file name where the secret can be found, i.e. the base64-encoded
secret is the content of the file.
As an example, suppose that a domain D2 will be updating is maintained

442
doc/sphinx/arm/dhcp4-srv.rst
View File

File diff suppressed because it is too large Load Diff

478
doc/sphinx/arm/dhcp6-srv.rst
View File

File diff suppressed because it is too large Load Diff

132
doc/sphinx/arm/ext-radius.rst
View File

@ -9,14 +9,14 @@ RADIUS Overview
---------------
This hook library allows Kea to interact with two types of RADIUS
services: access and accounting. Although the most common DHCP and RADIUS
integration is done on the DHCP relay-agent level (DHCP clients send
services: access and accounting. The most common DHCP and RADIUS
integration is done on the DHCP relay-agent level: DHCP clients send
DHCP packets to DHCP relays; those relays contact the RADIUS server and
depending on the response either send the packet to the DHCP server or
drop it), it does require DHCP relay hardware to support RADIUS
communication. Also, even if the relay has the necessary support, it is
either send the packet to the DHCP server or drop it, depending on the
response. It does require DHCP relay hardware to support RADIUS
communication, though, and even if the relay has the necessary support, it is
often not flexible enough to send and receive additional RADIUS
attributes. As such, the alternative looks more appealing: to extend the
attributes. There is a more appealing alternative: to extend the
DHCP server to talk to RADIUS directly. That is the goal of this library.
.. note::
@ -30,9 +30,9 @@ Access-Request to the RADIUS server and waits for a response. The server
then sends back either an Access-Accept with specific client attributes,
or an Access-Reject. There are two cases supported here: first, the
Access-Accept includes a Framed-IP-Address attribute (for DHCPv4) or a
Framed-IPv6-Address attribute or a Delegated-IPv6-Prefix (for DHCPv6),
Framed-IPv6-Address attribute/Delegated-IPv6-Prefix (for DHCPv6),
which are interpreted by Kea as instructions to assign the specified IPv4
or IPv6 address, or IPv6 prefix. This effectively means RADIUS can act
or IPv6 address/IPv6 prefix. This effectively means RADIUS can act
as an address-reservation database.
The second supported case is the ability to assign clients to specific
@ -60,7 +60,7 @@ takes many parameters. For example, this configuration can be used:
{
"Dhcp4": {
// Your regular DHCPv4 configuration parameters goes here.
// Your regular DHCPv4 configuration parameters go here.
"hooks-libraries": [
{
@ -88,14 +88,14 @@ takes many parameters. For example, this configuration can be used:
RADIUS is a complicated environment. As such, it is not feasible
to provide a default configuration that works for everyone.
However, we do have an example that showcases some of the more common
features. Please see ``doc/examples/kea4/hooks-radius.json`` in the Kea
features; please see ``doc/examples/kea4/hooks-radius.json`` in the Kea
sources.
The RADIUS hook library supports the following global configuration
flags:
- ``bindaddr`` (default ``"*"``) - specifies the address to be used by the
hook library in communication with RADIUS servers. The ``"*"`` special
hook library in communication with the RADIUS servers. The ``"*"`` special
value tells the kernel to choose the address at hook library load time.
- ``canonical-mac-address`` (default ``false``) - specifies whether MAC
@ -103,49 +103,49 @@ flags:
pairs of hexadecimal digits separated by ``-``).
- ``client-id-pop0`` (default ``false``) - is used with
:ischooklib:`libdhcp_flex_id.so`. Removes the leading zero (or pair of zeroes
in DHCPv6) type in the client id (duid in DHCPv6). See
:ischooklib:`libdhcp_flex_id.so`; it removes the leading zero (or pair of zeroes
in DHCPv6) type in the client ID (DUID in DHCPv6). See
``client-id-printable`` for any value implications when used in conjunction
with it.
- ``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
hexadecimal. It implies that ``client-id-pop0`` and ``extract-duid`` as 0 and 255 are
not printable.
- ``deadtime`` (default ``0``) - is a mechanism that helps in sorting the
servers such that the servers that have proved responsive so far are inquired
first, and the servers that have proved unresponsive are left at the end. The
servers so those that have proved responsive so far are contacted
first, and the servers that have proved unresponsive are left to try later. The
deadtime value specifies the number of seconds after which a server is
considered unresponsive. 0 disables the mechanism.
- ``dictionary`` (default ``"/etc/kea/radius/dictionary"``) - is the
attribute and value dictionary. Note that it is a critical parameter.
attribute and value dictionary; note that it is a critical parameter.
A dictionary is provided by Kea and is set by default.
- ``extract-duid`` (default ``true``) - extracts the embedded duid from an
RFC-4361-compliant DHCPv4 client id. See ``client-id-printable`` for any
- ``extract-duid`` (default ``true``) - extracts the embedded DUID from an
RFC 4361-compliant DHCPv4 client ID. See ``client-id-printable`` for any
value implications when used in conjunction with it.
- ``identifier-type4`` (default ``"client-id"``) - specifies the identifier
type to build the User-Name attribute. It should be the same as the
type to build the User-Name attribute for DHCPv4; it should be the same as the
host identifier. When :ischooklib:`libdhcp_flex_id.so` is used, then
``replace-client-id`` must be set to ``true`` and ``client-id`` must be used
with ``client-id-pop0`` enabled.
- ``identifier-type6`` (default ``"duid"``) - specifies the identifier type to
build the User-Name attribute. It should be the same as the host
build the User-Name attribute for DHCPv6; it should be the same as the host
identifier. When :ischooklib:`libdhcp_flex_id.so` is used, then
``replace-client-id`` must be set to ``true`` and ``duid`` must be used with
``client-id-pop0`` enabled.
- ``nas-ports`` (default ``[]``), specifies the NAS port to use in place of
a subnet ID (default behavior). It is an array of maps, each map having two
elements at most: the mandatory NAS port value, and, optionally, a selector
consisting of either a subnet id, a subnet prefix, or a shared-network name.
elements at most: the mandatory NAS port value, and optionally, a selector
consisting of either a subnet ID, a subnet prefix, or a shared-network name.
If the selector is applied to the packet, the NAS port is used instead of the
subnet id. When the subnet id is 0 or missing, the specified NAS port acts as
a default. Its substition happens for all packets that did not match a
subnet ID. When the subnet ID is 0 or missing, the specified NAS port acts as
a default. The substitution happens for all packets that did not match a
selector.
- ``realm`` (default ``""``) - is the default realm.
@ -153,8 +153,8 @@ flags:
- ``reselect-subnet-address`` (default ``false``) - enables subnet reselection
according to the value of the Framed-IP-Address or, respectively,
the Framed-IPv6-Address attribute from the RADIUS access response. With this
flag enabled, if the IP address is not in range of the currently selected
subnet, but is in range of another subnet that is selectable with regards to
flag enabled, if the IP address is not in the range of the currently selected
subnet, but is in the range of another subnet that is selectable with regards to
other criteria, the latter subnet is selected and used further in the lease
assignment process.
@ -165,7 +165,7 @@ flags:
another selectable subnet that is guarded by it, the latter subnet is
selected and used further in the lease assignment process.
This reselection is attempted first, and if successful, it prevents the
function of reselect-subnet-address from coming into effect.
function of ``reselect-subnet-address`` from coming into effect.
- ``retries`` (default ``3``) - is the number of retries before trying the
next server.
@ -174,11 +174,11 @@ flags:
persistent storage for accounting session history.
- ``thread-pool-size`` (default ``0``) indicates the number of threads that
is used for sending RADIUS requests and processing RADIUS responses for both
access and accounting services before passing it to the core thread pool. A
are used for sending RADIUS requests and processing RADIUS responses for both
access and accounting services before passing them to the core thread pool. A
value of ``0`` instructs the RADIUS hook library to use the same number of
threads used for core DHCP processing. This value is only relevant if Kea
core is configured as multi-threaded. Single-threaded Kea core results in
threads used for core DHCP processing. This value is only relevant if the Kea
core is configured as multi-threaded; a single-threaded Kea core results in
single-threaded RADIUS processing.
- ``timeout`` (default ``10``) - is the number of seconds during which a
@ -212,34 +212,34 @@ At the service level, three sections can be configured:
defines the value in hex), or ``expr`` (which defines an expression
that is evaluated for each incoming packet independently).
- ``name`` - the name of the attribute.
- ``name`` - is the name of the attribute.
- ``type`` - the type of the attribute. Either the type or the name must be
- ``type`` - is the type of the attribute. Either the type or the name must be
provided, and the attribute must be defined in the dictionary.
- ``data`` - the first of three ways to specify the attribute content.
- ``data`` - is the first of three ways to specify the attribute content.
It specifies the textual representation of the attribute content.
- ``raw`` - the second of three ways to specify the attribute content.
- ``raw`` - is the second of three ways to specify the attribute content.
It specifies the content in hexadecimal.
- ``expr`` - the last of the three ways to specify the attribute content.
- ``expr`` - is the last of the three ways to specify the attribute content.
It specifies an evaluation expression on the DHCP query packet.
Currently this is restricted to the access service.
Attributes are supported only for the access service.
- The ``peer-updates`` boolean flag (default ``true``) controls whether lease
updates coming from an active High-Availability (HA) partner should result in
an accounting request. This may be desirable to remove duplicates if HA
partners are configured to send request to the same RADIUS server. The flag is
partners are configured to send requests to the same RADIUS server. The flag is
only supported by the accounting service. The lease synchronization process at
the startup of an HA node does not trigger a RADIUS accounting request,
regardless of the value of this flag.
- The ``max-pending-requests`` positive integer (default ``0``) limits the
number of pending RADIUS requests. The value ``0`` means no limit. It is
supported only by the access service. ``64`` can be a good value to set it to.
number of pending RADIUS requests. It is supported only by the access service.
The value ``0`` means no limit; ``64`` is a recommended setting.
For example, to specify a single access server available on localhost
that uses ``"xyz123"`` as a secret, and tell Kea to send three additional
@ -353,14 +353,14 @@ And here's how to specify period-separated hexadecimal notation (``dead.beef.caf
For :ischooklib:`libdhcp_radius.so` to operate properly in DHCPv4,
:ischooklib:`libdhcp_host_cache.so` must also be loaded. The reason for this
is somewhat complex. In a typical deployment, the DHCP clients send
is somewhat complex. In a typical deployment, 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
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 cannot send
by sending packets directly to the DHCP server. The relays cannot
insert their RAI options at that point, 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
@ -369,7 +369,7 @@ later when sending accounting messages.
This mechanism is implemented based on user context in host
reservations. (See :ref:`user-context` and :ref:`user-context-hooks` for
details.) The host-cache mechanism allows the information retrieved by
RADIUS to be stored and later used for sending access and accounting
RADIUS to be stored and used later to send access and accounting
queries to the RADIUS server. In other words, the host-cache mechanism
is mandatory, unless administrators do not want RADIUS communication for messages
other than Discover and the first Request from each client.
@ -377,7 +377,7 @@ other than Discover and the first Request from each client.
.. note::
Currently the RADIUS hook library is incompatible with the
``early-global-reservations-lookup`` global parameter i.e.
``early-global-reservations-lookup`` global parameter, i.e.
setting the parameter to ``true`` raises an error when the
hook library is loaded.
@ -394,8 +394,8 @@ RADIUS Server Setup Example
---------------------------
The RADIUS hook library requires at least one RADIUS server to function. One
popular open-source implementation is FreeRADIUS. This is how it can be
set up to enable basic functionality in Kea.
popular open source implementation is FreeRADIUS; here's how to
set it up to enable basic functionality in Kea.
1. Install FreeRADIUS through the package manager or from the tarballs available
on [the freeradius.org download page](https://freeradius.org/releases/).
@ -414,10 +414,10 @@ set up to enable basic functionality in Kea.
5. If the Kea DHCP server and the RADIUS server are on different machines,
edit ``/etc/freeradius/clients.conf`` with the proper address under
``ipadddr``. This file is also where the secret is set, which needs to match
``ipadddr``. This file is also where the secret is set; it needs to match
the one set in the hook library's configuration.
6. If RADIUS is used for the purpose of authorizing DHCP clients, each DHCP
6. If RADIUS is used to authorize DHCP clients, each DHCP
client needs to have an entry in the authorize file, which can be commonly
found at:
@ -425,14 +425,14 @@ set up to enable basic functionality in Kea.
- ``/etc/freeradius/3.0/mods-config/files/authorize``
- ``/etc/freeradius/users`` (for RADIUS 2.x series)
Entries need to have the password set which needs to match the password
configured in the configuration of the RADIUS hook library under the
``User-Password`` attribute. Each entry can have zero, one or multiple
The passwords for entries must match the passwords
in the configuration of the RADIUS hook library under the
``User-Password`` attribute. Each entry can have zero or more
attributes.
In the following example, there are 6 entries with the password set to the
client ID, which would need to be dynamically set in the hook library's
configuration. Here's how the entries can look like:
In the following example, there are six entries with the password set to the
client ID, which needs to be dynamically set in the hook library's
configuration. Here's how the entries might look:
::
@ -454,8 +454,8 @@ set up to enable basic functionality in Kea.
Framed-IPv6-Address = "2001:db8::9",
Framed-Pool = "classroom"
7. Accounting should work out of the box with Kea, but customizations are
possible in the accounting file, which can be commonly found at:
7. Accounting does not need to be modified to work with Kea, but customizations are
possible in the accounting file, which can commonly be found at:
- ``/etc/radius-config/mods-config/files/accounting``
- ``/etc/freeradius/3.0/mods-config/files/accounting``
@ -465,7 +465,7 @@ set up to enable basic functionality in Kea.
RADIUS Workflows for Lease Allocation
-------------------------------------
The following diagrams show a high level view of how RADIUS assists with the
The following diagrams show a high-level view of how RADIUS assists with the
lease allocation process in :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`.
.. figure:: ../uml/radius.*
@ -481,21 +481,21 @@ Parked-Packet Limit
Refer to :ref:`parked-packet-limit` for a basic introduction to packet parking.
The RADIUS hook library makes use of this mechanism. To allow for asynchronous
The RADIUS hook library uses this mechanism. To allow for asynchronous
communication between Kea and the RADIUS server and concurrent processing of
DHCP packets by the Kea server, the DHCP request is parked, before the access
request is sent on the subnet select callout. When the access response becomes
available to the Kea DHCP server, the request is unparked, and the server
continues processing on it.
continues processing it.
.. _radius-differences:
Differences Between RADIUS Hook Libraries Prior To 2.4.0 and As Of 2.6.0
------------------------------------------------------------------------
Differences Between RADIUS Hook Libraries Prior To Kea 2.4.0 and As Of 2.6.0
----------------------------------------------------------------------------
The RADIUS hook library in 2.4.0 and prior versions relied on the FreeRADIUS
client library to function. Starting with 2.6.0 and onwards, the RADIUS hook
library is standalone with its own RADIUS client implementation and its own
client library to function. Starting with 2.6.0 and onward, the RADIUS hook
library is standalone, with its own RADIUS client implementation and its own
RADIUS dictionary. There are differences:
.. list-table::
@ -517,7 +517,7 @@ RADIUS dictionary. There are differences:
- Taken from the FreeRADIUS dictionary.
- Taken from the Kea RADIUS dictionary and the IANA registry. There is an aliasing mechanism built into the library that ensures backward compatibility e.g. ``Password`` translates to the standard name of the attribute ``User-Password``.
- Taken from the Kea RADIUS dictionary and the IANA registry. There is an aliasing mechanism built into the library that ensures backward compatibility, e.g. ``Password`` translates to the standard name of the attribute ``User-Password``.
* - Resolution of RADIUS Server Domain Names

2
doc/sphinx/arm/hammer.rst
View File

@ -91,7 +91,7 @@ To exclude the installation and generation of docs, type:
$ ./hammer.py build -p local -x install docs
The basic scope can be extended by mysql, pgsql, native-pkg, shell, and forge.
Please check ``./hammer.py build --help`` for more details.
Please refer to ``./hammer.py build --help`` for more details.
.. note::

20
doc/sphinx/arm/hooks-cb-cmds.rst
View File

@ -13,10 +13,10 @@ configuration information in the respective databases. For example:
:ischooklib:`libdhcp_pgsql_cb.so` implements this API for PostgreSQL.
To manage the configuration information in a MySQL database, both
:ischooklib:`libdhcp_mysql_cb.so` and :ischooklib:`libdhcp_cb_cmds.so`
must be loaded by the server used for the configuration management.
must be loaded by the server used for configuration management.
To manage the configuration information in a PostgreSQL database, both
:ischooklib:`libdhcp_pgsql_cb.so` and :ischooklib:`libdhcp_cb_cmds.so`
must be loaded by the server used for the configuration management.
must be loaded by the server used for configuration management.
More information on how to configure the Configuration Backend hook library for
use with a MySQL or PostgreSQL database can be found in the :ref:`dhcp4-cb`
@ -892,7 +892,7 @@ database:
This command includes the ``interface`` parameter, which sets the shared
network-level interface name. Any remaining shared-network level parameters,
network-level interface name. Any remaining shared-network-level parameters,
which are not specified with the command, will be marked as
"unspecified" in the database. The DHCP server uses the global
values for unspecified parameters or, if the global values are not
@ -1300,7 +1300,7 @@ be deleted. If the option is not explicitly specified for this
shared network, no option is deleted. In particular, the given
option may be present for a subnet belonging to the shared network.
Such an option instance is not affected by this command as this
command merely deletes the shared-network level option. To
command merely deletes the shared-network-level option. To
delete a subnet-level option, the :isccmd:`remote-option4-subnet-del`,
:isccmd:`remote-option6-subnet-del` commands must be used instead.
@ -1393,7 +1393,7 @@ option is not explicitly specified for this pool, no option is deleted.
In particular, the given option may exist for a subnet containing
the specified pool. Such an option instance is not affected by this
command, as this command merely deletes a prefix delegation pool-level
option. To delete a subnet level option, the
option. To delete a subnet-level option, the
:isccmd:`remote-option6-subnet-del` command must be used instead.
.. code-block:: json
@ -1486,8 +1486,8 @@ is not explicitly specified for this pool, no option is deleted.
In particular, the given option may exist for a subnet containing
the specified pool. Such an option instance is not affected by this
command, as this command merely deletes a pool-level option. To
delete a subnet-level option, the :isccmd:`remote-option4-subnet-del`,
:isccmd:`remote-option6-subnet-del` commands must be used instead.
delete a subnet-level option, the :isccmd:`remote-option4-subnet-del`
or :isccmd:`remote-option6-subnet-del` command must be used instead.
The following command attempts to delete an option having the
option code 5 in the top-level option space from an IPv4 address
@ -1858,8 +1858,8 @@ looks similar to this:
The returned information about each subnet is limited to the subnet identifier,
prefix, and associated shared network name. To retrieve full
information about the selected subnet, use
the :isccmd:`remote-subnet4-get-by-id`, :isccmd:`remote-subnet6-get-by-id` commands
or the :isccmd:`remote-subnet4-get-by-prefix`, :isccmd:`remote-subnet6-get-by-prefix` commands.
the :isccmd:`remote-subnet4-get-by-id` / :isccmd:`remote-subnet6-get-by-id` command
or the :isccmd:`remote-subnet4-get-by-prefix` / :isccmd:`remote-subnet6-get-by-prefix` command.
The example response above contains two subnets. One of the subnets is
associated with both servers: "server1" and "server2". The second subnet is
@ -1907,7 +1907,7 @@ or disassociates the subnet with a shared network.
The structure of the subnet information is similar to the structure used
in the configuration file (see :ref:`dhcp4-configuration` and
:ref:`dhcp6-configuration`). The subnet information conveyed in the
:isccmd:`remote-subnet4-set`, :isccmd:`remote-subnet6-set` commands
:isccmd:`remote-subnet4-set` or :isccmd:`remote-subnet6-set` command
must include the additional parameter
``shared-network-name``, which denotes whether the subnet belongs to a
shared network.

9
doc/sphinx/arm/hooks-cb-mysql.rst
View File

@ -12,7 +12,8 @@ for more details.
.. note::
:ischooklib:`libdhcp_mysql_cb.so` is part of the open source code and is
available to every Kea user, but it requires :ischooklib:`libdhcp_cb_cmds.so`
which is available only to ISC customers with
a paid support contract. For more information on subscription options,
please complete the form at https://www.isc.org/contact.
available to every Kea user. However, this hook library only works
with :ischooklib:`libdhcp_cb_cmds.so`, which allows easy configuration
management with the use of API commands. :ischooklib:`libdhcp_cb_cmds.so`
is available only to ISC customers with a paid support contract; for more information
on subscription options, please complete the form at https://www.isc.org/contact.

9
doc/sphinx/arm/hooks-cb-pgsql.rst
View File

@ -12,7 +12,8 @@ for more details.
.. note::
:ischooklib:`libdhcp_pgsql_cb.so` is part of the open source code and is
available to every Kea user, but it requires :ischooklib:`libdhcp_cb_cmds.so`
which is available only to ISC customers with
a paid support contract. For more information on subscription options,
please complete the form at https://www.isc.org/contact.
available to every Kea user. However, this hook library only works
with :ischooklib:`libdhcp_cb_cmds.so`, which allows easy configuration
management with the use of API commands. :ischooklib:`libdhcp_cb_cmds.so`
is available only to ISC customers with a paid support contract; for more information
on subscription options, please complete the form at https://www.isc.org/contact.

8
doc/sphinx/arm/hooks-class-cmds.rst
View File

@ -114,12 +114,12 @@ be removed with the :isccmd:`class-del` command and then added again with a
different name using :isccmd:`class-add`. Note, however, that the class with
the new name will be added at the end of the list of configured classes.
As with other update commands, this command overwrites all the contents of the
As with other update commands, this command overwrites all the contents of an
entry. If the client class previously had a resource assigned to it, and the
:isccmd:`class-update` command is missing the resource, it is deleted from the server
configuration. If an incremental update of the class is desired, then this can
be achieved by doing a :isccmd:`class-get` to get the current state
of the client class, picking the client class out of the response, modifying it
configuration. If an incremental update of the class is desired, it can
be achieved by issuing a :isccmd:`class-get` to get the current state
of the client class, selecting the client class from the response, modifying it
to the required outcome, and then issuing the ``client-update`` command with the
resulting client class attached.

64
doc/sphinx/arm/hooks-flex-option.rst
View File

@ -39,7 +39,7 @@ numeric code or its name; either the code or the name must be
specified. The option space is DHCPv4 or DHCPv6, depending
on the server where the hook library is loaded.
Similar to other hook libraries, :ischooklib:`libdhcp_flex_option.so` can be loaded
:ischooklib:`libdhcp_flex_option.so` can be loaded
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
@ -71,9 +71,9 @@ If (and only if) the **query** includes a ``host-name`` option (code 12), a
followed by ``.boot`` for content.
A commonly discussed use case is modifying the DHCPv4 subnet mask option
(code 1). The following example demonstrates that capability. All ingress
(code 1). The following example demonstrates that capability, as all ingress
packets identified by the gateway address 192.168.0.1 are met with a /32 subnet
mask in the response.
mask in the response:
.. code-block:: json
@ -95,9 +95,9 @@ mask in the response.
}
}
The flexible option library supports both DHCPv4 and DHCPv6.
The Flexible Option library supports both DHCPv4 and DHCPv6.
Since Kea 1.9.0, the ``add`` and ``supersede`` actions take an optional
The ``add`` and ``supersede`` actions take an optional
```csv-format``` boolean parameter. If not specified or set to ``false``, the
option data is set using the raw value of the evaluated expression. When it is
configured to ``true``, this value is parsed using the option definition from
@ -105,36 +105,36 @@ the option data specified in the configuration file. This eases option setting
for options using complex record formats or fully qualified domain names.
For instance, if the expression evaluation returns "example.com" and
the option is defined with the ``fqdn`` type, the domain name will be
the option is defined with the ``fqdn`` type, the domain name is
encoded into DNS binary format.
Since Kea 2.1.4, the ``client-class`` parameter specifies a class guard.
It takes a client class name. If not empty, the client's packet needs to
belong to specified class for this entry to be used.
Since Kea 2.1.4, the ``client-class`` parameter specifies a class guard,
and takes a client-class name. If not empty, the client's packet needs to
belong to tne specified class for this entry to be used.
Since Kea 2.1.4, it is allowed to have multiple entries for the same option,
It is also possible to have multiple entries for the same option,
but each entry must have exactly one action. If the option is not defined
in the ``dhcp4`` for DHCPv4 or ``dhcp6`` for DHCPv6 you can specify the
space where to find the option definition using its name with the new
in ``dhcp4`` for DHCPv4 or ``dhcp6`` for DHCPv6, the location of
the option definition can be specified using its name, with the new
``space`` parameter.
Since Kea 2.1.4, sub-options are supported with a new entry ``sub-options``
Since Kea 2.1.4, sub-options are supported with a new entry, ``sub-options``,
which replaces the action in the configuration of the container option,
i.e. the option where sub-options are located.
The ``sub-options`` entry takes a list of sub-option configuration similar
to the option one with:
The ``sub-options`` parameter takes a list of sub-option entries, each
containing:
- ``code`` - specifies the sub-option code, either the ``code`` or ``name``
must be specified. When both are given they must match or the configuration
- ``code`` - specifies the sub-option code; either the ``code`` or ``name``
must be specified. If both are given, they must match or the configuration
is rejected at load time.
- ``name`` - specifies the sub-option name, either the ``code`` or ``name``
must be specified. When both are given they must match or the configuration
- ``name`` - specifies the sub-option name; either the ``code`` or ``name``
must be specified. If both are given, they must match or the configuration
is rejected at load time.
- ``space`` - specifies the space where the sub-option can be defined. This
parameter is optional because it can be found in the container option
parameter is optional, because it can be found in the container option
definition. The configuration is rejected if no valid space name is
available at load time. Note that vendor spaces are supported for the
DHCPv4 ``vivso-suboptions`` and for the DHCPv6 ``vendor-opts``, both
@ -149,26 +149,26 @@ to the option one with:
- ``remove`` - (action) removes a sub-option if it already exists and the
expression evaluates to true.
- ``container-add`` - boolean value which specifies if the container option
should be created if it does not exit in the ``add`` and ``supersede``
action. When not specified, it defaults to true.
- ``container-add`` - a boolean value that specifies whether the container option
should be created, if it does not exist in the ``add`` and ``supersede``
action. If not specified, it defaults to ``true``.
- ``container-remove`` - boolean value which specifies if the container option
should be deleted if it remains empty after the removal of a sub-option by
the ``remove`` action. When not specified, it defaults to true.
- ``container-remove`` - a boolean value that specifies whether the container option
should be deleted, if it remains empty after the removal of a sub-option by
the ``remove`` action. If not specified, it defaults to ``true``.
- ``csv-format`` - boolean value which specifies if the raw value of the
- ``csv-format`` - a boolean value that specifies whether the raw value of the
evaluated expression is used (false, default) or parsed using the sub-option
definition (true).
- ``client-class`` - specifies if the sub-option entry must be skipped when
the **query** does not belong to the specified client class. Note the similar
- ``client-class`` - specifies whether the sub-option entry must be skipped when
the **query** does not belong to the specified client class. Note that the similar
parameter in the container option entry applies to the whole ``sub-options``
list.
For instance this configuration adds a string sub-option in the DHCPv4
``vendor-encapsulated-options`` (code 43) option. Note this option
in last resort encapsulates the ``vendor-encapsulated-options`` space.
For instance, this configuration adds a string sub-option in the DHCPv4
``vendor-encapsulated-options`` (code 43) option. This option
encapsulates the ``vendor-encapsulated-options`` space.
.. code-block:: json

122
doc/sphinx/arm/hooks-ha.rst
View File

@ -1320,7 +1320,7 @@ Controlling Lease-Page Size Limit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An HA-enabled server initiates synchronization of the lease database after
downtime or upon receiving the :isccmd:`ha-sync` command. The server uses commands
downtime or upon receiving the :isccmd:`ha-sync` command. The server uses the commands
:isccmd:`lease4-get-page` and :isccmd:`lease6-get-page`
to fetch leases from its partner server (lease queries). The size of the results
page (the maximum number of leases to be returned in a single response to one of
@ -1615,23 +1615,15 @@ Since Kea 1.9.0, basic HTTP authentication is supported.
Multi-Threaded Configuration (HA+MT)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
: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
each of its peers.
In Kea 1.9.7 and newer, it is possible to configure HA to use direct
It is possible to configure HA to use direct
multi-threaded communication between peers. We refer to this mode as HA+MT.
With HA+MT enabled, each peer runs its own dedicated, internal HTTP listener
(i.e. server) which receives and responds to commands directly, thus eliminating
the need for an agent to carry out HA protocol between peers. In addition, both
the listener and client components use multi-threading to support multiple,
the need for an agent to carry out the HA protocol between peers. In addition, both
the listener and client components use multi-threading to support multiple
concurrent connections between peers. By eliminating the agent and executing
multiple command exchanges in parallel, HA throughput between peers should
improve considerably in most situations.
multiple command exchanges in parallel, HA throughput between peers
improves considerably over earlier versions of Kea in most situations.
The following parameters have been added to the HA configuration, to support
HA+MT operation:
@ -1748,11 +1740,11 @@ Parked-Packet Limit
Refer to :ref:`parked-packet-limit` for a basic introduction to packet parking.
The HA hook library makes use of this mechanism. When an HA server
The HA hook library uses this mechanism. When an HA server
needs to send a lease update to its peers to notify them of the change to the
lease, it will park the client response until the peers acknowledge the lease
update. At that point, the server will unpark the response and send it to the
client. This applies to client queries which cause lease changes, such as
lease, it parks the client response until the peers acknowledge the lease
update. At that point, the server unparks the response and sends it to the
client. This applies to client queries that cause lease changes, such as
DHCPREQUEST for DHCPv4 and Request, Renew, and Rebind for DHCPv6. It does not
apply to DHPCDISCOVERs (v4) or Solicits (v6).
@ -1780,8 +1772,8 @@ to instantly start serving all DHCP clients, and the other server to instantly
stop serving any DHCP clients, so it can be safely shut down.
The maintenance feature of the High Availability hook library addresses this
situation. The :isccmd:`ha-maintenance-start` command was introduced to allow the
administrator to put the pairs of the active servers in a state in which one of
situation. The :isccmd:`ha-maintenance-start` command allows the
administrator to put the pairs of the active servers into a state in which one of
them is responding to all DHCP queries and the other one is awaiting shutdown.
Suppose that the HA setup includes two active servers, ``server1`` and
@ -1826,10 +1818,10 @@ normal state negotiation process.
If the server has many relationships with different partners, the ``ha-maintenance-start``
command attempts to transition all of the relationships into the
``partner-in-maintenance`` state by sending the ``ha-mainteance-notify`` to all
partner servers. If this step fails for any server an error is returned.
In that case, send the ``ha-maintenance-cancel`` command to resume normal
operation and fix the issue.
``partner-in-maintenance`` state by sending ``ha-maintenance-notify`` to all
partner servers. If this step fails for any server, an error is returned.
If that happens, the ``ha-maintenance-cancel`` command can be used to resume normal
operations and fix the issue.
Upgrading From Older HA Versions
@ -1957,9 +1949,9 @@ and "HA_server2" scopes. To disable all scopes specify an empty list:
}
}
The optional ``server-name`` parameter specifies a name of one of the partners belonging
to the HA relationship this command pertains to. This parameter can be omitted if the
server receiving this command has only one HA relationship in the configuration.
The optional ``server-name`` parameter specifies the name of one of the partners in
the HA relationship that this command pertains to. This parameter can be omitted if the
server receiving this command has only one HA relationship in its configuration.
.. isccmd:: ha-continue
.. _command-ha-continue:
@ -1982,9 +1974,9 @@ command structure is simply:
}
}
The optional ``server-name`` parameter specifies a name of one of the partners belonging
to the HA relationship this command pertains to. This parameter can be omitted if the
server receiving this command has only one HA relationship in the configuration.
The optional ``server-name`` parameter specifies the name of one of the partners in
the HA relationship that this command pertains to. This parameter can be omitted if the
server receiving this command has only one HA relationship in its configuration.
.. isccmd:: ha-heartbeat
.. _command-ha-heartbeat:
@ -2011,9 +2003,9 @@ no arguments:
}
}
The optional ``server-name`` parameter specifies a name of one of the partners belonging
to the HA relationship this command pertains to. This parameter can be omitted if the
server receiving this command has only one HA relationship in the configuration.
The optional ``server-name`` parameter specifies the name of one of the partners in
the HA relationship that this command pertains to. This parameter can be omitted if the
server receiving this command has only one HA relationship in its configuration.
Upon successful communication with the server, a response similar to this should
be returned:
@ -2238,9 +2230,9 @@ status of the backup servers.
The ``ha-maintenance-start`` Command
------------------------------------
This command is used to initiate the transition of the server's partners into the
``in-maintenance`` state and the transition of the server receiving the command
into the ``partner-in-maintenance`` state in each HA relationship. See the
This command initiates the transition of the server's partners into the
``in-maintenance`` state, and the transition of the server receiving the command
into the ``partner-in-maintenance`` state, in each HA relationship. See the
:ref:`ha-maintenance` section for details.
::
@ -2257,8 +2249,8 @@ The ``ha-maintenance-cancel`` Command
-------------------------------------
This command is used to cancel the maintenance previously initiated using the
:isccmd:`ha-maintenance-start` command. The server receiving this command will first
send :isccmd:`ha-maintenance-notify`, with the ``cancel`` flag set to ``true``, to its
:isccmd:`ha-maintenance-start` command. The server receiving this command first
sends :isccmd:`ha-maintenance-notify`, with the ``cancel`` flag set to ``true``, to its
partners. Next, the server reverts from the ``partner-in-maintenance`` state to
its previous state. See the :ref:`ha-maintenance` section for details.
@ -2291,9 +2283,9 @@ previous state. See the :ref:`ha-maintenance` section for details.
}
}
The optional ``server-name`` parameter specifies a name of one of the partners belonging
to the HA relationship this command pertains to. This parameter can be omitted if the
server receiving this command has only one HA relationship in the configuration.
The optional ``server-name`` parameter specifies the name of one of the partners in
the HA relationship that this command pertains to. This parameter can be omitted if the
server receiving this command has only one HA relationship in its configuration.
.. warning::
@ -2330,9 +2322,9 @@ machine.
}
}
The optional ``server-name`` parameter specifies a name of one of the partners belonging
to the HA relationship this command pertains to. This parameter can be omitted if the
server receiving this command has only one HA relationship in the configuration.
The optional ``server-name`` parameter specifies the name of one of the partners in
the HA relationship that this command pertains to. This parameter can be omitted if the
server receiving this command has only one HA relationship in its configuration.
It elicits the response:
@ -2371,9 +2363,9 @@ responding to clients.
}
}
The optional ``server-name`` parameter specifies a name of one of the partners belonging
to the HA relationship this command pertains to. This parameter can be omitted if the
server receiving this command has only one HA relationship in the configuration.
The optional ``server-name`` parameter specifies the name of one of the partners in
the HA relationship that this command pertains to. This parameter can be omitted if the
server receiving this command has only one HA relationship in its configuration.
The ``origin-id`` parameter is used to select the HA service for which the receiving server should
enable the DHCP service when it receives this notification. This is the same origin the
@ -2403,19 +2395,19 @@ It elicits the response:
Hub and Spoke Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The hub-and-spoke is a common arrangement of the DHCP servers for resiliency. It contains
one central server and multiple branch servers. The branch servers are the primary servers
A hub-and-spoke arrangement, with one central server and multiple branch servers,
is a common way to ensure resiliency of the DHCP servers. The branch servers are the primary servers
in the ``hot-standby`` mode and respond to the local DHCP traffic in their respective
locations. The central server acts as a standby server for each branch server.
It maintains independent state machines with the branch servers, called relationships.
If one of the branch servers experiences a failure, the central server can take over its
DHCP traffic. In this case, we say that one of the central server's relationships is in
DHCP traffic. In this case, one of the central server's relationships is in
the ``partner-down`` state. The remaining relationships may still be in the ``hot-standby``
state and not actively respond to DHCP traffic. When the branch server becomes active again,
it synchronizes the lease database with the central server, and the central server becomes
fully passive again. In rare cases, when multiple branch servers stop, the central server
takes responsibility for all their traffic (possibly the entire DHCP traffic in the network
when all branch servers are down). A simple hub-and-spoke arrangement consisting of two
it synchronizes the lease database with the central server and the central server becomes
fully passive again. In rare cases, if multiple branch servers stop, the central server
takes responsibility for all their traffic, and potentially all DHCP traffic in the entire network
if every branch server is down. A simple hub-and-spoke arrangement consisting of two
branch servers and one central server is shown below.
::
@ -2430,10 +2422,10 @@ branch servers and one central server is shown below.
+---------------------------+
Each branch server's configuration comprises a set of subnets appropriate for the branch
server. Different branch servers serve different subnets. The central server's configuration
comprises all subnets of the branch servers so that it can respond to the DHCP traffic
directed to any of the failing branch servers. The subnets in the central server must be
grouped into relationships like in the snippet below:
server; different branch servers serve different subnets. The central server's configuration
includes all subnets of the branch servers, so that it can respond to DHCP traffic
directed to any branch servers that fail. The subnets in the central server must be
grouped into relationships as in the snippet below:
.. code-block:: json
@ -2530,9 +2522,9 @@ grouped into relationships like in the snippet below:
The peer names in the relationships must be unique. The user context for each subnet contains
the ``ha-server-name`` parameter associating a subnet with a relationship. The ``ha-server-name``
can be any of the peer names in the relationship. Suppose a relationship contains peer names
``server1`` and ``server2``. It doesn't matter whether the ``ha-server-name`` is ``server1`` or
the ``ha-server-name`` parameter, associating a subnet with a relationship. The ``ha-server-name``
can be any of the peer names in the relationship. For example, if a relationship contains peer names
``server1`` and ``server2``, it does not matter whether the ``ha-server-name`` is ``server1`` or
``server2``. In both cases, it associates a subnet with that relationship.
It is not required to specify the ``ha-server-name`` in the branch servers, assuming that the
@ -2603,15 +2595,15 @@ branch ``server3``:
.. note::
Even though it is not required to include the ``ha-server-name`` user context parameters in the
Even though it is possible to omit the ``ha-server-name`` user context parameters in the
branch servers, we recommend including them. The servers fetch all leases from the
partners during the database synchronization. If the subnets are not explicitly associated with
partners during the database synchronization; if the subnets are not explicitly associated with
the relationship, the branch server inserts all fetched leases from the central server (including
those from other relationships) into its database. Specifying ``ha-server-name`` parameter for
those from other relationships) into its database. Specifying the ``ha-server-name`` parameter for
each configured subnet in the branch server guarantees that only the leases belonging to its
relationship are inserted into the branch server's database.
.. note::
The peer names in the branch servers must match the peer names in the respective central
server's relationships because these names are used for signaling between the HA partners.
server's relationships, because these names are used for signaling between the HA partners.

80
doc/sphinx/arm/hooks-host-cmds.rst
View File

@ -94,12 +94,12 @@ The ``subnet-id`` Parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before examining the individual commands, it is worth discussing the
parameter ``subnet-id``. Currently this parameter is mandatory for all of the
parameter ``subnet-id``. Currently, this parameter is mandatory for all of the
commands supplied by this library, with the exception of
:isccmd:`reservation-get-by-hostname` and :isccmd:`reservation-get-by-address`,
where it is optional. Since Kea 1.9.0,
``subnet-id`` is also optional in :isccmd:`reservation-get-page`, and
it is forbidden in :isccmd:`reservation-get-by-id`.
where it is optional. ``subnet-id`` is also optional in
:isccmd:`reservation-get-page`, and it is forbidden
in :isccmd:`reservation-get-by-id`.
Reservations can be specified globally, and are not necessarily specific to any
subnet. When reservations are supplied via the configuration file, the
@ -113,27 +113,27 @@ scoped to a specific subnet, use that subnet's ID.
On the other hand, when the ``subnet-id`` is not specified in the command
parameters, it is added to each host in responses. If the ``subnet-id``
has the unused special value, this means the host entry belongs only
to the other IP version (i.e. IPv6 in DHCPv4 server or IPv4 in DHCPv6
to the other IP version (i.e. IPv6 in the DHCPv4 server or IPv4 in the DHCPv6
server) and this entry is ignored.
The ``operation-target`` Parameter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Most host commands accept the ``operation-target`` parameter that selects
Most host commands accept the ``operation-target`` parameter, which selects
the host data source. The commands may process data from the server
configuration (i.e., memory operation target), a database (database target),
or both of them (all sources). The operation target parameter is optional.
or both (all sources). The operation-target parameter is optional.
By default, the commands that only read the data use all data sources
(memory and database); the commands that modify the state (i.e., :isccmd:`reservation-add`,
(memory and database); the commands that modify the state (i.e. :isccmd:`reservation-add`,
:isccmd:`reservation-del`, and :isccmd:`reservation-update`) only use the
database target.
The ``operation-target`` parameter accepts the following values:
- ``memory`` - query or update the runtime server configuration.
- ``database`` - query or update host database(s).
- ``all`` - query or update both runtime configuration and host database(s).
- ``default`` - query or update a default host data source - it is command specific.
- ``memory`` - query or update the runtime server configuration
- ``database`` - query or update host database(s)
- ``all`` - query or update both runtime configuration and host database(s)
- ``default`` - query or update a default host data source - it is command-specific
.. isccmd:: reservation-add
.. _command-reservation-add:
@ -164,7 +164,7 @@ only the two mandatory entries:
}
In that case, however, it does not assign any resources to the host. An IPv4
address can be assigned like so:
address can be assigned as in this example:
.. code-block:: json
@ -179,7 +179,7 @@ address can be assigned like so:
}
}
It can also take many more parameters, for example:
It can also take many more parameters, such as:
.. code-block:: json
@ -319,7 +319,7 @@ follows:
}
The command accepts the ``operation-target`` argument. By default, it gets the
reservation from both JSON configuration and the hosts database.
reservation from both the JSON configuration and the hosts database.
.. code-block:: json
@ -437,7 +437,7 @@ may be disruptive; use with caution. For larger deployments, please
consider using :isccmd:`reservation-get-page` instead.
The command accepts the ``operation-target`` argument. By default, it gets the
reservation from both JSON configuration and the hosts database.
reservation from both the JSON configuration and the hosts database.
.. code-block:: json
@ -575,9 +575,9 @@ page is received. Its response will look like this:
"text": "0 IPv4 host(s) found."
}
The command doesn't accept the ``operation-target`` argument.
The command does not accept the ``operation-target`` argument.
This command is more complex than :isccmd:`reservation-get-all`, but lets
This command is more complex than :isccmd:`reservation-get-all`, but it lets
users retrieve larger host reservations lists in smaller chunks. For
small deployments with few reservations, it is easier to use
:isccmd:`reservation-get-all`.
@ -589,8 +589,8 @@ The ``reservation-get-by-address`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:isccmd:`reservation-get-by-address` can be used to query the host database and
retrieve all reservations for given IP address or a delegated prefix (without
a prefix length) in a specified subnet or in all subnets. This command uses
retrieve all reservations for a given IP address or a delegated prefix (without
a prefix length), in a specified subnet or in all subnets. This command uses
parameters providing the mandatory ``ip-address`` and the optional ``subnet-id``
and ``operation-target``.
@ -645,7 +645,7 @@ can return two IPv4 hosts:
"text": "2 IPv4 host(s) found."
}
To search for all reservations in all subnets simply skip the ``subnet-id`` parameter:
To search for all reservations in all subnets, simply skip the ``subnet-id`` parameter:
::
@ -659,7 +659,7 @@ To search for all reservations in all subnets simply skip the ``subnet-id`` para
]
}
An example response can be:
An example response could be:
::
@ -719,9 +719,9 @@ An example response can be:
When using the command for retrieving DHCP6 host reservations, one can provide
either an IPv6 address or a delegated prefix as the ``ip-address`` parameter.
Please notice that this command does not take prefix length as a parameter in the
current implementation. That's why searching by an IP address ``2001:db8:2:cafe::``
can return host reservations having delegated prefixes matching this search with
different lengths. For example: ``2001:db8:2:cafe::/63``, ``2001:db8:2:cafe::/64`` etc.
current implementation. Thus, searching by an IP address ``2001:db8:2:cafe::``
can return host reservations with delegated prefixes of different lengths matching
this search. For example: ``2001:db8:2:cafe::/63``, ``2001:db8:2:cafe::/64``, etc.
Please consider the example below:
::
@ -778,7 +778,7 @@ Response:
}
The command accepts the ``operation-target`` argument. By default, it gets the
reservation from both JSON configuration and the hosts database.
reservation from both the JSON configuration and the hosts database.
.. code-block:: json
@ -798,14 +798,14 @@ reservation from both JSON configuration and the hosts database.
This command is useful in specific cases. By default, having more than
one host reservation for the same IP address in a given subnet is not allowed,
as explained in the
as explained in
:ref:`Multiple Reservations for the Same IPv4 <multiple-reservations-same-ip4>`
or in the
or
:ref:`Multiple Reservations for the Same IPv6 <multiple-reservations-same-ip6>`.
That's why this command comes in handy
when the ``ip-reservations-unique`` boolean parameter is set to ``false``.
Other use case of this command is having overlapping subnets and having
the same IP address reservation (but with different identifier) in different
Another use case of this command is having overlapping subnets with
the same IP address reservations (but with different identifiers) in different
subnets.
.. isccmd:: reservation-get-by-hostname
@ -871,7 +871,7 @@ The response returned by :isccmd:`reservation-get-by-hostname` can be long,
particularly when responses are not limited to a subnet.
The command accepts the ``operation-target`` argument. By default, it gets the
reservation from both JSON configuration and the hosts database.
reservation from both the JSON configuration and the hosts database.
.. code-block:: json
@ -959,7 +959,7 @@ The response returned by :isccmd:`reservation-get-by-id` can be long,
particularly when responses are not limited to a subnet.
The command accepts the ``operation-target`` argument. By default, it gets the
reservation from both JSON configuration and the hosts database.
reservation from both the JSON configuration and the hosts database.
.. code-block:: json
@ -1072,7 +1072,7 @@ The ``reservation-update`` Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:isccmd:`reservation-update` allows for the update of an existing host. It takes the
same set of arguments as :isccmd:`reservation-add`, and just as well,
same set of arguments as :isccmd:`reservation-add`, and also
requires a host identifier and a subnet ID to identify the host that is being
updated. The command can be as simple as having only the two mandatory entries:
@ -1089,7 +1089,7 @@ updated. The command can be as simple as having only the two mandatory entries:
}
In that case, however, it does not assign any resources to the host. An IPv4
address can be assigned like so:
address can be assigned as in this example:
.. code-block:: json
@ -1104,7 +1104,7 @@ address can be assigned like so:
}
}
It can also take many more parameters, for example:
It can also take many more parameters, such as:
.. code-block:: json
@ -1165,7 +1165,7 @@ Here is an example of a complex IPv6 reservation update:
}
The command returns a status that indicates either success (result ``0``) or
failure (result ``1``) and a text parameter that confirms success or explains
failure (result ``1``), and a text parameter that confirms success or explains
the cause of the failure. Here's an example of a successful update:
.. code-block:: json
@ -1193,9 +1193,9 @@ target is not the JSON configuration.
As with other update and set commands, this command overwrites all the contents
of the entry. If the host previously had a resource assigned to it, and the
:isccmd:`reservation-update` command is missing the resource, it is deleted from the
database. If an incremental update of the host is desired, then this can be
achieved by doing a :isccmd:`reservation-get-by-id` to get the current state of the
host, picking the host out of the response, modifying it to the required
database. If an incremental update of the host is desired, this can be
achieved by issuing a :isccmd:`reservation-get-by-id` to get the current state of the
host, selecting the host from the response, modifying it to the required
outcome, and then issuing the :isccmd:`reservation-update` command with the resulting
host attached.
@ -1206,7 +1206,7 @@ General Mentions
.. note::
The host cache and RADIUS hook libraries are two host backends that do not
The host backends for the host cache and RADIUS hook libraries do not
respond to commands that return a collection of host reservations, such as
:isccmd:`reservation-get-all`. Commands returning one host entry or dedicated host
cache commands should be used instead.

8
doc/sphinx/arm/hooks-lease-cmds.rst
View File

@ -931,8 +931,8 @@ As with other update commands, this command overwrites all the contents of the
entry. If the lease previously had a resource assigned to it, and the
:isccmd:`lease4-update` / :isccmd:`lease6-update` command is missing the resource, it is
deleted from the lease database. If an incremental update of the lease is
desired, then this can be achieved by doing a :isccmd:`lease4-get` / :isccmd:`lease6-get`
command to get the current state of the lease, picking the lease out of the
desired, then this can be achieved by issuing a :isccmd:`lease4-get` / :isccmd:`lease6-get`
command to get the current state of the lease, selecting the lease from the
response, modifying it to the required outcome, and then issuing the
:isccmd:`lease4-update` / :isccmd:`lease6-update` command with the resulting lease attached.
@ -1063,8 +1063,8 @@ backend and write the lease database into a CSV file. They take the path
of the file as the ``filename`` argument. If the specified output file
is the same as the configured memfile one, the backend closes and reopens
the file in an attempt to synchronize both the files and the in-memory images
of the lease database. The extension ``.bak`` with server PID number is added
to the previous filename. For example ``.bak14326``.
of the lease database. The extension ``.bak`` and the server PID number are added
to the previous filename: for example, ``.bak14326``.
.. note::

69
doc/sphinx/arm/hooks-lease-query.rst
View File

@ -192,8 +192,7 @@ attached to a ``DHCPV6_LEASEQUERY`` message:
`RFC 5007, Section 3.3 <https://tools.ietf.org/html/rfc5007#section-3.3>`__
states that querying by IP address should return either a lease (e.g.
binding) for the address itself or a lease for a delegated prefix that
contains the address. The latter case is not supported by releases
prior to Kea 2.3.7.
contains the address.
``DHCPV6_LEASEQUERY`` queries are only honored if the source address of
the query matches an entry in a list of known IP addresses which are
@ -299,7 +298,7 @@ The client-data option encapsulates the following options:
+------------------------------+-------+-----------------------------------------------+
If the lease with the most recent client-last-transaction-time (CLTT)
value has relay information in its user-context (see
value has relay information in its user context (see
:ref:`store-extended-info-v6`), then an ``OPTION_LQ_RELAY_DATA`` option is
added to the reply (see
`RFC 5007, Section 4.1.2.4 <https://tools.ietf.org/html/rfc5007#section-4.1.2.4>`__).
@ -345,22 +344,22 @@ addresses:
When a query by IP address does not match an existing address lease,
a search for a matching delegated prefix is conducted. This is carried
out by iterating over a list of prefix lengths, in descending order,
extracting a prefix of that length from the query address and searching
out by iterating over a list of prefix lengths in descending order,
extracting a prefix of that length from the query address, and searching
for a delegation matching the resulting prefix. This continues for each
length in the list until a match is found or the list is exhausted.
By default, the list of prefix lengths to use in the search is determined
dynamically after (re)configuration events. This resulting list will
contain unique values of ``delegated-len`` gleaned from the currently
dynamically after (re)configuration events. The resulting list
contains unique values of ``delegated-len``, gleaned from the currently
configured set of PD pools.
There is an optional parameter, ``prefix-lengths``, shown above which
There is an optional parameter, ``prefix-lengths``, which
provides the ability to explicitly configure the list rather than having
it be determined dynamically. This provides tighter control over which
prefix lengths are searched. In the above example, the prefix length
search will be restricted to single pass, using a length of 72, regardless
of whether or not there are pools using other values for ``delegated-len``.
prefix lengths are searched. In the above example, the prefix-length
search is restricted to a single pass, using a length of 72, regardless
of whether there are pools using other values for ``delegated-len``.
Specifying an empty list, as shown below:
::
@ -418,12 +417,12 @@ RFC 6926 also defines new options for Bulk Leasequery:
- query-start-time (154)
This query option specifies a start query time; replies will only
This query option specifies a start-query time; replies will only
contain leases that are older than this value.
- query-end-time (155)
This query option specifies an end query time; replies will only
This query option specifies an end-query time; replies will only
contain leases that are newer than this value.
- dhcp-state (156)
@ -486,13 +485,13 @@ not yet used by the hook library.
Bulk Leasequery Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Bulk Leasequery configuration is done via a new map parameter, ``advanced``,
Bulk Leasequery configuration is specified via a new map parameter, ``advanced``,
with these possible entries:
- ``bulk-query-enabled``
When ``true``, Kea accepts connections from IP addresses in the requesters
list and processes received Bulk Leasequeries. The default is ``false``.
list and processes received bulk leasequeries. The default is ``false``.
- ``active-query-enabled``
@ -508,16 +507,16 @@ with these possible entries:
- ``lease-query-ip``
This is the IP address upon which to listen for connections. The address must be
of the same family as the server, e.g. IPv6 for DHCPv6 server.
of the same family as the server, e.g. IPv6 for the DHCPv6 server.
- ``lease-query-port``
This is the port upon which to listen. The default is 67 for IPv4 and 547 for IPv6,
i.e. the same value as for the UDP DHCP service but for TCP.
i.e. the same value as for the UDP DHCP service, but for TCP.
- ``max-bulk-query-threads``
This indicates the maximum number of threads that Bulk Leasequery processing
This indicates the maximum number of threads that bulk leasequery processing
should use. A value of 0 instructs the server to use the same number of
threads that the Kea core is using for DHCP multi-threading.
The default is 0.
@ -609,10 +608,10 @@ or for DHCPv6:
Updating Existing Leases in SQL Lease Backends
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Bulk Lease Query required additions to the lease data stored. With SQL lease
backends, leases created prior to the server being configured for Bulk Lease
Query will not contain the new data required. In order to populate this data
it is necessary to run API commands:
Bulk Leasequery requires additions to the lease data that is stored. With SQL lease
backends, leases created prior to the server being configured for bulk lease
query do not contain the new data required. In order to populate this data,
it is necessary to run these API commands:
.. isccmd:: extended-info4-upgrade
.. _command-extended-info4-upgrade:
@ -630,7 +629,7 @@ For DHCPv6 lease data, the command is:
.. isccmd:: extended-info6-upgrade
.. _command-extended-info6-upgrade:
for extended info used for by relay id and by remote id the command is:
For extended info used by relay ID and by remote ID, the command is:
::
@ -639,8 +638,8 @@ for extended info used for by relay id and by remote id the command is:
}
In all cases the response will indicate whether it succeeded or failed
and include either the count of leases updated or the nature of the failure:
In all cases, the response indicates whether it succeeded or failed
and includes either the count of leases updated or the nature of the failure:
::
@ -652,24 +651,24 @@ and include either the count of leases updated or the nature of the failure:
This ``extended-info6-upgrade`` command must be called when:
- the database schema was upgraded from a previous version
- the database schema was upgraded from a previous version.
- Bulk Lease Query was not enabled (tables are maintained only when v6 BLQ is
enabled)
- Bulk Leasequery was not enabled; tables are maintained only when v6 BLQ is
enabled.
- data in tables do not seem to be consistent (tables are not maintained in
an atomic way so consistency is not guaranteed. For instance when a database
is shared between several servers races can happen between updates)
- data in tables does not seem to be consistent; tables are not maintained in
an atomic way, so consistency is not guaranteed. For instance, when a database
is shared between several servers, races can happen between updates.
The operation of extended info command is governed by ``extended-info-checks``
parameter under the sanity-checks element. Please see :ref:`sanity-checks4`
The operation of the extended info command is governed by the ``extended-info-checks``
parameter, under the ``sanity-checks`` element. Please see :ref:`sanity-checks4`
or :ref:`sanity-checks6`.
For large numbers of leases this command may take some time to complete.
For large numbers of leases, this command may take some time to complete.
.. note::
Existing leases must have been created by Kea with ``store-extended-info``
enabled in order for the new data from extended info to be extracted
enabled, in order for the new data from extended info to be extracted
and stored.

16
doc/sphinx/arm/hooks-legal-log.rst
View File

@ -432,9 +432,9 @@ Examples:
2018-01-06 01:02:12 CET Administrator deleted a lease for a device identified by: hw-address of 1a:1b:1c:1d:1e:1f
If High availability module is enabled, the partner will periodically send lease
commands which have a similar format, the only difference is that the issuer of
the command is 'HA partner' instead of 'Administrator'.
If the High Availability hook library is enabled, the partner periodically sends lease
commands in a similar format; the only difference is that the issuer of
the command is "HA partner" instead of "Administrator."
::
@ -757,9 +757,9 @@ Examples:
2018-01-06 01:02:11 PST Administrator deleted a lease for a device identified by: duid of 1a:1b:1c:1d:1e:1f:20:21:22:23:24
If High availability module is enabled, the partner will periodically send lease
commands which have a similar format, the only difference is that the issuer of
the command is 'HA partner' instead of 'Administrator'.
If the High Availability hook library is enabled, the partner periodically sends lease
commands in a similar format; the only difference is that the issuer of
the command is "HA partner" instead of "Administrator."
::
@ -1089,6 +1089,6 @@ backends is considered fatal only if ``retry-on-startup`` is set to ``false``
(the default). A fatal error is logged and the server exits, based on the idea
that the configuration should be valid at startup. Exiting to the operating
system allows nanny scripts to detect the problem.
If ``retry-on-startup`` is set to ``true``, the server will start reconnection
attempts even at server startup or on reconfigure events, and will honor the
If ``retry-on-startup`` is set to ``true``, the server starts reconnection
attempts even at server startup or on reconfigure events, and honors the
action specified in the ``on-fail`` parameter.

6
doc/sphinx/arm/hooks-limits.rst
View File

@ -119,9 +119,9 @@ This is how a lease limit is defined for a subnet inside a shared network:
.. note::
Database connection retries are not attempted on startup if the
:ischooklib:`libdhcp_limits.so` is loaded because the hook library requires a
valid connection to the database to check if JSON format is supported and to
If :ischooklib:`libdhcp_limits.so` is loaded, database connection retries are not attempted
on startup. The hook library requires a
valid connection to the database to check whether JSON format is supported and to
recount class limits.
.. _hooks-limits-lease-limiting:

193
doc/sphinx/arm/hooks-perfmon.rst
View File

@ -1,21 +1,26 @@
.. ischooklib:: libdhcp_perfmon.so
.. _hooks-perfmon:
``libdhcp_perfmon.so``: PerfMon
===============================
``libdhcp_perfmon.so``: Performance Monitoring
==============================================
This hook library can be loaded by either kea-dhcp4 or kea-dhcp6 servers
to extend them with the ability to track and report performance related data.
The Performance Monitoring (perfmon) hook library gives the Kea DHCPv4 and DHCPv6 server
the ability to track and report performance-related data.
.. note::
This library is experimental and not recommended for use in production
environments.
.. note::
:ischooklib:`libdhcp_perfmon.so` is part of the open source code and is
available to every Kea user.
Overview
~~~~~~~~
The library, added in Kea 2.5.6, can be loaded by the :iscman:`kea-dhcp4` or
The perfmon library, added in Kea 2.5.6, can be loaded by the :iscman:`kea-dhcp4` or
:iscman:`kea-dhcp6` daemon by adding it to the ``hooks-libraries`` element of
the server's configuration:
@ -34,33 +39,33 @@ the server's configuration:
...
}
It tracks the life cycle of client query packets as they are processed by Kea,
beginning with when the query was received by the kernel to when the response
is ready to be sent. This tracking is driven by a packet event stack which
The library tracks the lifecycle of client query packets as they are processed by Kea,
from when the query was received by the kernel to when the response
is ready to be sent. This tracking is driven by a packet event stack, which
contains a list of event/timestamp pairs for significant milestones that
occur during the processing of a client query. The list of possible events is
shown below:
#. socket_received - Kernel placed the client query into the socket buffer
#. buffer_read - Server read the client query from the socket buffer
#. mt_queued - Server placed the client query into its thread-pool work queue (MT mode only)
#. process_started - Server has begun processing the query
#. process_completed - Server has constructed the response and is ready to send it
#. socket_received - kernel placed the client query into the socket buffer
#. buffer_read - server read the client query from the socket buffer
#. mt_queued - server placed the client query into its thread-pool work queue (multi-threaded mode only)
#. process_started - server has begun processing the query
#. process_completed - server has constructed the response and is ready to send it
This list is likely to expand over time. It will also be possible for hook developers
to add their own events. This will be detailed in a future release.
This list is likely to expand over time; it will also be possible for hook developers
to add their own events. This will be detailed in future releases.
Passive Event Logging
~~~~~~~~~~~~~~~~~~~~~
As long as the PerfMon hook library is loaded it will log the packet event stack
contents for each client query which generates a response packet. The log entry
will contain client query identifiers followed the list of event/timestamp pairs
as they occurred in the order they occurred.
When the perfmon hook library is loaded, it logs the packet event stack
contents for each client query that generates a response packet. The log entry
contains client query identifiers, followed by the list of event/timestamp pairs
in the order that they occurred.
For :iscman:`kea-dhcp4` the log is identified by the label, ``PERFMON_DHCP4_PKT_EVENTS``,
For :iscman:`kea-dhcp4`, the log is identified by the label ``PERFMON_DHCP4_PKT_EVENTS``,
and emitted at logger debug level 50 or higher. For a DHCPDISCOVER it is emitted
once the DHCPOFFER is ready to send and will look similar to the following (see
once the DHCPOFFER is ready to send, and looks similar to the following (see
the second entry)::
2024-03-20 10:52:20.069 INFO [kea-dhcp4.leases/50033.140261252249344] DHCP4_LEASE_OFFER [hwtype=1 08:00:27:25:d3:f4], cid=[no info], tid=0xc288f9: lease 178.16.2.0 will be offered
@ -68,9 +73,9 @@ the second entry)::
..
For :iscman:`kea-dhcp6` the log is identified by the label, ``PERFMON_DHCP6_PKT_EVENTS``,
and emitted only at logger debug level 50 or higher. For a DHCPV6_SOLICIT it is emitted
once the DHCPV6_ADVERTISE is ready to send and will look similar to the following (see
For :iscman:`kea-dhcp6`, the log is identified by the label ``PERFMON_DHCP6_PKT_EVENTS``,
and emitted at logger debug level 50 or higher. For a DHCPV6_SOLICIT it is emitted
once the DHCPV6_ADVERTISE is ready to send, and looks similar to the following (see
the second entry)::
2024-03-20 10:22:14.030 INFO [kea-dhcp6.leases/47195.139913679886272] DHCP6_LEASE_ADVERT duid=[00:03:00:01:08:00:27:25:d3:f4], [no hwaddr info], tid=0xb54806: lease for address 3002:: and iaid=11189196 will be advertised
@ -81,20 +86,20 @@ the second entry)::
Duration Monitoring
~~~~~~~~~~~~~~~~~~~
When monitoring is enabled, stack event data will be aggregated over a specified interval. These
aggregates are referred to as monitored durations or simply durations for ease. Durations are
When monitoring is enabled, stack event data is aggregated over a specified interval. These
aggregates are referred to as "monitored durations" or simply "durations" for ease. Durations are
uniquely identified by a "duration key" which consists of the following values:
* query message type - Message type of the client query (e.g.DHCPDISCOVER, DHCPV6_REQUEST)
* response message type - Message type of the server response (e.g. DHCPOFFER, DHCPV6_REPLY)
* start event label - Event that defines the beginning of the task (e.g. socket_received, process_started)
* stop event label - Event that defines the end of the task (e.g. buffer_read, process_completed)
* query message type - message type of the client query (e.g.DHCPDISCOVER, DHCPV6_REQUEST)
* response message type - message type of the server response (e.g. DHCPOFFER, DHCPV6_REPLY)
* start event label - event that defines the beginning of the task (e.g. socket_received, process_started)
* stop event label - event that defines the end of the task (e.g. buffer_read, process_completed)
* subnet id - subnet selected during message processing (or 0 for global durations)
Once the server has finished constructing a response to a query, the query's event stack
is processed into a series of updates to monitored durations. If upon updating, a
is processed into a series of updates to monitored durations. If, upon updating, a
duration's sample interval is found to have been completed, it is sent to reporting
and a new sample interval is begun. The interval width is dictacted by configuration
and a new sample interval is begun. The interval width is dictated by configuration
parameter ``interval-width-secs``.
The event stack for the multi-threaded mode DHCPDISCOVER/DHCPOFFER cycle shown above
@ -114,7 +119,7 @@ contains the following events:
| 2024-Mar-20 14:52:20.069614 | process_completed |
+-----------------------------+--------------------+
Assuming the selected subnet's ID was 100, the duration updates formed by PerfMon
Assuming the selected subnet's ID was 100, the duration updates created by perfmon
from these events are shown below:
+--------------------------------------------------------------+--------------+
@ -134,8 +139,8 @@ from these events are shown below:
Notice that in addition to the adjacent event updates, there is an additional duration
update for the total duration of the entire stack whose key contains the event-pair
``composite-total_response``. This tracks the total time to responds from query
received until the response is ready to send. Finally, there would also be global
``composite-total_response``. This tracks the total time to respond from when the query
is received until the response is ready to send. Finally, there are also global
duration updates for each of the above:
+--------------------------------------------------------------+--------------+
@ -156,20 +161,20 @@ duration updates for each of the above:
Statistics Reporting
~~~~~~~~~~~~~~~~~~~~
When enabled (see ``stats-mgr-reporting``), PerfMon will report a duration's data
each time the duration completes a sampling interval. Each statistic employs the
following naming convention:
When enabled, perfmon reports a duration's data each time the duration completes a
sampling interval (see ``stats-mgr-reporting`` under :ref:`perfmon-configuration`). Each
statistic employs the following naming convention:
::
{subnet-id[x]}.perfmon.<query type>-<response type>.<start event>-<end event>.<value-name>
And there will be both a global and a subnet-specific value for each. Currently the only
value reported for a given duration key is "average-ms". This statistic is the average time
There is both a global and a subnet-specific value for each. Currently, the only
value reported for a given duration key is ``average-ms``; this statistic is the average time
between the duration's event pair over the most recently completed interval. In other
words if during a given interval there were 7 occurrences (i.e. updates) totaling
350ms, the the average-ms reported would be 50ms. Continuing with example above, the
statistics reported would be named as follows for subnet level values:
words, if during a given interval there were seven occurrences (i.e. updates) totaling
350ms, the ``average-ms`` reported would be 50ms. Continuing with the example above, the
statistics reported are named as follows for the subnet-level values:
::
@ -189,28 +194,29 @@ and as shown for global values:
perfmon.DHCPDISCOVER.DHCPOFFER.process_started-process_completed.average-ms
perfmon.DHCPDISCOVER.DHCPOFFER.composite-total_response.average-ms
Since they are reported to StatsMgr they may be fetched using the commands :isccmd:`statistic-get-all`
or :isccmd:`statistic-get`.
The results are reported to StatsMgr, an internal Kea component that reports data as statistics
that can be retrieved using statistics commands. They can be fetched using the commands
:isccmd:`statistic-get-all` or :isccmd:`statistic-get`.
Alarms
~~~~~~
Alarms may be defined to watch specific durations. Each alarm defines a high-water mark,
``high-water-ms`` and a low-water mark, ``low-water-ms``. When the reported average value
for duration exceeds the high-water mark, a WARN level alarm log will be emitted at which
point the alarm is considered "triggered". Once triggered the WARN level log will be
repeated at a specified alarm report interval, ``alarm-report-secs`` as long the reported
``high-water-ms``, and a low-water mark, ``low-water-ms``. If the reported average value
for the duration exceeds the high-water mark a WARN level alarm log is emitted, at which
point the alarm is considered "triggered." Once triggered, the WARN level log is
repeated at the alarm report interval specified by ``alarm-report-secs``, as long as the reported
average for the duration remains above the low-water mark. Once the average falls below the
low-water mark the alarm is "cleared" and an INFO level log will be emitted.
low-water mark the alarm is cleared and an INFO level log is emitted.
The alarm triggered WARN log will look similar to the following:
The alarm-triggered WARN log looks similar to the following:
::
2024-03-20 10:22:14.030 WARN [kea-dhcp6.leases/47195.139913679886272] PERFMON_ALARM_TRIGGERED Alarm for DHCPDISCOVER.DHCPOFFER.composite-total_response.0 has been triggered since 2024-03-20 10:18:20.070000, reported average duration 00:00:00.700000 exceeds high-water-ms: 500
and the alarm cleared INFO log will look similar to the following:
The alarm-cleared INFO log looks like this:
::
@ -222,10 +228,51 @@ API Commands
Commands to enable or disable monitoring, clear or alter alarms, and fetch duration data
are anticipated but not yet supported.
.. _perfmon-configuration:
Configuration
~~~~~~~~~~~~~
An example of the anticipated configuration is shown below:
Use of the performance monitoring hook library is configured via several parameters:
* enable-monitoring
This parameter enables event data aggregation for reporting, statistics, and alarms. It defaults to ``false``.
* interval-width-secs
This specifies the amount of time, in seconds, that individual task durations are accumulated into an
aggregate before they are reported. The default is 60 seconds.
* stats-mgr-reporting
This enables the reporting of aggregates to StatsMgr. It defaults to ``true``.
* alarm-report-secs
This specifies the amount of time, in seconds, between logging instances for an alarm once it has been triggered.
It defaults to 300 seconds.
* alarms
This is an optional list of alarms that monitor specific duration aggregates. Each alarm is
defined by these four parameters:
* duration-key
Identifies the monitored duration for the following:
* query-type - message type of the client query (e.g.DHCPDISCOVER, DHCPV6_REQUEST)
* response-type - message type of the server response (e.g. DHCPOFFER, DHCPV6_REPLY)
* start-event - event that defines the beginning of the task (e.g. socket_received, process_started)
* stop-event - event that defines the end of the task
* subnet-id - subnet selected during message processing (or 0 for global durations)
* enable-alarm
Enables or disables this alarm; defaults to ``true``.
* high-water-ms
Specifies the value, in milliseconds, over which the duration must occur to trigger this alarm;
must be greater than zero.
* low-water-ms
Specifies the value, in milliseconds, under which the duration must fall to clear this alarm;
must be greater than zero but less than ``high-water-ms``.
.. note::
Passive event logging is always enabled, even without specifying the "parameters" section.
A sample configuration is shown below:
.. code-block:: javascript
@ -254,43 +301,3 @@ An example of the anticipated configuration is shown below:
}
}]
}
Where:
* enable-monitoring
Enables event data aggregation for reporting, statistics, and alarms. Defaults to false.
* interval-width-secs
The amount of time, in seconds, that individual task durations are accumulated into an
aggregate before it is reported. Default is 60 seconds.
* stats-mgr-reporting
Enables reporting aggregates to StatsMgr. Defaults to true.
* alarm-report-secs
The amount of time, in seconds, between logging for an alarm once it has been triggered.
Defaults to 300 seconds.
* alarms
A optional list of alarms that monitor specific duration aggregates. Each alarm is
defined by the following:
* duration-key
Identifies the monitored duration to watch
* query-type - Message type of the client query (e.g.DHCPDISCOVER, DHCPV6_REQUEST)
* response-type - Message type of the server response (e.g. DHCPOFFER, DHCPV6_REPLY)
* start-event - Event that defines the beginning of the task (e.g. socket_received, process_started)
* stop-event - Event that defines the end of the task
* subnet-id - subnet selected during message processing (or 0 for global durations)
* enable-alarm
Enables or disables this alarm. Defaults to true.
* high-water-ms
The value, in milliseconds, that must be exceeded to trigger this alarm.
Must be greater than zero.
* low-water-ms
The value, in milliseconds, that must be subceeded to clear this alarm
Must be greater than zero but less than high-water-ms.
.. note::
Passive event logging is always enabled, even without specifying the 'parameters' section.

91
doc/sphinx/arm/hooks-ping-check.rst
View File

@ -7,7 +7,12 @@
This hook library adds the ability to perform a "ping check" of a candidate
IPv4 address prior to offering it to a DHCP client. This feature is similar
to a behavior available in ISC DHCP and one suggested in `RFC
2131 <https://tools.ietf.org/html/rfc2131>`__ , see section 3.1, item 2.
2131 <https://tools.ietf.org/html/rfc2131>`__, section 3.1, item 2.
.. note::
This library is experimental and not recommended for use in production
environments.
.. note::
@ -18,7 +23,7 @@ to a behavior available in ISC DHCP and one suggested in `RFC
Overview
~~~~~~~~
The library, added in Kea 2.5.4, can be loaded by the :iscman:`kea-dhcp4` daemon
The Ping Check library, added in Kea 2.5.4, can be loaded by the :iscman:`kea-dhcp4` daemon
by adding it to the ``hooks-libraries`` element of the server's configuration:
.. code-block:: javascript
@ -36,10 +41,10 @@ by adding it to the ``hooks-libraries`` element of the server's configuration:
...
}
When the library is loaded :iscman:`kea-dhcp4` will conduct a ping-check prior to
offering a lease to client if all of the following conditions are true:
When the library is loaded, :iscman:`kea-dhcp4` conducts a ping check prior to
offering a lease to a client if all of the following conditions are true:
1. Ping check hook library is loaded.
1. The ping check hook library is loaded.
2. Ping checking is enabled.
@ -52,82 +57,81 @@ offering a lease to client if all of the following conditions are true:
a. This is the first offer of this lease to this client. This check
can only be done if ``offer-lifetime`` is greater than zero (i.e. temporary
allocation on DHCPDISCOVER is enabled). If ``offer-lifetime`` is zero
ping checks are done for every DHCPOFFER as the server has no way to
know it has made prior offers.
ping checks are done for every DHCPOFFER, as the server has no way to
know whether prior offers were made.
b. The lease is being offered to a client other than its previous owner.
c. The lease is being offered to its previous owner and more than a
configurable number of seconds, ``ping-cltt-secs``, have elapsed since
c. The lease is being offered to its previous owner and more than the
number of seconds specified by ``ping-cltt-secs`` have elapsed since the
CLTT of the original lease.
When the ping check library is loaded, in response to a DHCPDISCOVER the
:iscman:`kea-dhcp4` will:
When the ping check library is loaded, the :iscman:`kea-dhcp4` server
responds to a DHCPDISCOVER by:
1. Select a candidate IPv4 address through normal processes and use it to
1. Selecting a candidate IPv4 address through normal processes and using it to
construct a DHCPOFFER.
2. Park the DHCPOFFER and request a ping-check from the ping-check hook
library via its ``lease4_offer`` callout. Refer to :ref:`parked-packet-limit` for
2. Parking the DHCPOFFER and requesting a ping check from the ping check hook
library, via its ``lease4_offer`` callout. Refer to :ref:`parked-packet-limit` for
a basic introduction to packet parking.
3. The callout will test conditions described above. If they are not
satisfied it will return without conducting a check, and the server
will send the DHCPOFFER to the client. Otherwise the callout will
initiate a ping-check for the lease address.
3. Testing the callout conditions described above: if they are not
satisfied, it returns without conducting a check, and the server
sends the DHCPOFFER to the client. Otherwise, the callout
initiates a ping check for the lease address.
4. Upon conclusion of the ping-check, the server will either send the DHCPOFFER
to the client if the check concluded that the address is available, or discard
the DHCPFOFFER and create a DECLINED lease for the address.
4. Upon conclusion of the ping check, the server either sends the DHCPOFFER
to the client, if the check concluded that the address is available, or discards
the DHCPFOFFER and creates a DECLINED lease for the address.
Each ping-check consists of the following steps:
Each ping check consists of the following steps:
1. If the number of ECHO REPLYs sent is less than the configured
minimum number to send, send an ICMP ECHO REQUEST to the lease address.
Otherwise, conclude that the address is available.
2. If no ECHO REPLY is received within a configurable amount of time
2. If no ECHO REPLY is received within a configurable amount of time,
return to step 1.
3. Upon receipt of an ICMP ECHO REPLY, conclude that the lease is NOT available.
4. Any of the following occur:
4. If any of the following occur:
a. Receipt of an ICMP DESTINATION UNREACHABLE message
b. Send fail of an ICMP ECHO REQUEST due to a network error (e.g. network is unreachable)
c. Send fail of an ICMP ECHO REQUEST due to a permissions error (e.g. lease address is a broadcast address)
d. Send fail of an ICMP ECHO REQUEST with socket buffer full error
b. Send failure of an ICMP ECHO REQUEST due to a network error (e.g. network is unreachable)
c. Send failure of an ICMP ECHO REQUEST due to a permissions error (e.g. lease address is a broadcast address)
d. Send failure of an ICMP ECHO REQUEST with socket buffer full error
In each of these instances the address could not be checked and is treated as
available.
skip the address check and treat it as available.
.. note::
Socket buffer full of errors indicates that the OS rate limits on ICMP are
being exceeded. The server will not retry them as this would likely only
exacerbate the situation. If this occurs continuously then the client load
"Socket buffer full" errors indicate that the OS rate limits on ICMP are
being exceeded. The server does not retry them, as this would likely only
exacerbate the situation. If this occurs continuously, then the client load
on the server may be too high to accommodate ping checking. Ping checking is
not recommended for systems with high throughput demands.
Configuration
~~~~~~~~~~~~~
The ping-check hook library currently supports the following configuration parameters
that may be set at the global and subnet levels. Subnet values override global values.
The ping check hook library currently supports the following configuration parameters
that may be set at the global and subnet levels; subnet values override global values:
- ``enable-ping-check`` - Enables or disables ping checking at a given scope.
- ``enable-ping-check`` - This parameter enables or disables ping checking at a given scope.
- ``min-ping-requests`` - The minimum number of ECHO REQUESTs sent without receiving a reply needed to declare an address available. The default is 1, it must be greater than zero.
- ``min-ping-requests`` - This is the minimum number of ECHO REQUESTs sent without receiving a reply, before an address is declared available. The default is 1; it must be greater than zero.
- ``reply-timeout`` - The maximum amount of time to wait for a reply to a single ECHO REQUEST. Specified in milliseconds, it must be greater than zero, it defaults to 100.
- ``reply-timeout`` - This is the maximum amount of time to wait for a reply to a single ECHO REQUEST. Specified in milliseconds, it must be greater than zero; the default is 100.
- ``ping-cltt-secs`` - The number of seconds that must elapse after the lease's CLTT before a ping check will be conducted when the client is the lease's previous owner. The default value is sixty seconds.
- ``ping-cltt-secs`` - This specifies the number of seconds that must elapse after the lease's CLTT before a ping check is conducted, when the client is the lease's previous owner. The default value is 60 seconds.
The following parameter is only supported at the global level:
- ``ping-channel-threads`` - In multi-threaded mode, this is the number of threads in the channel's thread pool. The default is 0 which instructs the library to use the same number of threads as Kea core. The value is ignored if given when Kea is in single-threaded mode.
- ``ping-channel-threads`` - In multi-threaded mode, this is the number of threads in the channel's thread pool. The default is 0, which instructs the library to use the same number of threads as the Kea core. This value is ignored if given when Kea is in single-threaded mode.
The following configuration excerpt illustrates global level configuration:
The following configuration excerpt illustrates a global-level configuration:
.. code-block:: javascript
@ -144,7 +148,7 @@ The following configuration excerpt illustrates global level configuration:
}]
}
The following excerpt demonstrates subnet level configuration:
The following excerpt demonstrates a subnet-level configuration:
.. code-block:: javascript
@ -163,8 +167,3 @@ The following excerpt demonstrates subnet level configuration:
}
}]
}
.. note::
Ping checking is an experimental feature. It is not currently recommended for
production environments.

2
doc/sphinx/arm/hooks-radius.rst
View File

@ -5,7 +5,7 @@
============================================
This hook library allows the Kea DHCP servers to use the RADIUS protocol to
authorize DHCP clients through the access service or for DHCP lease journaling
authorize DHCP clients through the access service, or for DHCP lease journaling
through the accounting service. For details on RADIUS in Kea, please see
:ref:`radius`.

2
doc/sphinx/arm/hooks-rbac.rst
View File

@ -90,7 +90,7 @@ Role Configuration
.. note::
The role assignment may fail, for instance with ``cert-subject`` when
The role assignment may fail with ``cert-subject`` when
the client certificate was not required, or it may have no subject common
name and instead have a DNS alternative subject name. In this case, the role
assignment returns the empty role and the ``default-role`` entry is used.

7
doc/sphinx/arm/hooks-run-script.rst
View File

@ -12,9 +12,10 @@ packet-processing hook points.
:ischooklib:`libdhcp_run_script.so` is part of the open source code and is
available to every Kea user.
The library, which was added in Kea 1.9.5, can be loaded in a
similar way to other hook libraries by the :iscman:`kea-dhcp4` and
:iscman:`kea-dhcp6` processes.
.. note::
This library can only be loaded by the :iscman:`kea-dhcp4` or
:iscman:`kea-dhcp6` process.
.. code-block:: json

23
doc/sphinx/arm/hooks-subnet-cmds.rst
View File

@ -358,17 +358,18 @@ The response to this command has the following structure:
}
}
It is recommended, but not mandatory, to specify the subnet ID. If not
specified, Kea will try to assign the next ``subnet-id`` value. This
As of Kea 2.6.0, Kea no longer automatically generates subnet IDS; they must
be specified for :isccmd:`subnet4-add` and :isccmd:`subnet6-add`. If not
specified, Kea tries to assign the next ``subnet-id`` value. This
automatic ID value generator is simple; it returns the previous
automatically assigned value, increased by 1. This works well, unless
a subnet is manually created with a larger value than one previously used. For
example, if :isccmd:`subnet4-add` is called five times, each without an ID, Kea will
assign IDs 1, 2, 3, 4, and 5 and it will work just fine. However, if
assign IDs 1, 2, 3, 4, and 5 and everything will work properly. However, if
:isccmd:`subnet4-add` is called five times, with the first subnet having the
``subnet-id`` of value 3 and the remaining ones having no ``subnet-id``, the operation will
fail. The first command (with the explicit value) will use ``subnet-id`` 3; the
second command will create a subnet with and ID of 1; the third will use a
second command will create a subnet with an ID of 1; the third will use a
value of 2; and finally the fourth will have its ``subnet-id`` value
auto-generated as 3. However, since there is already a subnet with that
ID, the process will fail.
@ -432,10 +433,10 @@ The response to this command has the following structure:
}
As with other update commands, this command overwrites all the contents of the
entry. If the IPv4 subnet previously had a resource assigned to it, and the
entry. If the IPv4 subnet previously had a resource assigned to it and the
:isccmd:`subnet4-update` command is missing the resource, it is deleted from the
server configuration. If an incremental update of the subnet is desired, then
this can be achieved with :isccmd:`subnet4-delta-add`.
server configuration. If an incremental update of the subnet is desired,
use :isccmd:`subnet4-delta-add`.
.. isccmd:: subnet6-update
.. _command-subnet6-update:
@ -486,10 +487,10 @@ The response to this command has the following structure:
}
As with other update commands, this command overwrites all the contents of the
entry. If the IPv6 subnet previously had a resource assigned to it, and the
entry. If the IPv6 subnet previously had a resource assigned to it and the
:isccmd:`subnet6-update` command is missing the resource, it is deleted from the
server configuration. If an incremental update of the subnet is desired, then
this can be achieved with :isccmd:`subnet6-delta-add`.
server configuration. If an incremental update of the subnet is desired,
use :isccmd:`subnet6-delta-add`.
.. isccmd:: subnet4-del
.. _command-subnet4-del:
@ -1172,7 +1173,7 @@ command looks as follows:
}
}
Assuming there was such a network configured, the response will look
Assuming such a network was configured, the response looks
similar to the following:
::

48
doc/sphinx/arm/hooks.rst
View File

@ -241,8 +241,8 @@ Notes:
There is one case where this is not true: if Kea is running with a
configuration that contains a ``hooks-libraries`` item, and that
item is removed and the configuration reloaded, the removal will
be ignored and the libraries remain loaded. As a workaround,
item is removed and the configuration reloaded, the removal is
ignored and the libraries remain loaded. As a workaround,
instead of removing the ``hooks-libraries`` item, change it to an
empty list.
@ -257,13 +257,13 @@ Order of Configuration:
It is important to recognize that the order in which hook libraries are
configured determines the order in which their callouts will be executed,
in cases where more than one hook library implements the same callout. For
example, if you wish to use the flex-id hook library to formulate the client
IDs in conjunction with HA hook library for load-balanced HA, it is essential
that the flex-id library be specified first in your server's ``hooks-libraries``
section. This ensures that the client ID is formulated by the flex-id library
before the HA library uses it for load-balancing. Similarly it would be best to
specify forensic logging last, to ensure any other install hooks have made
their contributions to the packet processing.
example, to use the Flexible Identifier (also called Flex ID) hook library to formulate the client
IDs in conjunction with the High Availability (HA) hook library for load-balanced HA, it is essential
that the Flex ID library be specified first in the server's ``hooks-libraries``
section. This ensures that the client ID is formulated by the Flex ID library
before the HA library uses it for load-balancing. Similarly, it is best to
specify the Forensic Logging library last, to ensure that any other installed hooks have already made
their contributions to the packet processing before that one is loaded.
.. _user-context-hooks:
@ -295,7 +295,7 @@ User context can store configuration for multiple hooks and comments at once.
Some hooks use user context for a configuration that can be easily edited
without the need to restart the server.
The DDNS-Tuning Hook uses user-context to configure per subnet behavior. Example:
The DDNS Tuning Hook uses user context to configure per-subnet behavior. Here's an example:
::
@ -370,9 +370,9 @@ Parked-Packet Limit
~~~~~~~~~~~~~~~~~~~
Kea servers contain a mechanism by which the response to a client packet may
be held, pending completion of hook library work. We refer to this as parking
the packet. When work is ready to continue, the server will unpark the response
and continue processing.
be held, pending completion of hook library work. We refer to this as "parking
the packet." When work is ready to continue, the server unparks the response
and continues processing.
There is a global parameter, ``parked-packet-limit``, that may be used to limit
the number of responses that may be parked at any given time. This acts as a
@ -382,7 +382,7 @@ limit is reached, the server emits a log and drops any new responses until
parking spaces are available.
In general, smaller values for the parking lot limit are likely to cause more
drops but with shorter response times. Larger values are likely to result in
drops but with shorter response times; larger values are likely to result in
fewer drops but with longer response times. Currently, the default value for
``parked-packet-limit`` is 256.
@ -396,7 +396,7 @@ fewer drops but with longer response times. Currently, the default value for
recommend users initially leave it at the default value of 256 and observe
how the system behaves over time with varying load conditions.
Here is an example of the global parameter used with ischooklib:`libdhcp_ha.so`.
Here is an example of the global parameter used with :ischooklib:`libdhcp_ha.so`.
It lowers the number of concurrently parked packets to 128.
.. code-block:: json
@ -446,9 +446,9 @@ libraries, discussed in the following sections.
.. note::
Some of these libraries are available with the base code, while others are
premium libraries available for purchase, or only shared with organizations
who contribute to Kea's development through paid ISC support contracts. Paid support
Some of these libraries are available at no cost with the open source base code; others are
premium libraries available for standalone purchase, while some are only available to organizations
that contribute to Kea's development through paid ISC support contracts. Paid support
includes professional engineering assistance, advance security notifications, input
into ISC's roadmap planning, and many other benefits, while helping
keep Kea sustainable in the long term. ISC encourages companies and organizations
@ -598,13 +598,13 @@ loaded by the correct process per the table below.
| | | a repository for the Kea configuration information. Kea |
| | | servers use this library to fetch their configurations. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+
| :ref:`PerfMon <hooks-perfmon>` | Kea open | With this hook library, :iscman:`kea-dhcp4` server and |
| | source | :iscman:`kea-dhcp6` servers can track and report performance |
| | | data. CURRENTLY UNDER DEVELOPMENT |
| :ref:`PerfMon <hooks-perfmon>` | Kea open | With this hook library, :iscman:`kea-dhcp4` and |
| CURRENTLY EXPERIMENTAL | source | :iscman:`kea-dhcp6` servers can track and report performance |
| | | data. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+
| :ref:`Ping Check <hooks-ping-check>` | ISC support | With this hook library, :iscman:`kea-dhcp4` server can |
| | customers | perform ping checks of candidate lease addresses before |
| | | offering them to clients. |
| :ref:`Ping Check <hooks-ping-check>` | ISC support | With this hook library, the :iscman:`kea-dhcp4` server can |
| | source | perform ping checks of candidate lease addresses before |
| | customers | offering them to clients. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+
| :ref:`PostgreSQL Configuration Backend <hooks-cb-pgsql>` | Kea open | This hook library is an implementation of the Kea |
| | source | Configuration Backend for PostgreSQL. It uses a PostgreSQL |

74
doc/sphinx/arm/install.rst
View File

@ -7,23 +7,23 @@ Installation
Packages
========
ISC publishes native RPM, deb, and APK packages, along with the tarballs
with the source code. The packages are available on
`Cloudsmith <https://cloudsmith.io/~isc/repos/>`_ at
https://cloudsmith.io/~isc/repos. The native packages can be downloaded
ISC publishes native RPM, deb, and APK packages, as well as tarballs
with the source code. The packages are available in
`ISC's Cloudsmith repositories <https://cloudsmith.io/~isc/repos>`_.
The native packages can be downloaded
and installed using the system available in a specific distribution (such
as dpkg or rpm). The Kea repository can also be added to the system,
making it easier to install updates. For details, please
go to https://cloudsmith.io/~isc/repos, choose the repository of
interest, and then click the ``Set Me Up`` button. For detailed
instructions or refer to ISC `KB article <https://kb.isc.org/docs/isc-kea-packages>`_.
go to https://cloudsmith.io/~isc/repos, choose the desired Kea version,
and then click the "Set Me Up" button. For detailed
instructions, please refer to this `Knowledgebase article <https://kb.isc.org/docs/isc-kea-packages>`_.
Installation From Cloudsmith Packages
-------------------------------------
ISC provides Kea packages for Alpine, Debian, Fedora, RHEL, and Ubuntu.
The recommended method for installing Kea on any of these systems, from the
Cloudsmith repository for Kea release 2.3.1 or later, is to install the ``isc-kea``
metapackage. This metapackage is included on all supported distros and
The recommended method for installing Kea on any of these systems is to
install the ``isc-kea`` metapackage from the Cloudsmith repository.
This metapackage is included on all supported distros and
installs all of the services offered by the Kea software suite.
Specific Kea components
@ -41,17 +41,18 @@ can be installed individually, with any of the following packages:
- ``isc-kea-hooks`` — Kea open source DHCP hooks
Kea Premium hook packages are not included in the ``isc-kea-hooks`` package.
Kea premium hook packages are not included in the ``isc-kea-hooks`` package.
For ISC customers with access to the premium hooks, those packages have the
``isc-kea-premium-`` prefix.
``isc-kea-premium-`` prefix. Users wishing to purchase the premium hooks
can find them on ISC's website, at https://www.isc.org/shop/.
Once installed, the services can be managed through the distribution's
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
packages, to maintain compatibility with pre-existing scripts. A
The real service names on Debian and Ubuntu use slightly different
package names, to maintain compatibility with some older scripts. A
systemd service alias is used to allow users to refer to them with shorter
names. Calling ``systemctl enable`` on these services requires
the real service names, which are: ``isc-kea-dhcp4-server``,
@ -61,7 +62,7 @@ service manager. The services are named: :iscman:`kea-dhcp4`, :iscman:`kea-dhcp6
Caveats When Upgrading Kea Packages
-----------------------------------
To upgrade to Kea 2.3.2 or later from an earlier version of Kea on Debian
To upgrade to a current version of Kea from version 2.3.2 or earlier on Debian
and Ubuntu systems, run ``apt dist-upgrade`` instead of the usual ``apt upgrade``.
Once this upgrade has been completed, it is possible to upgrade to later versions
normally using ``apt upgrade`` on Debian and Ubuntu systems.
@ -88,11 +89,12 @@ To install the entire Kea software suite, simply run
``apt install isc-kea`` after upgrading, which
will install all of the relevant subpackages that make up Kea.
This upgrade path issue does not apply to RPM and Alpine systems; however,
customers with ISC support contracts who experience difficulties with upgrading
past 2.3.1 are invited to open a ticket in their support queue. Other users
are encouraged to describe their situation on the kea-users mailing list for
best-effort support from other list members.
This upgrade path issue does not apply to RPM and Alpine systems.
Customers with ISC support contracts who experience difficulties with upgrading
are invited to open a ticket in their support queue. Other users
are encouraged to describe their situation on the `kea-users mailing list <https://lists.isc.org/mailman/listinfo/kea-users>`_
for best-effort support from other list members.
.. _install-hierarchy:
@ -169,7 +171,7 @@ the system:
or on a machine reachable over a network is required. Note that running
the unit tests requires a local PostgreSQL server.
- Sysrepo v1.4.140 and libyang v1.0.240 are needed to connect to a Sysrepo
- Sysrepo v1.4.140 and libyang v1.0.240, needed to connect to a Sysrepo
datastore. Earlier versions are no longer supported. When compiling from
sources, the configure switches that can be used are ``--with-libyang`` and
``--with-sysrepo`` without any parameters. If these dependencies were
@ -177,7 +179,7 @@ the system:
- The MIT Kerberos 5 or Heimdal libraries are needed by Kea DDNS server to sign
and verify DNS updates using GSS-TSIG. The configuration switch which enables
this functionality is ``--with-gssapi`` without any parameters. If these
this functionality is ``--with-gssapi``, without any parameters. If these
dependencies were installed in custom paths, point the switch to them.
- googletest (version 1.8 or later) is required when using the ``--with-gtest``
@ -240,8 +242,8 @@ The code can be checked out from
The code checked out from the git repository does not include the
generated configure script or the Makefile.in files, nor their related build
files. They can be created by running ``autoreconf`` with the
``--install`` switch. This will run ``autoconf``, ``aclocal``,
files. Those can be created by running ``autoreconf`` with the
``--install`` switch, which will run ``autoconf``, ``aclocal``,
``libtoolize``, ``autoheader``, ``automake``, and related commands.
Write access to the Kea repository is only granted to ISC staff.
@ -297,13 +299,13 @@ options. Some commonly used options are:
found, Kea searches for OpenSSL. Normally this is not necessary.
- ``--enable-shell``
Build the optional :iscman:`kea-shell` tool (more in :ref:`kea-shell`).
Build the optional :iscman:`kea-shell` tool (see :ref:`kea-shell`).
The default is to not build it.
- ``--with-site-packages``
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
Install the kea-shell Python packages in the specified directory; this
is only useful when :iscman:`kea-shell` is enabled, and is
mostly helpful for Debian-related distributions. While most systems store
Python packages in ``${prefix}/usr/lib/pythonX/site-packages``, Debian
introduced a separate directory for packages installed from DEB. Such
Python packages are expected to be installed in
@ -379,7 +381,7 @@ If ``configure`` fails, it may be due to missing or old dependencies.
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., :iscman:`kea-dhcp4`.
and is also embedded into the executable binaries, e.g. :iscman:`kea-dhcp4`.
Build
-----
@ -438,7 +440,7 @@ system (the ``build`` system) from the one where Kea runs
It is outside of the scope of common administrator operations and requires
some developer skills, but the Developer Guide explains how to do that
using an x86_64 Linux system to build Kea for a Raspberry Pi box running
Raspbian: `Kea Cross-Compiling Example
Raspbian: see this `Kea Cross-Compiling Example
<https://reports.kea.isc.org/dev_guide/de/d9a/crossCompile.html>`__.
.. _dhcp-install-configure:
@ -449,7 +451,7 @@ DHCP Database Installation and Configuration
Kea stores its leases in a lease database. The software has been written
in a way that makes it possible to choose which database product should
be used to store the lease information. Kea supports three
database backends: MySQL, PostgreSQL and memfile. To limit external
database backends: MySQL, PostgreSQL, and memfile. To limit external
dependencies, MySQL and PostgreSQL support are disabled by default and only
memfile is available. Support for the optional external database backend must
be explicitly included when Kea is built.
@ -558,8 +560,8 @@ If using systemd, modify its service file
User=admin
Group=admin
The most important step is to set the capabilities of the binaries. Refer to `man capabilities` to get
more information.
The most important step is to set the capabilities of the binaries. Refer to the operating system man page
for `capabilities` for more information.
.. code-block:: console
@ -614,7 +616,7 @@ Deprecated Features
===================
This section lists significant features that have been or will be removed. We try to
deprecate features before removing them to signal
deprecate features before removing them, to signal
to current users to plan a migration. New users should not rely on deprecated features.
Sysrepo 0.x or 1.x
@ -622,12 +624,12 @@ Sysrepo 0.x or 1.x
Kea 2.3.2 introduced support for Sysrepo 2.x. Unfortunately,
Sysrepo continues to undergo major changes that are backward-incompatible,
and Kea versions 2.3.2 do not support Sysrepo earlier than versions 2.x.
and current Kea versions do not support Sysrepo earlier than versions 2.x.
:isccmd:`libreload` command
----------------------------------------
The :isccmd:`libreload` command was deprecated in Kea 2.3.4. The code to handle this command is
still there, but there are reports of it being buggy and not really usable.
Kea 2.3 and 2.4 versions will produce a warning when this command
Kea 2.3 and 2.4 versions produce a warning when this command
is used, and it will be removed entirely sometime in the 2.5 branch.

62
doc/sphinx/arm/logging.rst
View File

@ -123,7 +123,7 @@ program — and all libraries it uses other than 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
The currently defined loggers are listed 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).
@ -148,14 +148,14 @@ libraries), or hook libraries (open source or premium).
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.auth`` | core | A logger which covers |
| | | access control details, such as|
| | | a result of the basic HTTP |
| | | the result of basic HTTP |
| | | authentication. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.ctrl-agent`` | core | Used to log results of |
| | | configuration checks, |
| | | information about services |
| | | starting or failing to start, |
| | | command receival and |
| | | command reception, and |
| | | forwarding. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.http`` | core | A logger which |
@ -219,7 +219,7 @@ libraries), or hook libraries (open source or premium).
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.callouts``, | core | Used to log messages |
| ``kea-dhcp4.callouts``, | | pertaining to the |
| ``kea-dhcp6.callouts``, | | callouts registation and |
| ``kea-dhcp6.callouts``, | | callouts registration and |
| ``kea-dhcp-ddns.callouts`` | | execution for a particular |
| | | hook point. |
+----------------------------------+---------------------------------------+--------------------------------+
@ -242,7 +242,7 @@ libraries), or hook libraries (open source or premium).
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.database``, | core | Used to log messages |
| ``kea-dhcp6.database`` | | relating to general |
| | | operations on the |
| | | operations of the |
| | | relational databases. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.ddns-tuning-hooks``, | :ischooklib:`libdhcp_ddns_tuning.so` | Used to log messages related |
@ -291,9 +291,9 @@ libraries), or hook libraries (open source or premium).
| | | library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.hooks``, | core | Used to log messages related |
| ``kea-dhcp4.hooks``, | | to the maagemet of hook |
| ``kea-dhcp4.hooks``, | | to the management of hook |
| ``kea-dhcp6.hooks``, | | libraries, e.g. |
| ``kea-dhcp-ddns.hooks`` | | registatin and |
| ``kea-dhcp-ddns.hooks`` | | registration and |
| | | deregistration of the |
| | | libraries, and to the |
| | | initialization of the |
@ -322,7 +322,7 @@ libraries), or hook libraries (open source or premium).
| | | by the library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.hosts``, | core | Used within |
| ``kea-dhcp6.hosts`` | | ``libdhcpsrv``, it logs |
| ``kea-dhcp6.hosts`` | | ``libdhcpsrv`` to log |
| | | messages related to |
| | | the management of |
| | | DHCP host |
@ -399,7 +399,7 @@ libraries), or hook libraries (open source or premium).
| ``kea-dhcp4.packets``, | core | Mostly |
| ``kea-dhcp6.packets`` | | used to log messages |
| | | related to |
| | | transmission of the |
| | | transmission of |
| | | DHCP packets, i.e. |
| | | packet reception and |
| | | the sending of a |
@ -428,12 +428,14 @@ libraries), or hook libraries (open source or premium).
| | | the packet is parsed. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.perfmon-hooks``, | :ischooklib:`libdhcp_perfmon.so` | Used to log messages related |
| ``kea-dhcp6.perfmon-hooks`` | open-source hook library | to performance monitoring. |
| ``kea-dhcp6.perfmon-hooks`` | open-source hook library | to the operation of the |
| | | Performance Monitoring hook |
| | | library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.ping-check-hooks`` | :ischooklib:`libdhcp_ping_check.so` | Used |
| | subscription hook library | to log messages related to |
| | | carrying out pre-offer ping |
| | | checks of candidate leases. |
| | | the operation of the Ping |
| | | Check hook library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.pgsql-cb-hooks``, | :ischooklib:`libdhcp_pgsql_cb.so` | Used |
| ``kea-dhcp6.pgsql-cb-hooks`` | open-source hook library | to log messages |
@ -482,7 +484,7 @@ libraries), or hook libraries (open source or premium).
| ``kea-dhcp6.tcp`` | | to TCP traffic. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.user_chk``, | :ischooklib:`libdhcp_user_chk.so` | Used to log messages related |
| ``kea-dhcp6.user_chk`` | hook library | to the operaton of the |
| ``kea-dhcp6.user_chk`` | hook library | to the operation of the |
| | | User Check hook library. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp-ddns`` | core | The root logger for |
@ -497,7 +499,7 @@ libraries), or hook libraries (open source or premium).
| | | more specialized |
| | | loggers. |
+----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.dctl``, | core | Used to log basic inofrmaton |
| ``kea-ctrl-agent.dctl``, | core | Used to log basic information |
| ``kea-dhcp-ddns.dctl`` | | about the process, |
| | | received signals, and |
| | | triggered |
@ -623,13 +625,13 @@ where log messages are sent and are explained in detail below.
.. note::
As of Kea 2.5.1, alias ``output-options`` was added that can be used
interchangeably with previous ``output_options`` configuration key.
The reason behind this was to keep all configuration keys consistent i.e.
to use "dash" instead of "underscore" in the key name. For the time being
The alias ``output-options`` was added in Kea 2.5.1, to be used
interchangeably with the previous ``output_options`` configuration key.
This was done to keep all configuration keys consistent, i.e.
using a hyphen (`-`) instead of an underscore (`_`) in the key name. Currently,
both configuration keys are considered correct and mean the same to Kea parsers.
As of Kea 2.5.2, the ``output-options`` becomes the default configuration key
As of Kea 2.5.2, ``output-options`` becomes the default configuration key
and ``output_options`` can be used as an alias.
The ``output`` (string) Option
@ -647,7 +649,7 @@ The ``flush`` (boolean) Option
This flushes the buffers after each log message. Doing this reduces performance
but ensures that if the program terminates abnormally, all messages
up to the point of termination are output. The default is ``true``.
up to the point of termination are recorded. The default is ``true``.
The ``maxsize`` (integer) Option
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -900,24 +902,24 @@ A complete list of logging parameters supported by Kea is shown in the table bel
+-----------+------------------------------------------------------------------------+
| ``%M`` | Outputs caller (function name) of the log message |
+-----------+------------------------------------------------------------------------+
| ``%n`` | Outputs line separator suppored by platform e.g., ``\n`` in Linux |
| ``%n`` | Outputs line separator supported by platform e.g., ``\n`` in Linux |
+-----------+------------------------------------------------------------------------+
| ``%p`` | Outputs log severity e.g., INFO |
+-----------+------------------------------------------------------------------------+
| ``%r`` | Outputs milliseconds since program start e.g., 1235 |
+-----------+------------------------------------------------------------------------+
| ``%t`` | Outputs thread id that generated the log message e.g., 281472855306256 |
| ``%t`` | Outputs thread ID that generated the log message e.g., 281472855306256 |
+-----------+------------------------------------------------------------------------+
| ``%T`` | Outputs thread name that generated the log message e.g., 168005 |
+-----------+------------------------------------------------------------------------+
| ``%i`` | Outputs process id that generated the log message e.g., 168030 |
| ``%i`` | Outputs process ID that generated the log message e.g., 168030 |
+-----------+------------------------------------------------------------------------+
| ``%%`` | Outputs a literal percent sign |
+-----------+------------------------------------------------------------------------+
Padding and truncation are also possible with modifiers preceeding the component. This is
Padding and truncation are also possible with modifiers preceding the component; this is
done by placing a number and other modifier characters between the component and the %
sign. There are five ways of modifying the output shown by example here.
sign. There are five ways of modifying the output:
- ``%20p``
Left pads with spaces (align right) if the severity is shorter than 20 characters.
@ -939,11 +941,11 @@ sign. There are five ways of modifying the output shown by example here.
Right pad with spaces (align left) if the log message is shorter than 15 characters.
If the message is longer than 40 characters, truncate from the beginning.
Supported parameters depend on the liblog4cplus version used to compile Kea. This can
be checked by executing ``kea-dhcp4 -W | grep -i log4cplus`` which will produce output
like this: ``LOG4CPLUS_VERSION: 2.0.5``. Consult the documentation in the
Supported parameters depend on the liblog4cplus version used to compile Kea, which can
be checked by executing ``kea-dhcp4 -W | grep -i log4cplus``. This produces a result
such as: ``LOG4CPLUS_VERSION: 2.0.5``. Consult the documentation in the
`log4cplus wiki <https://github.com/log4cplus/log4cplus/wiki>`__ for further information
about the version you have installed.
about the installed version.
Example Logger Configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -1010,7 +1012,7 @@ 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. In the absence of
any logging configuration in the configuration file, the settings of the
(possibly modified) default configuration will persist while the program
(possibly modified) default configuration persist while the program
is running.
The following environment variables can be used to control the behavior

31
doc/sphinx/arm/quickstart.rst
View File

@ -17,8 +17,8 @@ Quick Start Guide Using tarball
:ref:`build-requirements` for details.
2. Download the Kea source tarball from
`the ISC.org downloads page <https://www.isc.org/download/>`__ or
`the ISC downloads site <https://downloads.isc.org/isc/kea/>`__ or
`the main isc.org downloads page <https://www.isc.org/download/>`__,
`the ISC downloads site <https://downloads.isc.org/isc/kea/>`__, or
`the ISC Cloudsmith page <https://cloudsmith.io/~isc/packages/?q=format%3Araw>`__.
3. Extract the tarball. For example:
@ -53,17 +53,17 @@ Quick Start Guide Using Native Packages
=======================================
ISC provides native Alpine, deb, and RPM packages, which make Kea installation
much easier. Unless specific compilation options are desired, it is usually
much easier than building from source. Unless specific compilation options are desired, it is usually
easier to install Kea using native packages.
1. Go to `Kea on cloudsmith.io <https://cloudsmith.io/~isc/repos/>`__.
2. Choose the Cloudsmith repository e.g. |cloudsmith_repo| for Kea |version|.
3. Click on the arrow besides the ``Set Me Up`` button and select your OS flavor
out of: ``Alpine``, ``Debian``, ``RedHat``.
3. Click on the arrow beside the "Set Me Up" button and select the desired OS flavor:
Alpine, Debian, or RedHat.
4. Follow the instructions written there.
4. Follow the onscreen instructions.
.. note::
For example, the Debian setup instructions for Kea 2.4 can be found here:
@ -152,7 +152,7 @@ or specific packages:
$ apk add isc-kea-dhcp6
or every single Kea-related package, including development headers, debug
or ALL Kea-related packages, including development headers, debug
symbols, and premium hooks (if available):
.. list-table::
@ -207,9 +207,9 @@ or all packages with a specified version number:
# apk search isc-kea | sed 's/-[0-9].*//g' | grep r20230921141113 | xargs apk add
8. All installed packages should be now available directly.
8. All installed packages should be now available.
You can start a server up manually:
You can start a server manually:
.. code-block:: console
@ -231,9 +231,9 @@ or all packages with a specified version number:
:iscman:`keactrl` is not available in packages, as similar functionality is provided
by the native systemctl scripts.
9. On Debian/Ubuntu systems, the service is enabled at boot time automatically
9. On Debian/Ubuntu systems, the service is automatically enabled at boot time
when the package is installed. On Fedora/RHEL and Alpine, the service is not
enabled automatically, so, if desired, it must be enabled manually.
automatically enabled, so if desired, it must be enabled manually.
With systemd on Fedora/RedHat:
@ -253,7 +253,7 @@ or all packages with a specified version number:
Quick Start Guide Using Docker Containers
=========================================
1. Go to `ISC docker repository on cloudsmith.io <https://cloudsmith.io/~isc/repos/docker/packages/>`__.
1. Go to the `ISC docker repository on cloudsmith.io <https://cloudsmith.io/~isc/repos/docker/packages/>`__.
2. Create an ipvlan network attached to the client-facing host interface and
assigned to the subnet that is served by Kea.
@ -268,8 +268,7 @@ Quick Start Guide Using Docker Containers
$ docker pull docker.cloudsmith.io/isc/docker/kea-dhcp6
4. Create a container out of the image. Mount the configuration volume and the
4. Create a container from the image. Mount the configuration volume and the
data volume if needed.
.. code-block:: console
@ -306,8 +305,8 @@ Quick Start Guide for DHCPv4 and DHCPv6 Services
1. Edit the Kea configuration files, which by default are installed in
the ``[kea-install-dir]/etc/kea/`` directory. These are:
``kea-dhcp4.conf``, ``kea-dhcp6.conf``, ``kea-dhcp-ddns.conf`` and
``kea-ctrl-agent.conf``, ``keactrl.conf`` for DHCPv4 server, DHCPv6 server,
D2, Control Agent, and the keactrl script, respectively.
``kea-ctrl-agent.conf``, ``keactrl.conf`` for the DHCPv4 server, DHCPv6 server,
D2, Control Agent, and keactrl script, respectively.
2. To start the DHCPv4 server in the background, run the
following command (as root):

4
doc/sphinx/arm/shell.rst
View File

@ -127,7 +127,7 @@ during the installation of Kea. When building on Debian systems,
.. note::
From Kea 2.4.0 version, the :iscman:`kea-shell` no longer supports Python 2.7.
Beginning with Kea 2.4.0, :iscman:`kea-shell` no longer supports Python 2.7.
The Kea shell is intended to serve more as a demonstration of the
RESTful interface's capabilities (and, perhaps, an illustration for
@ -146,7 +146,7 @@ tool.
TLS Support
===========
Since Kea 1.9.6, :iscman:`kea-shell` supports HTTPS connections. The TLS/HTTPS
: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

2
doc/sphinx/arm/stats.rst
View File

@ -26,7 +26,7 @@ There are four types of statistics:
64-bit integer (int64_t in C++), so it can hold any value between
-2^63 to 2^63-1.
- *big integer* - this type is inteded for holding large numbers. It is
- *big integer* - this type is intended to hold large numbers. It is
implemented as a 128-bit integer (boost::multiprecision::int128_t in C++), so
it can hold any value between -2^127 to 2^127-1.

14
doc/sphinx/man/kea-admin.8.rst
View File

@ -55,17 +55,17 @@ Arguments
for the Cassandra backend has been deprecated.)
The first line of the file contains the column names. This can be used
as a way to switch from a database backend to a memfile backend.
Alternatively, it can be used as a diagnostic tool, so it provides a
It can also be used as a diagnostic tool, as it provides a
portable form of the lease data. There are other mandatory arguments
that must be used together with this command. Either ``-4`` or ``-6`` must
be specified. Also ``-o`` or ``--output`` must be provided.
that must be used together with this command: either ``-4`` or ``-6`` must
be specified, and either ``-o`` or ``--output`` must be provided.
``lease-upload``
Uploads leases from a CSV (comma-separated values) text file to a MySQL or
a PostgreSQL lease database. The CSV file needs to be in memfile format.
There are other mandatory arguments that must be used together with this
command. Either ``-4`` or ``-6`` must be specified.
Also ``-i`` or ``--input`` must be provided.
command: either ``-4`` or ``-6`` must be specified,
and either ``-i`` or ``--input`` must be provided.
``stats-recount``
Recounts lease statistics for a MySQL or PostgreSQL database.
@ -79,8 +79,8 @@ Arguments
The default value is ``localhost``.
``-i|--input input_file``
Specifies the CSV (comma-separated values) text file with leases to be uploaded.
Required for ``lease-upload``.
Specifies the CSV (comma-separated values) text file with the leases to be uploaded;
required for ``lease-upload``.
``-P|--port port``
Specifies the port when connecting to a database. If not specified,

43
doc/sphinx/man/perfdhcp.8.rst
View File

@ -240,16 +240,15 @@ Options
``-o code,hexstring``
Forces ``perfdhcp`` to insert the specified extra option (or options if
used several times) into packets being transmitted. The code
specifies the option code and the hexstring is a hexadecimal string that
defines the content of the option. Care should be taken as ``perfdhcp``
does not offer any kind of logic behind those options; they are simply
used multiple times) into packets being transmitted. The code
specifies the option code, and the hexstring is a hexadecimal string that
defines the content of the option. Care should be taken, as ``perfdhcp``
does not offer any kind of logic behind the options; they are simply
inserted into packets and sent as is. Be careful not to duplicate
options that are already inserted. For example, to insert client
class identifier (option code 60) with a string "docsis", use
"-o 60,646f63736973". The ``-o`` may be used multiple times. It is
necessary to specify the protocol family (either ``-4`` or ``-6``) before
using ``-o``.
options that are already inserted. For example, to insert the
client-class identifier (option code 60) with the string "docsis", use
``-o 60,646f63736973``. The ``-o`` may be used multiple times. The protocol
family (``-4`` or ``-6``) must be specified before using ``-o``.
``-P preload``
Initiates preload exchanges back-to-back at startup. Must be 0
@ -362,19 +361,19 @@ The following options only apply for DHCPv6 (i.e. when ``-6`` is given).
traffic passing through a single relay agent.
``--or encapsulation-level:code,hexstring``
This option is very similar to ``-o``, only that it forces ``perfdhcp``
to insert the specified extra option (or options if used several times)
into relayed DHCPv6 message at given level of encapsulation (currently
the only supported encapsulation-level value is 1). The code
specifies the option code and the hexstring is a hexadecimal string that
defines the content of the option. Care should be taken as ``perfdhcp``
does not offer any kind of logic behind those options; they are simply
inserted into packets and sent as is. Please notice that ``encapsulation-level:``
is optional and if omitted, default encapsulation-level value 1 is used.
For example, to insert Subscriber identifier (option code 38) with a
value 1234 at first level of encapsulation, use ``--or 38,31323334``
or ``--or 1:38,31323334``. The ``--or`` may be used multiple times.
It must be used together with ``-A``.
Forces ``perfdhcp`` to insert the specified extra option (or options if
used multiple times) into a relayed DHCPv6 message at the given level of
encapsulation; currently, the only supported encapsulation-level value is 1.
This option is very similar to ``-o``: the code
specifies the option code, and the hexstring is a hexadecimal string that
defines the content of the option. Care should be taken, as ``perfdhcp``
does not offer any kind of logic behind the options; they are simply
inserted into packets and sent as is. ``encapsulation-level:``
is optional; if it is omitted, the default encapsulation-level value 1 is used.
For example, to insert the Subscriber identifier (option code 38) with a
value 1234 at the first level of encapsulation, use ``--or 38,31323334``
or ``--or 1:38,31323334``. The ``--or`` may be used multiple times, and
it must be used in conjunction with ``-A``.
Template-Related Options
~~~~~~~~~~~~~~~~~~~~~~~~