start-stop-daemon/start-stop-daemon.8

   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