mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-02 06:55:16 +00:00
Code Issues Releases Wiki Activity

[#2554] add 'ischooklib' anchors and references

Browse Source
This commit is contained in:
Andrei Pavel
2023-06-06 13:30:39 +03:00
parent a51ab99885
commit aaa3a91b9b
28 changed files with 143 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -188,7 +188,7 @@ and the result is interpreted as a class. For example, modern cable
modems send this option with value ``docsis3.0``, so the packet belongs to
class ``VENDOR_CLASS_docsis3.0``.
The ``HA_`` prefix is used by the High Availability hook library to
The ``HA_`` prefix is used by :ischooklib:`libdhcp_ha.so` to
designate certain servers to process DHCP packets as a result of load
balancing. The class name is constructed by prepending the ``HA_`` prefix
to the name of the server which should process the DHCP packet. This
@@ -202,7 +202,7 @@ names at runtime. The spawned class name is constructed by prepending the
``SPAWN_<template-class-name>_<evaluated-value>``.
More details can be found in :ref:`classification-configuring`.
The ``BOOTP`` class is used by the BOOTP hook library to classify and
The ``BOOTP`` class is used by :ischooklib:`libdhcp_bootp.so` to classify and
respond to inbound BOOTP queries.
The ``SKIP_DDNS`` class is used by the DDNS-tuning hook library to suppress

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

@@ -13,11 +13,11 @@ to manage and fetch their configuration from one or more databases. In
this documentation, the term "Configuration Backend" may also refer to
the particular Kea module providing support to manage and fetch the
configuration information from the particular database type. For
example, the MySQL Configuration Backend is the logic implemented within the
``mysql_cb`` hook library, which provides a complete set of functions to
example, the MySQL Configuration Backend is the logic implemented within
:ischooklib:`libdhcp_mysql_cb.so`, which provides a complete set of functions to
manage and fetch the configuration information from the MySQL database.
The PostgreSQL Configuration Backend is the logic implemented within the
``pgsql_cb`` hook library, which provides a complete set of functions to
The PostgreSQL Configuration Backend is the logic implemented within
:ischooklib:`libdhcp_pgsql_cb.so`, which provides a complete set of functions to
manage and fetch the configuration information from the PostgreSQL database.
From herein, the term "database" is used to refer to either a MySQL or
PostgreSQL database.
@@ -85,7 +85,7 @@ Currently, the Kea CB has the following limitations:
Kea CB stores data in a schema that is public. It is possible to
insert configuration data into the tables manually or automatically
using SQL scripts, but this requires SQL and schema knowledge.
The supported method for managing the data is through the ``cb-cmds`` hook library,
The supported method for managing the data is through :ischooklib:`libdhcp_cb_cmds.so`,
which provides management commands for config backends. It simplifies many
typical operations, such as listing, adding, retrieving, and deleting global
parameters, shared networks, subnets, pools, options, option definitions, and
@@ -95,7 +95,7 @@ Appendix A of this manual for a complete list.
.. note::
The ``cb_cmds`` hook library is available only to ISC support subscribers.
:ischooklib:`libdhcp_cb_cmds.so` is available only to ISC support subscribers.
For more information on subscription options, please complete the form
at https://www.isc.org/contact.
@@ -132,11 +132,11 @@ in two independent configuration sources.
.. note::
It is recommended that the ``subnet_cmds`` hook library not be used to
It is recommended that :ischooklib:`libsubnet_cmds.so` not be used to
manage subnets when the configuration backend is used as a source
of information about the subnets. The ``subnet_cmds`` hook library
of information about the subnets. :ischooklib:`libsubnet_cmds.so`
modifies the local subnets configuration in the server's memory,
not in the database. Use the ``cb_cmds`` hook library to manage the
not in the database. Use :ischooklib:`libcb_cmds.so` to manage the
subnets information in the database instead.
.. note::
@@ -162,13 +162,13 @@ in two independent configuration sources.
CB Components
-------------
To use a MySQL configuration backend you must compile the ``mysql_cb`` open
source hook library and configure the DHCP servers to load it. It is compiled when
the ``--with-mysql`` configuration switch is used during the Kea build. The MySQL
C client libraries must be installed, as explained in :ref:`dhcp-install-configure`.
To use a MySQL configuration backend you must compile
:ischooklib:`libdhcp_mysql_cb.so` and configure the DHCP servers to load it.
It is compiled when the ``--with-mysql`` configuration switch is used during the Kea build.
The MySQL C client libraries must be installed, as explained in :ref:`dhcp-install-configure`.
To use a PostgreSQL configuration backend you must compile the ``pgsql_cb`` open
source hook library and configure the DHCP servers to load it. It is compiled when
To use a PostgreSQL configuration backend you must compile :ischooklib:`libdhcp_pgsql_cb.so`
and configure the DHCP servers to load it. It is compiled when
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`.
@@ -178,18 +178,15 @@ C client libraries must be installed, as explained in :ref:`dhcp-install-configu
required by the particular Kea version using the :iscman:`kea-admin` tool,
as described in :ref:`kea-admin`.
The ``cb_cmds`` premium hook library, which is available to ISC's paid support
:ischooklib:`libdhcp_cb_cmds.so`, which is available to ISC's paid support
customers, provides a complete set of commands to manage the
servers' configuration information within the database. This library can
be attached to both DHCPv4 and DHCPv6 server instances. While it is
possible to manage the configuration information without the ``cb_cmds``
hook library with commonly available tools, such as MySQL Workbench or
possible to manage the configuration information without :ischooklib:`libdhcp_cb_cmds.so`
with commonly available tools, such as MySQL Workbench or
the command-line MySQL client, or by directly working with the database;
these avenues are neither recommended nor supported.
Refer to :ref:`hooks-cb-cmds` for the details regarding the
``cb_cmds`` hook library.
The DHCPv4 and DHCPv6 server-specific configurations of the CB, as well as
the list of supported configuration parameters, can be found in
:ref:`dhcp4-cb` and :ref:`dhcp6-cb`, respectively.
@@ -266,8 +263,8 @@ that any particular subnet may have only one definition within this
network. Each subnet has two unique identifiers: the subnet identifier and the
subnet prefix. The subnet identifier is used in Kea to uniquely
identify the subnet within the network and to connect it with other configuration elements,
e.g. in host reservations. Some commands provided by the
``cb_cmds`` hook library allow the subnet
e.g. in host reservations. Some commands provided by
:ischooklib:`libdhcp_cb_cmds.so` allow the subnet
information to be accessed by either subnet identifier or prefix, and explicitly prohibit
using the server tag to access the subnet. This is because, in
general, the subnet definition is associated with multiple servers

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

@@ -273,7 +273,7 @@ as a single entry (JSON map) as follows:
These types of errors are possible on systems configured for either basic
authentication or agents that load the RBAC hook library.
authentication or agents that load :ischooklib:`libca_rbac.so`.
.. _ctrl-channel-client:

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

@@ -2179,7 +2179,7 @@ to be configured with those options.
+--------------------+------+----------------------------------------------------------------------+
All other RAI sub-options can be used in client classification to classify incoming packets to specific classes
and/or by ``flex-id`` to construct a unique device identifier.
and/or by :ischooklib:`libdhcp_flex_id.so` to construct a unique device identifier.
.. _dhcp4-custom-options:
@@ -5727,7 +5727,7 @@ reservations for the same IP address within a particular subnet, to avoid
having two different clients compete for the same address.
When using the default settings, the server returns a configuration error
when it finds two or more reservations for the same IP address within
a subnet in the Kea configuration file. The :ref:`hooks-host-cmds` hook
a subnet in the Kea configuration file. :ischooklib:`libdhcp_host_cmds.so`
returns an error in response to the :isccmd:`reservation-add` command
when it detects that the reservation exists in the database for the IP
address for which the new reservation is being added.
@@ -5752,7 +5752,7 @@ The ``ip-reservations-unique`` is a boolean parameter that defaults to
``true``, which forbids the specification of more than one reservation
for the same IP address within a given subnet. Setting this parameter to
``false`` allows such reservations to be created both in the Kea configuration
file and in the host database backend, via the ``host-cmds`` hook library.
file and in the host database backend, via :ischooklib:`libdhcp_host_cmds.so`.
This setting is currently supported by the most popular host database
backends, i.e. MySQL and PostgreSQL.
@@ -6672,7 +6672,7 @@ The parameter is expressed in seconds, so the example above
instructs the server to recycle declined leases after one hour.
There are several statistics and hook points associated with the decline
handling procedure. The ``lease4_decline`` hook is triggered after the
handling procedure. The ``lease4_decline`` hook point is triggered after the
incoming DHCPDECLINE message has been sanitized and the server is about
to decline the lease. The ``declined-addresses`` statistic is increased
after the hook returns (both the global and subnet-specific variants). (See
@@ -7488,7 +7488,7 @@ the DHCPv4 server parameters can be configured in the database. All other
parameters must be specified in the JSON configuration file, if
required.
All supported parameters can be configured via the ``cb_cmds`` hook library
All supported parameters can be configured via :ischooklib:`libdhcp_cb_cmds.so`
described in the :ref:`hooks-cb-cmds` section. The general rule is that
scalar global parameters are set using
:isccmd:`remote-global-parameter4-set`; shared-network-specific parameters
@@ -7728,13 +7728,13 @@ waiting for the next fetch cycle.
In the configuration examples above, two hook libraries are loaded. The first
is a library which implements the Configuration Backend for a specific database
type: ``libdhcp_mysql_cb.so`` provides support for MySQL and ``libdhcp_pgsql_cb.so``
type: :ischooklib:`libdhcp_mysql_cb.so` provides support for MySQL and :ischooklib:`libdhcp_pgsql_cb.so`
provides support for PostgreSQL. The library loaded must match the database
``type`` specified within the ``config-control`` parameter or an will error be
logged when the server attempts to load its configuration and the load will
fail.
The second hook library, ``libdhcp_cb_cmds.so``, is optional. It should
The second hook library, :ischooklib:`libdhcp_cb_cmds.so`, is optional. It should
be loaded when the Kea server instance is to be used to manage the
configuration in the database. See the :ref:`hooks-cb-cmds` section for
details. This hook library is only available to ISC
@@ -7983,7 +7983,7 @@ before using this allocator. The FLQ allocator can heavily impact the server's
startup and reconfiguration time, because the allocator has to populate the
list of free leases for each subnet where it is used. These delays can be
observed both during the configuration reload and when the subnets are
created using the ``subnet_cmds`` hook. The allocator increases the
created using :ischooklib:`libdhcp_subnet_cmds.so`. The allocator increases the
memory consumption to hold the list of free leases, proportional
to the total size of the address pools for which this allocator is used.
Finally, lease reclamation must be enabled with a low value of the

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

@@ -4942,8 +4942,8 @@ reservations for the same IP address or delegated prefix within a
particular subnet, to avoid having two different clients
compete for the same lease. When using the default settings, the server
returns a configuration error when it finds two or more reservations for
the same lease within a subnet in the Kea configuration file. The
:ref:`hooks-host-cmds` hook library returns an error in response to the
the same lease within a subnet in the Kea configuration file.
:ischooklib:`libdhcp_host_cmds.so` returns an error in response to the
:isccmd:`reservation-add` command when it detects that the reservation exists
in the database for the lease for which the new reservation is being added.
@@ -4957,7 +4957,7 @@ The ``ip-reservations-unique`` is a boolean parameter that defaults to
``true``, which forbids the specification of more than one reservation
for the same lease in a given subnet. Setting this parameter to ``false``
allows such reservations to be created both in the Kea configuration
file and in the host database backend, via the ``host-cmds`` hook library.
file and in the host database backend, via :ischooklib:`libdhcp_host_cmds.so`.
This setting is currently supported by the most popular host database
backends, i.e. MySQL and PostgreSQL.
@@ -6309,7 +6309,7 @@ The parameter is expressed in seconds, so the example above
instructs the server to recycle declined leases after one hour.
There are several statistics and hook points associated with the decline
handling procedure. The ``lease6_decline`` hook is triggered after the
handling procedure. The ``lease6_decline`` hook point is triggered after the
incoming DHCPDECLINE message has been sanitized and the server is about
to decline the lease. The ``declined-addresses`` statistic is increased
after the hook returns (both the global and subnet-specific variants). (See
@@ -7197,7 +7197,7 @@ the DHCPv6 server parameters can be configured in the database. All other
parameters must be specified in the JSON configuration file, if
required.
All supported parameters can be configured via the ``cb_cmds`` hook library
All supported parameters can be configured via :ischooklib:`libdhcp_cb_cmds.so`
described in the :ref:`hooks-cb-cmds` section. The general rule is that
scalar global parameters are set using
:isccmd:`remote-global-parameter6-set`; shared-network-specific parameters
@@ -7567,7 +7567,7 @@ before using this allocator for prefix delegation. The FLQ allocator can heavily
impact the server's startup and reconfiguration time, because the allocator
has to populate the list of free leases for each subnet where it is used.
These delays can be observed both during the configuration reload and when
the subnets are created using the ``subnet_cmds`` hook. The allocator
the subnets are created using :ischooklib:`libdhcp_subnet_cmds.so`. The allocator
increases the memory consumption to hold the list of free leases,
proportional to the total size of the pools for which this allocator is used.
Finally, lease reclamation must be enabled with a low value of the

10
doc/sphinx/arm/ext-gss-tsig.rst
View File

@@ -15,7 +15,7 @@ Windows servers, have chosen to adopt a more complex GSS-TSIG approach that offe
additional capabilities, such as using negotiated dynamic keys.
Kea supports GSS-TSIG to protect DNS updates sent by
the Kea DHCP-DDNS (D2) server in a premium hook, called ``gss_tsig``.
the Kea DHCP-DDNS (D2) server in a premium hook, called :ischooklib:`libddns_gss_tsig.so`.
GSS-TSIG is defined in `RFC 3645 <https://tools.ietf.org/html/rfc3645>`__.
The GSS-TSIG protocol itself is an implementation of generic GSS-API v2
@@ -116,11 +116,11 @@ detection, similar to this:
6. Compile ``make -jX``, where X is the number of CPU cores
available.
7. After compilation, the ``gss_tsig`` hook is available in the
7. After compilation, :ischooklib:`libddns_gss_tsig.so` is available in the
``premium/src/hooks/d2/gss_tsig`` directory. It can be loaded by
the Kea DHCP-DDNS (D2) daemon.
The ``gss_tsig`` hook library was developed using the MIT Kerberos 5 implementation, but
:ischooklib:`libddns_gss_tsig.so` was developed using the MIT Kerberos 5 implementation, but
Heimdal is also supported. Note that Heimdal is picky about
security-sensitive file permissions and is known to emit an unclear error message.
It is a good idea to keep these files plain, with one link and no
@@ -464,7 +464,7 @@ Using GSS-TSIG
There are a number of steps required to enable the GSS-TSIG mechanism:
1. The ``gss_tsig`` hook library must be loaded by the D2 server.
1. :ischooklib:`libddns_gss_tsig.so` must be loaded by the D2 server.
2. The GSS-TSIG-capable DNS servers must be specified with their parameters.
An excerpt from a D2 server configuration is provided below; more examples are available in the
@@ -606,7 +606,7 @@ specified, the default of 53 is assumed. This is similar to basic mode, with no
authentication done using TSIG keys, with the
exception that static TSIG keys are not referenced by name.
Second, the ``libddns_gss_tsig.so`` library must be specified on the
Second, :ischooklib:`libddns_gss_tsig.so` must be specified on the
``hooks-libraries`` list. This hook takes many parameters. The most important
one is ``servers``, which is a list of GSS-TSIG-capable servers. If there are
several servers and they share some characteristics, the values can be specified

5
doc/sphinx/arm/hooks-bootp.rst
View File

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_bootp.so
.. _hooks-bootp:
``bootp``: Support for BOOTP Clients
====================================
``libdhcp_bootp.so``: Support for BOOTP Clients
===============================================
This hook library adds support for BOOTP with vendor-information extensions
(`RFC 1497 <https://tools.ietf.org/html/rfc1497>`__). Received BOOTP

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

@@ -1,27 +1,28 @@
.. ischooklib:: libdhcp_cb_cmds.so
.. _hooks-cb-cmds:
``cb_cmds``: Configuration Backend Commands
===========================================
``libdhcp_cb_cmds.so``: Configuration Backend Commands
======================================================
This hook library is used to manage Kea
servers' configurations in a configuration backend database. This library must
be used in conjunction with the available CB hook libraries implementing
the common APIs to create, read, update, and delete (CRUD) the
configuration information in the respective databases. For example:
the ``mysql_cb`` hook library implements this API for MySQL while the
``pgsql_cb`` hook library implements this API for PostgreSQL.
To manage the configuration information in a MySQL database, both the
``mysql_cb`` and ``cb_cmds`` libraries must be loaded by the server used for the
configuration management.
To manage the configuration information in a PostgreSQL database, both the
``pgsql_cb`` and ``cb_cmds`` libraries must be loaded by the server used for the
configuration management.
:ischooklib:`libdhcp_mysql_cb.so` implements this API for MySQL while
:ischooklib:`libdhcp_pgsql_cb.so` implements this API for PostgreSQL.
To manage the configuration information in a MySQL database, both
:ischooklib:`libdhcp_mysql_cb.so` and :ischooklib:`libdhcp_cb_cmds.so`
must be loaded by the server used for the configuration management.
To manage the configuration information in a PostgreSQL database, both
:ischooklib:`libdhcp_pgsql_cb.so` and :ischooklib:`libdhcp_cb_cmds.so`
must be loaded by the server used for the configuration management.
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`
and :ref:`dhcp6-cb` sections.
The ``cb_cmds`` library is only available to ISC customers with a paid
:ischooklib:`libdhcp_cb_cmds.so` is only available to ISC customers with a paid
support contract.
.. note::
@@ -79,7 +80,7 @@ be specified, the parameter should be omitted. In this case, the server
will use the first backend listed in the ``config-control`` map within
the configuration of the server receiving the command.
The ``cb_cmds`` library is only available to ISC customers with a paid
:ischooklib:`libdhcp_cb_cmds.so` is only available to ISC customers with a paid
support contract.
.. note::
@@ -98,7 +99,7 @@ support contract.
to use a single configuration backend. Strictly speaking, it is
possible to point the Kea server to at most one database (either MySQL or
PostgreSQL) using the ``config-control`` parameter. Therefore, the ``remote``
parameter may be omitted in the commands and the ``cb_cmds`` hook library
parameter may be omitted in the commands and :ischooklib:`libdhcp_cb_cmds.so`
uses the sole backend by default. The example commands below most often show a
value of "mysql" for the ``type`` parameter; it should be assumed that the
value is "postgresql" for installations using a PostgreSQL database.
@@ -109,7 +110,7 @@ Control Commands for DHCP Servers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes and gives some examples of the control commands
implemented by the ``cb_cmds`` hook library, to manage the
implemented by :ischooklib:`libdhcp_cb_cmds.so`, to manage the
configuration information of the DHCPv4 and DHCPv6 servers. Many of the
commands are almost identical between DHCPv4 and DHCPv6; they only
differ by the command name. Other commands differ slightly by the

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

@@ -1,9 +1,10 @@
.. ischooklib:: libdhcp_mysql_cb.so
.. _hooks-cb-mysql:
``mysql_cb``: Configuration Backend for MySQL
=============================================
``libdhcp_mysql_cb.so``: Configuration Backend for MySQL
========================================================
This hook library works in conjunction with the ``cb_cmds`` library to
This hook library works in conjunction with :ischooklib:`libdhcp_cb_cmds.so` to
implement the API to create, read, update, and delete (CRUD) the
configuration in a MySQL database. Please see :ref:`hooks-cb-cmds`
for more details.

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

@@ -1,9 +1,10 @@
.. ischooklib:: libdhcp_pgsql_cb.so
.. _hooks-cb-pgsql:
``pgsql_cb``: Configuration Backend for PostgreSQL
==================================================
``libdhcp_pgsql_cb.so``: Configuration Backend for PostgreSQL
=============================================================
This hook library works in conjunction with the ``cb_cmds`` library to
This hook library works in conjunction with :ischooklib:`libdhcp_cb_cmds.so` to
implement the API to create, read, update, and delete (CRUD) the
configuration in a PostgreSQL database. Please see :ref:`hooks-cb-cmds`
for more details.

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

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_class_cmds.so
.. _hooks-class-cmds:
``class_cmds``: Class Commands
==============================
``libdhcp_class_cmds.so``: Class Commands
=========================================
This hook library exposes
several control commands for manipulating client classes (part of the

16
doc/sphinx/arm/hooks-ddns-tuning.rst
View File

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_ddns_tuning.so
.. _hooks-ddns-tuning:
``ddns_tuning``: DDNS Tuning
============================
``libdhcp_ddns_tuning.so``: DDNS Tuning
=======================================
This hook library adds support for fine-tuning various DNS update aspects.
It currently supports procedural host-name generation and the ability to skip
@@ -157,7 +158,7 @@ response to a client query (e.g. SOLICIT, REQUEST, RENEW, REBIND) is as follows:
Skipping DDNS Updates
~~~~~~~~~~~~~~~~~~~~~
The ``ddns-tuning`` library also provides the ability to skip DDNS updates on a
:ischooklib:`libdhcp_ddns_tuning.so` also provides the ability to skip DDNS updates on a
per-client basis. The library recognizes a special client class, "SKIP_DDNS"; when a
client is matched to this class, the Kea servers (:iscman:`kea-dhcp4` and :iscman:`kea-dhcp6`) do not
send DDNS update requests (NCRs) to :iscman:`kea-dhcp-ddns`. A common use case would be
@@ -175,13 +176,8 @@ simply assigning the class to the host reservation as shown below:
}]
}
<<<<<<< HEAD
The ``ddns-tuning`` library notes the presence of the "SKIP_DDNS" class in the
||||||| parent of 0e20e5ed8c (isccmd)
:ischooklib:`libdhcp_ddns_tuning.so` notes the presence of the ``"SKIP_DDNS"`` class in the
=======
The :ischooklib:`libdhcp_ddns_tuning.so` hook library notes the presence of the ``"SKIP_DDNS"`` class in the
>>>>>>> 0e20e5ed8c (isccmd)
The :ischooklib:`libdhcp_ddns_tuning.so` hook library notes the
presence of the ``"SKIP_DDNS"`` class in the
client's class list each time the client requests, renews, or releases its lease,
and instructs :iscman:`kea-dhcp4` to bypass sending DDNS updates. A similar workflow is
supported for :iscman:`kea-dhcp6`:

17
doc/sphinx/arm/hooks-flex-id.rst
View File

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_flex_id.so
.. _hooks-flex-id:
``flex_id``: Flexible Identifier for Host Reservations
======================================================
``libdhcp_flex_id.so``: Flexible Identifier for Host Reservations
=================================================================
The Kea software provides a way to handle
host reservations that include addresses, prefixes, options, client
@@ -21,7 +22,7 @@ contract.
This library can only be loaded by the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6`
process.
The ``flex_id`` library allows the definition of an expression, using notation initially
:ischooklib:`libdhcp_flex_id.so` allows the definition of an expression, using notation initially
used only for client classification. (See
:ref:`classification-using-expressions` for a detailed description of
the syntax available.) One notable difference is that for client
@@ -155,7 +156,7 @@ The ``replace-client-id`` Flag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When ``replace-client-id`` is set to ``false`` (which is the default setting),
the ``flex-id`` hook library uses the evaluated flexible identifier solely for
:ischooklib:`libdhcp_flex_id.so` uses the evaluated flexible identifier solely for
identifying host reservations, i.e. searching for reservations within a
database. This is the functional equivalent of other identifiers, similar
to hardware address or circuit-id. However, this mode of operation
@@ -172,7 +173,7 @@ and other parameters are used that identify where the device is connected
(e.g. circuit-id), rather than the device identification itself (e.g.
MAC address).
The ``flex-id`` library offers a way to overcome the problem with lease
:ischooklib:`libdhcp_flex_id.so` offers a way to overcome the problem with lease
conflicts by dynamically replacing the client identifier (or DUID in DHCPv6)
with a value derived from the flexible identifier. The server
processes the client's query as if the flexible identifier were sent in the
@@ -215,7 +216,7 @@ client-id option) is ignored.
The :ref:`hooks-lease-cmds` section describes commands used to retrieve,
update, and delete leases using various identifiers, such as ``hw-address`` and
``client-id``. The ``lease_cmds`` library does not natively support querying
``client-id``. :ischooklib:`libdhcp_lease_cmds.so` does not natively support querying
for leases by flexible identifier. However, when ``replace-client-id`` is
set to ``true``, it makes it possible to query for leases using a value
derived from the flexible identifier. In DHCPv4, the query
@@ -251,8 +252,8 @@ In DHCPv6, the corresponding query looks something like this:
The ``ignore-iaid`` Flag
~~~~~~~~~~~~~~~~~~~~~~~~
When ``ignore-iaid`` is set to ``true`` (the default value is ``false``), the
``flex-id`` hook library causes the Kea DHCPv6 server to ignore the IAID value
When ``ignore-iaid`` is set to ``true`` (the default value is ``false``),
:ischooklib:`libdhcp_flex_id.so` causes the Kea DHCPv6 server to ignore the IAID value
from incoming IPv6 packets. This parameter is ignored by the Kea DHCPv4 server.
If the packet contains only one IA_NA, the IAID value will be changed to ``0``

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

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_flex_option.so
.. _hooks-flex-option:
``flex_option``: Flexible Option Actions for Option Value Settings
==================================================================
``libdhcp_flex_option.so``: Flexible Option Actions for Option Value Settings
=============================================================================
This library allows administrators to define an action to take, for a given
option, based upon on the result of an expression. These actions are carried
@@ -33,7 +34,7 @@ numeric code or its name; either the code or the name must be
specified. The option space is DHCPv4 or DHCPv6, depending
on the server where the hook library is loaded.
Similar to other hook libraries, the ``flex_option`` library can be loaded
Similar to other hook libraries, :ischooklib:`libdhcp_flex_option.so` can be loaded
by either the :iscman:`kea-dhcp4` or :iscman:`kea-dhcp6`
process. It takes a mandatory ``options`` parameter with a list of
per-option parameter maps, with ``code``, ``name``, ``add``, ``supersede``, and

5
doc/sphinx/arm/hooks-gss-tsig.rst
View File

@@ -1,7 +1,8 @@
.. ischooklib:: libddns_gss_tsig.so
.. _hooks-gss-tsig:
``gss-tsig``: Sign DNS Updates With GSS-TSIG
============================================
``libddns_gss_tsig.so``: Sign DNS Updates With GSS-TSIG
=======================================================
This hook library allows the :iscman:`kea-dhcp-ddns` server to use
GSS-TSIG to sign DNS updates. For a full discussion of GSS-TSIG in Kea,

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

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_ha.so
.. _hooks-high-availability:
``ha``: High Availability Outage Resilience for Kea Servers
===========================================================
``libdhcp_ha.so``: High Availability Outage Resilience for Kea Servers
======================================================================
This hook library can be loaded on a pair of DHCPv4 or DHCPv6 servers, to
increase the reliability of the DHCP service in the event of an outage on one
@@ -714,14 +715,14 @@ only difference that ``this-server-name`` should be set to "server2" and
}]
}
Two hook libraries must be loaded to enable HA: ``libdhcp_lease_cmds.so`` and
``libdhcp_ha.so``. The latter implements the HA feature, while the former
Two hook libraries must be loaded to enable HA: :ischooklib:`libdhcp_lease_cmds.so` and
:ischooklib:`libdhcp_ha.so`. The latter implements the HA feature, while the former
enables control commands required by HA to fetch and manipulate leases on the
remote servers. In the example provided above, it is assumed that Kea libraries
are installed in the ``/usr/lib`` directory. If Kea is not installed in the
``/usr`` directory, the hook libraries' locations must be updated accordingly.
The HA configuration is specified within the scope of ``libdhcp_ha.so``.
The HA configuration is specified within the scope of :ischooklib:`libdhcp_ha.so`.
Note that while the top-level parameter ``high-availability`` is a list, only a
single entry is currently supported.
@@ -1474,8 +1475,7 @@ state machine.
In order to "unpause" the state machine, the :isccmd:`ha-continue` command must be
sent to the paused server. This command does not take any arguments. See
:ref:`ha-control-commands` for details about commands specific to the HA hook
library.
:ref:`ha-control-commands` for details about commands specific to :ischooklib:`libdhcp_ha.so`.
It is possible to configure the state machine to pause in more than one state.
Consider the following configuration:

