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

[#3299] fix parked-packet-limit mentions in ARM

Browse Source 
- move PPL section to general hooks section
- remove note that PPL is used only for HA
- add PPL section in RADIUS
- add PPL reference in ping-check
- change values in doc/examples to resemble defaults
This commit is contained in:
Andrei Pavel
2024-04-01 15:57:03 +03:00
parent 2cb3999f62
commit 4dae2a3954
8 changed files with 106 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/examples/kea4/all-keys-netconf.json
View File

@@ -572,7 +572,7 @@
// This value limits the number of packets that can be held pending
// the updates. In times of heavy client traffic, this value can keep
// kea-dhcp4 from building an insurmountable backlog of updates.
"parked-packet-limit": 128,
"parked-packet-limit": 256,
// List of global DHCP options that the Kea DHCPv4 server assigns to
// clients.

2
doc/examples/kea4/all-keys.json
View File

@@ -594,7 +594,7 @@
// This value limits the number of packets that can be held pending
// the updates. In times of heavy client traffic, this value can keep
// kea-dhcp4 from building an insurmountable backlog of updates.
"parked-packet-limit": 128,
"parked-packet-limit": 256,
// List of global DHCP options that the Kea DHCPv4 server assigns to
// clients.

2
doc/examples/kea6/all-keys-netconf.json
View File

@@ -564,7 +564,7 @@
// be held pending the updates. In times of heavy client traffic,
// this value can keep kea-dhcp6 from building an insurmountable
// backlog of updates.
"parked-packet-limit": 128,
"parked-packet-limit": 256,
// Global (default) value of the preferred lifetime.
"preferred-lifetime": 50,

2
doc/examples/kea6/all-keys.json
View File

@@ -586,7 +586,7 @@
// be held pending the updates. In times of heavy client traffic,
// this value can keep kea-dhcp6 from building an insurmountable
// backlog of updates.
"parked-packet-limit": 128,
"parked-packet-limit": 256,
// Global (default) value of the preferred lifetime.
"preferred-lifetime": 50,

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

@@ -473,6 +473,20 @@ Somewhat tangential to lease allocation, and not shown in the diagrams above,
is the ``command_processed`` callout, which sends Accounting-Request messages
when a lease command is received.
.. _radius-parked-packet-limit:
Parked-Packet Limit
~~~~~~~~~~~~~~~~~~~
Refer to :ref:`parked-packet-limit` for a basic introduction to packet parking.
The RADIUS hook library makes use of this mechanism. To allow for asynchronous
communication between Kea and the RADIUS server and concurrent processing of
DHCP packets by the Kea server, the DHCP request is parked, before the access
request is sent on the subnet select callout. When the access response becomes
available to the Kea DHCP server, the request is unparked, and the server
continues processing on it.
.. _radius-differences:
Differences Between RADIUS Hook Libraries Prior To 2.4.0 and As Of 2.6.0

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

@@ -1742,67 +1742,16 @@ four threads for the client.
Parked-Packet Limit
~~~~~~~~~~~~~~~~~~~
Kea servers contain a mechanism by which the response to a client packet may
be held, pending completion of hook library work. We refer to this as "parking"
the packet. The HA hook library makes use of this mechanism. When an HA server
needs to send a lease update to its peer(s) to notify it of the change to the
lease, it will "park" the client response until the peer acknowledges the lease
update. At that point, the server will "unpark" the response and send it to the
Refer to :ref:`parked-packet-limit` for a basic introduction to packet parking.
The HA hook library makes use of this mechanism. When an HA server
needs to send a lease update to its peers to notify them of the change to the
lease, it will park the client response until the peers acknowledge the lease
update. At that point, the server will unpark the response and send it to the
client. This applies to client queries which cause lease changes, such as
DHCPREQUEST for DHCPv4 and Request, Renew, and Rebind for DHCPv6. It does not
apply to DHPCDISCOVERs (v4) or Solicits (v6).
There is a global parameter, ``parked-packet-limit``, that may be used to limit
the number of responses that may be parked at any given time. This acts as a
form of congestion handling and protects the server from being swamped when the
volume of client queries is outpacing the server's ability to respond. Once the
limit is reached, the server emits a log and drops any new responses until
parking spaces are available.
In general, smaller values for the parking lot limit are likely to cause more
drops but with shorter response times. Larger values are likely to result in
fewer drops but with longer response times. Currently, the default value for
``parked-packet-limit`` is 256.
.. warning::
Using too small a value may result in an unnecessarily high drop rate, while
using too large a value may lead to response times that are simply too long
to be useful. A value of 0, while allowed, disables the limit altogether, but
this is highly discouraged as it may lead to Kea servers becoming
unresponsive to clients. Choosing the best value is very site-specific; we
recommend users initially leave it at the default value of 256 and observe
how the system behaves over time with varying load conditions.
::
"Dhcp6": {
// Limit the number of concurrently parked packets to 128.
"parked-packet-limit": 128,
"hooks-libraries": [
{
"library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so",
"parameters": { }
},
{
"library": "/usr/lib/kea/hooks/libdhcp_ha.so",
"parameters": {
"high-availability": [ {
"this-server-name": "server1",
...
} ]
}
},
...
],
...
}
.. note::
While ``parked-packet-limit`` is not specifically tied to HA, currently HA
is the only ISC hook that employs packet parking.
.. _ha-maintenance:
Controlled Shutdown and Maintenance of DHCP Servers

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

@@ -50,15 +50,15 @@ offering a lease to client if all of the following conditions are true:
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
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
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
@@ -68,7 +68,8 @@ When the ping check library is loaded, in response to a DHCPDISCOVER the
construct a DHCPOFFER.
2. Park the DHCPOFFER and request a ping-check from the ping-check hook
library via its `lease4_offer` callout.
library via its ``lease4_offer`` callout. Refer to :ref:`parked-packet-limit` for
a basic introduction to packet parking.
3. The callout will test conditions described above. If they are not
satisfied it will return without conducting a check, and the server
@@ -114,17 +115,17 @@ Configuration
The ping-check hook library currently supports the following configuration parameters
that may be set at the global and subnet levels. Subnet values override global values.
- `enable-ping-check` - Enables or disables ping checking at a given scope.
- ``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.
- ``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.
- ``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.
- ``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 at the global level:
- `ping-channel-threads` - In multi-threaded mode, this is the number of threads in the channel's thread pool. The default is 0 which instructs the library to use the same number of threads as Kea core. The value is ignored if given when Kea is in single-threaded mode.
- ``ping-channel-threads`` - In multi-threaded mode, this is the number of threads in the channel's thread pool. The default is 0 which instructs the library to use the same number of threads as Kea core. The value is ignored if given when Kea is in single-threaded mode.
The following configuration excerpt illustrates global level configuration:

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

@@ -364,6 +364,78 @@ The Limits hook uses user-context in classes and subnets to set parameters. For
}
}
.. _parked-packet-limit:
Parked-Packet Limit
~~~~~~~~~~~~~~~~~~~
Kea servers contain a mechanism by which the response to a client packet may
be held, pending completion of hook library work. We refer to this as parking
the packet. When work is ready to continue, the server will unpark the response
and continue processing.
There is a global parameter, ``parked-packet-limit``, that may be used to limit
the number of responses that may be parked at any given time. This acts as a
form of congestion handling and protects the server from being swamped when the
volume of client queries is outpacing the server's ability to respond. Once the
limit is reached, the server emits a log and drops any new responses until
parking spaces are available.
In general, smaller values for the parking lot limit are likely to cause more
drops but with shorter response times. Larger values are likely to result in
fewer drops but with longer response times. Currently, the default value for
``parked-packet-limit`` is 256.
.. warning::
Using too small a value may result in an unnecessarily high drop rate, while
using too large a value may lead to response times that are simply too long
to be useful. A value of 0, while allowed, disables the limit altogether, but
this is highly discouraged as it may lead to Kea servers becoming
unresponsive to clients. Choosing the best value is very site-specific; we
recommend users initially leave it at the default value of 256 and observe
how the system behaves over time with varying load conditions.
Here is an example of the global parameter used with ischooklib:`libdhcp_ha.so`.
It lowers the number of concurrently parked packets to 128.
.. code-block:: json
{
"Dhcp6": {
// Limit the number of concurrently parked packets to 128.
"parked-packet-limit": 128
"hooks-libraries": [
{
"library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so"
},
{
"library": "/usr/lib/kea/hooks/libdhcp_ha.so",
"parameters": {
"high-availability": [
{
"mode": "hot-standby",
"peers": [
{
"name": "server1",
"role": "primary",
"url": "http://127.0.0.1:8080/"
},
{
"name": "server2",
"role": "standby",
"url": "http://127.0.0.1:8088/"
}
],
"this-server-name": "server1"
}
]
}
}
],
}
}
Available Hook Libraries
========================