kea/doc/guide/congestion-handling.xml

<!--
 - Copyright (C) 2018-2019 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>
  <section xml:id="congeston-handling-background">
  <title>What is Congestion?</title>
  <para>Congestion occurs when servers are subjected to client queries
  faster than they can be processed. As a result, the servers begin
  accumulating a backlog of pending queries. The longer the high rate of
  traffic continues the farther behind the servers fall. Depending on the
  client implementations, those that fail to get leases either give up or simply
  continue to retry forever. In the former case, the server may eventually
  recover, but the latter case is a vicious cycle from which the server is unable
  to escape.
  </para>

  <para>
  In a well-planned deployment, the number and capacity of servers is matched
  to the maximum client loads expected. As long as capacity is matched to
  load, congestion does not occur. If the load is routinely too heavy, then
  the deployment needs to be re-evaluated. Congestion typically occurs when
  there is a network event that causes overly large numbers of clients to
  simultaneously need leases, such as recovery after a network outage.
  </para>

  <para>
  The goal of congestion handling is to help servers mitigate the peak
  in traffic by fulfilling as many of the most relevant requests as possible
  until the congestion subsides.
  </para>

  <para>Prior to Kea 1.5, kea-dhcp4 and kea-dhcp4 read inbound packets directly
  from the interface sockets in the main application thread, which meant that
  packets waiting to be processed were held in socket buffers themselves. Once
  these buffers filled, any new packets were discarded. Under swamped conditions,
  the servers ended up processing client packets that were no longer
  relevant, or worse were redundant. In other words, the packets waiting in
  the FIFO socket buffers became increasingly stale.
  </para>
  </section>
  <section xml:id="congeston-handling-solution">
  <title>Configuring Congestion Handling</title>
  <para>Kea 1.5 introduced the Congestion Handling feature.
  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, and the server's main application thread processes packets from this queue
  rather than from the socket buffers. By structuring it this way, a configurable layer
  has been introduced 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 the queue by discarding packets from the front of the queue. Rather than
  always discarding the newest packets, Kea now always discards 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 capacity to the number of leases per second your installation of
  Kea can handle. Please note that this figure varies widely depending on the
  specifics of your deployment.
  </para>

  <para>As there is no one algorithm that will best handle the dynamics of
  all sites, and because over time new approaches will evolve, the packet
  queue is implemented as a plug-in, which can replaced by a custom queue
  implementation via a hook library. This should make it straightforward
  for interested parties to experiment with their own solutions. (Developers
  can refer to isc::dhcp::PacketQueue and isc::dhcp::PacketQueueMgr, described in the Kea
  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 processes packets
        from the packet queue, which is filled by a separate thread. When
        false, the server processes packets directly from the socket buffers
        in the main thread. It is
        disabled by default.
        </simpara>
      </listitem>
      <listitem>
        <simpara><command>queue-type</command> name of the queue implementation
        to use. This value exists so that custom implementations can be
        registered (via hook library) and then selected. There is a default
        packet queue implementation that is pre-registered during server
        start up: "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 queue can hold before packets
        are discarded. The optimal value for this is extremely site-dependent.
        The default value 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 capacity of 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 capacity of 300 packets:
<screen>
"Dhcp6":
{
    ...
   "dhcp-queue-control": {
       "enable-queue": true,
       "queue-type": "kea-ring6",
       "capacity" : 300
    },
    ...
}
</screen>
  </para>
  </section>
</chapter>