[4518] Changes after review:

 - added vendor options example and made it out-of-pool in
   kea6/reservations.json
 - fixed couple indents in dhcp{4,6}-srv.xml
 - added enclosing subnet4 where it was missing in examples
 - renamed section dedicated to option reservations
 - default value of host-reservation-identifiers presented
   differently

doc/examples/kea6/reservations.json

@@ -84,11 +84,25 @@
           },
 # This is a bit more advanced reservation. The client with the specified
 # DUID will get a reserved address, a reserved prefix and a hostname.
+# This reservation is for an address that it not within the dynamic pool.
+# Finally, this reservation features vendor specific options for CableLabs,
+# which happen to use enterprise-id 4491. Those particular values will
+# be returned only to the client that has a DUID matching this reservation.
           {
               "duid": "01:02:03:04:05:06:07:08:09:0A",
-              "ip-addresses": [ "2001:db8:1::102" ],
+              "ip-addresses": [ "2001:db8:1:cafe::1" ],
               "prefixes": [ "2001:db8:2:abcd::/64" ],
-              "hostname": "foo.example.com"
+              "hostname": "foo.example.com",
+              "option-data": [ {
+                  "name": "vendor-opts",
+                  "data": "4491"
+              },
+              {
+                  "name": "tftp-servers",
+                  "space": "vendor-4491",
+                  "data": "3000:1::234"
+              } ]
+
           }
       ]
     }

doc/guide/dhcp4-srv.xml

@@ -10,13 +10,11 @@
     <section id="dhcp4-start-stop">
       <title>Starting and Stopping the DHCPv4 Server</title>
 
-      <!-- @todo Rewrite this section once #3422 is done -->
-
       <para>
-      It is recommended that the Kea DHCPv4 server be started and stopped
-      using <command>keactrl</command> (described in <xref linkend="keactrl"/>).
-      However, it is also possible to run the server directly: it accepts
-      the following command-line switches:
+        It is recommended that the Kea DHCPv4 server be started and stopped
+        using <command>keactrl</command> (described in <xref linkend="keactrl"/>).
+        However, it is also possible to run the server directly: it accepts
+        the following command-line switches:
       </para>
 
       <itemizedlist>
@@ -64,25 +62,25 @@
       </itemizedlist>
 
       <para>
-            The <command>-V</command> command returns the versions of the
-            external libraries dynamically linked.
+        The <command>-V</command> command returns the versions of the
+        external libraries dynamically linked.
       </para>
 
       <para>
-            The <command>-W</command> command describes the environment used
-            to build Kea.  This command displays a copy of the
-            <filename>config.report</filename> file produced by
-            <userinput>./configure</userinput> that is embedded in the
-            executable binary.
+        The <command>-W</command> command describes the environment used
+        to build Kea.  This command displays a copy of the
+        <filename>config.report</filename> file produced by
+        <userinput>./configure</userinput> that is embedded in the
+        executable binary.
       </para>
 
       <para>
-            The <filename>config.report</filename> may also be accessed more
-            directly.  The following command may be used to extract this
-            information.  The binary <userinput>path</userinput> may be found
-            in the install directory or in the <filename>.libs</filename>
-            subdirectory in the source tree. For example
-            <filename>kea/src/bin/dhcp4/.libs/kea-dhcp4</filename>.
+        The <filename>config.report</filename> may also be accessed more
+        directly.  The following command may be used to extract this
+        information.  The binary <userinput>path</userinput> may be found
+        in the install directory or in the <filename>.libs</filename>
+        subdirectory in the source tree. For example
+        <filename>kea/src/bin/dhcp4/.libs/kea-dhcp4</filename>.
 
 <screen>
 strings <userinput>path</userinput>/kea-dhcp4 | sed -n 's/;;;; //p'
@@ -90,9 +88,9 @@ strings <userinput>path</userinput>/kea-dhcp4 | sed -n 's/;;;; //p'
       </para>
 
       <para>
-            When running in a console, the server can be shut down by
-            pressing ctrl-c. It detects the key combination and shuts
-            down gracefully.
+        When running in a console, the server can be shut down by
+        pressing ctrl-c. It detects the key combination and shuts
+        down gracefully.
       </para>
 
       <para>
@@ -2493,7 +2491,7 @@ It is merely echoed by the server
     192.0.2.204 for a client that uses a client identifier with value
     01:11:22:33:44:55:66.</para>
 
-    <para>Note that the above example is used for ilustrational purposes only
+    <para>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="reservations4-tuning"/> for detailed
     discussion.</para>
@@ -2675,7 +2673,7 @@ It is merely echoed by the server
     </section>
 
     <section id="reservation4-options">
-      <title>Reserving specific options</title>
+      <title>Including specific DHCPv4 options in reservations</title>
       <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
@@ -2685,20 +2683,24 @@ It is merely echoed by the server
       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": [
