From f64300a95e724d460c6ea861d40f4ea28aa5065d Mon Sep 17 00:00:00 2001 From: Thomas Markwalder Date: Tue, 13 Nov 2018 08:54:49 -0500 Subject: [PATCH] [#260,!120] Added Congestion Handling chapter to admin guide Added a new chapter on Congestion Handling rather than independent sections for kea-dhcp4 and 6. modified: doc/guide/Makefile.am modified: doc/guide/kea-guide.xml new file: doc/guide/congestion-handling.xml --- doc/guide/Makefile.am | 2 +- doc/guide/congestion-handling.xml | 124 ++++++++++++++++++++++++++++++ doc/guide/kea-guide.xml | 2 + 3 files changed, 127 insertions(+), 1 deletion(-) create mode 100644 doc/guide/congestion-handling.xml diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index 4245738d9a..e59aca09e3 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -10,7 +10,7 @@ DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml logging. DOCBOOK += ddns.xml hooks.xml hooks-class-cmds.xml hooks-ha.xml hooks-host-cache.xml DOCBOOK += hooks-lease-cmds.xml hooks-radius.xml hooks-stat-cmds.xml libdhcp.xml DOCBOOK += lfc.xml stats.xml ctrl-channel.xml classify.xml shell.xml agent.xml -DOCBOOK += netconf.xml api.xml +DOCBOOK += netconf.xml api.xml congestion-handling.xml EXTRA_DIST = $(DOCBOOK) diff --git a/doc/guide/congestion-handling.xml b/doc/guide/congestion-handling.xml new file mode 100644 index 0000000000..2c11acc004 --- /dev/null +++ b/doc/guide/congestion-handling.xml @@ -0,0 +1,124 @@ + + + + + Congestion Handling in DHCPv4 and DHCPv6 + Prior to Kea 1.5, kea-dhcp4 and kea-dhcp4 read inbound packets directly + from the interface sockets in the main application thread. This meant that + packets waiting to be processed were held in socket buffers themselves. Once + these buffers fill any new packets are discarded. Under swamped conditions + the servers can end up processing client packets that may no longer be + relevant, or worse are redundant. In other words, the packets waiting in + the FIFO socket buffers become more and more stale. + + + Kea 1.5 introduces a new feature referred to as Congestion Handling. + Congestion handling offers the ability to configure the server to use a + separate thread to read packets from the interface socket buffers. As the + thread reads packets from the buffers they are added to an internal packet + queue. The server's main application thread process packets from this queue + rather than the socket buffers. By structuring it this way, we've introduced + a configurable layer which can make decisions on which packets to process, + how to store them, and the order in which they are processed by the server. + + + The default packet queue implemenation for both kea-dhcp4 and kea-dhcp6 + is a simple ring buffer. Once it reaches capacity, new packets get added to + the back of queue by discarding packets from the front of queue. Rather than + always discarding the newest packets, we now always discard the oldest + packets. The capacity of the buffer, (i.e the maximum number of packets the + buffer can contain) is configurable. A reasonable starting point would be to + match the queue size to the number of leases per second your installation of + Kea can handle (Please note this figure varies widely depending on your + configuration). We anticipate adding more knobs as we learn from experience, + testing, and user feedback. + + + As there is no one algorithm that will best handle the dynamncis of + all sites, and because over time new approaches will evolve, the packet + queue is implemented as plug-in, which can replaced by a custom queue + implementation via hook library. This should make it straight forward + for interested parties to experiment with their own solutions. (Developers + may refer to isc::dhcp::PacketQueue and isc::dhcp::PacketQueueMgr, in our + Developer's guide). + + + Packet queue behavior is configured in both kea-dhcp4 and kea-dhcp6 + servers through an optional, top level configuration element, + 'dhcp-queue-control' (Omitting this element disables packet queueing): + + ... + "dhcp-queue-control": { + "enable-queue": true|false, + "queue-type": "queue type", + "capacity" : n + } + + where: + + + enable-queue true|false. Enables or + disables packet queueing. When true, the server will process packets + from the packet queue, which is filled by a separate thread. When + false, the server will process packets directly from the socket buffers + in the main thread (as done in all releases prior Kea 1.5). Packet + queuing is disabled by default. + + + + queue-type name of the queue implementation + to use. This value exists such that custom implementations can be + registered (via hook lib) and then selected. As mentioned earlier, + there is a default implementation registered: "kea-ring4" for kea-dhcp4 + and "kea-ring6" for kea-dhcp6. + + + + capacity = n [packets]. This is the + maximum number of packets the packet queue can hold before packets + are discarded. The optimal value for this is extremely site dependent. + The default value for is 500 for both kea-ring4 and kea-ring6. + + + + + The following example enables the default packet queue for kea-dhcp4, + with a queue capactiy fo 250 packets: + +"Dhcp4": +{ + ... + "dhcp-queue-control": { + "enable-queue": true, + "queue-type": "kea-ring4", + "capacity" : 250 + }, + ... +} + + + The following example enables the default packet queue for kea-dhcp6, + with a queue capactiy fo 300 packets: + +"Dhcp6": +{ + ... + "dhcp-queue-control": { + "enable-queue": true, + "queue-type": "kea-ring6", + "capacity" : 300 + }, + ... +} + + + + The number of parameters and plug-ins is expected to grow over time. + + diff --git a/doc/guide/kea-guide.xml b/doc/guide/kea-guide.xml index 25ae20e6c8..3b98f850b7 100644 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@ -72,6 +72,8 @@ + + -- 2.47.2