pyldb: avoid segfault when adding an element with no name
[vlendec/samba-autobuild/.git] / 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.