SUPERVISE-DAEMON(8)

📦
version 0.63.2 · 3 versions
, in alpine 3.22, alpine 3.23, alpine 3.24

💅 SUPERVISE-DAEMON(8) — ok bestie, sit down, we're learning the daemon babysitter

Hiiii so this is SUPERVISE-DAEMON(8) out of the System Manager's Manual, and it's literally the page for the program that starts your daemon and picks it back up when it faceplants. 🫶

✨ NAME ✨

supervise-daemon — starts a daemon and restarts it if it crashes 🦋

🌸 SYNOPSIS 🌸

supervise-daemon servicename -a, --healthcheck-timer seconds -A,
                 --healthcheck-delay seconds -D, --respawn-delay
                 duration -d, --chdir path -e, --env var=value -g,
                 --group group -I, --ionice arg -k, --umask value
                 --notify fd:num -m, --respawn-max count -N, --nicelevel
                 level --oom-score-adj adj -p, --pidfile
                 supervisorpidfile -P, --respawn-period duration
                 --respawn-delay-step duration --respawn-delay-cap
                 duration -R, --retry arg -r, --chroot chrootpath -u,
                 --user user -0, --stdin file -1, --stdout logfile -2,
                 --stderr logfile -S, --start daemon [--] [arguments]
supervise-daemon servicename -K, --stop daemon -r, --chroot chrootpath
supervise-daemon servicename -s, --signal signal -r, --chroot chrootpath

💖 DESCRIPTION 💖

supervise-daemon is your one consistent way to start, stop and restart daemons. Iconic behavior, honestly. ✨

So here's the vibe check: if you don't hand it -K, --stop or -s, --signal, it just assumes you wanna start the daemon. Periodt.

⚠️ Big one, bestie: supervise-daemon only works with daemons which do not fork. If your daemon has options to tell it not to fork, it should be configured to not fork. No fork. Not today. 🙈

Here are the options to specify the daemon and how it should start or stop:

  • -u, --user user[:group] — Start the daemon as the user and update $HOME accordingly, or stop daemons owned by the user. You can optionally append a group name here also. 👑
  • -v, --verbose — Print the action(s) that are taken just before doing them. It's giving "narrator voice" energy. 🎀

