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