From: Marcin Siodelski <marcin@isc.org>
Date: Tue, 19 May 2020 14:36:36 +0000 (+0200)
Subject: [#1087] Updated status-get description
X-Git-Tag: Kea-1.7.8~34
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=65a956f36d0fa86993ebdebe1cf7fbfa5824d2aa;p=thirdparty%2Fkea.git

[#1087] Updated status-get description

The HA specific part of the status-get command was updated.
---

diff --git a/doc/sphinx/api/status-get.json b/doc/sphinx/api/status-get.json
index 66926830d2..e2facef985 100644
--- a/doc/sphinx/api/status-get.json
+++ b/doc/sphinx/api/status-get.json
@@ -21,20 +21,25 @@
         "        \"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\": {",
-        "                \"age\": <the age of the remote status in seconds>,",
-        "                \"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>",
+        "        \"high-availability\": [",
+        "            {",
+        "                \"ha-mode\": <HA mode configured for this relationship>",
+        "                \"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\": {",
+        "                        \"age\": <the age of the remote status in seconds>,",
+        "                        \"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/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst
index b7e506779c..237e9fdcab 100644
--- a/doc/sphinx/arm/hooks-ha.rst
+++ b/doc/sphinx/arm/hooks-ha.rst
@@ -1586,29 +1586,48 @@ the HA status of two load balancing servers:
            "pid": 1234,
            "uptime": 3024,
            "reload": 1111,
-           "ha-mode": "load-balancing",
-           "ha-servers": {
-               "local": {
-                   "role": "primary",
-                   "scopes": [ "server1" ],
-                   "state": "load-balancing"
-               },
-                "remote": {
-                   "age": 10,
-                   "in-touch": true,
-                   "role": "secondary",
-                   "last-scopes": [ "server2" ],
-                   "last-state": "load-balancing",
-                   "communication-interrupted": true,
-                   "connecting-clients": 2,
-                   "unacked-clients": 1,
-                   "unacked-clients-left": 2,
-                   "analyzed-packets": 8
+           "high-availability": [
+               {
+                   "ha-mode": "load-balancing",
+                   "ha-servers": {
+                       "local": {
+                           "role": "primary",
+                           "scopes": [ "server1" ],
+                           "state": "load-balancing"
+                       },
+                       "remote": {
+                           "age": 10,
+                           "in-touch": true,
+                           "role": "secondary",
+                           "last-scopes": [ "server2" ],
+                           "last-state": "load-balancing",
+                           "communication-interrupted": true,
+                           "connecting-clients": 2,
+                           "unacked-clients": 1,
+                           "unacked-clients-left": 2,
+                           "analyzed-packets": 8
+                       }
+                   }
                }
-           }
+           ]
        }
    }
 
+The ``high-availability`` argument is a list which currently always comprises
+one element. There are plans to extend the HA implementation to facilitate
+multiple HA relationships for a single server instance. In that case, the
+returned list will comprise more elements, each describing the status of
+a different relationship in which the server participates. Currently, it
+is only one status.
+
+.. note::
+
+   In Kea 1.7.8 an incompatible change was introduced to the syntax of the
+   ``status-get`` response. Previously, the HA status for a single relationship
+   was returned within the ``arguments`` map. Currently, the returned status
+   is enclosed in the list as described above. Any existing code relying on the
+   previous syntax must be updated to work with the new Kea versions.
+
 
 The ``ha-servers`` map contains two structures: ``local`` and ``remote``. The former
 contains the status information of the server which received the command. The