openrc/man/supervise-daemon.8

.\" Copyright (c) 2007-2015 The OpenRC Authors.
.\" See the Authors file at the top-level directory of this distribution and
.\" https://github.com/OpenRC/openrc/blob/HEAD/AUTHORS
.\"
.\" This file is part of OpenRC. It is subject to the license terms in
.\" the LICENSE file found in the top-level directory of this
.\" distribution and at https://github.com/OpenRC/openrc/blob/HEAD/LICENSE
.\" This file may not be copied, modified, propagated, or distributed
.\"    except according to the terms contained in the LICENSE file.
.\"
.Dd April 27, 2016
.Dt SUPERVISE-DAEMON 8 SMM
.Os OpenRC
.Sh NAME
.Nm supervise-daemon
.Nd starts a daemon and restarts it if it crashes
.Sh SYNOPSIS
.Nm
servicename
.Fl a , -healthcheck-timer
.Ar seconds
.Fl A , -healthcheck-delay
.Ar seconds
.Fl D , -respawn-delay
.Ar seconds
.Fl d , -chdir
.Ar path
.Fl e , -env
.Ar var=value
.Fl g , -group
.Ar group
.Fl I , -ionice
.Ar arg
.Fl k , -umask
.Ar value
.Fl m , -respawn-max
.Ar count
.Fl N , -nicelevel
.Ar level
.Fl -oom-score-adj
.Ar adj
.Fl p , -pidfile
.Ar supervisorpidfile
.Fl P , -respawn-period
.Ar seconds
.Fl R , -retry
.Ar arg
.Fl r , -chroot
.Ar chrootpath
.Fl u , -user
.Ar user
.Fl 1 , -stdout
.Ar logfile
.Fl 2 , -stderr
.Ar logfile
.Fl S , -start
.Ar daemon
.Op Fl -
.Op Ar arguments
.Nm
servicename
.Fl K , -stop
.Ar daemon
.Fl r , -chroot
.Ar chrootpath
.Nm
servicename
.Fl s , -signal
.Ar signal
.Fl r , -chroot
.Ar chrootpath
.Sh DESCRIPTION
.Nm
provides a consistent method of starting, stopping and restarting
daemons. If
.Fl K , -stop
or
.Fl s , -signal
is not provided, then we assume we are starting the daemon.
.Nm
only works with daemons which do not fork. If your daemon has options to
tell it not to fork, it should be configured to not fork.
.Pp
Here are the options to specify the daemon and how it should start or stop:
.Bl -tag -width indent
.It Fl u , -user Ar user Ns Op : Ns Ar group
Start the daemon as the
.Ar user
and update $HOME accordingly or stop daemons
owned by the user. You can optionally append a
.Ar group
name here also.
.It Fl v , -verbose
Print the action(s) that are taken just before doing them.
.El
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl a , -healthcheck-timer Ar seconds
Run the healthcheck() command, possibly followed by the unhealthy()
command every time this number of seconds passes.
.It Fl A , -healthcheck-delay Ar seconds
Wait this long before the first health check.
.It Fl D , -respawn-delay Ar seconds
Wait this number of seconds before restarting a daemon after it crashes.
The default is 0.
.It Fl d , -chdir Ar path
chdir to this directory before starting the daemon.
.It Fl e , -env Ar VAR=VALUE
Set the environment variable VAR to VALUE.
.It Fl g , -group Ar group
Start the daemon as in the group.
.It Fl I , -ionice Ar class Ns Op : Ns Ar data
Modifies the IO scheduling priority of the daemon.
Class can be 0 for none, 1 for real time, 2 for best effort and 3 for idle.
Data can be from 0 to 7 inclusive.
.It Fl k , -umask Ar mode
Set the umask of the daemon.
.It Fl m , -respawn-max Ar count
Sets the maximum number of times a daemon will be respawned. If a daemon
crashes more than this number of times,
.Nm
will give up and exit. The default is 10 and 0 means unlimited.
.Pp
If respawn-period is also set, more than respawn-max crashes must occur
during respawn-period seconds to cause
.Nm
to give up and exit.
.It Fl p , -pidfile Ar supervisorpidfile
Sets a path for the supervisor's pid file. Note that this is not the pid
file of the process that is being supervised.
.It Fl N , -nicelevel Ar level
Modifies the scheduling priority of the daemon.
.It Fl -oom-score-adj Ar adj
Modifies the OOM score adjustment of the daemon.
.It Fl P , -respawn-period Ar seconds
Sets the length of a respawn period. See the
description of --respawn-max for more information.
.It Fl R , -retry Ar timeout | Ar signal Ns / Ns Ar timeout
The retry specification can be either a timeout in seconds or multiple
signal/timeout pairs (like SIGTERM/5).
If this option is not given, the default is SIGTERM/5.
.It Fl r , -chroot Ar path
chroot to this directory before starting the daemon. All other paths, such
as the path to the daemon and chdir should be relative to the chroot.
.It Fl  , -signal Ar signal
Instruct a supervisor to signal the process it is supervising. The
process to communicate with is determined by the name of the service
taken from the RC_SVCNAME environment variable.
.It Fl u , -user Ar user
Start the daemon as the specified user.
.It Fl 1 , -stdout Ar logfile
Redirect the standard output of the process to logfile.
Must be an absolute pathname, but relative to the path optionally given with
.Fl r , -chroot .
The logfile can also be a named pipe.
.It Fl 2 , -stderr Ar logfile
The same thing as
.Fl 1 , -stdout
but with the standard error output.
.El
.Sh ENVIRONMENT
.Va SSD_IONICELEVEL
can also set the IO scheduling priority of the daemon, but the command line
option takes precedence.
.Pp
.Va SSD_NICELEVEL
can also set the scheduling priority of the daemon, but the command line
option takes precedence.
.Pp
.Va SSD_OOM_SCORE_ADJ
can also set the OOM score adjustment of the daemon, but the command line
option takes precedence.
.Sh NOTE
.Nm
uses
.Xr getopt 3
to parse its options, which allows it to accept the `--' option which will
cause it to stop processing options at that point. Any subsequent arguments
are passed as arguments to the daemon to start and used when finding a daemon
to stop or signal.
.Sh NOTE
If respawn-delay, respawn-max and respawn-period are not set correctly,
it is possible to trigger a situation in which the supervisor will
infinitely try to respawn a daemon. To avoid this, if you change the
values of --respawn-delay, --respawn-max or --respawn-period, always
make sure the settings mmake sense. For example, a respawn period of 5
seconds with a respawn max of 10 and a respawn delay of 1 second leads
to infinite respawning since there can never be 10 respawns within 5
seconds.
.Sh NOTE
Invoking supervise-daemon requires both the RC_SVCNAME  environment
variable to be set and the name of the service as the first argument on
the command line, so it is best to invoke it inside a service script
rather than manually.
.Sh SEE ALSO
.Xr chdir 2 ,
.Xr chroot 2 ,
.Xr getopt 3 ,
.Xr nice 2 ,
.Sh HISTORY
.Nm
first appeared in Debian.
.Pp
This is a complete re-implementation with the process finding code in the
OpenRC library (librc, -lrc) so other programs can make use of it.
.Sh AUTHORS
.An William Hubbs <w.d.hubbs@gmail.com>