RC.SUBR(8) FreeBSD System Manager's Manual RC.SUBR(8)
NAME
rc.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 this naming
policy:
1. When possible, use the same name as the daemon it is referring to.
2. 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:
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 variable or any of the rc_* functions and set the
rc_bg or rc_reload variables, 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_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.
ENVIRONMENT
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:
1. 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
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_execdir, daemon_flags, daemon_logger,
daemon_rtable, daemon_timeout, 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 ALSO
rc(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 <
[email protected]>,
Antoine Jacoutot <
[email protected]>, and Ingo Schwarze
<
[email protected]>.
FreeBSD 14.1-RELEASE-p8 October 22, 2022 FreeBSD 14.1-RELEASE-p8