--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY mdash "—" >
+]>
+<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>
+
+ <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
+ client.</para>
+
+ <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>
+
+ <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.
+ </para>
+
+ <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:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <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>
+ </listitem>
+ <listitem>
+ <simpara>Update DNS, i.e. remove any DNS entries associated with
+ the expired lease.</simpara>
+ </listitem>
+ <listitem>
+ <simpara>Update lease information in the lease database to
+ indicate that the lease is now available for re-assignment.</simpara>
+ </listitem>
+ <listitem>
+ <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>
+ </listitem>
+ </itemizedlist>
+
+ <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>
+
+ <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:
+
+<screen>
+"Dhcp4": {
+ ...
+
+ "expired-leases-processing": {
+ "reclaim-timer-wait-time": 5,
+ "max-reclaim-leases": 0,
+ "max-reclaim-time": 0,
+ "flush-reclaimed-timer-wait-time": 0,
+ },
+
+ ...
+}
+</screen>
+ </para>
+
+ <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.
+
+<screen>
+
+| c1 | | c2 | |c3| | c4 |
+|<---->|<---------->|<-->|<---------->|<>|<---------->|<-->|
+---------------------------------------------------------------->
+| | 5s | | 5s | | 5s | | time
+
+</screen>
+
+ </para>
+ <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>
+
+ <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>
+
+ <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:
+
+<screen>
+"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,
+ },
+
+ ...
+}
+
+</screen>
+
+ </para>
+
+ <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.
+
+<screen>
+
+| c1 | | c2 | | c3 | | c4 |
+|<-->|<-------------->|<-->|<-------------->|<-->|<-------------->|<-->|<--
+------------------------------------------------------------------------------>
+|50ms| 3s |50ms| 3s |50ms| 3s |50ms| time
+
+</screen>
+
+ </para>
+
+ <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>
+
+ <para>Setting the <command>reclaim-timer-wait-time</command> to 0 disables
+ periodic reclamation of the expired leases.</para>
+
+ </section>
+
+ <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>
+
+ <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>
+
+ <para>Consider the following configuration:
+
+<screen>
+"Dhcp4": {
+ ...
+
+ "expired-leases-processing": {
+ "reclaim-timer-wait-time": 3,
+ "hold-reclaimed-time": 1800,
+ "flush-reclaimed-timer-wait-time": 5
+ },
+
+ ...
+}
+</screen>
+
+ </para>
+
+ <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>
+
+ <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>
+
+ <itemizedlist>
+ <listitem>
+ <simpara><command>reclaim-timer-wait-time</command> = 10 [seconds]</simpara>
+ </listitem>
+ <listitem>
+ <simpara><command>flush-reclaimed-timer-wait-time</command> = 25 [seconds]</simpara>
+ </listitem>
+ <listitem>
+ <simpara><command>hold-reclaimed-time</command> = 3600 [seconds]</simpara>
+ </listitem>
+ <listitem>
+ <simpara><command>max-reclaim-leases</command> = 100 </simpara>
+ </listitem>
+ <listitem>
+ <simpara><command>max-reclaim-time</command> = 250 [milliseconds]</simpara>
+ </listitem>
+ <listitem>
+ <simpara><command>unwarned-reclaim-cycles</command> = 5</simpara>
+ </listitem>
+ </itemizedlist>
+
+ <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>
+
+ </section>
+
+</chapter>
projects / thirdparty / kea.git / commitdiff
