212 lines
6.6 KiB
Groff
212 lines
6.6 KiB
Groff
.\" 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.
|
|
.It Fl -capabilities Ar cap-list
|
|
Start the daemon with the listed inheritable, ambient and bounding capabilities.
|
|
The format is the same as in cap_iab(3).
|
|
.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>
|