[#2976] Added doc and ChangeLog entry

diff --git a/ChangeLog b/ChangeLog
index 8de62c369861e1241f995bf3e96e9d30bcf6ccfa..2755d01e57ebf533f99ae6add8919cbf708f9136 100644 (file)
--- 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 3d75c07955ff3a7205f1dff785add1e5a0c54c8e..e55158b78dd089c9ca454e26a8ad5af317f7b249 100644 (file)
--- 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