[#14,!14] Admin guide updates regarding global HRs and subnet IDs

doc/guide/dhcp4-srv.xml

@@ -986,9 +986,11 @@ temporarily override a list of interface names and listen on all interfaces.
     subnet 4, something that may have unexpected consequences. It is planned
     to implement a mechanism to preserve auto-generated subnet ids in a
     future version of Kea.  However, the only remedy for this issue
-    at present is to
+    at present is to manually specify a unique identifier for each subnet.
-    manually specify a unique identifier for each subnet.
   </para>
+  <note>
+    Subnet IDs must be greater than zero and less than 4294967295.
+  </note>
       <para>
         The following configuration will assign the specified subnet
         identifier to the newly configured subnet:

doc/guide/dhcp6-srv.xml

@@ -759,6 +759,9 @@ temporarily override a list of interface names and listen on all interfaces.
         at present is to
         manually specify a unique identifier for each subnet.
       </para>
+      <note>
+        Subnet IDs must be greater than zero and less than 4294967295.
+      </note>
       <para>
         The following configuration will assign the specified subnet
         identifier to the newly configured subnet:

doc/guide/hooks.xml

@@ -1412,6 +1412,24 @@ Requirements </link> document.</para>
 </screen>
         </para>
 
+        <section>
+          <title>The subnet-id parameter</title>
+        <para> Prior to diving into the individual commands, it is worth
+        discussing the parameter, <command>subnet-id</command>. Currently
+        it is mandatory for all of the commands supplied by this library.
+        Prior to Kea 1.5.0, reservations had to belong to specific subnet.
+        Beginning with Kea 1.5.0, reservations may now be specified globally.
+        In other words, they are not specific to any subnet.  When reservations
+        are supplied via the configuration file, the ID of the containing
+        subnet (or lack thereof) is implicit in the configuration structure.
+        In order to manage reservations in a data store however, it is
+        necessary to identify the scope to which the reservation belongs,
+        along with any other host command parameters.  For global reservations,
+        use a value of zero (0) for <command>subnet-id</command>.  For subnet
+        level reservations, use the ID of the owning subnet.
+        </para>
+        </section>
+
         <section>
           <title>reservation-add command</title>
         <para>
@@ -1419,13 +1437,11 @@ Requirements </link> document.</para>
           takes a set of arguments that vary depending on the nature of the host
           reservation. Any parameters allowed in the configuration file that
           pertain to host reservation are permitted here. For details regarding
-          IPv4 reservations, see <xref linkend="host-reservation-v4"/> and <xref linkend="host-reservation-v6"/>. There is one notable addition. A
+          IPv4 reservations, see <xref linkend="host-reservation-v4"/> and
-          <command>subnet-id</command> must be specified.  This parameter is
+          <xref linkend="host-reservation-v6"/>.
-          mandatory, because reservations specified in the configuration file
+          The <command>subnet-id</command> is manadatory. Use a value of zero (0) to
-          are always defined within a subnet, so the subnet they belong to is
+          add a global reservation, or the id of the subnet to which the reservation
-          clear. This is not the case with reservation-add, therefore the
+          should be added.  An example command can be as simple as:
-          subnet-id must be specified explicitly. An example command can be as
-          simple as:
 <screen>{
     "command": "reservation-add",
     "arguments": {
@@ -1520,8 +1536,11 @@ Here is an example of complex IPv6 reservation:
           identifier. Currently supported identifiers are "hw-address", "duid",
           "circuit-id", "client-id" and "flex-id", but additional types may be
           added in the future. If any new identifier types are defined in the
-          future, reservation-get command will support them
+          future, reservation-get command will support them automatically.
-          automatically.</para>
+          The <command>subnet-id</command> is manadatory. Use a value of zero (0) to
+          fetch a global reservation, or the id of the subnet to which the reservation
+          belongs.
+          </para>
 
           <para>
             An example command for getting a host reservation by (subnet-id,
@@ -1596,7 +1615,11 @@ An example result returned when the query was malformed:<screen>
           "hw-address", "duid", "circuit-id", "client-id" and "flex-id", but
           additional types may be added in the future. If any new identifier
           types are defined in the future, reservation-get command will support
-          them automatically.</para>
+          them automatically.
+          The <command>subnet-id</command> is manadatory. Use a value of zero (0) to
+          delete a global reservation, or the id of the subnet from which the reservation
+          should be deleted.
+          </para>
 
           <para>
             An example command for deleting a host reservation by (subnet-id,
@@ -2052,6 +2075,9 @@ If the subnet exists the response will be similar to this:
           used). You can mix those two approaches only if you
           understand how the internal automatic subnet-id generation works.
         </para>
+        <note>
+          Subnet IDs must be greater than zero and less than 4294967295.
+        </note>
 
       </section>