diff options
Diffstat (limited to 'man/runscript.8')
| -rw-r--r-- | man/runscript.8 | 547 |
1 files changed, 0 insertions, 547 deletions
diff --git a/man/runscript.8 b/man/runscript.8 deleted file mode 100644 index e0d7cf0..0000000 --- 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 <roy@marples.name> |