[3575] Reservations section added for DHCPv6

doc/Makefile.am

@@ -10,6 +10,7 @@ nobase_dist_doc_DATA += examples/kea6/simple.json
 nobase_dist_doc_DATA += examples/kea6/several-subnets.json
 nobase_dist_doc_DATA += examples/kea6/multiple-options.json
 nobase_dist_doc_DATA += examples/kea6/advanced.json
+nobase_dist_doc_DATA += examples/kea6/reservations.json
 nobase_dist_doc_DATA += examples/ddns/sample1.json
 nobase_dist_doc_DATA += examples/ddns/template.json
 

doc/examples/kea6/reservations.json

@@ -0,0 +1,94 @@
+# This is an example configuration file for DHCPv6 server in Kea
+# that showcases how to do host reservations. It is
+# assumed that one subnet (2001:db8:1::/64) is available directly
+# over ethX interface. A number of hosts have various combinations
+# of addresses and prefixes reserved for them.
+
+{ "Dhcp6":
+
+{
+# Kea is told to listen on ethX interface only.
+  "interfaces": [ "ethX" ],
+
+# We need to specify lease type. As of May 2014, three backends are supported:
+# memfile, mysql and pgsql. We'll just use memfile, because it doesn't require
+# any prior set up.
+  "lease-database": {
+    "type": "memfile"
+  },
+
+# This is pretty basic stuff, it has nothing to do with reservations.
+  "preferred-lifetime": 3000,
+  "valid-lifetime": 4000,
+  "renew-timer": 1000,
+  "rebind-timer": 2000,
+
+# 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.
+  "subnet6": [
+    {
+      "subnet": "2001:db8:1::/48",
+
+      "pools": [ { "pool": "2001:db8:1::/80" } ],
+
+      "pd-pools": [
+          {
+              "prefix": "2001:db8:1:8000::",
+              "prefix-len": 56,
+              "delegated-len": 64
+          }
+      ],
+      "interface": "ethX",
+
+# Host reservations. Define two reservations for the 192.0.2.202 and
+# 192.0.2.100 address. Note that the latter is a reservation for the
+# address which is within the range of the pool of the dynamically
+# allocated address. The server will exclude this address from this
+# pool and only assign it to the client which has a reservation for
+# it.
+      "reservations": [
+# This is a simple host reservation. The host with DUID matching
+# specified value will get 2001:db8:1::100 address.
+          {
+              "duid": "01:02:03:04:05:0A:0B:0C:0D:0E",
+              "ip-addresses": [ "2001:db8:1::100" ]
+          },
+# 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.
+          {
+              "hw-address": "00:01:02:03:04:05",
+              "ip-addresses": [ "2001:db8:1::101" ]
+          },
+# This is a bit more advanced configuration. The client with specified
+# DUID will get a reserved address, prefix and a hostname.
+          {
+              "duid": "01:02:03:04:05:06:07:08:09:0A",
+              "ip-addresses": [ "2001:db8:1::102" ],
+              "prefixes": [ "2001:db8:2:abcd::/64" ],
+              "hostname": "foo.example.com"
+          }
+      ]
+    }
+  ]
+},
+
+# The following configures logging. Kea will log all debug messages
+# to /var/log/kea-debug.log file.
+"Logging": {
+    "loggers": [
+        {
+            "name": "kea-dhcp6",
+            "output_options": [
+                {
+                    "output": "/var/log/kea-debug.log"
+                }
+            ],
+            "debuglevel": 99,
+            "severity": "DEBUG"
+        }
+    ]
+}
+
+}

doc/guide/dhcp4-srv.xml

@@ -1746,12 +1746,13 @@ temporarily override a list of interface names and listen on all interfaces.
 
     <para>Hosts are defined as parameters for each subnet. Each host has to be
     identified by its hardware/MAC address. There is an optional
