aboutsummaryrefslogtreecommitdiff
path: root/man/start-stop-daemon.8
blob: a4df24f1b2fb9536e0e043641f3a15fa4f6572cf (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
.\" 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 August 20, 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 k , -umask Ar mode
Set the umask of the daemon.
.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