start-stop-daemon(8)

📦
version 1.23.7ubuntu2 · 17 versions
, in ubuntu stonking

✨ start-stop-daemon(8) — the dpkg suite's little process-wrangler ✨

okay bestie, gather round, because this one is literally the backstage crew of your whole system 💅 it lives in the dpkg suite, and it's the thing that starts your daemons up and shuts them down. no cap.

🎀 NAME 🎀

start-stop-daemon — start and stop system daemon programs

like, that's the whole job. it starts them. it stops them. iconic behaviour, honestly 🫶

🌸 SYNOPSIS 🌸

start-stop-daemon [option...] command

that's it, that's the shape of it: a pile of options, then one command. make it make sense and you're golden ✨

💖 DESCRIPTION 💖

so start-stop-daemon is the girl who controls the creation and termination of system-level processes. that's her whole thing. and by using one of the matching options, she can be configured to find existing instances of a running process — like, she can go "oh, is that little guy already running? hold on, let me look" 🔍

Note: unless you pass --pid or --pidfile, start-stop-daemon behaves similar to killall(1).

okay so here's what that actually means, because it matters:

  • start-stop-daemon will scan the process table looking for any processes which match the process name, parent pid, uid, and/or gid (if specified 😌).
  • Any matching process will prevent --start from starting the daemon. so no doubling up, she's not doing that today 💀
  • All matching processes will be sent the TERM signal (or the one you specified via --signal or --retry) if --stop is specified.
  • and this one is important: for daemons which have long-lived children which need to live through a --stop, you must specify a pidfile. like, must. no shortcuts. periodt 👑

👑 COMMANDS 👑

pick your fighter. one of these goes at the end of your option pile 🎀

  • -S, --start [--] arguments — Checks for the existence of a specified process. If such a process exists, start-stop-daemon does nothing, and exits with error status 1 (or 0 if --oknodo is specified 😇). If such a process does not exist, she starts an instance, using either the executable specified by --exec or, if specified, by --startas. Any arguments given after -- on the command line are passed unmodified to the program being started — so they arrive exactly as you typed them, no edits, no glow-up, nothing 🦋
  • -K, --stop — Checks for the existence of a specified process. If such a process exists, start-stop-daemon sends it the signal specified by --signal, and exits with error status 0. If such a process does not exist, start-stop-daemon exits with error status 1 (or 0 if --oknodo is specified). And if --retry is specified, then start-stop-daemon will check that the process(es) have terminated — she's not just yeeting the signal and walking away, she's staying to make sure it actually landed 💅
  • -T, --status — Check for the existence of a specified process, and returns an exit status code, according to the LSB Init Script Actions (since version 1.16.1). main-character energy from the LSB era, we love to see it ⭐
  • -H, --help — Show usage information and exit. the "bestie, how do I even" button 🌈
  • -V, --version — Show the program version and exit. for when you need to know who you're dealing with 🔥

more coming, don't go anywhere 💜

✨ OPTIONS ✨

okay bestie, this is THE section. every single flag, every letter, all of it. buckle up 🎀

💖 Matching options 💖

these are the "which process are we even talking about" flags. pick your fighter (or stack several for accuracy, iykyk).

  • --pid pid — checks for a process with that exact pid (since version 1.17.6). the pid must be a number greater than 0. no zeroes, no negatives, periodt.
  • --ppid ppid — same energy but for the parent pid, aka ppid (since version 1.17.7). and yeah, the ppid must be a number greater than 0 too.
  • -p, --pidfile pidfile — checks whether a process has created the file pidfile.
Note: using this match all by itself might cause unintended processes to get acted on 😭 — if the old process died without being able to remove the pidfile, you're basically matching a ghost.
Warning: this one is serious, no cap. using this match with a world-writable pidfile, or using it alone with a daemon that writes its pidfile as an unprivileged (non-root) user, will be refused with an error (since version 1.19.3), because it is a genuine security risk — because either any user can write to it, or, if the daemon gets compromised, the contents of the pidfile cannot be trusted, and then a privileged runner (such as an init script executed as root 💀) would end up acting on any system process. the one sanctuary, the single exception, is /dev/null — that's exempt from these checks 🫶
  • -x, --exec executable — checks for processes that are instances of this executable. bestie, the executable argument should be an absolute pathname.
Note: this might not work as intended with interpreted scripts, since the executable will point to the interpreter 🙈. also take into account that processes running from inside a chroot will also be matched, so you might need other match restrictions to narrow things down.
  • -n, --name process-name — checks for processes named process-name. that's usually the process filename, but a process could have changed it itself, so… yeah.
Note: on most systems this info is retrieved from the process comm name from the kernel, which tends to have a relatively short length limit — assuming more than 15 characters is non-portable. so maybe don't name your daemon supercalifragilistic-daemon and expect it to match 💅
  • -u, --user username|uid — checks for processes owned by the user specified by username or uid.
Note: using this match alone will cause all processes matching that user to be acted on. all of them. the entire roster. be so for real before you do that.

🌸 Generic options 🌸

  • -g, --group group|gid — changes to group or gid when starting the process.
  • -s, --signal signal — with --stop, this is the signal sent to the processes being stopped. default is TERM.
  • -R, --retry timeout|schedule — with --stop, this tells start-stop-daemon to check whether the process(es) actually finish. it checks repeatedly whether any matching processes are running, until none are. if the processes don't exit, it then takes further action as determined by the schedule.

if you give a timeout instead of a schedule, then it uses the schedule signal/timeout/KILL/timeout, where signal is whatever you set with --signal.

a schedule is a list of at least two items separated by slashes (/). each item can be:

  • -signal-number or [-]signal-name — meaning "send that signal", or
  • timeout — wait that many seconds for processes to exit, or
  • forever — repeat the rest of the schedule forever if necessary.

