diff options
28 files changed, 143 insertions, 130 deletions
diff --git a/doc/sphinx/arm/classify.rst b/doc/sphinx/arm/classify.rst index 607a56a316..17eb774948 100644 --- a/doc/sphinx/arm/classify.rst +++ b/doc/sphinx/arm/classify.rst @@ -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 diff --git a/doc/sphinx/arm/config-backend.rst b/doc/sphinx/arm/config-backend.rst index b7d785ea02..8aab0923b1 100644 --- a/doc/sphinx/arm/config-backend.rst +++ b/doc/sphinx/arm/config-backend.rst @@ -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 diff --git a/doc/sphinx/arm/ctrl-channel.rst b/doc/sphinx/arm/ctrl-channel.rst index 8fe0ad1ad3..4ede42c02d 100644 --- a/doc/sphinx/arm/ctrl-channel.rst +++ b/doc/sphinx/arm/ctrl-channel.rst @@ -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: diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index 55a16a3b5c..49b6288486 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -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 diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index 4d4cd717e6..0b827aa343 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -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 diff --git a/doc/sphinx/arm/ext-gss-tsig.rst b/doc/sphinx/arm/ext-gss-tsig.rst index 321d7b65c5..f8c66a2db0 100644 --- a/doc/sphinx/arm/ext-gss-tsig.rst +++ b/doc/sphinx/arm/ext-gss-tsig.rst @@ -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 diff --git a/doc/sphinx/arm/hooks-bootp.rst b/doc/sphinx/arm/hooks-bootp.rst index 53460c11fa..6942376ec1 100644 --- a/doc/sphinx/arm/hooks-bootp.rst +++ b/doc/sphinx/arm/hooks-bootp.rst @@ -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 diff --git a/doc/sphinx/arm/hooks-cb-cmds.rst b/doc/sphinx/arm/hooks-cb-cmds.rst index d96e19db5d..6d8ad1e1ba 100644 --- a/doc/sphinx/arm/hooks-cb-cmds.rst +++ b/doc/sphinx/arm/hooks-cb-cmds.rst @@ -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 diff --git a/doc/sphinx/arm/hooks-cb-mysql.rst b/doc/sphinx/arm/hooks-cb-mysql.rst index 16111ff7bb..30667e2d4e 100644 --- a/doc/sphinx/arm/hooks-cb-mysql.rst +++ b/doc/sphinx/arm/hooks-cb-mysql.rst @@ -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. diff --git a/doc/sphinx/arm/hooks-cb-pgsql.rst b/doc/sphinx/arm/hooks-cb-pgsql.rst index cf8deccb15..238954d786 100644 --- a/doc/sphinx/arm/hooks-cb-pgsql.rst +++ b/doc/sphinx/arm/hooks-cb-pgsql.rst @@ -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. diff --git a/doc/sphinx/arm/hooks-class-cmds.rst b/doc/sphinx/arm/hooks-class-cmds.rst index c9ea21fa49..bb1baff335 100644 --- a/doc/sphinx/arm/hooks-class-cmds.rst +++ b/doc/sphinx/arm/hooks-class-cmds.rst @@ -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 diff --git a/doc/sphinx/arm/hooks-ddns-tuning.rst b/doc/sphinx/arm/hooks-ddns-tuning.rst index b4a58b7d3c..6feb34189f 100644 --- a/doc/sphinx/arm/hooks-ddns-tuning.rst +++ b/doc/sphinx/arm/hooks-ddns-tuning.rst @@ -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`: diff --git a/doc/sphinx/arm/hooks-flex-id.rst b/doc/sphinx/arm/hooks-flex-id.rst index eab5e48aeb..368f032436 100644 --- a/doc/sphinx/arm/hooks-flex-id.rst +++ b/doc/sphinx/arm/hooks-flex-id.rst @@ -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`` diff --git a/doc/sphinx/arm/hooks-flex-option.rst b/doc/sphinx/arm/hooks-flex-option.rst index 06824c0ed2..b0dcc38dd0 100644 --- a/doc/sphinx/arm/hooks-flex-option.rst +++ b/doc/sphinx/arm/hooks-flex-option.rst @@ -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 diff --git a/doc/sphinx/arm/hooks-gss-tsig.rst b/doc/sphinx/arm/hooks-gss-tsig.rst index 89260eda38..d5817d39d3 100644 --- a/doc/sphinx/arm/hooks-gss-tsig.rst +++ b/doc/sphinx/arm/hooks-gss-tsig.rst @@ -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, diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst index c6dc426e76..c6a9738d0d 100644 --- a/doc/sphinx/arm/hooks-ha.rst +++ b/doc/sphinx/arm/hooks-ha.rst @@ -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: diff --git a/doc/sphinx/arm/hooks-host-cache.rst b/doc/sphinx/arm/hooks-host-cache.rst index 3a5d50850f..de7a121e54 100644 --- a/doc/sphinx/arm/hooks-host-cache.rst +++ b/doc/sphinx/arm/hooks-host-cache.rst @@ -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 diff --git a/doc/sphinx/arm/hooks-host-cmds.rst b/doc/sphinx/arm/hooks-host-cmds.rst index 92f292a93b..93a0395122 100644 --- a/doc/sphinx/arm/hooks-host-cmds.rst +++ b/doc/sphinx/arm/hooks-host-cmds.rst @@ -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. diff --git a/doc/sphinx/arm/hooks-lease-cmds.rst b/doc/sphinx/arm/hooks-lease-cmds.rst index f0c7556aa8..c6a0d10047 100644 --- a/doc/sphinx/arm/hooks-lease-cmds.rst +++ b/doc/sphinx/arm/hooks-lease-cmds.rst @@ -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 diff --git a/doc/sphinx/arm/hooks-lease-query.rst b/doc/sphinx/arm/hooks-lease-query.rst index 04f21888fb..2ad2c32889 100644 --- a/doc/sphinx/arm/hooks-lease-query.rst +++ b/doc/sphinx/arm/hooks-lease-query.rst @@ -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 diff --git a/doc/sphinx/arm/hooks-legal-log.rst b/doc/sphinx/arm/hooks-legal-log.rst index 32dbb9e439..daea88fcdf 100644 --- a/doc/sphinx/arm/hooks-legal-log.rst +++ b/doc/sphinx/arm/hooks-legal-log.rst @@ -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 diff --git a/doc/sphinx/arm/hooks-limits.rst b/doc/sphinx/arm/hooks-limits.rst index f7bf8be58b..6560102df3 100644 --- a/doc/sphinx/arm/hooks-limits.rst +++ b/doc/sphinx/arm/hooks-limits.rst @@ -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: diff --git a/doc/sphinx/arm/hooks-radius.rst b/doc/sphinx/arm/hooks-radius.rst index cdf156a26d..3ee245bc0d 100644 --- a/doc/sphinx/arm/hooks-radius.rst +++ b/doc/sphinx/arm/hooks-radius.rst @@ -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``. diff --git a/doc/sphinx/arm/hooks-rbac.rst b/doc/sphinx/arm/hooks-rbac.rst index 46e3fb702d..7f3026be57 100644 --- a/doc/sphinx/arm/hooks-rbac.rst +++ b/doc/sphinx/arm/hooks-rbac.rst @@ -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 diff --git a/doc/sphinx/arm/hooks-run-script.rst b/doc/sphinx/arm/hooks-run-script.rst index 8fc894fac6..5e7e182686 100644 --- a/doc/sphinx/arm/hooks-run-script.rst +++ b/doc/sphinx/arm/hooks-run-script.rst @@ -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. diff --git a/doc/sphinx/arm/hooks-stat-cmds.rst b/doc/sphinx/arm/hooks-stat-cmds.rst index 1fe7e55786..eccbfaafa3 100644 --- a/doc/sphinx/arm/hooks-stat-cmds.rst +++ b/doc/sphinx/arm/hooks-stat-cmds.rst @@ -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 diff --git a/doc/sphinx/arm/hooks-subnet-cmds.rst b/doc/sphinx/arm/hooks-subnet-cmds.rst index 18cee139bc..878a7dc025 100644 --- a/doc/sphinx/arm/hooks-subnet-cmds.rst +++ b/doc/sphinx/arm/hooks-subnet-cmds.rst @@ -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 diff --git a/doc/sphinx/arm/hooks-user-chk.rst b/doc/sphinx/arm/hooks-user-chk.rst index a7d2ba2243..75db216594 100644 --- a/doc/sphinx/arm/hooks-user-chk.rst +++ b/doc/sphinx/arm/hooks-user-chk.rst @@ -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: |