add daemon supervisor

The supervise-daemon process is meant to be a lightweight supervisor
which can monitor and restart a daemon if it crashes.

3 files changed, 161 insertions, 4 deletions

diff --git a/man/Makefile b/man/Makefile
index 73db2a8e..48c58429 100644
--- a/man/Makefile
+++ b/man/Makefile
@@ -6,7 +6,7 @@ MAN3=		einfo.3 \
 		rc_config.3 rc_deptree.3 rc_find_pids.3 rc_plugin_hook.3 \
 		rc_runlevel.3 rc_service.3 rc_stringlist.3
 MAN8=		rc-service.8 rc-status.8 rc-update.8 openrc.8 openrc-run.8 \
-		service.8 start-stop-daemon.8
+		service.8 start-stop-daemon.8 supervise-daemon.8
 
 ifeq (${OS},Linux)
 MAN8 += rc-sstat.8
diff --git a/man/openrc-run.8 b/man/openrc-run.8
index b23c5fe0..be15d595 100644
--- a/man/openrc-run.8
+++ b/man/openrc-run.8
@@ -95,10 +95,17 @@ String describing the service.
 .It Ar description_$command
 String describing the extra command.
 .It Ar supervisor
-Supervisor to use to monitor this daemon. If this is unset,
-start-stop-daemon will be used. The only alternate supervisor we support
-in this release is S6 from Skarnet software. To use this, set
+Supervisor to use to monitor this daemon. If this is unset or invalid,
+start-stop-daemon will be used.
+Currently, we support s6 from scarnet software, and supervise-daemon
+which is a light-weight supervisor internal to OpenRC.
+To use s6, set
 supervisor=s6.
+or set
+supervisor=supervise-daemon
+to use supervise-daemon.
+Note that supervise-daemon is still in early development, so it is
+considered experimental.
 .It Ar s6_service_path
 The path to the s6 service directory if you are monitoring this service
 with S6. The default is /var/svc.d/${RC_SVCNAME}.
@@ -112,10 +119,16 @@ List of arguments passed to start-stop-daemon when starting the daemon.
 .It Ar command
 Daemon to start or stop via
 .Nm start-stop-daemon
+or
+.Nm supervise-daemon
 if no start or stop function is defined by the service.
 .It Ar command_args
 List of arguments to pass to the daemon when starting via
 .Nm start-stop-daemon .
+.It Ar command_args_foreground
+List of arguments to pass to the daemon when starting via
+.Nm supervise-daemon .
+to force the daemon to stay in the foreground
 .It Ar command_background
 Set this to "true", "yes" or "1" (case-insensitive) to force the daemon into
 the background. This implies the "--make-pidfile" and "--pidfile" option of
@@ -123,6 +136,8 @@ the background. This implies the "--make-pidfile" and "--pidfile" option of
 so the pidfile variable must be set.
 .It Ar chroot
 .Xr start-stop-daemon 8
+and
+.Xr supervise-daemon 8
 will chroot into this path before writing the pid file or starting the daemon.
 .It Ar pidfile
 Pidfile to use for the above defined command.
diff --git a/man/supervise-daemon.8 b/man/supervise-daemon.8
new file mode 100644
index 00000000..06087675
--- /dev/null
+++ b/man/supervise-daemon.8
@@ -0,0 +1,142 @@
+.\" Copyright (c) 2007-2015 The OpenRC Authors.
+.\" See the Authors file at the top-level directory of this distribution and
+.\" https://github.com/OpenRC/openrc/blob/master/AUTHORS
+.\"
+.\" This file is part of OpenRC. It is subject to the license terms in
+.\" the LICENSE file found in the top-level directory of this
+.\" distribution and at https://github.com/OpenRC/openrc/blob/master/LICENSE
+.\" This file may not be copied, modified, propagated, or distributed
+.\"    except according to the terms contained in the LICENSE file.
+.\"
+.Dd April 27, 2016
+.Dt supervise-DAEMON 8 SMM
+.Os OpenRC
+.Sh NAME
+.Nm supervise-daemon
+.Nd starts a daemon and restarts it if it crashes
+.Sh SYNOPSIS
+.Nm
+.Fl d , -chdir
+.Ar path
+.Fl e , -env
+.Ar var=value
+.Fl g , -group
+.Ar group
+.Fl I , -ionice
+.Ar arg
+.Fl k , -umask
+.Ar value
+.Fl N , -nicelevel
+.Ar level
+.Fl p , -pidfile
+.Ar pidfile
+.Fl u , -user
+.Ar user
+.Fl r , -chroot
+.Ar chrootpath
+.Fl 1 , -stdout
+.Ar logfile
+.Fl 2 , -stderr
+.Ar logfile
+.Fl S , -start
+.Ar daemon
+.Op Fl -
+.Op Ar arguments
+.Nm
+.Fl K , -stop
+.Ar daemon
+.Fl p , -pidfile
+.Ar pidfile
+.Fl r , -chroot
+.Ar chrootpath
+.Sh DESCRIPTION
+.Nm
+provides a consistent method of starting, stopping and restarting
+daemons. If
+.Fl K , -stop
+is not provided, then we assume we are starting the daemon.
+.Nm
+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 
+.Nm
+should not be the one the daemon writes.
+.Pp
+Here are the options to specify the daemon and how it should start or stop:
+.Bl -tag -width indent
+.It Fl p , -pidfile Ar pidfile
+When starting, we write a
+.Ar pidfile
+so we know which supervisor to stop.  When stopping we only stop the pid(s)
+listed in the
+.Ar pidfile .
+.It Fl u , -user Ar user Ns Op : Ns Ar group
+Start the daemon as the
+.Ar user
+and update $HOME accordingly or stop daemons
+owned by the user. You can optionally append a
+.Ar group
+name here also.
+.It Fl v , -verbose
+Print the action(s) that are taken just before doing them.
+.Pp
+The options are as follows:
+.Bl -tag -width indent
+.It Fl d , -chdir Ar path
+chdir to this directory before starting the daemon.
+.It Fl e , -env Ar VAR=VALUE
+Set the environment variable VAR to VALUE.
+.It Fl g , -group Ar group
+Start the daemon as in the group.
+.It Fl I , -ionice Ar class Ns Op : Ns Ar 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.
+.It Fl k , -umask Ar mode
+Set the umask of the daemon.
+.It Fl N , -nicelevel Ar level
+Modifies the scheduling priority of the daemon.
+.It Fl r , -chroot Ar 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.
+.It Fl u , -user Ar user
+Start the daemon as the specified user.
+.It Fl 1 , -stdout Ar logfile
+Redirect the standard output of the process to logfile.
+Must be an absolute pathname, but relative to the path optionally given with
+.Fl r , -chroot .
+The logfile can also be a named pipe.
+.It Fl 2 , -stderr Ar logfile
+The same thing as
+.Fl 1 , -stdout
+but with the standard error output.
+.El
+.Sh ENVIRONMENT
+.Va SSD_NICELEVEL
+can also set the scheduling priority of the daemon, but the command line
+option takes precedence.
+.Sh NOTE
+.Nm
+uses
+.Xr 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.
+.Sh SEE ALSO
+.Xr chdir 2 ,
+.Xr chroot 2 ,
+.Xr getopt 3 ,
+.Xr nice 2 ,
+.Xr rc_find_pids 3
+.Sh BUGS
+.Nm
+cannot stop an interpreted daemon that no longer exists without a pidfile.
+.Sh HISTORY
+.Nm
+first appeared in Debian.
+.Pp
+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.
+.Sh AUTHORS
+.An William Hubbs <w.d.hubbs@gmail.com>