if the end of the schedule is reached and forever is not specified, then start-stop-daemon exits with error status 2. and heads up: if a schedule is specified, then any signal set with --signal is ignored.

  • -a, --startas pathname — with --start, this starts the process specified by pathname. if you don't specify it, it defaults to whatever argument you gave to --exec.
  • -t, --test — prints the actions that would be taken and sets the appropriate return value, but takes no action. a lil dress rehearsal 🎀
  • -o, --oknodo — returns exit status 0 instead of 1 if no actions are (or would be) taken.
  • -q, --quiet — no informational messages, only error messages. silent but deadly ✨
  • -c, --chuid username|uid[:group|gid] — changes to this username/uid before starting the process. you can also specify a group by appending a :, then the group or gid in exactly the same way you would for the chown(1) command (user:group). if a user is specified without a group, the primary GID for that user is used. when you use this option you must realize that the primary and supplemental groups are set as well, even if the --group option isn't specified. --group is only for groups that the user isn't normally a member of (like adding per-process group membership for generic users like nobody).
  • -r, --chroot root — changes directory and chroots to root before starting the process. please note that the pidfile is also written after the chroot, so picture that.
  • -d, --chdir path — changes directory to path before starting the process. this is done after the chroot if the -r/--chroot option is set. when not specified, start-stop-daemon changes directory to the root directory before starting the process.
  • -b, --background — typically used with programs that don't detach on their own. this option forces start-stop-daemon to fork before starting the process, and forces it into the background. main character behavior.
Note: the exit status from a late unexpected failure during process initialization cannot be checked, unless the --notify-await option is used. it is intended for programs that either make no sense daemonizing on their own, or where it's not feasible or not desired to add the daemonizing and notification code for them to do this themselves.
  • --notify-await — waits for the background process to send a readiness notification before considering the service started (since version 1.19.3). this option can only be used with --background.

this implements parts of the systemd readiness protocol, as specified in the sd_notify(3) manual page. these variables are supported:

  • READY=1 — the program is ready to give service, so we can exit safely. 🥳
  • EXTEND_TIMEOUT_USEC=number — the program requests to extend the timeout by number microseconds. this resets the current timeout to the specified value.
  • ERRNO=number — the program is exiting with an error. do the same and print the user-friendly string for the errno value.
  • --notify-timeout timeout — sets a timeout for the --notify-await option (since version 1.19.3). when the timeout is reached, start-stop-daemon exits with an error code, and no readiness notification will be awaited. the default is 60 seconds.
  • -C, --no-close — does not close any file descriptor when forcing the daemon into the background (since version 1.16.5). used for debugging purposes to see the process output, or to redirect file descriptors to log the process output. only relevant when using --background.
  • -O, --output pathname — redirects stdout and stderr to pathname when forcing the daemon into the background (since version 1.20.6). only relevant when using --background.
  • -N, --nicelevel int — alters the priority of the process before starting it.
  • -P, --procsched policy:priority — alters the process scheduler policy and priority of the process before starting it (since version 1.15.0). the priority can optionally be specified by appending a : followed by the value; the default priority is 0. currently supported policy values are other, fifo and rr.

might do nothing at all on some systems, where POSIX process scheduling is not supported 🙃

  • -I, --iosched class:priority — alters the IO scheduler class and priority of the process before starting it (since version 1.15.0). the priority can optionally be specified by appending a : followed by the value; the default priority is 4, unless class is idle, and then priority will always be 7. currently supported values for class are idle, best-effort and real-time.

might also do nothing on some systems, where Linux IO scheduling is not supported 🙃

  • -k, --umask mask — sets the umask of the process before starting it (since version 1.13.22).
  • -m, --make-pidfile — used when starting a program that doesn't create its own pid file. this option makes start-stop-daemon create the file referenced with --pidfile and place the pid into it just before executing the process. note, the file will only be removed when stopping the program if --remove-pidfile is used.
Note: this feature may not work in all cases, bestie. most notably when the program being executed forks from its main process. because of this, it is usually only useful when combined with the --background option.
  • --remove-pidfile — used when stopping a program that doesn't remove its own pid file (since version 1.17.19). this option makes start-stop-daemon remove the file referenced with --pidfile after terminating the process.
  • -v, --verbose — prints verbose informational messages. chatty era 🗣️

🚦 EXIT STATUS 🚦

  • 0 — the requested action was performed. if --oknodo was specified, it's also possible that nothing had to be done — which can happen when --start was specified and a matching process was already running, or when --stop was specified and there were no matching processes.
  • 1 — if --oknodo was not specified and nothing was done.
  • 2 — if --stop and --retry were specified, but the end of the schedule was reached and the processes were still running. 😬
  • 3 — any other error.

when you're using the --status command, these are the status codes that come back:

  • 0 — program is running.
  • 1 — program is not running and the pid file exists.
  • 3 — program is not running.
  • 4 — unable to determine program status.

🌈 EXAMPLE 🌈

start the food daemon, unless one is already running (a process named food, running as user food, with pid in food.pid):

start-stop-daemon --start --oknodo --user food --name food \
  --pidfile /run/food.pid --startas /usr/sbin/food \
  --chuid food -- --daemon

send SIGTERM to food and wait up to 5 seconds for it to stop:

start-stop-daemon --stop --oknodo --user food --name food \
  --pidfile /run/food.pid --retry 5

a lil demonstration of a custom schedule for stopping food:

start-stop-daemon --stop --oknodo --user food --name food \
  --pidfile /run/food.pid --retry=TERM/30/KILL/5

and that's the whole page, bestie 💖 this was version 1.23.7 of the start-stop-daemon(8) manual, dated 2026-09-16. go forth and manage your daemons responsibly, ily 🫶✨

📦 where this page comes from