man/start-stop-daemon.pod

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