dmon.8

.\" Man page generated from reStructuredText.
.
.TH DMON 8 "" "" ""
.SH NAME
dmon \- Daemonize and monitor processes
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBdmon [options] cmd [cmdoptions] [\-\- logcmd [logcmdoptions]]\fP
.SH DESCRIPTION
.sp
The \fBdmon\fP program will launch a program and re\-launch it whenever it
dies. Optionally, the standard output streams of the programs may be piped
into a second program (named \fIlog command\fP), which will receive the output
of the program in its standard input stream. The log command will be also
monitored and re\-launched when it dies.
.SH USAGE
.sp
Command line options:
.INDENT 0.0
.TP
.BI \-C \ PATH\fR,\fB \ \-\-config \ PATH
Read contents from \fIPATH\fP as if they were command line options.
Those will be parsed after the options picked from the
\fBDMON_OPTIONS\fP environment variable and before the options
given in the command line. If given, this option \fBmust\fP be
the first one passed to to \fBdmon\fP\&.
.TP
.BI \-I \ PATH\fR,\fB \ \-\-write\-info \ PATH
Write status changes of monitored processes to \fIPATH\fP, one
status message per line. See the \fI\%status file format\fP section
for details on the format.
.TP
.BI \-p \ PATH\fR,\fB \ \-\-pid\-file \ PATH
Write the PID of the master \fBdmon\fP process to a file in the
specified \fIPATH\fP\&. You can signal the process to interact with
it. (See \fI\%SIGNALS\fP below.)
.TP
.BI \-W \ PATH\fR,\fB \ \-\-work\-dir \ PATH
Change to the directory located at \fIPATH\fP and use it as working
directory. Note that all other paths passed to \fBdmon\fP (except
the configuration file) will be interpreted as relative to the
working directory.
.TP
.BI \-i \ TIME\fR,\fB \ \-\-interval \ TIME
When execution of the process ends with a successful (zero)
exit status, wait for \fITIME\fP seconds before respawning the
process instead of doing it immediately. This can be used to
make \fBdmon\fP behave as el\-cheapo \fIcron(8)\fP replacement. This
option cannot be used along with \fB\-1\fP\&.
.TP
.BI \-t \ TIME\fR,\fB \ \-\-timeout \ TIME
If the process takes longer than \fITIME\fP seconds to complete,
terminate it by sending the \fITERM\fP/\fICONT\fP signal combo. Then
the process will be respawned again. This is useful to ensure
that potentially locking processes which should take less than
some known time limit do not hog the computer. Most likely,
this flag is useful in conjunction with \fB\-1\fP, and with
\fB\-n\fP e.g. when using it in a \fIcron(8)\fP job.
.TP
.BI \-L \ NUMBER\fR,\fB \ \-\-load\-high \ NUMBER
Enable tracking the system\(aqs load average, and suspend the
execution of the command process when the system load goes
over \fINUMBER\fP\&. To pause the process, \fISTOP\fP signal will be
sent to it. You may want to use \fB\-l\fP as well to specify
under which load value the process is resumed, otherwise
when the system load falls below \fINUMBER/2\fP the process will
be resumed.
.TP
.BI \-l \ NUMBER\fR,\fB \ \-\-load\-low \ NUMBER
When using \fB\-L\fP, the command process execution will be
resumed when the system load falls below \fINUMBER\fP, instead of
using the default behavior of resuming the process when the
load falls below half the limit specified with \fB\-L\fP\&.
.TP
.BI \-E \ ENVVAR\fR,\fB \ \-\-environ \ ENVVAR
Manipulates environment variables. Specifying just a variable
name (e.g. \fB\-E foo\fP) as \fIENVVAR\fP will clear it and remove
the variable from the environment. Adding a value will define
the variable (e.g. \fB\-E foo=bar\fP). This option may be
specified multiple times. Environment variables will affect
\fIboth\fP the \fBdmon\fP and the child process; this is intended
behaviour.
.TP
.BI \-u \ UIDGID\fR,\fB \ \-\-cmd\-user \ UIDGID
Executes the command with the credentials of user \fIUID\fP,
and additional group \fIGID\fP specified separated with
semicolons. Both user and group identifiers might be given
as strings or numerically.
.TP
.BI \-U \ UIDGID\fR,\fB \ \-\-log\-user \ UIDGID
Executes the \fBlog\fP command with the credentials of user
\fIUID\fP, and additional group \fIGID\fP specified separated with
semicolons. Both user and group identifiers might be given
as strings or numerically.
.TP
.B \-n\fP,\fB  \-\-no\-daemon
Do not daemonize: \fBdmon\fP will keep working in foreground,
without detaching and without closing its standard input and
output streams. This is useful for debugging and, to a limited
extent, to run interactive programs.
.TP
.B \-1\fP,\fB  \-\-once
Run command only once: if the command exits with a success
status (i.e. exit code is zero), then \fBdmon\fP will exit and
stop the logging process. If the program dies due to a signal
or with a non\-zero exit status, it is respawned. This option
tends to be used in conjunction with \fB\-n\fP, and cannot be
used with \fB\-i\fP\&.
.TP
.BI \-m \ COUNT\fR,\fB \ \-\-max\-respawns \ COUNT
Respawn command m number of times. \fBdmon\fP does not check the
exit status on each respawn. For example, if you want the
command to never respawn, set \fB\-m 0\fP\&. After the set number of
respawns have passed \fBdmon\fP will NOT respawn the cmd.
Instead, \fBdmon\fP will exit and stop the logging process.
.TP
.B \-e\fP,\fB  \-\-stderr\-redir
Redirect both the standard error and standard output streams
to the log command. If not specified, only the standard output
is redirected.
.TP
.B \-s\fP,\fB  \-\-cmd\-sigs
Forward signals \fICONT\fP, \fIALRM\fP, \fIQUIT\fP, \fIUSR1\fP, \fIUSR2\fP and
\fIHUP\fP to the monitored command when \fBdmon\fP receives them.
.TP
.B \-S\fP,\fB  \-\-log\-sigs
Forward signals \fICONT\fP, \fIALRM\fP, \fIQUIT\fP, \fIUSR1\fP, \fIUSR2\fP and
\fIHUP\fP to the log command when \fBdmon\fP receives them.
.TP
.BI \-r \ LIMIT\fR,\fB \ \-\-limit \ LIMIT
Set \fILIMIT\fP for process execution. Limits are specified as
\fBname=value\fP strings, and multiple limits may be set by
using \fB\-r\fP multiple times. The available set of limits
depends on the current operating system, to get a list
\fB\-r help\fP can be used.
.TP
.B \-h\fP,\fB  \-\-help
Show a summary of available options.
.UNINDENT
.sp
Usual log commands include \fIdlog(8)\fP and \fIdslog(8)\fP, which are part of the
\fBdmon\fP suite. Other log commands like \fIrotlog(8)\fP or \fImultilog(8)\fP may be
used as long as they consume data from standard input and do not detach
themsemlves from the controlling process.
.sp
As a convenience, time values passed to \fB\-i\fP, \fB\-t\fP and values of limits
specified with \fB\-r\fP may be given with the following suffixes:
.INDENT 0.0
.IP \(bu 2
\fBm\fP: Minutes, e.g. \fB30m\fP means "30 minutes".
.IP \(bu 2
\fBh\fP: Hours, e.g. \fB4h\fP means "4 hours".
.IP \(bu 2
\fBd\fP: Days, e.g. \fB3d\fP means "3 days".
.IP \(bu 2
\fBw\fP: Weeks, e.g. \fB1w\fP means "1 week".
.UNINDENT
.sp
For size values (bytes) the strings passed to \fB\-r\fP as limits may have the
following suffixes:
.INDENT 0.0
.IP \(bu 2
\fBk\fP: Kilobytes.
.IP \(bu 2
\fBm\fP: Megabytes.
.IP \(bu 2
\fBg\fP: Gigabytes.
.UNINDENT
.SH SIGNALS
.sp
Signals may be used to interact with the monitored processes and \fBdmon\fP
itself.
.sp
The \fBTERM\fP and \fBINT\fP signals are catched by \fBdmon\fP, and they will
make it shut down gracefully: both the main command and the log command
will receive a \fBTERM\fP signal followed by a \fBCONT\fP and they will be
waited for.
.sp
When at least one of \fB\-s\fP or \fB\-S\fP are used, the \fBCONT\fP, \fBALRM\fP,
\fBQUIT\fP, \fBUSR1\fP, \fBUSR2\fP and \fBHUP\fP signals are forwarded to the
managed processes. By default, if none of the options are used, those
signals are ignored.
.SH EXAMPLES
.sp
The following command will supervise a shell which prints a string each
fifth second, and the output is logged to a file with timestamps:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dmon \-n sh \-c \(aqwhile echo "Hello World" ; do sleep 5 ; done\(aq \e
  \-\- dlog logfile
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In order to turn the previous example into a daemon, we only need to
remove the \fB\-n\fP\&. I may be convenient to specify a PID file path:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dmon \-p example.pid \e
  sh \-c \(aqwhile echo "Hello dmon" ; do sleep 5 ; done\(aq \e
  \-\- dlog logfile
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following example launches the \fIcron(8)\fP daemon with the logging
process running as user and group \fBlog:wheel\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dmon \-p /var/run/crond.pid \-u log:wheel \-e cron \-f
  \-\- dlog /var/log/cron.log
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This example will run a (probably lengthy) backup process, pausing it when
the system load goes above 3.5 and resuming it when the load drops below
1.0:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dmon \-1 \-n \-l 1 \-L 3.5 rsync \-avz ~/ /backup/homedir
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If you have a PID file, terminating the daemon is an easy task:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
kill $(cat example.pid)
.ft P
.fi
.UNINDENT
.UNINDENT
.SH STATUS FILE FORMAT
.sp
When using the \fB\-I\fP \fIPATH\fP option, status updates are written to \fIPATH\fP,
one line per update. The following line formats may be used:
.sp
A process was started by \fBdmon\fP:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmd start <pid>
log start <pid>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
A process is about to be stopped by \fBdmon\fP:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmd stop <pid>
log stop <pid>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
A process has exited by its own means, or was terminated by the other means
different than \fBdmon\fP itself (e.g. by the kernel or the user):
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmd exit <pid> <status>
log exit <pid> <status>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The \fB<status>\fP field is numeric, and must be interpreted the same as the
\fIstatus\fP argument to the \fIwaitpid(2)\fP system call. Most of the time this is
the expected integer code passed to \fIexit(2)\fP, but this may not be true if
the process exits forcibly.
.sp
A signal is about to be sent to a process:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmd signal <pid> <signal>
log signal <pid> <signal>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The main monitored process timed out (when \fB\-t\fP is in effect):
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmd timeout <pid>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
Process was paused or resumed due to system load constraints (when the
\fB\-l\fP and \fB\-L\fP options are in effect):
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmd pause <pid>
cmd resume <pid>
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH ENVIRONMENT
.sp
Additional options will be picked from the \fBDMON_OPTIONS\fP environment
variable, if defined. Any command line option can be specified this way.
Arguments read from the environment variable will be prepended to the ones
given in the command line, so they may still be overriden.
.sp
If the \fBDMON_LIST_MULTICALL_APPLETS\fP is defined and has a non\-zero value,
the list of applets compiled into a multicall binary will be printed out,
and the program will exit immediately.
.SH SEE ALSO
.sp
\fIdlog(8)\fP, \fIdslog(8)\fP, \fIrotlog(8)\fP, \fImultilog(8)\fP, \fIsupervise(8)\fP, \fIcron(8)\fP
.sp
\fI\%http://cr.yp.to/daemontools.html\fP
.SH AUTHOR
Adrian Perez <aperez@igalia.com>
.\" Generated by docutils manpage writer.
.