[#136,!143] Updated global-reservations.json

As a result of review. Improved header comment, indentation and some other
comments.

doc/examples/kea4/global-reservations.json

@@ -1,6 +1,11 @@
 // This is an example configuration file for the DHCPv4 server in Kea.
-// It contains one subnet and two global reservations for the clients
+// It demonstrates how global host reservations can be configured.
-// identified by the MAC addresses.
+// The global reservations are not associated with any subnet. They
+// are assigned regardless of the subnet to which the DHCP client belongs.
+// Global reservations are assigned to the DHCP clients using the
+// same host identifier types as subnet specific reservations. This file
+// contains multiple examples of host reservations using different
+// identifier types, e.g. MAC address, client identifier etc.
 { "Dhcp4":
 
 {
@@ -9,7 +14,7 @@
     "interfaces": [ "ethX" ]
   },
 
-// We need to specify the the database used to store leases. As of September
+// We need to specify the database used to store leases. As of September
 // 2016, four database backends are supported: MySQL, PostgreSQL, Cassandra, and
 // the in-memory database, Memfile.  We'll use memfile because it doesn't
 // require any prior set up.
@@ -44,10 +49,11 @@
   "host-reservation-identifiers": [ "circuit-id", "hw-address", "duid",
                                     "client-id", "flex-id" ],
 
-// This directive tells Kea that reservations are global.
+// This directive tells Kea that reservations are global. Note that this
+// can also be specified at shared network and/or subnet level.
   "reservation-mode": "global",
 
-// Define some reservations at the global scope.
+// Define several global host reservations.
   "reservations": [
 
 // This is a reservation for a specific hardware/MAC address. It's a very
@@ -73,7 +79,8 @@
 // The third reservation is based on DUID. This reservation also
 // defines special option values for this particular client. If
 // the domain-name-servers option would have been defined on a global,
-// subnet or class level, the host specific values take preference.
+// subnet or class level, the host specific values take precedence for
+// this particular DHCP client.
     {
         "duid": "01:02:03:04:05",
         "ip-address": "192.0.2.203",
@@ -127,6 +134,7 @@
         "ip-address": "192.0.2.206"
     }
   ],
+
   // Define a subnet.
   "subnet4": [
     {

doc/examples/kea6/global-reservations.json

@@ -1,8 +1,11 @@
-// This is an example configuration file for DHCPv6 server in Kea
+// This is an example configuration file for the DHCPv6 server in Kea.
-// that showcases how to do globalhost reservations. It is
+// It demonstrates how global host reservations can be configured.
-// assumed that one subnet (2001:db8:1::/64) is available directly
+// The global reservations are not associated with any subnet. They
-// over ethX interface.
+// are assigned regardless of the subnet to which the DHCP client belongs.
-
+// Global reservations are assigned to the DHCP clients using the
+// same host identifier types as subnet specific reservations. This file
+// contains multiple examples of host reservations using different
+// identifier types, e.g. DUID, MAC address etc.
 { "Dhcp6":
 
 {
@@ -11,7 +14,7 @@
     "interfaces": [ "ethX" ]
   },
 
-// We need to specify the the database used to store leases. As of
+// We need to specify the database used to store leases. As of
 // September 2016, four database backends are supported: MySQL,
 // PostgreSQL, Cassandra, and the in-memory database, Memfile.
 // We'll use memfile  because it doesn't require any prior set up.
@@ -35,10 +38,11 @@
 // given network.
     "host-reservation-identifiers": [ "duid", "hw-address", "flex-id" ],
 
-// This directive tells Kea that reservations are global.
+// This directive tells Kea that reservations are global. Note that this
+// can also be specified at shared network and/or subnet level.
     "reservation-mode": "global",
 
-// Host reservations. Define several reservations.
+// Define several global host reservations.
     "reservations": [
 
 // This is a simple host reservation. The host with DUID matching
@@ -58,7 +62,8 @@
 // 'mac-sources' directive for details). This particular reservation
 // also specifies two extra options to be available for this client. If
 // there are options with the same code specified in a global, subnet or
-// class scope, the values defined at host level take precedence.
+// class scope, the values defined at host level take precedence for
+// this particular DHCP client.
       {
           "hw-address": "00:01:02:03:04:05",
           "ip-addresses": [ "2001:db8:1::101" ],
@@ -70,7 +75,8 @@
               {
                   "name": "nis-servers",
                   "data": "3000:1::234"
-            }],
+              }
+          ],
           "client-classes": [ "special_snowflake", "office" ]
       },
 
@@ -85,7 +91,8 @@
           "ip-addresses": [ "2001:db8:1:cafe::1" ],
           "prefixes": [ "2001:db8:2:abcd::/64" ],
           "hostname": "foo.example.com",
-            "option-data": [ {
+          "option-data": [
+              {
                   "name": "vendor-opts",
                   "data": "4491"
               },
@@ -93,7 +100,8 @@
                   "name": "tftp-servers",
                   "space": "vendor-4491",
                   "data": "3000:1::234"
-            } ]
+              }
+          ]
       },
 
 // This reservation is using flexible identifier. Instead of relying