ctdb/doc/cluster_mutex_helper.txt

   1 Writing CTDB cluster mutex helpers
   2 ==================================
   3
   4 CTDB uses cluster-wide mutexes to protect against a "split brain",
   5 which could occur if the cluster becomes partitioned due to network
   6 failure or similar.
   7
   8 CTDB uses a cluster-wide mutex for its "recovery lock", which is used
   9 to ensure that only one database recovery can happen at a time.  For
  10 an overview of recovery lock configuration see the RECOVERY LOCK
  11 section in ctdb(7).  CTDB tries to ensure correct operation of the
  12 recovery lock by attempting to take the recovery lock when CTDB knows
  13 that it should already be held.
  14
  15 By default, CTDB uses a supplied mutex helper that uses a fcntl(2)
  16 lock on a specified file in the cluster filesystem.
  17
  18 However, a user supplied mutex helper can be used as an alternative.
  19 The rest of this document describes the API for mutex helpers.
  20
  21 A mutex helper is an external executable
  22 ----------------------------------------
  23
  24 A mutex helper is an external executable that can be run by CTDB.
  25 There are no CTDB-specific compilation dependencies.  This means that
  26 a helper could easily be scripted around existing commands.  Mutex
  27 helpers are run relatively rarely and are not time critical.
  28 Therefore, reliability is preferred over high performance.
  29
  30 Taking a mutex with a helper
  31 ----------------------------
  32
  33 1. Helper is executed with helper-specific arguments
  34
  35 2. Helper attempts to take mutex
  36
  37 3. On success, the helper writes ASCII 0 to standard output
  38
  39 4. Helper stays running, holding mutex, awaiting termination by CTDB
  40
  41 5. When a helper receives SIGTERM it must release any mutex it is
  42    holding and then exit.
  43
  44 Status codes
  45 ------------
  46
  47 CTDB ignores the exit code of a helper.  Instead, CTDB reacts to a
  48 single ASCII character that is sent to it via a helper's standard
  49 output.
  50
  51 Valid status codes are:
  52
  53 0 - The helper took the mutex and is holding it, awaiting termination.
  54
  55 1 - The helper was unable to take the mutex due to contention.
  56
  57 2 - The helper took too long to take the mutex.
  58
  59     Helpers do not need to implement this status code.  CTDB
  60     already implements any required timeout handling.
  61
  62 3 - An unexpected error occurred.
  63
  64 If a 0 status code is sent then it the helper should periodically
  65 check if the (original) parent processes still exists while awaiting
  66 termination.  If the parent process disappears then the helper should
  67 release the mutex and exit.  This avoids stale mutexes.  Note that a
  68 helper should never wait for parent process ID 1!
  69
  70 If a non-0 status code is sent then the helper can exit immediately.
  71 However, if the helper does not exit then it must terminate if it
  72 receives SIGTERM.
  73
  74 Logging
  75 -------
  76
  77 Anything written to standard error by a helper is incorporated into
  78 CTDB's logs.  A helper should generally only output to stderr for
  79 unexpected errors and avoid output to stderr on success or on mutex
  80 contention.