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