[5198] Changes after review

src/bin/keactrl/kea.conf.pre

@@ -15,8 +15,8 @@
 // do. Comments in this configuration file sometimes refer to sections for more
 // details. These are section numbers in Kea User's Guide. The version matching
 // your software should come with your Kea package, but it is also available
-// on Kea webpage (http://kea.isc.org, click User's Guide, direct link for stable
-// version is http://kea.isc.org/docs/kea-guide.html).
+// on Kea web page (http://kea.isc.org, click User's Guide, direct link for
+// stable version is http://kea.isc.org/docs/kea-guide.html).
 {
 
 // DHCPv4 configuration starts here. This section will be read by DHCPv4 server
@@ -34,15 +34,15 @@
         // that don't have IPv4 address yet, are received. However, if your
         // traffic is always relayed, it is often better to use regular
         // UDP sockets. If you want to do that, uncomment this line:
-        // "dhcp-socket-type": "raw"
+        // "dhcp-socket-type": "udp"
     },
 
-    // Kea support control channel, which is a way to receive management commands
-    // while the server is running. This is a Unix domain socket that receives
-    // commands formatted in JSON, e.g. config-set (which sets new configuration),
-    // config-reload (which tells Kea to reload its configuration from file),
-    // statistic-get (to retrieve statistics) and many more. For detailed
-    // description, see Sections 8.8, 16 and 15.
+    // Kea support control channel, which is a way to receive management
+    // commands while the server is running. This is a Unix domain socket that
+    // receives commands formatted in JSON, e.g. config-set (which sets new
+    // configuration), config-reload (which tells Kea to reload its
+    // configuration from file), statistic-get (to retrieve statistics) and many
+    // more. For detailed description, see Sections 8.8, 16 and 15.
     "control-socket": {
         "socket-type": "unix",
         "socket-name": "/tmp/kea4-ctrl-socket.sock"
@@ -60,7 +60,6 @@
         "type": "memfile"
     },
 
-
     // Kea allows storing host reservations in a database. If your network is
     // small or you have few reservations, it's probably easier to keep them
     // in the configuration file. If your network is large, it's usually better
@@ -97,22 +96,24 @@
     "rebind-timer": 1800,
     "valid-lifetime": 3600,
 
-    // Similar to DHCPv4, many other parameters can be specified here:
-    // - option definitions (if you want to define vendor options, your own custom
-    //                       options or perhaps handle standard options that Kea
-    //                       does not support out of the box yet)
+    // Many additional parameters can be specified here:
+    // - option definitions (if you want to define vendor options, your own
+    //                       custom options or perhaps handle standard options
+    //                       that Kea does not support out of the box yet)
     // - client classes
     // - hooks
+    // - ddns information (how the DHCPv4 component can reach a DDNS daemon)
     //
-    // See the examples in DHCPv4 for specific syntax.
-
-    // These are global options. They are going to be sent when a client requests
-    // them, unless overwritten with values in more specific scopes. The scope
-    // hierarchy is:
-    // - global
-    // - subnet
-    // - class
-    // - host
+    // Some of them have examples below, but there are other parameters.
+    // Consult Kea User's Guide to find out about them.
+
+    // These are global options. They are going to be sent when a client
+    // requests them, unless overwritten with values in more specific scopes.
+    // The scope hierarchy is:
+    // - global (most generic, can be overwritten by class, subnet or host)
+    // - class (can be overwritten by subnet or host)
+    // - subnet (can be overwritten by host)
+    // - host (most specific, overwrites any other scopes)
     //
     // Not all of those options make sense. Please configure only those that
     // are actually useful in your network.
@@ -154,7 +155,7 @@
         },
 
         // Domain search is also a popular option. It tells the client to
-        // attempt to resolve names within those specificed domains. For
+        // attempt to resolve names within those specified domains. For
         // example, name "foo" would be attempted to be resolved as
         // foo.mydomain.example.com and if it fails, then as foo.example.com
         {
@@ -163,14 +164,14 @@
         },
 
         // String options that have a comma in their values need to have
