ctdb/config/events.d/README

   1 This directory is where you should put any local or application
   2 specific event scripts for ctdb to call.
   3
   4 All event scripts start with the prefic 'NN.' where N is a digit.
   5 The event scripts are run in sequence based on NN.
   6 Thus 10.interfaces will be run before 60.nfs.
   7
   8 Each NN must be unique and duplicates will cause undefined behaviour.
   9 I.e. having both 10.interfaces and 10.otherstuff is not allowed.
  10
  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 event scripts with executable permissions are run from CTDB. Any event
  17 script that does not have executable permission is ignored.
  18
  19 The eventscripts are called with varying number of arguments.
  20 The first argument is the "event" and the rest of the arguments depend
  21 on which event was triggered.
  22
  23 All of the events except the 'shutdown' and 'startrecovery' events will be
  24 called with the ctdb daemon in NORMAL mode (ie. not in recovery)
  25
  26 The events currently implemented are
  27 init
  28         This event does not take any additional arguments.
  29         This event is only invoked once, when ctdb is starting up.
  30         This event is used to do some cleanup work from earlier runs
  31         and prepare the basic setup.
  32         At this stage 'ctdb' commands won't work.
  33
  34         Example: 00.ctdb cleans up $CTDB_VARDIR/state
  35
  36 setup
  37         This event does not take any additional arguments.
  38         This event is only invoked once, after init event is completed.
  39         This event is used to do setup any tunables defined in ctdb
  40         configuration file.
  41
  42 startup
  43         This event does not take any additional arguments.
  44         This event is only invoked once, when ctdb has finished
  45         the initial recoveries. This event is used to wait for
  46         the service to start and all resources for the service
  47         becoming available.
  48
  49         This is used to prevent ctdb from starting up and advertize its
  50         services until all dependent services have become available.
  51
  52         All services that are managed by ctdb should implement this
  53         event and use it to start the service.
  54
  55         Example: 50.samba uses this event to start the samba daemon
  56         and then wait until samba and all its associated services have
  57         become available. It then also proceeds to wait until all
  58         shares have become available.
  59
  60 shutdown
  61         This event is called when the ctdb service is shuting down.
  62
  63         All services that are managed by ctdb should implement this event
  64         and use it to perform a controlled shutdown of the service.
  65
  66         Example: 60.nfs uses this event to shut down nfs and all associated
  67         services and stop exporting any shares when this event is invoked.
  68
  69 monitor
  70         This event is invoked every X number of seconds.
  71         The interval can be configured using the MonitorInterval tunable
  72         but defaults to 15 seconds.
  73
  74         This event is triggered by ctdb to continuously monitor that all
  75         managed services are healthy.
  76         When invoked, the event script will check that the service is healthy
  77         and return 0 if so. If the service is not healthy the event script
  78         should return non zero.
  79
  80         If a service returns nonzero from this script this will cause ctdb
  81         to consider the node status as UNHEALTHY and will cause the public
  82         address and all associated services to be failed over to a different
  83         node in the cluster.
  84
  85         All managed services should implement this event.
  86
  87         Example: 10.interfaces which checks that the public interface (if used)
  88         is healthy, i.e. it has a physical link established.
  89
  90 takeip
  91         This event is triggered everytime the node takes over a public ip
  92         address during recovery.
  93         This event takes three additional arguments :
  94         'interface' 'ipaddress' and 'netmask'
  95
  96         Before this event there will always be a 'startrecovery' event.
  97
  98         This event will always be followed by a 'recovered' event once
  99         all ipaddresses have been reassigned to new nodes and the ctdb database
 100         has been recovered.
 101         If multiple ip addresses are reassigned during recovery it is
 102         possible to get several 'takeip' events followed by a single
 103         'recovered' event.
 104
 105         Since there might involve substantial work for the service when an ip
 106         address is taken over and since multiple ip addresses might be taken
 107         over in a single recovery it is often best to only mark which addresses
 108         are being taken over in this event and defer the actual work to
 109         reconfigure or restart the services until the 'recovered' event.
 110
 111         Example: 60.nfs which just records which ip addresses are being taken
 112         over into a local state directory   and which defers the actual
 113         restart of the services until the 'recovered' event.
 114
 115
 116 releaseip
 117         This event is triggered everytime the node releases a public ip
 118         address during recovery.
 119         This event takes three additional arguments :
 120         'interface' 'ipaddress' and 'netmask'
 121
 122         In all other regards this event is analog to the 'takeip' event above.
 123
 124         Example: 60.nfs
 125
 126 updateip
 127         This event is triggered everytime the node moves a public ip
 128         address between interfaces
 129         This event takes four additional arguments :
 130         'old-interface' 'new-interface' 'ipaddress' and 'netmask'
 131
 132         Example: 10.interface
 133
 134 startrecovery
 135         This event is triggered everytime we start a recovery process
 136         or before we start changing ip address allocations.
 137
 138 recovered
 139         This event is triggered every time we have finished a full recovery
 140         and also after we have finished reallocating the public ip addresses
 141         across the cluster.
 142
 143         Example: 60.nfs which if the ip address configuration has changed
 144         during the recovery (i.e. if addresses have been taken over or
 145         released) will kill off any tcp connections that exist for that
 146         service and also send out statd notifications to all registered
 147         clients.
 148
 149 ipreallocated
 150
 151         This event is triggered after releaseip and takeip events in a
 152         takeover run.  It can be used to reconfigure services, update
 153         routing and many other things.
 154
 155 Additional note for takeip, releaseip, recovered:
 156
 157 ALL services that depend on the ip address configuration of the node must
 158 implement all three of these events.
 159
 160 ALL services that use TCP should also implement these events and at least
 161 kill off any tcp connections to the service if the ip address config has
 162 changed in a similar fashion to how 60.nfs does it.
 163 The reason one must do this is that ESTABLISHED tcp connections may survive
 164 when an ip address is released and removed from the host until the ip address
 165 is re-takenover.
 166 Any tcp connections that survive a release/takeip sequence can potentially
 167 cause the client/server tcp connection to get out of sync with sequence and
 168 ack numbers and cause a disruptive ack storm.
 169
 170