GeezerVison is showing man.openbsd.org — rc.subr(8) - OpenBSD manual pages
rc.subr —
daemon control scripts
routines
daemon=path_to_executable |
|
Apart from a few notable exceptions, rc scripts must follow this
naming policy:
- When possible, use the same name as the
daemon it
is referring to.
- It must follow ksh(1) variable naming: begin with an alphabetic or underscore
character, followed by one or more alphanumeric or underscore characters.
Dashes (‘-’) have to be converted to underscores
(‘_’).
Every script under /etc/rc.d follows this
pattern:
- Define the daemon variable.
- Define service-specific defaults for one or more
daemon_* variables (optional).
- Source
rc.subr, which defines default shell
functions and variable values.
- Override the pexp variable or any of the
rc_* functions and set the
rc_bg or rc_reload variables,
if needed.
- Define an
rc_pre and/or
rc_post function, if needed.
- Call the
rc_cmd function as “rc_cmd
$1”.
The following shell functions are defined by
rc.subr:
rc_check- Search for processes of the service with
pgrep(1)
using the regular expression given in the pexp
variable.
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_${action} 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. Similarly, the special variable
rc_usercheck must be set to “NO” if
the check action requires
root privileges.
The action argument can be
start, stop,
reload, restart, or
check:
check- Call
rc_check. Return 0 if the daemon is
running or 1 if it is not.
start- Check that the service is running by calling
rc_check. If it's not running, call
rc_pre if it exists, then
rc_start.
stop- Check that the service is running by calling
rc_check. If it is running, call
rc_stop and wait up to 30 seconds for the
daemon to properly shutdown. If successful, run
rc_post if it exists.
restart- Run the action argument
stop, then if successful run
start.
reload- Check that the service is running by calling
rc_check. If it is running, call
rc_reload.
rc_configtest- Check daemon configuration before running
start,
reload and restart if
implemented by the rc.d(8) script.
rc_exec- Execute argument using su(1) according to daemon_class,
daemon_execdir, daemon_user,
daemon_rtable and
daemon_logger values.
rc_post- This function is run after
stop if implemented by
the rc.d(8)
script.
rc_pre- This function is run before
start if implemented
by the rc.d(8) script.
rc_reload- Send the rc_reload_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, i.e. that it will reload its
configuration.
rc_start- Start the daemon. Defaults to:
rc_exec "${daemon} ${daemon_flags}"
rc_stop- Stop the daemon. Send the rc_stop_signal using
pkill(1)
on the regular expression given in the pexp
variable.
rc_cmd uses the following shell variables
to control its behaviour.
- daemon
- The path to the daemon, optionally followed by one or more whitespace
separated arguments. Arguments included here are always used, even if
daemon_flags is empty. This variable is required. It
is an error to source
rc.subr without defining
daemon first.
- 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.
- daemon_execdir
- Change to this directory before running
rc_exec.
- daemon_flags
- Arguments to call the daemon with.
- daemon_logger
- Redirect standard output and error to
logger(1) using the configured priority (e.g.
"daemon.info").
- daemon_rtable
- Routing table to run the daemon under, using
route(8).
- daemon_timeout
- Maximum time in seconds to wait for the
start,
stop and reload actions to
return. This is only guaranteed with the default
rc_start, rc_stop and
rc_reload functions.
- daemon_user
- User to run the daemon as, using
su(1).
- pexp
- A regular expression to be passed to
pgrep(1)
in order to find the desired process or to be passed to
pkill(1)
to stop it. 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_bg
- Can be set to
YES in an
rc.d script to force starting the daemon in
background when using the default rc_start.
- rc_reload
- Can be set to “NO” in an
rc.d script
to disable the reload action if the respective daemon does not support
reloading its configuration.
The same is
possible, but almost never useful, for other actions.
- rc_reload_signal
- Signal sent to the daemon process (pexp) by the
default
rc_reload() function. Defaults to
HUP.
- rc_stop_signal
- Signal sent to the daemon process (pexp) by the
default
rc_stop() function. Default to
TERM.
- rc_usercheck
- Can be set to “NO” in an
rc.d
script, if the check action needs root
privileges.
All daemon_* variables are set in the
following ways:
- Global defaults are provided by
rc.subr:
daemon_class=daemon
daemon_execdir=
daemon_flags=
daemon_logger=
daemon_rtable=0
daemon_timeout=30
daemon_user=root
- Service-specific defaults may be provided in the respective
rc.d script
before sourcing
rc.subr, thus overriding the global defaults.
- As noted in rc.d(8), site-specific values provided in
rc.conf.local(8) for daemon_execdir,
daemon_flags, daemon_logger,
daemon_rtable, daemon_timeout,
and daemon_user will override those defaults.
- /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.
The rc.subr framework first appeared in
OpenBSD 4.9.
|