[5132] Flex-id described

diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml
index 79b9bb629f68e512c3bf04202c542808c9d949be..4ae200b0cb8009acf9a3464a2dd98c1468d9b148 100644 (file)
--- a/doc/guide/hooks.xml
+++ b/doc/guide/hooks.xml
@@ -216,9 +216,9 @@
               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 Identifier
+              client. Those scenarios are addressed by the Flexible Identifiers
               hook application. It allows defining an expression, similar to
-              the one used in client classiciation,
+              the one used in client classifiation,
              e.g. substring(relay6[0].option[37],0,6). Each incoming packet is
              evaluated against that expression and its value is then searched
              in the reservations database.
@@ -550,7 +550,107 @@ link address: 3001::1, hop count: 1, identified by remote-id:
       <section>
         <title>flex_id: Flexible Identifiers for Host Reservations</title>
         <para>
-          This section describes ... TODO.
+          This section describes a hook application dedicated to generate
+          flexible identifiers for host reservation. Kea software provides a way
+          to handle host reservations that include addresses, prefixes, options,
+          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
+          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
+          hook application.</para>
+
+       <para>The library allows defining an expression, using notation
+       initially used for client classification only. See <xref
+       linkend="classification-using-expressions" /> for detailed description
+       of the syntax available. One notable difference is that for client
+       classification the expression currently has to evaluate to either true
+       or false, while the flexible identifier expression is expected to
+       evaluate to a string that will be used as identifier. It is a valid case
+       for the expression to evaluate to empty string (e.g. in cases where a
+       client does not sent specific options). This expression is then
+       evaluated for each incoming packet. This evaluation generates an
+       identifier that is used to identify the client. In particular, there may
+       be host reservations that are tied to specific values of the flexible
+       identifier.</para>
+
+       <para>
+         The library can be loaded in similar way as other hook libraries. It
+         takes one mandatory parameter identifier-expression:
+<screen>
+"Dhcp6": { <userinput>
+    "hooks-libraries": [
+        {
+            "library": "/path/libdhcp_flex_id.so",
+            "parameters": {
+                "identifier-expression": "<userinput>expression</userinput>"
+            }
+        },
+        ...
+    ] </userinput>
+}
+</screen>
+       </para>
+
+       <para>
+         The flexible identifier library supports both DHCPv4 and DHCPv6.
+       </para>
+
+       <para>
+         EXAMPLE: Let's consider a case of an IPv6 network that has an
+         independent interface for each of the connected customers. Customers
+         are able to plug in whatever device they want, so any type of
+         identifier (e.g. a client-id) is unreliable. Therefore the operator
+         may decide to use an option inserted by a relay agent to differentiate
+         between clients. In this particular deployment, the operator verified
+         that the interface-id is unique for each customer facing
+         interface. Therefore it is suitable for usage as reservation. However,
+         only the first 6 bytes of the interface-id are interesting, because
+         remaining bytes are either randomly changed or not unique between
+         devices. Therefore the customer decided to use first 6 bytes of the
+         interface-id option inserted by the relay agent. This could be
+         achieved by using the following configuration:
+<screen>
+"Dhcp6": {
+    "subnet6": [{ ..., // subnet definition starts here
+    "reservations": [
+        <userinput>"flex-id": "'port1234'"</userinput>, // value of the first 8 bytes of the interface-id
+        "ip-addresses": [ "2001:db8::1" ]
+    ],
+    }], // end of subnet definitions
+    "hooks-libraries": [
+        {
+            "library": "/path/libdhcp_flex_id.so",
+            "parameters": {
+                "identifier-expression": "<userinput>substring(relay6[0].option[18],0,8)</userinput>"
+            }
+        },
+        ...
+    ]
+}
+</screen>
+       </para>
+
+       <para>
+         NOTE: Care should be taken when adjusting the expression. If the
+         expression changes, then all the flex-id values may change, possibly
+         rendering all reservations based on flex-id unusable until they're
+         manually updated. Therefore it is strongly recommended to start with
+         the expression and a handful reservations, adjust the expression as
+         needed and only after it was confirmed the expression does exactly
+         what is expected out of it go forward with host reservations on any
+         broader scale.
+       </para>
+
+       <para>
+         flex-id values in host reservations can be specified in two
+         ways. First, they can be expressed as hex string, e.g. bar string
+         can be represented as 626174. Alternatively, it can be expressed
+         as quoted value (using double and single quotes), e.g. "'bar'".
+         The former is more convenient for printable characters, while hex
+         string values are more convenient for non-printable characters.
        </para>
       </section>