[#3106] Update HA commands documentation

diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst
index 681276a24e0fce7a50e9ac379af0d2c22c769532..8ad6433fe80956b51e3647361b1d7cd31bcad6cc 100644 (file)
--- a/doc/sphinx/arm/hooks-ha.rst
+++ b/doc/sphinx/arm/hooks-ha.rst
@@ -1828,7 +1828,7 @@ stop serving any DHCP clients, so it can be safely shut down.
 
 The maintenance feature of the High Availability hook library addresses this
 situation. The :isccmd:`ha-maintenance-start` command was introduced to allow the
-administrator to put the pair of the active servers in a state in which one of
+administrator to put the pairs of the active servers in a state in which one of
 them is responding to all DHCP queries and the other one is awaiting shutdown.
 
 Suppose that the HA setup includes two active servers, ``server1`` and
@@ -1871,6 +1871,14 @@ partner is offline, canceling the maintenance is no longer possible. In that
 case, it is necessary to restart the other server and allow it to complete its
 normal state negotiation process.
 
+If the server has many relationships with different partners, the ``ha-maintenance-start``
+command attempts to transition all of the relationships into the
+``partner-in-maintenance`` state by sending the ``ha-mainteance-notify`` to all
+partner servers. If this step fails for any server an error is returned.
+In that case, send the ``ha-maintenance-cancel`` command to resume normal
+operation and fix the issue.
+
+
 Upgrading From Older HA Versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1977,7 +1985,8 @@ learn which scopes are available for the different HA modes of operation. The
        "command": "ha-scopes",
        "service": [ "dhcp4" ],
        "arguments": {
-           "scopes": [ "HA_server1", "HA_server2" ]
+           "scopes": [ "HA_server1", "HA_server2" ],
+           "server-name": "server2"
        }
    }
 
@@ -1990,10 +1999,15 @@ and "HA_server2" scopes. To disable all scopes specify an empty list:
        "command": "ha-scopes",
        "service": [ "dhcp4 "],
        "arguments": {
-           "scopes": [ ]
+           "scopes": [ ],
+           "server-name": "server2"
        }
    }
 
+The optional ``server-name`` parameter specifies a name of one of the partners belonging
+to the HA relationship this command pertains to. This parameter can be omitted if the
+server receiving this command has only one HA relationship in the configuration.
+
 .. isccmd:: ha-continue
 .. _command-ha-continue:
 
@@ -2008,9 +2022,17 @@ command structure is simply:
 
    {
        "command": "ha-continue",
-       "service": [ "dhcp4" ]
+       "service": [ "dhcp4" ],
+       "arguments": {
+           "scopes": [ ],
+           "server-name": "server2"
+       }
    }
 
+The optional ``server-name`` parameter specifies a name of one of the partners belonging
+to the HA relationship this command pertains to. This parameter can be omitted if the
+server receiving this command has only one HA relationship in the configuration.
+
 .. isccmd:: ha-heartbeat
 .. _command-ha-heartbeat:
 
@@ -2029,9 +2051,17 @@ no arguments:
 
    {
        "command": "ha-heartbeat",
-       "service": [ "dhcp4" ]
+       "service": [ "dhcp4" ],
+       "arguments": {
+           "scopes": [ ],
+           "server-name": "server2"
+       }
    }
 
+The optional ``server-name`` parameter specifies a name of one of the partners belonging
+to the HA relationship this command pertains to. This parameter can be omitted if the
+server receiving this command has only one HA relationship in the configuration.
+
 Upon successful communication with the server, a response similar to this should
 be returned:
 
@@ -2253,10 +2283,10 @@ status of the backup servers.
 The ``ha-maintenance-start`` Command
 ------------------------------------
 
-This command is used to initiate the transition of the server's partner into the
+This command is used to initiate the transition of the server's partners into the
 ``in-maintenance`` state and the transition of the server receiving the command
-into the ``partner-in-maintenance`` state. See the :ref:`ha-maintenance` section
-for details.
+into the ``partner-in-maintenance`` state in each HA relationship. See the
+:ref:`ha-maintenance` section for details.
 
 ::
 
@@ -2274,7 +2304,7 @@ The ``ha-maintenance-cancel`` Command
 This command is used to cancel the maintenance previously initiated using the
 :isccmd:`ha-maintenance-start` command. The server receiving this command will first
 send :isccmd:`ha-maintenance-notify`, with the ``cancel`` flag set to ``true``, to its
-partner. Next, the server reverts from the ``partner-in-maintenance`` state to
+partners. Next, the server reverts from the ``partner-in-maintenance`` state to
 its previous state. See the :ref:`ha-maintenance` section for details.
 
 ::
@@ -2301,10 +2331,15 @@ previous state. See the :ref:`ha-maintenance` section for details.
        "command": "ha-maintenance-notify",
        "service": [ "dhcp4" ],
        "arguments": {
-           "cancel": false
+           "cancel": false,
+           "server-name": "server2"
        }
    }
 
+The optional ``server-name`` parameter specifies a name of one of the partners belonging
+to the HA relationship this command pertains to. This parameter can be omitted if the
+server receiving this command has only one HA relationship in the configuration.
+
 .. warning::
 
    The :isccmd:`ha-maintenance-notify` command is not meant to be used by system
@@ -2330,16 +2365,21 @@ connection after a temporary connection failure. It is also required when the
 A server administrator may send this command to reset a misbehaving state
 machine.
 
-This command includes no arguments:
-
 ::
 
    {
        "command": "ha-reset",
-       "service": [ "dhcp4" ]
+       "service": [ "dhcp4" ],
+       "arguments": {
+           "server-name": "server2"
+       }
    }
 