-    {
-        "name": "cookie-servers",
-        "data": "10.1.1.202,10.1.1.203"
-    },
-    {
-        "name": "log-servers",
-        "data": "10.1.1.200,10.1.1.201"
-    } ]</userinput>
-} ]</screen>
+    "subnet4": [ {
+        "reservations": [
+        {
+            "hw-address": "aa:bb:cc:dd:ee:ff",
+            "ip-address": "192.0.2.1",
+            <userinput>"option-data": [
+            {
+                "name": "cookie-servers",
+                "data": "10.1.1.202,10.1.1.203"
+            },
+            {
+                "name": "log-servers",
+                "data": "10.1.1.200,10.1.1.201"
+            } ]</userinput>
+        } ]
+    } ]
+}</screen>
 
     <para>Vendor specific options can be reserved in a similar manner:</para>
 
@@ -2852,10 +2854,17 @@ It is merely echoed by the server
 ]</screen>
 </para>
 
-<para>If not specified, the default value is: <command>hw-address, duid,
-circuit-id</command>.</para> <!-- see CfgHostOperations::createConfig4() in
+<para>If not specified, the default value is:
+
+<screen>
+<userinput>"host-reservation-identifiers": [ "hw-address", "duid", "circuit-id" ]</userinput>
+</screen>
+<!-- see CfgHostOperations::createConfig4() in
 src/lib/dhcpsrv/cfg_host_operations.cc -->
 
+</para>
+
+
 
    </section>
 

doc/guide/dhcp6-srv.xml

@@ -11,10 +11,10 @@
       <title>Starting and Stopping the DHCPv6 Server</title>
 
       <para>
-      It is recommended that the Kea DHCPv6 server be started and stopped
-      using <command>keactrl</command> (described in <xref linkend="keactrl"/>).
-      However, it is also possible to run the server directly: it accepts
-      the following command-line switches:
+        It is recommended that the Kea DHCPv6 server be started and stopped
+        using <command>keactrl</command> (described in <xref linkend="keactrl"/>).
+        However, it is also possible to run the server directly: it accepts
+        the following command-line switches:
       </para>
 
       <itemizedlist>
@@ -62,25 +62,25 @@
       </itemizedlist>
 
       <para>
-            The <command>-V</command> command returns the versions of the
-            external libraries dynamically linked.
+        The <command>-V</command> command returns the versions of the
+        external libraries dynamically linked.
       </para>
 
       <para>
-            The <command>-W</command> command describes the environment used
-            to build Kea.  This command displays a copy of the
-            <filename>config.report</filename> file produced by
-            <userinput>./configure</userinput> that is embedded in the
-            executable binary.
+        The <command>-W</command> command describes the environment used
+        to build Kea.  This command displays a copy of the
+        <filename>config.report</filename> file produced by
+        <userinput>./configure</userinput> that is embedded in the
+        executable binary.
       </para>
 
       <para>
-            The <filename>config.report</filename> may also be accessed more
-            directly.  The following command may be used to extract this
-            information.  The binary <userinput>path</userinput> may be found
-            in the install directory or in the <filename>.libs</filename>
-            subdirectory in the source tree. For example
-            <filename>kea/src/bin/dhcp6/.libs/kea-dhcp6</filename>.
+        The <filename>config.report</filename> may also be accessed more
+        directly.  The following command may be used to extract this
+        information.  The binary <userinput>path</userinput> may be found
+        in the install directory or in the <filename>.libs</filename>
+        subdirectory in the source tree. For example
+        <filename>kea/src/bin/dhcp6/.libs/kea-dhcp6</filename>.
 
 <screen>
 strings <userinput>path</userinput>/kea-dhcp6 | sed -n 's/;;;; //p'
@@ -88,9 +88,9 @@ strings <userinput>path</userinput>/kea-dhcp6 | sed -n 's/;;;; //p'
       </para>
 
       <para>
-            When running in a console, the server can be shut down by
-            pressing ctrl-c. It detects the key combination and shuts
-            down gracefully.
+        When running in a console, the server can be shut down by
+        pressing ctrl-c. It detects the key combination and shuts
+        down gracefully.
       </para>
 
       <para>
@@ -2404,7 +2404,7 @@ should include options from the isc option space:
 </section>
 
     <section id="reservation6-options">
-      <title>Reserving specific options</title>
+      <title>Including specific DHCPv6 options in reservations</title>
 
       <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
@@ -2583,7 +2583,11 @@ should include options from the isc option space:
 </para>
 
 <para>
-  If not specified, the default value is: <command>hw-address,duid</command>.
+  If not specified, the default value is:
+<screen>
+<userinput>"host-reservation-identifiers": [ "hw-address", "duid" ]</userinput>
+</screen>
+
 </para>
 <!-- see CfgHostOperations::createConfig6() in
      src/lib/dhcpsrv/cfg_host_operations.cc -->