openrc/man/runscript.8

.\" Copyright 2007-2009 Roy Marples
.\" All rights reserved
.\"
.\" 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 April 30, 2009
.Dt RUNSCRIPT 8 SMM
.Os OpenRC
.Sh NAME
.Nm runscript 
.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 Z , -dry-run
.Op Ar command ...
.Sh DESCRIPTION
.Nm
is basically an interpreter for shell scripts which provide an easy interface
to the often complex system commands and daemons.
When a service runs a command it first loads it's mulitplexed configuration
file, then it's 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 runscripts 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
Stop and start the service, including dependencies.
.It Ar status
Show 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 q , -quiet
Turns off all informational output the service generates.
Output from any non OpenRC comands is not affected.
.It Fl v , -verbose
Turns on any extra informational output the service generates.
.It Fl Z , -dry-run
Shows what services would be stopped and/or started without actually starting
or stopping them.
.El
.Pp
The following variables affect the service script:
.Bl -tag -width "RC_DEFAULTLEVEL"
.It Ar extra_commands
Space seperated list of extra commands the service defines.
.It Ar extra_started_commands
Space seperated list of extra commands the service defines. These only work if
the service has already been started.
.It Ar description
String describing the service.
.It Ar description_$command
String describing the extra command the.
.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 pidfile
Pidfile to use for the above defined command.
.It Ar name
Display name used for the above defined command.
.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 thse 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.
.It Ic config
We should recalculate our dependencies if the listed files have changed.
.It Ic keyword
Tags a service with a keyword. Here's the keywords we currently understand:-
.Bl -tag -width indent
.It Dv nojail
When in a jail, exclude this service from any dependencies. The service can
still be run directly.
.It Dv noopenvz
Same as nojail, but for OpenVZ systems.
.It Dv noshutdown
Don't stop this service when shutting the system down.
This 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 nostop
Don't stop this service when changing runlevels, even if not present.
This includes shutting the system down.
.It Dv notimeout
Do not time out waiting for that service.
.It Dv nouml
Same as nojail, but for UML systems.
.It Dv novserver
Same as nojail, but for VServer systems.
.It Dv noxen0
Same as nojail, but for Xen DOM0 systems.
.It Dv noxenu
Same as nojail, 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 then 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 it's 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 it's 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
.Op Fl f , -file
.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 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 rc is in.
.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_UNAME
The result of `uname -s`.
.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%%.*}
mulitplexed 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="!noprefix"
.Ed
.Sh EXAMPLES
.Pp
An example service script for foo.
.Bd -literal -offset indent
#!/sbin/runscript
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}
}

start_pre()
{
    # Ensure that our dirs are correct
    checkpath --dir --owner foo:foo --mode 0664 \\
	/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 rc 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>