mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-30 13:37:55 +00:00
Code Issues Releases Wiki Activity

[master] Merge branch 'trac3979'

Browse Source
This commit is contained in:
Marcin Siodelski 2015-10-27 16:02:30 +01:00
commit a2ee99ba31
12 changed files with 653 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/Makefile.am
View File

@ -12,12 +12,14 @@ nobase_dist_doc_DATA = examples/kea4/single-subnet.json
nobase_dist_doc_DATA += examples/kea4/several-subnets.json
nobase_dist_doc_DATA += examples/kea4/multiple-options.json
nobase_dist_doc_DATA += examples/kea4/reservations.json
nobase_dist_doc_DATA += examples/kea4/leases-expiration.json
nobase_dist_doc_DATA += examples/kea6/simple.json
nobase_dist_doc_DATA += examples/kea6/several-subnets.json
nobase_dist_doc_DATA += examples/kea6/multiple-options.json
nobase_dist_doc_DATA += examples/kea6/advanced.json
nobase_dist_doc_DATA += examples/kea6/stateless.json
nobase_dist_doc_DATA += examples/kea6/reservations.json
nobase_dist_doc_DATA += examples/kea6/leases-expiration.json
nobase_dist_doc_DATA += examples/ddns/sample1.json
nobase_dist_doc_DATA += examples/ddns/template.json

2
doc/devel/mainpage.dox
View File

@ -100,6 +100,8 @@
* - @subpage hostmgr
* - @subpage optionsConfig
* - @subpage allocengine
* - @subpage timerManager
* - @subpage leaseReclamationRoutine
* - @subpage libdhcp_ddns
* - @subpage dhcpDatabaseBackends
* - @subpage configBackend

71
doc/examples/kea4/leases-expiration.json Normal file
View File

@ -0,0 +1,71 @@
# This is an example configuration file for the DHCPv4 server in Kea.
# It provides parameters controlling processing of expired leases,
# a.k.a. leases reclamation.
{ "Dhcp4":
{
# Kea is told to listen on ethX interface only.
"interfaces-config": {
"interfaces": [ "ethX" ]
},
# We need to specify lease type. As of May 2014, three backends are supported:
# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require
# any prior set up.
"lease-database": {
"type": "memfile"
},
# The following parameters control processing expired leases. Expired leases
# will be reclaimed periodically according to the "reclaim-timer-wait-time"
# parameter. Reclaimed leases will be held in the database for 1800s to
# facilitate lease affinity. After this period the leases will be removed.
# The frequency of removal is controlled by the "flush-reclaimed-timer-wait-time"
# parameter. The lease reclamation routine will process at most 500 leases
# or will last for at most 100ms, during a single run. If there are still
# some unreclaimed leases after 10 attempts, a warning message is issued.
"expired-leases-processing": {
"reclaim-timer-wait-time": 5,
"hold-reclaimed-time": 1800,
"flush-reclaimed-timer-wait-time": 10,
"max-reclaim-leases": 500,
"max-reclaim-time": 100,
"unwarned-reclaim-cycles": 10
},
# Addresses will be assigned with valid lifetimes being 4000. Client
# is told to start renewing after 1000 seconds. If the server does not respond
# after 2000 seconds since the lease was granted, client is supposed
# to start REBIND procedure (emergency renewal that allows switching
# to a different server).
"valid-lifetime": 4000,
# The following list defines subnets. We have only one subnet
# here. We tell Kea that it is directly available over local interface.
"subnet4": [
{
"pools": [ { "pool": "192.0.2.1 - 192.0.2.200" } ],
"subnet": "192.0.2.0/24",
"interface": "ethX"
}
]
},
# The following configures logging. It assumes that messages with at least
# informational level (info, warn, error) will will be logged to stdout.
"Logging": {
"loggers": [
{
"name": "kea-dhcp4",
"output_options": [
{
"output": "stdout"
}
],
"severity": "INFO"
}
]
}
}

77
doc/examples/kea6/leases-expiration.json Normal file
View File

