start-stop-daemon.pod (13494B)
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-2016, 2018 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 =encoding utf8 24 25 =head1 NAME 26 27 start-stop-daemon - start and stop system daemon programs 28 29 =head1 SYNOPSIS 30 31 B<start-stop-daemon> 32 [I<option>...] I<command> 33 34 =head1 DESCRIPTION 35 36 B<start-stop-daemon> 37 is used to control the creation and termination of system-level processes. 38 Using one of the matching options, B<start-stop-daemon> 39 can be configured to find existing instances of a running process. 40 41 B<Note:> Unless 42 B<--pid> 43 or 44 B<--pidfile> 45 are specified, 46 B<start-stop-daemon> 47 behaves similar to 48 B<killall>(1). 49 B<start-stop-daemon> 50 will scan the process table looking for any processes which 51 match the process name, parent pid, uid, and/or gid (if specified). Any 52 matching process will prevent 53 B<--start> 54 from starting the daemon. All matching processes will be sent the TERM 55 signal (or the one specified via B<--signal> or B<--retry>) if 56 B<--stop> 57 is specified. For daemons which have long-lived children 58 which need to live through a 59 B<--stop>, 60 you must specify a pidfile. 61 62 =head1 COMMANDS 63 64 =over 65 66 =item B<-S>, B<--start> [B<-->] I<arguments> 67 68 Check for the existence of a specified process. 69 If such a process exists, 70 B<start-stop-daemon> 71 does nothing, and exits with error status 1 (0 if 72 B<--oknodo> 73 is specified). 74 If such a process does not exist, it starts an 75 instance, using either the executable specified by 76 B<--exec> 77 or, if specified, by 78 B<--startas>. 79 Any arguments given after 80 B<--> 81 on the command line are passed unmodified to the program being 82 started. 83 84 =item B<-K>, B<--stop> 85 86 Checks for the existence of a specified process. 87 If such a process exists, 88 B<start-stop-daemon> 89 sends it the signal specified by 90 B<--signal>, 91 and exits with error status 0. 92 If such a process does not exist, 93 B<start-stop-daemon> 94 exits with error status 1 95 (0 if 96 B<--oknodo> 97 is specified). If 98 B<--retry> 99 is specified, then 100 B<start-stop-daemon> 101 will check that the process(es) have terminated. 102 103 =item B<-T>, B<--status> 104 105 Check for the existence of a specified process, and returns an exit status 106 code, according to the LSB Init Script Actions (since version 1.16.1). 107 108 =item B<-H>, B<--help> 109 110 Show usage information and exit. 111 112 =item B<-V>, B<--version> 113 114 Show the program version and exit. 115 116 =back 117 118 =head1 OPTIONS 119 120 =head2 Matching options 121 122 =over 123 124 =item B<--pid> I<pid> 125 126 Check for a process with the specified I<pid> (since version 1.17.6). 127 The I<pid> must be a number greater than 0. 128 129 =item B<--ppid> I<ppid> 130 131 Check for a process with the specified parent pid I<ppid> 132 (since version 1.17.7). 133 The I<ppid> must be a number greater than 0. 134 135 =item B<-p>, B<--pidfile> I<pidfile> 136 137 Check whether a process has created the file I<pidfile>. 138 139 B<Note:> Using this matching option alone might cause unintended processes to 140 be acted on, if the old process terminated without being able to remove the 141 I<pidfile>. 142 143 B<Warning:> Using this match option with a world-writable pidfile or using 144 it alone with a daemon that writes the pidfile as an unprivileged (non-root) 145 user will be refused with an error (since version 1.19.3) as this is a 146 security risk, because either any user can write to it, or if the daemon 147 gets compromised, the contents of the pidfile cannot be trusted, and then 148 a privileged runner (such as an init script executed as root) would end up 149 acting on any system process. 150 Using I</dev/null> is exempt from these checks. 151 152 =item B<-x>, B<--exec> I<executable> 153 154 Check for processes that are instances of this I<executable>. The 155 I<executable> argument should be an absolute pathname. 156 157 B<Note:> This might 158 not work as intended with interpreted scripts, as the executable will point 159 to the interpreter. Take into account processes running from inside a chroot 160 will also be matched, so other match restrictions might be needed. 161 162 =item B<-n>, B<--name> I<process-name> 163 164 Check for processes with the name I<process-name>. The I<process-name> 165 is usually the process filename, but it could have been changed by the 166 process itself. 167 168 B<Note:> On most systems this information is retrieved from 169 the process comm name from the kernel, which tends to have a relatively 170 short length limit (assuming more than 15 characters is non-portable). 171 172 =item B<-u>, B<--user> I<username>|I<uid> 173 174 Check for processes owned by the user specified by I<username> or 175 I<uid>. 176 177 B<Note:> Using this matching option alone will cause all processes 178 matching the user to be acted on. 179 180 =back 181 182 =head2 Generic options 183 184 =over 185 186 =item B<-g>, B<--group> I<group>|I<gid> 187 188 Change to I<group> or I<gid> when starting the process. 189 190 =item B<-s>, B<--signal> I<signal> 191 192 With 193 B<--stop>, 194 specifies the signal to send to processes being stopped (default TERM). 195 196 =item B<-R>, B<--retry> I<timeout>|I<schedule> 197 198 With 199 B<--stop>, 200 specifies that 201 B<start-stop-daemon> 202 is to check whether the process(es) 203 do finish. It will check repeatedly whether any matching processes 204 are running, until none are. If the processes do not exit it will 205 then take further action as determined by the schedule. 206 207 If 208 I<timeout> 209 is specified instead of 210 I<schedule>, 211 then the schedule 212 I<signal>B</>I<timeout>B</KILL/>I<timeout> 213 is used, where 214 I<signal> 215 is the signal specified with 216 B<--signal>. 217 218 I<schedule> 219 is a list of at least two items separated by slashes 220 (B</>); 221 each item may be 222 B<->I<signal-number> 223 or [B<->]I<signal-name>, 224 which means to send that signal, 225 or 226 I<timeout>, 227 which means to wait that many seconds for processes to 228 exit, 229 or 230 B<forever>, 231 which means to repeat the rest of the schedule forever if 232 necessary. 233 234 If the end of the schedule is reached and 235 B<forever> 236 is not specified, then 237 B<start-stop-daemon> 238 exits with error status 2. 239 If a schedule is specified, then any signal specified 240 with 241 B<--signal> 242 is ignored. 243 244 =item B<-a>, B<--startas> I<pathname> 245 246 With 247 B<--start>, 248 start the process specified by 249 I<pathname>. 250 If not specified, defaults to the argument given to 251 B<--exec>. 252 253 =item B<-t>, B<--test> 254 255 Print actions that would be taken and set appropriate return value, 256 but take no action. 257 258 =item B<-o>, B<--oknodo> 259 260 Return exit status 0 instead of 1 if no actions are (would be) taken. 261 262 =item B<-q>, B<--quiet> 263 264 Do not print informational messages; only display error messages. 265 266 =item B<-c>, B<--chuid> I<username>|I<uid>[B<:>I<group>|I<gid>] 267 268 Change to this username/uid before starting the process. You can also 269 specify a group by appending a 270 B<:>, 271 then the group or gid in the same way 272 as you would for the B<chown>(1) command (I<user>B<:>I<group>). 273 If a user is specified without a group, the primary GID for that user is used. 274 When using this option 275 you must realize that the primary and supplemental groups are set as well, 276 even if the 277 B<--group> 278 option is not specified. The 279 B<--group> 280 option is only for 281 groups that the user isn't normally a member of (like adding per process 282 group membership for generic users like 283 B<nobody>). 284 285 =item B<-r>, B<--chroot> I<root> 286 287 Change directory and chroot to 288 I<root> 289 before starting the process. Please note that the pidfile is also written 290 after the chroot. 291 292 =item B<-d>, B<--chdir> I<path> 293 294 Change directory to 295 I<path> 296 before starting the process. This is done after the chroot if the 297 B<-r>|B<--chroot> option is set. When not specified, 298 B<start-stop-daemon> 299 will change directory to the root directory before starting the process. 300 301 =item B<-b>, B<--background> 302 303 Typically used with programs that don't detach on their own. This option 304 will force 305 B<start-stop-daemon> 306 to fork before starting the process, and force it into the background. 307 308 B<Warning: start-stop-daemon> 309 cannot check the exit status if the process fails to execute for 310 B<any> 311 reason. This is a last resort, and is only meant for programs that either 312 make no sense forking on their own, or where it's not feasible to add the 313 code for them to do this themselves. 314 315 =item B<--notify-await> 316 317 Wait for the background process to send a readiness notification before 318 considering the service started (since version 1.19.3). 319 This implements parts of the systemd readiness protocol, as specified 320 in the B<sd_notify>(3) man page. 321 The following variables are supported: 322 323 =over 324 325 =item B<READY=1> 326 327 The program is ready to give service, so we can exit safely. 328 329 =item B<EXTEND_TIMEOUT_USEC=>I<number> 330 331 The program requests to extend the timeout by I<number> microseconds. 332 This will reset the current timeout to the specified value. 333 334 =item B<ERRNO=>I<number> 335 336 The program is exiting with an error. 337 Do the same and print the user-friendly string for the B<errno> value. 338 339 =back 340 341 =item B<--notify-timeout> I<timeout> 342 343 Set a timeout for the B<--notify-await> option (since version 1.19.3). 344 When the timeout is reached, B<start-stop-daemon> will exit with an 345 error code, and no readiness notification will be awaited. 346 The default is B<60> seconds. 347 348 =item B<-C>, B<--no-close> 349 350 Do not close any file descriptor when forcing the daemon into the background 351 (since version 1.16.5). 352 Used for debugging purposes to see the process output, or to redirect file 353 descriptors to log the process output. 354 Only relevant when using B<--background>. 355 356 =item B<-O>, B<--output> I<pathname> 357 358 Redirect B<stdout> and B<stderr> to I<pathname> when forcing the daemon into 359 the background (since version 1.20.6). 360 Only relevant when using B<--background>. 361 362 =item B<-N>, B<--nicelevel> I<int> 363 364 This alters the priority of the process before starting it. 365 366 =item B<-P>, B<--procsched> I<policy>B<:>I<priority> 367 368 This alters the process scheduler policy and priority of the process before 369 starting it (since version 1.15.0). 370 The priority can be optionally specified by appending a B<:> 371 followed by the value. The default I<priority> is 0. The currently 372 supported policy values are B<other>, B<fifo> and B<rr>. 373 374 =item B<-I>, B<--iosched> I<class>B<:>I<priority> 375 376 This alters the IO scheduler class and priority of the process before starting 377 it (since version 1.15.0). 378 The priority can be optionally specified by appending a B<:> followed 379 by the value. The default I<priority> is 4, unless I<class> is B<idle>, 380 then I<priority> will always be 7. The currently supported values for 381 I<class> are B<idle>, B<best-effort> and B<real-time>. 382 383 =item B<-k>, B<--umask> I<mask> 384 385 This sets the umask of the process before starting it (since version 1.13.22). 386 387 =item B<-m>, B<--make-pidfile> 388 389 Used when starting a program that does not create its own pid file. This 390 option will make 391 B<start-stop-daemon> 392 create the file referenced with 393 B<--pidfile> 394 and place the pid into it just before executing the process. Note, the 395 file will only be removed when stopping the program if 396 B<--remove-pidfile> is used. 397 398 B<Note:> 399 This feature may not work in all cases. Most notably when the program 400 being executed forks from its main process. Because of this, it is usually 401 only useful when combined with the 402 B<--background> 403 option. 404 405 =item B<--remove-pidfile> 406 407 Used when stopping a program that does not remove its own pid file 408 (since version 1.17.19). 409 This option will make 410 B<start-stop-daemon> 411 remove the file referenced with 412 B<--pidfile> 413 after terminating the process. 414 415 =item B<-v>, B<--verbose> 416 417 Print verbose informational messages. 418 419 =back 420 421 =head1 EXIT STATUS 422 423 =over 424 425 =item B<0> 426 427 The requested action was performed. If 428 B<--oknodo> 429 was specified, it's also possible that nothing had to be done. 430 This can happen when 431 B<--start> 432 was specified and a matching process was already running, or when 433 B<--stop> 434 was specified and there were no matching processes. 435 436 =item B<1> 437 438 If 439 B<--oknodo> 440 was not specified and nothing was done. 441 442 =item B<2> 443 444 If 445 B<--stop> 446 and 447 B<--retry> 448 were specified, but the end of the schedule was reached and the processes were 449 still running. 450 451 =item B<3> 452 453 Any other error. 454 455 =back 456 457 When using the B<--status> command, the following status codes are 458 returned: 459 460 =over 461 462 =item B<0> 463 464 Program is running. 465 466 =item B<1> 467 468 Program is not running and the pid file exists. 469 470 =item B<3> 471 472 Program is not running. 473 474 =item B<4> 475 476 Unable to determine program status. 477 478 =back 479 480 =head1 EXAMPLE 481 482 Start the B<food> daemon, unless one is already running (a process named 483 food, running as user food, with pid in food.pid): 484 485 =over 486 487 start-stop-daemon --start --oknodo --user food --name food \ 488 --pidfile /run/food.pid --startas /usr/sbin/food \ 489 --chuid food -- --daemon 490 491 =back 492 493 Send B<SIGTERM> to B<food> and wait up to 5 seconds for it to stop: 494 495 =over 496 497 start-stop-daemon --stop --oknodo --user food --name food \ 498 --pidfile /run/food.pid --retry 5 499 500 =back 501 502 Demonstration of a custom schedule for stopping B<food>: 503 504 =over 505 506 start-stop-daemon --stop --oknodo --user food --name food \ 507 --pidfile /run/food.pid --retry=TERM/30/KILL/5 508 509 =back