Commit | Line | Data |
---|---|---|
487cc3be VM |
1 | .\" dpkg manual page - start-stop-daemon(8) |
2 | .\" | |
3 | .\" Copyright © 1999 Klee Dienes <klee@mit.edu> | |
4 | .\" Copyright © 1999 Ben Collins <bcollins@debian.org> | |
5 | .\" Copyright © 2000-2001 Wichert Akkerman <wakkerma@debian.org> | |
6 | .\" Copyright © 2002-2003 Adam Heath <doogie@debian.org> | |
7 | .\" Copyright © 2004 Scott James Remnant <keybuk@debian.org> | |
8 | .\" Copyright © 2008-2015 Guillem Jover <guillem@debian.org> | |
9 | .\" | |
10 | .\" This is free software; you can redistribute it and/or modify | |
11 | .\" it under the terms of the GNU General Public License as published by | |
12 | .\" the Free Software Foundation; either version 2 of the License, or | |
13 | .\" (at your option) any later version. | |
14 | .\" | |
15 | .\" This is distributed in the hope that it will be useful, | |
16 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | .\" GNU General Public License for more details. | |
19 | .\" | |
20 | .\" You should have received a copy of the GNU General Public License | |
21 | .\" along with this program. If not, see <https://www.gnu.org/licenses/>. | |
22 | . | |
23 | .TH start\-stop\-daemon 8 "2014-03-26" "Debian Project" "dpkg utilities" | |
24 | .SH NAME | |
25 | start\-stop\-daemon \- start and stop system daemon programs | |
26 | . | |
27 | .SH SYNOPSIS | |
28 | .B start\-stop\-daemon | |
29 | .RI [ option "...] " command | |
30 | . | |
31 | .SH DESCRIPTION | |
32 | .B start\-stop\-daemon | |
33 | is used to control the creation and termination of system-level processes. | |
34 | Using one of the matching options, \fBstart\-stop\-daemon\fP | |
35 | can be configured to find existing instances of a running process. | |
36 | .PP | |
37 | Note: unless | |
38 | .B \-\-pid | |
39 | or | |
40 | .B \-\-pidfile | |
41 | are specified, | |
42 | .B start\-stop\-daemon | |
43 | behaves similar to | |
44 | .BR killall (1). | |
45 | .B start\-stop\-daemon | |
46 | will scan the process table looking for any processes which | |
47 | match the process name, parent pid, uid, and/or gid (if specified). Any | |
48 | matching process will prevent | |
49 | .BR \-\-start | |
50 | from starting the daemon. All matching processes will be sent the TERM | |
51 | signal (or the one specified via \fB\-\-signal\fP or \fB\-\-retry\fP) if | |
52 | .BR \-\-stop | |
53 | is specified. For daemons which have long-lived children | |
54 | which need to live through a | |
55 | .BR \-\-stop , | |
56 | you must specify a pidfile. | |
57 | . | |
58 | .SH COMMANDS | |
59 | .TP | |
60 | .BR \-S ", " \-\-start " [" \-\- "] \fIarguments\fP" | |
61 | Check for the existence of a specified process. | |
62 | If such a process exists, | |
63 | .B start\-stop\-daemon | |
64 | does nothing, and exits with error status 1 (0 if | |
65 | .BR \-\-oknodo | |
66 | is specified). | |
67 | If such a process does not exist, it starts an | |
68 | instance, using either the executable specified by | |
69 | .B \-\-exec | |
70 | or, if specified, by | |
71 | .BR \-\-startas . | |
72 | Any arguments given after | |
73 | .BR \-\- | |
74 | on the command line are passed unmodified to the program being | |
75 | started. | |
76 | .TP | |
77 | .BR \-K ", " \-\-stop | |
78 | Checks for the existence of a specified process. | |
79 | If such a process exists, | |
80 | .B start\-stop\-daemon | |
81 | sends it the signal specified by | |
82 | .BR \-\-signal , | |
83 | and exits with error status 0. | |
84 | If such a process does not exist, | |
85 | .B start\-stop\-daemon | |
86 | exits with error status 1 | |
87 | (0 if | |
88 | .BR \-\-oknodo | |
89 | is specified). If | |
90 | .B \-\-retry | |
91 | is specified, then | |
92 | .B start\-stop\-daemon | |
93 | will check that the process(es) have terminated. | |
94 | .TP | |
95 | .BR \-T ", " \-\-status | |
96 | Check for the existence of a specified process, and returns an exit status | |
97 | code, according to the LSB Init Script Actions (since version 1.16.1). | |
98 | .TP | |
99 | .BR \-H ", " \-\-help | |
100 | Show usage information and exit. | |
101 | .TP | |
102 | .BR \-V ", " \-\-version | |
103 | Show the program version and exit. | |
104 | . | |
105 | .SH OPTIONS | |
106 | .SS Matching options | |
107 | .TP | |
108 | .BR \-\-pid " \fIpid\fP" | |
109 | Check for a process with the specified \fIpid\fP (since version 1.17.6). | |
110 | The \fIpid\fP must be a number greater than 0. | |
111 | .TP | |
112 | .BR \-\-ppid " \fIppid\fP" | |
113 | Check for a process with the specified parent pid \fIppid\fP | |
114 | (since version 1.17.7). | |
115 | The \fIppid\fP must be a number greater than 0. | |
116 | .TP | |
117 | .BR \-p ", " \-\-pidfile " \fIpid-file\fP" | |
118 | Check whether a process has created the file \fIpid-file\fP. Note: using this | |
119 | matching option alone might cause unintended processes to be acted on, if the | |
120 | old process terminated without being able to remove the \fIpid-file\fP. | |
121 | .TP | |
122 | .BR \-x ", " \-\-exec " \fIexecutable\fP" | |
123 | Check for processes that are instances of this \fIexecutable\fP. The | |
124 | \fIexecutable\fP argument should be an absolute pathname. Note: this might | |
125 | not work as intended with interpreted scripts, as the executable will point | |
126 | to the interpreter. Take into account processes running from inside a chroot | |
127 | will also be matched, so other match restrictions might be needed. | |
128 | .TP | |
129 | .BR \-n ", " \-\-name " \fIprocess-name\fP" | |
130 | Check for processes with the name \fIprocess-name\fP. The \fIprocess-name\fP | |
131 | is usually the process filename, but it could have been changed by the | |
132 | process itself. Note: on most systems this information is retrieved from | |
133 | the process comm name from the kernel, which tends to have a relatively | |
134 | short length limit (assuming more than 15 characters is non-portable). | |
135 | .TP | |
136 | .BR \-u ", " \-\-user " \fIusername\fP|\fIuid\fP | |
137 | Check for processes owned by the user specified by \fIusername\fP or | |
138 | \fIuid\fP. Note: using this matching option alone will cause all processes | |
139 | matching the user to be acted on. | |
140 | . | |
141 | .SS Generic options | |
142 | .TP | |
143 | .BR \-g ", " \-\-group " \fIgroup\fP|\fIgid\fP" | |
144 | Change to \fIgroup\fP or \fIgid\fP when starting the process. | |
145 | .TP | |
146 | .BR \-s ", " \-\-signal " \fIsignal\fP" | |
147 | With | |
148 | .BR \-\-stop , | |
149 | specifies the signal to send to processes being stopped (default TERM). | |
150 | .TP | |
151 | .BR \-R ", " \-\-retry " \fItimeout\fP|\fIschedule\fP" | |
152 | With | |
153 | .BR \-\-stop , | |
154 | specifies that | |
155 | .B start\-stop\-daemon | |
156 | is to check whether the process(es) | |
157 | do finish. It will check repeatedly whether any matching processes | |
158 | are running, until none are. If the processes do not exit it will | |
159 | then take further action as determined by the schedule. | |
160 | ||
161 | If | |
162 | .I timeout | |
163 | is specified instead of | |
164 | .IR schedule , | |
165 | then the schedule | |
166 | .IB signal / timeout /KILL/ timeout | |
167 | is used, where | |
168 | .I signal | |
169 | is the signal specified with | |
170 | .BR \-\-signal . | |
171 | ||
172 | .I schedule | |
173 | is a list of at least two items separated by slashes | |
174 | .RB ( / ); | |
175 | each item may be | |
176 | .BI \- signal-number | |
177 | or [\fB\-\fP]\fIsignal-name\fP, | |
178 | which means to send that signal, | |
179 | or | |
180 | .IR timeout , | |
181 | which means to wait that many seconds for processes to | |
182 | exit, | |
183 | or | |
184 | .BR forever , | |
185 | which means to repeat the rest of the schedule forever if | |
186 | necessary. | |
187 | ||
188 | If the end of the schedule is reached and | |
189 | .BR forever | |
190 | is not specified, then | |
191 | .B start\-stop\-daemon | |
192 | exits with error status 2. | |
193 | If a schedule is specified, then any signal specified | |
194 | with | |
195 | .B \-\-signal | |
196 | is ignored. | |
197 | .TP | |
198 | .BR \-a ", " \-\-startas " \fIpathname\fP" | |
199 | With | |
200 | .BR \-\-start , | |
201 | start the process specified by | |
202 | .IR pathname . | |
203 | If not specified, defaults to the argument given to | |
204 | .BR \-\-exec . | |
205 | .TP | |
206 | .BR \-t ", " \-\-test | |
207 | Print actions that would be taken and set appropriate return value, | |
208 | but take no action. | |
209 | .TP | |
210 | .BR \-o ", " \-\-oknodo | |
211 | Return exit status 0 instead of 1 if no actions are (would be) taken. | |
212 | .TP | |
213 | .BR \-q ", " \-\-quiet | |
214 | Do not print informational messages; only display error messages. | |
215 | .TP | |
216 | .BR \-c ", " \-\-chuid " \fIusername\fR|\fIuid\fP[\fB:\fP\fIgroup\fR|\fIgid\fP]" | |
217 | Change to this username/uid before starting the process. You can also | |
218 | specify a group by appending a | |
219 | .BR : , | |
220 | then the group or gid in the same way | |
221 | as you would for the \fBchown\fP(1) command (\fIuser\fP\fB:\fP\fIgroup\fP). | |
222 | If a user is specified without a group, the primary GID for that user is used. | |
223 | When using this option | |
224 | you must realize that the primary and supplemental groups are set as well, | |
225 | even if the | |
226 | .B \-\-group | |
227 | option is not specified. The | |
228 | .B \-\-group | |
229 | option is only for | |
230 | groups that the user isn't normally a member of (like adding per process | |
231 | group membership for generic users like | |
232 | .BR nobody ). | |
233 | .TP | |
234 | .BR \-r ", " \-\-chroot " \fIroot\fP" | |
235 | Chdir and chroot to | |
236 | .I root | |
237 | before starting the process. Please note that the pidfile is also written | |
238 | after the chroot. | |
239 | .TP | |
240 | .BR \-d ", " \-\-chdir " \fIpath\fP" | |
241 | Chdir to | |
242 | .I path | |
243 | before starting the process. This is done after the chroot if the | |
244 | \fB\-r\fP|\fB\-\-chroot\fP option is set. When not specified, | |
245 | .B start\-stop\-daemon | |
246 | will chdir to the root directory before starting the process. | |
247 | .TP | |
248 | .BR \-b ", " \-\-background | |
249 | Typically used with programs that don't detach on their own. This option | |
250 | will force | |
251 | .B start\-stop\-daemon | |
252 | to fork before starting the process, and force it into the background. | |
253 | .B Warning: start\-stop\-daemon | |
254 | cannot check the exit status if the process fails to execute for | |
255 | .B any | |
256 | reason. This is a last resort, and is only meant for programs that either | |
257 | make no sense forking on their own, or where it's not feasible to add the | |
258 | code for them to do this themselves. | |
259 | .TP | |
260 | .BR \-C ", " \-\-no\-close | |
261 | Do not close any file descriptor when forcing the daemon into the background | |
262 | (since version 1.16.5). | |
263 | Used for debugging purposes to see the process output, or to redirect file | |
264 | descriptors to log the process output. | |
265 | Only relevant when using \fB\-\-background\fP. | |
266 | .TP | |
267 | .BR \-N ", " \-\-nicelevel " \fIint\fP" | |
268 | This alters the priority of the process before starting it. | |
269 | .TP | |
270 | .BR \-P ", " \-\-procsched " \fIpolicy\fP\fB:\fP\fIpriority\fP" | |
271 | This alters the process scheduler policy and priority of the process before | |
272 | starting it (since version 1.15.0). | |
273 | The priority can be optionally specified by appending a \fB:\fP | |
274 | followed by the value. The default \fIpriority\fP is 0. The currently | |
275 | supported policy values are \fBother\fP, \fBfifo\fP and \fBrr\fP. | |
276 | .TP | |
277 | .BR \-I ", " \-\-iosched " \fIclass\fP\fB:\fP\fIpriority\fP" | |
278 | This alters the IO scheduler class and priority of the process before starting | |
279 | it (since version 1.15.0). | |
280 | The priority can be optionally specified by appending a \fB:\fP followed | |
281 | by the value. The default \fIpriority\fP is 4, unless \fIclass\fP is \fBidle\fP, | |
282 | then \fIpriority\fP will always be 7. The currently supported values for | |
283 | \fIclass\fP are \fBidle\fP, \fBbest-effort\fP and \fBreal-time\fP. | |
284 | .TP | |
285 | .BR \-k ", " \-\-umask " \fImask\fP" | |
286 | This sets the umask of the process before starting it (since version 1.13.22). | |
287 | .TP | |
288 | .BR \-m ", " \-\-make\-pidfile | |
289 | Used when starting a program that does not create its own pid file. This | |
290 | option will make | |
291 | .B start\-stop\-daemon | |
292 | create the file referenced with | |
293 | .B \-\-pidfile | |
294 | and place the pid into it just before executing the process. Note, the | |
295 | file will only be removed when stopping the program if | |
296 | \fB\-\-remove\-pidfile\fP is used. | |
297 | .B Note: | |
298 | This feature may not work in all cases. Most notably when the program | |
299 | being executed forks from its main process. Because of this, it is usually | |
300 | only useful when combined with the | |
301 | .B \-\-background | |
302 | option. | |
303 | .TP | |
304 | .B \-\-remove\-pidfile | |
305 | Used when stopping a program that does not remove its own pid file | |
306 | (since version 1.17.19). | |
307 | This option will make | |
308 | .B start\-stop\-daemon | |
309 | remove the file referenced with | |
310 | .B \-\-pidfile | |
311 | after terminating the process. | |
312 | .TP | |
313 | .BR \-v ", " \-\-verbose | |
314 | Print verbose informational messages. | |
315 | . | |
316 | .SH EXIT STATUS | |
317 | .TP | |
318 | .B 0 | |
319 | The requested action was performed. If | |
320 | .B \-\-oknodo | |
321 | was specified, it's also possible that nothing had to be done. | |
322 | This can happen when | |
323 | .B \-\-start | |
324 | was specified and a matching process was already running, or when | |
325 | .B \-\-stop | |
326 | was specified and there were no matching processes. | |
327 | .TP | |
328 | .B 1 | |
329 | If | |
330 | .B \-\-oknodo | |
331 | was not specified and nothing was done. | |
332 | .TP | |
333 | .B 2 | |
334 | If | |
335 | .B \-\-stop | |
336 | and | |
337 | .B \-\-retry | |
338 | were specified, but the end of the schedule was reached and the processes were | |
339 | still running. | |
340 | .TP | |
341 | .B 3 | |
342 | Any other error. | |
343 | .PP | |
344 | When using the \fB\-\-status\fP command, the following status codes are | |
345 | returned: | |
346 | .TP | |
347 | .B 0 | |
348 | Program is running. | |
349 | .TP | |
350 | .B 1 | |
351 | Program is not running and the pid file exists. | |
352 | .TP | |
353 | .B 3 | |
354 | Program is not running. | |
355 | .TP | |
356 | .B 4 | |
357 | Unable to determine program status. | |
358 | . | |
359 | .SH EXAMPLE | |
360 | Start the \fBfood\fP daemon, unless one is already running (a process named | |
361 | food, running as user food, with pid in food.pid): | |
362 | .IP | |
363 | .nf | |
364 | start\-stop\-daemon \-\-start \-\-oknodo \-\-user food \-\-name food \\ | |
365 | \-\-pidfile /run/food.pid \-\-startas /usr/sbin/food \\ | |
366 | \-\-chuid food \-\- \-\-daemon | |
367 | .fi | |
368 | .PP | |
369 | Send \fBSIGTERM\fP to \fBfood\fP and wait up to 5 seconds for it to stop: | |
370 | .IP | |
371 | .nf | |
372 | start\-stop\-daemon \-\-stop \-\-oknodo \-\-user food \-\-name food \\ | |
373 | \-\-pidfile /run/food.pid \-\-retry 5 | |
374 | .fi | |
375 | .PP | |
376 | Demonstration of a custom schedule for stopping \fBfood\fP: | |
377 | .IP | |
378 | .nf | |
379 | start\-stop\-daemon \-\-stop \-\-oknodo \-\-user food \-\-name food \\ | |
380 | \-\-pidfile /run/food.pid \-\-retry=TERM/30/KILL/5 | |
381 | .fi |