1.. _congestion-handling: 2 3******************* 4Congestion Handling 5******************* 6 7.. _congestion-handling-background: 8 9What is Congestion? 10=================== 11 12Congestion occurs when servers are subjected to client queries faster 13than those queries can be processed. As a result, the servers begin accumulating 14a backlog of pending queries. The longer the high rate of traffic 15continues, the farther behind the servers fall. Depending on the client 16implementations, those that fail to get leases either give up or simply 17continue to retry forever. In the former case, the server may eventually 18recover, but the latter case is a vicious cycle from which the server is 19unable to escape. 20 21In a well-planned deployment, the number and capacity of servers is 22matched to the maximum client loads expected. As long as capacity is 23matched to load, congestion does not occur. If the load is routinely too 24heavy, then the deployment needs to be re-evaluated. Congestion 25typically occurs when there is a network event that causes overly large 26numbers of clients to simultaneously need leases, such as recovery after 27a network outage. 28 29The goal of congestion handling is to help servers mitigate the peak in 30traffic by fulfilling as many of the most relevant requests as possible 31until the congestion subsides. 32 33Prior to Kea 1.5, kea-dhcp4 and kea-dhcp6 read inbound packets directly 34from the interface sockets in the main application thread, which meant 35that packets waiting to be processed were held in socket buffers 36themselves. Once these buffers filled, any new packets were discarded. 37Under swamped conditions, the servers ended up processing client packets 38that were no longer relevant, or worse, were redundant. In other words, 39the packets waiting in the FIFO socket buffers became increasingly 40stale. 41 42.. _congestion-handling-solution: 43 44Configuring Congestion Handling 45=============================== 46 47Kea 1.5 introduced the Congestion Handling feature. Congestion handling 48offers the ability to configure the server to use a separate thread to 49read packets from the interface socket buffers. As the thread reads 50packets from the buffers, they are added to an internal packet queue, 51and the server's main application thread processes packets from this 52queue rather than from the socket buffers. By structuring it this way, a 53configurable layer has been introduced which can make decisions on which 54packets to process, how to store them, and the order in which they are 55processed by the server. 56 57The default packet queue implementation for both kea-dhcp4 and kea-dhcp6 58is a simple ring buffer. Once it reaches capacity, new packets get added 59to the back of the queue by discarding packets from the front of the 60queue. Rather than always discarding the newest packets, Kea now always 61discards the oldest packets. The capacity of the buffer, i.e. the maximum 62number of packets the buffer can contain, is configurable. A reasonable 63starting point would be to match the capacity to the number of leases 64per second a specific installation of Kea can handle. Please note that this 65figure varies widely depending on the specifics of an individual deployment. 66 67As there is no one algorithm that will best handle the dynamics of all 68sites, and because over time new approaches will evolve, the packet 69queue is implemented as a plug-in, which can be replaced by a custom queue 70implementation via a hook library. This should make it straightforward 71for interested parties to experiment with their own solutions. 72(Developers can refer to isc::dhcp::PacketQueue and 73isc::dhcp::PacketQueueMgr, described in the 74`Kea Developer's Guide <https://reports.kea.isc.org/dev_guide/index.html>`__.) 75 76Packet queue behavior is configured in both kea-dhcp4 and kea-dhcp6 77servers through an optional, top-level, configuration element, 78``dhcp-queue-control``. Omitting this element disables packet queueing: 79 80:: 81 82 "dhcp-queue-control": { 83 "enable-queue": true|false, 84 "queue-type": "queue type", 85 "capacity" : n 86 } 87 88where: 89 90- ``enable-queue`` true|false - enables or disables packet queueing. 91 When true, the server processes packets from the packet queue, which 92 is filled by a separate thread. When false, the server processes 93 packets directly from the socket buffers in the main thread. It is 94 disabled by default. 95 96- ``queue-type`` - name of the queue implementation to use. This value 97 exists so that custom implementations can be registered (via a hook 98 library) and then selected. There is a default packet queue 99 implementation that is pre-registered during server start up: 100 "kea-ring4" for kea-dhcp4 and "kea-ring6" for kea-dhcp6. 101 102- ``capacity`` = n [packets] - this is the maximum number of packets the 103 queue can hold before packets are discarded. The optimal value for 104 this is extremely site-dependent. The default value is 64 for both 105 kea-ring4 and kea-ring6. 106 107The following example enables the default packet queue for kea-dhcp4, 108with a queue capacity of 250 packets: 109 110:: 111 112 "Dhcp4": 113 { 114 ... 115 "dhcp-queue-control": { 116 "enable-queue": true, 117 "queue-type": "kea-ring4", 118 "capacity" : 250 119 }, 120 ... 121 } 122 123The following example enables the default packet queue for kea-dhcp6, 124with a queue capacity of 300 packets: 125 126:: 127 128 "Dhcp6": 129 { 130 ... 131 "dhcp-queue-control": { 132 "enable-queue": true, 133 "queue-type": "kea-ring6", 134 "capacity" : 300 135 }, 136 ... 137 } 138 139.. note: 140 141 Currently the congestion handling is incompatible with multi-threading: 142 when both are enabled the congestion handling is silently disabled. 143