185 lines
6.0 KiB
Groff
185 lines
6.0 KiB
Groff
.\" Copyright 2007-2008 Roy Marples
|
|
.\" All rights reserved
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd Jul 08, 2008
|
|
.Dt START-STOP-DAEMON 8 SMM
|
|
.Os OpenRC
|
|
.Sh NAME
|
|
.Nm start-stop-daemon
|
|
.Nd ensures that daemons start and stop
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Fl S , -start
|
|
.Ar daemon
|
|
.Op Fl -
|
|
.Op Ar arguments
|
|
.Nm
|
|
.Fl K , -stop
|
|
.Ar daemon
|
|
.Nm
|
|
.Fl s , -signal
|
|
.Ar signal
|
|
.Ar daemon
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
provides a consistent method of starting, stopping and signalling daemons.
|
|
If neither
|
|
.Fl K , -stop
|
|
nor
|
|
.Fl s , -signal
|
|
are provided, then we assume we are starting the daemon.
|
|
If a daemon cannot background by itself, nor create a pidfile,
|
|
.Nm
|
|
can do it for the daemon in a secure fashion.
|
|
.Nm
|
|
also ensures that a daemon really has started by checking to see if it still
|
|
exists for a short time after it has started. This is because some badly
|
|
written daemons like to daemonize before checking their configuration, doing
|
|
sanity checks, etc. Likewise,
|
|
.Nm
|
|
ensures that a daemon really stops as well, again by using the information
|
|
above to ensure that it's not running.
|
|
.Pp
|
|
If
|
|
.Nm
|
|
is used in an OpenRC service, then OpenRC can in turn check to see if the
|
|
daemon is still running. If not, then the service is marked as crashed.
|
|
.Pp
|
|
Here are the options to specify the daemon and how it should start or stop:
|
|
.Bl -tag -width indent
|
|
.It Fl x , -exec Ar daemon
|
|
The
|
|
.Ar daemon
|
|
we start or stop.
|
|
If this option is not specified, then the first non option argument
|
|
is used.
|
|
If the
|
|
.Ar daemon
|
|
is a script and you are not using the pidfile or process name options,
|
|
then you should replace
|
|
.Ar daemon
|
|
with the interpreter and pass
|
|
.Ar daemon
|
|
as an argument. Below is an example:
|
|
.Pp
|
|
start-stop-daemon perl -- /usr/bin/daemon.pl
|
|
.It Fl p , -pidfile Ar pidfile
|
|
When starting, we expect the daemon to create a valid
|
|
.Ar pidfile
|
|
within a reasonable amount of time. When stopping we only stop the pid(s)
|
|
listed in the
|
|
.Ar pidfile .
|
|
.It Fl n , -name Ar name
|
|
Match the process
|
|
.Ar name
|
|
instead of a pidfile or executable.
|
|
.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 t , -test
|
|
Print the action(s) that would be taken, but don't actually do anything.
|
|
The return value is set as if the command was taken and worked.
|
|
.El
|
|
.Pp
|
|
These options are only used for starting daemons:
|
|
.Bl -tag -width indent
|
|
.It Fl a , -startas Ar name
|
|
Change the process name of the daemon to
|
|
.Ar name .
|
|
This just changes the first argument passed to the daemon.
|
|
.It Fl b , -background
|
|
Force the daemon into the background. Some daemons don't create pidfiles, so a
|
|
good trick is to get the daemon to run in the foreground, and use the this
|
|
option along with
|
|
.Fl m , -make-pidfile
|
|
to create a working pidfile.
|
|
.It Fl d , -chdir Ar path
|
|
chdir to this directory before starting the daemon.
|
|
.It Fl r , -chroot Ar path
|
|
chroot to this directory before starting the daemon. All other paths, such
|
|
as the path to the daemon, chdir and pidfile, should be relative to the chroot.
|
|
.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 m , -make-pidfile
|
|
Saves the pid of the daemon in the file specified by the
|
|
.Fl p , -pidfile
|
|
option. Only useful when used with daemons that run in the foreground and
|
|
forced into the background with the
|
|
.Fl -b , -background
|
|
option.
|
|
.It Fl n , -nice Ar level
|
|
Modifies the scheduling priority of the daemon.
|
|
.It Fl 1 , -stdout Ar logfile
|
|
Redirect the standard output of the process to logfile when started with
|
|
.Fl background .
|
|
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
|
|
.Pp
|
|
These options are only used for stopping daemons:
|
|
.Bl -tag -width indent
|
|
.It Fl R , -retry Ar timeout | Ar signal Ns / Ns Ar timeout
|
|
You can either specify a timeout or a multiple signal/timeout pairs as a
|
|
stopping schedule.
|
|
If not specified then a default value of SIGTERM/5 is
|
|
assumed.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
.Va SSD_NICELEVEL
|
|
can also set the scheduling priority 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 SEE ALSO
|
|
.Xr chdir 2 ,
|
|
.Xr chroot 2 ,
|
|
.Xr getopt 3 ,
|
|
.Xr nice 2 ,
|
|
.Xr rc_find_pids 3
|
|
.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 "Roy Marples" Aq roy@marples.name
|