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 ``backend``. Additional, non-mandatory options may be specified. The
currently supported commands are: currently supported commands are:
- ``db-init`` — initializes a new database schema. This is useful - ``db-init`` — initializes a new database schema, which is useful
during a new Kea installation. The database is initialized to the during a new Kea installation. The new database is updated to
latest version supported by the version of the software being installed. match the Kea version being installed. :iscman:`kea-admin` is
Called automatically on startup or reconfiguration of Kea DHCP servers if automatically invoked with this command if a missing schema is
required. detected during startup or reconfiguration of Kea DHCP servers.
- ``db-version`` — reports the database backend version number. This - ``db-version`` — reports the database backend version number. This
is not necessarily equal to the Kea version number, as each backend 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 | | Lcase | lcase('LoWeR') | Converts the value of |
| | | a string expression | | | | a string expression |
| | | to lower case e.g. | | | | to lower case, e.g. |
| | | 'lower' | | | | 'lower' |
+-----------------------+-------------------------+-----------------------+ +-----------------------+-------------------------+-----------------------+
| Ucase | ucase('uPpEr') | Converts the value of | | Ucase | ucase('uPpEr') | Converts the value of |
| | | a string expression | | | | a string expression |
| | | to upper case e.g. | | | | to upper case, e.g. |
| | | 'UPPER' | | | | 'UPPER' |
+-----------------------+-------------------------+-----------------------+ +-----------------------+-------------------------+-----------------------+
| Split | split('foo.bar', '.', 2)| Return the second | | 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 The next example shows a client class named "Client_enterprise" being defined
server. In it the class named "Client_enterprise" is defined. It is for use by the DHCPv6 server. It is
comprised of all clients whose client identifiers start with the given comprised of all clients whose client identifiers start with the given
hex string (which would indicate a DUID based on an enterprise ID of 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 ``0x0002AABBCCDD``. Members of this class will be given 2001:db8:0::1 and
2001:db8:2::1 as their domain name servers. 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 configuration (vs. alphabetical order). Required classes follow the order in
which they are required. which they are required.
When determining which client-class information (comprising of When determining which client-class information (comprised of
options, lease lifetimes or DHCPv4 field values) that is part of class options, lease lifetimes, or DHCPv4 field values) is part of the class
definitions, to include in the response, the server examines the union of 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 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. 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 priority, and matching required classes are last, so they have the
lowest priority. lowest priority.
Optons defined in classes override any global options, and in turn will be Options defined in classes override any global options, and in turn are
overridden by options defined for an individual subnet, shared network, pool or overridden by options defined for an individual subnet, shared network, pool, or
reservation. reservation.
On the other hand, lease lifetimes and DHCPv4 field values defined at class 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 The PostgreSQL Configuration Backend is the logic implemented within
:ischooklib:`libdhcp_pgsql_cb.so`, which provides a complete set of functions to :ischooklib:`libdhcp_pgsql_cb.so`, which provides a complete set of functions to
manage and fetch the configuration information from the PostgreSQL database. 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. PostgreSQL database.
In small deployments, e.g. those comprising a single DHCP server In small deployments, e.g. those comprising a single DHCP server
instance with limited and infrequently changing number of subnets, it instance with limited and infrequently changing number of subnets, it
may be impractical to use the CB as a configuration repository because may be impractical to use the CB as a configuration repository because
it requires additional third-party software to be installed and 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 Once the number of DHCP servers and/or the number of managed subnets in the
network grows, the usefulness of the CB becomes obvious. 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 Using the database as a configuration repository for Kea servers also
brings other benefits, such as: 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; information;
- the ability to create customized statistics based on the information - the ability to create customized statistics based on the information
@ -163,13 +163,13 @@ in two independent configuration sources.
CB Components CB Components
------------- -------------
To use a MySQL configuration backend you must compile To use a MySQL configuration backend, :ischooklib:`libdhcp_mysql_cb.so`
:ischooklib:`libdhcp_mysql_cb.so` and configure the DHCP servers to load it. 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. 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`. 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` To use a PostgreSQL configuration backend, :ischooklib:`libdhcp_pgsql_cb.so` must
and configure the DHCP servers to load it. It is compiled when 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 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`. 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 servers' configuration information within the database. This library can
be attached to both DHCPv4 and DHCPv6 server instances. While it is be attached to both DHCPv4 and DHCPv6 server instances. While it is
possible to manage the configuration information without :ischooklib:`libdhcp_cb_cmds.so` possible to manage the configuration information without :ischooklib:`libdhcp_cb_cmds.so`
with commonly available tools, such as MySQL Workbench or using commonly available tools, such as MySQL Workbench or
the command-line MySQL client, or by directly working with the database; the command-line MySQL client, or by directly working with the database,
these avenues are neither recommended nor supported. these avenues are neither recommended nor supported.
The DHCPv4 and DHCPv6 server-specific configurations of the CB, as well as 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 Commands which contain the logical server `all` are applied to all servers
connecting to the database. The `all` server cannot be connecting to the database. The `all` server cannot be
deleted or modified, and it is not returned among other servers 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 In most cases, there are no server tags defined in the configuration
database; all connecting servers get the same configuration database; all connecting servers get the same configuration
@ -242,7 +242,7 @@ servers.
To differentiate between different Kea server configurations, a To differentiate between different Kea server configurations, a
list of the server tags used by the servers must be stored in the 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 :isccmd:`remote-server4-set` and :isccmd:`remote-server6-set` commands. The
server tags can then be used to associate the configuration information with server tags can then be used to associate the configuration information with
the servers. However, it is important to note that some DHCP 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; curly brackets). However, some hook libraries may expect specific formatting;
please consult the specific hook library documentation for details. please consult the specific hook library documentation for details.
In a sense the user-context mechanism has superseded the JSON comment The user-context mechanism has superseded the JSON comment
capabilities; ISC encourages administrators to use user-context instead of capabilities; ISC encourages administrators to use user context instead of
the older mechanisms. To promote this way of storing comments, Kea compared the older mechanisms. To promote this way of storing comments, Kea
converts JSON comments to user-context on the fly. converts JSON comments to user context on the fly.
However, if the configuration uses the old JSON However, if the configuration uses the old JSON
comment, the :isccmd:`config-get` command returns a slightly modified 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 a configuration. It is not uncommon for a call for :isccmd:`config-set` followed by
:isccmd:`config-get` to receive a slightly different structure. :isccmd:`config-get` to receive a slightly different structure.
The best way to avoid this problem is simply to abandon JSON comments and 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, Kea supports user contexts at the following levels: global scope,
interfaces configuration, shared networks, 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 :isccmd:`config-set` command. However, there may be certain differences, as
comments are not retained. If the original configuration used file comments are not retained. If the original configuration used file
inclusion, the returned configuration includes all parameters from inclusion, the returned configuration includes all parameters from
all included files. Starting with 2.4.0, the successful response also 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 if a contains a SHA-256 digest that can be used to easily determine whether a
configuration has changed or not. configuration has changed.
.. warning:: .. 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 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 later determine if a configuration of the new or current configuration. This may be used to determine whether a configuration
has changed or not. has changed.
.. isccmd:: config-reload .. isccmd:: config-reload
.. _command-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 configuration file that was used previously. This operation is useful if
the configuration file has been changed by some external source; for the configuration file has been changed by some external source; for
example, a system administrator can tweak the configuration file and use this 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, remembers the location of the configuration file it was started with,
and this configuration can be significantly changed using the :isccmd:`config-set` 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 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 hook libraries to be replaced with newer versions, without requiring Kea
servers to be reconfigured or restarted. The hook libraries servers to be reconfigured or restarted. The hook libraries
are passed the same parameter values (if any) that were passed when they 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)" } {"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 In Kea 2.4.0 and later, the successful response from a DHCPv4, DHCPv6, or DHCP-DDNS daemon
also contain a SHA-256 digest of the newly set configuration. The digest can be used to easily also contains a SHA-256 digest of the newly set configuration. The digest can be used to easily
determine if a configuration has changed or not. determine whether a configuration has changed.
.. isccmd:: shutdown .. isccmd:: shutdown
.. _command-shutdown: .. _command-shutdown:
@ -654,7 +654,7 @@ The ``shutdown`` Command
------------------------ ------------------------
The :isccmd:`shutdown` command instructs the server to initiate its shutdown 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 process. This command does not take any arguments. An example command
may look like this: 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 Since Kea 1.9.4, there is an additional ``origin`` parameter that specifies the
command source. A server administrator should typically omit this parameter command source. A server administrator should typically omit this parameter
because the default value "user" indicates that the administrator sent the 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 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 in a numeric format. However, due to compatibility issues with older
Kea versions that did not properly parse the numeric values, it was necessary Kea versions that did not properly parse numeric values, it was necessary
to introduce the new parameter, ``origin-id``, in Kea 2.5.8. 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 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 can still be passed using the ``origin`` parameter, but it can cause the
aforementioned compatibility issues between the HA partners running different aforementioned compatibility issues between HA partners running different
Kea versions. Therefore, new Kea versions favor using ``origin-id`` in communication Kea versions; if both are used, ``origin-id`` takes precedence. New Kea versions
between the HA partners. The ``origin`` parameter can still be used, but the favor using ``origin-id`` in communication between the HA partners, but
``origin-id`` takes precedence. Overall, it is recommended that both parameters be overall, it is recommended that both parameters be
omitted from the user commands. omitted and the default value used.
The following codes represent the supported origins in numeric format: The following codes represent the supported origins in numeric format:
- ``1`` - a user command, same as specifying ``"origin": "user"``, - ``1`` - a user command; the same as specifying ``"origin": "user"``.
- ``2000``, ``2001``, ``2002`` etc. - origins specified by HA partners where - ``2000``, ``2001``, ``2002``, etc. - origins specified by HA partners where
the increments above ``2000`` are distinct HA service identifiers used when the increments above ``2000`` are distinct HA service identifiers used when
the partners have many relationships. 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`` sending the command for the service with ID of ``2``. The ``origin``
parameter will be ignored in this case. 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 Since Kea 1.9.4, there is an additional ``origin`` parameter that specifies the
command source. A server administrator should typically omit this parameter command source. A server administrator should typically omit this parameter
because the default value "user" indicates that the administrator sent the 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 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 in a numeric format. However, due to compatibility issues with older
Kea versions that did not properly parse the numeric values, it was necessary Kea versions that did not properly parse numeric values, it was necessary
to introduce the new parameter, ``origin-id``, in Kea 2.5.8. 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 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 can still be passed using the ``origin`` parameter, but it can cause the
aforementioned compatibility issues between the HA partners running different aforementioned compatibility issues between HA partners running different
Kea versions. Therefore, new Kea versions favor using ``origin-id`` in communication Kea versions.; if both are used, ``origin-id`` takes precedence. New Kea versions
between the HA partners. The ``origin`` parameter can still be used, but the favor using ``origin-id`` in communication between the HA partners, but
``origin-id`` takes precedence. Overall, it is recommended that both parameters be overall, it is recommended that both
omitted from the user commands.
The following codes represent the supported origins in numeric format: The following codes represent the supported origins in numeric format:
- ``1`` - a user command, same as specifying ``"origin": "user"``, - ``1`` - a user command; the same as specifying ``"origin": "user"``.
- ``2000``, ``2001``, ``2002`` etc. - origins specified by HA partners where - ``2000``, ``2001``, ``2002``, etc. - origins specified by HA partners where
the increments above ``2000`` are distinct HA service identifiers used when the increments above ``2000`` are distinct HA service identifiers used when
the partners have many relationships. 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`` sending the command for the service with ID of ``2``. The ``origin``
parameter will be ignored in this case. 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 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. 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 attempts even at server startup or on reconfigure events, and will honor the
action specified in the ``on-fail`` parameter. action specified in the ``on-fail`` parameter.
Database connection retries are not attempted on startup if the Database connection retries are not attempted on startup if the
:ischooklib:`libdhcp_limits.so` is loaded because the hook library requires a :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 valid connection to the database to check whether JSON format is supported and to
recount class limits. recount class limits.
During dynamic reconfiguration, all backends are disconnected and then 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 operations. If the connection cannot be restored and the server is configured
to exit, it issues a fatal error before shutdown. to exit, it issues a fatal error before shutdown.
For Kea DHCP servers to work with database backends, the schema has to be For Kea DHCP servers to work with database backends, the database schema must be
created and has to have the version specific to the version of the running Kea created and must match the version of the Kea
server. If the version check fails on a database backend that is not configured server. If the version check fails and the database backend is not configured
as readonly, Kea attempts to initialize the schema. as read-only, Kea attempts to initialize the schema.
.. note:: .. note::
Schema upgrades are not attempted to not accidentally remove the Kea does not automatically attempt to upgrade an existing schema; doing so
opportunity for prior administrative actions that users may be interested in, might deprive users of the opportunity to take precautions, such as
like, for example, backing up the database or temporarily shutting off running backing up the database or temporarily shutting off running
Kea servers that are currently operating on the database. Kea servers that are currently operating on the database.
The connection to the database server can optionally be protected by TLS. 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 DHCP-DDNS Server (:iscman:`kea-dhcp-ddns`, known informally as D2) conducts
the client side of the Dynamic DNS protocol (DDNS, defined in `RFC the client side of the Dynamic DNS protocol (DDNS, defined in `RFC
2136 <https://tools.ietf.org/html/rfc2136>`__) on behalf of the DHCPv4 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 The DHCP servers construct DDNS update requests, known as NameChangeRequests
(NCRs), based on DHCP lease change events and then post them to D2. D2 (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 attempts to match each request to the appropriate DNS server(s) and
carries out the necessary conversation with those servers to update the carries out the necessary conversation with those servers to update the
DNS data. DNS data.
For the ability to generate host names procedurally, based on an expression, and The Kea hook library :ischooklib:`libdhcp_ddns_tuning.so` provides the ability
for the ability to skip DDNS updates on a per-client basis, or fine-tuning for both :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` to generate host names
various DNS update aspects, the :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6` can procedurally based on an expression, to skip DDNS updates on a per-client basis,
load the premium hook library `libdhcp_ddns_tuning.so` which is available from or to fine-tune various DNS update aspects. Please refer to the :ref:`hooks-ddns-tuning`
ISC. Please refer to :ref:`hooks-ddns-tuning` documentation for the documentation for the configuration options.
configuration options.
.. _dhcp-ddns-dns-server-selection: .. _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 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. 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: - ``secret-file`` - since Kea 2.5.8, this more secure alternative is supported.
specify a file name where the secret can be found, i.e. the base64-encoded This value specifies the file name where the secret can be found, i.e. the base64-encoded
secret is the content of the file. secret is the content of the file.
As an example, suppose that a domain D2 will be updating is maintained As an example, suppose that a domain D2 will be updating is maintained

436
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 This hook library allows Kea to interact with two types of RADIUS
services: access and accounting. Although the most common DHCP and RADIUS services: access and accounting. The most common DHCP and RADIUS
integration is done on the DHCP relay-agent level (DHCP clients send integration is done on the DHCP relay-agent level: DHCP clients send
DHCP packets to DHCP relays; those relays contact the RADIUS server and 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 either send the packet to the DHCP server or drop it, depending on the
drop it), it does require DHCP relay hardware to support RADIUS response. It does require DHCP relay hardware to support RADIUS
communication. Also, even if the relay has the necessary support, it is communication, though, and even if the relay has the necessary support, it is
often not flexible enough to send and receive additional RADIUS 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. DHCP server to talk to RADIUS directly. That is the goal of this library.
.. note:: .. 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, then sends back either an Access-Accept with specific client attributes,
or an Access-Reject. There are two cases supported here: first, the or an Access-Reject. There are two cases supported here: first, the
Access-Accept includes a Framed-IP-Address attribute (for DHCPv4) or a 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 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. as an address-reservation database.
The second supported case is the ability to assign clients to specific 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": { "Dhcp4": {
// Your regular DHCPv4 configuration parameters goes here. // Your regular DHCPv4 configuration parameters go here.
"hooks-libraries": [ "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 RADIUS is a complicated environment. As such, it is not feasible
to provide a default configuration that works for everyone. to provide a default configuration that works for everyone.
However, we do have an example that showcases some of the more common 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. sources.
The RADIUS hook library supports the following global configuration The RADIUS hook library supports the following global configuration
flags: flags:
- ``bindaddr`` (default ``"*"``) - specifies the address to be used by the - ``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. value tells the kernel to choose the address at hook library load time.
- ``canonical-mac-address`` (default ``false``) - specifies whether MAC - ``canonical-mac-address`` (default ``false``) - specifies whether MAC
@ -103,49 +103,49 @@ flags:
pairs of hexadecimal digits separated by ``-``). pairs of hexadecimal digits separated by ``-``).
- ``client-id-pop0`` (default ``false``) - is used with - ``client-id-pop0`` (default ``false``) - is used with
:ischooklib:`libdhcp_flex_id.so`. Removes the leading zero (or pair of zeroes :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 in DHCPv6) type in the client ID (DUID in DHCPv6). See
``client-id-printable`` for any value implications when used in conjunction ``client-id-printable`` for any value implications when used in conjunction
with it. with it.
- ``client-id-printable`` (default ``false``) - checks whether the - ``client-id-printable`` (default ``false``) - checks whether the
``client-id``/``duid`` content is printable and uses it as is instead of in ``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. not printable.
- ``deadtime`` (default ``0``) - is a mechanism that helps in sorting the - ``deadtime`` (default ``0``) - is a mechanism that helps in sorting the
servers such that the servers that have proved responsive so far are inquired servers so those that have proved responsive so far are contacted
first, and the servers that have proved unresponsive are left at the end. The 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 deadtime value specifies the number of seconds after which a server is
considered unresponsive. 0 disables the mechanism. considered unresponsive. 0 disables the mechanism.
- ``dictionary`` (default ``"/etc/kea/radius/dictionary"``) - is the - ``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. A dictionary is provided by Kea and is set by default.
- ``extract-duid`` (default ``true``) - extracts the embedded duid from an - ``extract-duid`` (default ``true``) - extracts the embedded DUID from an
RFC-4361-compliant DHCPv4 client id. See ``client-id-printable`` for any RFC 4361-compliant DHCPv4 client ID. See ``client-id-printable`` for any
value implications when used in conjunction with it. value implications when used in conjunction with it.
- ``identifier-type4`` (default ``"client-id"``) - specifies the identifier - ``identifier-type4`` (default ``"client-id"``) - specifies the identifier
type to build the User-Name attribute. It should be the same as the 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 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 ``replace-client-id`` must be set to ``true`` and ``client-id`` must be used
with ``client-id-pop0`` enabled. with ``client-id-pop0`` enabled.
- ``identifier-type6`` (default ``"duid"``) - specifies the identifier type to - ``identifier-type6`` (default ``"duid"``) - specifies the identifier type to
build the User-Name attribute. It should be the same as the host 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 identifier. When :ischooklib:`libdhcp_flex_id.so` is used, then
``replace-client-id`` must be set to ``true`` and ``duid`` must be used with ``replace-client-id`` must be set to ``true`` and ``duid`` must be used with
``client-id-pop0`` enabled. ``client-id-pop0`` enabled.
- ``nas-ports`` (default ``[]``), specifies the NAS port to use in place of - ``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 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 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. 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 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 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 a default. The substitution happens for all packets that did not match a
selector. selector.
- ``realm`` (default ``""``) - is the default realm. - ``realm`` (default ``""``) - is the default realm.
@ -153,8 +153,8 @@ flags:
- ``reselect-subnet-address`` (default ``false``) - enables subnet reselection - ``reselect-subnet-address`` (default ``false``) - enables subnet reselection
according to the value of the Framed-IP-Address or, respectively, according to the value of the Framed-IP-Address or, respectively,
the Framed-IPv6-Address attribute from the RADIUS access response. With this 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 flag enabled, if the IP address is not in the range of the currently selected
subnet, but is in range of another subnet that is selectable with regards to 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 other criteria, the latter subnet is selected and used further in the lease
assignment process. assignment process.
@ -165,7 +165,7 @@ flags:
another selectable subnet that is guarded by it, the latter subnet is another selectable subnet that is guarded by it, the latter subnet is
selected and used further in the lease assignment process. selected and used further in the lease assignment process.
This reselection is attempted first, and if successful, it prevents the 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 - ``retries`` (default ``3``) - is the number of retries before trying the
next server. next server.
@ -174,11 +174,11 @@ flags:
persistent storage for accounting session history. persistent storage for accounting session history.
- ``thread-pool-size`` (default ``0``) indicates the number of threads that - ``thread-pool-size`` (default ``0``) indicates the number of threads that
is used for sending RADIUS requests and processing RADIUS responses for both are used for sending RADIUS requests and processing RADIUS responses for both
access and accounting services before passing it to the core thread pool. A 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 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 threads used for core DHCP processing. This value is only relevant if the Kea
core is configured as multi-threaded. Single-threaded Kea core results in core is configured as multi-threaded; a single-threaded Kea core results in
single-threaded RADIUS processing. single-threaded RADIUS processing.
- ``timeout`` (default ``10``) - is the number of seconds during which a - ``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 defines the value in hex), or ``expr`` (which defines an expression
that is evaluated for each incoming packet independently). 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. 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. 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. 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. 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. Attributes are supported only for the access service.
- The ``peer-updates`` boolean flag (default ``true``) controls whether lease - The ``peer-updates`` boolean flag (default ``true``) controls whether lease
updates coming from an active High-Availability (HA) partner should result in updates coming from an active High-Availability (HA) partner should result in
an accounting request. This may be desirable to remove duplicates if HA 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 only supported by the accounting service. The lease synchronization process at
the startup of an HA node does not trigger a RADIUS accounting request, the startup of an HA node does not trigger a RADIUS accounting request,
regardless of the value of this flag. regardless of the value of this flag.
- The ``max-pending-requests`` positive integer (default ``0``) limits the - The ``max-pending-requests`` positive integer (default ``0``) limits the
number of pending RADIUS requests. The value ``0`` means no limit. It is number of pending RADIUS requests. It is supported only by the access service.
supported only by the access service. ``64`` can be a good value to set it to. The value ``0`` means no limit; ``64`` is a recommended setting.
For example, to specify a single access server available on localhost For example, to specify a single access server available on localhost
that uses ``"xyz123"`` as a secret, and tell Kea to send three additional 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, For :ischooklib:`libdhcp_radius.so` to operate properly in DHCPv4,
:ischooklib:`libdhcp_host_cache.so` must also be loaded. The reason for this :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 their packets via DHCP relay, which inserts certain Relay Agent
Information options, such as ``circuit-id`` or ``remote-id``. The values of 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 those options are then used by the Kea DHCP server to formulate the
necessary attributes in the Access-Request message sent to the RADIUS necessary attributes in the Access-Request message sent to the RADIUS
server. However, once the DHCP client gets its address, it then renews 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 by sending packets directly to the DHCP server. The relays cannot
are not able to insert their RAI options, and the DHCP server cannot send 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 the Access-Request queries to the RADIUS server by using just the
information from incoming packets. Kea needs to keep the information information from incoming packets. Kea needs to keep the information
received during the initial Discover/Offer exchanges and use it again 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 This mechanism is implemented based on user context in host
reservations. (See :ref:`user-context` and :ref:`user-context-hooks` for reservations. (See :ref:`user-context` and :ref:`user-context-hooks` for
details.) The host-cache mechanism allows the information retrieved by 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 queries to the RADIUS server. In other words, the host-cache mechanism
is mandatory, unless administrators do not want RADIUS communication for messages is mandatory, unless administrators do not want RADIUS communication for messages
other than Discover and the first Request from each client. 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:: .. note::
Currently the RADIUS hook library is incompatible with the 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 setting the parameter to ``true`` raises an error when the
hook library is loaded. 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 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 popular open source implementation is FreeRADIUS; here's how to
set up to enable basic functionality in Kea. set it up to enable basic functionality in Kea.
1. Install FreeRADIUS through the package manager or from the tarballs available 1. Install FreeRADIUS through the package manager or from the tarballs available
on [the freeradius.org download page](https://freeradius.org/releases/). 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, 5. If the Kea DHCP server and the RADIUS server are on different machines,
edit ``/etc/freeradius/clients.conf`` with the proper address under 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. 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 client needs to have an entry in the authorize file, which can be commonly
found at: found at:
@ -425,14 +425,14 @@ set up to enable basic functionality in Kea.
- ``/etc/freeradius/3.0/mods-config/files/authorize`` - ``/etc/freeradius/3.0/mods-config/files/authorize``
- ``/etc/freeradius/users`` (for RADIUS 2.x series) - ``/etc/freeradius/users`` (for RADIUS 2.x series)
Entries need to have the password set which needs to match the password The passwords for entries must match the passwords
configured in the configuration of the RADIUS hook library under the in the configuration of the RADIUS hook library under the
``User-Password`` attribute. Each entry can have zero, one or multiple ``User-Password`` attribute. Each entry can have zero or more
attributes. attributes.
In the following example, there are 6 entries with the password set to the In the following example, there are six entries with the password set to the
client ID, which would need to be dynamically set in the hook library's client ID, which needs to be dynamically set in the hook library's
configuration. Here's how the entries can look like: 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-IPv6-Address = "2001:db8::9",
Framed-Pool = "classroom" Framed-Pool = "classroom"
7. Accounting should work out of the box with Kea, but customizations are 7. Accounting does not need to be modified to work with Kea, but customizations are
possible in the accounting file, which can be commonly found at: possible in the accounting file, which can commonly be found at:
- ``/etc/radius-config/mods-config/files/accounting`` - ``/etc/radius-config/mods-config/files/accounting``
- ``/etc/freeradius/3.0/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 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`. lease allocation process in :iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`.
.. figure:: ../uml/radius.* .. figure:: ../uml/radius.*
@ -481,21 +481,21 @@ Parked-Packet Limit
Refer to :ref:`parked-packet-limit` for a basic introduction to packet parking. 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 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 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 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 available to the Kea DHCP server, the request is unparked, and the server
continues processing on it. continues processing it.
.. _radius-differences: .. _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 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 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 library is standalone, with its own RADIUS client implementation and its own
RADIUS dictionary. There are differences: RADIUS dictionary. There are differences:
.. list-table:: .. list-table::
@ -517,7 +517,7 @@ RADIUS dictionary. There are differences:
- Taken from the FreeRADIUS dictionary. - 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 * - 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 $ ./hammer.py build -p local -x install docs
The basic scope can be extended by mysql, pgsql, native-pkg, shell, and forge. 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:: .. 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. :ischooklib:`libdhcp_pgsql_cb.so` implements this API for PostgreSQL.
To manage the configuration information in a MySQL database, both To manage the configuration information in a MySQL database, both
:ischooklib:`libdhcp_mysql_cb.so` and :ischooklib:`libdhcp_cb_cmds.so` :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 To manage the configuration information in a PostgreSQL database, both
:ischooklib:`libdhcp_pgsql_cb.so` and :ischooklib:`libdhcp_cb_cmds.so` :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 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` 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 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 which are not specified with the command, will be marked as
"unspecified" in the database. The DHCP server uses the global "unspecified" in the database. The DHCP server uses the global
values for unspecified parameters or, if the global values are not 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 shared network, no option is deleted. In particular, the given
option may be present for a subnet belonging to the shared network. option may be present for a subnet belonging to the shared network.
Such an option instance is not affected by this command as this 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`, delete a subnet-level option, the :isccmd:`remote-option4-subnet-del`,
:isccmd:`remote-option6-subnet-del` commands must be used instead. :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 In particular, the given option may exist for a subnet containing
the specified pool. Such an option instance is not affected by this the specified pool. Such an option instance is not affected by this
command, as this command merely deletes a prefix delegation pool-level 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. :isccmd:`remote-option6-subnet-del` command must be used instead.
.. code-block:: json .. 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 In particular, the given option may exist for a subnet containing
the specified pool. Such an option instance is not affected by this the specified pool. Such an option instance is not affected by this
command, as this command merely deletes a pool-level option. To command, as this command merely deletes a pool-level option. To
delete a subnet-level option, the :isccmd:`remote-option4-subnet-del`, delete a subnet-level option, the :isccmd:`remote-option4-subnet-del`
:isccmd:`remote-option6-subnet-del` commands must be used instead. or :isccmd:`remote-option6-subnet-del` command must be used instead.
The following command attempts to delete an option having the The following command attempts to delete an option having the
option code 5 in the top-level option space from an IPv4 address 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, The returned information about each subnet is limited to the subnet identifier,
prefix, and associated shared network name. To retrieve full prefix, and associated shared network name. To retrieve full
information about the selected subnet, use information about the selected subnet, use
the :isccmd:`remote-subnet4-get-by-id`, :isccmd:`remote-subnet6-get-by-id` 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` commands. 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 The example response above contains two subnets. One of the subnets is
associated with both servers: "server1" and "server2". The second subnet 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 The structure of the subnet information is similar to the structure used
in the configuration file (see :ref:`dhcp4-configuration` and in the configuration file (see :ref:`dhcp4-configuration` and
:ref:`dhcp6-configuration`). The subnet information conveyed in the :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 must include the additional parameter
``shared-network-name``, which denotes whether the subnet belongs to a ``shared-network-name``, which denotes whether the subnet belongs to a
shared network. shared network.

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

@ -12,7 +12,8 @@ for more details.
.. note:: .. note::
:ischooklib:`libdhcp_mysql_cb.so` is part of the open source code and is :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` available to every Kea user. However, this hook library only works
which is available only to ISC customers with with :ischooklib:`libdhcp_cb_cmds.so`, which allows easy configuration
a paid support contract. For more information on subscription options, management with the use of API commands. :ischooklib:`libdhcp_cb_cmds.so`
please complete the form at https://www.isc.org/contact. 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:: .. note::
:ischooklib:`libdhcp_pgsql_cb.so` is part of the open source code and is :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` available to every Kea user. However, this hook library only works
which is available only to ISC customers with with :ischooklib:`libdhcp_cb_cmds.so`, which allows easy configuration
a paid support contract. For more information on subscription options, management with the use of API commands. :ischooklib:`libdhcp_cb_cmds.so`
please complete the form at https://www.isc.org/contact. 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 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. 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 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 :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 configuration. If an incremental update of the class is desired, it can
be achieved by doing a :isccmd:`class-get` to get the current state be achieved by issuing a :isccmd:`class-get` to get the current state
of the client class, picking the client class out of the response, modifying it 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 to the required outcome, and then issuing the ``client-update`` command with the
resulting client class attached. 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 specified. The option space is DHCPv4 or DHCPv6, depending
on the server where the hook library is loaded. 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` by either the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6`
process. It takes a mandatory ``options`` parameter with a list of process. It takes a mandatory ``options`` parameter with a list of
per-option parameter maps, with ``code``, ``name``, ``add``, ``supersede``, and 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. followed by ``.boot`` for content.
A commonly discussed use case is modifying the DHCPv4 subnet mask option 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 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 .. 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 ```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 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 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 options using complex record formats or fully qualified domain names.
For instance, if the expression evaluation returns "example.com" and 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. encoded into DNS binary format.
Since Kea 2.1.4, the ``client-class`` parameter specifies a class guard. 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 and takes a client-class name. If not empty, the client's packet needs to
belong to specified class for this entry to be used. 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 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 in ``dhcp4`` for DHCPv4 or ``dhcp6`` for DHCPv6, the location of
space where to find the option definition using its name with the new the option definition can be specified using its name, with the new
``space`` parameter. ``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, which replaces the action in the configuration of the container option,
i.e. the option where sub-options are located. i.e. the option where sub-options are located.
The ``sub-options`` entry takes a list of sub-option configuration similar The ``sub-options`` parameter takes a list of sub-option entries, each
to the option one with: containing:
- ``code`` - specifies the sub-option code, either the ``code`` or ``name`` - ``code`` - specifies the sub-option code; either the ``code`` or ``name``
must be specified. When both are given they must match or the configuration must be specified. If both are given, they must match or the configuration
is rejected at load time. is rejected at load time.
- ``name`` - specifies the sub-option name, either the ``code`` or ``name`` - ``name`` - specifies the sub-option name; either the ``code`` or ``name``
must be specified. When both are given they must match or the configuration must be specified. If both are given, they must match or the configuration
is rejected at load time. is rejected at load time.
- ``space`` - specifies the space where the sub-option can be defined. This - ``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 definition. The configuration is rejected if no valid space name is
available at load time. Note that vendor spaces are supported for the available at load time. Note that vendor spaces are supported for the
DHCPv4 ``vivso-suboptions`` and for the DHCPv6 ``vendor-opts``, both 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 - ``remove`` - (action) removes a sub-option if it already exists and the
expression evaluates to true. expression evaluates to true.
- ``container-add`` - boolean value which specifies if the container option - ``container-add`` - a boolean value that specifies whether the container option
should be created if it does not exit in the ``add`` and ``supersede`` should be created, if it does not exist in the ``add`` and ``supersede``
action. When not specified, it defaults to true. action. If not specified, it defaults to ``true``.
- ``container-remove`` - boolean value which specifies if the container option - ``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 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. 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 evaluated expression is used (false, default) or parsed using the sub-option
definition (true). definition (true).
- ``client-class`` - specifies if the sub-option entry must be skipped when - ``client-class`` - specifies whether the sub-option entry must be skipped when
the **query** does not belong to the specified client class. Note the similar 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`` parameter in the container option entry applies to the whole ``sub-options``
list. list.
For instance this configuration adds a string sub-option in the DHCPv4 For instance, this configuration adds a string sub-option in the DHCPv4
``vendor-encapsulated-options`` (code 43) option. Note this option ``vendor-encapsulated-options`` (code 43) option. This option
in last resort encapsulates the ``vendor-encapsulated-options`` space. encapsulates the ``vendor-encapsulated-options`` space.
.. code-block:: json .. 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 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` :isccmd:`lease4-get-page` and :isccmd:`lease6-get-page`
to fetch leases from its partner server (lease queries). The size of the results 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 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) Multi-Threaded Configuration (HA+MT)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
HA peer communication consists of specialized API commands sent between HA peers. It is possible to configure HA to use direct
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
multi-threaded communication between peers. We refer to this mode as HA+MT. 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 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 (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 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, the listener and client components use multi-threading to support multiple
concurrent connections between peers. By eliminating the agent and executing concurrent connections between peers. By eliminating the agent and executing
multiple command exchanges in parallel, HA throughput between peers should multiple command exchanges in parallel, HA throughput between peers
improve considerably in most situations. improves considerably over earlier versions of Kea in most situations.
The following parameters have been added to the HA configuration, to support The following parameters have been added to the HA configuration, to support
HA+MT operation: HA+MT operation:
@ -1748,11 +1740,11 @@ Parked-Packet Limit
Refer to :ref:`parked-packet-limit` for a basic introduction to packet parking. 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 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 lease, it parks the client response until the peers acknowledge the lease
update. At that point, the server will unpark the response and send it to the update. At that point, the server unparks the response and sends it to the
client. This applies to client queries which cause lease changes, such as 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 DHCPREQUEST for DHCPv4 and Request, Renew, and Rebind for DHCPv6. It does not
apply to DHPCDISCOVERs (v4) or Solicits (v6). 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. stop serving any DHCP clients, so it can be safely shut down.
The maintenance feature of the High Availability hook library addresses this The maintenance feature of the High Availability hook library addresses this
situation. The :isccmd:`ha-maintenance-start` command was introduced to allow the situation. The :isccmd:`ha-maintenance-start` command allows the
administrator to put the pairs of the active servers in a state in which one of 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. 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 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`` If the server has many relationships with different partners, the ``ha-maintenance-start``
command attempts to transition all of the relationships into the command attempts to transition all of the relationships into the
``partner-in-maintenance`` state by sending the ``ha-mainteance-notify`` to all ``partner-in-maintenance`` state by sending ``ha-maintenance-notify`` to all
partner servers. If this step fails for any server an error is returned. 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 If that happens, the ``ha-maintenance-cancel`` command can be used to resume normal
operation and fix the issue. operations and fix the issue.
Upgrading From Older HA Versions 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 The optional ``server-name`` parameter specifies the name of one of the partners in
to the HA relationship this command pertains to. This parameter can be omitted if the 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 the configuration. server receiving this command has only one HA relationship in its configuration.
.. isccmd:: ha-continue .. isccmd:: ha-continue
.. _command-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 The optional ``server-name`` parameter specifies the name of one of the partners in
to the HA relationship this command pertains to. This parameter can be omitted if the 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 the configuration. server receiving this command has only one HA relationship in its configuration.
.. isccmd:: ha-heartbeat .. isccmd:: ha-heartbeat
.. _command-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 The optional ``server-name`` parameter specifies the name of one of the partners in
to the HA relationship this command pertains to. This parameter can be omitted if the 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 the configuration. server receiving this command has only one HA relationship in its configuration.
Upon successful communication with the server, a response similar to this should Upon successful communication with the server, a response similar to this should
be returned: be returned:
@ -2238,9 +2230,9 @@ status of the backup servers.
The ``ha-maintenance-start`` Command The ``ha-maintenance-start`` Command
------------------------------------ ------------------------------------
This command is used to initiate the transition of the server's partners into 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 ``in-maintenance`` state, and the transition of the server receiving the command
into the ``partner-in-maintenance`` state in each HA relationship. See the into the ``partner-in-maintenance`` state, in each HA relationship. See the
:ref:`ha-maintenance` section for details. :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 This command is used to cancel the maintenance previously initiated using the
:isccmd:`ha-maintenance-start` command. The server receiving this command will first :isccmd:`ha-maintenance-start` command. The server receiving this command first
send :isccmd:`ha-maintenance-notify`, with the ``cancel`` flag set to ``true``, to its 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 partners. Next, the server reverts from the ``partner-in-maintenance`` state to
its previous state. See the :ref:`ha-maintenance` section for details. 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 The optional ``server-name`` parameter specifies the name of one of the partners in
to the HA relationship this command pertains to. This parameter can be omitted if the 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 the configuration. server receiving this command has only one HA relationship in its configuration.
.. warning:: .. warning::
@ -2330,9 +2322,9 @@ machine.
} }
} }
The optional ``server-name`` parameter specifies a name of one of the partners belonging The optional ``server-name`` parameter specifies the name of one of the partners in
to the HA relationship this command pertains to. This parameter can be omitted if the 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 the configuration. server receiving this command has only one HA relationship in its configuration.
It elicits the response: 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 The optional ``server-name`` parameter specifies the name of one of the partners in
to the HA relationship this command pertains to. This parameter can be omitted if the 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 the configuration. 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 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 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 Hub and Spoke Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
The hub-and-spoke is a common arrangement of the DHCP servers for resiliency. It contains A hub-and-spoke arrangement, with one central server and multiple branch servers,
one central server and multiple branch servers. The branch servers are the primary 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 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. locations. The central server acts as a standby server for each branch server.
It maintains independent state machines with the branch servers, called relationships. 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 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`` 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, 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 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 fully passive again. In rare cases, if multiple branch servers stop, the central server
takes responsibility for all their traffic (possibly the entire DHCP traffic in the network takes responsibility for all their traffic, and potentially all DHCP traffic in the entire network
when all branch servers are down). A simple hub-and-spoke arrangement consisting of two if every branch server is down. A simple hub-and-spoke arrangement consisting of two
branch servers and one central server is shown below. 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 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 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 includes all subnets of the branch servers, so that it can respond to DHCP traffic
directed to any of the failing branch servers. The subnets in the central server must be directed to any branch servers that fail. The subnets in the central server must be
grouped into relationships like in the snippet below: grouped into relationships as in the snippet below:
.. code-block:: json .. 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 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`` 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 can be any of the peer names in the relationship. For example, if a relationship contains peer names
``server1`` and ``server2``. It doesn't matter whether the ``ha-server-name`` is ``server1`` or ``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. ``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 It is not required to specify the ``ha-server-name`` in the branch servers, assuming that the
@ -2603,15 +2595,15 @@ branch ``server3``:
.. note:: .. 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 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 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 each configured subnet in the branch server guarantees that only the leases belonging to its
relationship are inserted into the branch server's database. relationship are inserted into the branch server's database.
.. note:: .. note::
The peer names in the branch servers must match the peer names in the respective central 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 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 commands supplied by this library, with the exception of
:isccmd:`reservation-get-by-hostname` and :isccmd:`reservation-get-by-address`, :isccmd:`reservation-get-by-hostname` and :isccmd:`reservation-get-by-address`,
where it is optional. Since Kea 1.9.0, where it is optional. ``subnet-id`` is also optional in
``subnet-id`` is also optional in :isccmd:`reservation-get-page`, and :isccmd:`reservation-get-page`, and it is forbidden
it is forbidden in :isccmd:`reservation-get-by-id`. in :isccmd:`reservation-get-by-id`.
Reservations can be specified globally, and are not necessarily specific to any Reservations can be specified globally, and are not necessarily specific to any
subnet. When reservations are supplied via the configuration file, the 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 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`` 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 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. server) and this entry is ignored.
The ``operation-target`` Parameter 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 the host data source. The commands may process data from the server
configuration (i.e., memory operation target), a database (database target), 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 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 :isccmd:`reservation-del`, and :isccmd:`reservation-update`) only use the
database target. database target.
The ``operation-target`` parameter accepts the following values: The ``operation-target`` parameter accepts the following values:
- ``memory`` - query or update the runtime server configuration. - ``memory`` - query or update the runtime server configuration
- ``database`` - query or update host database(s). - ``database`` - query or update host database(s)
- ``all`` - query or update both runtime configuration and 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. - ``default`` - query or update a default host data source - it is command-specific
.. isccmd:: reservation-add .. isccmd:: reservation-add
.. _command-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 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 .. 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 .. code-block:: json
@ -319,7 +319,7 @@ follows:
} }
The command accepts the ``operation-target`` argument. By default, it gets the 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 .. code-block:: json
@ -437,7 +437,7 @@ may be disruptive; use with caution. For larger deployments, please
consider using :isccmd:`reservation-get-page` instead. consider using :isccmd:`reservation-get-page` instead.
The command accepts the ``operation-target`` argument. By default, it gets the 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 .. code-block:: json
@ -575,9 +575,9 @@ page is received. Its response will look like this:
"text": "0 IPv4 host(s) found." "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 users retrieve larger host reservations lists in smaller chunks. For
small deployments with few reservations, it is easier to use small deployments with few reservations, it is easier to use
:isccmd:`reservation-get-all`. :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 :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 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 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`` parameters providing the mandatory ``ip-address`` and the optional ``subnet-id``
and ``operation-target``. and ``operation-target``.
@ -645,7 +645,7 @@ can return two IPv4 hosts:
"text": "2 IPv4 host(s) found." "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 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. 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 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::`` current implementation. Thus, searching by an IP address ``2001:db8:2:cafe::``
can return host reservations having delegated prefixes matching this search with can return host reservations with delegated prefixes of different lengths matching
different lengths. For example: ``2001:db8:2:cafe::/63``, ``2001:db8:2:cafe::/64`` etc. this search. For example: ``2001:db8:2:cafe::/63``, ``2001:db8:2:cafe::/64``, etc.
Please consider the example below: Please consider the example below:
:: ::
@ -778,7 +778,7 @@ Response:
} }
The command accepts the ``operation-target`` argument. By default, it gets the 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 .. 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 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, 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>` :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>`. :ref:`Multiple Reservations for the Same IPv6 <multiple-reservations-same-ip6>`.
That's why this command comes in handy That's why this command comes in handy
when the ``ip-reservations-unique`` boolean parameter is set to ``false``. when the ``ip-reservations-unique`` boolean parameter is set to ``false``.
Other use case of this command is having overlapping subnets and having Another use case of this command is having overlapping subnets with
the same IP address reservation (but with different identifier) in different the same IP address reservations (but with different identifiers) in different
subnets. subnets.
.. isccmd:: reservation-get-by-hostname .. 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. particularly when responses are not limited to a subnet.
The command accepts the ``operation-target`` argument. By default, it gets the 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 .. 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. particularly when responses are not limited to a subnet.
The command accepts the ``operation-target`` argument. By default, it gets the 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 .. 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 :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 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: 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 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 .. 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 .. 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 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: the cause of the failure. Here's an example of a successful update:
.. code-block:: json .. 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 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 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 :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 database. If an incremental update of the host is desired, this can be
achieved by doing a :isccmd:`reservation-get-by-id` to get the current state of the achieved by issuing 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 host, selecting the host from the response, modifying it to the required
outcome, and then issuing the :isccmd:`reservation-update` command with the resulting outcome, and then issuing the :isccmd:`reservation-update` command with the resulting
host attached. host attached.
@ -1206,7 +1206,7 @@ General Mentions
.. note:: .. 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 respond to commands that return a collection of host reservations, such as
:isccmd:`reservation-get-all`. Commands returning one host entry or dedicated host :isccmd:`reservation-get-all`. Commands returning one host entry or dedicated host
cache commands should be used instead. 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 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 :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 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` desired, then this can be achieved by issuing a :isccmd:`lease4-get` / :isccmd:`lease6-get`
command to get the current state of the lease, picking the lease out of the 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 response, modifying it to the required outcome, and then issuing the
:isccmd:`lease4-update` / :isccmd:`lease6-update` command with the resulting lease attached. :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 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 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 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 of the lease database. The extension ``.bak`` and the server PID number are added
to the previous filename. For example ``.bak14326``. to the previous filename: for example, ``.bak14326``.
.. note:: .. 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>`__ `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. 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 binding) for the address itself or a lease for a delegated prefix that
contains the address. The latter case is not supported by releases contains the address.
prior to Kea 2.3.7.
``DHCPV6_LEASEQUERY`` queries are only honored if the source address of ``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 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) 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 :ref:`store-extended-info-v6`), then an ``OPTION_LQ_RELAY_DATA`` option is
added to the reply (see added to the reply (see
`RFC 5007, Section 4.1.2.4 <https://tools.ietf.org/html/rfc5007#section-4.1.2.4>`__). `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, 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 a search for a matching delegated prefix is conducted. This is carried
out by iterating over a list of prefix lengths, in descending order, out by iterating over a list of prefix lengths in descending order,
extracting a prefix of that length from the query address and searching extracting a prefix of that length from the query address, and searching
for a delegation matching the resulting prefix. This continues for each 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. 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 By default, the list of prefix lengths to use in the search is determined
dynamically after (re)configuration events. This resulting list will dynamically after (re)configuration events. The resulting list
contain unique values of ``delegated-len`` gleaned from the currently contains unique values of ``delegated-len``, gleaned from the currently
configured set of PD pools. 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 provides the ability to explicitly configure the list rather than having
it be determined dynamically. This provides tighter control over which it be determined dynamically. This provides tighter control over which
prefix lengths are searched. In the above example, the prefix length prefix lengths are searched. In the above example, the prefix-length
search will be restricted to single pass, using a length of 72, regardless search is restricted to a single pass, using a length of 72, regardless
of whether or not there are pools using other values for ``delegated-len``. of whether there are pools using other values for ``delegated-len``.
Specifying an empty list, as shown below: Specifying an empty list, as shown below:
:: ::
@ -418,12 +417,12 @@ RFC 6926 also defines new options for Bulk Leasequery:
- query-start-time (154) - 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. contain leases that are older than this value.
- query-end-time (155) - 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. contain leases that are newer than this value.
- dhcp-state (156) - dhcp-state (156)
@ -486,13 +485,13 @@ not yet used by the hook library.
Bulk Leasequery Configuration 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: with these possible entries:
- ``bulk-query-enabled`` - ``bulk-query-enabled``
When ``true``, Kea accepts connections from IP addresses in the requesters 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`` - ``active-query-enabled``
@ -508,16 +507,16 @@ with these possible entries:
- ``lease-query-ip`` - ``lease-query-ip``
This is the IP address upon which to listen for connections. The address must be 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`` - ``lease-query-port``
This is the port upon which to listen. The default is 67 for IPv4 and 547 for IPv6, 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`` - ``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 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. threads that the Kea core is using for DHCP multi-threading.
The default is 0. The default is 0.
@ -609,10 +608,10 @@ or for DHCPv6:
Updating Existing Leases in SQL Lease Backends Updating Existing Leases in SQL Lease Backends
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Bulk Lease Query required additions to the lease data stored. With SQL lease 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 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 query do not contain the new data required. In order to populate this data,
it is necessary to run API commands: it is necessary to run these API commands:
.. isccmd:: extended-info4-upgrade .. isccmd:: extended-info4-upgrade
.. _command-extended-info4-upgrade: .. _command-extended-info4-upgrade:
@ -630,7 +629,7 @@ For DHCPv6 lease data, the command is:
.. isccmd:: extended-info6-upgrade .. isccmd:: extended-info6-upgrade
.. _command-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 In all cases, the response indicates whether it succeeded or failed
and include either the count of leases updated or the nature of the failure: 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: 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 - Bulk Leasequery was not enabled; tables are maintained only when v6 BLQ is
enabled) enabled.
- data in tables do not seem to be consistent (tables are not maintained in - 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 an atomic way, so consistency is not guaranteed. For instance, when a database
is shared between several servers races can happen between updates) is shared between several servers, races can happen between updates.
The operation of extended info command is governed by ``extended-info-checks`` 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` parameter, under the ``sanity-checks`` element. Please see :ref:`sanity-checks4`
or :ref:`sanity-checks6`. 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:: .. note::
Existing leases must have been created by Kea with ``store-extended-info`` 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. 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 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 If the High Availability hook library is enabled, the partner periodically sends lease
commands which have a similar format, the only difference is that the issuer of commands in a similar format; the only difference is that the issuer of
the command is 'HA partner' instead of 'Administrator'. 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 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 If the High Availability hook library is enabled, the partner periodically sends lease
commands which have a similar format, the only difference is that the issuer of commands in a similar format; the only difference is that the issuer of
the command is 'HA partner' instead of 'Administrator'. 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 (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 that the configuration should be valid at startup. Exiting to the operating
system allows nanny scripts to detect the problem. system allows nanny scripts to detect the problem.
If ``retry-on-startup`` is set to ``true``, the server will start reconnection If ``retry-on-startup`` is set to ``true``, the server starts reconnection
attempts even at server startup or on reconfigure events, and will honor the attempts even at server startup or on reconfigure events, and honors the
action specified in the ``on-fail`` parameter. 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:: .. note::
Database connection retries are not attempted on startup if the If :ischooklib:`libdhcp_limits.so` is loaded, database connection retries are not attempted
:ischooklib:`libdhcp_limits.so` is loaded because the hook library requires a on startup. The hook library requires a
valid connection to the database to check if JSON format is supported and to valid connection to the database to check whether JSON format is supported and to
recount class limits. recount class limits.
.. _hooks-limits-lease-limiting: .. _hooks-limits-lease-limiting:

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

@ -1,21 +1,26 @@
.. ischooklib:: libdhcp_perfmon.so .. ischooklib:: libdhcp_perfmon.so
.. _hooks-perfmon: .. _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 The Performance Monitoring (perfmon) hook library gives the Kea DHCPv4 and DHCPv6 server
to extend them with the ability to track and report performance related data. the ability to track and report performance-related data.
.. note:: .. note::
This library is experimental and not recommended for use in production This library is experimental and not recommended for use in production
environments. environments.
.. note::
:ischooklib:`libdhcp_perfmon.so` is part of the open source code and is
available to every Kea user.
Overview 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 :iscman:`kea-dhcp6` daemon by adding it to the ``hooks-libraries`` element of
the server's configuration: 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, The library tracks the lifecycle of client query packets as they are processed by Kea,
beginning with when the query was received by the kernel to when the response 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 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 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 occur during the processing of a client query. The list of possible events is
shown below: shown below:
#. socket_received - Kernel placed the client query into the socket buffer #. socket_received - kernel placed the client query into the socket buffer
#. buffer_read - Server read the client query from 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) #. 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_started - server has begun processing the query
#. process_completed - Server has constructed the response and is ready to send it #. 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 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. to add their own events. This will be detailed in future releases.
Passive Event Logging Passive Event Logging
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
As long as the PerfMon hook library is loaded it will log the packet event stack When the perfmon hook library is loaded, it logs the packet event stack
contents for each client query which generates a response packet. The log entry contents for each client query that generates a response packet. The log entry
will contain client query identifiers followed the list of event/timestamp pairs contains client query identifiers, followed by the list of event/timestamp pairs
as they occurred in the order they occurred. 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 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):: 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 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``, 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 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 will look similar to the following (see once the DHCPV6_ADVERTISE is ready to send, and looks similar to the following (see
the second entry):: 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 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 Duration Monitoring
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
When monitoring is enabled, stack event data will be aggregated over a specified interval. These 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 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: 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) * 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) * 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) * 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) * 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) * 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 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 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``. parameter ``interval-width-secs``.
The event stack for the multi-threaded mode DHCPDISCOVER/DHCPOFFER cycle shown above 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 | | 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: 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 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 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 ``composite-total_response``. This tracks the total time to respond from when the query
received until the response is ready to send. Finally, there would also be global is received until the response is ready to send. Finally, there are also global
duration updates for each of the above: duration updates for each of the above:
+--------------------------------------------------------------+--------------+ +--------------------------------------------------------------+--------------+
@ -156,20 +161,20 @@ duration updates for each of the above:
Statistics Reporting Statistics Reporting
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
When enabled (see ``stats-mgr-reporting``), PerfMon will report a duration's data When enabled, perfmon reports a duration's data each time the duration completes a
each time the duration completes a sampling interval. Each statistic employs the sampling interval (see ``stats-mgr-reporting`` under :ref:`perfmon-configuration`). Each
following naming convention: statistic employs the following naming convention:
:: ::
{subnet-id[x]}.perfmon.<query type>-<response type>.<start event>-<end event>.<value-name> {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 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 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 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 words, if during a given interval there were seven occurrences (i.e. updates) totaling
350ms, the the average-ms reported would be 50ms. Continuing with example above, the 350ms, the ``average-ms`` reported would be 50ms. Continuing with the example above, the
statistics reported would be named as follows for subnet level values: 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.process_started-process_completed.average-ms
perfmon.DHCPDISCOVER.DHCPOFFER.composite-total_response.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` The results are reported to StatsMgr, an internal Kea component that reports data as statistics
or :isccmd:`statistic-get`. that can be retrieved using statistics commands. They can be fetched using the commands
:isccmd:`statistic-get-all` or :isccmd:`statistic-get`.
Alarms Alarms
~~~~~~ ~~~~~~
Alarms may be defined to watch specific durations. Each alarm defines a high-water mark, 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 ``high-water-ms``, and a low-water mark, ``low-water-ms``. If the reported average value
for duration exceeds the high-water mark, a WARN level alarm log will be emitted at which 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 will be point the alarm is considered "triggered." Once triggered, the WARN level log is
repeated at a specified alarm report interval, ``alarm-report-secs`` as long the reported 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 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 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 Commands to enable or disable monitoring, clear or alter alarms, and fetch duration data
are anticipated but not yet supported. are anticipated but not yet supported.
.. _perfmon-configuration:
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 .. 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 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 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 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:: .. note::
@ -18,7 +23,7 @@ to a behavior available in ISC DHCP and one suggested in `RFC
Overview 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: by adding it to the ``hooks-libraries`` element of the server's configuration:
.. code-block:: javascript .. 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 When the library is loaded, :iscman:`kea-dhcp4` conducts a ping check prior to
offering a lease to client if all of the following conditions are true: 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. 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 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 can only be done if ``offer-lifetime`` is greater than zero (i.e. temporary
allocation on DHCPDISCOVER is enabled). If ``offer-lifetime`` is zero allocation on DHCPDISCOVER is enabled). If ``offer-lifetime`` is zero
ping checks are done for every DHCPOFFER as the server has no way to ping checks are done for every DHCPOFFER, as the server has no way to
know it has made prior offers. know whether prior offers were made.
b. The lease is being offered to a client other than its previous owner. 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 c. The lease is being offered to its previous owner and more than the
configurable number of seconds, ``ping-cltt-secs``, have elapsed since number of seconds specified by ``ping-cltt-secs`` have elapsed since the
CLTT of the original lease. CLTT of the original lease.
When the ping check library is loaded, in response to a DHCPDISCOVER the When the ping check library is loaded, the :iscman:`kea-dhcp4` server
:iscman:`kea-dhcp4` will: 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. construct a DHCPOFFER.
2. Park the DHCPOFFER and request a ping-check from the ping-check hook 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 library, via its ``lease4_offer`` callout. Refer to :ref:`parked-packet-limit` for
a basic introduction to packet parking. a basic introduction to packet parking.
3. The callout will test conditions described above. If they are not 3. Testing the callout conditions described above: if they are not
satisfied it will return without conducting a check, and the server satisfied, it returns without conducting a check, and the server
will send the DHCPOFFER to the client. Otherwise the callout will sends the DHCPOFFER to the client. Otherwise, the callout
initiate a ping-check for the lease address. initiates a ping check for the lease address.
4. Upon conclusion of the ping-check, the server will either send the DHCPOFFER 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 discard to the client, if the check concluded that the address is available, or discards
the DHCPFOFFER and create a DECLINED lease for the address. 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 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. minimum number to send, send an ICMP ECHO REQUEST to the lease address.
Otherwise, conclude that the address is available. 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. return to step 1.
3. Upon receipt of an ICMP ECHO REPLY, conclude that the lease is NOT available. 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 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) b. Send failure 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) c. Send failure 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 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 skip the address check and treat it as available.
available.
.. note:: .. note::
Socket buffer full of errors indicates that the OS rate limits on ICMP are "Socket buffer full" errors indicate that the OS rate limits on ICMP are
being exceeded. The server will not retry them as this would likely only being exceeded. The server does not retry them, as this would likely only
exacerbate the situation. If this occurs continuously then the client load 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 on the server may be too high to accommodate ping checking. Ping checking is
not recommended for systems with high throughput demands. not recommended for systems with high throughput demands.
Configuration Configuration
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
The ping-check hook library currently supports the following configuration parameters 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. 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: 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 .. 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 .. 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 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 through the accounting service. For details on RADIUS in Kea, please see
:ref:`radius`. :ref:`radius`.

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

