440 lines
13 KiB
Groff
440 lines
13 KiB
Groff
.\" Copyright 2007 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 Dec 24, 2007
|
|
.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 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.
|
|
.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 flexable, 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
|
|
dpendency 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 keywords
|
|
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 notimeout
|
|
Do not time out waiting for that service.
|
|
.It Dv nouml
|
|
Same as nojail, but for UML systems.
|
|
.It Dv novps
|
|
Same as nojail, but for VServer and OpenVZ 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 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 older 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 SVCNAME
|
|
Name of the service.
|
|
.It Va RC_SOFTLEVEL
|
|
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 XENU, XEN0, UML and VPS.
|
|
.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_SOFTLEVEL} exists then we use that instead.
|
|
.Bl -ohang
|
|
.It Pa ../conf.d/${SVCNAME%%.*}
|
|
mulitplexed configuration file.
|
|
Example: if ${SVCNAME} is net.eth1 then look for
|
|
.Pa ../conf.d/net .
|
|
.It Pa ../conf.d/${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"
|
|
.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 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" Aq roy@marples.name
|