From 9817f071ed021f471dba7d7796c307512550b54b Mon Sep 17 00:00:00 2001 From: Thomas Markwalder Date: Tue, 14 Nov 2023 15:21:43 -0500 Subject: [PATCH] [#3084] Added initial ARM documentation modified: hooks-ping-check.rst --- doc/sphinx/arm/hooks-ping-check.rst | 172 +++++++++++++++++++++++++++- 1 file changed, 167 insertions(+), 5 deletions(-) diff --git a/doc/sphinx/arm/hooks-ping-check.rst b/doc/sphinx/arm/hooks-ping-check.rst index 661d3c8871..e327a4ccaf 100644 --- a/doc/sphinx/arm/hooks-ping-check.rst +++ b/doc/sphinx/arm/hooks-ping-check.rst @@ -4,13 +4,175 @@ ``libdhcp_ping_check.so``: Ping Check ===================================== -This hook library is under development and currently provides no functionality. -Once complete it will provide :iscman:`kea-dhcp4` with the ability to carry out ping checks of candidate addresses prior to offering them in leases to clients. +This hook library adds the ability to perform a "ping check" of a candidate +IPv4 address prior to offering it to a DHCP client. This feature is similar +to a behavior available in ISC DHCP and one suggested in `RFC +2131 `__ , see section 3.2, item 2. .. note:: - :ischooklib:`libdhcp_ping_check.so` will be 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. + :ischooklib:`libdhcp_ping_check.so` is available only to ISC customers + with a paid support contract. For more information on subscription options, + please complete the form at https://www.isc.org/contact. +Overview +~~~~~~~~ +The library, added in Kea 2.5.4, can be loaded by the :iscman:`kea-dhcp4` daemon +by adding it to the ``hooks-libraries`` element of the server's configuration: + +.. code-block:: javascript + + { + "hooks-libraries": [ + { + "library": "/usr/local/lib/libdhcp_ping_check.so", + "parameters": { + ... + } + }, + ... + ], + ... + } + +When the library is loaded :iscman:`kea-dhcp4` will conduct ping-check prior to +offering a lease to client if all of the following conditions are true + +1. Ping check hook library is loaded + +2. Ping checking is enabled + +3. The server is responding to a DHCPDISCOVER. + +4. The candidate lease is neither active nor reserved + +5. Any of the following are true: + + a. This is the first offer of this lease to this client. This check + can only be done if `offer-lifetime` is greater than zero (i.e. temporary + allocation on DHCPDISCOVER is enabled). If `offer-lifetime` is zero + ping checks are done for every DHCPOFFER as the server has no way to + know it has made prior offers. + + b. The lease is being offered to a client other than its previous owner + + c. The lease is being offered to its previous owner and more than a + configurable number of seconds, `ping-cltt-secs`, have elapsed since + CLTT of the original lease. + +When the ping check library is loaded, in response to a DHCPDISCOVER the +:iscman:`kea-dhcp4` will: + +1. Select a candidate IPv4 address through normal processes and use it to +construct a DHCPOFFER + +2. Park the DHCPOFFER and request a ping-check from the ping-check hook +library via its `lease4-offer` callout + +3. The callout will test conditions described above. If they are not +satisfied it will return without conducting a check, and the server +will send the DHCPOFFER to the client. Otherwise the callout will +initiate a ping-check for the lease address. + +4. Upon conclusion of the ping-check, the server will either send the DHCPOFFER +to the client if the check concluded that the address is available, or discard +the DHCPFOFFER and create a DECLINED lease for the address. + +Each ping-check consists of the following steps: + +1. If the number of ECHO REPLYs sent is less than the configured +minimum number to send, send an ICMP ECHO REQUEST to the lease address. +Otherwise, conclude that the address is available. + +2. If no ECHO REPLY is received within a configurable amount of time +return to step 1. + +3. Upon receipt of an ICMP ECHO REPLY, conclude that the lease is NOT available. + +4. Any of the following occur: + + a. Receipt of an ICMP DESTINATION UNREACHABLE message + b. ICMP ECHO REQUEST send fails due to a network error + c. ICMP ECHO REQUEST send fails with Socket buffer full error + + In each of these instances the address could not be checked and is treated as + available. + +.. note:: + + Socket buffer full errors indicate that the OS rate limits on ICMP are being + been exceeded. The server will not retry them as this would likely only + exacerbate the situation. If this occurs continuously then the client load + on the server may be too high to accommodate ping checking. Ping checking is + not recommended for systems with high throughput demands. + +Configuration +~~~~~~~~~~~~~ + +The ping-check hook library currently supports the following configuration parameters +that may be set the global and subnet levels. Subnet values override global values. + +- `enable-ping-check` - 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. + +- `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. + +- `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. + +The following parameter is only supported 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 code to use the same number of threads as Kea core. + +The following configuration excerpt illustrates global level configuration: + +.. code-block:: javascript + + "hooks-libraries": [{ + "library": "lib/kea/hooks/libdhcp_ping_check.so", + "parameters": { + "enable-ping-check" : true, + "min-ping-requests" : 1, + "reply-timeout" : 100, + "ping-cltt-secs" : 60, + "ping-channel-threads" : 0 + } + }, + +The following excerpt demonstrates subnet level configuration: + +.. code-block:: javascript + + { + "subnet4": [{ + "subnet": "192.0.2.0/24", + "pools": [{ + "pool": "192.0.2.10 - 192.0.2.20" + } ], + + // This is a subnet-specific user context. + "user-context": { + "enable-ping-check" : true, + "min-ping-requests" : 2, + "reply-timeout" : 250, + "ping-cltt-secs" : 120, + }, + }], + ... + } + +.. note:: + + Ping checking is an experimental feature. It is not currently recommended for + production environments. + +.. note:: + + Ping checking is currently only supported when Kea is configured for multi-threaded operation. + +.. note:: + + Ping checking is not yet fully integrated with High Availability (HA). When ping checking + concludes that an address is not available and a declined lease is created, no corresponding + lease update is sent to HA peer(s).