5
doc/sphinx/arm/hooks-host-cache.rst
View File

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_host_cache.so
.. _hooks-host-cache:
``host_cache``: Host Cache Reservations for Improved Performance
================================================================
``libdhcp_host_cache.so``: Host Cache Reservations for Improved Performance
===========================================================================
Some database backends, such as RADIUS, are slow and may take
a long time to respond. Since Kea in general is synchronous, backend

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

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_host_cmds.so
.. _hooks-host-cmds:
``host_cmds``: Host Commands
============================
``libdhcp_host_cmds.so``: Host Commands
=======================================
Kea can store host reservations in a database; in many larger deployments,
it is useful to be able to manage that information while the server is
@@ -51,7 +52,7 @@ modify data stored in the host database, the hosts database must be specified
and it must not operate in read-only mode (for details, see the
``hosts-databases`` descriptions in :ref:`hosts-databases-configuration4` and
:ref:`hosts-databases-configuration6`). If the ``hosts-databases`` are not
specified or are running in read-only mode, the ``host_cmds`` library will
specified or are running in read-only mode, :ischooklib:`libhost_cmds.so` will
load, but any attempts to use :isccmd:`reservation-add`, :isccmd:`reservation-del`, and
:isccmd:`reservation-update` to modify data in that database will fail.

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

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_lease_cmds.so
.. _hooks-lease-cmds:
``lease_cmds``: Lease Commands for Easier Lease Management
==========================================================
``libdhcp_lease_cmds.so``: Lease Commands for Easier Lease Management
=====================================================================
Kea allows users to store lease information in several
backends (memfile, MySQL, and PostgreSQL), and the Lease Commands library provides an

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

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_lease_query.so
.. _hooks-lease-query:
``lease_query``: Leasequery Support
===================================
``libdhcp_lease_query.so``: Leasequery Support
==============================================
This library provides support for DHCPv4 Leasequery as described in
`RFC 4388 <https://tools.ietf.org/html/rfc4388>`__; and for DHCPv6

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

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_legal_log.so
.. _hooks-legal-log:
``legal_log``: Forensic Logging
===============================
``libdhcp_legal_log.so``: Forensic Logging
==========================================
The Forensic Logging hook library provides
hooks that record a detailed log of assignments, renewals, releases, and other
@@ -76,14 +77,14 @@ Configuring the Forensic Logging Hooks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To use this functionality, the hook library must be included in the
configuration of the desired DHCP server modules. The ``legal_log`` library
configuration of the desired DHCP server modules. :ischooklib:`libdhcp_legal_log.so`
can save logs to a text file or to a database (created using
:iscman:`kea-admin`; see :ref:`mysql-database-create` and :ref:`pgsql-database-create`).
The library is installed alongside the Kea libraries in
``[kea-install-dir]/var/lib/kea``, where ``kea-install-dir`` is determined
by the ``--prefix`` option of the configure script; it defaults to
``/usr/local``. Assuming the default value, :iscman:`kea-dhcp4` can be configured to load
the ``legal_log`` library like this:
:ischooklib:`libdhcp_legal_log.so` like this:
.. code-block:: json

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

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_limits.so
.. _hooks-limits:
``limits``: Limits to Manage Lease Allocation and Packet Processing
===================================================================
``libdhcp_limits.so``: Limits to Manage Lease Allocation and Packet Processing
==============================================================================
This hook library enables two types of limits:

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

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_radius.so
.. _hooks-radius:
``radius``: RADIUS Server Support
=================================
``libdhcp_radius.so``: RADIUS Server Support
============================================
This hook library allows Kea to interact with two types of RADIUS
servers: access and accounting. Although the most common DHCP and RADIUS
@@ -377,13 +378,13 @@ flags, which correspond to FreeRADIUS client library options:
- ``identifier-type4`` (default ``client-id``) - specifies the identifier
type to build the User-Name attribute. It should be the same as the
host identifier, and when the ``flex-id`` hook library is used the
host identifier, and when :ischooklib:`libdhcp_flex_id.so` is used the
``replace-client-id`` must be set to ``true``; ``client-id`` is used with
``client-id-pop0``.
- ``identifier-type6`` (default ``duid``) - specifies the identifier type to
build the User-Name attribute. It should be the same as the host
identifier, and when the ``flex-id`` hook library is used the
identifier, and when :ischooklib:`libdhcp_flex_id.so` is used the
``replace-client-id`` must be set to ``true``; ``duid`` is used with
``client-id-pop0``.

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

