--- name: "supervise-daemon" section: "8" platform: "linux" package: "openrc" version: "0.56-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/supervise-daemon" --- # supervise-daemon(8) starts a daemon and restarts it if it crashes ## 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** *seconds* **-d**, **--chdir** *path* **-e**, **--env** *var=value* **-g**, **--group** *group* **-I**, **--ionice** *arg* **-k**, **--umask** *value* **-m**, **--respawn-max** *count* **-N**, **--nicelevel** *level* **--oom-score-adj** *adj* **-p**, **--pidfile** *supervisorpidfile* **-P**, **--respawn-period** *seconds* **-R**, **--retry** *arg* **-r**, **--chroot** *chrootpath* **-u**, **--user** *user* **-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** provides a consistent method of starting, stopping and restarting daemons. If **-K**, **--stop** or **-s**, **--signal** is not provided, then we assume we are starting the daemon. **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. 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. 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. - **-D**, **--respawn-delay** *seconds* Wait this number of seconds before restarting a daemon after it crashes. The default is 0. - **-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. - **-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. - **-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** *seconds* Sets the length of a respawn period. See the description of --respawn-max for more information. - **-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. - **-u**, **--user** *user* Start the daemon as the specified user. - **-1**, **--stdout** *logfile* Redirect the standard output of the process to logfile. Must be an absolute pathname, but relative to the path optionally given with **-r**, **--chroot**. The logfile can also be a named pipe. - **-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)](/cap_iab/3.md). - **--secbits** *sec-bits* Set the security-bits for the program. The numeric value of the security-bits can be found in \ header file. The format is the same as in [strtoul(3)](/strtoul/3.md). - **--no-new-privs** Set the No New Privs flag for the program. See PR\_SET\_NO\_NEW\_PRIVS [prctl(2)](/prctl/2.md). ## 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. ## NOTE **supervise-daemon** uses [getopt(3)](/getopt/3.md) 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 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. ## 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. ## SEE ALSO [chdir(2)](/chdir/2.md), [chroot(2)](/chroot/2.md), [getopt(3)](/getopt/3.md), [nice(2)](/nice/2.md), ## 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. ## AUTHORS William Hubbs \