@ -90,7 +90,7 @@ Role Configuration
.. note:: .. 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 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 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. 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 :ischooklib:`libdhcp_run_script.so` is part of the open source code and is
available to every Kea user. available to every Kea user.
The library, which was added in Kea 1.9.5, can be loaded in a .. note::
similar way to other hook libraries by the :iscman:`kea-dhcp4` and
:iscman:`kea-dhcp6` processes. This library can only be loaded by the :iscman:`kea-dhcp4` or
:iscman:`kea-dhcp6` process.
.. code-block:: json .. 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 As of Kea 2.6.0, Kea no longer automatically generates subnet IDS; they must
specified, Kea will try to assign the next ``subnet-id`` value. This 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 automatic ID value generator is simple; it returns the previous
automatically assigned value, increased by 1. This works well, unless automatically assigned value, increased by 1. This works well, unless
a subnet is manually created with a larger value than one previously used. For 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 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 :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 ``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 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 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 auto-generated as 3. However, since there is already a subnet with that
ID, the process will fail. 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 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 :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 server configuration. If an incremental update of the subnet is desired,
this can be achieved with :isccmd:`subnet4-delta-add`. use :isccmd:`subnet4-delta-add`.
.. isccmd:: subnet6-update .. isccmd:: subnet6-update
.. _command-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 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 :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 server configuration. If an incremental update of the subnet is desired,
this can be achieved with :isccmd:`subnet6-delta-add`. use :isccmd:`subnet6-delta-add`.
.. isccmd:: subnet4-del .. isccmd:: subnet4-del
.. _command-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: 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 There is one case where this is not true: if Kea is running with a
configuration that contains a ``hooks-libraries`` item, and that configuration that contains a ``hooks-libraries`` item, and that
item is removed and the configuration reloaded, the removal will item is removed and the configuration reloaded, the removal is
be ignored and the libraries remain loaded. As a workaround, ignored and the libraries remain loaded. As a workaround,
instead of removing the ``hooks-libraries`` item, change it to an instead of removing the ``hooks-libraries`` item, change it to an
empty list. empty list.
@ -257,13 +257,13 @@ Order of Configuration:
It is important to recognize that the order in which hook libraries are It is important to recognize that the order in which hook libraries are
configured determines the order in which their callouts will be executed, configured determines the order in which their callouts will be executed,
in cases where more than one hook library implements the same callout. For 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 example, to use the Flexible Identifier (also called Flex ID) hook library to formulate the client
IDs in conjunction with HA hook library for load-balanced HA, it is essential 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 your server's ``hooks-libraries`` 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 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 before the HA library uses it for load-balancing. Similarly, it is best to
specify forensic logging last, to ensure any other install hooks have made specify the Forensic Logging library last, to ensure that any other installed hooks have already made
their contributions to the packet processing. their contributions to the packet processing before that one is loaded.
.. _user-context-hooks: .. _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 Some hooks use user context for a configuration that can be easily edited
without the need to restart the server. 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 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 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 the packet." When work is ready to continue, the server unparks the response
and continue processing. and continues processing.
There is a global parameter, ``parked-packet-limit``, that may be used to limit 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 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. parking spaces are available.
In general, smaller values for the parking lot limit are likely to cause more 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 fewer drops but with longer response times. Currently, the default value for
``parked-packet-limit`` is 256. ``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 recommend users initially leave it at the default value of 256 and observe
how the system behaves over time with varying load conditions. 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. It lowers the number of concurrently parked packets to 128.
.. code-block:: json .. code-block:: json
@ -446,9 +446,9 @@ libraries, discussed in the following sections.
.. note:: .. note::
Some of these libraries are available with the base code, while others are Some of these libraries are available at no cost with the open source base code; others are
premium libraries available for purchase, or only shared with organizations premium libraries available for standalone purchase, while some are only available to organizations
who contribute to Kea's development through paid ISC support contracts. Paid support that contribute to Kea's development through paid ISC support contracts. Paid support
includes professional engineering assistance, advance security notifications, input includes professional engineering assistance, advance security notifications, input
into ISC's roadmap planning, and many other benefits, while helping into ISC's roadmap planning, and many other benefits, while helping
keep Kea sustainable in the long term. ISC encourages companies and organizations 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 | | | | a repository for the Kea configuration information. Kea |
| | | servers use this library to fetch their configurations. | | | | servers use this library to fetch their configurations. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+ +-----------------------------------------------------------+--------------+--------------------------------------------------------------+
| :ref:`PerfMon <hooks-perfmon>` | Kea open | With this hook library, :iscman:`kea-dhcp4` server and | | :ref:`PerfMon <hooks-perfmon>` | Kea open | With this hook library, :iscman:`kea-dhcp4` and |
| | source | :iscman:`kea-dhcp6` servers can track and report performance | | CURRENTLY EXPERIMENTAL | source | :iscman:`kea-dhcp6` servers can track and report performance |
| | | data. CURRENTLY UNDER DEVELOPMENT | | | | data. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+ +-----------------------------------------------------------+--------------+--------------------------------------------------------------+
| :ref:`Ping Check <hooks-ping-check>` | ISC support | With this hook library, :iscman:`kea-dhcp4` server can | | :ref:`Ping Check <hooks-ping-check>` | ISC support | With this hook library, the :iscman:`kea-dhcp4` server can |
| | customers | perform ping checks of candidate lease addresses before | | | source | perform ping checks of candidate lease addresses before |
| | | offering them to clients. | | | customers | offering them to clients. |
+-----------------------------------------------------------+--------------+--------------------------------------------------------------+ +-----------------------------------------------------------+--------------+--------------------------------------------------------------+
| :ref:`PostgreSQL Configuration Backend <hooks-cb-pgsql>` | Kea open | This hook library is an implementation of the Kea | | :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 | | | source | Configuration Backend for PostgreSQL. It uses a PostgreSQL |

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

