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/Makefile | 2 +- man/rc-status.8 | 92 +++++++----- man/rc-update.8 | 117 ++++++++++----- man/start-stop-daemon.8 | 367 +++++++++++++++++------------------------------- 4 files changed, 272 insertions(+), 306 deletions(-) (limited to 'man') diff --git a/man/Makefile b/man/Makefile index b3f4921..f6c7712 100644 --- a/man/Makefile +++ b/man/Makefile @@ -1,5 +1,5 @@ DIR = /usr/share/man/man8 -CONF = rc-status.8 rc-update.8 start-stop-daemon.8 +INC = rc-status.8 rc-update.8 start-stop-daemon.8 TOPDIR = .. include $(TOPDIR)/default.mk diff --git a/man/rc-status.8 b/man/rc-status.8 index af86e60..732530d 100644 --- a/man/rc-status.8 +++ b/man/rc-status.8 @@ -1,33 +1,61 @@ -.TH "OPENRC" "8" "Nov 2007" "openrc" "openrc" -.SH NAME -rc-status \- show status info about runlevels -.SH SYNOPSIS -\fBrc-status\fR \fI[command [runlevel]]\fR -.SH DESCRIPTION -\fBrc-status\fR gathers and displays information about the status of init -scripts in different runlevels. The default behavior is to show information +.\" 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 RC-STATUS 8 SMM +.Os OpenRC +.Sh NAME +.Nm rc-status +.Nd show status info about runlevels +.Sh SYNOPSIS +.Nm +.Op Fl alsuC +.Op Ar runlevel +.Sh DESCRIPTION +.Nm +gathers and displays information about the status of services +in different runlevels. The default behavior is to show information about the current runlevel, but any runlevel can be quickly examined. -directory. They must also conform to the OpenRC runscript standard. -.SH OPTIONS -.TP -\fB\-\-all (\-a)\fR -Show all runlevels and their services -.TP -\fB\-\-list (\-l)\fR -List all defined runlevels -.TP -\fB\-\-nocolor (\-nc)\fR -Disable color output -.TP -\fB\-\-servicelist (\-s)\fR -Show all services -.TP -\fB\-\-unused (\-u)\fR -Show services not assigned to any runlevel -.TP -\fB[runlevel]\fR -Show information only for the named \fBrunlevel\fR -.SH "SEE ALSO" -.BR rc-update (8) -.SH AUTHORS -Mike Frysinger +.Pp +The options are as follows: +.Bl -tag -width ".Fl test , test string" +.It Fl a , -all +Show all runlevels and their services. +.It Fl l , -list +List all defined runlevels. +.It Fl s , -servicelist +Show all services. +.It Fl u , -unused +Show services not assigned to any runlevel. +.It Fl C , -nocolor +Disable color output. +.It Ar runlevel +Show information only for the named +.Ar runlevel . +.El +.Sh SEE ALSO +.Xr rc 8 , +.Xr rc-update 8 +.Sh AUTHORS +.An "Roy Marples" Aq roy@marples.name diff --git a/man/rc-update.8 b/man/rc-update.8 index b99146e..f4d0e54 100644 --- a/man/rc-update.8 +++ b/man/rc-update.8 @@ -1,39 +1,80 @@ -.TH "OPENRC" "8" "Nov 2007" "openrc" "openrc" -.SH NAME -rc-update \- add and remove init scripts to a runlevel -.SH SYNOPSIS -\fBrc-update\fR \fIadd\fR \fIscript\fR \fI\fR -.br -\fBrc-update\fR \fIdel\fR \fIscript\fR \fI[runlevels]\fR -.br -\fBrc-update\fR \fIshow\fR \fI[\-\-verbose]\fR \fI[runlevels]\fR -.SH DESCRIPTION +.\" 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 RC-UPDATE 8 SMM +.Os OpenRC +.Sh NAME +.Nm rc-update +.Nd add and remove services to and from a runlevel +.Sh SYNOPSIS +.Nm +.Fl a , -add +.Ar service +.Op Ar runlevel ... +.Nm +.Fl d , -delete +.Ar service +.Op Ar runlevel ... +.Nm +.Fl s , -show +.Op Fl v , -verbose +.Op Ar runlevel ... +.Sh DESCRIPTION OpenRC uses named runlevels. Rather than editing some obscure -file or managing a directory of symlinks, \fBrc-update\fR exists to quickly -add or delete init scripts from different runlevels. - -All scripts specified with this utility must reside in the \fI/etc/init.d\fR -directory. They must also conform to the OpenRC runscript standard. -.SH OPTIONS -.TP -\fBadd (\-a)\fR \fIscript\fR \fI\fR -Add the specified \fIinit script\fR to the specified \fIrunlevels\fR. You -must specify at least one runlevel. - -Example: rc-update add net.eth0 default -.TP -\fBdel (\-d)\fR \fIscript\fR \fI[runlevels]\fR -Delete the specified \fIinit script\fR from the specified \fIrunlevels\fR. -If you do not specify the \fIrunlevels\fR from which to delete, the script -will be removed from all exists runlevels. - -Example: rc-update del sysklogd -.TP -\fBshow (\-s)\fR \fI[\-v|\-\-verbose]\fR \fI[runlevels]\fR -Show all enabled scripts and the runlevels they belong to. If you specify -\fIrunlevels\fR to show, then only those will be included in the output. To -view all init scripts, run with the \fI\-\-verbose\fR option. - -Example: rc-update show -.SH "SEE ALSO" -.BR rc-status (8) +file or managing a directory of symlinks, +.Nm +exists to quickly add or delete services to and from from different runlevels. +All services must reside in the +.Pa /etc/init.d +or +.Pa /usr/local/etc/init.d +directories. They must also conform to the OpenRC runscript standard. +.Pp +.Bl -tag -width "Fl a , -delete service" +.It Fl a , -add Ar service +Add the +.Ar service +to the +.Ar runlevel +or the current one if none given. +Services added to the boot runlevel must exist in +.Pa /etc/init.d . +.It Fl d , -delete Ar service +Delete the +.Ar service +from the +.Ar runlevel +or the current one if none given. +.It Fl s , -show +Show all enabled services and the runlevels they belong to. If you specify +runlevels to show, then only those will be included in the output. +.It Fl v , -verbose +Show all services. +.El +.Sh SEE ALSO +.Xr rc 8 , +.Xr rc-status 8 +.Sh AUTHORS +.An "Roy Marples" Aq roy@marples.name 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