1.. _lease-expiration: 2 3**************** 4Lease Expiration 5**************** 6 7The primary role of the DHCP server is to assign addresses and/or 8delegate prefixes to DHCP clients. These addresses and prefixes are 9often referred to as "leases." Leases are typically assigned to clients 10for a finite amount of time, known as the "valid lifetime." DHCP clients 11who wish to continue using their assigned leases periodically renew 12them by sending the appropriate message to the DHCP server. The DHCP 13server records the time when these leases are renewed and calculates new 14expiration times for them. 15 16If the client does not renew a lease before its valid lifetime elapses, 17the lease is considered expired. There are many situations when the 18client may cease lease renewals; a common scenario is when the machine 19running the client shuts down for an extended period of time. 20 21The process through which the DHCP server makes expired leases available 22for reassignment is referred to as "lease reclamation" and expired 23leases returned to availability through this process are referred to as 24"reclaimed." The DHCP server attempts to reclaim an expired lease as 25soon as it detects that it has expired. The server has several possible 26ways to detect expiration: it may attempt to allocate a lease to a 27client but find this lease already present in the database and expired; 28or it can periodically query the lease database for expired leases. 29Regardless of how an expired lease is detected, it must be reclaimed 30before it can be assigned to a client. 31 32This chapter explains how to configure the server to periodically query 33for the expired leases, and how to minimize the impact of the periodic 34lease reclamation process on the server's responsiveness. Finally, it 35explains "lease affinity," which provides the means to assign the same 36lease to a returning client after its lease has expired. 37 38Although all configuration examples in this section are provided for the 39DHCPv4 server, the same parameters may be used for DHCPv6 server 40configuration. 41 42.. _lease-reclamation: 43 44Lease Reclamation 45================= 46 47Lease reclamation is the process through which an expired lease becomes 48available for assignment to the same or a different client. This process 49involves the following steps for each reclaimed lease: 50 51- Invoke callouts for the ``lease4_expire`` or ``lease6_expire`` hook 52 points, if hook libraries supporting those callouts are currently 53 loaded. 54 55- Update the DNS, i.e. remove any DNS entries associated with the 56 expired lease. 57 58- Update lease information in the lease database to indicate that the 59 lease is now available for re-assignment. 60 61- Update counters on the server, a process that includes increasing the 62 number of reclaimed leases and decreasing the number of assigned 63 addresses or delegated prefixes. 64 65Please refer to :ref:`dhcp-ddns-server` to see how to configure DNS 66updates in Kea, and to :ref:`hooks-libraries` for information about 67using hooks libraries. 68 69.. _lease-reclamation-defaults: 70 71Lease Reclamation Configuration Parameters 72========================================== 73 74The following list presents all configuration parameters pertaining to 75processing expired leases with their default values: 76 77- ``reclaim-timer-wait-time`` - this parameter governs intervals 78 between the completion of the previous reclamation cycle and the start of the 79 next one. Specified in seconds. The default value is 10 [seconds]. 80 81- ``flush-reclaimed-timer-wait-time`` - this parameter controls how 82 often the server initiates the lease reclamation procedure. Expressed in 83 seconds. The default value is 25 [seconds]. 84 85- ``hold-reclaimed-time`` - this parameter governs how long the lease 86 should be kept after it is reclaimed. This enables lease affinity 87 when set to a non-zero value. Expressed in seconds. The default value 88 is 3600 [seconds]. 89 90- ``max-reclaim-leases`` - this parameter specifies the maximum number 91 of reclaimed leases that can be processed at one time. Zero means 92 unlimited (i.e. process all reclaimed leases). The default value is 93 100. 94 95- ``max-reclaim-time`` - this parameter specifies an upper limit to the 96 length of time a lease reclamation procedure can take. Zero means no time 97 limit. Expressed in milliseconds. The default value is 250 98 [milliseconds]. 99 100- ``unwarned-reclaim-cycles`` - if lease reclamation limits are 101 specified (``max-reclaim-leases`` and/or ``max-reclaim-time``), then 102 under certain circumstances the server may not be able to deal with 103 the leases to be reclaimed fast enough. This parameter specifies how many 104 consecutive clean-up cycles must end with remaining leases to be 105 processed before a warning is printed. The default is 5 [cycles]. 106 107The parameters are explained in more detail in the rest of this chapter. 108 109The default value for any parameter is used when the parameter is not 110explicitly specified in the configuration. If the 111``expired-leases-processing`` map is omitted entirely in the 112configuration, the default values are used for all 113parameters listed above. 114 115.. _lease-reclaim-config: 116 117Configuring Lease Reclamation 118============================= 119 120Kea can be configured to periodically detect and reclaim expired leases. 121During this process the lease entries in the database are modified or 122removed. While this is happening, the server will not process incoming 123DHCP messages to avoid issues with concurrent access to database 124information. As a result, the server will be unresponsive while lease 125reclamation is performed and DHCP queries will accumulate; responses 126will be sent once the lease-reclamation cycle is complete. 127 128In deployments where response time is critical, administrators may wish 129to minimize the interruptions in service caused by lease reclamation. 130To this end, Kea provides configuration parameters to control the 131frequency of lease reclamation cycles, the maximum number of leases 132processed in a single reclamation cycle, and the maximum amount of time 133a single reclamation cycle is allowed to run before being interrupted. 134The following examples demonstrate how these parameters can be used: 135 136:: 137 138 "Dhcp4": { 139 ... 140 141 "expired-leases-processing": { 142 "reclaim-timer-wait-time": 5, 143 "max-reclaim-leases": 0, 144 "max-reclaim-time": 0, 145 }, 146 147 ... 148 } 149 150The first parameter is expressed in seconds and specifies an interval 151between the two consecutive lease reclamation cycles. This is explained 152by the following diagram: 153 154:: 155 156 157 | c1 | | c2 | |c3| | c4 | 158 |<---->|<---------->|<-->|<---------->|<>|<---------->|<-->|<-- 159 ------------------------------------------------------------------> 160 | | 5s | | 5s | | 5s | | time 161 162This diagram shows four lease-reclamation cycles (c1 through c4) of 163variable duration. Note that the duration of the reclamation cycle 164depends on the number of expired leases detected and processed in the 165particular cycle. This duration is usually significantly shorter than 166the interval between the cycles. 167 168According to the ``reclaim-timer-wait-time``, the server keeps fixed 169intervals of five seconds between the end of one cycle and the start of 170the next cycle. This guarantees the presence of 5-second-long periods during 171which the server remains responsive to DHCP queries and does not perform 172lease reclamation. The ``max-reclaim-leases`` and ``max-reclaim-time`` 173are set to 0, which sets no restriction on the maximum number of leases 174reclaimed in the particular cycle, or on the maximum duration of each 175cycle. 176 177In deployments with high lease-pool utilization, relatively short valid 178lifetimes, and frequently disconnecting clients which allow leases to 179expire, the number of expired leases requiring reclamation at any given 180time may rise significantly. In this case, it is often desirable to 181apply restrictions to the maximum duration of a reclamation cycle or the 182maximum number of leases reclaimed in a cycle. The following 183configuration demonstrates how this can be done: 184 185:: 186 187 "Dhcp4": { 188 ... 189 190 "expired-leases-processing": { 191 "reclaim-timer-wait-time": 3, 192 "max-reclaim-leases": 100, 193 "max-reclaim-time": 50, 194 "unwarned-reclaim-cycles": 10, 195 }, 196 197 ... 198 } 199 200The ``max-reclaim-leases`` parameter limits the number of leases 201reclaimed in a single cycle to 100. The ``max-reclaim-time`` limits the 202maximum duration of each cycle to 50ms. The lease-reclamation cycle will 203be interrupted if either of these limitations is reached. The 204reclamation of any unreclaimed leases will be attempted in subsequent 205cycles. 206 207The following diagram illustrates the behavior of the system in the 208presence of many expired leases, when the limits are applied for the 209reclamation cycles: 210 211:: 212 213 214 | c1 | | c2 | | c3 | | c4 | 215 |<-->|<-------------->|<-->|<-------------->|<-->|<-------------->|<-->|<-- 216 ------------------------------------------------------------------------------> 217 |50ms| 3s |50ms| 3s |50ms| 3s |50ms| time 218 219This diagram demonstrates the case when each reclamation cycle takes 220more than 50ms, and thus is interrupted according to the value of the 221``max-reclaim-time``. This results in equal durations of all reclamation 222cycles over time. Note that in this example the limitation of the 223maximum 100 leases is not reached. This may be the case when database 224transactions or callouts in the hook libraries attached to the 225server are slow. Regardless, the chosen values for either the maximum 226number of leases or a maximum cycle time strongly depend on the 227particular deployment, the lease database backend being used, and any 228hooks libraries, etc. Administrators may need to experiment to tune the 229system to suit the dynamics of their deployment. 230 231It is important to realize that with the use of these limits, there is a 232risk that expired leases will accumulate faster than the server can 233reclaim them. This should not be a problem if the server is dealing with 234a temporary burst of expirations, because it should be able to 235eventually deal with them over time. However, if leases expire at a high 236rate for a long period of time, the unreclaimed leases will pile up in 237the database. To notify the administrator that the current configuration 238does not satisfy the needs for reclamation of expired leases, the server 239issues a warning message in the log if it is unable to reclaim all 240leases within several reclamation cycles. The number of cycles after 241which such a warning is issued is specified with the 242``unwarned-reclaim-cycles`` configuration parameter. 243 244Setting the ``reclaim-timer-wait-time`` to 0 disables periodic 245reclamation of the expired leases. 246 247.. _lease-affinity: 248 249Configuring Lease Affinity 250========================== 251 252Suppose that a laptop goes into sleep mode after a period of user 253inactivity. While the laptop is in sleep mode, its DHCP client will not 254renew leases obtained from the server and these leases will eventually 255expire. When the laptop wakes up, it is often desirable for it to 256continue using its previous assigned IP addresses. To facilitate this, 257the server needs to correlate returning clients with their expired 258leases. When the client returns, the server will first check for those 259leases and re-assign them if they have not been assigned to another 260client. The ability of the server to re-assign the same lease to a 261returning client is referred to as "lease affinity." 262 263When lease affinity is enabled (i.e. when ``hold-reclaimed-time`` is 264configured to a value greater than zero), the server will still reclaim 265leases according to the parameters described in :ref:`lease-reclaim-config`, 266but the reclaimed leases will be 267held in the database for a specified amount of 268time rather than removed. When the client returns, the server will first verify whether 269there are any reclaimed leases associated with this client and will 270re-assign them if possible. However, it is important to note that any 271reclaimed lease may be assigned to another client if that client 272specifically asks for it. Therefore, lease affinity does not guarantee 273that the reclaimed lease will be available for the client who used it 274before; it merely increases the chances of the client being assigned 275the same lease. If the lease pool is small - namely, in 276DHCPv4, for which address space is small - there is an increased 277likelihood that the expired lease will be assigned to another client. 278 279Consider the following configuration: 280 281:: 282 283 "Dhcp4": { 284 ... 285 286 "expired-leases-processing": { 287 "reclaim-timer-wait-time": 3, 288 "hold-reclaimed-time": 1800, 289 "flush-reclaimed-timer-wait-time": 5 290 }, 291 292 ... 293 } 294 295The ``hold-reclaim-time`` specifies how many seconds after an expiration 296a reclaimed lease should be held in the database for re-assignment to 297the same client. In the example given above, reclaimed leases will be 298held for 30 minutes (1800s) after their expiration. During this time, 299the server will likely be able to re-assign the same lease to the 300returning client, unless another client specifically requests this lease and the 301server assigns it. 302 303The server must periodically remove reclaimed leases for which the time 304indicated by ``hold-reclaim-time`` has elapsed. The 305``flush-reclaimed-timer-wait-time`` parameter controls how often the 306server removes such leases. In the example provided above, the server 307will initiate removal of such leases five seconds after the previous 308removal attempt was completed. Setting this value to 0 disables lease 309affinity, meaning leases will be removed from the lease database 310when they are reclaimed. If lease affinity is enabled, it is recommended 311that ``hold-reclaim-time`` be set to a value significantly higher than 312the ``reclaim-timer-wait-time``, as timely removal of expired-reclaimed 313leases is less critical than the removal process, which may impact 314server responsiveness. 315 316There is no guarantee that lease affinity will work every time; if a 317server is running out of addresses, it will reassign expired addresses 318to new clients. Also, clients can request specific addresses and the 319server will try to honor such requests if possible. Administrators who want to 320ensure a client keeps its address, even after periods of inactivity, 321should consider using host reservations or leases with very long lifetimes. 322 323.. _leases-reclamation-using-command: 324 325Reclaiming Expired Leases via Command 326===================================== 327 328The ``leases-reclaim`` command can be used to trigger lease reclamation at 329any time. Please consult the :ref:`command-leases-reclaim` section 330for details about using this command. 331