-    <command>reservation</command> array. Each element in that array is a
-    structure, that holds information about a single host. In particular, such
-    a structure has to have an indentifer that uniquely identifies a host.
-    In DHCPv4 context, such an identifier is a hardware or MAC address.
-    In most cases, also an address will be specified. It is possible to specify
-    a hostname. Additional capabilities are planed.</para>
+    <command>reservations</command> array in the <command>Subnet4</command>
+    element. Each element in that array is a structure, that holds information
+    about a single host. In particular, such a structure has to have an
+    indentifer that uniquely identifies a host.  In DHCPv4 context, such an
+    identifier is a hardware or MAC address.  In most cases, also an address
+    will be specified. It is possible to specify a hostname. Additional
+    capabilities are planed.</para>
 
     <para>The following example shows how to reserve addresses for specific
     hosts:
@@ -1765,17 +1766,22 @@ temporarily override a list of interface names and listen on all interfaces.
         <userinput>"reservations": [
             {
                 "hw-address": "1a:1b:1c:1d:1e:1f",
-                "ip-address": "192.0.2.202",
-                "hostname": "alice-laptop"
+                "ip-address": "192.0.2.202"
             },
             {
                 "hw-address": "0a:0b:0c:0d:0e:0f",
-                "ip-address": "192.0.2.100"
+                "ip-address": "192.0.2.100",
+                "hostname": "alice-laptop"
             }
         ]</userinput>
     }
 ]
 </screen>
+    The first entry reserves the 192.0.2.202 address for the client that uses
+    MAC adress of 1a:1b:1c:1d:1e:1f. The second entry reserves the address
+    192.0.2.100 address and a hostname of alice-laptop for client with MAC
+    address 0a:0b:0c:0d:0e:0f. Note that if you plan to do DNS updates, it
+    is strongly recommended for the hostnames to be unique.
     </para>
 
     <para>Making a reservation for a mobile host that may visit multiple subnets
@@ -1802,13 +1808,13 @@ temporarily override a list of interface names and listen on all interfaces.
       by the DHCPv4 server. That dynamic part is referred to as a dynamic pool or
       simply a pool. In principle the host reservation can reserve any address
       that belongs to the subnet. The reservations that specify an address that
-      belong to configure pools are called <command>in-pool reservations</command>.
+      belong to configured pools are called <command>in-pool reservations</command>.
       In contract, those that do not belong to dynamic pools are called
-      <command>out-of-pool reservations</command>. This is no formal difference
+      <command>out-of-pool reservations</command>. There is no formal difference
       in the reservation syntax. As of 0.9.1, both reservation types are
       handled uniformly. However, upcoming releases may offer improved performance
       if there are only out-of-pool reservations as the server will be able
-      to skip reservation checks when dealing with existing leases. Therefore
+      to skip reservation checks when dealing with existing leases. Therefore,
       system administrators are encouraged to use out-of-pool reservations, if
       possible.</para>
     </section>
@@ -1825,13 +1831,14 @@ temporarily override a list of interface names and listen on all interfaces.
       cases where such an operation is warranted.</para>
 
       <para>The server now has a conflict to resolve. Let's analyze the
