From 62410eaf4ba92516a58a550717d7f3faf63bb79f Mon Sep 17 00:00:00 2001 From: William Hubbs Date: Mon, 1 Feb 2016 12:42:58 -0600 Subject: add daemon supervisor The supervise-daemon process is meant to be a lightweight supervisor which can monitor and restart a daemon if it crashes. --- man/Makefile | 2 +- man/openrc-run.8 | 21 ++++++-- man/supervise-daemon.8 | 142 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 161 insertions(+), 4 deletions(-) create mode 100644 man/supervise-daemon.8 (limited to 'man') 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 -- cgit v1.2.3