ctdb/config/events.d/README

   1 The events.d/ directory contains event scripts used by CTDB.  Event
   2 scripts are triggered on certain events, such as startup, monitoring
   3 or public IP allocation.  Scripts may be specific to services,
   4 networking or internal CTDB operations.
   5
   6 All event scripts start with the prefix 'NN.' where N is a digit.  The
   7 event scripts are run in sequence based on NN.  Thus 10.interface will
   8 be run before 60.nfs.  It is recommended to keep each NN unique.
   9 However, scripts with the same NN prefix will be executed in
  10 alphanumeric sort order.
  11
  12 As a special case, any eventscript that ends with a '~' character will be
  13 ignored since this is a common postfix that some editors will append to
  14 older versions of a file.
  15
  16 Only executable event scripts are run by CTDB.  Any event script that
  17 does not have execute permission is ignored.
  18
  19 The eventscripts are called with varying number of arguments.  The
  20 first argument is the event name and the rest of the arguments depend
  21 on the event name.
  22
  23 Event scripts must return 0 for success and non-zero for failure.
  24
  25 Output of event scripts is logged.  On failure the output of the
  26 failing event script is included in the output of "ctdb scriptstatus".
  27
  28 The following events are supported (with arguments shown):
  29
  30 init
  31
  32         This event is triggered once when CTDB is starting up.  This
  33         event is used to do some basic cleanup and initialisation.
  34
  35         During the "init" event CTDB is not listening on its Unix
  36         domain socket, so the "ctdb" CLI will not work.
  37
  38         Failure of this event will cause CTDB to terminate.
  39
  40         Example: 00.ctdb creates $CTDB_SCRIPT_VARDIR
  41
  42 setup
  43
  44         This event is triggered once, after the "init" event has
  45         completed.
  46
  47         For this and any subsequent events the CTDB Unix domain socket
  48         is available, so the "ctdb" CLI will work.
  49
  50         Failure of this event will cause CTDB to terminate.
  51
  52         Example: 00.ctdb processes tunables defined in the CTDB
  53         configuration using CTDB_SET_<TunableName>=<TunableValue>.
  54
  55 startup
  56
  57         This event is triggered after the "setup" event has completed
  58         and CTDB has finished its initial database recovery.
  59
  60         This event starts all services that are managed by CTDB.  Each
  61         service that is managed by CTDB should implement this event
  62         and use it to (re)start the service.
  63
  64         If the "startup" event fails then CTDB will retry it until it
  65         succeeds.  There is no limit on the number of retries.
  66
  67         Example: 50.samba uses this event to start the Samba daemon if
  68         CTDB_MANAGES_SAMBA=yes.
  69
  70 shutdown
  71
  72         This event is triggered when CTDB is shutting down.
  73
  74         This event shuts down all services that are managed by CTDB.
  75         Each service that is managed by CTDB should implement this
  76         event and use it to stop the service.
  77
  78         Example: 50.samba uses this event to shut down the Samba
  79         daemon if CTDB_MANAGES_SAMBA=yes.
  80
  81 monitor
  82
  83         This event is run periodically.  The interval between
  84         successive "monitor" events is configured using the
  85         MonitorInterval tunable, which defaults to 15 seconds.
  86
  87         This event is triggered by CTDB to continuously monitor that
  88         all managed services are healthy.  If all event scripts
  89         complete then the monitor event successfully then the node is
  90         marked HEALTHY.  If any event script fails then no subsequent
  91         scripts will be run for that event and the node is marked
  92         UNHEALTHY.
  93
  94         Each service that is managed by CTDB should implement this
  95         event and use it to monitor the service.
  96
  97         Example: 10.interface checks that each configured interface
  98         for public IP addresses has a physical link established.
  99
 100 startrecovery
 101
 102         This event is triggered every time a database recovery process
 103         is started.
 104
 105         This is rarely used.
 106
 107 recovered
 108
 109         This event is triggered every time a database recovery process
 110         is completed.
 111
 112         This is rarely used.
 113
 114 takeip <interface> <ip-address> <netmask-bits>
 115
 116         This event is triggered for each public IP address taken by a
 117         node during IP address (re)assignment.  Multiple "takeip"
 118         events can be run in parallel if multiple IP addresses are
 119         being assigned.
 120
 121         Example: In 10.interface the "ip" command (from the Linux
 122         iproute2 package) is used to add the specified public IP
 123         address to the specified interface.  The "ip" command can
 124         safely be run concurrently.  However, the "iptables" command
 125         cannot be run concurrently so a wrapper is used to serialise
 126         runs using exclusive locking.
 127
 128         If substantial work is required to reconfigure a service when
 129         a public IP address is taken over it can be better to defer
 130         service reconfiguration to the "ipreallocated" event, after
 131         all IP addresses have been assigned.
 132
 133         Example: 60.nfs uses ctdb_service_set_reconfigure() to flag
 134         that public IP addresses have changed so that service
 135         reconfiguration will occur in the "ipreallocated" event.
 136
 137 releaseip <interface> <ip-address> <netmask-bits>
 138
 139         This event is triggered for each public IP address released by
 140         a node during IP address (re)assignment.  Multiple "releaseip"
 141         events can be run in parallel if multiple IP addresses are
 142         being unassigned.
 143
 144         In all other regards, this event is analogous to the "takeip"
 145         event above.
 146
 147 updateip <old-interface> <new-interface> <ip-address> <netmask-bits>
 148
 149         This event is triggered for each public IP address moved
 150         between interfaces on a node during IP address (re)assignment.
 151         Multiple "updateip" events can be run in parallel if multiple
 152         IP addresses are being moved.
 153
 154         This event is only used if multiple interfaces are capable of
 155         hosting an IP address, as specified in the public addresses
 156         configuration file.
 157
 158         This event is similar to the "takeip" event above.
 159
 160 ipreallocated
 161
 162         This event is triggered after "releaseip", "takeip" and
 163         "updateip" events during public IP address (re)assignment.
 164
 165         This event is used to reconfigure services.
 166
 167         This event runs even if public IP addresses on a node have not
 168         been changed.  This allows reconfiguration to depend on the
 169         states of other nodes rather that just IP addresses.
 170
 171         Example: 11.natgw recalculates the NAT gateway master and
 172         updates the relevant network configuration on each node if the
 173         NAT gateway master has changed.
 174
 175 Additional notes for "takeip", "releaseip", "updateip",
 176 ipreallocated":
 177
 178 * Failure of any of these events causes IP allocation to be retried.
 179
 180 * The "ipreallocated" event is run on all nodes.  It is even run if no
 181   "takeip", "releaseip" or "updateip" events were triggered.
 182
 183 * An event script can use ctdb_service_set_reconfigure() in "takeip"
 184   or "releaseip" events to flag that its service needs to be
 185   reconfigured.  The event script can then define a
 186   service_reconfigure() function, which will be implicitly run before
 187   the "ipreallocated" event.  This is a useful way of performing
 188   reconfiguration that is conditional upon public IP address changes.
 189
 190   This means an explicit "ipreallocated" event handler is usually not
 191   necessary.