Browse Source

[master] Merge branch 'master' of ssh://git.kea.isc.org/git/kea

Francis Dupont 7 years ago
parent
commit
0e45526873
3 changed files with 75 additions and 5 deletions
  1. 7 1
      ChangeLog
  2. 1 1
      configure.ac
  3. 67 3
      doc/guide/hooks.xml

+ 7 - 1
ChangeLog

@@ -1,3 +1,9 @@
+1318.	[doc]		marcin
+	Updated Kea Administrator's Manual with the information about
+	new capability of flex-id hook library to use value derived from
+	flexible identifier as a client identifier or DUID.
+	(Trac #5384, git cce58fee4aa0476712209a7ed92fab587258b49b)
+
 1317.	[bug]		fdupont
 1317.	[bug]		fdupont
 	The kea-admin script now behaves properly when -4 or -6 is missing
 	The kea-admin script now behaves properly when -4 or -6 is missing
 	while using lease-dump command.
 	while using lease-dump command.
@@ -51,7 +57,7 @@
 	(Trac #5368, git 6842036714f84bf12529e1a43e12ac5a07e2e5c0)
 	(Trac #5368, git 6842036714f84bf12529e1a43e12ac5a07e2e5c0)
 
 
 1309.	[func]		fdupont
 1309.	[func]		fdupont
-	Kea-shell script now has an optional --path parameter that allows 
+	Kea-shell script now has an optional --path parameter that allows
         using not empty URL path.
         using not empty URL path.
 	(Trac #5361, git 9a31c417d52f1481185b0880a10a4b5f16d8462a)
 	(Trac #5361, git 9a31c417d52f1481185b0880a10a4b5f16d8462a)
 
 

+ 1 - 1
configure.ac

@@ -7,7 +7,7 @@ AC_PREREQ([2.59])
 # For GIT versions, this is x.y.z-git, where x.y.z denotes the software
 # For GIT versions, this is x.y.z-git, where x.y.z denotes the software
 # version that was used as a base + changes that were made later, but
 # version that was used as a base + changes that were made later, but
 # are not released yet.
 # are not released yet.
-AC_INIT(kea,1.2.0-git, kea-dev@lists.isc.org)
+AC_INIT(kea,1.3.0-beta-git, kea-dev@lists.isc.org)
 AC_CONFIG_SRCDIR(README)
 AC_CONFIG_SRCDIR(README)
 
 
 # serial-tests is not available in automake version before 1.13, so
 # serial-tests is not available in automake version before 1.13, so

+ 67 - 3
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
           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, DUID, circuit-id or client-id in DHCPv4 and using
           hardware address or DUID in DHCPv6. However, there are sometimes
           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
           options that mentioned above, uses part of specific options or perhaps
           even a combination of several options and fields to uniquely identify
           even a combination of several options and fields to uniquely identify
           a client. Those scenarios are addressed by the Flexible Identifiers
           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>
         <para>
           The library can be loaded in similar way as other hook libraries. It
           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>
 <screen>
 "Dhcp6": { <userinput>
 "Dhcp6": { <userinput>
     "hooks-libraries": [
     "hooks-libraries": [
         {
         {
             "library": "/path/libdhcp_flex_id.so",
             "library": "/path/libdhcp_flex_id.so",
             "parameters": {
             "parameters": {
-                "identifier-expression": "<userinput>expression</userinput>"
+                "identifier-expression": "<userinput>expression</userinput>",
+                "replace-client-id": "<userinput>false</userinput>"
             }
             }
         },
         },
         ...
         ...
@@ -818,6 +820,68 @@ Administrator deleted a lease for a device identified by: duid of 1a:1b:1c:1d:1e
     ]
     ]
 }
 }
 </screen>
 </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 is a functional equivalent of other identifiers,
+          similar to hardware address or circuit-id. However,
+          this mode of operation has an implication that if a client device is
+          replaced, it 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.
+          A manifestation of this problem is dependant on specific expression
+          used as flexible identifier and is likely to appear if you only use options
+          and other parameters that are identifying where the device is
+          connected (e.g. circuit-id), rather than the device identification
+          itself (e.g. MAC address).
+        </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.
+          "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>
+        <para>
+          If "replace-client-id" option is set to true, the value of "echo-client-id"
+          parameter (that governs whether to send back a client-id option or
+          not) is ignored.
+        </para>
+
       </section>
       </section>
 
 
       <section id="host-cmds">
       <section id="host-cmds">