[4518] Documentation for DHCPv6 reservations updated.

doc/examples/kea4/reservations.json

@@ -31,7 +31,7 @@
 #  "rebind-timer": 2000,
 
 
-# Kea supports several reservations by several different types of identifiers:
+# Kea supports reservations by several different types of identifiers:
 # hw-address (hardware/MAC address of the client), duid (DUID inserted by the
 # client), client-id (client identifier inserted by the client) and circuit-id
 # (circuit identifier inserted by the relay agent). When told to do so, Kea can

doc/examples/kea6/reservations.json

@@ -25,6 +25,13 @@
   "renew-timer": 1000,
   "rebind-timer": 2000,
 
+# Kea supports two types of identifiers in DHCPv6: hw-address (hardware/MAC address
+# of the client) and duid (DUID inserted by the client). When told to do so, Kea can
+# check for each of those identifier types, but it takes a costly database lookup
+# to do so. It is therefore useful from performance perspective to use only
+# that reservation types that are actually used in a given network.
+    "host-reservation-identifiers": [ "duid", "hw-address" ],
+
 # The following list defines subnets. Subnet, pools and interface definitions
 # are the same as in the regular scenario, without host reservations.
 # least subnet and pool entries.
@@ -58,13 +65,26 @@
           },
 # This is similar to the previous one, but this time the reservation is done
 # based on hardware/MAC address. The server will do its best to extract
-# the hardware/MAC address from received packets.
+# the hardware/MAC address from received packets (see 'mac-sources' directive
+# for details). This particular reservation also specifies two extra options
+# to be available for this client. If there are options with the same code
+# specified in global, subnet or class scope, the values defined at host level
+# takes precedence.
           {
               "hw-address": "00:01:02:03:04:05",
-              "ip-addresses": [ "2001:db8:1::101" ]
+              "ip-addresses": [ "2001:db8:1::101" ],
+              "option-data": [
+              {
+                  "name": "dns-servers",
+                  "data": "3000:1::234"
+              },
+              {
+                  "name": "nis-servers",
+                  "data": "3000:1::234"
+              }]
           },