@ -0,0 +1,77 @@
# This is an example configuration file for DHCPv6 server in Kea.
# It provides parameters controlling processing of expired leases,
# a.k.a. leases reclamation.
{ "Dhcp6":
{
# Kea is told to listen on ethX interface only.
"interfaces-config": {
"interfaces": [ "ethX" ]
},
# We need to specify lease type. As of May 2014, three backends are supported:
# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require
# any prior set up.
"lease-database": {
"type": "memfile"
},
# The following parameters control processing expired leases. Expired leases
# will be reclaimed periodically according to the "reclaim-timer-wait-time"
# parameter. Reclaimed leases will be held in the database for 1800s to
# facilitate lease affinity. After this period the leases will be removed.
# The frequency of removal is controlled by the "flush-reclaimed-timer-wait-time"
# parameter. The lease reclamation routine will process at most 500 leases
# or will last for at most 100ms, during a single run. If there are still
# some unreclaimed leases after 10 attempts, a warning message is issued.
"expired-leases-processing": {
"reclaim-timer-wait-time": 5,
"hold-reclaimed-time": 1800,
"flush-reclaimed-timer-wait-time": 10,
"max-reclaim-leases": 500,
"max-reclaim-time": 100,
"unwarned-reclaim-cycles": 10
},
# Addresses will be assigned with preferred and valid lifetimes
# being 3000 and 4000, respectively. Client is told to start
# renewing after 1000 seconds. If the server does not respond
# after 2000 seconds since the lease was granted, client is supposed
# to start REBIND procedure (emergency renewal that allows switching
# to a different server).
"preferred-lifetime": 3000,
"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,
# The following list defines subnets. Each subnet consists of at
# least subnet and pool entries.
"subnet6": [
{
"pools": [ { "pool": "2001:db8:1::/80" } ],
"subnet": "2001:db8:1::/64",
"interface": "ethX"
}
]
},
# The following configures logging. Kea will log all debug messages
# to /var/log/kea-debug.log file.
"Logging": {
"loggers": [
{
"name": "kea-dhcp6",
"output_options": [
{
"output": "/var/log/kea-debug.log"
}
],
"debuglevel": 99,
"severity": "DEBUG"
}
]
}
}

4
doc/guide/Makefile.am
View File

@ -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
EXTRA_DIST = $(DOCBOOK)
DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml

27
doc/guide/ctrl-channel.xml
View File

@ -112,6 +112,33 @@ configuration file.</para>
<section id="commands-common">
<title>Commands supported by both DHCPv4 and DHCPv6 servers</title>
<section id="command-leases-reclaim">
<title>leases-reclaim command</title>
<para>
<emphasis>leases-reclaim</emphasis> command instructs the server to
reclaim all expired leases immediately. The command has the following
JSON syntax:
<screen>
{
"command": "leases-reclaim",
"arguments": {
"remove": true
}
}
</screen>
</para>
<para>The <emphasis>remove</emphasis> boolean parameter is mandatory
and it indicates whether the reclaimed leases should be removed from
the lease database (if true), or they should be left in the
<emphasis>expired-reclaimed</emphasis> state (if false). The latter
facilitates lease affinity, i.e. ability to re-assign expired lease to
the same client which used this lease before. See
<xref linkend="lease-affinity"/> for the details. Also, see
<xref linkend="lease-reclamation"/> for the general information
about the processing of expired leases (leases reclamation).</para>
</section>
<section id="command-list-commands">
<title>list-commands command</title>

17
doc/guide/dhcp4-srv.xml
View File

@ -2968,11 +2968,10 @@ It is merely echoed by the server
given subnet. This statistic increases every time a new lease is
allocated (as a result of receiving a DHCPREQUEST message) and is
decreased every time a lease is released (a DHCPRELEASE message is
received). When lease expiration is implemented (planned for Kea
1.0), it will also decrease when a lease is expired. The
<emphasis>id</emphasis> is the subnet-id of a given subnet. This
statistic is exposed for each subnet separately. This statistic is
reset during reconfiguration event.</entry>
received) or expires. The <emphasis>id</emphasis> is the subnet-id
of a given subnet. This statistic is exposed for each subnet
separately. This statistic is reset during reconfiguration event.
</entry>
</row>
</tbody>
</tgroup>
@ -3116,14 +3115,6 @@ It is merely echoed by the server
<listitem>
<simpara>Address duplication report (DECLINE) is not supported yet.</simpara>
</listitem>
<listitem>
<simpara>
The server doesn't act upon expired leases. In particular,
when a lease expires, the server doesn't request the removal
of the DNS records associated with it. Expired leases can be
recycled.
</simpara>
</listitem>
</itemizedlist>
</section>

26
doc/guide/dhcp6-srv.xml
View File

