[3979] Did some clean up and rewording

doc/guide/ctrl-channel.xml

@@ -133,8 +133,8 @@ configuration file.</para>
         the lease database (if true), or they should be left in the
         <emphasis>expired-reclaimed</emphasis> state (if false). The latter
         facilitates lease affinity, i.e. ability to re-assign expired lease to
-        the same client which used this lease before. See the
+        the same client which used this lease before. See
-        <xref linkend="lease-affinity"/> for the details. Also, see the
+        <xref linkend="lease-affinity"/> for the details. Also, see
         <xref linkend="lease-reclamation"/> for the general information
         about the processing of expired leases (leases reclamation).</para>
       </section>

doc/guide/lease-expiration.xml

@@ -6,38 +6,41 @@
 <chapter id="lease-expiration">
   <title>Lease Expiration in DHCPv4 and DHCPv6</title>
 
-  <para>The major role of the DHCP server is to assign addresses or/and
+  <para>The primary role of the DHCP server is to assign addresses and/or
-  delegate prefixes to the DHCP clients. These addresses and delegated
+  delegate prefixes to DHCP clients. These addresses and prefixes are
-  prefixes are often referred to as 'leases'. The leases are typically
+  often referred to as 'leases'. Leases are typically assigned to clients
-  assigned to the clients for a finite amount of time, known as
+  for a finite amount of time, known as 'valid lifetime'. DHCP clients who
-  'valid lifetime'. The DHCP client willing to continue using the assigned
+  wish to continue using their assigned leases, will periodically renew them
-  leases, will periodically renew them by sending appropriate message
+  by sending the appropriate message to the DHCP server. The DHCP server records
-  to the DHCP server. The DHCP server records the time when the lease
+  the time when these leases are renewed and calculates new expiration times
-  is renewed and calculates a new expiration time for it.
+  for them.
   </para>
 
-  <para>If the client does not renew a lease and its valid lifetime
+  <para>If the client does not renew a lease before its valid lifetime
   elapses, the lease is considered expired. There are many situations
-  when the client may cease lease renewals.
+  when the client may cease lease renewals.  A common scenario is when
-  The most obvious one is the shutdown of the machine running the
+  the machine running the client shuts down for an extended period of
-  client.</para>
+  time.
+  .</para>
+
+  <para> The process through which the DHCP server makes expired leases
+  available for reassignment is referred to as "lease reclamation" and expired
+  leases returned to availability through this process are referred to as
+  "reclaimed".
 
-  <para>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
+  that it has expired. One way in which the server may detect expiration
-  expiration is when it is trying to allocate a lease to a client and
+  is when it is trying to allocate a lease to a client and finds this
-  it finds this lease is already present in the database. If this lease
+  lease already present in the database but expired.  Another way the
-  is expired, it may be allocated to the same or another client, but it
+  server detects expired leases is by periodically querying the lease
-  must be first reclaimed. Another way the server detects
+  database for them.  Regardless of how an expired lease is detected, before
-  expired leases is by periodically quering the lease database. The
+  it my assigned to a client, it must be reclaimed.
-  further sections of this chapter explain how to configure the server
+
-  to periodically query for the expired leases and how to minimize the
+  This chapter explains how to configure the server to periodically query
-  impact of the periodic leases reclamation process on the server's
+  for the expired leases and how to minimize the impact of the periodic leases
-  responsiveness. Finally, the 'lease affinity' is explained, which
+  reclamation process on the server's responsiveness. Finally, 'lease affinity',
-  provides means to assign the same lease to the returning client
+  which provides the means to assign the same lease to the returning client
-  after its lease has expired.
+  after its lease has expired, is explained.
   </para>
 
   <para>Although, all configuration examples in this section are provided
@@ -47,7 +50,7 @@
 
   <section id="lease-reclamation">
     <title>Lease Reclamation</title>
-    <para>The lease reclamation is a process in which an expired lease
+    <para>lease reclamation is the process through which an expired lease
     becomes available for assignment to the same or a different client.
     This process involves the following steps for each reclaimed lease:
     </para>
@@ -73,30 +76,29 @@
       </listitem>
     </itemizedlist>
 
-    <para>Please refer to the <xref linkend="dhcp-ddns-server"/> to see
+    <para>Please refer to <xref linkend="dhcp-ddns-server"/> to see
-    how to configure the DNS updates in Kea, and to the
+    how to configure DNS updates in Kea, and to
     <xref linkend="hooks-libraries"/> for information about using
     hooks libraries.</para>
   </section>
 
   <section id="lease-reclaim-config">
     <title>Configuring Leases Reclamation</title>
-    <para>Kea can be configured to periodically detect and process expired
+    <para>Kea can be configured to periodically detect and reclaim expired
     leases. During this process the lease entries in the database are