-# This is a bit more advanced configuration. The client with specified
-# DUID will get a reserved address, prefix and a hostname.
+# This is a bit more advanced reservation. The client with specified
+# DUID will get a reserved address, a reserved prefix and a hostname.
           {
               "duid": "01:02:03:04:05:06:07:08:09:0A",
               "ip-addresses": [ "2001:db8:1::102" ],

doc/guide/dhcp4-srv.xml

@@ -2501,7 +2501,7 @@ It is merely echoed by the server
 
     <para>Note that the above example is used for ilustrational purposes only
     and in actual deployments it is recommended to use as few types as possible
-    (preferably just one). See <xref linkend="reservation-tuning4"/> for detailed
+    (preferably just one). See <xref linkend="reservations4-tuning"/> for detailed
     discussion.</para>
 
     <para>Making a reservation for a mobile host that may visit multiple subnets
@@ -2734,7 +2734,7 @@ It is merely echoed by the server
 
     </section>
 
-    <section id="reservation-tuning4">
+    <section id="reservations4-tuning">
       <title>Fine Tuning IPv4 Host Reservation</title>
 
       <para>Host reservation capability introduces additional restrictions for the

doc/guide/dhcp6-srv.xml

@@ -2419,21 +2419,65 @@ should include options from the isc option space:
 
     <section id="reservation6-options">
       <title>Reserving specific options</title>
-      <!-- @todo: replace this with the actual text once #3573 is implemented -->
-      <para>Currently it is not possible to specify options in host
-      reservation. Such a feature will be added in the upcoming Kea
-      releases.</para>
+
+      <para>Kea 1.1.0 introduced the ability to specify options on a
+      per host basis. The options follow the same rules as any other
+      options. These can be standard options (see <xref
+      linkend="dhcp6-std-options" />), custom options (see <xref
+      linkend="dhcp6-custom-options"/>) or vendor specific options
+      (see <xref linkend="dhcp6-vendor-opts" />). The following
+      example showcases how standard options can be defined.</para>
+
+      <screen>
+"reservations": [
+{
+    "hw-address": "aa:bb:cc:dd:ee:ff",
+    "ip-address": "192.0.2.1",
+    <userinput>"option-data": [
+    {
+        "duid": "01:02:03:05:06:07:08",
+        "ip-addresses": [ "2001:db8:1::2" ],
+        "option-data": [ {
+            "name": "dns-servers",
+            "data": "3000:1::234"
+        },
+        {
+            "name": "nis-servers",
+            "data": "3000:1::234"
+        }
+    } ]</userinput>
+} ]</screen>
+
+    <para>Vendor specific options can be reserved in similar manner:</para>
+
+    <screen>
+"reservations": [
+{
+    "duid": "aa:bb:cc:dd:ee:ff",
+    "ip-addresses": [ "2001:db8::1" ],
+    <userinput>"option-data": [
+    {
+        "name": "vendor-opts",
+        "data": 4491"
+    },
+    {
+        "name": "tftp-servers",
+        "space": "vendor-4491",
+        "data": "3000:1::234"
+    } ]</userinput>
+} ]</screen>
+
+<para>
+  Options defined on host level have the highest priority. In other words,
+ if there are option defined with the same type on global, subnet, class and
+ host level, the host specific values will be used.
+</para>
+
     </section>
 
-    <section id="reservation6-mode">
+    <section id="reservations6-tuning">
       <title>Fine Tuning IPv6 Host Reservation</title>
 
-      <note>
-        <para><command>reservation-mode</command> in the DHCPv6 server is
-        implemented in Kea 0.9.1 beta, but has not been tested and is
-        considered experimental.</para>
-      </note>
-
       <para>Host reservation capability introduces additional restrictions for the
       allocation engine during lease selection and renewal. In particular, three
       major checks are necessary. First, when selecting a new lease, it is not
@@ -2493,6 +2537,47 @@ should include options from the isc option space:
 }
 </screen>
       </para>
+
+      <para>Another aspect of the host reservations are different types of
+      identifiers. Currently (June 2016) Kea supports two types of identifiers
+      in DHCPv6: hw-address and duid, but more identifier types
+      are likely to be added in the future. This is beneficial from the
+      usability perspective. However, there is a drawback. For each incoming
+      packet Kea has to to extract each identifier type and then query the
+      database to see if there's a reservation done by this particular
+      identifier. If there is not, the next identifier is extracted and next
+      query is issued. This process continues until either a reservation is
+      found or all identifier types were checked. Over time with increasing
+      number of supported identifier types, Kea would become slower and
+      slower.</para>
+
+      <para>To address this problem, a parameter called
+      <command>host-reservation-identifiers</command> has been introduced. It
+      takes a list of identifier types as a parameter. Kea will check only those
+      identifier types enumerated in host-reservation-identifiers. From the
+      performance perspective the number of identifier types should be kept to
+      minimum, ideally limited to one. If your deployment uses several
+      reservation types, please enumerate them from most to least frequently
+      used as this increases the chances of Kea finding the reservation using
+      fewer number of queries. An example of host reservation identifiers looks
+      as follows:
+
+<screen>
+<userinput>"host-reservation-identifiers": [ "duid", "hw-address" ],</userinput>
+"subnet4": [
+    {
+        "subnet": "192.0.2.0/24",
+        ...
+    }
+]</screen>
+</para>
+
+<para>
+  If not specified, the default value is <command>hw-address,duid</command>.
+</para>
+<!-- see CfgHostOperations::createConfig6() in
+     src/lib/dhcpsrv/cfg_host_operations.cc -->
+
    </section>
 
     <!-- @todo: add support for per IA reservation (that specifies IAID in

src/lib/dhcpsrv/cfg_host_operations.cc

@@ -17,6 +17,8 @@ CfgHostOperations::CfgHostOperations()
 
 CfgHostOperationsPtr
 CfgHostOperations::createConfig4() {
+    // If this list modified, please update reservations4-tuning section in
+    // doc/guide/dhcp4-srv.xml
     CfgHostOperationsPtr cfg(new CfgHostOperations());
     cfg->addIdentifierType("hw-address");
     cfg->addIdentifierType("duid");
@@ -26,6 +28,8 @@ CfgHostOperations::createConfig4() {
 
 CfgHostOperationsPtr
 CfgHostOperations::createConfig6() {
+    // If this list modified, please update reservations6-tuning section in
+    // doc/guide/dhcp6-srv.xml
     CfgHostOperationsPtr cfg(new CfgHostOperations());
     cfg->addIdentifierType("hw-address");
     cfg->addIdentifierType("duid");