@ -2921,11 +2921,10 @@ should include options from the isc option space:
This statistic shows the number of NA addresses in a given subnet that
are assigned. This statistic increases every time a new lease is allocated
(as a result of receiving a REQUEST message) and is decreased every time a
lease is released (a RELEASE message is received). When lease expiration
is implemented (planned for Kea 1.0), it will also decrease when a lease
is expired. The <emphasis>id</emphasis> is the subnet-id of a given
subnet. This statistic is exposed for each subnet separately. This
statistic is reset during a reconfiguration event.
lease is released (a RELEASE message is received) or expires. The
<emphasis>id</emphasis> is the subnet-id of a given subnet. This
statistic is exposed for each subnet separately. This statistic is
reset during a reconfiguration event.
</entry>
</row>
@ -2951,11 +2950,10 @@ should include options from the isc option space:
This statistic shows the number of PD prefixes in a given subnet that
are assigned. This statistic increases every time a new lease is allocated
(as a result of receiving a REQUEST message) and is decreased every time a
lease is released (a RELEASE message is received). When lease expiration
is implemented (planned for Kea 1.0), it will also decrease when a lease
is expired. The <emphasis>id</emphasis> is the subnet-id of a given
subnet. This statistic is exposed for each subnet separately. This
statistic is reset during a reconfiguration event.
lease is released (a RELEASE message is received) or expires. The
<emphasis>id</emphasis> is the subnet-id of a given subnet. This statistic
is exposed for each subnet separately. This statistic is reset during a
reconfiguration event.
</entry>
</row>
@ -3117,14 +3115,6 @@ should include options from the isc option space:
not yet supported.
</simpara>
</listitem>
<listitem>
<simpara>
The server doesn't act upon expired leases. In particular,
when a lease expires, the server doesn't request removal of
the DNS records associated with it.
</simpara>
</listitem>
</itemizedlist>
</section>

2
doc/guide/kea-guide.xml
View File

@ -67,6 +67,8 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp6-srv.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lease-expiration.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ddns.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lfc.xml" />

341
doc/guide/lease-expiration.xml Normal file
View File

@ -0,0 +1,341 @@
<?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 "&#x2014;" >
]>
<chapter id="lease-expiration">
<title>Lease Expiration in DHCPv4 and DHCPv6</title>
<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 '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>
<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
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".
The DHCP server should reclaim an expired lease as soon as it detects
that it has expired. One way in which the server may detect expiration
is when it is trying to allocate a lease to a client and finds this
lease already present in the database but expired. Another way the
server detects expired leases is by periodically querying the lease
database for them. Regardless of how an expired lease is detected, before
it my assigned to a client, it must be reclaimed.
This chapter explains 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, 'lease affinity',
which provides the means to assign the same lease to the returning client
after its lease has expired, is explained.
</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>Lease reclamation is the process through 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 <xref linkend="dhcp-ddns-server"/> to see
how to configure DNS updates in Kea, and to
<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 reclaim 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 while lease reclamation
is performed. DHCP queries will accumulate and responses will be
sent once the leases 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
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
following 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 |
|&#x3c;----&#x3e;|&#x3c;----------&#x3e;|&#x3c;--&#x3e;|&#x3c;----------&#x3e;|&#x3c;&#x3e;|&#x3c;----------&#x3e;|&#x3c;--&#x3e;|
---------------------------------------------------------------->
| | 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 leases reclaimed
in the particular cycle, or the maximum duration of each cycle.
</para>
<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
cycle or the maximum number of leases reclaimed in a 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 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
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 |
|&#x3c;--&#x3e;|&#x3c;--------------&#x3e;|&#x3c;--&#x3e;|&#x3c;--------------&#x3e;|&#x3c;--&#x3e;|&#x3c;--------------&#x3e;|&#x3c;--&#x3e;|&#x3c;--
------------------------------------------------------------------------------>
|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 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
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
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 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
renew leases obtained from the server and these leases will eventually
expire. When the laptop wakes up, it is often desired that it continue
using its previous assigned IP addresses. In order 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 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'.
</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
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
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,
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 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
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
is recommended that hold-reclaim-time 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>
</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>
<section 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
command.</para>
</section>
</chapter>

1
src/bin/dhcp4/tests/configs-list.txt
View File

@ -3,3 +3,4 @@
../../../../doc/examples/kea4/single-subnet.json
../../../../doc/examples/kea4/several-subnets.json
../../../../doc/examples/kea4/leases-expiration.json

116
src/lib/dhcpsrv/libdhcpsrv.dox
View File

