RC.SUBR(8) OpenBSD System Manager's Manual RC.SUBR(8)NAMErc.subr - daemon control scripts routines
SYNOPSIS
daemon=path_to_executable
. /etc/rc.d/rc.subr
rc_cmd action
DESCRIPTION
Apart from a few notable exceptions, rc scripts must follow the following
naming policy:
1. Use the same name as the daemon it is referring to.
2. dashes have to be converted to underscores.
Every script under /etc/rc.d follows the following pattern:
1. Define the daemon variable.
2. Define service-specific defaults for one or more daemon_* variables
(optional).
3. Source rc.subr, which defines default shell functions and variable
values.
4. Override the pexp or rc_reload variables or any of the rc_*
functions, if needed.
5. Define an rc_pre and/or rc_post function, if needed.
6. Call the rc_cmd function as ``rc_cmd $1''.
The following shell functions are defined by rc.subr:
rc_cmd action
Run the action for the current rc.d script, based on the
settings of various shell variables. rc_cmd is extremely
flexible, and allows fully functional rc.d scripts to be
implemented in a small amount of shell code. For a given
action, if the rc_${action}() function is not defined, then a
default function is provided by rc.subr. In addition actions
can be disabled by setting the rc_${name} variable to NO.
For example, if rc_reload=NO is set in the rc.d script, and
rc_cmd is called for the reload action, an error will be
raised.
The action argument can be start, stop, reload, restart, or
check, each running one of the functions described below.
rc_start Check whether the service is already running by calling
rc_check, If it's not running, call rc_pre() if it exists,
then start the daemon.
rc_stop Check that the service is running by calling rc_check. If it
is running, stop the daemon, then call rc_post() if it
exists.
rc_reload Send a SIGHUP signal using pkill(1) on the regular expression
given in the pexp variable. One has to make sure that
sending SIGHUP to a daemon will have the desired effect, that
is, that it will reload its configuration.
rc_restart Perform a stop then a start.
rc_check Return 0 if the daemon is running or 1 if it is not.
ENVIRONMENT
rc_cmd uses the following shell variables to control its behaviour.
daemon The path to the daemon. This variable is required. It is
an error to source rc.subr without defining daemon first.
daemon_flags Arguments to call daemon with.
daemon_user User to run daemon as, using su(1).
daemon_class Login class to run the daemon with, using su(1). This is a
read only variable that gets set by rc.subr itself. It
searches login.conf(5) for a login class that has the same
name as the rc.d script itself and uses that. If no such
login class exists then daemon will be used.
pexp A regular expression to be passed to pgrep(1) or pkill(1)
in order to find the desired process. By default this
variable contains the daemon and daemon_flags variables.
To override the default value, an rc.d script has to
redefine this variable after sourcing rc.subr.
rc_reload Can be set to NO in an rc.d script to disable the reload
action if the respective daemon does not support the SIGHUP
signal to reload its configuration. The same is possible,
but almost never useful, for other actions.
rcexec Holds the full su(1) arguments used to run daemon.
Defaults to: su -l -c ${daemon_class} -s /bin/sh
${daemon_user} -c.
All daemon_* variables are set in the following ways:
1. Global defaults are provided by rc.subr:
daemon_class=daemon
daemon_flags=""
daemon_user=root
2. Service-specific defaults may be provided in the respective rc.d
script before sourcing rc.subr, thus overriding the global defaults.
3. As noted in rc.d(8), site-specific values provided in
rc.conf.local(8) for daemon_flags and daemon_user will override
those defaults.
FILES
/etc/rc.d/
Directory containing daemon control scripts.
/etc/rc.d/rc.subr
Functions and variables used by rc.d scripts.
/usr/ports/infrastructure/templates/rc.template
A sample rc.d script.
SEE ALSOrc(8), rc.conf(8), rc.d(8)HISTORY
The rc.subr framework first appeared in OpenBSD 4.9.
AUTHORS
The rc.subr framework was written by Robert Nagy <robert@openbsd.org>,
Antoine Jacoutot <ajacoutot@openbsd.org>, and Ingo Schwarze
<schwarze@openbsd.org>.
OpenBSD 4.9 February 24, 2011 OpenBSD 4.9
