From 4a4f808a0f92b9415e8ded69fe8b3203197bb687 Mon Sep 17 00:00:00 2001 From: Roy Marples Date: Mon, 17 Dec 2007 10:14:54 +0000 Subject: Rework the manpages into mdoc format for easier maintainence --- man/start-stop-daemon.8 | 367 +++++++++++++++++------------------------------- 1 file changed, 132 insertions(+), 235 deletions(-) (limited to 'man/start-stop-daemon.8') diff --git a/man/start-stop-daemon.8 b/man/start-stop-daemon.8 index d674a0b..5944068 100644 --- a/man/start-stop-daemon.8 +++ b/man/start-stop-daemon.8 @@ -1,237 +1,134 @@ -.TH "OPENRC" "13" "Nov 2007" "openrc" "openrc" -.SH NAME -start\-stop\-daemon \- start and stop system daemon programs -.SH SYNOPSIS -.B start-stop-daemon -.BR -S | --start -.IR options -.RB [ \-\- ] -.IR arguments -.HP -.B start-stop-daemon -.BR -K | --stop -.IR options -.HP -.B start-stop-daemon -.BR -s | --signal -.IR options -.HP -.B start-stop-daemon -.BR -H | --help -.HP -.B start-stop-daemon -.BR -V | --version -.SH DESCRIPTION -.B start\-stop\-daemon -is used to control the creation and termination of system-level processes. -Using the -.BR --exec ", " --pidfile ", " --user ", and " --name " options," -.B start\-stop\-daemon -can be configured to find existing instances of a running process. - -With -.BR --start , -.B start\-stop\-daemon -checks for the existence of a specified process. -If such a process exists, -.B start\-stop\-daemon -does nothing, and exits with error status 1. -If such a process does not exist, it starts an -instance, using the executable specified by -.BR --exec . -Any arguments given after -.BR -- -on the command line are passed unmodified to the program being -started. -.B start\-stop\-daemon -pauses for a little bit then checks the daemon is still running as badly -written ones like to fork early and then bail on a error in their config. -As such it may be necessary to use the --name parameter if the daemon in -question is not a C program, ie a script. Once started, we store how we -are called in \fBrc\fR if called from an init script. - -With -.BR --stop , -.B start\-stop\-daemon -also checks for the existence of a specified process. -If such a process exists, -.B start\-stop\-daemon -sends it the signal specified by -.BR --signal , -and exits with error status 0. -If such a process does not exist, or there was an error stopping it -.B start\-stop\-daemon -exits with error status 1. If -.BR --test -is specified then we just send the signal and not the schedule. If -.BR --oknodo -is specified then we don't remove the daemon information from -.BR rc. If neither -.BR --test -or -.BR --okndo -are specified then we kill signalling and waiting according to our -schedule specified by -.BR --retry -until we timeout the process(es) exited. If we didn't timeout then -we remove our daemon information from rc. - -With -.BR --signal , -.B start\-stop\-daemon -also checks for the existence of a specified process. -If such a process exists, -.B start\-stop\-daemon -sends it the signal specified and exits with error status 0. -If such a process does not exist, or there was an error stopping it -.B start\-stop\-daemon -exits with error status 1. No futher action is taken - -.SH OPTIONS - -.TP -\fB-x\fP|\fB--exec\fP \fIexecutable\fP -Check for processes that are instances of this executable. -.TP -\fB-p\fP|\fB--pidfile\fP \fIpid-file\fP -Check for processes whose process-id is specified in -.I pid-file. -.TP -\fB-u\fP|\fB--user\fP \fIusername\fP|\fIuid\fP -Check for processes owned by the user specified by -.I username -or -.I uid. -.TP -\fB-n\fP|\fB--name\fP \fIprocess-name\fP -Check for processes with the name -.I process-name -.TP -\fB-s\fP|\fB--signal\fP \fIsignal\fP -With -.BR --stop -, specifies the signal to send to processes being stopped (default SIGTERM). -.TP -\fB-R\fP|\fB--retry\fP \fItimeout\fP|\fIschedule\fP -With -.BR --stop , -specifies that -.B start-stop-daemon -is to check whether the process(es) -do finish. It will check repeatedly whether any matching processes -are running, until none are. If the processes do not exit it will -then take further action as determined by the schedule. - +.\" Copyright 2007 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 Dec 15, 2007 +.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 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 -.I timeout -is specified instead of -.I schedule -then the schedule -.IB signal / timeout -is used, where -.I signal -is the signal specified with -.BR --signal . - -.I schedule -is a list of at least two items separated by slashes -.RB ( / ); -each item may be -.BI - signal-number -or [\fB\-\fP]\fIsignal-name\fP, -which means to send that signal, -or -.IR timeout , -which means to wait that many seconds for processes to -exit, -or -.BR forever , -which means to repeat the rest of the schedule forever if -necessary. - -If the end of the schedule is reached and -.BR forever -is not specified, then -.B start-stop-daemon -exits with error status 2. -If a schedule is specified, then any signal specified -with -.B --signal -is ignored. -.TP -.BR -t | --test -Print actions that would be taken and set appropriate return value, -but take no action. -.TP -.BR -o | --oknodo -Used for sending signals to a running daemon but not expecting it to stop. -In this version you can don't need --oknodo if you don't use --stop either. -.TP -.BR -q | --quiet -Do not print informational messages; only display error messages. -.TP -\fB-c\fP|\fB--chuid\fP \fIusername\fR|\fIuid\fP -Change to this username/uid before starting the process. You can also -specify a group by appending a -.BR : , -then the group or gid in the same way -as you would for the `chown' command (\fIuser\fP\fB:\fP\fIgroup\fP). -When using this option -you must realize that the primary and supplemental groups are set as well, -even if the -.B --group -option is not specified. The -.B --group -option is only for -groups that the user isn't normally a member of (like adding per/process -group membership for generic users like -.BR nobody ). -.TP -\fB-r\fP|\fB--chroot\fP \fIroot\fP -Chdir and chroot to -.I root -before starting the process. Please note that the pidfile is also written -after the chroot. -.TP -.BR -b | --background -Typically used with programs that don't detach on their own. This option -will force -.B start-stop-daemon -to fork before starting the process, and force it into the background. -.TP -\fB-1\fP|\fB--stdout\fP \fIlogfile\fP -Redirect the standard output of the process to \fIlogfile\fP when started with -\fB--background\fP. Must be an absolute pathname, but relative to the -\fIpath\fP optionally given with \fB--chroot\fP. -Hint: The \fIlogfile\fP can also be a named pipe. -.TP -\fB-2\fP|\fB--stderr\fP \fIlogfile\fP -The same thing as \fB--stdout\fP but with the standard error output. -.TP -.BR -N | --nicelevel -This alters the prority of the process before starting it. This can also be set -by the environment variable \fBSSD_NICELEVEL\fR. -.TP -.BR -m | --make-pidfile -Used when starting a program that does not create its own pid file. This -option will make -.B start-stop-daemon -create the file referenced with -.B --pidfile -and place the pid into it just before executing the process. Note, it will -not be removed when stopping the program. -.B NOTE: -This feature may not work in all cases. Most notably when the program -being executed forks from its main process. Because of this it is usually -only useful when combined with the -.B --background +.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 daemon we start or stop. +.It Fl p , -pidfile Ar pidfile +When starting, we expect the daemon to create a valid pidfile within a +reasonable amount of time. When stopping we only stop the pid(s) listed in +the pidfile. +.It Fl n , -name Ar name +For whatever reason, some daemons don't create pidfiles or change their +process name. You can specify name here to be the process name to stop. +You may need to use this for interpreted daemons using languages such as +perl, ruby, shell, etc. +.It Fl u , -user Ar user Ns Op : Ns Ar group +Start the daemon as the user and update $HOME accordingly or stop daemons +owned by the user. You can optionally append a groupname 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 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 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. -.TP -.BR -v | --verbose -Print verbose informational messages. -.TP -.BR -H | --help -Print help information; then exit. -.TP -.BR -V | --version -Print version information; then exit. +.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 SEE ALSO +.Xr chdir 2 , +.Xr chroot 2 , +.Xr nice 2 +.Sh AUTHORS +.An "Roy Marples" Aq roy@marples.name -- cgit v1.2.3