[5350] Documentation updated.

doc/examples/kea4/advanced.json

@@ -80,11 +80,22 @@
     "match-client-id": true,
 
     // The following list defines subnets. Each subnet consists of at
-    // least subnet and pool entries.
+    // least subnet and pool entries. One extra feature that requires some
+    // explanation is user-context. This is a structure that you can define
+    // in subnets and pools. It is parsed by Kea, but not used directly.
+    // It is intended to keep anything you may want to put there - comments,
+    // extra designations, floor or depatment names etc. This structures
+    // will be made available to Kea hooks.
     "subnet4": [
         {
-            "pools": [ { "pool":  "192.0.2.1 - 192.0.2.200" } ],
-            "subnet": "192.0.2.0/24"
+            "pools": [ {
+                "pool":  "192.0.2.1 - 192.0.2.200",
+                "user-context": { "info": "what a large pool" }
+            } ],
+            "subnet": "192.0.2.0/24",
+            "user-context": {
+                "comment": "Our first subnet!"
+            }
         },
         {
             // This particular subnet has match-client-id value changed.

doc/examples/kea6/advanced.json

@@ -59,7 +59,6 @@
 // This entry marks options 110, 120 and 130 as RSOO-enabled.
    "relay-supplied-options": [ "110", "120", "130" ],
 
-
     // This defines a control socket. If defined, Kea will open a UNIX socket
     // and will listen for incoming commands. See section 15 of the Kea User's
     // Guide for list of supported commands.
@@ -79,11 +78,28 @@
   "renew-timer": 1000,
   "rebind-timer": 2000,
 
-// The following list defines subnets. Each subnet consists of at
-// least subnet and pool entries.
+  // The following list defines subnets. Each subnet consists of at
+  // least subnet and pool entries. Note the user-context being
+  // used throughout the definitions. This is something that is not
+  // being used by Kea, it's simply parsed and stored in appropriate
+  // structures. You can put anything you want in the user-context
+  // as long as it is a valid JSON.
   "subnet6": [
     {
-      "pools": [ { "pool": "2001:db8:1::/80" } ],
+        "pools": [
+            {
+                "pool": "2001:db8:1::/80",
+
+                // This is user context specified for this particular
+                // pool. You can use it to describe the pool in some way.
+                // Just keep in mind that the structure will not be used
+                // by Kea itself. It will be made available to hooks if
+                // they want to use it.
+                "user-context": { "department": "engineering" }
+            }],
+
+        // Here's the user-context for the whole subnet.
+        "user-context": { "comment": "Floor one, west wing" },
 
 // This defines PD (prefix delegation) pools. In this case
 // we have only one pool. That consists of /64 prefixes
@@ -95,7 +111,13 @@
           "prefix-len": 48,
           "delegated-len": 64,
           "excluded-prefix": "2001:db8:abcd:1234::",
-          "excluded-prefix-len": 62
+          "excluded-prefix-len": 62,
+
+          // Another user-context for this PD pool. Again, you can put anything
+          // you want in there as long as it's valid JSON.
+          "user-context": {
+              "purpose": "For CPE devices"
+          }
       }
       ],
       "subnet": "2001:db8:1::/64",

doc/guide/dhcp4-srv.xml

@@ -3915,7 +3915,7 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
     </section>
 
       <section>
-        <title>User context in IPv4 pools</title>
+        <title>User contexts in IPv4</title>
         <para>
           Kea allows loading hook libraries that sometimes could benefit from
           additional parameters. If such a parameter is specific to the whole
@@ -3923,11 +3923,23 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
           However, sometimes there is a need to specify parameters that are
           different for each pool.
         </para>
+
+        <para>
+          User contexts can store arbitrary data as long as it is valid JSON
+          syntax. Some hook libraries may expect specific formatting, though.
+          Please consult specific hook library documentation for details.
+        </para>
+
+        <para>
+          User contexts can be specified on either subnet or pool level. One
+          other useful usage is the ability to store comments or descriptions.
+        </para>
+
         <para>
           Let's consider an imaginary case of devices that have color LED
           lights. Depending on their location, they should glow red, blue or
           green. It would be easy to write a hook library that would send
-          specific values as maybe vendor option. However, the server has to
+          specific values as maybe a vendor option. However, the server has to
           have some way to specify that value for each pool. This need is
           addressed by user contexts. In essence, any user data can specified
           in the user context as long as it is a valid JSON map. For example,
@@ -3939,8 +3951,22 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
     "subnet4": [
         {
             "subnet": "192.0.2.0/24",
-            "pools": [ { "pool": "192.0.2.10 - 192.0.2.20" } ],
-            <userinput>"user-context": { "colour": "red" }</userinput>
+            "pools": [ {
+                "pool": "192.0.2.10 - 192.0.2.20",
+                // This is pool specific user context
+                <userinput>"user-context": { "colour": "red" }</userinput>
+            } ],
+
+            // This is a subnet specific user context. You can put whatever type
+            // of information you want as long as it is a valid JSON.
+            <userinput>"user-context": {
+                "comment": "network on the second floor",
+                "last-modified": "2017-09-04 13:32",
+                "description": "you can put here anything you like",
+                "phones": [ "x1234", "x2345" ],
+                "devices-registered": 42,
+                "billing": false
+            }</userinput>
         },
         ...
     ],
@@ -3951,11 +3977,10 @@ src/lib/dhcpsrv/cfg_host_operations.cc -->
         <para>
           It should be noted that Kea will not use that information, but will
           simply store and make it available to hook libraries. It is up to the
-        hook library to extract that information and make use of it.</para>
+          hook library to extract that information and make use of it.
+        </para>
         <para>
-          Currently only pools allow definition of user contexts, but this
-          concept is expected to be enhanced to other structures in the future.
-          For more background information, see <xref linkend="user-context"/>
+          For more background information, see <xref linkend="user-context"/>.
         </para>
     </section>
 

doc/guide/dhcp6-srv.xml

@@ -4071,7 +4071,7 @@ If not specified, the default value is:
     </section>
 
       <section>
-        <title>User context in IPv6 pools</title>
+        <title>User contexts in IPv6</title>
         <para>
           Kea allows loading hook libraries that sometimes could benefit from
           additional parameters. If such a parameter is specific to the whole
@@ -4079,6 +4079,18 @@ If not specified, the default value is:
           However, sometimes there is a need to specify parameters that are
           different for each pool.
         </para>
+
+        <para>
+          User contexts can store arbitrary data as long as it is valid JSON
+          syntax. Some hook libraries may expect specific formatting, though.
+          Please consult specific hook library documentation for details.
+        </para>
+
+        <para>
+          User contexts can be specified on either subnet or pool level. One
+          other useful usage is the ability to store comments or descriptions.
+        </para>
+
         <para>
           Let's consider an example where certain parameters are supposed
           to be delivered to clients in form of additional options,
@@ -4093,20 +4105,31 @@ If not specified, the default value is:
           parameters used by the hook library when it is loaded.
           An example configuration could look as follows:
           <screen>
-"Dhcp4": {
+"Dhcp6": {
     "subnet6": [ {
         "pd-pools": [
         {
             "prefix":  "2001:db8::",
             "prefix-len": 56,
             "delegated-len": 64,
+
+            // This is a pool specific context.
             <userinput>"user-context": {
                 "threshold-percent": 85,
                 "v4-network": "192.168.0.0/16",
                 "v4-overflow": "10.0.0.0/16"
             }</userinput>
         } ],
-        "subnet": "2001:db8::/32"
+        "subnet": "2001:db8::/32",
+
+        // This is a subnet specific context. You can put any type of
+        // information here as long as it is a valid JSON.
+        <userinput>"user-context": {
+            "comment": "Those v4-v6 migration technologies are tricky.",
+            "experimental": true,
+            "billing-department": 42,
+            "contact-points": [ "Alice", "Bob" ]
+        }</userinput>
     } ],
     ...
 }</screen>
@@ -4119,10 +4142,7 @@ If not specified, the default value is:
           and make use of it.
         </para>
         <para>
-          Currently only address and prefix pools allow definition of user
-          contexts, but this concept is expected to be enhanced to other
-          structures in the future. For more background information, see <xref
-          linkend="user-context"/>
+          For more background information, see <xref linkend="user-context"/>.
         </para>
     </section>
 

doc/guide/hooks.xml

@@ -1969,9 +1969,17 @@ If the subnet exists the response will be similar to this:
       and makes it available for the hook libraries.
       </para>
       <para>
-        As of Kea 1.2, the only structures that allow user contexts are address
-        and prefix pools, but it is expected to extend other structures with the
-        user context capability.
+        Another use case for user contexts may be storing comments and other
+        information that will be retained by Kea. Regular comments are discarded
+        when configuration is loaded, but user contexts are retained. This is
+        useful if you want your comments to survive config-set, config-get
+        operations for example.
+      </para>
+      <para>
+        As of Kea 1.3, the structures that allow user contexts are pools of all
+        types (addresses and prefixes) and subnets. These are supported in both
+        DHCPv4 and DHCPv6. It is expected that other structures will be extended
+        in the future to provide the user context capability.
       </para>
     </section>