[#153,!82] Changes after review:

- logging messages updated
 - existing simple-dhcp4.json tweaked, commented
 - added new simple4.xml example

doc/examples/netconf/simple-dhcp4.json

@@ -28,8 +28,21 @@
 
                 // The three control flags can be defined in this scope too
                 // and takes precedence over global and default values.
-                "boot-update": false,
+                // boot-update determines whether the initial configuration
-                "subscribe-changes": false,
+                // should be retrieved from netconf during kea-netconf startup.
+                // You almost always want to set this to yes.
+                "boot-update": true,
+
+                // This flag control whether the kea-netconf daemon should
+                // subscribe to any changes. If set to true, kea-netconf will
+                // monitor sysrepo and will pick up any changes that may be
+                // introduced, either using netconf clients or sysrepocfg.
+                "subscribe-changes": true,
+
+                // This parameters specifies whether kea-netconf will attempt
+                // to verify if the upcoming NETCONF configuration is sane. The
+                // verification is done by calling config-test. Depending on
+                // Kea response, the new configuration is accepted or rejected.
                 "validate-changes": false,
 
                 // Currently three control channel types are supported:
@@ -51,24 +64,27 @@
                 "comment": "Kea DHCP4 server serving network on floor 13"
             }
 
-        },
+        }
 
         // Netconf is able to load hook libraries that augment its operation.
         // The primary functionality is the ability to add new commands.
-        "hooks-libraries": [
+        //
-            // Hook libraries list may contain more than one library.
+        // Uncomment this section to load a hook library.
-            {
+        //
-                // The only necessary parameter is the library filename.
+        // "hooks-libraries": [
-                "library": "/opt/local/netconf-commands.so",
+        //    // Hook libraries list may contain more than one library.
-
+        //    {
-                // Some libraries may support parameters. Make sure you
+        //        // The only necessary parameter is the library filename.
-                // type this section carefully, as the CA does not validate
+        //        "library": "/opt/local/netconf-commands.so",
-                // it (because the format is library specific).
+        //
-                "parameters": {
+        //        // Some libraries may support parameters. Make sure you
-                    "param1": "foo"
+        //        // type this section carefully, as the CA does not validate
-                }
+        //        // it (because the format is library specific).
-            }
+        //        "parameters": {
-        ]
+        //            "param1": "foo"
+        //        }
+        //    }
+        //]
 
     },
 
@@ -80,7 +96,8 @@
                 "name": "kea-netconf",
                 "output_options": [
                     {
-                        "output": "/var/log/kea-netconf.log",
+                        //"output": "/var/log/kea-netconf.log",
+                        "output": "stdout",
                         // Several additional parameters are possible in addition
                         // to the typical output. Flush determines whether logger
                         // flushes output to a file. Maxsize determines maximum
@@ -92,6 +109,10 @@
                         "maxver": 4
                     }
                 ],
+                // You can change the severity to DEBUG, INFO, WARN, ERROR or
+                // CRIT. For DEBUG level, you can also additionally specify
+                // debuglevel (0-99, higher = more verbose). All configurations
+                // are logged on DEBUG/55.
                 "severity": "INFO",
                 "debuglevel": 0
             }

src/bin/netconf/configs/simple4.xml

@@ -0,0 +1,21 @@
+<config xmlns="urn:ietf:params:xml:ns:yang:kea-dhcp4-server">
+  <subnet4>
+    <subnet4>
+      <id>1</id>
+      <pools>
+        <pool>
+          <start-address>192.0.2.100</start-address>
+          <end-address>192.0.2.200</end-address>
+        </pool>
+      </pools>
+      <subnet>192.0.2.0/24</subnet>
+    </subnet4>
+  </subnet4>
+  <interfaces-config>
+    <interfaces>eth1</interfaces>
+  </interfaces-config>
+  <control-socket>
+    <socket-name>/tmp/kea4-ctrl-socket</socket-name>
+    <socket-type>unix</socket-type>
+  </control-socket>
+</config>

src/bin/netconf/netconf.cc

