--- /dev/null
+<!--
+ - Copyright (C) 2018 Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+-->
+
+<!-- Converted by db4-upgrade version 1.1 -->
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="congestion-handling">
+ <title>Congestion Handling in DHCPv4 and DHCPv6</title>
+ <para>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.
+ </para>
+
+ <para>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.
+ </para>
+
+ <para>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.
+ </para>
+
+ <para>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).
+ </para>
+
+ <para>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):
+<screen>
+ ...
+ "dhcp-queue-control": {
+ "enable-queue": true|false,
+ "queue-type": "queue type",
+ "capacity" : n
+ }
+</screen>
+ where:
+ <itemizedlist>
+ <listitem>
+ <simpara><command>enable-queue</command> 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.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara><command>queue-type</command> 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.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara><command>capacity</command> = 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.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>The following example enables the default packet queue for kea-dhcp4,
+ with a queue capactiy fo 250 packets:
+<screen>
+"Dhcp4":
+{
+ ...
+ "dhcp-queue-control": {
+ "enable-queue": true,
+ "queue-type": "kea-ring4",
+ "capacity" : 250
+ },
+ ...
+}
+</screen>
+ </para>
+ <para> The following example enables the default packet queue for kea-dhcp6,
+ with a queue capactiy fo 300 packets:
+<screen>
+"Dhcp6":
+{
+ ...
+ "dhcp-queue-control": {
+ "enable-queue": true,
+ "queue-type": "kea-ring6",
+ "capacity" : 300
+ },
+ ...
+}
+</screen>
+ </para>
+ <para>
+ The number of parameters and plug-ins is expected to grow over time.
+ </para>
+</chapter>
projects / thirdparty / kea.git / commitdiff
