Remove wheel submodule - will re-add later with new URL
[dmon:dmon.git] / dmon.rst
1 ======
2  dmon
3 ======
4
5 -------------------------------
6 Daemonize and monitor processes
7 -------------------------------
8
9 :Author: Adrian Perez <aperez@igalia.com>
10 :Manual section: 8
11
12
13 SYNOPSIS
14 ========
15
16 ``dmon [options] cmd [cmdoptions] [-- logcmd [logcmdoptions]]``
17
18
19 DESCRIPTION
20 ===========
21
22 The ``dmon`` program will launch a program and re-launch it whenever it
23 dies. Optionally, the standard output streams of the programs may be piped
24 into a second program (named *log command*), which will receive the output
25 of the program in its standard input stream. The log command will be also
26 monitored and re-launched when it dies.
27
28
29 USAGE
30 =====
31
32 Command line options:
33
34 -C PATH, --config PATH
35               Read contents from *PATH* as if they were command line options.
36               Those will be parsed after the options picked from the
37               ``DMON_OPTIONS`` environment variable and before the options
38               given in the command line. If given, this option **must** be
39               the first one passed to to ``dmon``.
40
41 -I PATH, --write-info PATH
42               Write status changes of monitored processes to *PATH*, one
43               status message per line. See the `status file format`_ section
44               for details on the format.
45
46 -p PATH, --pid-file PATH
47               Write the PID of the master ``dmon`` process to a file in the
48               specified *PATH*. You can signal the process to interact with
49               it. (See SIGNALS_ below.)
50
51 -i TIME, --interval TIME
52               When execution of the process ends with a successful (zero)
53               exit status, wait for *TIME* seconds before respawning the
54               process instead of doing it immediately. This can be used to
55               make ``dmon`` behave as el-cheapo `cron(8)` replacement. This
56               option cannot be used along with ``-1``.
57
58 -t TIME, --timeout TIME
59               If the process takes longer than *TIME* seconds to complete,
60               terminate it by sending the *TERM*/*CONT* signal combo. Then
61               the process will be respawned again. This is useful to ensure
62               that potentially locking processes which should take less than
63               some known time limit do not hog the computer. Most likely,
64               this flag is useful in conjunction with ``-1``, and with
65               ``-n`` e.g. when using it in a `cron(8)` job.
66
67 -L NUMBER, --load-high NUMBER
68               Enable tracking the system's load average, and suspend the
69               execution of the command process when the system load goes
70               over *NUMBER*. To pause the process, *STOP* signal will be
71               sent to it. You may want to use ``-l`` as well to specify
72               under which load value the process is resumed, otherwise
73               when the system load falls below *NUMBER/2* the process will
74               be resumed.
75
76 -l NUMBER, --load-low NUMBER
77               When using ``-L``, the command process execution will be
78               resumed when the system load falls below *NUMBER*, instead of
79               using the default behavior of resuming the process when the
80               load falls below half the limit specified with ``-L``.
81
82 -E ENVVAR, --environ ENVVAR
83               Manipulates environment variables. Specifying just a variable
84               name (e.g. ``-E foo``) as *ENVVAR* will clear it and remove
85               the variable from the environment. Adding a value will define
86               the variable (e.g. ``-E foo=bar``). This option may be
87               specified multiple times. Environment variables will affect
88               *both* the ``dmon`` and the child process; this is intended
89               behaviour.
90
91 -u UIDGID, --cmd-user UIDGID
92               Executes the command with the credentials of user *UID*,
93               and additional group *GID* specified separated with
94               semicolons. Both user and group identifiers might be given
95               as strings or numerically.
96
97 -U UIDGID, --log-user UIDGID
98               Executes the **log** command with the credentials of user
99               *UID*, and additional group *GID* specified separated with
100               semicolons. Both user and group identifiers might be given
101               as strings or numerically.
102
103 -n, --no-daemon
104               Do not daemonize: ``dmon`` will keep working in foreground,
105               without detaching and without closing its standard input and
106               output streams. This is useful for debugging and, to a limited
107               extent, to run interactive programs.
108
109 -1, --once    Run command only once: if the command exits with a success
110               status (i.e. exit code is zero), then ``dmon`` will exit and
111               stop the logging process. If the program dies due to a signal
112               or with a non-zero exit status, it is respawned. This option
113               tends to be used in conjunction with ``-n``, and cannot be
114               used with ``-i``.
115
116 -e, --stderr-redir
117               Redirect both the standard error and standard output streams
118               to the log command. If not specified, only the standard output
119               is redirected.
120
121 -s, --cmd-sigs
122               Forward signals *CONT*, *ALRM*, *QUIT*, *USR1*, *USR2* and
123               *HUP* to the monitored command when ``dmon`` receives them.
124
125 -S, --log-sigs
126               Forward signals *CONT*, *ALRM*, *QUIT*, *USR1*, *USR2* and
127               *HUP* to the log command when ``dmon`` receives them.
128
129 -r LIMIT, --limit LIMIT
130               Set *LIMIT* for process execution. Limits are specified as
131               ``name=value`` strings, and multiple limits may be set by
132               using ``-r`` multiple times. The available set of limits
133               depends on the current operating system, to get a list
134               ``-r help`` can be used.
135
136 -h, --help    Show a summary of available options.
137
138 Usual log commands include `dlog(8)` and `dslog(8)`, which are part of the
139 ``dmon`` suite. Other log commands like `rotlog(8)` or `multilog(8)` may be
140 used as long as they consume data from standard input and do not detach
141 themsemlves from the controlling process.
142
143 As a convenience, time values passed to ``-i``, ``-t`` and values of limits
144 specified with ``-r`` may be given with the following suffixes:
145
146 - ``m``: Minutes, e.g. ``30m`` means "30 minutes".
147 - ``h``: Hours, e.g. ``4h`` means "4 hours".
148 - ``d``: Days, e.g. ``3d`` means "3 days".
149 - ``w``: Weeks, e.g. ``1w`` means "1 week".
150
151 For size values (bytes) the strings passed to ``-r`` as limits may have the
152 following suffixes:
153
154 - ``k``: Kilobytes.
155 - ``m``: Megabytes.
156 - ``g``: Gigabytes.
157
158
159 SIGNALS
160 =======
161
162 Signals may be used to interact with the monitored processes and ``dmon``
163 itself.
164
165 The ``TERM`` and ``INT`` signals are catched by ``dmon``, and they will
166 make it shut down gracefully: both the main command and the log command
167 will receive a ``TERM`` signal followed by a ``CONT`` and they will be
168 waited for.
169
170 When at least one of ``-s`` or ``-S`` are used, the ``CONT``, ``ALRM``,
171 ``QUIT``, ``USR1``, ``USR2`` and ``HUP`` signals are forwarded to the
172 managed processes. By default, if none of the options are used, those
173 signals are ignored.
174
175
176 EXAMPLES
177 ========
178
179 The following command will supervise a shell which prints a string each
180 fifth second, and the output is logged to a file with timestamps::
181
182   dmon -n sh -c 'while echo "Hello World" ; do sleep 5 ; done' \
183     -- dlog logfile
184
185 In order to turn the previous example into a daemon, we only need to
186 remove the ``-n``. I may be convenient to specify a PID file path::
187
188   dmon -p example.pid \
189     sh -c 'while echo "Hello dmon" ; do sleep 5 ; done' \
190     -- dlog logfile
191
192 The following example launches the `cron(8)` daemon with the logging
193 process running as user and group ``log:wheel``::
194
195   dmon -p /var/run/crond.pid -u log:wheel -e cron -f
196     -- dlog /var/log/cron.log
197
198 This example will run a (probably lengthy) backup process, pausing it when
199 the system load goes above 3.5 and resuming it when the load drops below
200 1.0::
201
202   dmon -1 -n -l 1 -L 3.5 rsync -avz ~/ /backup/homedir
203
204 If you have a PID file, terminating the daemon is an easy task::
205
206   kill $(cat example.pid)
207
208
209 STATUS FILE FORMAT
210 ==================
211
212 When using the ``-I`` *PATH* option, status updates are written to *PATH*,
213 one line per update. The following line formats may be used:
214
215 A process was started by ``dmon``:
216
217   ::
218
219     cmd start <pid>
220     log start <pid>
221
222
223 A process is about to be stopped by ``dmon``:
224
225   ::
226
227     cmd stop <pid>
228     log stop <pid>
229
230
231 A process has exited by its own means, or was terminated by the other means
232 different than ``dmon`` itself (e.g. by the kernel or the user):
233
234   ::
235
236     cmd exit <pid> <status>
237     log exit <pid> <status>
238
239 The ``<status>`` field is numeric, and must be interpreted the same as the
240 *status* argument to the `waitpid(2)` system call. Most of the time this is
241 the expected integer code passed to `exit(2)`, but this may not be true if
242 the process exits forcibly.
243
244
245 A signal is about to be sent to a process:
246
247   ::
248
249     cmd signal <pid> <signal>
250     log signal <pid> <signal>
251
252
253 The main monitored process timed out (when ``-t`` is in effect):
254
255   ::
256
257     cmd timeout <pid>
258
259
260 Process was paused or resumed due to system load constraints (when the
261 ``-l`` and ``-L`` options are in effect):
262
263   ::
264
265     cmd pause <pid>
266     cmd resume <pid>
267
268
269
270 ENVIRONMENT
271 ===========
272
273 Additional options will be picked from the ``DMON_OPTIONS`` environment
274 variable, if defined. Any command line option can be specified this way.
275 Arguments read from the environment variable will be prepended to the ones
276 given in the command line, so they may still be overriden.
277
278
279 SEE ALSO
280 ========
281
282 `dlog(8)`, `dslog(8)`, `rotlog(8)`, `multilog(8)`, `supervise(8)`, `cron(8)`
283
284 http://cr.yp.to/daemontools.html
285