[#1986] added comments and updated ARM

doc/examples/agent/comments.json

@@ -9,6 +9,13 @@
         "comment": "A Control Agent",
 
         "http-host": "127.0.0.1",
+
+        // If enabling HA and multi-threading, the 8000 port is used by the HA
+        // hook library http listener. The control-agent is not required any
+        // longer for HA hook library with multi-threading to function because
+        // it uses it's own http listener on the same port, but it can still be
+        // used to handle other commands. In this case, a different port
+        // (eg. 8800) must be used for the control-agent.
         "http-port": 8000,
 
         // In authentication

doc/examples/agent/https.json

@@ -9,6 +9,12 @@
         "http-host": "127.0.0.1",
 
         // Another mandatory parameter is the HTTP port.
+        // If enabling HA and multi-threading, the 8000 port is used by the HA
+        // hook library http listener. The control-agent is not required any
+        // longer for HA hook library with multi-threading to function because
+        // it uses it's own http listener on the same port, but it can still be
+        // used to handle other commands. In this case, a different port
+        // (eg. 8800) must be used for the control-agent.
         "http-port": 8000,
 
         // TLS trust anchor (Certificate Authority). This is a file name or

doc/examples/agent/simple.json

@@ -9,6 +9,12 @@
         "http-host": "127.0.0.1",
 
         // Another mandatory parameter is the HTTP port.
+        // If enabling HA and multi-threading, the 8000 port is used by the HA
+        // hook library http listener. The control-agent is not required any
+        // longer for HA hook library with multi-threading to function because
+        // it uses it's own http listener on the same port, but it can still be
+        // used to handle other commands. In this case, a different port
+        // (eg. 8800) must be used for the control-agent.
         "http-port": 8000,
 
         // Optional authentication.

doc/sphinx/arm/agent.rst

@@ -102,6 +102,12 @@ provided above, the RESTful service will be available under the URL of
 ``https://10.20.30.40:8000/``. If these parameters are not specified, the
 default URL is ``http://127.0.0.1:8000/``.
 
+If enabling HA and multi-threading, the 8000 port is used by the HA hook library
+http listener. The CA is not required any longer for HA hook library with
+multi-threading to function because it uses it's own http listener on the same
+port, but it can still be used to handle other commands. In this case, a
+different port (eg. 8800) must be used for the CA.
+
 The ``trust-anchor``, ``cert-file``, ```key-file`` and ``cert-required``
 parameters specify the TLS setup for HTTP i.e. HTTPS. If these parameters
 are not specified HTTP is used. The TLS/HTTPS support in Kea is

doc/sphinx/arm/hooks-ha.rst

@@ -1457,6 +1457,12 @@ load-balancing and the hot-standby cases presented in previous sections.
    {
    "Control-agent": {
        "http-host": "192.168.56.33",
+       // If enabling HA and multi-threading, the 8000 port is used by the HA
+       // hook library http listener. The control-agent is not required any
+       // longer for HA hook library with multi-threading to function because
+       // it uses it's own http listener on the same port, but it can still be
+       // used to handle other commands. In this case, a different port
+       // (eg. 8800) must be used for the control-agent.
        "http-port": 8000,
 
        "control-sockets": {

src/bin/keactrl/kea-ctrl-agent.conf.pre

@@ -18,6 +18,12 @@
 // RESTful interface to be available at http://127.0.0.1:8000/
 "Control-agent": {
     "http-host": "127.0.0.1",
+    // If enabling HA and multi-threading, the 8000 port is used by the HA hook
+    // library http listener. The control-agent is not required any longer for
+    // HA hook library with multi-threading to function because it uses it's own
+    // http listener on the same port, but it can still be used to handle other
+    // commands. In this case, a different port (eg. 8800) must be used for the
+    // control-agent.
     "http-port": 8000,
 
     // Specify location of the files to which the Control Agent