@ -7,23 +7,23 @@ Installation
Packages Packages
======== ========
ISC publishes native RPM, deb, and APK packages, along with the tarballs ISC publishes native RPM, deb, and APK packages, as well as tarballs
with the source code. The packages are available on with the source code. The packages are available in
`Cloudsmith <https://cloudsmith.io/~isc/repos/>`_ at `ISC's Cloudsmith repositories <https://cloudsmith.io/~isc/repos>`_.
https://cloudsmith.io/~isc/repos. The native packages can be downloaded The native packages can be downloaded
and installed using the system available in a specific distribution (such 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, as dpkg or rpm). The Kea repository can also be added to the system,
making it easier to install updates. For details, please making it easier to install updates. For details, please
go to https://cloudsmith.io/~isc/repos, choose the repository of go to https://cloudsmith.io/~isc/repos, choose the desired Kea version,
interest, and then click the ``Set Me Up`` button. For detailed 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>`_. instructions, please refer to this `Knowledgebase article <https://kb.isc.org/docs/isc-kea-packages>`_.
Installation From Cloudsmith Packages Installation From Cloudsmith Packages
------------------------------------- -------------------------------------
ISC provides Kea packages for Alpine, Debian, Fedora, RHEL, and Ubuntu. ISC provides Kea packages for Alpine, Debian, Fedora, RHEL, and Ubuntu.
The recommended method for installing Kea on any of these systems, from the The recommended method for installing Kea on any of these systems is to
Cloudsmith repository for Kea release 2.3.1 or later, is to install the ``isc-kea`` install the ``isc-kea`` metapackage from the Cloudsmith repository.
metapackage. This metapackage is included on all supported distros and This metapackage is included on all supported distros and
installs all of the services offered by the Kea software suite. installs all of the services offered by the Kea software suite.
Specific Kea components 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 - ``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 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 Once installed, the services can be managed through the distribution's
service manager. The services are named: :iscman:`kea-dhcp4`, :iscman:`kea-dhcp6`, service manager. The services are named: :iscman:`kea-dhcp4`, :iscman:`kea-dhcp6`,
:iscman:`kea-dhcp-ddns`, and :iscman:`kea-ctrl-agent`. :iscman:`kea-dhcp-ddns`, and :iscman:`kea-ctrl-agent`.
.. note:: .. note::
The real service names on Debian and Ubuntu follow the names of the older The real service names on Debian and Ubuntu use slightly different
packages, to maintain compatibility with pre-existing scripts. A package names, to maintain compatibility with some older scripts. A
systemd service alias is used to allow users to refer to them with shorter systemd service alias is used to allow users to refer to them with shorter
names. Calling ``systemctl enable`` on these services requires names. Calling ``systemctl enable`` on these services requires
the real service names, which are: ``isc-kea-dhcp4-server``, 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 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``. 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 Once this upgrade has been completed, it is possible to upgrade to later versions
normally using ``apt upgrade`` on Debian and Ubuntu systems. 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 ``apt install isc-kea`` after upgrading, which
will install all of the relevant subpackages that make up Kea. will install all of the relevant subpackages that make up Kea.
This upgrade path issue does not apply to RPM and Alpine systems; however, This upgrade path issue does not apply to RPM and Alpine systems.
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 Customers with ISC support contracts who experience difficulties with upgrading
are encouraged to describe their situation on the kea-users mailing list for are invited to open a ticket in their support queue. Other users
best-effort support from other list members. 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: .. _install-hierarchy:
@ -169,7 +171,7 @@ the system:
or on a machine reachable over a network is required. Note that running or on a machine reachable over a network is required. Note that running
the unit tests requires a local PostgreSQL server. 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 datastore. Earlier versions are no longer supported. When compiling from
sources, the configure switches that can be used are ``--with-libyang`` and sources, the configure switches that can be used are ``--with-libyang`` and
``--with-sysrepo`` without any parameters. If these dependencies were ``--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 - 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 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. dependencies were installed in custom paths, point the switch to them.
- googletest (version 1.8 or later) is required when using the ``--with-gtest`` - 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 The code checked out from the git repository does not include the
generated configure script or the Makefile.in files, nor their related build generated configure script or the Makefile.in files, nor their related build
files. They can be created by running ``autoreconf`` with the files. Those can be created by running ``autoreconf`` with the
``--install`` switch. This will run ``autoconf``, ``aclocal``, ``--install`` switch, which will run ``autoconf``, ``aclocal``,
``libtoolize``, ``autoheader``, ``automake``, and related commands. ``libtoolize``, ``autoheader``, ``automake``, and related commands.
Write access to the Kea repository is only granted to ISC staff. 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. found, Kea searches for OpenSSL. Normally this is not necessary.
- ``--enable-shell`` - ``--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. The default is to not build it.
- ``--with-site-packages`` - ``--with-site-packages``
Only useful when :iscman:`kea-shell` is enabled, this switch causes the kea-shell Install the kea-shell Python packages in the specified directory; this
Python packages to be installed in the specified directory. This is is only useful when :iscman:`kea-shell` is enabled, and is
mostly useful for Debian-related distributions. While most systems store mostly helpful for Debian-related distributions. While most systems store
Python packages in ``${prefix}/usr/lib/pythonX/site-packages``, Debian Python packages in ``${prefix}/usr/lib/pythonX/site-packages``, Debian
introduced a separate directory for packages installed from DEB. Such introduced a separate directory for packages installed from DEB. Such
Python packages are expected to be installed in 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 When ``configure`` succeeds, it displays a report with the parameters used
to build the code. This report is saved into the file ``config.report`` 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 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 It is outside of the scope of common administrator operations and requires
some developer skills, but the Developer Guide explains how to do that 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 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>`__. <https://reports.kea.isc.org/dev_guide/de/d9a/crossCompile.html>`__.
.. _dhcp-install-configure: .. _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 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 in a way that makes it possible to choose which database product should
be used to store the lease information. Kea supports three 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 dependencies, MySQL and PostgreSQL support are disabled by default and only
memfile is available. Support for the optional external database backend must memfile is available. Support for the optional external database backend must
be explicitly included when Kea is built. be explicitly included when Kea is built.
@ -558,8 +560,8 @@ If using systemd, modify its service file
User=admin User=admin
Group=admin Group=admin
The most important step is to set the capabilities of the binaries. Refer to `man capabilities` to get The most important step is to set the capabilities of the binaries. Refer to the operating system man page
more information. for `capabilities` for more information.
.. code-block:: console .. code-block:: console
@ -614,7 +616,7 @@ Deprecated Features
=================== ===================
This section lists significant features that have been or will be removed. We try to 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. to current users to plan a migration. New users should not rely on deprecated features.
Sysrepo 0.x or 1.x 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, Kea 2.3.2 introduced support for Sysrepo 2.x. Unfortunately,
Sysrepo continues to undergo major changes that are backward-incompatible, 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 :isccmd:`libreload` command
---------------------------------------- ----------------------------------------
The :isccmd:`libreload` command was deprecated in Kea 2.3.4. The code to handle this command is 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. 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. 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 first entry (:iscman:`kea-dhcp4`). Messages generated by the ``dhcpsrv`` library
are logged according to the configuration set by the second entry. 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 "Software Package" column of this table specifies whether the particular
loggers belong to the core Kea code (open source Kea binaries and loggers belong to the core Kea code (open source Kea binaries and
libraries), or hook libraries (open source or premium). 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 | | ``kea-ctrl-agent.auth`` | core | A logger which covers |
| | | access control details, such as| | | | access control details, such as|
| | | a result of the basic HTTP | | | | the result of basic HTTP |
| | | authentication. | | | | authentication. |
+----------------------------------+---------------------------------------+--------------------------------+ +----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.ctrl-agent`` | core | Used to log results of | | ``kea-ctrl-agent.ctrl-agent`` | core | Used to log results of |
| | | configuration checks, | | | | configuration checks, |
| | | information about services | | | | information about services |
| | | starting or failing to start, | | | | starting or failing to start, |
| | | command receival and | | | | command reception, and |
| | | forwarding. | | | | forwarding. |
+----------------------------------+---------------------------------------+--------------------------------+ +----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.http`` | core | A logger which | | ``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-ctrl-agent.callouts``, | core | Used to log messages |
| ``kea-dhcp4.callouts``, | | pertaining to the | | ``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 | | ``kea-dhcp-ddns.callouts`` | | execution for a particular |
| | | hook point. | | | | hook point. |
+----------------------------------+---------------------------------------+--------------------------------+ +----------------------------------+---------------------------------------+--------------------------------+
@ -242,7 +242,7 @@ libraries), or hook libraries (open source or premium).
+----------------------------------+---------------------------------------+--------------------------------+ +----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.database``, | core | Used to log messages | | ``kea-dhcp4.database``, | core | Used to log messages |
| ``kea-dhcp6.database`` | | relating to general | | ``kea-dhcp6.database`` | | relating to general |
| | | operations on the | | | | operations of the |
| | | relational databases. | | | | relational databases. |
+----------------------------------+---------------------------------------+--------------------------------+ +----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.ddns-tuning-hooks``, | :ischooklib:`libdhcp_ddns_tuning.so` | Used to log messages related | | ``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. | | | | library. |
+----------------------------------+---------------------------------------+--------------------------------+ +----------------------------------+---------------------------------------+--------------------------------+
| ``kea-ctrl-agent.hooks``, | core | Used to log messages related | | ``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-dhcp6.hooks``, | | libraries, e.g. |
| ``kea-dhcp-ddns.hooks`` | | registatin and | | ``kea-dhcp-ddns.hooks`` | | registration and |
| | | deregistration of the | | | | deregistration of the |
| | | libraries, and to the | | | | libraries, and to the |
| | | initialization of the | | | | initialization of the |
@ -322,7 +322,7 @@ libraries), or hook libraries (open source or premium).
| | | by the library. | | | | by the library. |
+----------------------------------+---------------------------------------+--------------------------------+ +----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.hosts``, | core | Used within | | ``kea-dhcp4.hosts``, | core | Used within |
| ``kea-dhcp6.hosts`` | | ``libdhcpsrv``, it logs | | ``kea-dhcp6.hosts`` | | ``libdhcpsrv`` to log |
| | | messages related to | | | | messages related to |
| | | the management of | | | | the management of |
| | | DHCP host | | | | DHCP host |
@ -399,7 +399,7 @@ libraries), or hook libraries (open source or premium).
| ``kea-dhcp4.packets``, | core | Mostly | | ``kea-dhcp4.packets``, | core | Mostly |
| ``kea-dhcp6.packets`` | | used to log messages | | ``kea-dhcp6.packets`` | | used to log messages |
| | | related to | | | | related to |
| | | transmission of the | | | | transmission of |
| | | DHCP packets, i.e. | | | | DHCP packets, i.e. |
| | | packet reception and | | | | packet reception and |
| | | the sending of a | | | | the sending of a |
@ -428,12 +428,14 @@ libraries), or hook libraries (open source or premium).
| | | the packet is parsed. | | | | the packet is parsed. |
+----------------------------------+---------------------------------------+--------------------------------+ +----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.perfmon-hooks``, | :ischooklib:`libdhcp_perfmon.so` | Used to log messages related | | ``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 | | ``kea-dhcp4.ping-check-hooks`` | :ischooklib:`libdhcp_ping_check.so` | Used |
| | subscription hook library | to log messages related to | | | subscription hook library | to log messages related to |
| | | carrying out pre-offer ping | | | | the operation of the Ping |
| | | checks of candidate leases. | | | | Check hook library. |
+----------------------------------+---------------------------------------+--------------------------------+ +----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.pgsql-cb-hooks``, | :ischooklib:`libdhcp_pgsql_cb.so` | Used | | ``kea-dhcp4.pgsql-cb-hooks``, | :ischooklib:`libdhcp_pgsql_cb.so` | Used |
| ``kea-dhcp6.pgsql-cb-hooks`` | open-source hook library | to log messages | | ``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-dhcp6.tcp`` | | to TCP traffic. |
+----------------------------------+---------------------------------------+--------------------------------+ +----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp4.user_chk``, | :ischooklib:`libdhcp_user_chk.so` | Used to log messages related | | ``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. | | | | User Check hook library. |
+----------------------------------+---------------------------------------+--------------------------------+ +----------------------------------+---------------------------------------+--------------------------------+
| ``kea-dhcp-ddns`` | core | The root logger for | | ``kea-dhcp-ddns`` | core | The root logger for |
@ -497,7 +499,7 @@ libraries), or hook libraries (open source or premium).
| | | more specialized | | | | more specialized |
| | | loggers. | | | | 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, | | ``kea-dhcp-ddns.dctl`` | | about the process, |
| | | received signals, and | | | | received signals, and |
| | | triggered | | | | triggered |
@ -623,13 +625,13 @@ where log messages are sent and are explained in detail below.
.. note:: .. note::
As of Kea 2.5.1, alias ``output-options`` was added that can be used The alias ``output-options`` was added in Kea 2.5.1, to be used
interchangeably with previous ``output_options`` configuration key. interchangeably with the previous ``output_options`` configuration key.
The reason behind this was to keep all configuration keys consistent i.e. This was done to keep all configuration keys consistent, i.e.
to use "dash" instead of "underscore" in the key name. For the time being 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. 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. and ``output_options`` can be used as an alias.
The ``output`` (string) Option The ``output`` (string) Option
@ -647,7 +649,7 @@ The ``flush`` (boolean) Option
This flushes the buffers after each log message. Doing this reduces performance This flushes the buffers after each log message. Doing this reduces performance
but ensures that if the program terminates abnormally, all messages 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 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 | | ``%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 | | ``%p`` | Outputs log severity e.g., INFO |
+-----------+------------------------------------------------------------------------+ +-----------+------------------------------------------------------------------------+
| ``%r`` | Outputs milliseconds since program start e.g., 1235 | | ``%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 | | ``%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 | | ``%%`` | 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 % 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`` - ``%20p``
Left pads with spaces (align right) if the severity is shorter than 20 characters. 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. 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. 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 Supported parameters depend on the liblog4cplus version used to compile Kea, which can
be checked by executing ``kea-dhcp4 -W | grep -i log4cplus`` which will produce output be checked by executing ``kea-dhcp4 -W | grep -i log4cplus``. This produces a result
like this: ``LOG4CPLUS_VERSION: 2.0.5``. Consult the documentation in the such as: ``LOG4CPLUS_VERSION: 2.0.5``. Consult the documentation in the
`log4cplus wiki <https://github.com/log4cplus/log4cplus/wiki>`__ for further information `log4cplus wiki <https://github.com/log4cplus/log4cplus/wiki>`__ for further information
about the version you have installed. about the installed version.
Example Logger Configurations 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 default values, although it is possible to modify some aspects of the
settings by means of environment variables. In the absence of settings by means of environment variables. In the absence of
any logging configuration in the configuration file, the settings of the 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. is running.
The following environment variables can be used to control the behavior 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. :ref:`build-requirements` for details.
2. Download the Kea source tarball from 2. Download the Kea source tarball from
`the ISC.org downloads page <https://www.isc.org/download/>`__ 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 downloads site <https://downloads.isc.org/isc/kea/>`__, or
`the ISC Cloudsmith page <https://cloudsmith.io/~isc/packages/?q=format%3Araw>`__. `the ISC Cloudsmith page <https://cloudsmith.io/~isc/packages/?q=format%3Araw>`__.
3. Extract the tarball. For example: 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 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. easier to install Kea using native packages.
1. Go to `Kea on cloudsmith.io <https://cloudsmith.io/~isc/repos/>`__. 1. Go to `Kea on cloudsmith.io <https://cloudsmith.io/~isc/repos/>`__.
2. Choose the Cloudsmith repository e.g. |cloudsmith_repo| for Kea |version|. 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 3. Click on the arrow beside the "Set Me Up" button and select the desired OS flavor:
out of: ``Alpine``, ``Debian``, ``RedHat``. Alpine, Debian, or RedHat.
4. Follow the instructions written there. 4. Follow the onscreen instructions.
.. note:: .. note::
For example, the Debian setup instructions for Kea 2.4 can be found here: 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 $ 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): symbols, and premium hooks (if available):
.. list-table:: .. 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 # 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 .. 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 :iscman:`keactrl` is not available in packages, as similar functionality is provided
by the native systemctl scripts. 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 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: With systemd on Fedora/RedHat:
@ -253,7 +253,7 @@ or all packages with a specified version number:
Quick Start Guide Using Docker Containers 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 2. Create an ipvlan network attached to the client-facing host interface and
assigned to the subnet that is served by Kea. 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 $ docker pull docker.cloudsmith.io/isc/docker/kea-dhcp6
4. Create a container from the image. Mount the configuration volume and the
4. Create a container out of the image. Mount the configuration volume and the
data volume if needed. data volume if needed.
.. code-block:: console .. 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 1. Edit the Kea configuration files, which by default are installed in
the ``[kea-install-dir]/etc/kea/`` directory. These are: the ``[kea-install-dir]/etc/kea/`` directory. These are:
``kea-dhcp4.conf``, ``kea-dhcp6.conf``, ``kea-dhcp-ddns.conf`` and ``kea-dhcp4.conf``, ``kea-dhcp6.conf``, ``kea-dhcp-ddns.conf`` and
``kea-ctrl-agent.conf``, ``keactrl.conf`` for DHCPv4 server, DHCPv6 server, ``kea-ctrl-agent.conf``, ``keactrl.conf`` for the DHCPv4 server, DHCPv6 server,
D2, Control Agent, and the keactrl script, respectively. D2, Control Agent, and keactrl script, respectively.
2. To start the DHCPv4 server in the background, run the 2. To start the DHCPv4 server in the background, run the
following command (as root): 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:: .. 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 The Kea shell is intended to serve more as a demonstration of the
RESTful interface's capabilities (and, perhaps, an illustration for RESTful interface's capabilities (and, perhaps, an illustration for
@ -146,7 +146,7 @@ tool.
TLS Support 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: support requires Python 3. The additional command-line arguments are:
- ``--ca`` specifies the file or directory name of the Certification - ``--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 64-bit integer (int64_t in C++), so it can hold any value between
-2^63 to 2^63-1. -2^63 to 2^63-1.
- *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 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. 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.) for the Cassandra backend has been deprecated.)
The first line of the file contains the column names. This can be used 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. 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 portable form of the lease data. There are other mandatory arguments
that must be used together with this command. Either ``-4`` or ``-6`` must that must be used together with this command: either ``-4`` or ``-6`` must
be specified. Also ``-o`` or ``--output`` must be provided. be specified, and either ``-o`` or ``--output`` must be provided.
``lease-upload`` ``lease-upload``
Uploads leases from a CSV (comma-separated values) text file to a MySQL or 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. 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 There are other mandatory arguments that must be used together with this
command. Either ``-4`` or ``-6`` must be specified. command: either ``-4`` or ``-6`` must be specified,
Also ``-i`` or ``--input`` must be provided. and either ``-i`` or ``--input`` must be provided.
``stats-recount`` ``stats-recount``
Recounts lease statistics for a MySQL or PostgreSQL database. Recounts lease statistics for a MySQL or PostgreSQL database.
@ -79,8 +79,8 @@ Arguments
The default value is ``localhost``. The default value is ``localhost``.
``-i|--input input_file`` ``-i|--input input_file``
Specifies the CSV (comma-separated values) text file with leases to be uploaded. Specifies the CSV (comma-separated values) text file with the leases to be uploaded;
Required for ``lease-upload``. required for ``lease-upload``.
``-P|--port port`` ``-P|--port port``
Specifies the port when connecting to a database. If not specified, 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`` ``-o code,hexstring``
Forces ``perfdhcp`` to insert the specified extra option (or options if Forces ``perfdhcp`` to insert the specified extra option (or options if
used several times) into packets being transmitted. The code used multiple times) into packets being transmitted. The code
specifies the option code and the hexstring is a hexadecimal string that specifies the option code, and the hexstring is a hexadecimal string that
defines the content of the option. Care should be taken as ``perfdhcp`` 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 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 inserted into packets and sent as is. Be careful not to duplicate
options that are already inserted. For example, to insert client options that are already inserted. For example, to insert the
class identifier (option code 60) with a string "docsis", use client-class identifier (option code 60) with the string "docsis", use
"-o 60,646f63736973". The ``-o`` may be used multiple times. It is ``-o 60,646f63736973``. The ``-o`` may be used multiple times. The protocol
necessary to specify the protocol family (either ``-4`` or ``-6``) before family (``-4`` or ``-6``) must be specified before using ``-o``.
using ``-o``.
``-P preload`` ``-P preload``
Initiates preload exchanges back-to-back at startup. Must be 0 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. traffic passing through a single relay agent.
``--or encapsulation-level:code,hexstring`` ``--or encapsulation-level:code,hexstring``
This option is very similar to ``-o``, only that it forces ``perfdhcp`` Forces ``perfdhcp`` to insert the specified extra option (or options if
to insert the specified extra option (or options if used several times) used multiple times) into a relayed DHCPv6 message at the given level of
into relayed DHCPv6 message at given level of encapsulation (currently encapsulation; currently, the only supported encapsulation-level value is 1.
the only supported encapsulation-level value is 1). The code This option is very similar to ``-o``: the code
specifies the option code and the hexstring is a hexadecimal string that specifies the option code, and the hexstring is a hexadecimal string that
defines the content of the option. Care should be taken as ``perfdhcp`` 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 does not offer any kind of logic behind the options; they are simply
inserted into packets and sent as is. Please notice that ``encapsulation-level:`` inserted into packets and sent as is. ``encapsulation-level:``
is optional and if omitted, default encapsulation-level value 1 is used. is optional; if it is omitted, the default encapsulation-level value 1 is used.
For example, to insert Subscriber identifier (option code 38) with a For example, to insert the Subscriber identifier (option code 38) with a
value 1234 at first level of encapsulation, use ``--or 38,31323334`` value 1234 at the first level of encapsulation, use ``--or 38,31323334``
or ``--or 1:38,31323334``. The ``--or`` may be used multiple times. or ``--or 1:38,31323334``. The ``--or`` may be used multiple times, and
It must be used together with ``-A``. it must be used in conjunction with ``-A``.
Template-Related Options Template-Related Options
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~