@@ -185,7 +185,7 @@ NetconfAgent::keaConfig(const CfgServersMapPair& service_pair) {
         config = parseAnswer(rcode, answer);
     } catch (const std::exception& ex) {
         ostringstream msg;
-        msg << "configGet failed with " << ex.what();
+        msg << "config-get command failed with " << ex.what();
         LOG_ERROR(netconf_logger, NETCONF_GET_CONFIG_FAILED)
             .arg(service_pair.first)
             .arg(msg.str());
@@ -196,7 +196,7 @@ NetconfAgent::keaConfig(const CfgServersMapPair& service_pair) {
     }
     if (rcode != CONTROL_RESULT_SUCCESS) {
         ostringstream msg;
-        msg << "configGet returned " << answerToText(answer);
+        msg << "config-get command returned " << answerToText(answer);
         LOG_ERROR(netconf_logger, NETCONF_GET_CONFIG_FAILED)
             .arg(service_pair.first)
             .arg(msg.str());
@@ -208,6 +208,9 @@ NetconfAgent::keaConfig(const CfgServersMapPair& service_pair) {
             .arg("configGet returned an empty configuration");
         return;
     }
+    LOG_INFO(netconf_logger, NETCONF_BOOT_UPDATE_COMPLETE)
+        .arg(service_pair.first);
+
     LOG_DEBUG(netconf_logger, NETCONF_DBG_TRACE_DETAIL_DATA,
               NETCONF_GET_CONFIG_CONFIG)
         .arg(service_pair.first)
@@ -297,7 +300,7 @@ NetconfAgent::yangConfig(const CfgServersMapPair& service_pair) {
         parseAnswer(rcode, answer);
     } catch (const std::exception& ex) {
         ostringstream msg;
-        msg << "configSet failed with " << ex.what();
+        msg << "config-set command failed with " << ex.what();
         LOG_ERROR(netconf_logger, NETCONF_SET_CONFIG_FAILED)
             .arg(service_pair.first)
             .arg(msg.str());
@@ -305,7 +308,7 @@ NetconfAgent::yangConfig(const CfgServersMapPair& service_pair) {
     }
     if (rcode != CONTROL_RESULT_SUCCESS) {
         ostringstream msg;
-        msg << "configSet returned " << answerToText(answer);
+        msg << "config-set command returned " << answerToText(answer);
         LOG_ERROR(netconf_logger, NETCONF_SET_CONFIG_FAILED)
             .arg(service_pair.first)
             .arg(msg.str());
@@ -427,6 +430,8 @@ NetconfAgent::validate(S_Session sess, const CfgServersMapPair& service_pair) {
 
 int
 NetconfAgent::update(S_Session sess, const CfgServersMapPair& service_pair) {
+
+    // Check if we should and can process this update.
     if (NetconfProcess::global_shut_down_flag ||
         !service_pair.second->getSubscribeChanges()) {
         return (SR_ERR_OK);
@@ -435,8 +440,13 @@ NetconfAgent::update(S_Session sess, const CfgServersMapPair& service_pair) {
     if (!ctrl_sock) {
         return (SR_ERR_OK);
     }
-    LOG_DEBUG(netconf_logger, NETCONF_DBG_TRACE, NETCONF_UPDATE_CONFIG)
+
+    // All looks good, let's get started. Print an info that we're about
+    // to update the configuration.
+    LOG_INFO(netconf_logger, NETCONF_DBG_TRACE, NETCONF_UPDATE_CONFIG)
         .arg(service_pair.first);
+
+    // Retrieve the configuration from SYSREPO first.
     ConstElementPtr config;
     try {
         TranslatorConfig tc(sess, service_pair.second->getModel());
@@ -468,6 +478,9 @@ NetconfAgent::update(S_Session sess, const CfgServersMapPair& service_pair) {
     if (NetconfProcess::global_shut_down_flag) {
         return (SR_ERR_OK);
     }
+
+    // Ok, now open the control socket. We need this to send the config to
+    // the server.
     ControlSocketBasePtr comm;
     try {
         comm = createControlSocket(ctrl_sock);
@@ -479,6 +492,8 @@ NetconfAgent::update(S_Session sess, const CfgServersMapPair& service_pair) {
             .arg(msg.str());
         return (SR_ERR_OK);
     }
+
+    // Now apply the config using config-set command.
     ConstElementPtr answer;
     int rcode;
     try {

src/bin/netconf/netconf_messages.mes

@@ -6,9 +6,13 @@
 
 $NAMESPACE isc::netconf
 
+% NETCONF_BOOT_UPDATE_COMPLETE Boot-update configuration completed for server %1
+This informational message is issued when the initial configuration was retrieved
+from Netconf and successfully applied to Kea server.
+
 % NETCONF_CONFIG_CHANGE_EVENT Received YANG configuration change %1 event
-This informational message is issued when Netconf receives an YANG
+This informational message is issued when Netconf receives a YANG
-configuration change even.t. The type of event is printed.
+configuration change event. The type of event is printed.
 
 % NETCONF_CONFIG_CHANGED_DETAIL YANG configuration changed: %1
 This debug message indicates a YANG configuration change. The format
@@ -39,7 +43,9 @@ Kea server. The server name and the retrieved configuration are printed.
 
 % NETCONF_GET_CONFIG_FAILED getting configuration from %1 server failed: %2
 The error message indicates that Netconf got an error getting the
-configuration from a Kea server. The name of the server and the error
+configuration from a Kea server. Make sure that the server is up and running,
+has appropriate control socket defined and that the controls socket configuration
+on the server matches that of kea-netconf. The name of the server and the error
 are printed.
 
 % NETCONF_LOG_CHANGE_FAIL Netconf configuration change logging failed: %1
@@ -61,7 +67,9 @@ Kea server. The server name and the applied configuration are printed.
 % NETCONF_SET_CONFIG_FAILED setting configuration to %1 server: %2
 The error message indicates that Netconf got an error setting the
 configuration to a Kea server. The name of the server and the error
-are printed.
+are printed. Make sure that the server is up and running, has appropriate
+control socket defined and that the controls socket configuration
+on the server matches that of kea-netconf.
 
 % NETCONF_STARTED Netconf (version %1) started
 This informational message indicates that Netconf has processed
@@ -87,10 +95,19 @@ This debug message indicates that Netconf validate the configuration
 with a Kea server. The server name and the validated configuration are
 printed.
 
-% NETCONF_VALIDATE_CONFIG_FAILED validating configuration with %1 server: %2
+% NETCONF_VALIDATE_CONFIG_ERROR validating configuration errored with %1 server: %2
 The error message indicates that Netconf got an error validating the
 configuration with a Kea server. The name of the server and the error
-are printed.
+are printed. This message is produced when exception is thrown during
+an attempt to validate received configuration. Additional explanation may be
+provided as a parameter. You may also take a look at earlier log messages.
+
+% NETCONF_VALIDATE_CONFIG_FAILED validating configuration with %1 server: %2
+The warning message indicates that Netconf got an error validating the
+configuration with a Kea server. The name of the server and the error
+are printed. This message is printed when the configuration was rejected
+during normal processing. Additional explanation may be provided as
+a parameter. You may also take a look at earlier log messages.
 
 % NETCONF_UPDATE_CONFIG updating configuration for %1 server
 This debug message indicates that Netconf is trying to update the