From 183010b15a8497324078de0b8101b0a1627e963b Mon Sep 17 00:00:00 2001
From: Thomas Markwalder <tmark@isc.org>
Date: Fri, 10 Aug 2018 14:51:58 -0400
Subject: [PATCH] [5705] Added global HR documentation to the admin guide

	modified:   doc/guide/dhcp4-srv.xml
---
 doc/guide/dhcp4-srv.xml | 73 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 67 insertions(+), 6 deletions(-)

diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml
index 267e4ad8f5..4f29ae3a85 100644
--- a/doc/guide/dhcp4-srv.xml
+++ b/doc/guide/dhcp4-srv.xml
@@ -3462,7 +3462,7 @@ It is merely echoed by the server
     identifier, DUID and circuit-id have been added in Kea 1.1.0.</para>
 
     <para>The following example shows how to reserve addresses for specific
-    hosts:
+    hosts in a subnet:
 
 <screen>
 "subnet4": [
@@ -3541,6 +3541,20 @@ It is merely echoed by the server
       to skip reservation checks when dealing with existing leases. Therefore,
       system administrators are encouraged to use out-of-pool reservations if
       possible.</para>
+      <para>Beginning, with Kea 1.5.0, there is now support for global
+      host reservations.  These are reservations that are specified at the
+      global level within the configuration and that do not belong to any
+      specific subnet.  Kea will still match inbound client packets to a
+      subnet as before, but when the subnet's reservation mode is set to
+      <command>"global"</command>, Kea will look for host reservations only
+      among the global reservations defined. Typcially, such resrvations would
+      be used to reserve hostnames for clients which may move from one subnet
+      to another.
+      </para>
+      <note>You can reserve any ip-address in a global reservation. Just keep
+      in mind that Kea will not do any sanity checking on the address and for
+      Kea 1.5.0, support for this should be considered experimental.
+      </note>
     </section>
 
     <section xml:id="reservation4-conflict">
@@ -3884,10 +3898,10 @@ It is merely echoed by the server
       Allowed values are:
 
       <itemizedlist>
-      <listitem><simpara> <command>all</command> - enables all host reservation
-      types. This is the default value. This setting is the safest and the most
-      flexible. It allows in-pool and out-of-pool reservations. As all checks
-      are conducted, it is also the slowest.
+      <listitem><simpara> <command>all</command> - enables both in-pool
+      and out-of-pool host reservation types. This is the default value. This
+      setting is the safest and the most flexible. As all checks are conducted,
+      it is also the slowest.
       </simpara></listitem>
 
       <listitem><simpara> <command>out-of-pool</command> - allows only out of
@@ -3900,6 +3914,16 @@ It is merely echoed by the server
       <command>reservation-mode</command> and misconfiguration may cause problems.
       </simpara></listitem>
 
+      <listitem><simpara> <command>global</command> - allows only global
+      host reservations.  With this setting in place, the server searches for
+      reservations for a client only among the defined global reservations.
+      If an address is specified, the server will skip the reservation checks
+      done when dealing in other modes, thus improving performance.
+      Caution is advised when using this setting: Kea does not sanity check
+      the reservations when <command>global</command> and
+      misconfiguration may cause problems.
+      </simpara></listitem>
+
       <listitem><simpara>
       <command>disabled</command> - host reservation support is disabled. As there
       are no reservations, the server will skip all checks. Any reservations defined
@@ -3911,7 +3935,7 @@ It is merely echoed by the server
       </para>
 
       <para>
-        An example configuration that disables reservation looks like follows:
+        An example configuration that disables reservation appears as follows:
 <screen>
 "Dhcp4": {
     "subnet4": [
@@ -3923,8 +3947,45 @@ It is merely echoed by the server
     ]
 }
 </screen>
+
+
+      </para>
+      <para>
+        An example configuration using global reservations is shown below:
+<screen>
+"Dhcp4": {
+
+    <userinput>
+    "reservations": [
+       {
+        "hw-address": "01:bb:cc:dd:ee:ff",
+        "hostname": "host-one"
+       },
+       {
+        "hw-address": "02:bb:cc:dd:ee:ff",
+        "hostname": "host-two"
+       }
+    ],
+    </userinput>
+    "subnet4": [
+    {
+        "subnet": "192.0.2.0/24",
+        <userinput>"reservation-mode": "global"</userinput>,
+        ...
+    },
+    {
+        "subnet": "192.0.8.0/24",
+        <userinput>"reservation-mode": "global"</userinput>,
+        ...
+    }
+    ]
+}
+</screen>
+
+
       </para>
 
+
       <para>Another aspect of the host reservations are the different types of
       identifiers. Kea 1.1.0 supports four types of identifiers
       (hw-address, duid, client-id and circuit-id), but more identifier types
-- 
2.47.2