-      situation here. If host B boots up and request an address, the server
-      is not able to assign the requested address 192.0.2.10. A naive approach
-      would to be immediately remove the lease for host A and create a new
-      one for host B. That would not solve the problem, though, because as soon
-      as host B get the address, it will detect that the address is already in use
-      by someone else (host A) and would send Decline. Therefore in this situation,
-      the server has to temporarily assign a different address to host B.</para>
+      situation here. If host B boots up and request an address, the server is
+      not able to assign the reserved address 192.0.2.10. A naive approach would
+      to be immediately remove the lease for host A and create a new one for
+      host B. That would not solve the problem, though, because as soon as host
+      B get the address, it will detect that the address is already in use by
+      someone else (host A) and would send Decline. Therefore in this situation,
+      the server has to temporarily assign a different address (not matching
+      what has been reserved) to host B.</para>
 
       <para>When the host A renews its address, the server will discover that
       the address being renewed is now reserved for someone else (host

doc/guide/dhcp6-srv.xml

@@ -1712,6 +1712,188 @@ should include options from the isc option space:
 
    </section>
 
+  <!-- Host reservation is a large topic. There will be many subsections,
+   so it should be a section on its own. -->
+  <section id="host-reservation-v6">
+    <title>Host reservation in DHCPv6</title>
+
+    <para>There are many cases where it is useful to provide a configuration on
+    a per host basis. The most obvious one is to reserve specific, static IPv6
+    address or prefix for exclusive use by a given client &dash; returning
+    client will get the same address or prefix every time and other clients will
+    never get that address. Other example may be a host that has specific
+    requirements, e.g. a printer that needs additional options or a cable modem
+    need specific parameter. Yes another possible use case for host reservation
+    is to define unique host names for hosts.  Although not all of those
+    scenarios are possible yet, Kea software will support them in the near
+    future.</para>
+
+    <para>Hosts are defined as parameters for each subnet. Each host can be
+    identified by either DUID or its hardware/MAC address. See <xref
+    linkend="mac-in-dhcpv6"/> for details. There is an optional
+    <command>reservations</command> array in the <command>Subnet6</command>
+    structure. Each element in that array is a structure, that holds information
+    about a single host. In particular, such a structure has to have an
+    indentifer that uniquely identifies a host.  In DHCPv4 context, such an
+    identifier is a hardware or MAC address.  In most cases, also an address
+    will be specified. It is possible to specify a hostname. Additional
+    capabilities are planed.</para>
+
+    <para>The following example shows how to reserve addresses and prefixes
+    for specific hosts:
+
+<screen>
+"subnet6": [
+    {
+        "subnet": "2001:db8:1::/48",
+        "pools": [ { "pool": "2001:db8:1::/80" } ],
+        "pd-pools": [
+            {
+                "prefix": "2001:db8:1:8000::",
+                "prefix-len": 56,
+                "delegated-len": 64
+            }
+        ],
+        <userinput>"reservations": [
+            {
+                "duid": "01:02:03:04:05:0A:0B:0C:0D:0E",
+                "ip-addresses": [ "2001:db8:1::100" ]
+            },
+            {
+                "hw-address": "00:01:02:03:04:05",
+                "ip-addresses": [ "2001:db8:1::101" ]
+            },
+            {
+                "duid": "01:02:03:04:05:06:07:08:09:0A",
+                "ip-addresses": [ "2001:db8:1::102" ],
+                "prefixes": [ "2001:db8:2:abcd::/64" ],
+                "hostname": "foo.example.com"
+            }
+        ]</userinput>
+    }
+]
+</screen>
+    This example makes 3 reservations. The first one reserves 2001:db8:1::100 address
+    for the client using DUID 01:02:03:04:05:0A:0B:0C:0D:0E. The second one
+    also reserves an address, but does so using MAC or hardware address, rather than
+    DUID. The third example is most advanced. It reserves an address, a prefix and
+    a hostname at the same time.
+    </para>
+
+    <para>Note that DHCPv6 allows for a single client to lease multiple addresses
+    and multiple prefixes at the same time. In the upcoming Kea releases, it will
+    be possible to have multiple addresses and prefixes reserved for a single
+    host. Therefore <command>ip-addresses"</command> and <command>prefixes</command>
+    are plural and are actually arrays. As of 0.9.1 having more than one IPv6
+    address or prefix is only partially supported.</para>
+
+    <para>Making a reservation for a mobile host that may visit multiple subnets
+    requires a separate host definition in each subnet it is expected to visit.
+    It is not allowed to define multiple host definitions with the same hardware
+    address in a single subnet. It is a valid configuration, if such definitions
+    are specified in different subnets, though.
+    </para>
+
+    <para>Adding host reservation incurs a performance penalty. In principle,
+    when the server that does not support host reservation responds to a query,
+    it needs to check whether there is a lease for a given address being
+    considered for allocation or renewal. The server that also supports host
+    reservation, has to perform additional checks: not only if the address is
+    currently used (if there is a lease for it), but also whether the address
+    could be used by someone else (if there is a reservation for it). That
+    additional check incurs performance penalty.</para>
+
+    <section id="reservation6-types">
+      <title>Address/prefix reservation types</title>
+
+      <para>In a typical scenario there's an IPv6 subnet defined with a certain
+      part of it dedicated for dynamic address allocation by the DHCPv6
+      server. There may be an additional address space defined for prefix
+      delegation. Those dynamic parts is referred to as dynamic pools, address
+      and prefix pools or simply pools. In principle the host reservation can
+      reserve any address or prefix that belongs to the subnet. The reservations
+      that specify an address that belong to configured pools are called
+      <command>in-pool reservations</command>.  In contract, those that do not
+      belong to dynamic pools are called <command>out-of-pool
+      reservations</command>. There is no formal difference in the reservation
+      syntax. As of 0.9.1, both reservation types are handled
+      uniformly. However, upcoming releases may offer improved performance if
+      there are only out-of-pool reservations as the server will be able to skip
+      reservation checks when dealing with existing leases. Therefore, system
+      administrators are encouraged to use out-of-pool reservations, if
+      possible.</para>
+    </section>
+
+    <section it="reservation6-conflict">
+      <title>Conflicts in DHCPv6 reservations</title>
+      <para>As reservations and lease information are kept in different places,
+      conflict may arrise. Consider the following series of events. The server
+      has configured 2001:db8::10  to 2001:db8::20 dynamic pool range. Host A
+      requests an address and gets 2001:db8::10. Now the system administrator
+      decides to reserve an address for host B. He decides to reserve 2001:db8::10
+      for that purpose. In general, reserving an address that is currently
+      assigned to someone else is not recommended, but there are valid use
+      cases where such an operation is warranted.</para>
+
+      <para>The server now has a conflict to resolve. Let's analyze the
+      situation here. If host B boots up and request an address, the server is
+      not able to assign the reserved address 2001:db8::10. A naive approach
+      would to be immediately remove the lease for host A and create a new one
+      for host B. That would not solve the problem, though, because as soon as
+      host B get the address, it will detect that the address is already in use
+      by someone else (host A) and would send Decline. Therefore in this
+      situation, the server has to temporarily assign a different address (not
+      matching what has been reserved) to host B.</para>
+
+      <para>When the host A renews its address, the server will discover that
+      the address being renewed is now reserved for someone else (host
+      B). Therefore the server will remove the lease for 2001:db8::10 and select
+      a new address and will create a new lease for it. It will send two
+      addresses in its response: the old address with lifetimes set to 0 to
+      explicitly indicate that it is no longer valid and a new address with
+      non-zero lifetimes.When the host B renews its temporarily assigned
+      address, the server will detect that the existing lease does not match
+      reservation, so it will release the current address host B has and will
+      create a new lease matching the reservation. Similar as before, the server
+      will send two addresses: the temporary one with zeroed lifetimes and the
+      new one that matches reservation with proper lifetimes set.</para>
+
+      <para>This recovery will succeed, even if other hosts will attempt to get
+      the reserved address. Had the host C requested address 2001:db8::10 after
+      the reservation was made, the server will propose a different address.</para>
+
+      <para>This recovery mechanism allows the server to fully recover from a
+      case where reservations conflict with existing leases. This procedure
+      takes time and will roughly take as long as renew-timer value specified.
+      The best way to avoid such recovery is to not define new reservations that
+      conflict with existing leases. Another recommendation is to use
+      out-of-pool reservations. If the reserved address does not belong to a
+      pool, there is no way that other clients could get this address (note that
+      having multiple reservations for the same address is not allowed).
+      </para>
+    </section>
+
+    <section id="reservation6-hostname">
+      <title>Reserving a hostname</title>
+      <!-- @todo: replace this with the actual text once #3689 is implemented -->
+      <para>Reserving a hostname is currently not supported. It is possible
+      to specify that information in the configuration file, but that data
+      is not used by the server engine yet.</para>
+    </section>
+
+    <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>
+    </section>
+
+    <!-- @todo: add support for per IA reservation (that specifies IAID in
+                the ip-addresses and prefixes) -->
+  </section>
+  <!-- end of host reservations section -->
+
     <section id="dhcp6-serverid">
       <title>Server Identifier in DHCPv6</title>
       <para>The DHCPv6 protocol uses a "server identifier" (also known