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 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>: B<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) manual 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 This option might do nothing on some systems,
 375 where POSIX process scheduling is not supported.
 376
 377 =item B<-I>, B<--iosched> I<class>B<:>I<priority>
 378
 379 This alters the IO scheduler class and priority of the process before starting
 380 it (since version 1.15.0).
 381 The priority can be optionally specified by appending a B<:> followed
 382 by the value. The default I<priority> is 4, unless I<class> is B<idle>,
 383 then I<priority> will always be 7. The currently supported values for
 384 I<class> are B<idle>, B<best-effort> and B<real-time>.
 385
 386 This option might do nothing on some systems,
 387 where Linux IO scheduling is not supported.
 388
 389 =item B<-k>, B<--umask> I<mask>
 390
 391 This sets the umask of the process before starting it (since version 1.13.22).
 392
 393 =item B<-m>, B<--make-pidfile>
 394
 395 Used when starting a program that does not create its own pid file. This
 396 option will make
 397 B<start-stop-daemon>
 398 create the file referenced with
 399 B<--pidfile>
 400 and place the pid into it just before executing the process. Note, the
 401 file will only be removed when stopping the program if
 402 B<--remove-pidfile> is used.
 403
 404 B<Note>:
 405 This feature may not work in all cases. Most notably when the program
 406 being executed forks from its main process. Because of this, it is usually
 407 only useful when combined with the
 408 B<--background>
 409 option.
 410
 411 =item B<--remove-pidfile>
 412
 413 Used when stopping a program that does not remove its own pid file
 414 (since version 1.17.19).
 415 This option will make
 416 B<start-stop-daemon>
 417 remove the file referenced with
 418 B<--pidfile>
 419 after terminating the process.
 420
 421 =item B<-v>, B<--verbose>
 422
 423 Print verbose informational messages.
 424
 425 =back
 426
 427 =head1 EXIT STATUS
 428
 429 =over
 430
 431 =item B<0>
 432
 433 The requested action was performed. If
 434 B<--oknodo>
 435 was specified, it's also possible that nothing had to be done.
 436 This can happen when
 437 B<--start>
 438 was specified and a matching process was already running, or when
 439 B<--stop>
 440 was specified and there were no matching processes.
 441
 442 =item B<1>
 443
 444 If
 445 B<--oknodo>
 446 was not specified and nothing was done.
 447
 448 =item B<2>
 449
 450 If
 451 B<--stop>
 452 and
 453 B<--retry>
 454 were specified, but the end of the schedule was reached and the processes were
 455 still running.
 456
 457 =item B<3>
 458
 459 Any other error.
 460
 461 =back
 462
 463 When using the B<--status> command, the following status codes are
 464 returned:
 465
 466 =over
 467
 468 =item B<0>
 469
 470 Program is running.
 471
 472 =item B<1>
 473
 474 Program is not running and the pid file exists.
 475
 476 =item B<3>
 477
 478 Program is not running.
 479
 480 =item B<4>
 481
 482 Unable to determine program status.
 483
 484 =back
 485
 486 =head1 EXAMPLE
 487
 488 Start the B<food> daemon, unless one is already running (a process named
 489 food, running as user food, with pid in food.pid):
 490
 491 =over
 492
 493  start-stop-daemon --start --oknodo --user food --name food \
 494    --pidfile %RUNSTATEDIR%/food.pid --startas /usr/sbin/food \
 495    --chuid food -- --daemon
 496
 497 =back
 498
 499 Send B<SIGTERM> to B<food> and wait up to 5 seconds for it to stop:
 500
 501 =over
 502
 503  start-stop-daemon --stop --oknodo --user food --name food \
 504    --pidfile %RUNSTATEDIR%/food.pid --retry 5
 505
 506 =back
 507
 508 Demonstration of a custom schedule for stopping B<food>:
 509
 510 =over
 511
 512  start-stop-daemon --stop --oknodo --user food --name food \
 513    --pidfile %RUNSTATEDIR%/food.pid --retry=TERM/30/KILL/5
 514
 515 =back