-And elicits the response:
+The optional ``server-name`` parameter specifies a name of one of the partners belonging
+to the HA relationship this command pertains to. This parameter can be omitted if the
+server receiving this command has only one HA relationship in the configuration.
+
+It elicits the response:
 
 ::
 
@@ -2365,16 +2405,26 @@ test to its partner server. If the connection is still unavailable, the server
 in the ``partner-down`` state enables its own DHCP service to continue
 responding to clients.
 
-This command includes no arguments:
-
 ::
 
    {
        "command": "ha-sync-complete-notify",
-       "service": [ "dhcp4" ]
+       "service": [ "dhcp4" ],
+       "arguments": {
+           "origin": 1100,
+           "server-name": "server2"
+       }
    }
 
-And elicits the response:
+The optional ``server-name`` parameter specifies a name of one of the partners belonging
+to the HA relationship this command pertains to. This parameter can be omitted if the
+server receiving this command has only one HA relationship in the configuration.
+
+The `origin` is used to select the HA service for which the receiving server should
+enable the DHCP service when it receives this notification. This is the same origin the
+sending server used previously to disable the DHCP service before synchronization.
+
+It elicits the response:
 
 ::
 

diff --git a/src/share/api/ha-continue.json b/src/share/api/ha-continue.json
index 606296c5aac40acf1897a4fa7a3cc5aa4c4d69f6..0b5fb5d4c183ae3ed1753a306aca1a490191ebc0 100644 (file)
--- a/src/share/api/ha-continue.json
+++ b/src/share/api/ha-continue.json
@@ -4,6 +4,15 @@
     "brief": [
         "This command resumes the operation of a paused HA state machine."
     ],
+    "cmd-syntax": [
+        "{",
+        "    \"command\": \"ha-continue\",",
+        "    \"service\": [ <service affected: 'dhcp4' or 'dhcp6'> ],",
+        "    \"arguments\": {",
+        "        \"server-name\": <name of the partner server>,",
+        "    }",
+        "}"
+    ],
     "description": "See <xref linkend=\"command-ha-continue\"/>",
     "hook": "high_availability",
     "name": "ha-continue",

diff --git a/src/share/api/ha-heartbeat.json b/src/share/api/ha-heartbeat.json
index f7f05399581da76a91cbe8c42e7d649ded803664..d56c117591405cfcf94a4065ffcd2e0edeb032c6 100644 (file)
--- a/src/share/api/ha-heartbeat.json
+++ b/src/share/api/ha-heartbeat.json
@@ -7,6 +7,10 @@
     "cmd-syntax": [
         "{",
         "    \"command\": \"ha-heartbeat\"",
+        "    \"service\": [ <service affected: 'dhcp4' or 'dhcp6'> ],",
+        "    \"arguments\": {",
+        "        \"server-name\": <name of the partner server>,",
+        "    }",
         "}"
     ],
     "description": "See <xref linkend=\"ha-server-states\"/>",

diff --git a/src/share/api/ha-reset.json b/src/share/api/ha-reset.json
index 6a78a1295b55ab9abdf3afe43b427b9b95b5d982..ae821d3f95a2ed2bc17812642d3fdbe2f0533027 100644 (file)
--- a/src/share/api/ha-reset.json
+++ b/src/share/api/ha-reset.json
@@ -4,6 +4,15 @@
     "brief": [
         "This command resets the HA state machine of the server by transitioning it to the waiting state."
     ],
+    "cmd-syntax": [
+        "{",
+        "    \"command\": \"ha-reset\"",
+        "    \"service\": [ <service affected: 'dhcp4' or 'dhcp6'> ],",
+        "    \"arguments\": {",
+        "        \"server-name\": <name of the partner server>,",
+        "    }",
+        "}"
+    ],
     "description": "See <xref linkend=\"command-ha-reset\"/>",
     "hook": "high_availability",
     "name": "ha-reset",

diff --git a/src/share/api/ha-scopes.json b/src/share/api/ha-scopes.json
index 99240aa6956c59f739999a0ac659f2e30688b3a1..a29f52acd1733edf34aee21b368fafcd4dde5986 100644 (file)
--- a/src/share/api/ha-scopes.json
+++ b/src/share/api/ha-scopes.json
@@ -13,6 +13,7 @@
         "    \"service\": [ <service, typically 'dhcp4' or 'dhcp6'> ],",
         "    \"arguments\": {",
         "        \"scopes\": [ \"HA_server1\", \"HA_server2\" ]",
+        "        \"server-name\": <name of the partner server>,",
         "    }",
         "}"
     ],

diff --git a/src/share/api/ha-sync-complete-notify.json b/src/share/api/ha-sync-complete-notify.json
index 998157b75d39f38ab5e116be1938c7821712acfe..40ab8365c86099a381af698b03ed65abd35e1911 100644 (file)
--- a/src/share/api/ha-sync-complete-notify.json
+++ b/src/share/api/ha-sync-complete-notify.json
@@ -9,6 +9,17 @@
         "heartbeat it can resume allocating new leases in the partner-down state."
     ],
     "cmd-comment": [ "This command takes no arguments." ],
+    "cmd-syntax": [
+        "{",
+        "    \"command\": \"ha-sync-complete-notify\",",
+        "    \"service\": [ <service affected: 'dhcp4' or 'dhcp6'> ],",
+        "    \"arguments\": {",
+        "        \"server-name\": <name of the partner server>,",
+        "        \"origin\": <an integer identifier of an origin to enable the DHCP service>,",
+        "        \"max-period\": <integer, in seconds>",
+        "    }",
+        "}"
+    ],
     "description": [ "See <xref linkend=\"command-ha-sync-complete-notify\"/>" ],
     "hook": "high_availability",
     "name": "ha-sync-complete-notify",