@@ -1,14 +1,15 @@
.. ischooklib:: libca_rbac.so
.. _hooks-RBAC:
``rbac``: Role-Based Access Control
===================================
``libca_rbac.so``: Role-Based Access Control
============================================
.. _hooks-RBAC-overview:
Role-Based Access Control (RBAC) Overview
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before the processing of commands in received HTTP requests, the ``rbac`` hook
Before the processing of commands in received HTTP requests, :ischooklib:`libca_rbac.so`
takes specific parameters, e.g. the common-name part of the client
certificate subject name, to assign a role to the request.
The configuration associated with this role is used to accept or reject
@@ -99,7 +100,7 @@ API Commands
All commands of the REST API are described in files in the source directory
``src/share/api``, or in installed Kea
in ``.../share/kea/api``. The ``rbac`` hook reads these files to take the name,
in ``.../share/kea/api``. :ischooklib:`libca_rbac.so` reads these files to take the name,
the access right (i.e. ``read`` or ``write``), and the hook name. The access right
can be modified in the file but changes are only applied after the Control Agent
restarts. Removing command definitions from ``.../share/kea/api`` has

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

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_run_script.so
.. _hooks-run-script:
``run_script``: Run Script Support for External Hook Scripts
============================================================
``libdhcp_run_script.so``: Run Script Support for External Hook Scripts
=======================================================================
The Run Script hook library adds support for calling an external script for specific
packet-processing hook points.

5
doc/sphinx/arm/hooks-stat-cmds.rst
View File

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_stat_cmds.so
.. _hooks-stat-cmds:
``stat_cmds``: Statistics Commands for Supplemental Lease Statistics
====================================================================
``libdhcp_stat_cmds.so``: Statistics Commands for Supplemental Lease Statistics
===============================================================================
This library provides additional commands for retrieving lease
statistics from Kea DHCP servers. These commands were added to address

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

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_subnet_cmds.so
.. _hooks-subnet-cmds:
``subnet_cmds``: Subnet Commands to Manage Subnets and Shared Networks
======================================================================
``libdhcp_subnet_cmds.so``: Subnet Commands to Manage Subnets and Shared Networks
=================================================================================
This library offers commands used to query and manipulate subnet and shared network
configurations in Kea. These can be very useful in deployments

5
doc/sphinx/arm/hooks-user-chk.rst
View File

@@ -1,7 +1,8 @@
.. ischooklib:: libdhcp_user_chk.so
.. _hooks-user-chk:
``user_chk``: User Check
========================
``libdhcp_user_chk.so``: User Check
===================================
This library serves several purposes: