Commit 74e140a3 authored by Marcin Siodelski's avatar Marcin Siodelski
Browse files

[3979] Added new chapter about lease reclamation to the User Guide.

parent 360b7400
......@@ -6,8 +6,8 @@ dist_doc_DATA = $(DOCS)
dist_html_DATA = $(HTMLDOCS) kea-guide.css
DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml
DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml logging.xml ddns.xml hooks.xml
DOCBOOK += libdhcp.xml lfc.xml stats.xml ctrl-channel.xml faq.xml
DOCBOOK += keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml logging.xml
DOCBOOK += ddns.xml hooks.xml libdhcp.xml lfc.xml stats.xml ctrl-channel.xml faq.xml
DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml
......@@ -67,6 +67,8 @@
<xi:include xmlns:xi="" href="dhcp6-srv.xml" />
<xi:include xmlns:xi="" href="lease-expiration.xml" />
<xi:include xmlns:xi="" href="ddns.xml" />
<xi:include xmlns:xi="" href="lfc.xml" />
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"" [
<!ENTITY mdash "&#x2014;" >
<chapter id="lease-expiration">
<title>Lease Expiration in DHCPv4 and DHCPv6</title>
<para>The major role of the DHCP server is to assign addresses or/and
delegate prefixes to the DHCP clients. These addresses and delegated
prefixes are often referred to as 'leases'. The leases are typically
assigned to the clients for a finite amount of time, known as
'valid lifetime'. The DHCP client willing to continue using the assigned
leases, will periodically renew them by sending appropriate message
to the DHCP server. The DHCP server records the time when the lease
is renewed and calculates a new expiration time for it.
<para>If the client does not renew a lease and its valid lifetime
elapses, the lease is considered expired. There are many situations
when the client may cease lease renewals.
The most obvious one is the shutdown of the machine running the
<para>The DHCP server makes expired leases available for assignment.
This process is referred to as 'lease reclamation', and consequently
each expired lease made available for assignment is called 'reclaimed'.
The DHCP server should reclaim an expired lease as soon as it detects
that it has expired. One possible way in which the server may detect
expiration is when it is trying to allocate a lease to a client and
it finds this lease is already present in the database. If this lease
is expired, it may be allocated to the same or another client, but it
must be first reclaimed. Another way the server detects
expired leases is by periodically quering the lease database. The
further sections of this chapter explain how to configure the server
to periodically query for the expired leases and how to minimize the
impact of the periodic leases reclamation process on the server's
responsiveness. Finally, the 'lease affinity' is explained, which
provides means to assign the same lease to the returning client
after its lease has expired.
<para>Although, all configuration examples in this section are provided
for the DHCPv4 server, the same parameters may be used for the
DHCPv6 server configuration.
<section id="lease-reclamation">
<title>Lease Reclamation</title>
<para>The lease reclamation is a process in which an expired lease
becomes available for assignment to the same or a different client.
This process involves the following steps for each reclaimed lease:
<simpara>Invoke callouts for the <command>lease4_expire</command> or
<command>lease6_expire</command> hook points, if hook libraries
supporting those callouts are currently loaded.</simpara>
<simpara>Update DNS, i.e. remove any DNS entries associated with
the expired lease.</simpara>
<simpara>Update lease information in the lease database to
indicate that the lease is now available for re-assignment.</simpara>
<simpara>Update statistics of the server, which includes
increasing the number of reclaimed leases and decreasing the
number of assigned addresses or delegated prefixes etc.</simpara>
<para>Please refer to the <xref linkend="dhcp-ddns-server"/> to see
how to configure the DNS updates in Kea, and to the
<xref linkend="hooks-libraries"/> for information about using
hooks libraries.</para>
<section id="lease-reclaim-config">
<title>Configuring Leases Reclamation</title>
<para>Kea can be configured to periodically detect and process expired
leases. During this process the lease entries in the database are
modified or removed, therefore the server will not process incoming DHCP
messages to avoid issues with concurrent access to database information.
As a result, the server will be unresponsive when the leases reclamation
is performed, the DHCP queries will accumulate and responses will be
sent once the leases reclamation cycle is complete.</para>
<para>In the deployments where the response time is critical, the
administrators want to minimize the interruptions in the service
caused by the processing of expired leases. Kea provides a set of
configuration parameters to control the frequency of leases reclamation,
the maximum number of leases processed in a single cycle and the
timeout after which the reclamation should be interrupted. The
following configuration examples demonstrate how these parameters
can be used:
"Dhcp4": {
"expired-leases-processing": {
"reclaim-timer-wait-time": 5,
"max-reclaim-leases": 0,
"max-reclaim-time": 0,
"flush-reclaimed-timer-wait-time": 0,
<para>The first parameter is expressed in seconds and specifies an
interval between the two consecutive lease reclamation cycles. This
is explained on the following diagram.
| c1 | | c2 | |c3| | c4 |
| | 5s | | 5s | | 5s | | time
<para>This diagram shows 4 leases reclamation cycles of variable duration.
Note that the duration of the reclamation cycle depends on the number
of expired leases detected and processed in the particular cycle. This
duration is also usually significantly shorter than the interval between
the cycles.
<para>According to the <command>reclamim-timer-wait-time</command> the
server keeps fixed intervals of 5 seconds between the end of one cycle
and the start of the next cycle. This guarantees the presence of
5s long periods during which the server remains responsive to DHCP
queries and does not perform leases reclamation. The
<command>max-reclaim-leases</command> and
<command>max-reclaim-time</command> are set to 0, which implies that
there is no restriction on the maximum number of reclaimed leases
in the particular cycle, and the maximum duration of each cycle.
<para>In the deployments with high lease pool utilization, relatively
short valid lifetimes and clients often disconnecting allowing the
leases to expire, the number of expired leases requiring reclamation
at the given time may rise significantly. In this case it is often
desired to apply restrictions on the maximum duration of the leases
reclamation cycle or the number of leases that can be reclaimed in
this cycle. The following configuration demonstrates how this
can be done:
"Dhcp4": {
"expired-leases-processing": {
"reclaim-timer-wait-time": 3,
"max-reclaim-leases": 100,
"max-reclaim-time": 50,
"unwarned-reclaim-cycles": 10,
"flush-reclaimed-timer-wait-time": 0,
<para>The <command>max-reclaim-leases</command> parameter limits the number
of leases reclaimed in the single cycle to 100. The
<command>max-reclaim-time</command> limits the maximum duration of each
cycle to 50ms. The lease reclamation cycle will be interrupted when
first of these limitations is hit. The reclamation of all unreclaimed
leases will be attempted in subsequent cycles.</para>
<para>The following diagram illustrates the behavior of the system in the
presence of many expired leases, when the limits are applied for the
reclamation cycles.
| c1 | | c2 | | c3 | | c4 |
|50ms| 3s |50ms| 3s |50ms| 3s |50ms| time
<para>The diagram demonstrates the case when each reclamation cycle would take
more than 50ms, and thus is interrupted according to the value of the
<command>max-reclaim-time</command>. This results in equal durations of
all reclamation cycles over time. Note that in this example the limitation
of maximum 100 leases is not hit. This may be the case when the database
transactions are slow or the callouts in the hook libraries attached to
the server are slow. In any case, the choice between the selecting the
specific number of leases or the maximum time for the lease reclamation
strongly depends on the particular deployment, used lease database
backend, hooks libraries etc.</para>
<para>If the limits are applied on the maximum number of reclaimed leases
or the maximum time for a single reclamation cycle, there is a risk
that the server will not be able to catch up the number of expired
leases to reclaim. This should not be the problem if the server is
dealing with a temporary burst of expirations, because it should be
able to eventually deal with them over time. However, if leases
expire at the high rate for a longer period of time, the unreclaimed
leases will pile up in the database. In order to notify the administrator
that the current configuration does not satisfy the needs for
reclamation of expired leases, the server issues a warning message
in the log, if it was unable to reclaim all leases within the last
couple of reclamation cycles. The number of cycles after which such
warning is issued is specified with the
<command>unwarned-reclaim-cycles</command> configuration parameter.
<para>Setting the <command>reclaim-timer-wait-time</command> to 0 disables
periodic reclamation of the expired leases.</para>
<section id="lease-affinity">
<title>Configuring Lease Affinity</title>
<para>Suppose that the laptop goes to a sleep mode after a period of user's
inactivity. While the laptop is in the sleep mode, the DHCP client
running on it will not renew leases obtained from the server and the
leases will eventually expire. When the laptop wakes up from the
sleep mode, it is often desired that it can continue using previous
IP addresses. In order to facilitate it, the server needs to correlate
returning clients with the expired leases they were using in the past.
When the client returns, the server will first check for those
leases and re-assign them if they are still available (not assigned
to another client). The ability of the server to re-assign the same
lease to the returning client is referred to as 'lease affinity'.
<para>When the lease affinity is enabled, the server would still
reclaim leases according to the parameters described in
<xref linkend="lease-reclaim-config"/>, but the reclaimed leases
will be held in the database (rather than removed) for the specified
amount of time. When the client returns, the server will first check
if there are any reclaimed leases associated with this client and
re-assign them if possible. However, it is important to note that
any reclaimed lease may be assigned to another client if that client
asks for it. Therefore, the lease affinity provides no guarantee that
the reclaimed lease will be available for the client who used it
before. It merely increases the chances for the client to be assigned
the same lease. If the lease pool is small (mostly applies to DHCPv4
for which address space is small), there is an increased likelihood
that the expired lease will be hijacked by another client.
<para>Consider the following configuration:
"Dhcp4": {
"expired-leases-processing": {
"reclaim-timer-wait-time": 3,
"hold-reclaimed-time": 1800,
"flush-reclaimed-timer-wait-time": 5
<para>The <command>hold-reclaim-time</command> specifies how many seconds
after an expiration a reclaimed lease should be held in the database
for re-assignment to the same client. In the example given above, the
reclaimed leases will be held for 30 minutes (1800s) after their
expiration. During this time, the server will likely be able to
re-assign the same lease to the returning client, unless another client
requests this lease and the server assigns it.</para>
<para>The server must occasionally remove reclaimed leases for which the
time indicated by <command>hold-reclaim-time</command> elapsed. The
<command>flush-reclaimed-timer-wait-time</command> controls how
often the server removes such leases. In the example provided
above, the server will initiate removal of leases 5 seconds after
the previous removal attempt was completed. Setting this value to 0
disables lease affinity, in which case leases will be removed from the
lease database when they are reclaimed. If the lease affinity is
enabled, it is recommended that this parameter is set to significantly
higher value than the <command>reclaim-timer-wait-time</command>
because timely removal of expired-reclaimed leases is not critical,
while this removal impacts the server's responsiveness, because the
server doesn't process DHCP messages while it removes leases from
the database.</para>
<section id="lease-reclamation-defaults">
<title>Default Configuration Values for Leases Reclamation</title>
<para>The following list presents all configuration parameters
pertaining to processing expired leases with their default values:</para>
<simpara><command>reclaim-timer-wait-time</command> = 10 [seconds]</simpara>
<simpara><command>flush-reclaimed-timer-wait-time</command> = 25 [seconds]</simpara>
<simpara><command>hold-reclaimed-time</command> = 3600 [seconds]</simpara>
<simpara><command>max-reclaim-leases</command> = 100 </simpara>
<simpara><command>max-reclaim-time</command> = 250 [milliseconds]</simpara>
<simpara><command>unwarned-reclaim-cycles</command> = 5</simpara>
<para>The default value for any parameter is used when this parameter not
explicitly specified in the configuration. Also, the
<command>expired-leases-processing</command> map may be omitted entirely
in the configuration, in which case the default values are used for all
parameters listed above.</para>
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment