From 74e140a3a872beaac965ac19063a090a8dfe72e6 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Fri, 23 Oct 2015 17:06:23 +0200 Subject: [PATCH 01/10] [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. + +
+ + From 702b77ce47d6a2f8816a3474a93d7971bc25d564 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Mon, 26 Oct 2015 12:59:35 +0100 Subject: [PATCH 02/10] [3979] Added description of leases-reclaim command to User Guide. --- doc/guide/ctrl-channel.xml | 27 +++++++++++++++++++++++++++ doc/guide/lease-expiration.xml | 8 ++++++++ 2 files changed, 35 insertions(+) diff --git a/doc/guide/ctrl-channel.xml b/doc/guide/ctrl-channel.xml index eaba538005..88007ea5c6 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 the + for the details. Also, see the + for the general information + about the processing of expired leases (leases reclamation). +
+
list-commands command diff --git a/doc/guide/lease-expiration.xml b/doc/guide/lease-expiration.xml index f331ebf184..de81f943f1 100644 --- a/doc/guide/lease-expiration.xml +++ b/doc/guide/lease-expiration.xml @@ -336,4 +336,12 @@
+
+ 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. +
+ From f75ba49ed49df57cd27420cdb20f77d8b8605729 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Mon, 26 Oct 2015 13:58:13 +0100 Subject: [PATCH 03/10] [3979] Added examples demonstrating processing expired leases. --- doc/Makefile.am | 2 + doc/examples/kea4/leases-expiration.json | 71 ++++++++++++++++++++++ doc/examples/kea6/leases-expiration.json | 77 ++++++++++++++++++++++++ src/bin/dhcp4/tests/configs-list.txt | 1 + 4 files changed, 151 insertions(+) create mode 100644 doc/examples/kea4/leases-expiration.json create mode 100644 doc/examples/kea6/leases-expiration.json 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/examples/kea4/leases-expiration.json b/doc/examples/kea4/leases-expiration.json new file mode 100644 index 0000000000..3771eca8b3 --- /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, + "flush-reclaimed-timer-wait-time": 10, + "max-reclaim-leases": 500, + "max-reclaim-time": 100, + "hold-reclaimed-time": 1800, + "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..0f66bfc36c --- /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, + "flush-reclaimed-timer-wait-time": 10, + "max-reclaim-leases": 500, + "max-reclaim-time": 100, + "hold-reclaimed-time": 1800, + "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/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 From c586b9b8e45e6c187f0cc3a8d62de79a1052b834 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Mon, 26 Oct 2015 14:06:14 +0100 Subject: [PATCH 04/10] [3979] Removed notes in the statistics about lease expiration not impl. --- doc/guide/dhcp4-srv.xml | 9 ++++----- doc/guide/dhcp6-srv.xml | 18 ++++++++---------- 2 files changed, 12 insertions(+), 15 deletions(-) diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index b5b9964cf6..98feea82f1 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. + diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml index d0bb786042..ec422e3edb 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. From 0533f9d62e229c4e9137f3365f90e3b2842b5efe Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Mon, 26 Oct 2015 14:08:53 +0100 Subject: [PATCH 05/10] [3979] Removed lease expiration from the server limitations. --- doc/guide/dhcp4-srv.xml | 8 -------- doc/guide/dhcp6-srv.xml | 8 -------- 2 files changed, 16 deletions(-) diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml index 98feea82f1..07b0123fdf 100644 --- a/doc/guide/dhcp4-srv.xml +++ b/doc/guide/dhcp4-srv.xml @@ -3115,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 ec422e3edb..9e10e671d5 100644 --- a/doc/guide/dhcp6-srv.xml +++ b/doc/guide/dhcp6-srv.xml @@ -3115,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. - - From 94847b1629cd50d48cf25135be458f7f76154385 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Mon, 26 Oct 2015 16:15:55 +0100 Subject: [PATCH 06/10] [3979] Updated user guide for lease expiration. --- doc/devel/mainpage.dox | 2 + src/lib/dhcpsrv/libdhcpsrv.dox | 116 +++++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) 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/src/lib/dhcpsrv/libdhcpsrv.dox b/src/lib/dhcpsrv/libdhcpsrv.dox index 7c800e49ef..befff37559 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 the dedicated (for a timer) +@c isc::util::WatchSocket. Each timer has an instance of the +@c isc::util::WatchSocket associated with it, and each such socket +is registered in 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 the +@c isc::dhcp::IfaceMgr and the watch socket is cleared to accept +subsequent events for the 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) +in the @c isc::dhcp::TimerMgr. This worker thread runs an instance +of the @c isc::asiolink::IOService object, associated with all +registered timers. The thread uses a common callback function which +is executed when the 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 a 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 + +The 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. + +The leases 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 leases 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 leases reclamation routine may take 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 leases reclamation routine is +executed, the server is not processing 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 lease 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 the particular client. When the 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. + */ From c800de4b65bdb7e5f73e02f5b6a241e306fe6bdd Mon Sep 17 00:00:00 2001 From: Thomas Markwalder Date: Tue, 27 Oct 2015 10:03:06 -0400 Subject: [PATCH 07/10] [3979] Did some clean up and rewording --- doc/guide/ctrl-channel.xml | 4 +- doc/guide/lease-expiration.xml | 207 ++++++++++++++++----------------- src/lib/dhcpsrv/libdhcpsrv.dox | 34 +++--- 3 files changed, 120 insertions(+), 125 deletions(-) diff --git a/doc/guide/ctrl-channel.xml b/doc/guide/ctrl-channel.xml index 88007ea5c6..a1bb04b45a 100644 --- a/doc/guide/ctrl-channel.xml +++ b/doc/guide/ctrl-channel.xml @@ -133,8 +133,8 @@ configuration file. 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 the - for the details. Also, see the + 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). diff --git a/doc/guide/lease-expiration.xml b/doc/guide/lease-expiration.xml index de81f943f1..a698df2065 100644 --- a/doc/guide/lease-expiration.xml +++ b/doc/guide/lease-expiration.xml @@ -6,38 +6,41 @@ 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. + 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 and its valid lifetime + 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. - The most obvious one is the shutdown of the machine running the - client. + 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 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. + 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 @@ -47,7 +50,7 @@
Lease Reclamation - The lease reclamation is a process in which an expired lease + 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: @@ -73,30 +76,29 @@ - Please refer to the to see - how to configure the DNS updates in Kea, and to the + 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 process expired + 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 + 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 + 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 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: + 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": { @@ -120,7 +122,7 @@ -| c1 | | c2 | |c3| | c4 | +| c1 | | c2 | |c3| | c4 | |<---->|<---------->|<-->|<---------->|<>|<---------->|<-->| ----------------------------------------------------------------> | | 5s | | 5s | | 5s | | time @@ -142,18 +144,17 @@ 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. + there is no restriction on the maximum number of leases reclaimed + in the particular cycle, or 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: + 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": { @@ -175,10 +176,10 @@ The max-reclaim-leases parameter limits the number - of leases reclaimed in the single cycle to 100. The + 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 when - first of these limitations is hit. 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 all unreclaimed leases will be attempted in subsequent cycles. The following diagram illustrates the behavior of the system in the @@ -200,50 +201,47 @@ 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. + 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. - 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 + 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 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'. + 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 the lease affinity is enabled, the server would still + 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 @@ -251,12 +249,12 @@ 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. + 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: @@ -279,27 +277,24 @@ 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 + 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 occasionally remove reclaimed leases for which the - time indicated by hold-reclaim-time elapsed. The + 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 leases 5 seconds after + 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 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. - + 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.
diff --git a/src/lib/dhcpsrv/libdhcpsrv.dox b/src/lib/dhcpsrv/libdhcpsrv.dox index befff37559..97024fd27a 100644 --- a/src/lib/dhcpsrv/libdhcpsrv.dox +++ b/src/lib/dhcpsrv/libdhcpsrv.dox @@ -285,24 +285,24 @@ 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 the dedicated (for a timer) -@c isc::util::WatchSocket. Each timer has an instance of the +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 in the @c IfaceMgr using the @c IfaceMgr::addExternalSocket. +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 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 the particular timer. +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) -in the @c isc::dhcp::TimerMgr. This worker thread runs an instance -of the @c isc::asiolink::IOService object, associated with all +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 the timer elapses. This callback function receives +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 a main thread, the worker thread blocks +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 @@ -311,7 +311,7 @@ their readiness when they elapse. @section leaseReclamationRoutine Leases Reclamation Routine -The lease reclamation is the process in which the expired lease becomes +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 @@ -320,7 +320,7 @@ 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. -The leases reclamation is performed periodically for a bulk of expired +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) @@ -330,23 +330,23 @@ 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 leases reclamation routines are executed periodically according to +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 leases reclamation routine may take relatively +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 leases reclamation routine is -executed, the server is not processing any DHCP messages to avoid +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 lease reclamation routine to process +limit the time for the reclamation routine to process leases. Both limits are specified in the respective arguments passed to the lease reclamation routines. @@ -357,7 +357,7 @@ 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 the particular client. When the client returns 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 From f8c17848bd2c6a9d8eee9b1a4897a2f372ea752b Mon Sep 17 00:00:00 2001 From: Thomas Markwalder Date: Tue, 27 Oct 2015 10:15:54 -0400 Subject: [PATCH 08/10] [3979] Fixed a broken oops --- doc/guide/lease-expiration.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/guide/lease-expiration.xml b/doc/guide/lease-expiration.xml index a698df2065..3a95bc37da 100644 --- a/doc/guide/lease-expiration.xml +++ b/doc/guide/lease-expiration.xml @@ -294,7 +294,7 @@ 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. + process may impact server responsiveness.
From ba2386036d282f841dc5d46f17a83c896154c3da Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Tue, 27 Oct 2015 15:37:40 +0100 Subject: [PATCH 09/10] [3979] Corrected order of parameters in the lease-expiration.json. This is a result of the review. This change was suggested so as the order of lease expiration specific parameters follows the order in which they are described. --- doc/examples/kea4/leases-expiration.json | 2 +- doc/examples/kea6/leases-expiration.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/examples/kea4/leases-expiration.json b/doc/examples/kea4/leases-expiration.json index 3771eca8b3..b1397b3d18 100644 --- a/doc/examples/kea4/leases-expiration.json +++ b/doc/examples/kea4/leases-expiration.json @@ -27,10 +27,10 @@ # 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, - "hold-reclaimed-time": 1800, "unwarned-reclaim-cycles": 10 }, diff --git a/doc/examples/kea6/leases-expiration.json b/doc/examples/kea6/leases-expiration.json index 0f66bfc36c..59fea3022b 100644 --- a/doc/examples/kea6/leases-expiration.json +++ b/doc/examples/kea6/leases-expiration.json @@ -27,10 +27,10 @@ # 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, - "hold-reclaimed-time": 1800, "unwarned-reclaim-cycles": 10 }, From eff8e3d05b0d5cf9fbbb719c18d9f15133305acc Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Tue, 27 Oct 2015 15:46:40 +0100 Subject: [PATCH 10/10] [3979] Corrected a typos in the user guide. --- doc/guide/lease-expiration.xml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/guide/lease-expiration.xml b/doc/guide/lease-expiration.xml index 3a95bc37da..5b2c2c3737 100644 --- a/doc/guide/lease-expiration.xml +++ b/doc/guide/lease-expiration.xml @@ -20,8 +20,7 @@ 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. - . + time. The process through which the DHCP server makes expired leases available for reassignment is referred to as "lease reclamation" and expired @@ -50,7 +49,7 @@
Lease Reclamation - lease reclamation is the process through which an expired lease + 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: