[#2548] updated documentation

15 files changed, 91 insertions, 24 deletions

diff --git a/ChangeLog b/ChangeLog
index 8b827c9034..3c74239ed2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,8 +1,14 @@
-2072.	[build]		razvan
+2073.	[build]		razvan
 	The library version numbers have been bumped for the Kea 2.3.2
 	development release.
 	(Gitlab #2607)
 
+2072.	[func]		razvan
+	If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time"
+	are not 0, when the client sends a release message the lease is
+	expired instead of being deleted from the lease storage.
+	(Gitlab #2548)
+
 2071.	[perf]		andrei
 	Significantly improved the performance of editing configuration
 	with kea-netconf. Instead of making a request to the sysrepo
diff --git a/doc/examples/kea4/all-keys-netconf.json b/doc/examples/kea4/all-keys-netconf.json
index baa1594c22..5122e9136b 100644
--- a/doc/examples/kea4/all-keys-netconf.json
+++ b/doc/examples/kea4/all-keys-netconf.json
@@ -253,10 +253,18 @@
         "expired-leases-processing": {
             // Specifies the number of seconds since last removal of
             // the expired leases when next removal should occur.
+            // If both "flush-reclaimed-timer-wait-time" and
+            // "hold-reclaimed-time" are not 0, when the client sends a release
+            // message the lease is expired instead of being deleted from the
+            // lease storage.
             "flush-reclaimed-timer-wait-time": 25,
 
             // Specifies the time period in seconds to keep expired
             // leases in the lease database (lease affinity).
+            // If both "flush-reclaimed-timer-wait-time" and
+            // "hold-reclaimed-time" are not 0, when the client sends a release
+            // message the lease is expired instead of being deleted from the
+            // lease storage.
             "hold-reclaimed-time": 3600,
 
             // Specifies the maximum number of expired leases that can be
diff --git a/doc/examples/kea4/all-keys.json b/doc/examples/kea4/all-keys.json
index 383a5bef99..75072f0928 100644
--- a/doc/examples/kea4/all-keys.json
+++ b/doc/examples/kea4/all-keys.json
@@ -262,10 +262,18 @@
         "expired-leases-processing": {
             // Specifies the number of seconds since last removal of
             // the expired leases when next removal should occur.
+            // If both "flush-reclaimed-timer-wait-time" and
+            // "hold-reclaimed-time" are not 0, when the client sends a release
+            // message the lease is expired instead of being deleted from the
+            // lease storage.
             "flush-reclaimed-timer-wait-time": 25,
 
             // Specifies the time period in seconds to keep expired
             // leases in the lease database (lease affinity).
+            // If both "flush-reclaimed-timer-wait-time" and
+            // "hold-reclaimed-time" are not 0, when the client sends a release
+            // message the lease is expired instead of being deleted from the
+            // lease storage.
             "hold-reclaimed-time": 3600,
 
             // Specifies the maximum number of expired leases that can be
diff --git a/doc/examples/kea4/leases-expiration.json b/doc/examples/kea4/leases-expiration.json
index c40dd5d546..f2f4332eef 100644
--- a/doc/examples/kea4/leases-expiration.json
+++ b/doc/examples/kea4/leases-expiration.json
@@ -31,6 +31,9 @@
 // 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.
+// If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are not
+// 0, when the client sends a release message the lease is expired instead of
+// being deleted from the lease storage.
   "expired-leases-processing": {
     "reclaim-timer-wait-time": 5,
     "hold-reclaimed-time": 1800,
diff --git a/doc/examples/kea6/all-keys-netconf.json b/doc/examples/kea6/all-keys-netconf.json
index cce7e8ec37..a1def030f6 100644
--- a/doc/examples/kea6/all-keys-netconf.json
+++ b/doc/examples/kea6/all-keys-netconf.json
@@ -213,10 +213,18 @@
         "expired-leases-processing": {
             // Specifies the number of seconds since last removal of
             // the expired leases when next removal should occur.
+            // If both "flush-reclaimed-timer-wait-time" and
+            // "hold-reclaimed-time" are not 0, when the client sends a release
+            // message the lease is expired instead of being deleted from the
+            // lease storage.
             "flush-reclaimed-timer-wait-time": 25,
 
             // Specifies the time period in seconds to keep expired
             // leases in the lease database (lease affinity).
+            // If both "flush-reclaimed-timer-wait-time" and
+            // "hold-reclaimed-time" are not 0, when the client sends a release
+            // message the lease is expired instead of being deleted from the
+            // lease storage.
             "hold-reclaimed-time": 3600,
 
             // Specifies the maximum number of expired leases that can be
diff --git a/doc/examples/kea6/all-keys.json b/doc/examples/kea6/all-keys.json
index ccc395073b..fe0a6f424e 100644
--- a/doc/examples/kea6/all-keys.json
+++ b/doc/examples/kea6/all-keys.json
@@ -216,10 +216,18 @@
         "expired-leases-processing": {
             // Specifies the number of seconds since last removal of
             // the expired leases when next removal should occur.
+            // If both "flush-reclaimed-timer-wait-time" and
+            // "hold-reclaimed-time" are not 0, when the client sends a release
+            // message the lease is expired instead of being deleted from the
+            // lease storage.
             "flush-reclaimed-timer-wait-time": 25,
 
             // Specifies the time period in seconds to keep expired
             // leases in the lease database (lease affinity).
+            // If both "flush-reclaimed-timer-wait-time" and
+            // "hold-reclaimed-time" are not 0, when the client sends a release
+            // message the lease is expired instead of being deleted from the
+            // lease storage.
             "hold-reclaimed-time": 3600,
 
             // Specifies the maximum number of expired leases that can be
diff --git a/doc/examples/kea6/leases-expiration.json b/doc/examples/kea6/leases-expiration.json
index 5a3eeb4290..c5320ff7ed 100644
--- a/doc/examples/kea6/leases-expiration.json
+++ b/doc/examples/kea6/leases-expiration.json
@@ -31,6 +31,9 @@
 // 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.
+// If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are not
+// 0, when the client sends a release message the lease is expired instead of
+// being deleted from the lease storage.
   "expired-leases-processing": {
     "reclaim-timer-wait-time": 5,
     "hold-reclaimed-time": 1800,
diff --git a/doc/examples/template-ha-mt-tls/kea-dhcp4-1.conf b/doc/examples/template-ha-mt-tls/kea-dhcp4-1.conf
index 5bff5c19d4..6b38a2c063 100644
--- a/doc/examples/template-ha-mt-tls/kea-dhcp4-1.conf
+++ b/doc/examples/template-ha-mt-tls/kea-dhcp4-1.conf
@@ -76,6 +76,9 @@
     // will keep the leases in expired state for 2 days. This greatly increases the
     // chances for returning devices to get the same address again. To guarantee that,
     // use host reservation.
+    // If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are
+    // not 0, when the client sends a release message the lease is expired
+    // instead of being deleted from the lease storage.
     "expired-leases-processing": {
         "reclaim-timer-wait-time": 3600,
         "hold-reclaimed-time": 172800,
diff --git a/doc/examples/template-ha-mt-tls/kea-dhcp4-2.conf b/doc/examples/template-ha-mt-tls/kea-dhcp4-2.conf
index dcdfc332b4..ed65d7a3f0 100644
--- a/doc/examples/template-ha-mt-tls/kea-dhcp4-2.conf
+++ b/doc/examples/template-ha-mt-tls/kea-dhcp4-2.conf
@@ -76,6 +76,9 @@
     // will keep the leases in expired state for 2 days. This greatly increases the
     // chances for returning devices to get the same address again. To guarantee that,
     // use host reservation.
+    // If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are
+    // not 0, when the client sends a release message the lease is expired
+    // instead of being deleted from the lease storage.
     "expired-leases-processing": {
         "reclaim-timer-wait-time": 3600,
         "hold-reclaimed-time": 172800,
diff --git a/doc/examples/template-power-user-home/kea-dhcp4-1.conf b/doc/examples/template-power-user-home/kea-dhcp4-1.conf
index 3ff57feac7..8d635560ab 100644
--- a/doc/examples/template-power-user-home/kea-dhcp4-1.conf
+++ b/doc/examples/template-power-user-home/kea-dhcp4-1.conf
@@ -57,6 +57,9 @@
     // will keep the leases in expired state for 2 days. This greatly increases the
     // chances for returning devices to get the same address again. To guarantee that,
     // use host reservation.
+    // If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are
+    // not 0, when the client sends a release message the lease is expired
+    // instead of being deleted from the lease storage.
     "expired-leases-processing": {
         "reclaim-timer-wait-time": 3600,
         "hold-reclaimed-time": 172800,
diff --git a/doc/examples/template-power-user-home/kea-dhcp4-2.conf b/doc/examples/template-power-user-home/kea-dhcp4-2.conf
index bba501ab43..731671bb1e 100644
--- a/doc/examples/template-power-user-home/kea-dhcp4-2.conf
+++ b/doc/examples/template-power-user-home/kea-dhcp4-2.conf
@@ -57,6 +57,9 @@
     // will keep the leases in expired state for 2 days. This greatly increases the
     // chances for returning devices to get the same address again. To guarantee that,
     // use host reservation.
+    // If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are
+    // not 0, when the client sends a release message the lease is expired
+    // instead of being deleted from the lease storage.
     "expired-leases-processing": {
         "reclaim-timer-wait-time": 3600,
         "hold-reclaimed-time": 172800,
diff --git a/doc/sphinx/arm/config-templates.rst b/doc/sphinx/arm/config-templates.rst
index c98b795b02..caff036b81 100644
--- a/doc/sphinx/arm/config-templates.rst
+++ b/doc/sphinx/arm/config-templates.rst
@@ -23,7 +23,7 @@ Server1's DHCPv4 configuration file:
 
 .. literalinclude:: template-power-user-home-dhcp4-1.conf
    :language: javascript
-   :emphasize-lines: 25, 76, 81, 121, 133, 148, 152, 155-159, 167-181, 191-200
+   :emphasize-lines: 25, 79, 84, 124, 136, 151, 155, 158-162, 170-184, 194-203
    :linenos:
 
 Server2's Control Agent configuration file:
@@ -37,7 +37,7 @@ Server2's DHCPv4 configuration file:
 
 .. literalinclude:: template-power-user-home-dhcp4-2.conf
    :language: javascript
-   :emphasize-lines: 25, 76, 81, 121, 133, 148, 152, 155-159, 167-181, 191-200
+   :emphasize-lines: 25, 79, 84, 124, 136, 151, 155, 158-162, 170-184, 194-203
    :linenos:
 
 .. include:: template-ha-mt-tls.md
@@ -49,26 +49,26 @@ Server1's Control Agent configuration file:
 
 .. literalinclude:: template-ha-mt-tls-ca-1.conf
    :language: javascript
-   :emphasize-lines: 10, 14, 17, 20, 23, 32
+   :emphasize-lines: 10, 14, 18, 21, 24, 36
    :linenos:
 
 Server1's DHCPv4 configuration file:
 
 .. literalinclude:: template-ha-mt-tls-dhcp4-1.conf
    :language: javascript
-   :emphasize-lines: 25, 38-54, 95, 100, 133-142, 151, 153, 155, 157, 169, 171, 173, 175, 190, 194, 197-201
+   :emphasize-lines: 25, 38-54, 98, 103, 139-152, 161, 163, 165, 167, 181, 183, 185, 187, 204, 208, 211-215
    :linenos:
 
 Server2's Control Agent configuration file:
 
 .. literalinclude:: template-ha-mt-tls-ca-2.conf
    :language: javascript
-   :emphasize-lines: 10, 14, 17, 20, 23, 32
+   :emphasize-lines: 10, 14, 18, 21, 24, 36
    :linenos:
 
 Server2's DHCPv4 configuration file:
 
 .. literalinclude:: template-ha-mt-tls-dhcp4-2.conf
    :language: javascript
-   :emphasize-lines: 25, 38-54, 95, 100, 133-142, 151, 153, 155, 157, 169, 171, 173, 175, 190, 194, 197-201
+   :emphasize-lines: 25, 38-54, 98, 103, 139-152, 161, 163, 165, 167, 181, 183, 185, 187, 204, 208, 211-215
    :linenos:
diff --git a/doc/sphinx/arm/lease-expiration.rst b/doc/sphinx/arm/lease-expiration.rst
index 7742f25e3a..26ae67cf2d 100644
--- a/doc/sphinx/arm/lease-expiration.rst
+++ b/doc/sphinx/arm/lease-expiration.rst
@@ -81,12 +81,16 @@ processing expired leases, with their default values:
 
 -  ``flush-reclaimed-timer-wait-time`` - this parameter controls how
    often the server initiates the lease reclamation procedure. Expressed in
-   seconds; the default value is 25.
+   seconds; the default value is 25. If both ``flush-reclaimed-timer-wait-time``
+   and ``hold-reclaimed-time`` are not 0, when the client sends a release
+   message the lease is expired instead of being deleted from the lease storage.
 
 -  ``hold-reclaimed-time`` - this parameter governs how long the lease
    should be kept after it is reclaimed. This enables lease affinity
    when set to a non-zero value. Expressed in seconds; the default value
-   is 3600.
+   is 3600. If both ``flush-reclaimed-timer-wait-time`` and
+   ``hold-reclaimed-time`` are not 0, when the client sends a release message
+   the lease is expired instead of being deleted from the lease storage.
 
 -  ``max-reclaim-leases`` - this parameter specifies the maximum number
    of reclaimed leases that can be processed at one time. Zero means
@@ -256,21 +260,22 @@ leases and reassigns them if they have not been assigned to another
 client. The ability of the server to reassign the same lease to a
 returning client is referred to as "lease affinity."
 
-When lease affinity is enabled (i.e. when ``hold-reclaimed-time`` is
-configured to a value greater than zero), the server still reclaims
-leases according to the parameters described in :ref:`lease-reclaim-config`,
-but the reclaimed leases are
-held in the database for a specified amount of
-time rather than removed. When the client returns, the server first verifies whether
-there are any reclaimed leases associated with this client and then
-reassigns them if possible. However, it is important to note that any
-reclaimed lease may be assigned to another client if that client
-specifically asks for it. Therefore, lease affinity does not guarantee
-that the reclaimed lease will be available for the client who used it
-before; it merely increases the chances of the client being assigned
-the same lease. If the lease pool is small - namely, in
-DHCPv4, for which address space is limited - there is an increased
-likelihood that the expired lease will be assigned to another client.
+When lease affinity is enabled (i.e. when ``hold-reclaimed-time`` is configured
+to a value greater than zero), the server still reclaims leases according to the
+parameters described in :ref:`lease-reclaim-config`, but the reclaimed leases
+are held in the database for a specified amount of time rather than removed.
+If both ``flush-reclaimed-timer-wait-time`` and ``hold-reclaimed-time`` are
+greater than zero, the lease is expired immediately when the client sends a
+release message instead of being deleted from the lease storage. When the client
+returns, the server first verifies whether there are any reclaimed leases
+associated with this client and then reassigns them if possible. However, it is
+important to note that any reclaimed lease may be assigned to another client if
+that client specifically asks for it. Therefore, lease affinity does not
+guarantee that the reclaimed lease will be available for the client who used it
+before; it merely increases the chances of the client being assigned the same
+lease. If the lease pool is small - namely, in DHCPv4, for which address space
+is limited - there is an increased likelihood that the expired lease will be
+assigned to another client.
 
 Consider the following configuration:
 
diff --git a/src/bin/keactrl/kea-dhcp4.conf.pre b/src/bin/keactrl/kea-dhcp4.conf.pre
index a2f00e77eb..47f66eb08c 100644
--- a/src/bin/keactrl/kea-dhcp4.conf.pre
+++ b/src/bin/keactrl/kea-dhcp4.conf.pre
@@ -86,6 +86,9 @@
     // are 100 leases or 250 ms for a single cycle. A warning message
     // will be logged if there are still expired leases in the
     // database after 5 consecutive reclamation cycles.
+    // If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are
+    // not 0, when the client sends a release message the lease is expired
+    // instead of being deleted from the lease storage.
     "expired-leases-processing": {
         "reclaim-timer-wait-time": 10,
         "flush-reclaimed-timer-wait-time": 25,
diff --git a/src/bin/keactrl/kea-dhcp6.conf.pre b/src/bin/keactrl/kea-dhcp6.conf.pre
index 92ef1b76ad..acb10a363b 100644
--- a/src/bin/keactrl/kea-dhcp6.conf.pre
+++ b/src/bin/keactrl/kea-dhcp6.conf.pre
@@ -80,6 +80,9 @@
     // are 100 leases or 250 ms for a single cycle. A warning message
     // will be logged if there are still expired leases in the
     // database after 5 consecutive reclamation cycles.
+    // If both "flush-reclaimed-timer-wait-time" and "hold-reclaimed-time" are
+    // not 0, when the client sends a release message the lease is expired
+    // instead of being deleted from the lease storage.
     "expired-leases-processing": {
         "reclaim-timer-wait-time": 10,
         "flush-reclaimed-timer-wait-time": 25,