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

diff --git a/doc/guide/dhcp4-srv.xml b/doc/guide/dhcp4-srv.xml
index f1c6f03693bf90c6f1d6e24dbf9a0db4cda96442..d7a7720e49673a5334083a236ce8c0c823f8e499 100644 (file)
--- a/doc/guide/dhcp4-srv.xml
+++ b/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
-    manually specify a unique identifier for each subnet.
+    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:

diff --git a/doc/guide/dhcp6-srv.xml b/doc/guide/dhcp6-srv.xml
index ef57889451f618b72bb780854ce150623697041a..a8a6f6be3f52486622ed1a4322b7e26eb072ef73 100644 (file)
--- a/doc/guide/dhcp6-srv.xml
+++ b/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:

diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml
index cd16c7d550e61394ee6e8a5ab54f70250ed522a4..6b9621641945afe89bef29a679d7c4281b55e22c 100644 (file)
--- a/doc/guide/hooks.xml
+++ b/doc/guide/hooks.xml
@@ -787,7 +787,7 @@ identified by circuit-id: 68:6f:77:64:79 and remote-id: 87:f6:79:77:ef
         <para>
         Example:
 <screen>
-2018-01-06 01:02:03 CET Administrator added a lease of address: 192.0.2.202 to a device with hardware address: 
+2018-01-06 01:02:03 CET Administrator added a lease of address: 192.0.2.202 to a device with hardware address:
 1a:1b:1c:1d:1e:1f for 1 days 0 hrs 0 mins 0 secs
 </screen>
         </para>
@@ -802,7 +802,7 @@ identified by circuit-id: 68:6f:77:64:79 and remote-id: 87:f6:79:77:ef
         <para>
         Example:
 <screen>
-2018-01-06 01:02:03 CET Administrator updated information on the lease of address: 192.0.2.202 to a device 
+2018-01-06 01:02:03 CET Administrator updated information on the lease of address: 192.0.2.202 to a device
 with hardware address: 1a:1b:1c:1d:1e:1f, client-id: 1234567890
 </screen>
         </para>
@@ -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
-          <command>subnet-id</command> must be specified.  This parameter is
-          mandatory, because reservations specified in the configuration file
-          are always defined within a subnet, so the subnet they belong to is
-          clear. This is not the case with reservation-add, therefore the
-          subnet-id must be specified explicitly. An example command can be as
-          simple as:
+          IPv4 reservations, see <xref linkend="host-reservation-v4"/> and
+          <xref linkend="host-reservation-v6"/>.
+          The <command>subnet-id</command> is manadatory. Use a value of zero (0) to
+          add a global reservation, or the id of the subnet to which the reservation
+          should be added.  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
-          automatically.</para>
+          future, reservation-get command will support them automatically.
+          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>