From 69380a93fdce4c6bf0fa8772c7bec2a8b42bd504 Mon Sep 17 00:00:00 2001
From: Thomas Markwalder <tmark@isc.org>
Date: Fri, 7 Feb 2025 13:53:47 -0500
Subject: [PATCH] [#3463] Updated ARM

new file:
    changelog_unreleased/3463-optionally-store-response-dhcp-options-in-lease-user-context

modified:
    doc/sphinx/arm/hooks-lease-cmds.rst
---
 ...esponse-dhcp-options-in-lease-user-context |  6 ++
 doc/sphinx/arm/hooks-lease-cmds.rst           | 91 +++++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 changelog_unreleased/3463-optionally-store-response-dhcp-options-in-lease-user-context

diff --git a/changelog_unreleased/3463-optionally-store-response-dhcp-options-in-lease-user-context b/changelog_unreleased/3463-optionally-store-response-dhcp-options-in-lease-user-context
new file mode 100644
index 0000000000..ebbccebb87
--- /dev/null
+++ b/changelog_unreleased/3463-optionally-store-response-dhcp-options-in-lease-user-context
@@ -0,0 +1,6 @@
+[func]		tmark
+	The lease-cmds hook library now supports storing
+    custom values, referred to as ``binding-variables``,
+    within the lease's ``user-context``.  Supported
+    in both kea-dhcp4 and kea-dhcp6.
+	(Gitlab #3463)
diff --git a/doc/sphinx/arm/hooks-lease-cmds.rst b/doc/sphinx/arm/hooks-lease-cmds.rst
index 58320b09f9..e4046c9ab6 100644
--- a/doc/sphinx/arm/hooks-lease-cmds.rst
+++ b/doc/sphinx/arm/hooks-lease-cmds.rst
@@ -17,6 +17,10 @@ of the subnet to which it is supposed to belong. The library also
 provides a non-programmatic way to manage user contexts associated with
 leases.
 
+As of Kea 2.7.7, the library also provides support for ``binding-varriables``. Binding
+variables allow the user to store custom values for each lease. They are discussed here:
+:ref:`binding-variables`.
+
 .. note::
 
     :ischooklib:`libdhcp_lease_cmds.so` is part of the open source code and is
@@ -1094,3 +1098,90 @@ to the previous filename: for example, ``.bak14326``.
    These commands do not replace the LFC mechanism; they should be used
    only in exceptional circumstances, such as when recovering after
    running out of disk space.
+
+.. _binding-variables:
+
+Binding Variables
+~~~~~~~~~~~~~~~~~
+
+Binding variables allow users to store custom values with each lease. The
+values are calculated using expressions and stored in the lease's
+``user-context``.  The feature is similar to ISC DHCP's ``set`` statement.
+
+They are configured as parameters for the lease-cmds hook library.  Each
+variable has the following parameters:
+
+* name
+    The name of the variable that will appear in the ``user-context``. The
+    name must be unique within the list of binding variables..
+* expression
+    The expression used to calculate the variable's value (see :ref:
+    `classification-using-expressions`).
+* source
+    The packet to use as input for the  expression. It is either ``query``
+    (the packet sent by the client) or ``response`` (the packet the server
+    is sending in response).
+
+The following example would store a user-defined option sent by the
+client along with the domain-name sent by the server for each DCHPv4
+lease:
+
+.. code-block:: javascript
+
+    "hooks-libraries": [{
+        "library": "lib/kea/hooks/libdhcp_lease_cmds.so",
+        "parameters": {
+            "binding-variables": [{
+                "name": "opt-222",
+                "expression": "hexstring(option[222].hex, ':')",
+                "source": "query"
+            },{
+
+                "name": "domain-name",
+                "expression": "option[15].text",
+                "source": "response"
+            }]
+        }
+    }]
+
+The values are stored as name-value pairs in the ``ISC`` map in the lease's ``user-context``
+contents would look similar to the following:
+
+.. code-block:: javascript
+
+    {
+        "ISC": {
+            "binding-variables": [{
+                "domain-name": "example.org",
+                "opt-222": "01:02:03:04",
+            }
+        ]}
+    }
+
+When stored in database back ends, the user-context will not contain line breaks
+as shown above and would appear as follows:
+
+.. code-block::
+
+    { "ISC": { "binding-variables": { "domain-name": "example.org", "opt-222": "01:02:03:04" } } }
+
+When using memfile lease storage, the ``user-context`` is output with commas replaced by
+the escape sequence "&#x2c".  This is necessary to prevent interference with the lease file
+parsing.  The example output above would appear as follows in a memfile lease file:
+
+.. code-block::
+
+    { "ISC": { "binding-variables": { "domain-name": "example.org"&#x2c "opt-222": "01:02:03:04" } } }
+
+
+Binding variable values are evaluated whenever a lease is assigned or renewed.
+For :iscman:`kea-dhcp4`, they are also added if ``offer-lifetime`` is greater than zero.
+The lease is only updated in the back end if the values have changed.
+
+.. note::
+
+    When used in conjunction with the HA hook library, the lease-cmds
+    hook library must be listed before HA in the server's ``hooks``
+    configuration.  This ensures that the binding variables are evaluated
+    before HA sends lease updates to its peer(s).
+