-        // it escaped (i.e. each comma is predeced by two backslashes).
+        // it escaped (i.e. each comma is preceded by two backslashes).
         // That's because commas are reserved for separating fields in
         // compound options. At the same time, we need to be conformant
         // with JSON spec, that does not allow "\,". Therefore the
         // slightly uncommon double backslashes notation is needed.
 
         // Legal JSON escapes are \ followed by "\/bfnrt character
-        // or \u followed by 4 hexa-decimal numbers (currently Kea
+        // or \u followed by 4 hexadecimal numbers (currently Kea
         // supports only \u0000 to \u00ff code points).
         // CSV processing translates '\\' into '\' and '\,' into ','
         // only so for instance '\x' is translated into '\x'. But
@@ -196,9 +197,10 @@
         // based on rebind-timer parameter).
     ],
 
-    // Other global parameters that can be defined here are option defintions
-    // (this is useful if you want to use vendor options, your own custom options
-    // or perhaps handle options that Kea does not handle out of the box yet).
+    // Other global parameters that can be defined here are option definitions
+    // (this is useful if you want to use vendor options, your own custom
+    // options or perhaps handle options that Kea does not handle out of the box
+    // yet).
 
     // You can also define classes. If classes are defined, incoming packets
     // may be assigned to specific classes. A client class can represent any
@@ -216,7 +218,9 @@
             // This is a test. It is an expression that is being evaluated on
             // each incoming packet. It is supposed to evaluate to either
             // true or false. If it's true, the packet is added to specified
-            // class.
+            // class. See Section 12 for a list of available expressions. There
+            // are several dozens. Section 8.2.14 for more details for DHCPv4
+            // classification and Section 9.2.19 for DHCPv6.
             "test": "substring(option[60].hex,0,6) == 'Aastra'",
 
             // If a client belongs to this class, you can define extra behavior.
@@ -309,18 +313,23 @@
             // Kea also support flexible identifier (flex-id), which lets you
             // specify an expression that is evaluated for each incoming packet.
             // Resulting value is then used for as an identifier.
+            //
+            // Note that reservations are subnet-specific in Kea. This is
+            // different than ISC DHCP. Keep that in mind when migrating
+            // your configurations.
             "reservations": [
 
-                // This is a reservation for a specific hardware/MAC address. It's a
-                // rather simple reservation: just an address and nothing else.
+                // This is a reservation for a specific hardware/MAC address.
+                // It's a rather simple reservation: just an address and nothing
+                // else.
                 {
                     "hw-address": "1a:1b:1c:1d:1e:1f",
                     "ip-address": "192.0.2.201"
                 },
 
                 // This is a reservation for a specific client-id. It also shows
-                // the this client will get a reserved hostname. A hostname can be
-                // defined for any identifier type, not just client-id.
+                // the this client will get a reserved hostname. A hostname can
+                // be defined for any identifier type, not just client-id.
                 {
                     "client-id": "01:11:22:33:44:55:66",
                     "ip-address": "192.0.2.202",
@@ -336,7 +345,7 @@
                     "ip-address": "192.0.2.203",
                     "option-data": [ {
                         "name": "domain-name-servers",
-                        "data": "10.1.1.202,10.1.1.203"
+                        "data": "10.1.1.202, 10.1.1.203"
                     } ]
                 },
 
@@ -359,7 +368,7 @@
                         {
                             "name": "tftp-servers",
                             "space": "vendor-4491",
-                            "data": "10.1.1.202,10.1.1.203"
+                            "data": "10.1.1.202, 10.1.1.203"
                         }
                     ]
                 },
@@ -394,8 +403,8 @@
     ]
 
     // There are many, many more parameters that DHCPv4 server is able to use.
-    // They were not added here to not overwhelm people with too much information
-    // at once.
+    // They were not added here to not overwhelm people with too much
+    // information at once.
 },
 
 // DHCPv6 configuration starts here. This section will be read by DHCPv6 server
