-
- 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/.
+ - file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<para>The primary role of the DHCP server is to assign addresses and/or
delegate prefixes to DHCP clients. These addresses and prefixes are
- often referred to as "leases". Leases are typically assigned to clients
- for a finite amount of time, known as the "valid lifetime". DHCP clients who
- wish to continue using their assigned leases, will periodically renew them
+ often referred to as "leases." Leases are typically assigned to clients
+ for a finite amount of time, known as the "valid lifetime." DHCP clients who
+ wish to continue using their assigned leases will periodically renew them
by sending the appropriate message to the DHCP server. The DHCP server records
the time when these leases are renewed and calculates new expiration times
for them.
<para>If the client does not renew a lease before its valid lifetime
elapses, the lease is considered expired. There are many situations
- when the client may cease lease renewals. A common scenario is when
+ when the client may cease lease renewals; a common scenario is when
the machine running the client shuts down for an extended period of
time.</para>
<para> The process through which the DHCP server makes expired leases
available for reassignment is referred to as "lease reclamation" and expired
leases returned to availability through this process are referred to as
- "reclaimed".
+ "reclaimed."
The DHCP server attempts to reclaim an expired lease as soon as it detects
- that it has expired. One way in which the server detects expiration occurs
- when it is trying to allocate a lease to a client and finds this
- lease already present in the database but expired. Another way
- is by periodically querying the lease
- database for them. Regardless of how an expired lease is detected, before
- it may assigned to a client, it must be reclaimed.
+ that it has expired. The server has several possible ways to detect expiration:
+ it may attempt to allocate a lease to a client but find this
+ lease already present in the database and expired; or it can
+ periodically query the lease
+ database for expired leases. Regardless of how an expired lease is detected, it must be
+ reclaimed before it can be assigned to a client.
</para>
<para>
This chapter explains how to configure the server to periodically query
- for the expired leases and how to minimize the impact of the periodic lease
+ for the expired leases, and how to minimize the impact of the periodic lease
reclamation process on the server's responsiveness. Finally, it explains
- "lease affinity", which provides the means to assign the same lease to a
+ "lease affinity," which provides the means to assign the same lease to a
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
+ <para>Although all configuration examples in this section are provided
+ for the DHCPv4 server, the same parameters may be used for
DHCPv6 server configuration.
</para>
<section xml:id="lease-reclamation">
<title>Lease Reclamation</title>
<para>Lease reclamation is the process through which an expired lease
- becomes available for assignment to the same or different client.
+ 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
+ <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
+ <simpara>Update the DNS, i.e. remove any DNS entries associated with
the expired lease.</simpara>
</listitem>
<listitem>
<title>Configuring Lease Reclamation</title>
<para>Kea can be configured to periodically detect and reclaim expired
leases. During this process the lease entries in the database are
- modified or removed. While this is happening the server will not process incoming DHCP
+ modified or removed. While this is happening, 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 while lease reclamation
is performed and DHCP queries will accumulate; responses will be
- sent once the leases reclamation cycle is complete.</para>
+ sent once the lease-reclamation cycle is complete.</para>
<para>In deployments where response time is critical, administrators may
wish to minimize the interruptions in service caused by lease reclamation.
- Toward this end, Kea provides configuration parameters to control: the
+ Toward this end, Kea provides configuration parameters to control the
frequency of lease reclamation cycles, the maximum number of leases
processed in a single reclamation cycle, and the maximum amount of time a
single reclamation cycle is allowed to run before being interrupted. The
<para>The first parameter is expressed in seconds and specifies an
interval between the two consecutive lease reclamation cycles. This
- is explained by the following diagram.
+ is explained by the following diagram:
<screen>
</screen>
</para>
- <para>This diagram shows four lease reclamation cycles (c1 through c4) of variable duration.
+ <para>This diagram shows four lease-reclamation cycles (c1 through c4) 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
+ duration is usually significantly shorter than the interval between
the cycles.
</para>
- <para>According to the <command>reclaim-timer-wait-time</command> the
+ <para>According to the <command>reclaim-timer-wait-time</command>, the
server keeps fixed intervals of five 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
+ 5s-long periods during which the server remains responsive to DHCP
queries and does not perform lease reclamation. The
<command>max-reclaim-leases</command> and
<command>max-reclaim-time</command> are set to 0, which sets
in the particular cycle, or on the maximum duration of each cycle.
</para>
- <para>In deployments with high lease pool utilization, relatively
+ <para>In deployments with high lease-pool utilization, relatively
short valid lifetimes, and frequently disconnecting clients which
allow leases to expire, the number of expired leases requiring reclamation
- at any given time may rise significantly. In this case it is often
- desirable to apply restrictions on the maximum duration of a reclamation
+ at any given time may rise significantly. In this case, it is often
+ desirable to apply restrictions to the maximum duration of a reclamation
cycle or the maximum number of leases reclaimed in a cycle. The following
configuration demonstrates how this can be done:
<para>The <command>max-reclaim-leases</command> parameter limits the number
of leases reclaimed in a 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 if either
- of these limitations is reached. The reclamation of all unreclaimed
+ cycle to 50ms. The lease-reclamation cycle will be interrupted if either
+ of these limitations is reached. The reclamation of any 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.
+ reclamation cycles:
<screen>
</para>
- <para>The diagram demonstrates the case when each reclamation cycle would take
+ <para>This diagram demonstrates the case when each reclamation cycle takes
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 reached. This may be the case when database
+ of the maximum 100 leases is not reached. This may be the case when database
transactions are slow or callouts in the hook libraries attached to
- the server are slow. Regardless, the choosing values for either the
- maximum number of leases or a maximum cycle time strongly depends on the
- particular deployment, lease database backend being used, and any hooks
- libraries etc. Administrators may need to experiment to tune the system
+ the server are slow. Regardless, the chosen values for either the
+ maximum number of leases or a maximum cycle time strongly depend on the
+ particular deployment, the lease database backend being used, and any hooks
+ libraries, etc. Administrators may need to experiment to tune the system
to suit the dynamics of their deployment.</para>
<para>It is important to realize that with the use of these limits, there
is a risk that expired leases will accumulate faster than the server can
- reclaim them. This should not be the problem if the server is dealing
+ reclaim them. This should not be a 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 a 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
+ the database. 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
+ leases, the server issues a warning message in the log if it is unable
+ to reclaim all leases within several reclamation cycles. The
+ number of cycles after which such a warning is issued is specified with the
<command>unwarned-reclaim-cycles</command> configuration parameter.
</para>
<section xml:id="lease-affinity">
<title>Configuring Lease Affinity</title>
- <para>Suppose that a laptop goes to a sleep mode after a period of user
- inactivity. While the laptop is in sleep mode, its DHCP client will not
+ <para>Suppose that a laptop goes into sleep mode after a period of user
+ inactivity. While the laptop is in sleep mode, its DHCP client will not
renew leases obtained from the server and these leases will eventually
- expire. When the laptop wakes up, it is often desirable for it to continue
- using its previous assigned IP addresses. In order to facilitate this,
- the server needs to correlate returning clients with their expired leases
+ expire. When the laptop wakes up, it is often desirable for it to continue
+ using its previous assigned IP addresses. To facilitate this,
+ the server needs to correlate returning clients with their expired leases.
When the client returns, the server will first check for those leases and
- re-assign them if they have not been assigned to another client. The ability
+ re-assign them if they have not been assigned to another client. The ability
of the server to re-assign the same lease to a returning client is
- referred to as "lease affinity".
+ referred to as "lease affinity."
</para>
<para>When lease affinity is enabled, the server will 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
+ will be held in the database (rather than removed) for a specified
+ amount of time. When the client returns, the server will first verify
+ whether there are any reclaimed leases associated with this client and will
re-assign them if possible. However, it is important to note that
any reclaimed lease may be assigned to another client if that client
- specifically asks for it. Therefore, the lease affinity does not
+ specifically asks for it. Therefore, lease affinity does not
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 (this mostly applies
<para>The server must periodically remove reclaimed leases for which the
time indicated by <command>hold-reclaim-time</command> has elapsed. The
- <command>flush-reclaimed-timer-wait-time</command> controls how
+ <command>flush-reclaimed-timer-wait-time</command> parameter controls how
often the server removes such leases. In the example provided
above, the server will initiate removal of such 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 lease affinity is enabled, it
+ lease database when they are reclaimed. If lease affinity is enabled, it
is recommended that <command>hold-reclaim-time</command> be set to a value significantly
higher than the <command>reclaim-timer-wait-time</command>, as timely
- removal of expired-reclaimed leases is less critical while the removal
- process may impact server responsiveness.</para>
+ removal of expired-reclaimed leases is less critical than the removal
+ process, which may impact server responsiveness.</para>
</section>
<section xml:id="lease-reclamation-defaults">
- <title>Default Configuration Values for Leases Reclamation</title>
+ <title>Default Configuration Values for Lease Reclamation</title>
<para>The following list presents all configuration parameters
pertaining to processing expired leases with their default values:</para>
<simpara><command>hold-reclaimed-time</command> = 3600 [seconds]</simpara>
</listitem>
<listitem>
- <simpara><command>max-reclaim-leases</command> = 100 </simpara>
+ <simpara><command>max-reclaim-leases</command> = 100</simpara>
</listitem>
<listitem>
<simpara><command>max-reclaim-time</command> = 250 [milliseconds]</simpara>
</listitem>
</itemizedlist>
- <para>The default value for any parameter is used when this parameter not
+ <para>The default value for any parameter is used when this parameter is 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
<section xml:id="leases-reclamation-using-command">
<title>Reclaiming Expired Leases with Command</title>
<para>The <emphasis>leases-reclaim</emphasis> command can be used to trigger
- leases reclamation at any time. Please consult the
- <xref linkend="command-leases-reclaim"/> for the details about using this
+ lease reclamation at any time. Please consult the
+ <xref linkend="command-leases-reclaim"/> section for details about using this
command.</para>
</section>
projects / thirdparty / kea.git / commitdiff
