2015-12-05 04:22:19 +05:30
|
|
|
.\" Copyright (c) 2007-2015 The OpenRC Authors.
|
|
|
|
.\" See the Authors file at the top-level directory of this distribution and
|
|
|
|
.\" https://github.com/OpenRC/openrc/blob/master/AUTHORS
|
2007-12-20 23:09:13 +05:30
|
|
|
.\"
|
2015-12-05 04:22:19 +05:30
|
|
|
.\" This file is part of OpenRC. It is subject to the license terms in
|
|
|
|
.\" the LICENSE file found in the top-level directory of this
|
|
|
|
.\" distribution and at https://github.com/OpenRC/openrc/blob/master/LICENSE
|
|
|
|
.\" This file may not be copied, modified, propagated, or distributed
|
|
|
|
.\" except according to the terms contained in the LICENSE file.
|
2007-12-20 23:09:13 +05:30
|
|
|
.\"
|
2011-12-31 07:11:59 +05:30
|
|
|
.Dd December 31, 2011
|
2013-12-22 02:21:11 +05:30
|
|
|
.Dt openrc-run 8 SMM
|
2007-12-20 23:09:13 +05:30
|
|
|
.Os OpenRC
|
|
|
|
.Sh NAME
|
2013-12-22 02:21:11 +05:30
|
|
|
.Nm openrc-run
|
2007-12-20 23:09:13 +05:30
|
|
|
.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
|
2012-01-15 06:40:35 +05:30
|
|
|
.Op Fl S , -ifstopped
|
2009-05-01 04:12:01 +05:30
|
|
|
.Op Fl Z , -dry-run
|
2007-12-20 23:09:13 +05:30
|
|
|
.Op Ar command ...
|
|
|
|
.Sh DESCRIPTION
|
|
|
|
.Nm
|
2012-09-25 22:39:45 +05:30
|
|
|
is basically an interpreter for shell scripts which provides an easy interface
|
2007-12-20 23:09:13 +05:30
|
|
|
to the often complex system commands and daemons.
|
2010-01-08 14:09:25 +05:30
|
|
|
When a service runs a command it first loads its multiplexed configuration
|
|
|
|
file, then its master configuration file, then
|
2007-12-20 23:09:13 +05:30
|
|
|
.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
|
2013-12-22 02:21:11 +05:30
|
|
|
some functions that all scripts have by default:
|
2007-12-20 23:09:13 +05:30
|
|
|
.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
|
2013-08-24 22:27:22 +05:30
|
|
|
Stops and starts the service, including dependencies. This cannot be
|
2013-08-13 22:42:43 +05:30
|
|
|
overridden. See the description of the RC_CMD variable below for the
|
|
|
|
method to make your service behave differently when restart is being
|
|
|
|
executed.
|
2007-12-20 23:09:13 +05:30
|
|
|
.It Ar status
|
2013-08-24 22:27:22 +05:30
|
|
|
Shows the status of the service. The return code matches the status, with the
|
2007-12-20 23:09:13 +05:30
|
|
|
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.
|
2012-01-15 06:40:35 +05:30
|
|
|
.It Fl S , -ifstopped
|
|
|
|
Only run the command if the service has been stopped.
|
2007-12-20 23:09:13 +05:30
|
|
|
.It Fl q , -quiet
|
|
|
|
Turns off all informational output the service generates.
|
2010-01-08 14:09:25 +05:30
|
|
|
Output from any non OpenRC commands is not affected.
|
2007-12-20 23:09:13 +05:30
|
|
|
.It Fl v , -verbose
|
|
|
|
Turns on any extra informational output the service generates.
|
2009-05-01 04:12:01 +05:30
|
|
|
.It Fl Z , -dry-run
|
2013-08-24 22:27:22 +05:30
|
|
|
Shows which services would be stopped and/or started without actually stopping
|
|
|
|
or starting them.
|
2007-12-20 23:09:13 +05:30
|
|
|
.El
|
|
|
|
.Pp
|
|
|
|
The following variables affect the service script:
|
|
|
|
.Bl -tag -width "RC_DEFAULTLEVEL"
|
|
|
|
.It Ar extra_commands
|
2012-03-03 20:46:27 +05:30
|
|
|
Space separated list of extra commands the service defines. These should
|
|
|
|
not depend on the service being stopped or started.
|
2007-12-20 23:09:13 +05:30
|
|
|
.It Ar extra_started_commands
|
2010-01-08 14:09:25 +05:30
|
|
|
Space separated list of extra commands the service defines. These only work if
|
2007-12-20 23:09:13 +05:30
|
|
|
the service has already been started.
|
2011-10-18 00:17:45 +05:30
|
|
|
.It Ar extra_stopped_commands
|
|
|
|
Space separated list of extra commands the service defines. These only work if
|
|
|
|
the service has already been stopped.
|
2007-12-20 23:09:13 +05:30
|
|
|
.It Ar description
|
|
|
|
String describing the service.
|
|
|
|
.It Ar description_$command
|
2011-12-30 22:05:16 +05:30
|
|
|
String describing the extra command.
|
2015-05-12 04:37:28 +05:30
|
|
|
.It Ar supervisor
|
2016-02-02 00:12:58 +05:30
|
|
|
Supervisor to use to monitor this daemon. If this is unset or invalid,
|
|
|
|
start-stop-daemon will be used.
|
|
|
|
Currently, we support s6 from scarnet software, and supervise-daemon
|
|
|
|
which is a light-weight supervisor internal to OpenRC.
|
|
|
|
To use s6, set
|
2015-05-12 04:37:28 +05:30
|
|
|
supervisor=s6.
|
2016-02-02 00:12:58 +05:30
|
|
|
or set
|
|
|
|
supervisor=supervise-daemon
|
|
|
|
to use supervise-daemon.
|
|
|
|
Note that supervise-daemon is still in early development, so it is
|
|
|
|
considered experimental.
|
2015-05-12 04:37:28 +05:30
|
|
|
.It Ar s6_service_path
|
|
|
|
The path to the s6 service directory if you are monitoring this service
|
2015-05-14 01:17:35 +05:30
|
|
|
with S6. The default is /var/svc.d/${RC_SVCNAME}.
|
2015-05-12 04:37:28 +05:30
|
|
|
.It Ar s6_svwait_options_start
|
|
|
|
The options to pass to s6-svwait when starting the service via s6.
|
2015-05-14 22:10:29 +05:30
|
|
|
.It Ar s6_service_timeout_stop
|
|
|
|
The amount of time, in milliseconds, s6-svc should wait for the service
|
|
|
|
to go down when stopping the service. The default is 10000.
|
2011-12-30 20:29:42 +05:30
|
|
|
.It Ar start_stop_daemon_args
|
2011-12-30 22:05:16 +05:30
|
|
|
List of arguments passed to start-stop-daemon when starting the daemon.
|
2007-12-20 23:09:13 +05:30
|
|
|
.It Ar command
|
|
|
|
Daemon to start or stop via
|
|
|
|
.Nm start-stop-daemon
|
2016-02-02 00:12:58 +05:30
|
|
|
or
|
|
|
|
.Nm supervise-daemon
|
2007-12-20 23:09:13 +05:30
|
|
|
if no start or stop function is defined by the service.
|
|
|
|
.It Ar command_args
|
2015-05-12 02:07:30 +05:30
|
|
|
List of arguments to pass to the daemon when starting via
|
|
|
|
.Nm start-stop-daemon .
|
2016-09-14 00:32:10 +05:30
|
|
|
.It Ar command_args_background
|
|
|
|
This variable should be used if the daemon you are starting with
|
|
|
|
.Xr start-stop-daemon 8
|
|
|
|
runs in the foreground by default but has its own command line options
|
|
|
|
to request that it background and write a pid file. It should be set to
|
|
|
|
those options. It should not be used at the same time as
|
|
|
|
command_background, because command_background requests that
|
|
|
|
.Xr start-stop-daemon 8
|
|
|
|
go into the background before executing the daemon.
|
2016-02-02 00:12:58 +05:30
|
|
|
.It Ar command_args_foreground
|
|
|
|
List of arguments to pass to the daemon when starting via
|
|
|
|
.Nm supervise-daemon .
|
|
|
|
to force the daemon to stay in the foreground
|
2012-01-17 22:53:56 +05:30
|
|
|
.It Ar command_background
|
2016-09-14 00:32:10 +05:30
|
|
|
Set this to "true", "yes" or "1" (case-insensitive) if you want
|
|
|
|
.Xr start-stop-daemon 8
|
|
|
|
to force the daemon into the background. This forces the
|
|
|
|
"--make-pidfile" and "--pidfile" options, so the pidfile variable must be set.
|
2016-09-17 00:53:09 +05:30
|
|
|
.It Ar command_progress
|
|
|
|
Set this to "true", "yes" or "1" (case-insensitive) if you want
|
|
|
|
.Xr start-stop-daemon 8
|
|
|
|
to display a progress meter when waiting for a daemon to stop.
|
2016-09-14 00:32:10 +05:30
|
|
|
.It Ar command_user
|
|
|
|
If the daemon does not support changing to a different user id, you can
|
|
|
|
use this to change the user id before
|
2012-01-17 22:53:56 +05:30
|
|
|
.Xr start-stop-daemon 8
|
2016-09-14 00:32:10 +05:30
|
|
|
or
|
|
|
|
.Xr supervise-daemon 8
|
|
|
|
launches the daemon
|
2014-10-20 06:06:57 +05:30
|
|
|
.It Ar chroot
|
|
|
|
.Xr start-stop-daemon 8
|
2016-02-02 00:12:58 +05:30
|
|
|
and
|
|
|
|
.Xr supervise-daemon 8
|
2014-10-20 06:06:57 +05:30
|
|
|
will chroot into this path before writing the pid file or starting the daemon.
|
2007-12-20 23:09:13 +05:30
|
|
|
.It Ar pidfile
|
|
|
|
Pidfile to use for the above defined command.
|
|
|
|
.It Ar name
|
|
|
|
Display name used for the above defined command.
|
2016-06-23 18:10:45 +05:30
|
|
|
.It Ar procname
|
|
|
|
Process name to match when signaling the daemon.
|
2015-05-19 06:53:11 +05:30
|
|
|
.It Ar stopsig
|
|
|
|
Signal to send when stopping the daemon.
|
2011-12-31 07:11:59 +05:30
|
|
|
.It Ar retry
|
2011-12-31 09:21:05 +05:30
|
|
|
Retry schedule to use when stopping the daemon. It can either be a
|
|
|
|
timeout in seconds or multiple signal/timeout pairs (like SIGTERM/5).
|
2012-03-24 23:10:45 +05:30
|
|
|
.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.
|
2014-09-20 03:53:55 +05:30
|
|
|
.It Ar start_inactive
|
|
|
|
Set to yes to have the service marked inactive when it starts. This is
|
|
|
|
used along with in_background_fake to support re-entrant services.
|
|
|
|
.It Ar in_background_fake
|
|
|
|
Space separated list of commands which should always succeed when
|
|
|
|
in_background is yes.
|
2016-09-22 00:03:39 +05:30
|
|
|
.Pp
|
|
|
|
Keep in mind that eval is used to process chroot, command, command_args_*,
|
|
|
|
command_user, pidfile and procname. This may affect how they are
|
|
|
|
evvaluated depending on how they are quoted.
|
2007-12-20 23:09:13 +05:30
|
|
|
.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.
|
2008-11-04 19:58:51 +05:30
|
|
|
As it's a function it can be very flexible, see the example below.
|
2007-12-20 23:09:13 +05:30
|
|
|
Here is a list of the functions you can use in a
|
|
|
|
.Ic depend
|
2015-12-04 05:07:38 +05:30
|
|
|
function. You simply pass the names of the services you want to add to
|
|
|
|
that dependency type to the function, or prefix the names with ! to
|
|
|
|
remove them from the dependencies.
|
2012-01-22 05:47:42 +05:30
|
|
|
.Bl -tag -width "RC_DEFAULTLEVEL"
|
2007-12-20 23:09:13 +05:30
|
|
|
.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
|
2015-12-04 05:07:38 +05:30
|
|
|
The service will attempt to start any services it uses that have been added
|
2007-12-20 23:09:13 +05:30
|
|
|
to the runlevel.
|
2015-10-27 00:50:58 +05:30
|
|
|
.It Ic want
|
2015-12-04 05:07:38 +05:30
|
|
|
The service will attempt to start any services it wants, regardless of
|
|
|
|
whether they have been added to the runlevel.
|
2007-12-20 23:09:13 +05:30
|
|
|
.It Ic after
|
2010-01-08 14:09:25 +05:30
|
|
|
The service will start after these services and stop before these services.
|
2007-12-20 23:09:13 +05:30
|
|
|
.It Ic before
|
|
|
|
The service will start before these services and stop after these services.
|
|
|
|
.It Ic provide
|
2015-12-04 05:07:38 +05:30
|
|
|
The service provides this virtual service. For example, named provides dns.
|
2016-01-22 03:05:55 +05:30
|
|
|
Note that it is not legal to have a virtual and real service with the
|
|
|
|
same name. If you do this, you will receive an error message, and you
|
|
|
|
must rename either the real or virtual service.
|
2007-12-20 23:09:13 +05:30
|
|
|
.It Ic config
|
|
|
|
We should recalculate our dependencies if the listed files have changed.
|
2008-02-19 20:06:22 +05:30
|
|
|
.It Ic keyword
|
2012-09-25 22:39:45 +05:30
|
|
|
Tags a service with a keyword. These are the keywords we currently understand:
|
2008-02-19 19:45:53 +05:30
|
|
|
.Bl -tag -width indent
|
2009-07-01 04:37:32 +05:30
|
|
|
.It Dv -shutdown
|
2009-04-27 17:34:33 +05:30
|
|
|
Don't stop this service when shutting the system down.
|
2011-12-30 22:05:16 +05:30
|
|
|
This is normally quite safe as remaining daemons will be sent a SIGTERM just
|
2009-04-27 17:34:33 +05:30
|
|
|
before final shutdown.
|
|
|
|
Network related services such as the network and dhcpcd init scripts normally
|
|
|
|
have this keyword.
|
2009-07-01 04:37:32 +05:30
|
|
|
.It Dv -stop
|
2009-04-27 02:46:05 +05:30
|
|
|
Don't stop this service when changing runlevels, even if not present.
|
|
|
|
This includes shutting the system down.
|
2009-07-01 04:37:32 +05:30
|
|
|
.It Dv -timeout
|
2011-04-09 00:38:29 +05:30
|
|
|
Other services should wait indefinitely for this service to start. Use
|
|
|
|
this keyword if your service may take longer than 60 seconds to start.
|
2011-01-06 11:48:55 +05:30
|
|
|
.It Dv -jail
|
|
|
|
When in a jail, exclude this service from any dependencies. The service can
|
2012-01-22 05:47:42 +05:30
|
|
|
still be run directly. Set via
|
|
|
|
.Ic rc_sys
|
|
|
|
in
|
2011-01-06 11:48:55 +05:30
|
|
|
.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.
|
2012-07-03 08:34:22 +05:30
|
|
|
.It Dv -prefix
|
|
|
|
Same as -jail, but for Prefix systems.
|
2015-12-02 20:49:45 +05:30
|
|
|
.It Dv -rkt
|
|
|
|
Same as -jail, but for RKT systems.
|
2009-07-01 04:37:32 +05:30
|
|
|
.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.
|
2015-12-02 05:50:02 +05:30
|
|
|
.It Dv -docker
|
|
|
|
Same as -jail, but for docker systems.
|
2015-12-04 01:39:38 +05:30
|
|
|
.It Dv -containers
|
|
|
|
Same as -jail, but for all relevant container types on the operating
|
|
|
|
system.
|
2008-02-19 19:45:53 +05:30
|
|
|
.El
|
2007-12-20 23:09:13 +05:30
|
|
|
.El
|
2008-01-30 19:37:45 +05:30
|
|
|
.Pp
|
|
|
|
To see how to influence dependencies in configuration files, see the
|
|
|
|
.Sx FILES
|
|
|
|
section below.
|
2007-12-20 23:09:13 +05:30
|
|
|
.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
|
2008-06-03 17:27:15 +05:30
|
|
|
at the end of the line.
|
|
|
|
Otherwise output ok in square brackets at the end of the line.
|
|
|
|
The value of
|
2007-12-20 23:09:13 +05:30
|
|
|
.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
|
2008-06-03 17:27:15 +05:30
|
|
|
.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
|
2011-12-30 22:05:16 +05:30
|
|
|
is less than 1 then we wait indefinitely.
|
2008-01-18 19:47:58 +05:30
|
|
|
.It Ic is_newer_than Ar file1 Ar file2 ...
|
|
|
|
If
|
|
|
|
.Ar file1
|
|
|
|
is newer than
|
|
|
|
.Ar file2
|
|
|
|
return 0, otherwise 1.
|
|
|
|
If
|
|
|
|
.Ar file2
|
2010-01-08 14:09:25 +05:30
|
|
|
is a directory, then check all its contents too.
|
2008-01-18 19:47:58 +05:30
|
|
|
.It Ic is_older_than Ar file1 Ar file2 ...
|
|
|
|
If
|
|
|
|
.Ar file1
|
2008-07-03 19:00:17 +05:30
|
|
|
is newer than
|
2008-01-18 19:47:58 +05:30
|
|
|
.Ar file2
|
|
|
|
return 0, otherwise 1.
|
|
|
|
If
|
|
|
|
.Ar file2
|
2010-01-08 14:09:25 +05:30
|
|
|
is a directory, then check all its contents too.
|
2007-12-20 23:09:13 +05:30
|
|
|
.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
|
2012-01-10 08:50:47 +05:30
|
|
|
.Op Fl D , -directory-truncate
|
2007-12-20 23:09:13 +05:30
|
|
|
.Op Fl d , -directory
|
2012-01-10 08:50:47 +05:30
|
|
|
.Op Fl F , -file-truncate
|
2007-12-20 23:09:13 +05:30
|
|
|
.Op Fl f , -file
|
2012-01-10 08:50:47 +05:30
|
|
|
.Op Fl p , -pipe
|
2007-12-20 23:09:13 +05:30
|
|
|
.Op Fl m , -mode Ar mode
|
2014-07-12 03:03:42 +05:30
|
|
|
.Op Fl o , -owner Ar owner
|
2014-07-13 21:45:26 +05:30
|
|
|
.Op Fl W , -writable
|
2014-02-16 05:38:23 +05:30
|
|
|
.Op Fl q , -quiet
|
2007-12-20 23:09:13 +05:30
|
|
|
.Ar path ...
|
|
|
|
.Xc
|
2014-07-13 21:45:26 +05:30
|
|
|
If -d, -f or -p is specified, checkpath checks to see if the path
|
|
|
|
exists, is the right type and has the correct owner and access modes. If
|
|
|
|
any of these tests fail, the path is created and set up as specified. If
|
|
|
|
more than one of -d, -f or -p are specified, the last one will be used.
|
2014-02-16 05:38:23 +05:30
|
|
|
|
2014-07-13 21:45:26 +05:30
|
|
|
The argument to -m is a three or four digit octal number. If this option
|
|
|
|
is not provided, the value defaults to 0644 for files and 0775 for
|
|
|
|
directories.
|
2014-02-16 05:38:23 +05:30
|
|
|
|
2014-07-13 21:45:26 +05:30
|
|
|
The argument to -o is a representation of the user and/or group which
|
|
|
|
should own the path. The user and group can be represented numerically
|
|
|
|
or with names, and are separated by a colon.
|
2014-02-16 05:38:23 +05:30
|
|
|
|
2014-07-13 21:45:26 +05:30
|
|
|
The truncate options (-D and -F) cause the directory or file to be
|
|
|
|
cleared of all contents.
|
2014-02-16 05:38:23 +05:30
|
|
|
|
2014-07-13 21:45:26 +05:30
|
|
|
If -W is specified, checkpath checks to see if the first path given on
|
|
|
|
the command line is writable. This is different from how the test
|
|
|
|
command in the shell works, because it also checks to make sure the file
|
|
|
|
system is not read only.
|
|
|
|
|
|
|
|
Also, the -d, -f or -p options should not be specified along with this option.
|
|
|
|
|
|
|
|
The -q option suppresses all informational output. If it is specified
|
|
|
|
twice, all error messages are suppressed as well.
|
2008-01-18 19:47:58 +05:30
|
|
|
.It Ic yesno Ar value
|
|
|
|
If
|
|
|
|
.Ar value
|
|
|
|
matches YES, TRUE, ON or 1 regardless of case then we return 0, otherwise 1.
|
2007-12-20 23:09:13 +05:30
|
|
|
.El
|
|
|
|
.Sh ENVIRONMENT
|
|
|
|
.Nm
|
|
|
|
sets the following environment variables for use in the service scripts:
|
2012-01-22 05:47:42 +05:30
|
|
|
.Bl -tag -width "RC_DEFAULTLEVEL"
|
2008-03-20 01:27:24 +05:30
|
|
|
.It Va RC_SVCNAME
|
2007-12-20 23:09:13 +05:30
|
|
|
Name of the service.
|
2014-01-09 00:46:27 +05:30
|
|
|
.It Va RC_SERVICE
|
|
|
|
Full path to the service.
|
2008-03-19 22:41:50 +05:30
|
|
|
.It Va RC_RUNLEVEL
|
2013-12-12 05:09:38 +05:30
|
|
|
Current runlevel that OpenRC is in. Note that, in OpenRC, the reboot
|
2012-02-20 00:41:11 +05:30
|
|
|
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.
|
2012-02-20 00:19:53 +05:30
|
|
|
.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.
|
2007-12-20 23:09:13 +05:30
|
|
|
.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.
|
2008-03-03 22:49:56 +05:30
|
|
|
Possible values are OPENVZ, XENU, XEN0, UML and VSERVER.
|
2012-09-10 08:52:15 +05:30
|
|
|
.It Va RC_PREFIX
|
|
|
|
In a Gentoo Prefix installation, this variable contains the prefix
|
|
|
|
offset. Otherwise it is undefined.
|
2007-12-20 23:09:13 +05:30
|
|
|
.It Va RC_UNAME
|
|
|
|
The result of `uname -s`.
|
2012-09-22 20:27:46 +05:30
|
|
|
.It Va RC_CMD
|
2012-09-25 22:39:45 +05:30
|
|
|
This contains the name of the command the service script is executing, such
|
2013-08-13 22:42:43 +05:30
|
|
|
as start, stop, restart etc. One example of using this is to make a
|
|
|
|
service script behave differently when restart is being executed.
|
2014-01-09 00:46:27 +05:30
|
|
|
.It Va RC_GOINGDOWN
|
|
|
|
This variable contains YES if the system is going into single user mode
|
|
|
|
or shutting down.
|
|
|
|
.It Va RC_LIBEXECDIR
|
|
|
|
The value of libexecdir which OpenRC was configured with during build
|
|
|
|
time.
|
|
|
|
.It Va RC_NO_UMOUNTS
|
|
|
|
This variable is used by plugins to contain a list of directories which
|
|
|
|
should not be unmounted.
|
2007-12-20 23:09:13 +05:30
|
|
|
.El
|
|
|
|
.Sh FILES
|
|
|
|
.Pp
|
|
|
|
Configuration files, relative to the location of the service.
|
2008-03-19 22:41:50 +05:30
|
|
|
If a file ending with .${RC_RUNLEVEL} exists then we use that instead.
|
2007-12-20 23:09:13 +05:30
|
|
|
.Bl -ohang
|
2008-03-20 01:27:24 +05:30
|
|
|
.It Pa ../conf.d/${RC_SVCNAME%%.*}
|
2010-01-08 14:09:25 +05:30
|
|
|
multiplexed configuration file.
|
2008-03-20 01:27:24 +05:30
|
|
|
Example: if ${RC_SVCNAME} is net.eth1 then look for
|
2007-12-20 23:09:13 +05:30
|
|
|
.Pa ../conf.d/net .
|
2008-03-20 01:27:24 +05:30
|
|
|
.It Pa ../conf.d/${RC_SVCNAME}
|
2007-12-20 23:09:13 +05:30
|
|
|
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_.
|
2008-01-30 19:37:45 +05:30
|
|
|
Examples:
|
2007-12-20 23:09:13 +05:30
|
|
|
.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"
|
2008-01-30 19:37:45 +05:30
|
|
|
# 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"
|
2008-03-04 16:10:31 +05:30
|
|
|
|
2012-07-03 08:34:22 +05:30
|
|
|
# It's also possible to negate keywords. This is mainly useful for prefix
|
|
|
|
# users testing OpenRC.
|
|
|
|
rc_keyword="!-prefix"
|
2015-12-04 05:07:38 +05:30
|
|
|
# This can also be used to block a script from runining in all
|
|
|
|
# containers except one or two
|
|
|
|
rc_keyword="!-containers !-docker"
|
2007-12-20 23:09:13 +05:30
|
|
|
.Ed
|
|
|
|
.Sh EXAMPLES
|
|
|
|
.Pp
|
|
|
|
An example service script for foo.
|
|
|
|
.Bd -literal -offset indent
|
2013-12-22 02:21:11 +05:30
|
|
|
#!/sbin/openrc-run
|
2007-12-20 23:09:13 +05:30
|
|
|
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"
|
|
|
|
|
2008-01-18 19:47:58 +05:30
|
|
|
_need_dbus()
|
|
|
|
{
|
2007-12-20 23:09:13 +05:30
|
|
|
grep -q dbus /etc/foo/plugins
|
|
|
|
}
|
|
|
|
|
2008-01-18 19:47:58 +05:30
|
|
|
depend()
|
|
|
|
{
|
2007-12-20 23:09:13 +05:30
|
|
|
# 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
|
2012-01-22 05:47:42 +05:30
|
|
|
_need="${_need} dbus"
|
2007-12-20 23:09:13 +05:30
|
|
|
fi
|
|
|
|
fi
|
|
|
|
need ${_need}
|
|
|
|
}
|
|
|
|
|
2012-09-24 05:55:57 +05:30
|
|
|
# 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.
|
2008-01-18 19:47:58 +05:30
|
|
|
start_pre()
|
|
|
|
{
|
2012-10-17 00:58:45 +05:30
|
|
|
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
|
2007-12-20 23:09:13 +05:30
|
|
|
# Ensure that our dirs are correct
|
2013-08-15 20:44:42 +05:30
|
|
|
checkpath --directory --owner foo:foo --mode 0775 \\
|
2007-12-20 23:09:13 +05:30
|
|
|
/var/run/foo /var/cache/foo
|
|
|
|
}
|
|
|
|
|
2008-01-18 19:47:58 +05:30
|
|
|
start_post()
|
|
|
|
{
|
2007-12-20 23:09:13 +05:30
|
|
|
# Save our need
|
|
|
|
if _need_dbus; then
|
|
|
|
service_set_value need dbus
|
|
|
|
fi
|
|
|
|
}
|
|
|
|
|
|
|
|
stop_post() {
|
|
|
|
# Clean any spills
|
|
|
|
rm -rf /var/cache/foo/*
|
|
|
|
}
|
|
|
|
|
2008-01-18 19:47:58 +05:30
|
|
|
drink()
|
|
|
|
{
|
2007-12-20 23:09:13 +05:30
|
|
|
ebegin "Starting to drink"
|
|
|
|
${command} --drink beer
|
|
|
|
eend $? "Failed to drink any beer :("
|
|
|
|
}
|
|
|
|
|
2008-01-18 19:47:58 +05:30
|
|
|
eat()
|
|
|
|
{
|
2007-12-20 23:09:13 +05:30
|
|
|
local result=0 retval= ate= food=
|
|
|
|
ebegin "Starting to eat"
|
2008-01-18 19:47:58 +05:30
|
|
|
|
|
|
|
if yesno "${foo_diet}"; then
|
|
|
|
eend 1 "We are on a diet!"
|
|
|
|
return 1
|
|
|
|
fi
|
|
|
|
|
2007-12-20 23:09:13 +05:30
|
|
|
for food in /usr/share/food/*; do
|
|
|
|
veinfo "Eating `basename ${food}`"
|
|
|
|
${command} --eat ${food}
|
|
|
|
retval=$?
|
2011-11-11 08:16:08 +05:30
|
|
|
: $(( result += retval ))
|
2007-12-20 23:09:13 +05:30
|
|
|
[ ${retval} = 0 ] && ate="${ate} `basename ${food}`"
|
|
|
|
done
|
2008-01-18 19:47:58 +05:30
|
|
|
|
2007-12-20 23:09:13 +05:30
|
|
|
if eend ${result} "Failed to eat all the food"; then
|
|
|
|
service_set_value ate "${ate}"
|
|
|
|
fi
|
|
|
|
}
|
|
|
|
|
2008-01-18 19:47:58 +05:30
|
|
|
show()
|
|
|
|
{
|
2007-12-20 23:09:13 +05:30
|
|
|
einfo "Foo has eaten: `service_get_value ate`"
|
|
|
|
}
|
|
|
|
|
|
|
|
.Ed
|
2008-07-03 19:00:17 +05:30
|
|
|
.Sh BUGS
|
2011-12-11 12:48:08 +05:30
|
|
|
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
|
2008-07-03 19:00:17 +05:30
|
|
|
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.
|
2007-12-20 23:09:13 +05:30
|
|
|
.Sh SEE ALSO
|
2007-12-24 17:18:33 +05:30
|
|
|
.Xr einfo 3 ,
|
2013-12-12 05:09:38 +05:30
|
|
|
.Xr openrc 8 ,
|
2007-12-20 23:09:13 +05:30
|
|
|
.Xr rc-status 8 ,
|
|
|
|
.Xr rc-update 8 ,
|
2007-12-25 03:33:27 +05:30
|
|
|
.Xr rc_plugin_hook 3 ,
|
2007-12-20 23:09:13 +05:30
|
|
|
.Xr sh 1p ,
|
|
|
|
.Xr start-stop-daemon 8 ,
|
|
|
|
.Xr uname 1
|
|
|
|
.Sh AUTHORS
|
2008-12-31 00:38:51 +05:30
|
|
|
.An Roy Marples <roy@marples.name>
|