From 74e140a3a872beaac965ac19063a090a8dfe72e6 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Fri, 23 Oct 2015 17:06:23 +0200 Subject: [PATCH] [3979] Added new chapter about lease reclamation to the User Guide. --- doc/guide/Makefile.am | 4 +- doc/guide/kea-guide.xml | 2 + doc/guide/lease-expiration.xml | 339 +++++++++++++++++++++++++++++++++ 3 files changed, 343 insertions(+), 2 deletions(-) create mode 100644 doc/guide/lease-expiration.xml 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/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..f331ebf184 --- /dev/null +++ b/doc/guide/lease-expiration.xml @@ -0,0 +1,339 @@ + + +]> + + Lease Expiration in DHCPv4 and DHCPv6 + + 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. + + + 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. + + 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. + + + 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 + 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: + + + + + 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 the to see + how to configure the DNS updates in Kea, and to the + for information about using + hooks libraries. +
+ +
+ Configuring Leases Reclamation + 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. + + In the deployments where the response time is critical, the + administrators want to minimize the interruptions in the service + caused by the processing of expired leases. Kea provides a set of + configuration parameters to control the frequency of leases reclamation, + the maximum number of leases processed in a single cycle and the + timeout after which the reclamation should be interrupted. The + following configuration examples demonstrate how these parameters + can be used: + + +"Dhcp4": { + ... + + "expired-leases-processing": { + "reclaim-timer-wait-time": 5, + "max-reclaim-leases": 0, + "max-reclaim-time": 0, + "flush-reclaimed-timer-wait-time": 0, + }, + + ... +} + + + + 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 reclaimed leases + in the particular cycle, and the maximum duration of each cycle. + + + In the deployments with high lease pool utilization, relatively + short valid lifetimes and clients often disconnecting allowing the + leases to expire, the number of expired leases requiring reclamation + at the given time may rise significantly. In this case it is often + desired to apply restrictions on the maximum duration of the leases + reclamation cycle or the number of leases that can be reclaimed in + this cycle. The following configuration demonstrates how this + can be done: + + +"Dhcp4": { + ... + + "expired-leases-processing": { + "reclaim-timer-wait-time": 3, + "max-reclaim-leases": 100, + "max-reclaim-time": 50, + "unwarned-reclaim-cycles": 10, + "flush-reclaimed-timer-wait-time": 0, + }, + + ... +} + + + + + + The max-reclaim-leases parameter limits the number + of leases reclaimed in the single cycle to 100. The + max-reclaim-time 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. + + 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 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. + + 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 + 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 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'. + + + When the lease affinity is enabled, the server would 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 + 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. + + + 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, 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. + + The server must occasionally remove reclaimed leases for which the + time indicated by hold-reclaim-time 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 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 reclaim-timer-wait-time + 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. + +
+ +
+ 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. + +
+ + -- 2.47.2