[#1959] Updated ha-heartbeat documentation

diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst
index 6eb8e46006655262a933c6764c53cc208d8f7e17..e3c1995a03c84e1d2b8c649eb89ac2b557887975 100644 (file)
--- a/doc/sphinx/arm/hooks-ha.rst
+++ b/doc/sphinx/arm/hooks-ha.rst
@@ -1885,8 +1885,8 @@ command structure is as simple as:
 The ha-heartbeat Command
 ------------------------
 
-The :ref:`ha-server-states` describes how the ``ha-heartbeat`` command is used by
-the active HA servers to detect a failure of one of them. This command, however,
+The :ref:`ha-server-states` section describes how the ``ha-heartbeat`` command is
+used by the active HA servers to detect a failure of one of them. This command, however,
 can also be sent by the system administrator to one or both servers to check their
 state with regards to the HA relationship. This allows for hooking up a monitoring
 system to the HA enabled servers to periodically check if they are operational
@@ -1911,19 +1911,25 @@ be returned:
       "arguments":
           {
               "state": "partner-down",
-              "date-time": "Thu, 07 Nov 2019 08:49:37 GMT"
+              "date-time": "Thu, 07 Nov 2019 08:49:37 GMT",
+              "scopes": [ "server1" ],
+              "unsent-update-count": 123
           }
    }
 
 The returned state value may be one of the values listed in :ref:`ha-server-states`.
-In the example above the ``partner-down`` state is returned, which indicates that
-the server which responded to the command is assuming that its partner is offline,
-thus it is serving all DHCP requests sent to the servers. In order to ensure that
-the partner is indeed offline the administrator should send the ``ha-heartbeat``
-command to the second server. If sending the command fails, e.g. as a result of
-inability to establish TCP connection to the Control Agent or the Control Agent
-reports issues with communication with the DHCP server, it is very likely that
-the server is not running.
+In the example above, the ``partner-down`` state is returned, which indicates that
+the server which responded to the command is assuming that its partner is offline;
+thus, it is serving all DHCP requests sent to the servers. In order to ensure that
+the partner is indeed offline, the administrator should send the ``ha-heartbeat``
+command to the second server. If sending the command fails, e.g. due to inability
+to establish TCP connection to the Control Agent or the Control Agent reports
+issues with communication with the DHCP server, it is very likely that the server
+is not running.
+
+The ``date-time`` parameter conveys the server's notion of time. The
+``unsent-update-count`` is used internally by the partner receiving the heartbeat
+response to determine whether it should synchronize its lease database.
 
 The typical response returned by one of the servers when both servers are
 operational is:
@@ -1936,7 +1942,9 @@ operational is:
       "arguments":
           {
               "state": "load-balancing",
-              "date-time": "Thu, 07 Nov 2019 08:49:37 GMT"
+              "date-time": "Thu, 07 Nov 2019 08:49:37 GMT",
+              "scopes": [ "server1" ],
+              "unsent-update-count": 0
           }
    }
 

diff --git a/src/share/api/ha-heartbeat.json b/src/share/api/ha-heartbeat.json
index 062801894630efa97de179ec8e24f5c2da41b7c1..f7f05399581da76a91cbe8c42e7d649ded803664 100644 (file)
--- a/src/share/api/ha-heartbeat.json
+++ b/src/share/api/ha-heartbeat.json
@@ -13,7 +13,19 @@
     "hook": "high_availability",
     "name": "ha-heartbeat",
     "resp-comment": [
-        "The response to this command is different from the typical command response. The response includes the server state (see :ref:`ha-server-states`) plus the current clock value."
+        "The response includes a server state (see :ref:`ha-server-states`), current clock value, served scopes and the counter indicating how many leases the server has allocated without sending lease updates to its partner. The partner uses this counter to determine if it should synchronize its lease database."
+    ],
+    "resp-syntax": [
+        "{",
+        "    \"result\": 0,",
+        "    \"text\": \"HA peer status returned.\",",
+        "    \"arguments\": {",
+        "        \"state\": <server state>,",
+        "        \"date-time\": <server notion of time>,",
+        "        \"scopes\": [ <first scope>, <second scope>, ... ],",
+        "        \"unsent-update-count\": <total number of lease allocations in partner-down state>",
+        "    }",
+        "}"
     ],
     "support": [
         "kea-dhcp4",