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

- 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

Author: andrei-pavel

doc/examples/kea4/all-keys-netconf.json

@@ -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.

doc/examples/kea4/all-keys.json

@@ -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.

doc/examples/kea6/all-keys-netconf.json

@@ -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,

doc/examples/kea6/all-keys.json

@@ -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,

doc/sphinx/arm/ext-radius.rst

@@ -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

doc/sphinx/arm/hooks-ha.rst

@@ -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

doc/sphinx/arm/hooks-ping-check.rst

@@ -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:
 

doc/sphinx/arm/hooks.rst

@@ -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
 ========================