diff --git a/doc/Makefile.am b/doc/Makefile.am index 115e492dfa..5e31b591de 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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 diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox index 9204a327cf..df2cf4d028 100644 --- a/doc/devel/mainpage.dox +++ b/doc/devel/mainpage.dox @@ -100,6 +100,8 @@ * - @subpage hostmgr * - @subpage optionsConfig * - @subpage allocengine + * - @subpage timerManager + * - @subpage leaseReclamationRoutine * - @subpage libdhcp_ddns * - @subpage dhcpDatabaseBackends * - @subpage configBackend diff --git a/doc/examples/kea4/leases-expiration.json b/doc/examples/kea4/leases-expiration.json new file mode 100644 index 0000000000..b1397b3d18 --- /dev/null +++ b/doc/examples/kea4/leases-expiration.json @@ -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" + } + ] +} + +} diff --git a/doc/examples/kea6/leases-expiration.json b/doc/examples/kea6/leases-expiration.json new file mode 100644 index 0000000000..59fea3022b --- /dev/null +++ b/doc/examples/kea6/leases-expiration.json @@ -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" + } + ] +} + +} + diff --git a/doc/guide/Makefile.am b/doc/guide/Makefile.am index d1eef989da..e7c18ab9c6 100644 --- a/doc/guide/Makefile.am +++ b/doc/guide/Makefile.am @@ -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 diff --git a/doc/guide/ctrl-channel.xml b/doc/guide/ctrl-channel.xml index eaba538005..a1bb04b45a 100644 --- a/doc/guide/ctrl-channel.xml +++ b/doc/guide/ctrl-channel.xml @@ -112,6 +112,33 @@ configuration file.
Commands supported by both DHCPv4 and DHCPv6 servers +
+ leases-reclaim command + + leases-reclaim command instructs the server to + reclaim all expired leases immediately. The command has the following + JSON syntax: + +{ + "command": "leases-reclaim", + "arguments": { + "remove": true + } +} + + + + The remove 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 + expired-reclaimed 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 + for the details. Also, see + for the general information + about the processing of expired leases (leases reclamation). +
+
list-commands command diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index b5b9964cf6..07b0123fdf 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -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 - id is the subnet-id of a given subnet. This - statistic is exposed for each subnet separately. This statistic is - reset during reconfiguration event. + received) or expires. The id is the subnet-id + of a given subnet. This statistic is exposed for each subnet + separately. This statistic is reset during reconfiguration event. + @@ -3116,14 +3115,6 @@ It is merely echoed by the server Address duplication report (DECLINE) is not supported yet. - - - 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. - -
diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index d0bb786042..9e10e671d5 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -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 id 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 + id is the subnet-id of a given subnet. This + statistic is exposed for each subnet separately. This statistic is + reset during a reconfiguration event. @@ -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 id 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 + id is the subnet-id of a given subnet. This statistic + is exposed for each subnet separately. This statistic is reset during a + reconfiguration event. @@ -3117,14 +3115,6 @@ should include options from the isc option space: not yet supported. - - - - 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. - -
diff --git a/doc/guide/kea-guide.xml b/doc/guide/kea-guide.xml index dbf0694ced..dcccacc5d1 100644 --- a/doc/guide/kea-guide.xml +++ b/doc/guide/kea-guide.xml @@ -67,6 +67,8 @@ + + diff --git a/doc/guide/lease-expiration.xml b/doc/guide/lease-expiration.xml new file mode 100644 index 0000000000..5b2c2c3737 --- /dev/null +++ b/doc/guide/lease-expiration.xml @@ -0,0 +1,341 @@ + + +]> + + Lease Expiration in DHCPv4 and DHCPv6 + + 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. + + + 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. + + 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. + + + Although, all configuration examples in this section are provided + for the DHCPv4 server, the same parameters may be used for the + DHCPv6 server configuration. + + +
+ Lease Reclamation + 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: + + + + + Invoke callouts for the lease4_expire or + lease6_expire hook points, if hook libraries + supporting those callouts are currently loaded. + + + Update DNS, i.e. remove any DNS entries associated with + the expired lease. + + + Update lease information in the lease database to + indicate that the lease is now available for re-assignment. + + + Update statistics of the server, which includes + increasing the number of reclaimed leases and decreasing the + number of assigned addresses or delegated prefixes etc. + + + + Please refer to to see + how to configure DNS updates in Kea, and to + for information about using + hooks libraries. +
+ +
+ Configuring Leases Reclamation + 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. + + 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: + + +"Dhcp4": { + ... + + "expired-leases-processing": { + "reclaim-timer-wait-time": 5, + "max-reclaim-leases": 0, + "max-reclaim-time": 0, + "flush-reclaimed-timer-wait-time": 0, + }, + + ... +} + + + + 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 + + + + + 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. + + + According to the reclamim-timer-wait-time 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 + max-reclaim-leases and + max-reclaim-time 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. + + + 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: + + +"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, + }, + + ... +} + + + + + + The max-reclaim-leases parameter limits the number + of leases reclaimed in a single cycle to 100. The + max-reclaim-time 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. + + 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 + + + + + + The diagram demonstrates the case when each reclamation cycle would take + more than 50ms, and thus is interrupted according to the value of the + max-reclaim-time. 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. + + 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 + unwarned-reclaim-cycles configuration parameter. + + + Setting the reclaim-timer-wait-time to 0 disables + periodic reclamation of the expired leases. +
+ +
+ Configuring Lease Affinity + 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'. + + + When lease affinity is enabled, the server will still + reclaim leases according to the parameters described in + , 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. + + + Consider the following configuration: + + +"Dhcp4": { + ... + + "expired-leases-processing": { + "reclaim-timer-wait-time": 3, + "hold-reclaimed-time": 1800, + "flush-reclaimed-timer-wait-time": 5 + }, + + ... +} + + + + + The hold-reclaim-time 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. + + The server must periodically remove reclaimed leases for which the + time indicated by hold-reclaim-time has elapsed. The + flush-reclaimed-timer-wait-time 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 reclaim-timer-wait-time, as timely + removal of expired-reclaimed leases is less critical while the removal + process may impact server responsiveness. +
+ +
+ Default Configuration Values for Leases Reclamation + The following list presents all configuration parameters + pertaining to processing expired leases with their default values: + + + + reclaim-timer-wait-time = 10 [seconds] + + + flush-reclaimed-timer-wait-time = 25 [seconds] + + + hold-reclaimed-time = 3600 [seconds] + + + max-reclaim-leases = 100 + + + max-reclaim-time = 250 [milliseconds] + + + unwarned-reclaim-cycles = 5 + + + + The default value for any parameter is used when this parameter not + explicitly specified in the configuration. Also, the + expired-leases-processing map may be omitted entirely + in the configuration, in which case the default values are used for all + parameters listed above. + +
+ +
+ Reclaiming Expired Leases with Command + The leases-reclaim command can be used to trigger + leases reclamation at any time. Please consult the + for the details about using this + command. +
+ + diff --git a/src/bin/dhcp4/tests/configs-list.txt b/src/bin/dhcp4/tests/configs-list.txt index f7e5587bd0..0ba5616669 100644 --- a/src/bin/dhcp4/tests/configs-list.txt +++ b/src/bin/dhcp4/tests/configs-list.txt @@ -3,3 +3,4 @@ ../../../../doc/examples/kea4/single-subnet.json ../../../../doc/examples/kea4/several-subnets.json +../../../../doc/examples/kea4/leases-expiration.json diff --git a/src/lib/dhcpsrv/libdhcpsrv.dox b/src/lib/dhcpsrv/libdhcpsrv.dox index 7c800e49ef..97024fd27a 100644 --- a/src/lib/dhcpsrv/libdhcpsrv.dox +++ b/src/lib/dhcpsrv/libdhcpsrv.dox @@ -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. + */