From 3d76d8f1a065b4865d1c2c5f9465c75a645e54ae Mon Sep 17 00:00:00 2001
From: Marcin Siodelski <marcin@isc.org>
Date: Fri, 13 Dec 2019 16:03:05 +0100
Subject: [PATCH] [#1041] Updated docs about status-get

Added new HA specific section too.
---
 doc/sphinx/api/status-get.json  | 26 ++++++++++----
 doc/sphinx/arm/ctrl-channel.rst | 21 +++++++-----
 doc/sphinx/arm/hooks-ha.rst     | 60 +++++++++++++++++++++++++++++++++
 3 files changed, 92 insertions(+), 15 deletions(-)

diff --git a/doc/sphinx/api/status-get.json b/doc/sphinx/api/status-get.json
index 2e7ffff8aa..c0dab8e717 100644
--- a/doc/sphinx/api/status-get.json
+++ b/doc/sphinx/api/status-get.json
@@ -1,7 +1,7 @@
 {
     "avail": "1.7.3",
     "brief": [
-        "This command returns server runtime information.",
+        "This command returns server's runtime information.",
         "It takes no arguments."
     ],
     "cmd-syntax": [
@@ -12,16 +12,28 @@
     "description": "See <xref linkend=\"command-status-get\"/>",
     "name": "status-get",
     "resp-comment": [
-        "If the HA hook is loaded it adds HA servers info to the response."
+        "If the libdhcp_ha (High Availability) hooks library is loaded by the DHCP server receiving this command the response also includes the HA specific status information of the server receiving the command and its partner's status."
     ],
     "resp-syntax": [
         "{",
-        "    \"result\": 0,",
+        "    \"result\": <integer>,",
         "    \"arguments\": {",
-        "        \"pid\": 1234,",
-        "        \"uptime\": 59,",
-        "        \"reload\": 10,",
-        "        ...",
+        "        \"pid\": <integer>,",
+        "        \"uptime\": <uptime in seconds>,",
+        "        \"reload\": <time since reload in seconds>,",
+        "        \"ha-servers\": {",
+        "            \"local\": {",
+        "                \"role\": <role of this server as in the configuration file>,",
+        "                \"scopes\": <list of scope names served by this server>,",
+        "                \"state\": <HA state name of the server receiving the command>,",
+        "            },",
+        "            \"remote\": {",
+        "                \"in-touch\": <indicates if this server communicated with remote>,",
+        "                \"last-scopes\": <list of scopes served by partner>,",
+        "                \"last-state\": <HA state name of the partner>,",
+        "                \"role\": <partner role>",
+        "            }",
+        "        }",
         "    }",
         "}"
     ],
diff --git a/doc/sphinx/arm/ctrl-channel.rst b/doc/sphinx/arm/ctrl-channel.rst
index 36e893c83a..36ca31b126 100644
--- a/doc/sphinx/arm/ctrl-channel.rst
+++ b/doc/sphinx/arm/ctrl-channel.rst
@@ -543,7 +543,7 @@ The ``dhcp-enable`` command globally enables the DHCP service.
 The status-get Command
 ----------------------
 
-The ``status-get`` command returns server runtime information:
+The ``status-get`` command returns server's runtime information:
 
  - pid: process id.
 
@@ -551,20 +551,25 @@ The ``status-get`` command returns server runtime information:
 
  - reload: number of seconds since the last configuration (re)load.
 
- - ha-servers: HA hook information when the hook was loaded:
+ - ha-servers: HA specific status information about the DHCP servers
+   configured to use HA hooks library:
 
      * local: for the local server the state, the role (primary,
        secondary, ...) and scopes (i.e. what the server is actually
        processing).
 
-     * remote: for the remote server the last known state and the role
-       (scopes should be available in a future release)
+     * remote: for the remote server the last known state, served
+       HA scopes and the role of the server in HA relationship.
 
-.. note::
+The ``ha-servers`` information is only returned when the command is
+sent to the DHCP servers being in the HA setup. This parameter is
+never returned when the ``status-get`` command is sent to the
+Control Agent or DDNS deamon.
+
+To learn more about the HA status information returned by the
+``status-get`` command please refer to the the :ref:`command-ha-status-get`
+section.
 
-   The HA local server does not always know the current state of the
-   HA remote server. The command (or the ``ha-heartbeat``) should be
-   sent to the remote server as explained in HA :ref:`ha-server-states`.
 
 .. _command-server-tag-get:
 
diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst
index 92c16247ed..c741f4e860 100644
--- a/doc/sphinx/arm/hooks-ha.rst
+++ b/doc/sphinx/arm/hooks-ha.rst
@@ -1299,3 +1299,63 @@ to the failing server allows for detecting the failure.
   servers may not reflect issues with one of the servers that just began.
 
 
+.. _command-ha-status-get:
+
+The status-get Command
+------------------------
+
+The ``status-get`` is the general purpose command supported by several Kea deamons,
+not only DHCP servers. However, when sent to the DHCP server with HA enabled, it
+can be used to get insight into the details of the HA specific status information
+of the servers being in the HA configuration. Not only does the response contain
+the status information of the server receiving this command but also the
+information about its partner, if this information is available.
+
+The following is the example response to the ``status-get`` command including
+the HA status of two load balancing servers:
+
+::
+
+   {
+       "result": 0,
+       "text": "",
+       "arguments": {
+           "pid": 1234,
+           "uptime": 3024,
+           "reload": 1111,
+           "ha-servers": {
+               "local": {
+                   "role": "primary",
+                   "scopes": [ "server1" ],
+                   "state": "load-balancing"
+               },
+                "remote": {
+                   "in-touch": true,
+                   "role": "secondary",
+                   "last-scopes": [ "server2" ],
+                   "last-state": "load-balancing"
+               }
+           }
+       }
+   }
+
+
+The ``ha-servers`` map contains two structures: ``local`` and ``remote``. The former
+contains the status information of the server which received the command. The
+latter contains the status information known to the local server about the
+partner. The ``role`` of the partner server is gathered from the local
+configuration file, therefore it should always be available. The remaining
+status information such as ``last-scopes`` and ``last-state`` is not available
+until the local server communicates with the remote by successfully sending
+the ``ha-heartbeat`` command. If at least one such communication took place,
+the returned value of ``in-touch`` parameter is set to ``true``. By examining
+this value, the command sender can determine whether the information about
+the remote server is reliable.
+
+The ``last-scopes`` and ``last-state`` contain the information about the
+HA scopes served by the partner and its state. Note that this information
+is gathered during the heartbeat command exchange, so it may not be
+accurate if the communication problem occur between the partners and this
+status information is not refreshed. In such case, it may be useful to
+send the ``status-get`` command to the partner server directly to check
+its current state.