diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst index 681276a24e..8ad6433fe8 100644 --- 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 606296c5aa..0b5fb5d4c1 100644 --- 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\": [ ],", + " \"arguments\": {", + " \"server-name\": ,", + " }", + "}" + ], "description": "See ", "hook": "high_availability", "name": "ha-continue", diff --git a/src/share/api/ha-heartbeat.json b/src/share/api/ha-heartbeat.json index f7f0539958..d56c117591 100644 --- a/src/share/api/ha-heartbeat.json +++ b/src/share/api/ha-heartbeat.json @@ -7,6 +7,10 @@ "cmd-syntax": [ "{", " \"command\": \"ha-heartbeat\"", + " \"service\": [ ],", + " \"arguments\": {", + " \"server-name\": ,", + " }", "}" ], "description": "See ", diff --git a/src/share/api/ha-reset.json b/src/share/api/ha-reset.json index 6a78a1295b..ae821d3f95 100644 --- 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\": [ ],", + " \"arguments\": {", + " \"server-name\": ,", + " }", + "}" + ], "description": "See ", "hook": "high_availability", "name": "ha-reset", diff --git a/src/share/api/ha-scopes.json b/src/share/api/ha-scopes.json index 99240aa695..a29f52acd1 100644 --- a/src/share/api/ha-scopes.json +++ b/src/share/api/ha-scopes.json @@ -13,6 +13,7 @@ " \"service\": [ ],", " \"arguments\": {", " \"scopes\": [ \"HA_server1\", \"HA_server2\" ]", + " \"server-name\": ,", " }", "}" ], diff --git a/src/share/api/ha-sync-complete-notify.json b/src/share/api/ha-sync-complete-notify.json index 998157b75d..40ab8365c8 100644 --- 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\": [ ],", + " \"arguments\": {", + " \"server-name\": ,", + " \"origin\": ,", + " \"max-period\": ", + " }", + "}" + ], "description": [ "See " ], "hook": "high_availability", "name": "ha-sync-complete-notify",