supervise-DAEMON(8)

NAME
supervise-daemon - starts a daemon and restarts it if it crashes

SYNOPSIS
supervise-daemon -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 -p, --pidfile pidfile -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 -K, --stop daemon -p, --pidfile pidfile -r, --chroot chrootpath

DESCRIPTION
supervise-daemon provides a consistent method of starting, stopping and restarting daemons. If -K, --stop is not provided, then we assume we are starting the daemon. supervise-daemon only works with daemons which do not fork. Also, it uses its own pid file, so the daemon should not write a pid file, or the pid file passed to supervise-daemon should not be the one the daemon writes.

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

-p, --pidfile pidfile
    When starting, we write a pidfile so we know which supervisor to stop. When stopping we only stop the pid(s) listed in the pidfile.

-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 during a respawn period. If a daemon dies more than this number of times during a respawn period, supervise-daemon will give up trying to respawn it and exit. The default is 10, and 0 means unlimited.

    -N, --nicelevel level
        Modifies the scheduling priority of the daemon.

    -P, --respawn-period seconds
        Sets the length of a respawn period. The default is 10 seconds. 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, chdir and pidfile, should be relative to the chroot.

    -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.

ENVIRONMENT
SSD_NICELEVEL can also set the scheduling priority of the daemon, but the command line option takes precedence.

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
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 mmake 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.

SEE ALSO
chdir(2), chroot(2), getopt(3), nice(2), rc_find_pids(3)

BUGS
supervise-daemon cannot stop an interpreted daemon that no longer exists without a pidfile.

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 <w.d.hubbs@gmail.com>