[#1010] Updated ARM and all-keys.json

modified:
doc/examples/kea4/all-keys.json
doc/examples/kea6/all-keys.json
doc/sphinx/arm/dhcp4-srv.rst
doc/sphinx/arm/dhcp6-srv.rst

doc/examples/kea4/all-keys.json

@@ -511,6 +511,10 @@
         // DHCP client renews the lease.
         "renew-timer": 30,
 
+        // Global value to store extended information (e.g. relay agent
+        // information) with each lease.
+        "store-extended-info:" true,
+
         // Governs how the Kea DHCPv4 server should deal with the invalid
         // data received from the client.
         "sanity-checks": {
@@ -609,6 +613,10 @@
                 // network is selected for client assignments.
                 "require-client-classes": [ "late" ],
 
+                // Turn off storage of extended information (e.g. relay agent
+                // information) with each lease for this shared-network.
+                "store-extended-info:" false,
+
                 // Shared network level server hostname set in 'sname' field.
                 "server-hostname": "",
 
@@ -672,6 +680,10 @@
                         // in 'siaddr'.
                         "next-server": "0.0.0.0",
 
+                        // Turn on storage of extended information (e.g. relay agent
+                        // information) with each lease for this subnet.
+                         "store-extended-info:" true,
+
                         // Subnet level list of DHCP options.
                         "option-data": [
                             {

doc/examples/kea6/all-keys.json

@@ -452,6 +452,10 @@
         // DHCP client renews the lease.
         "renew-timer": 30,
 
+        // Global value to store extended information (e.g. relay agent
+        // information) with each lease.
+        "store-extended-info:" true,
+
         // Governs how the Kea DHCPv6 server should deal with the invalid
         // data received from the client.
         "sanity-checks": {
@@ -574,6 +578,10 @@
                 // network is selected for client assignments.
                 "require-client-classes": [ "late" ],
 
+                // Turn off storage of extended information (e.g. relay agent
+                // information) with each lease for this shared-network.
+                "store-extended-info:" false,
+
                 // List of IPv6 subnets belonging to this shared network.
                 "subnet6": [
                     {
@@ -618,6 +626,10 @@
                         // which the response is sent.
                         "interface-id": "",
 
+                        // Turn on storage of extended information (e.g. relay agent
+                        // information) with each lease for this subnet.
+                         "store-extended-info:" true,
+
                         // Subnet level list of DHCP options.
                         "option-data": [
                             {

doc/sphinx/arm/dhcp4-srv.rst

@@ -3693,6 +3693,50 @@ An example configuration that sets this parameter looks as follows:
        ...
    }
 
+.. _dhcp4-store-extended-info:
+
+Storing Extended Lease Information
+----------------------------------
+In order to support such features as DHCP LeaseQuery
+(`RFC 4388 <https://tools.ietf.org/html/rfc4388>`__) it is necessary to
+store additional information with each lease.  Because the amount
+of information stored for each lease has ramifications in terms of
+performance and system resource consumption, storing this additional
+information is configurable through the "store-extended-info" parameter.
+It defaults to false and may be set at the global, shared-network, and
+subnet levels.
+
+::
+
+   "Dhcp4": {
+       "store-extended-info": true,
+       ...
+   }
+
+When enabled, information relevant to the DHCPREQUEST asking for the lease is
+added into the lease's user-context as a map element labeled "ISC".  Currently,
+the map will contain a single value, the relay-agent-info option (DHCP Option 82),
+when the DHCPREQUEST received contains it.  Other values may be added at a
+future date. Since DHCPREQUESTs sent as renewals will likely not contain this
+information, the values taken from the last DHCPREQUEST that did contain it will
+be retained on the lease.  The lease's user-context will look something like this:
+
+::
+
+  { "ISC": { "relay-agent-info": "0x52050104AABBCCDD" } }
+
+.. note::
+    This feature is intended to be used in conjunction with an upcoming LeaseQuery
+    hook library and at this time there is other use for this information within Kea.
+
+.. note::
+    It is possible that other hook libraries are already making use of user-context.
+    Enabling store-extended-info should not interfere with any other user-context
+    content so long as it does not also use an element labled "ISC".  In other
+    words, user-context is intended to be a flexible container serving mulitple
+    purposes.  As long as no other purpose also writes an "ISC" element to
+    user-contex there should not be a conflict.
+
 .. _host-reservation-v4:
 
 Host Reservation in DHCPv4

doc/sphinx/arm/dhcp6-srv.rst

@@ -3187,6 +3187,68 @@ An example configuration that sets this parameter looks as follows:
        ...
    }
 
+.. _store-extended-info-v6:
+
+Storing Extended Lease Information
+----------------------------------
+In order to support such features as DHCPv6 Reconfigure
+(`RFC 3315 <https://tools.ietf.org/html/rfc3315>`__) and LeaseQuery
+(`RFC 5007 <https://tools.ietf.org/html/rfc5007>`__) it is necessary to
+store additional information with each lease.  Because the amount
+of information stored for each lease has ramifications in terms of
+performance and system resource consumption, storing this additional
+information is configurable through the "store-extended-info" parameter.
+It defaults to false and may be set at the global, shared-network, and
+subnet levels.
+
+::
+
+   "Dhcp6": {
+       "store-extended-info": true,
+       ...
+   }
+
+When enabled, information relevant to the DHCPv6 query (e.g. REQUEST, RENEW,
+or REBIND) asking for the lease is added into the lease's user-context as a
+map element labeled "ISC".  Currently the information contained in the map
+will be a list of relays, one for each relay message layer that encloses the
+client query. Other values may be added at a future date. The lease's
+user-context for a two-hop query might look something like this (shown
+pretty-printed for clarity):
+
+::
+
+    {
+        "ISC": {
+            "relays": [
+            {
+                "hop": 2,
+                "link": "2001:db8::1",
+                "peer": "2001:db8::2"
+            },
+            {
+                "hop": 1,
+                "link": "2001:db8::3",
+                "options": "0x00C800080102030405060708",
+                "peer": "2001:db8::4"
+            }]
+        }
+    }
+
+
+.. note::
+    This feature is intended to be used in conjunction with an upcoming
+    LeaseQuery hook library and at this time there is other use for this
+    information within Kea.
+
+.. note::
+    It is possible that other hook libraries are already making use of
+    user-context.  Enabling store-extended-info should not interfere with
+    any other user-context content so long as it does not also use an element
+    labled "ISC".  In other words, user-context is intended to be a flexible
+    container serving mulitple purposes.  As long as no other purpose also
+    writes an "ISC" element to user-contex there should not be a conflict.
+
 .. _host-reservation-v6:
 
 Host Reservation in DHCPv6