From: Francis Dupont <fdupont@isc.org>
Date: Sun, 31 Mar 2024 21:32:06 +0000 (+0200)
Subject: [#2976] Added doc and ChangeLog entry
X-Git-Tag: Kea-2.5.8~5
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4160b00b4a641b20a131f81794d9921de7442e5b;p=thirdparty%2Fkea.git

[#2976] Added doc and ChangeLog entry
---

diff --git a/ChangeLog b/ChangeLog
index 8de62c3698..2755d01e57 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2227.	[func]		fdupont
+	Implemented the stash-agent-options global parameter
+	for DHCPv4 (new feature from ISC DHCP allowing to
+	renew reserved address when the host reservation identifier
+	is based on the dhcp-agent-options option added by a relay.
+	(Gitlab #2976)
+
 2226.	[func]		piotrek
 	Added information about transaction ID in all possible
 	places in loggers: alloc-engine, bad-packets, ddns,
diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst
index 3d75c07955..e55158b78d 100644
--- a/doc/sphinx/arm/dhcp4-srv.rst
+++ b/doc/sphinx/arm/dhcp4-srv.rst
@@ -4421,7 +4421,8 @@ Storing Extended Lease Information
 ----------------------------------
 
 To support such features as DHCP Leasequery
-(`RFC 4388 <https://tools.ietf.org/html/rfc4388>`__),
+(`RFC 4388 <https://tools.ietf.org/html/rfc4388>`__) and
+stash agent options (:ref:`stash-agent-options`)
 additional information must be stored with each lease. Because the amount
 of information for each lease has ramifications in terms of
 performance and system resource consumption, storage of this additional
@@ -4499,6 +4500,39 @@ and supports these levels:
    not to the lease file, i.e. inconsistent leases stay in the lease
    file.
 
+.. _stash-agent-options:
+
+Stash Agent Options
+-------------------
+
+Introduced in version 2.5.8 the ``stash-agent-options`` global parameter
+when set to ``true`` (its default is ``false``) allows to solve a common
+problem with host reservations using an identifier based on the content
+of the dhcp-agent-options option inserted relays. When a client tries
+to renew its reserved address the request is sent directly to the server
+so no through the relay: the server is not able to recognize the client
+as the host identifier can't be found in a direct request.
+
+Set in flex-id (:ref:`hooks-flex-id`) the ``replace-client-id`` to ``true``
+allows to use the same identifier for leases and host reservations.
+This solves some problems but not this one. In fact this configuration
+is incompatible with ``stash-agent-options``.
+
+When ``stash-agent-options`` is true for direct renewal requests the
+lease for the client address is fetched: if it exists, is not yet expired,
+belongs to the client and has additional information with the
+dhcp-agent-options option content. When all these conditions are met the
+server behaves as the option was included.
+
+.. note::
+
+   Here belongs to the client is implemented the same way as for Releases.
+   This guarantees the security of the feature but does not allow the use
+   the same identity for both leases and host reservations based on the
+   content of the dhcp-agent-options option, i.e. if the client changes
+   its identity (client id and/or hardware address) and there is an existing
+   not expired lease for the reserved address the lease will conflict.
+
 .. _dhcp4-multi-threading-settings:
 
 Multi-Threading Settings