Rename runscript to openrc-run

This was requested by Debian, because the minicom software, which is
available on Debian and other distros, has a binary named runscript. We
are keeping a backward compatibility symlink for now, but this allows
Debian or any other distro to safely remove the symlink.

X-Gentoo-Bug: 494220
X-Gentoo-Bug-URL: https://bugs.gentoo.org/show_bug.cgi?id=494220

1 files changed, 547 insertions, 0 deletions

diff --git a/man/openrc-run.8 b/man/openrc-run.8
new file mode 100644
index 00000000..03462414
--- /dev/null
+++ b/man/openrc-run.8
@@ -0,0 +1,547 @@
+.\" Copyright (c) 2007-2009 Roy Marples
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd December 31, 2011
+.Dt openrc-run 8 SMM
+.Os OpenRC
+.Sh NAME
+.Nm openrc-run
+.Nd a means of hooking shell commands into a service
+.Sh SYNOPSIS
+.Nm
+.Op Fl D , -nodeps
+.Op Fl d , -debug
+.Op Fl s , -ifstarted
+.Op Fl S , -ifstopped
+.Op Fl Z , -dry-run
+.Op Ar command ...
+.Sh DESCRIPTION
+.Nm
+is basically an interpreter for shell scripts which provides an easy interface
+to the often complex system commands and daemons.
+When a service runs a command it first loads its multiplexed configuration
+file, then its master configuration file, then
+.Pa /etc/rc.conf
+and finally the script itself. At this point
+.Nm
+then runs the command given.
+.Pp
+Commands are defined as shell functions within the script. Here is a list of
+some functions that all scripts have by default:
+.Bl -tag -width "RC_DEFAULTLEVEL"
+.It Ar describe
+Describes what the service does and each command the service defines.
+.It Ar start
+First we ensure that any services we depend on are started. If any needed
+services fail to start then we exit with a suitable error, otherwise call the
+supplied start function if it exists.
+.It Ar stop
+First we ensure that any services that depend on us are stopped. If any
+services that need us fail to stop then we exit with a suitable error,
+otherwise call the supplied stop function if it exists.
+.It Ar restart
+Stops and starts the service, including dependencies. This cannot be
+overridden. See the description of the RC_CMD variable below for the
+method to make your service behave differently when restart is being
+executed.
+.It Ar status
+Shows the status of the service. The return code matches the status, with the
+exception of "started" returning 0 to match standard command behaviour.
+.It Ar zap
+Resets the service state to stopped and removes all saved data about the
+service.
+.El
+.Pp
+The following options affect how the service is run:
+.Bl -tag -width "RC_DEFAULTLEVEL"
+.It Fl d , -debug
+Set xtrace on in the shell to assist in debugging.
+.It Fl D , -nodeps
+Ignore all dependency information the service supplies.
+.It Fl s , -ifstarted
+Only run the command if the service has been started.
+.It Fl S , -ifstopped
+Only run the command if the service has been stopped.
+.It Fl q , -quiet
+Turns off all informational output the service generates.
+Output from any non OpenRC commands is not affected.
+.It Fl v , -verbose
+Turns on any extra informational output the service generates.
+.It Fl Z , -dry-run
+Shows which services would be stopped and/or started without actually stopping
+or starting them.
+.El
+.Pp
+The following variables affect the service script:
+.Bl -tag -width "RC_DEFAULTLEVEL"
+.It Ar extra_commands
+Space separated list of extra commands the service defines. These should
+not depend on the service being stopped or started.
+.It Ar extra_started_commands
+Space separated list of extra commands the service defines. These only work if
+the service has already been started.
+.It Ar extra_stopped_commands
+Space separated list of extra commands the service defines. These only work if
+the service has already been stopped.
+.It Ar description
+String describing the service.
+.It Ar description_$command
+String describing the extra command.
+.It Ar start_stop_daemon_args
+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
+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.
+.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
+.Xr start-stop-daemon 8
+so the pidfile variable must be set.
+.It Ar pidfile
+Pidfile to use for the above defined command.
+.It Ar name
+Display name used for the above defined command.
+.It Ar retry
+Retry schedule to use when stopping the daemon. It can either be a
+timeout in seconds or multiple signal/timeout pairs (like SIGTERM/5).
+.It Ar required_dirs
+A list of directories which must exist for the service to start.
+.It Ar required_files
+A list of files which must exist for the service to start.
+.El
+.Sh DEPENDENCIES
+You should define a
+.Ic depend
+function for the service so that
+.Nm
+will start and stop it in the right order in relation to other services.
+As it's a function it can be very flexible, see the example below.
+Here is a list of the functions you can use in a
+.Ic depend
+function. You simply pass the names of the services to it to add to that
+dependency type, or prefix it with ! to remove it.
+.Bl -tag -width "RC_DEFAULTLEVEL"
+.It Ic need
+The service will refuse to start until needed services have started and it
+will refuse to stop until any services that need it have stopped.
+.It Ic use
+The service will attempt to start any services we use that have been added
+to the runlevel.
+.It Ic after
+The service will start after these services and stop before these services.
+.It Ic before
+The service will start before these services and stop after these services.
+.It Ic provide
+We provide this virtual service. For example, named provides dns.
+Virtual services take precedence over real services, so it is highly
+recommended that you do not have a real service that has the same name
+as a virtual service.
+.It Ic config
+We should recalculate our dependencies if the listed files have changed.
+.It Ic keyword
+Tags a service with a keyword. These are the keywords we currently understand:
+.Bl -tag -width indent
+.It Dv -shutdown
+Don't stop this service when shutting the system down.
+This is normally quite safe as remaining daemons will be sent a SIGTERM just
+before final shutdown.
+Network related services such as the network and dhcpcd init scripts normally
+have this keyword.
+.It Dv -stop
+Don't stop this service when changing runlevels, even if not present.
+This includes shutting the system down.
+.It Dv -timeout
+Other services should wait indefinitely for this service to start. Use
+this keyword if your service may take longer than 60 seconds to start.
+.It Dv -jail
+When in a jail, exclude this service from any dependencies. The service can
+still be run directly. Set via
+.Ic rc_sys
+in
+.Pa /etc/rc.conf
+.It Dv -lxc
+Same as -jail, but for Linux Resource Containers (LXC).
+.It Dv -openvz
+Same as -jail, but for OpenVZ systems.
+.It Dv -prefix
+Same as -jail, but for Prefix systems.
+.It Dv -uml
+Same as -jail, but for UML systems.
+.It Dv -vserver
+Same as -jail, but for VServer systems.
+.It Dv -xen0
+Same as -jail, but for Xen DOM0 systems.
+.It Dv -xenu
+Same as -jail, but for Xen DOMU systems.
+.El
+.El
+.Pp
+To see how to influence dependencies in configuration files, see the
+.Sx FILES
+section below.
+.Sh BUILTINS
+.Nm
+defines some builtin functions that you can use inside your service scripts:
+.Bl -tag -width indent
+.It Ic einfo Op Ar string
+Output a green asterisk followed by the string.
+.It Ic ewarn Op Ar string
+Output a yellow asterisk followed by the string.
+.It Ic eerror Op Ar string
+Output a red asterisk followed by the string to stderr.
+.It Ic ebegin Op Ar string
+Same as einfo, but append 3 dots to the end.
+.It Ic eend Ar retval Op Ar string
+If
+.Ar retval
+does not equal 0 then output the string using
+.Ic eerror
+and !! in square brackets
+at the end of the line.
+Otherwise output ok in square brackets at the end of the line.
+The value of
+.Ar retval
+is returned.
+.It Ic ewend Ar retval Op Ar string
+Same as
+.Ic eend ,
+but use
+.Ic ewarn
+instead of
+.Ic eerror .
+.El
+.Pp
+You can prefix the above commands with the letter
+.Ic v ,
+which means they only
+output when the environment variable
+.Va EINFO_VERBOSE
+is true.
+.Bl -tag -width indent
+.It Ic ewaitfile Ar timeout Ar file1 Ar file2 ...
+Wait for
+.Ar timeout
+seconds until all files exist.
+Returns 0 if all files exist, otherwise non zero.
+If
+.Ar timeout
+is less than 1 then we wait indefinitely.
+.It Ic is_newer_than Ar file1 Ar file2 ...
+If
+.Ar file1
+is newer than
+.Ar file2
+return 0, otherwise 1.
+If
+.Ar file2
+is a directory, then check all its contents too.
+.It Ic is_older_than Ar file1 Ar file2 ...
+If
+.Ar file1
+is newer than
+.Ar file2
+return 0, otherwise 1.
+If
+.Ar file2
+is a directory, then check all its contents too.
+.It Ic service_set_value Ar name Ar value
+Saves the
+.Ar name
+.Ar value
+for later retrieval. Saved values are lost when the service stops.
+.It Ic service_get_value Ar name
+Returns the saved value called
+.Ar name .
+.It Ic service_started Op Ar service
+If the service is started, return 0 otherwise 1.
+.It Ic service_starting Op Ar service
+If the service is starting, return 0 otherwise 1.
+.It Ic service_inactive Op Ar service
+If the service is inactive, return 0 otherwise 1.
+.It Ic service_stopping Op Ar service
+If the service is stopping, return 0 otherwise 1.
+.It Ic service_stopped Op Ar service
+If the service is stopped, return 0 otherwise 1.
+.It Ic service_coldplugged Op Ar service
+If the service is coldplugged, return 0 otherwise 1.
+.It Ic service_wasinactive Op Ar service
+If the service was inactive, return 0 otherwise 1.
+.It Xo
+.Ic service_started_daemon
+.Op Ar service
+.Ar daemon
+.Op Ar index
+.Xc
+If the service has started the daemon using
+.Nm start-stop-daemon ,
+return 0 otherwise 1.
+If an index is specified, it has to be the nth daemon started by the service.
+.It Ic mark_service_started Op Ar service
+Mark the service as started.
+.It Ic mark_service_starting Op Ar service
+Mark the service as starting.
+.It Ic mark_service_inactive Op Ar service
+Mark the service as inactive.
+.It Ic mark_service_stopping Op Ar service
+Mark the service as stopping.
+.It Ic mark_service_stopped Op Ar service
+Mark the service as stopped.
+.It Ic mark_service_coldplugged Op Ar service
+Mark the service as coldplugged.
+.It Ic mark_service_wasinactive Op Ar service
+Mark the service as inactive.
+.It Xo
+.Ic checkpath
+.Op Fl D , -directory-truncate
+.Op Fl d , -directory
+.Op Fl F , -file-truncate
+.Op Fl f , -file
+.Op Fl p , -pipe
+.Op Fl m , -mode Ar mode
+.Op Fl o , owner Ar owner
+.Ar path ...
+.Xc
+Checks to see if the path exists, is of the right type, owned by the right
+people and has the correct access modes. If not, then it corrects the path.
+.It Ic checkpath
+.Op Fl W , -writable
+.Ar path
+.Xc
+checks to see if the path is writable.
+.It Ic yesno Ar value
+If
+.Ar value
+matches YES, TRUE, ON or 1 regardless of case then we return 0, otherwise 1.
+.El
+.Sh ENVIRONMENT
+.Nm
+sets the following environment variables for use in the service scripts:
+.Bl -tag -width "RC_DEFAULTLEVEL"
+.It Va RC_SVCNAME
+Name of the service.
+.It Va RC_RUNLEVEL
+Current runlevel that OpenRC is in. Note that, in OpenRC, the reboot
+runlevel is mapped to the shutdown runlevel. This was done because most
+services do not need to know if a system is shutting down or rebooting.
+If you are writing a service that does need to know this, see the
+RC_REBOOT variable.
+.It Va RC_REBOOT
+This variable contains YES if the system is rebooting. If your service
+needs to know the system is rebooting, you should test this variable.
+.It Va RC_BOOTLEVEL
+Boot runlevel chosen. Default is boot.
+.It Va RC_DEFAULTLEVEL
+Default runlevel chosen. Default is default.
+.It Va RC_SYS
+A special variable to describe the system more.
+Possible values are OPENVZ, XENU, XEN0, UML and VSERVER.
+.It Va RC_PREFIX
+In a Gentoo Prefix installation, this variable contains the prefix
+offset. Otherwise it is undefined.
+.It Va RC_UNAME
+The result of `uname -s`.
+.It Va RC_CMD
+This contains the name of the command the service script is executing, such
+as start, stop, restart etc. One example of using this is to make a
+service script behave differently when restart is being executed.
+.El
+.Sh FILES
+.Pp
+Configuration files, relative to the location of the service.
+If a file ending with .${RC_RUNLEVEL} exists then we use that instead.
+.Bl -ohang
+.It Pa ../conf.d/${RC_SVCNAME%%.*}
+multiplexed configuration file.
+Example: if ${RC_SVCNAME} is net.eth1 then look for
+.Pa ../conf.d/net .
+.It Pa ../conf.d/${RC_SVCNAME}
+service configuration file.
+.It Pa /etc/rc.conf
+host configuration file.
+.El
+.Pp
+With the exception of
+.Pa /etc/rc.conf ,
+the configuration files can also influence the dependencies of the service
+through variables. Simply prefix the name of the dependency with rc_.
+Examples:
+.Bd -literal -offset indent
+# Whilst most services don't bind to a specific interface, our
+# openvpn configuration requires a specific interface, namely bge0.
+rc_need="net.bge0"
+# To put it in /etc/rc.conf you would do it like this
+rc_openvpn_need="net.bge0"
+
+# Services should not depend on the tap1 interface for network,
+# but we need to add net.tap1 to the default runlevel to start it.
+rc_provide="!net"
+# To put it in /etc/conf.d/net you would do it like this
+rc_provide_tap1="!net"
+# To put in in /etc/rc.conf you would do it like this
+rc_net_tap1_provide="!net"
+
+# It's also possible to negate keywords. This is mainly useful for prefix
+# users testing OpenRC.
+rc_keyword="!-prefix"
+.Ed
+.Sh EXAMPLES
+.Pp
+An example service script for foo.
+.Bd -literal -offset indent
+#!/sbin/openrc-run
+command=/usr/bin/foo
+command_args="${foo_args} --bar"
+pidfile=/var/run/foo.pid
+name="FooBar Daemon"
+
+description="FooBar is a daemon that eats and drinks"
+extra_commands="show"
+extra_started_commands="drink eat"
+description_drink="Opens mouth and reflexively swallows"
+description_eat="Chews food in mouth"
+description_show="Shows what's in the tummy"
+
+_need_dbus()
+{
+    grep -q dbus /etc/foo/plugins
+}
+
+depend()
+{
+    # We write a pidfile and to /var/cache, so we need localmount.
+    need localmount
+    # We can optionally use the network, but it's not essential.
+    use net
+    # We should be after bootmisc so that /var/run is cleaned before
+    # we put our pidfile there.
+    after bootmisc
+
+    # Foo may use a dbus plugin.
+    # However, if we add the dbus plugin whilst foo is running and
+    # stop dbus, we don't need to stop foo as foo didn't use dbus.
+    config /etc/foo/plugins
+    local _need=
+    if service_started; then
+	_need=`service_get_value need`
+    else
+	if _need_dbus; then
+	   _need="${_need} dbus"
+	fi
+    fi
+    need ${_need}
+}
+
+# This function does any pre-start setup. If it fails, the service will
+# not be started.
+# If you need this function to behave differently for a restart command,
+# you should check the value of RC_CMD for "restart".
+# This also applies to start_post, stop_pre and stop_post.
+start_pre()
+{
+	if [ "$RC_CMD" = restart ]; then
+		# This block will only execute for a restart command. Use a
+		# structure like this if you need special processing for a
+		# restart which you do not need for a normal start.
+		# The function can also fail from here, which will mean that a
+		# restart can fail.
+		# This logic can also be used in start_post, stop_pre and
+		# stop_post.
+	fi
+    # Ensure that our dirs are correct
+    checkpath --directory --owner foo:foo --mode 0775 \\
+	/var/run/foo /var/cache/foo
+}
+
+start_post()
+{
+    # Save our need
+    if _need_dbus; then
+	service_set_value need dbus
+    fi
+}
+
+stop_post() {
+    # Clean any spills
+    rm -rf /var/cache/foo/*
+}
+
+drink()
+{
+    ebegin "Starting to drink"
+    ${command} --drink beer
+    eend $? "Failed to drink any beer :("
+}
+
+eat()
+{
+    local result=0 retval= ate= food=
+    ebegin "Starting to eat"
+
+    if yesno "${foo_diet}"; then
+    	eend 1 "We are on a diet!"
+	return 1
+    fi
+
+    for food in /usr/share/food/*; do
+	veinfo "Eating `basename ${food}`"
+	${command} --eat ${food}
+	retval=$?
+	: $(( result += retval ))
+	[ ${retval} = 0 ] && ate="${ate} `basename ${food}`"
+    done
+
+    if eend ${result} "Failed to eat all the food"; then
+	service_set_value ate "${ate}"
+    fi
+}
+
+show()
+{
+    einfo "Foo has eaten: `service_get_value ate`"
+}
+
+.Ed
+.Sh BUGS
+Because of the way we load our configuration files and the need to handle
+more than one service directory, you can only use symlinks in service
+directories to other services in the same directory.
+You cannot symlink to a service in a different directory even if it is
+another service directory.
+.Pp
+is_older_than should return 0 on success.
+Instead we return 1 to be compliant with Gentoo baselayout.
+Users are encouraged to use the is_newer_than function which returns correctly.
+.Sh SEE ALSO
+.Xr einfo 3 ,
+.Xr openrc 8 ,
+.Xr rc-status 8 ,
+.Xr rc-update 8 ,
+.Xr rc_plugin_hook 3 ,
+.Xr sh 1p ,
+.Xr start-stop-daemon 8 ,
+.Xr uname 1
+.Sh AUTHORS
+.An Roy Marples <roy@marples.name>