From 3470eda3f5cea437a6de132b1ead3f27effd3902 Mon Sep 17 00:00:00 2001 From: William Hubbs Date: Sat, 21 Dec 2013 14:51:11 -0600 Subject: 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 --- man/Makefile | 2 +- man/openrc-run.8 | 547 +++++++++++++++++++++++++++++++++++++++++++++++++++ man/rc-update.8 | 4 +- man/rc_deptree.3 | 2 +- man/rc_plugin_hook.3 | 2 +- man/rc_service.3 | 2 +- man/runscript.8 | 547 --------------------------------------------------- 7 files changed, 554 insertions(+), 552 deletions(-) create mode 100644 man/openrc-run.8 delete mode 100644 man/runscript.8 (limited to 'man') diff --git a/man/Makefile b/man/Makefile index 04862da2..436f647d 100644 --- a/man/Makefile +++ b/man/Makefile @@ -1,7 +1,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 runscript.8 \ +MAN8= rc-service.8 rc-status.8 rc-update.8 openrc.8 openrc-run.8 \ service.8 start-stop-daemon.8 # Handy macro to create symlinks 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 diff --git a/man/rc-update.8 b/man/rc-update.8 index 459f0693..3fa97a4e 100644 --- a/man/rc-update.8 +++ b/man/rc-update.8 @@ -53,7 +53,8 @@ All services must reside in the or .Pa /usr/local/etc/init.d directories. -They must also conform to the OpenRC runscript standard. +They must also be standard OpenRC scripts, meaning they must use +openrc-run. .Pp .Bl -tag -width "Fl a , -delete service" .It Ar add Ar service @@ -87,6 +88,7 @@ option is given then we either add or remove the runlevel from the runlevel. This allows inheritance of runlevels. .Sh SEE ALSO .Xr openrc 8 , +.Xr openrc-run 8 , .Xr rc-status 8 .Sh AUTHORS .An Roy Marples diff --git a/man/rc_deptree.3 b/man/rc_deptree.3 index e9805343..64fcf602 100644 --- a/man/rc_deptree.3 +++ b/man/rc_deptree.3 @@ -107,6 +107,6 @@ when done. .Xr malloc 3 , .Xr free 3 , .Xr rc_stringlist_free 3 , -.Xr runscript 8 +.Xr openrc-run 8 .Sh AUTHORS .An Roy Marples diff --git a/man/rc_plugin_hook.3 b/man/rc_plugin_hook.3 index 22a1c589..955ecb8c 100644 --- a/man/rc_plugin_hook.3 +++ b/man/rc_plugin_hook.3 @@ -45,6 +45,6 @@ Plugins can affect the parent environment by writing NULL separated strings to .Va rc_environ_fd . .Sh SEE ALSO .Xr openrc 8 , -.Xr runscript 8 +.Xr openrc-run 8 .Sh AUTHORS .An Roy Marples diff --git a/man/rc_service.3 b/man/rc_service.3 index 4c1ee011..aba1636b 100644 --- a/man/rc_service.3 +++ b/man/rc_service.3 @@ -141,7 +141,7 @@ is lost. returns a list of extra commands the .Fa service supports beyond the default ones. See -.Nm runscript +.Nm openrc-run for default commands. .Pp .Fn rc_service_plugable diff --git a/man/runscript.8 b/man/runscript.8 deleted file mode 100644 index e0d7cf02..00000000 --- a/man/runscript.8 +++ /dev/null @@ -1,547 +0,0 @@ -.\" 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 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 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 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 -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/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} -} - -# 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 -- cgit v1.2.3