@ -258,4 +258,120 @@ was made. The client will be offered/allocated a reserved address
the next time it retries sending a DHCPDISCOVER/DHCPREQUEST message to
the server.
@section timerManager Timer Manager
The fundamental role of the DHCP server is to receive and process DHCP
messages received over the sockets opened on network interfaces. The
servers' include the main loops in which the servers passively wait
for the messages. This is done by calling the
@c isc::dhcp::IfaceMgr::receive4 and/or @c isc::dhcp::IfaceMgr::receive6
methods for DHCPv4 and DHCPv6 server respectively. Internally, these
methods call @c select() on open sockets, which blocks for a
specified amount of time.
The implication of using the @c select() is that the server has no
means to process any "events" while it is waiting for the @c select()
to return. An example of such an event is the expiration of the timer
which controls when the server should detect and process expired
leases.
The @c isc::dhcp::TimerMgr has been created to address the issue of
processing expired leases according to the the dedicated timer.
Nevertheless, this concept is univeral and should be used for
all timers which need to be triggered asynchronously, i.e. independently
from processing the DHCP messages.
The @c TimerMgr allows for registering timers and associating them with
user callback functions, which are executed without waiting for the
call to the @c select() function to return as a result of the timeout.
When the particular timer elapses, the blocking call to select is
interrupted by sending data over a dedicated (for a timer)
@c isc::util::WatchSocket. Each timer has an instance of
@c isc::util::WatchSocket associated with it, and each such socket
is registered with the @c IfaceMgr using the @c IfaceMgr::addExternalSocket.
When the transmission of the data over the watch socket interrupts the
@c select() call, the user callback is executed by
@c isc::dhcp::IfaceMgr and the watch socket is cleared to accept
subsequent events for that particular timer.
The timers are implemented using the @c isc::asiolink::IntervalTimer class.
They are run in a dedicated thread which is owned (created and destroyed)
by @c isc::dhcp::TimerMgr. This worker thread runs an instance
of @c isc::asiolink::IOService object which is associated with all
registered timers. The thread uses a common callback function which
is executed when a timer elapses. This callback function receives
a name of the elapsed timer as an argument and, based on that, selects the
appropriate @c isc::util::WatchSocket to be marked as ready. In order to
overcome the race conditions with the main thread, the worker thread blocks
right after it marks the watch socket as ready, and waits for this
socket to be cleared by the main thread. This is the indication
that the timer specific callback function has been invoked and the
worker thread may continue monitoring registered timers and signal
their readiness when they elapse.
@section leaseReclamationRoutine Leases Reclamation Routine
Lease reclamation is the process in which the expired lease becomes
available for re-assignment to the same or another client. When the
server reclaims the lease it executes the callouts registered for the
"lease4_expire" and "lease6_expire" hook points, performs the DNS update
to remove any DNS records associated with the expired lease, and finally
marks a lease as reclaimed in the lease database. The lease may be
marked as reclaimed by setting its state to @c Lease::STATE_EXPIRED_RECLAIMED
or by being removed from the database.
Reclamation is performed periodically for a bulk of expired
leases in the lease reclamation routine. The lease reclamation routines
for both DHCP servers are implemented in the @c isc::dhcp::AllocEngine:
- @c isc::dhcp::AllocEngine::reclaimExpiredLeases4 (DHCPv4)
- @c isc::dhcp::AllocEngine::reclaimExpiredLeases6 (DHCPv6)
Note that besides the reclamation of the leases, these methods also
update the relevant statistics, i.e. decrease the number of assigned
leases and increase the number of reclaimed leases.
The reclamation routines are executed periodically according to
the server configuration (see the documentation for the
"expired-leases-processing" configuration map). Internally, they are
registered as callback functions in the @c isc::dhcp::TimerMgr
(see @ref timerManager for the details), during the servers' startup
or reconfiguration.
Execution of the reclamation routine may take a relatively
long period of time. It depends on the complexity of the callouts,
whether the DNS update is required for leases, and the type of the
lease database used. While the reclamation routine is
executed, the server will not process any DHCP messages to avoid
race conditions being a result of concurrent access to the lease
database to allocate and reclaim leases. To make sure that the
server remains responsive, it is possible to limit the number of
leases being processed by the leases reclamation routine and/or
limit the time for the reclamation routine to process
leases. Both limits are specified in the respective arguments
passed to the lease reclamation routines.
As mentioned above, reclaimed leases may be marked as such, by
updating their state to @c Lease::STATE_EXPIRED_RECLAIMED or by
being removed. This behavior is controlled by the boolean parameter
passed to the reclamation routine. The first approach is desired
when the server should provide "lease affinity", i.e. ability to
re-assign the same lease to the returning client. By only
updating the lease state, the server preserves association of the
lease with a particular client. When that client returns the
server may assign the same lease to the client, assuming that this
lease is still available. The lease is removed during the
reclamation when the lease affinity is not required and it is
preferred to not keep redundant information (about expired
leases) in the lease database.
If the reclaimed leases are not removed, they are held in the
database for a specified amount of time after their expiration.
Each reclaimed lease is removed when this time elapses for it.
The @c isc::dhcp::LeaseMgr::deleteExpiredReclaimedLeases4 and
@c isc::dhcp::LeaseMgr::deleteExpiredReclaimedLeases6 are used
to remove those leases for which the specified amount of time
since expiration elapsed. These methods are executed periodically
by the DHCP servers using the dedicated timers registered in the
@c isc::dhcp::TimerMgr.
*/