| 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 |