-    modified or removed, therefore the server will not process incoming DHCP
+    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
+    As a result, the server will be unresponsive while lease reclamation
-    is performed, the DHCP queries will accumulate and responses will be
+    is performed. DHCP queries will accumulate and responses will be
     sent once the leases reclamation cycle is complete.</para>
 
-    <para>In the deployments where the response time is critical, the
+    <para>In deployments where response time is critical, administrators may
-    administrators want to minimize the interruptions in the service
+    wish to minimize the interruptions in service caused by lease reclamation.
-    caused by the processing of expired leases. Kea provides a set of
+    Toward this end, Kea provides configuration parameters to control: the
-    configuration parameters to control the frequency of leases reclamation,
+    frequency of lease reclamation cycles, the maximum number of leases
-    the maximum number of leases processed in a single cycle and the
+    processed in a single reclamation cycle, and the maximum amount of time a
-    timeout after which the reclamation should be interrupted. The
+    single reclamation cycle is allowed to run before being interrupted. The
-    following configuration examples demonstrate how these parameters
+    following examples demonstrate how these parameters can be used:
-    can be used:
 
 <screen>
 "Dhcp4": {
@@ -142,18 +144,17 @@
     queries and does not perform leases reclamation. The
     <command>max-reclaim-leases</command> and
     <command>max-reclaim-time</command> are set to 0, which implies that
-    there is no restriction on the maximum number of reclaimed leases
+    there is no restriction on the maximum number of leases reclaimed
-    in the particular cycle, and the maximum duration of each cycle.
+    in the particular cycle, or the maximum duration of each cycle.
     </para>
 
-    <para>In the deployments with high lease pool utilization, relatively
+    <para>In deployments with high lease pool utilization, relatively
-    short valid lifetimes and clients often disconnecting allowing the
+    short valid lifetimes, and frequently disconnecting clients which
-    leases to expire, the number of expired leases requiring reclamation
+    allow leases to expire; the number of expired leases requiring reclamation
-    at the given time may rise significantly. In this case it is often
+    at any given time may rise significantly. In this case it is often
-    desired to apply restrictions on the maximum duration of the leases
+    desirable to apply restrictions on the maximum duration of a reclamation
-    reclamation cycle or the number of leases that can be reclaimed in
+    cycle or the maximum number of leases reclaimed in a cycle. The following
-    this cycle. The following configuration demonstrates how this
+    configuration demonstrates how this can be done:
-    can be done:
 
 <screen>
 "Dhcp4": {
@@ -175,10 +176,10 @@
     </para>
 
     <para>The <command>max-reclaim-leases</command> parameter limits the number
-    of leases reclaimed in the single cycle to 100. The
+    of leases reclaimed in a single cycle to 100. The
     <command>max-reclaim-time</command> limits the maximum duration of each
-    cycle to 50ms. The lease reclamation cycle will be interrupted when
+    cycle to 50ms. The lease reclamation cycle will be interrupted if either
-    first of these limitations is hit. The reclamation of all unreclaimed
+    of these limitations is reached. The reclamation of all unreclaimed
     leases will be attempted in subsequent cycles.</para>
 
     <para>The following diagram illustrates the behavior of the system in the
@@ -200,50 +201,47 @@
     more than 50ms, and thus is interrupted according to the value of the
     <command>max-reclaim-time</command>. This results in equal durations of
     all reclamation cycles over time. Note that in this example the limitation
-    of maximum 100 leases is not hit. This may be the case when the database
+    of maximum 100 leases is not reached. This may be the case when database
-    transactions are slow or the callouts in the hook libraries attached to
+    transactions are slow or callouts in the hook libraries attached to
-    the server are slow. In any case, the choice between the selecting the
+    the server are slow.  Regardless, the choosing values for either the
-    specific number of leases or the maximum time for the lease reclamation
+    maximum number of leases or a maximum cycle time strongly depends on the
-    strongly depends on the particular deployment, used lease database
+    particular deployment, lease database backend being used, and any hooks
-    backend, hooks libraries etc.</para>
+    libraries etc.  Administrators may need to experiment to tune the system
+    to suit the dynamics of their deployment.</para>
 
-    <para>If the limits are applied on the maximum number of reclaimed leases
+    <para>It is important to realize that with the use of these limits, there
-    or the maximum time for a single reclamation cycle, there is a risk
+    is a risk that expired leases will accumulate faster than the server can
-    that the server will not be able to catch up the number of expired
+    reclaim them.  This should not be the problem if the server is dealing
-    leases to reclaim. This should not be the problem if the server is
+    with a temporary burst of expirations, because it should be able to
-    dealing with a temporary burst of expirations, because it should be
+    eventually deal with them over time. However, if leases expire at the high
-    able to eventually deal with them over time. However, if leases
+    rate for a longer period of time, the unreclaimed leases will pile up in
-    expire at the high rate for a longer period of time, the unreclaimed
+    the database. In order to notify the administrator that the current
-    leases will pile up in the database. In order to notify the administrator
+    configuration does not satisfy the needs for reclamation of expired
-    that the current configuration does not satisfy the needs for
+    leases, the server issues a warning message in the log, if it was unable
-    reclamation of expired leases, the server issues a warning message
+    to reclaim all leases within the last couple of reclamation cycles. The
-    in the log, if it was unable to reclaim all leases within the last
+    number of cycles after which such warning is issued is specified with the
-    couple of reclamation cycles. The number of cycles after which such
-    warning is issued is specified with the
     <command>unwarned-reclaim-cycles</command> configuration parameter.
     </para>
 
     <para>Setting the <command>reclaim-timer-wait-time</command> to 0 disables
     periodic reclamation of the expired leases.</para>
-
   </section>
 
   <section id="lease-affinity">
     <title>Configuring Lease Affinity</title>
-    <para>Suppose that the laptop goes to a sleep mode after a period of user's
+    <para>Suppose that a laptop goes to a sleep mode after a period of user
-    inactivity. While the laptop is in the sleep mode, the DHCP client
+    inactivity.  While the laptop is in sleep mode, its DHCP client will not
-    running on it will not renew leases obtained from the server and the
+    renew leases obtained from the server and these leases will eventually
-    leases will eventually expire. When the laptop wakes up from the
+    expire.  When the laptop wakes up, it is often desired that it continue
-    sleep mode, it is often desired that it can continue using previous
+    using its previous assigned IP addresses. In order to facilitate this,
-    IP addresses. In order to facilitate it, the server needs to correlate
+    the server needs to correlate returning clients with their expired leases
-    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
-    When the client returns, the server will first check for those
+    re-assign them if they have not assigned to another client.  The ability
-    leases and re-assign them if they are still available (not assigned
+    of the server to re-assign the same lease to a returning client is
-    to another client). The ability of the server to re-assign the same
+    referred to as 'lease affinity'.
-    lease to the returning client is referred to as 'lease affinity'.
     </para>
 
-    <para>When the lease affinity is enabled, the server would still
+    <para>When lease affinity is enabled, the server will still
     reclaim leases according to the parameters described in
     <xref linkend="lease-reclaim-config"/>, but the reclaimed leases
     will be held in the database (rather than removed) for the specified
@@ -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
+    specifically asks for it. Therefore, the lease affinity does not
-    the reclaimed lease will be available for the client who used it
+    guarantee that the reclaimed lease will be available for the client
-    before. It merely increases the chances for the client to be assigned
+    who used it before. It merely increases the chances for the client to
-    the same lease. If the lease pool is small (mostly applies to DHCPv4
+    be assigned the same lease. If the lease pool is small (mostly applies
-    for which address space is small), there is an increased likelihood
+    to DHCPv4 for which address space is small), there is an increased
-    that the expired lease will be hijacked by another client.
+    likelihood that the expired lease will be hijacked by another client.
     </para>
 
     <para>Consider the following configuration:
@@ -279,27 +277,24 @@
 
     <para>The <command>hold-reclaim-time</command> specifies how many seconds
     after an expiration a reclaimed lease should be held in the database
-    for re-assignment to the same client. In the example given above, 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.</para>
 
-    <para>The server must occasionally remove reclaimed leases for which the
+    <para>The server must periodically remove reclaimed leases for which the
-    time indicated by <command>hold-reclaim-time</command> elapsed. The
+    time indicated by <command>hold-reclaim-time</command> has elapsed. The
     <command>flush-reclaimed-timer-wait-time</command> controls how
     often the server removes such leases. In the example provided
-    above, the server will initiate removal of 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
+    lease database when they are reclaimed.  If lease affinity is enabled, it
-    enabled, it is recommended that this parameter is set to significantly
+    is recommended that hold-reclaim-time be set to a value significantly
-    higher value than the <command>reclaim-timer-wait-time</command>
+    higher than the <command>reclaim-timer-wait-time</command>, as timely
-    because timely removal of expired-reclaimed leases is not critical,
+    removal of expired-reclaimed leases is less critical while the removal
-    while this removal impacts the server's responsiveness, because the
+    process may impact server responsiveness.
-    server doesn't process DHCP messages while it removes leases from
-    the database.</para>
-
   </section>
 
   <section id="lease-reclamation-defaults">

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)
+interrupted by sending data over a dedicated (for a timer)
-@c isc::util::WatchSocket. Each timer has an instance of the
+@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
+by @c isc::dhcp::TimerMgr. This worker thread runs an instance
-of the @c isc::asiolink::IOService object, associated with all
+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
+lease database used. While the reclamation routine is
-executed, the server is not processing any DHCP messages to avoid
+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