[5384] Updated Kea User's Guide flex-id library section.

diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml
index bf2db722cf99b8f7ea6ba2657db0b30f0d12e187..7c77c39977b4737b20f5d3aef5ad41edd830a71b 100644 (file)
--- a/doc/guide/hooks.xml
+++ b/doc/guide/hooks.xml
@@ -697,7 +697,7 @@ Administrator deleted a lease for a device identified by: duid of 1a:1b:1c:1d:1e
           client classes and other features. The reservation can be based on
           hardware address, DUID, circuit-id or client-id in DHCPv4 and using
           hardware address or DUID in DHCPv6. However, there are sometimes
-          scenario where the reservation is more complex, e.g. uses other
+          scenarios where the reservation is more complex, e.g. uses other
           options that mentioned above, uses part of specific options or perhaps
           even a combination of several options and fields to uniquely identify
           a client. Those scenarios are addressed by the Flexible Identifiers
@@ -722,14 +722,16 @@ Administrator deleted a lease for a device identified by: duid of 1a:1b:1c:1d:1e
 
         <para>
           The library can be loaded in similar way as other hook libraries. It
-          takes one mandatory parameter identifier-expression:
+          takes a mandatory parameter identifier-expression and optional
+          boolean parameter replace-client-id:
 <screen>
 "Dhcp6": { <userinput>
     "hooks-libraries": [
         {
             "library": "/path/libdhcp_flex_id.so",
             "parameters": {
-                "identifier-expression": "<userinput>expression</userinput>"
+                "identifier-expression": "<userinput>expression</userinput>",
+                "replace-client-id": "<userinput>false</userinput>"
             }
         },
         ...
@@ -818,6 +820,56 @@ Administrator deleted a lease for a device identified by: duid of 1a:1b:1c:1d:1e
     ]
 }
 </screen>
+
+        <para>
+          When "replace-client-id" is set to false (which is the default setting),
+          the flex-id hook library uses evaluated flexible identifier solely for
+          identifying host reservations, i.e. searching for reservations within a
+          database. This mode of operation has an implication that replacement of
+          a client device may cause a conflict between an existing lease (allocated
+          for old device) and the new lease being allocated for the new device. The
+          conflict arises because the same flexible identifier is computed for the
+          replaced device and the server will try to allocate the same lease. The
+          mismatch between client identifiers sent by new device and old device causes
+          the server to refuse this new allocation until the old lease expires.
+        </para>
+
+        <para>
+          The flex-id library offers a way to overcome the problem with lease conflicts
+          by dynamically replacing client identifier (or DUID in DHCPv6 case) with a
+          value derived from flexible identifier. The server processes the client's
+          query as if flexible identifier was sent in the client identifier (or DUID)
+          option. This guarantees that returning client (for which the same flexible
+          identifier is evaluated) will be assigned the same lease desplite the client
+          identifier and/or MAC address change.
+        </para>
+
+        <para>
+          The following is a stub configuration that enables this behavior:
+<screen>
+"Dhcp4": { <userinput>
+    "hooks-libraries": [
+        {
+            "library": "/path/libdhcp_flex_id.so",
+            "parameters": {
+                "identifier-expression": "<userinput>expression</userinput>",
+                "replace-client-id": "<userinput>true</userinput>"
+            }
+        },
+        ...
+    ] </userinput>
+}
+</screen>
+        </para>
+
+        <para>
+          Note that for this mechanism to take effect, the DHCPv4 server must be configured
+          to respect the client identifier option value during lease allocation, i.e.
+          "dhcp4-match-client-id" must be set to true. See
+          <xref linkend="dhcp4-match-client-id"/> for details. No additional settings
+          are required for DHCPv6.
+        </para>
+
       </section>
 
       <section id="host-cmds">