From 3a8b318fb08033a0c1bc98a61ea98c7c0f718fc3 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Thu, 12 Jul 2018 17:55:27 +0200 Subject: [PATCH] [5675] Described HA state machine pausing. --- doc/guide/hooks-ha.xml | 185 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 184 insertions(+), 1 deletion(-) diff --git a/doc/guide/hooks-ha.xml b/doc/guide/hooks-ha.xml index 3766e6c654..aab8e0bcac 100644 --- a/doc/guide/hooks-ha.xml +++ b/doc/guide/hooks-ha.xml @@ -137,7 +137,7 @@ -
+
Server States The DHCP server operating within an HA setup runs a state machine and the state of the server can be retrieved by its peers using the @@ -1047,6 +1047,176 @@
+
+ Pausing HA State Machine + The high availability state machine includes many different + states described in detail in . + The server enters each state when certain conditions are met, most + often taking into account the partner server's state. In some states + the server performs specific actions, e.g. synchronization of the + lease database in the syncing state or responding + to DHCP queries according to the configured mode of operation in the + load-balancing and hot-standby + states. + + + By default, transitions between the states are performed + automatically and the server administrator has no direct control + when the transitions take place and, in most cases, the + administrator doesn't need such control. In some situations, + however, the administrator may want to "pause" the HA state + machine in a selected state to perform some additional administrative + actions before the server transitions to the next state. + + + Consider a server failure which results in a loss of entire lease + database. Typically, the server will rebuild its lease database + when it enters the syncing state by querying + the partner server for leases, but it is possible that the + partner was also experiencing a failure and lacks lease information. + In this case, it may be required to reconstruct lease databases on + both servers from some external source, e.g. a backup server. If the + lease database is going to be reconstructed via RESTful API, the + servers should be started in the initial, i.e. waiting + state and remain in this state while leases are being added. In + particular, the servers should not attempt to synchronize their lease + databases nor start serving DHCP clients. + + + The HA hooks library provides configuration parameters and a + command to control when the HA state machine should be paused and + resumed. The following configuration will cause the HA state machine + to pause in the waiting state after server startup. + +"Dhcp4": { + + ... + + "hooks-libraries": [ + { + "library": "/usr/lib/hooks/libdhcp_lease_cmds.so", + "parameters": { } + }, + { + "library": "/usr/lib/hooks/libdhcp_ha.so", + "parameters": { + "high-availability": [ { + "this-server-name": "server1", + "mode": "load-balancing", + "peers": [ + { + "name": "server1", + "url": "http://192.168.56.33:8080/", + "role": "primary" + }, + { + "name": "server2", + "url": "http://192.168.56.66:8080/", + "role": "secondary" + } + ], + "state-machine": [ + { + "state": "waiting", + "pause": "once" + } + ] + } ] + } + } + ], + + ... + +} + + + + The pause parameter value once + denotes that the state machine should be paused upon the first transition + to the waiting state. Later transitions to this state + won't cause the state machine to pause. Two other supported values of the + pause parameter are: always and + never. The latter is the default value for each state, + which instructs the server to never pause the state machine. + + + In order to "unpause" the state machine the ha-continue + command must be sent to the paused server. This command does not take + any arguments. See for details + about commands specific for HA hooks library. + + + It is possible to configure the state machine to pause in more than + one state. Consider the following configuration. + +"Dhcp4": { + + ... + + "hooks-libraries": [ + { + "library": "/usr/lib/hooks/libdhcp_lease_cmds.so", + "parameters": { } + }, + { + "library": "/usr/lib/hooks/libdhcp_ha.so", + "parameters": { + "high-availability": [ { + "this-server-name": "server1", + "mode": "load-balancing", + "peers": [ + { + "name": "server1", + "url": "http://192.168.56.33:8080/", + "role": "primary" + }, + { + "name": "server2", + "url": "http://192.168.56.66:8080/", + "role": "secondary" + } + ], + "state-machine": [ + { + "state": "ready", + "pause": "always" + }, + { + "state": "partner-down", + "pause": "once" + } + ] + } ] + } + } + ], + + ... + +} + + + + This configuration instructs the server to pause the state + machine every time it transitions to the ready state + and upon the first transition to the partner-down + state. + + Refer to the for a complete of + list of server states. The state machine can be paused in any of the + supported states, however it is not practical for the + backup and terminated states because + the server never transitions out of these states anyway. + + + In the syncing state the server is paused + before it makes an attempt to synchronize lease database with a partner. + In order to pause the state machine after lease database synchronization, + use the ready state instead. + +
+
Control Agent Configuration The describes in detail the @@ -1198,6 +1368,19 @@
+
+ ha-continue command + This command is used to resume the operation of the paused HA + state machine as described in the . + It takes no arguments, so the command structure is as simple as: + +{ + "command": "ha-continue" +} + + +
+
-- 2.47.2