@@ -403,7 +412,7 @@
 "Dhcp6": {
     // Add names of your network interfaces to listen on.
     "interfaces-config": {
-        // You typcially want to put specific interface names here, e.g. eth0
+        // You typically want to put specific interface names here, e.g. eth0
         // but you can also specify unicast addresses (e.g. eth0/2001:db8::1) if
         // you want your server to handle unicast traffic in addition to
         // multicast. (DHCPv6 is a multicast based protocol).
@@ -445,7 +454,6 @@
     // },
     // See Section 8.2.3 "Hosts storage" for details.
 
-
     // Setup reclamation of the expired leases and leases affinity.
     // Expired leases will be reclaimed every 10 seconds. Every 25
     // seconds reclaimed leases, which have expired more than 3600
@@ -524,14 +532,14 @@
         },
 
         // String options that have a comma in their values need to have
-        // it escaped (i.e. each comma is predeced by two backslashes).
+        // it escaped (i.e. each comma is preceded by two backslashes).
         // That's because commas are reserved for separating fields in
         // compound options. At the same time, we need to be conformant
         // with JSON spec, that does not allow "\,". Therefore the
         // slightly uncommon double backslashes notation is needed.
 
         // Legal JSON escapes are \ followed by "\/bfnrt character
-        // or \u followed by 4 hexa-decimal numbers (currently Kea
+        // or \u followed by 4 hexadecimal numbers (currently Kea
         // supports only \u0000 to \u00ff code points).
         // CSV processing translates '\\' into '\' and '\,' into ','
         // only so for instance '\x' is translated into '\x'. But
@@ -579,6 +587,25 @@
             // host reservations defined for them.
             "pools": [ { "pool": "2001:db8:1::/80" } ],
 
+            // Kea supports prefix delegation (PD). This mechanism delegates
+            // whole prefixes, instead of single addresses. You need to specify
+            // a prefix and then size of the delegated prefixes that it will
+            // be split into. This example below tells Kea to use
+            // 2001:db8:1::/56 prefix as pool and split it into /64 prefixes.
+            // This will give you 256 (2^(64-56)) prefixes.
+            "pd-pools": [
+                {
+                    "prefix": "2001:db8:8::",
+                    "prefix-len": 56,
+                    "delegated-len": 64
+
+                    // Kea also supports excluded prefixes. This advanced option
+                    // is explained in Section 9.2.9. Please make sure your
+                    // excluded prefix matches the pool it is defined in.
+                    // "excluded-prefix": "2001:db8:8:0:80::",
+                    // "excluded-prefix-len": 72
+                }
+            ],
             "option-data": [
                 // You can specify additional options here that are subnet
                 // specific. Also, you can override global options here.
@@ -589,6 +616,10 @@
             ],
 
             // Host reservations can be defined for each subnet.
+            //
+            // Note that reservations are subnet-specific in Kea. This is
+            // different than ISC DHCP. Keep that in mind when migrating
+            // your configurations.
             "reservations": [
                 // This is a simple host reservation. The host with DUID matching
                 // the specified value will get an address of 2001:db8:1::100.
@@ -680,6 +711,15 @@
         //          "pools": [ { "pool": "2001:db8:4::/80" } ]
         //      }
     ]
+
+    // Client-clesses can be defined here. See "client-classes" in Dhcp4 for
+    // an example.
+
+    // Hook libraries can be defined here. See "hooks-libraries" example in
+    // Dhcp4.
+
+    // DDNS information (how the DHCPv6 component can reach a DDNS daemon)
+
 },
 
 // DHCP DDNS configuration starts here. This is a very simple configuration
@@ -706,7 +746,13 @@
         "name": "kea-dhcp4",
         "output_options": [
             {
-                // Specifies the output file.
+                // Specifies the output file. There are several special values
+                // supported:
+                // - stdout (prints on standard output)
+                // - stderr (prints on standard error)
+                // - syslog (logs to syslog)
+                // - syslog:name (logs to syslog using specified name)
+                // Any other value is considered a name of a time
                 "output": "@localstatedir@/log/kea-dhcp4.log"
 
                 // This governs whether the log output is flushed to disk after