1 .\" Man page generated from reStructeredText.
5 dmon \- Daemonize and monitor processes
7 .nr rst2man-indent-level 0
11 level \\n[rst2man-indent-level]
12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
19 .\" .rstReportMargin pre:
21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
22 . nr rst2man-indent-level +1
23 .\" .rstReportMargin post:
27 .\" indent \\n[an-margin]
28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .nr rst2man-indent-level -1
30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
35 \fBdmon [options] cmd [cmdoptions] [\-\- logcmd [logcmdoptions]]\fP
38 The \fBdmon\fP program will launch a program and re\-launch it whenever it
39 dies. Optionally, the standard output streams of the programs may be piped
40 into a second program (named \fIlog command\fP), which will receive the output
41 of the program in its standard input stream. The log command will be also
42 monitored and re\-launched when it dies.
48 .BI \-C \ PATH, \ \-\-config \ PATH
49 Read contents from \fIPATH\fP as if they were command line options.
50 Those will be parsed after the options picked from the
51 \fBDMON_OPTIONS\fP environment variable and before the options
52 given in the command line. If given, this option \fBmust\fP be
53 the first one passed to to \fBdmon\fP.
55 .BI \-I \ PATH, \ \-\-write\-info \ PATH
56 Write status changes of monitored processes to \fIPATH\fP, one
57 status message per line. See the \fI\%status file format\fP section
58 for details on the format.
60 .BI \-p \ PATH, \ \-\-pid\-file \ PATH
61 Write the PID of the master \fBdmon\fP process to a file in the
62 specified \fIPATH\fP. You can signal the process to interact with
63 it. (See \fI\%SIGNALS\fP below.)
65 .BI \-i \ TIME, \ \-\-interval \ TIME
66 When execution of the process ends with a successful (zero)
67 exit status, wait for \fITIME\fP seconds before respawning the
68 process instead of doing it immediately. This can be used to
69 make \fBdmon\fP behave as el\-cheapo \fIcron(8)\fP replacement. This
70 option cannot be used along with \fB\-1\fP.
72 .BI \-t \ TIME, \ \-\-timeout \ TIME
73 If the process takes longer than \fITIME\fP seconds to complete,
74 terminate it by sending the \fITERM\fP/\fICONT\fP signal combo. Then
75 the process will be respawned again. This is useful to ensure
76 that potentially locking processes which should take less than
77 some known time limit do not hog the computer. Most likely,
78 this flag is useful in conjunction with \fB\-1\fP, and with
79 \fB\-n\fP e.g. when using it in a \fIcron(8)\fP job.
81 .BI \-L \ NUMBER, \ \-\-load\-high \ NUMBER
82 Enable tracking the system\(aqs load average, and suspend the
83 execution of the command process when the system load goes
84 over \fINUMBER\fP. To pause the process, \fISTOP\fP signal will be
85 sent to it. You may want to use \fB\-l\fP as well to specify
86 under which load value the process is resumed, otherwise
87 when the system load falls below \fINUMBER/2\fP the process will
90 .BI \-l \ NUMBER, \ \-\-load\-low \ NUMBER
91 When using \fB\-L\fP, the command process execution will be
92 resumed when the system load falls below \fINUMBER\fP, instead of
93 using the default behavior of resuming the process when the
94 load falls below half the limit specified with \fB\-L\fP.
96 .BI \-E \ ENVVAR, \ \-\-environ \ ENVVAR
97 Manipulates environment variables. Specifying just a variable
98 name (e.g. \fB\-E foo\fP) as \fIENVVAR\fP will clear it and remove
99 the variable from the environment. Adding a value will define
100 the variable (e.g. \fB\-E foo=bar\fP). This option may be
101 specified multiple times. Environment variables will affect
102 \fIboth\fP the \fBdmon\fP and the child process; this is intended
105 .BI \-u \ UIDGID, \ \-\-cmd\-user \ UIDGID
106 Executes the command with the credentials of user \fIUID\fP,
107 and additional group \fIGID\fP specified separated with
108 semicolons. Both user and group identifiers might be given
109 as strings or numerically.
111 .BI \-U \ UIDGID, \ \-\-log\-user \ UIDGID
112 Executes the \fBlog\fP command with the credentials of user
113 \fIUID\fP, and additional group \fIGID\fP specified separated with
114 semicolons. Both user and group identifiers might be given
115 as strings or numerically.
117 .B \-n, \-\-no\-daemon
118 Do not daemonize: \fBdmon\fP will keep working in foreground,
119 without detaching and without closing its standard input and
120 output streams. This is useful for debugging and, to a limited
121 extent, to run interactive programs.
124 Run command only once: if the command exits with a success
125 status (i.e. exit code is zero), then \fBdmon\fP will exit and
126 stop the logging process. If the program dies due to a signal
127 or with a non\-zero exit status, it is respawned. This option
128 tends to be used in conjunction with \fB\-n\fP, and cannot be
131 .B \-e, \-\-stderr\-redir
132 Redirect both the standard error and standard output streams
133 to the log command. If not specified, only the standard output
136 .B \-s, \-\-cmd\-sigs
137 Forward signals \fICONT\fP, \fIALRM\fP, \fIQUIT\fP, \fIUSR1\fP, \fIUSR2\fP and
138 \fIHUP\fP to the monitored command when \fBdmon\fP receives them.
140 .B \-S, \-\-log\-sigs
141 Forward signals \fICONT\fP, \fIALRM\fP, \fIQUIT\fP, \fIUSR1\fP, \fIUSR2\fP and
142 \fIHUP\fP to the log command when \fBdmon\fP receives them.
144 .BI \-r \ LIMIT, \ \-\-limit \ LIMIT
145 Set \fILIMIT\fP for process execution. Limits are specified as
146 \fBname=value\fP strings, and multiple limits may be set by
147 using \fB\-r\fP multiple times. The available set of limits
148 depends on the current operating system, to get a list
149 \fB\-r help\fP can be used.
152 Show a summary of available options.
155 Usual log commands include \fIdlog(8)\fP and \fIdslog(8)\fP, which are part of the
156 \fBdmon\fP suite. Other log commands like \fIrotlog(8)\fP or \fImultilog(8)\fP may be
157 used as long as they consume data from standard input and do not detach
158 themsemlves from the controlling process.
160 As a convenience, time values passed to \fB\-i\fP, \fB\-t\fP and values of limits
161 specified with \fB\-r\fP may be given with the following suffixes:
164 \fBm\fP: Minutes, e.g. \fB30m\fP means "30 minutes".
166 \fBh\fP: Hours, e.g. \fB4h\fP means "4 hours".
168 \fBd\fP: Days, e.g. \fB3d\fP means "3 days".
170 \fBw\fP: Weeks, e.g. \fB1w\fP means "1 week".
173 For size values (bytes) the strings passed to \fB\-r\fP as limits may have the
185 Signals may be used to interact with the monitored processes and \fBdmon\fP
188 The \fBTERM\fP and \fBINT\fP signals are catched by \fBdmon\fP, and they will
189 make it shut down gracefully: both the main command and the log command
190 will receive a \fBTERM\fP signal followed by a \fBCONT\fP and they will be
193 When at least one of \fB\-s\fP or \fB\-S\fP are used, the \fBCONT\fP, \fBALRM\fP,
194 \fBQUIT\fP, \fBUSR1\fP, \fBUSR2\fP and \fBHUP\fP signals are forwarded to the
195 managed processes. By default, if none of the options are used, those
199 The following command will supervise a shell which prints a string each
200 fifth second, and the output is logged to a file with timestamps:
204 dmon \-n sh \-c \(aqwhile echo "Hello World" ; do sleep 5 ; done\(aq \e
209 In order to turn the previous example into a daemon, we only need to
210 remove the \fB\-n\fP. I may be convenient to specify a PID file path:
214 dmon \-p example.pid \e
215 sh \-c \(aqwhile echo "Hello dmon" ; do sleep 5 ; done\(aq \e
220 The following example launches the \fIcron(8)\fP daemon with the logging
221 process running as user and group \fBlog:wheel\fP:
225 dmon \-p /var/run/crond.pid \-u log:wheel \-e cron \-f
226 \-\- dlog /var/log/cron.log
230 This example will run a (probably lengthy) backup process, pausing it when
231 the system load goes above 3.5 and resuming it when the load drops below
236 dmon \-1 \-n \-l 1 \-L 3.5 rsync \-avz ~/ /backup/homedir
240 If you have a PID file, terminating the daemon is an easy task:
244 kill $(cat example.pid)
247 .SH STATUS FILE FORMAT
249 When using the \fB\-I\fP \fIPATH\fP option, status updates are written to \fIPATH\fP,
250 one line per update. The following line formats may be used:
252 A process was started by \fBdmon\fP:
265 A process is about to be stopped by \fBdmon\fP:
278 A process has exited by its own means, or was terminated by the other means
279 different than \fBdmon\fP itself (e.g. by the kernel or the user):
285 cmd exit <pid> <status>
286 log exit <pid> <status>
292 The \fB<status>\fP field is numeric, and must be interpreted the same as the
293 \fIstatus\fP argument to the \fIwaitpid(2)\fP system call. Most of the time this is
294 the expected integer code passed to \fIexit(2)\fP, but this may not be true if
295 the process exits forcibly.
297 A signal is about to be sent to a process:
303 cmd signal <pid> <signal>
304 log signal <pid> <signal>
310 The main monitored process timed out (when \fB\-t\fP is in effect):
322 Process was paused or resumed due to system load constraints (when the
323 \fB\-l\fP and \fB\-L\fP options are in effect):
337 Additional options will be picked from the \fBDMON_OPTIONS\fP environment
338 variable, if defined. Any command line option can be specified this way.
339 Arguments read from the environment variable will be prepended to the ones
340 given in the command line, so they may still be overriden.
343 \fIdlog(8)\fP, \fIdslog(8)\fP, \fIrotlog(8)\fP, \fImultilog(8)\fP, \fIsupervise(8)\fP, \fIcron(8)\fP
345 \fI\%http://cr.yp.to/daemontools.html\fP
347 Adrian Perez <aperez@igalia.com>
348 .\" Generated by docutils manpage writer.
projects / dmon:dmon.git / blob