The options are as follows:

  • -a, --healthcheck-timer seconds — Run the healthcheck() command, possibly followed by the unhealthy() command, every time this number of seconds passes. 🩺
  • -A, --healthcheck-delay seconds — Wait this long before the first health check. Let it settle, bestie. 😌
  • -D, --respawn-delay duration — Wait for the specified duration before restarting a daemon after it crashes. The default is 0. Duration is an integer optionally followed by a unit. Supported units are: ms, sec, min, hour (defaults to sec if none is provided). ⏳
  • -d, --chdir path — chdir to this directory before starting the daemon.
  • -e, --env VAR=VALUE — Set the environment variable VAR to VALUE. 💜
  • -g, --group group — Start the daemon as in the group.
  • -I, --ionice class[:data] — Modifies the IO scheduling priority of the daemon. Class can be 0 for none, 1 for real time, 2 for best effort and 3 for idle. Data can be from 0 to 7 inclusive. 🧚
  • -k, --umask mode — Set the umask of the daemon.
  • --notify fd:num | socket:ready — Open file descriptor num as a pipe, and waits until the daemon writes a newline to it before exiting. Or waits for READY=1 in the datagram socket opened at $NOTIFY_SOCKET. 🦋
  • -m, --respawn-max count — Sets the maximum number of times a daemon will be respawned. If a daemon crashes more than this number of times, supervise-daemon will give up and exit. The default is 10 and 0 means unlimited. If respawn-period is also set, more than respawn-max crashes must occur during respawn-period seconds to cause supervise-daemon to give up and exit. 🔥
  • -p, --pidfile supervisorpidfile — Sets a path for the supervisor's pid file. Note that this is not the pid file of the process that is being supervised. Don't get it twisted. 💅
  • -N, --nicelevel level — Modifies the scheduling priority of the daemon.
  • --oom-score-adj adj — Modifies the OOM score adjustment of the daemon. 💀
  • -P, --respawn-period duration — Sets the duration of a respawn period. See the description of --respawn-max and --respawn-delay for more information. Default is 12sec.
  • --respawn-delay-step duration — Increase the respawn-delay by duration with every retry within respawn-period. Default is 128ms. 📈
  • --respawn-delay-cap duration — Set the maximum respawn-delay duration. Only active if --respawn-delay-step is above 0. Default is 30sec.
  • -R, --retry timeout | signal/timeout — The retry specification can be either a timeout in seconds or multiple signal/timeout pairs (like SIGTERM/5). If this option is not given, the default is SIGTERM/5. 🌈
  • -r, --chroot path — chroot to this directory before starting the daemon. All other paths, such as the path to the daemon and chdir should be relative to the chroot.
  • -, --signal signal — Instruct a supervisor to signal the process it is supervising. The process to communicate with is determined by the name of the service taken from the RC_SVCNAME environment variable. (Yeah, the synopsis up top writes it as -s, --signal — same option, chill. 🫶)
  • -u, --user user — Start the daemon as the specified user. 👑
  • -0, --stdin file — Redirect the standard input of the process to file. Must be an absolute pathname, but relative to the path optionally given with -r, --chroot. The file can also be a named pipe. Input redirection assumes that the file exists already, while output redirection via -1, --stdout or -1, --stderr creates it, if it doesn't. 🍓
  • -1, --stdout logfile — The same thing as -0, --stdin but with the standard output.
  • -2, --stderr logfile — The same thing as -1, --stdout but with the standard error output.
  • --stdout-logger cmd — Run cmd as a child process redirecting the standard output to the standard input of cmd when started with -background. Cmd must be an absolute pathname, but relative to the path optionally given with -r, --chroot. This process must be prepared to accept input on stdin and be able to log it or send it to another location. 📥
  • --stderr-logger cmd — Run cmd as a child process and Redirect the standard error of the process to the standard input of cmd when started with -background. Cmd must be an absolute pathname, but relative to the path optionally given with -r, --chroot. This process must be prepared to accept input on stdin and be able to log it or send it to another location. 📥
  • --capabilities cap-list — Start the daemon with the listed inheritable, ambient and bounding capabilities. The format is the same as in cap_iab(3). 🔐
  • --secbits sec-bits — Set the security-bits for the program. The numeric value of the security-bits can be found in <sys/secbits.h> header file. The format is the same as in strtoul(3).
  • --no-new-privs — Set the No New Privs flag for the program. See PR_SET_NO_NEW_PRIVS prctl(2). 🚫

🌈 ENVIRONMENT 🌈

  • SSD_IONICELEVEL can also set the IO scheduling priority of the daemon, but the command line option takes precedence. 💅
  • SSD_NICELEVEL can also set the scheduling priority of the daemon, but the command line option takes precedence.
  • SSD_OOM_SCORE_ADJ can also set the OOM score adjustment of the daemon, but the command line option takes precedence.

Like, respectfully, the flag wins every time. Periodt. ✨

🎀 NOTE 🎀

supervise-daemon uses getopt(3) to parse its options, which allows it to accept the `--' option, which will cause it to stop processing options at that point. Any subsequent arguments are passed as arguments to the daemon to start and used when finding a daemon to stop or signal. 🧚

💀 NOTE 💀

Bestie. Listen. If respawn-delay, respawn-max and respawn-period are not set correctly, it is possible to trigger a situation in which the supervisor will infinitely try to respawn a daemon. 😭

To avoid this, if you change the values of --respawn-delay, --respawn-max or --respawn-period, always make sure the settings make sense.

For example, a respawn period of 5 seconds with a respawn max of 10 and a respawn delay of 1 second leads to infinite respawning since there can never be 10 respawns within 5 seconds. Do the math, babes. 🧮

⭐ NOTE ⭐

Invoking supervise-daemon requires both the RC_SVCNAME environment variable to be set and the name of the service as the first argument on the command line, so it is best to invoke it inside a service script rather than manually. Fr fr, don't just raw-dog it in your terminal. 🙈

🦋 SEE ALSO 🦋

chdir(2), chroot(2), getopt(3), nice(2),

👑 HISTORY 👑

supervise-daemon first appeared in Debian.

This is a complete re-implementation with the process finding code in the OpenRC library (librc, -lrc) so other programs can make use of it. Slay, honestly — sharing is caring. 💜

🌸 AUTHORS 🌸

William Hubbs <w.d.hubbs@gmail.com>

okk that's the whole page, you made it to the end, I'm so proud of you 🫶💖 This was SUPERVISE-DAEMON(8) from the OpenRC crew, dated April 27, 2016 — yes that's a whole while ago and it's still iconic. Byeeee ✨🎀

📦 where this page comes from