[OpenBSD]

Manual Page Search Parameters
RC.SUBR(8) System Manager's Manual RC.SUBR(8)

NAME

rc.subrdaemon 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_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_check
Search for processes of the service with pgrep(1) using the regular expression given in the pexp variable.
 
 
rc_start
Start the daemon. Defaults to:
${rcexec} "${daemon} ${daemon_flags} ${_bg}"
    
 
 
rc_stop
Stop the daemon. Send a SIGTERM signal using pkill(1) on the regular expression given in the pexp variable.
 
 
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, i.e. that it will reload its configuration.

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_flags
Arguments to call the daemon with.
 
 
daemon_rtable
Routing table to run the daemon under, using route(8).
 
 
daemon_timeout
Maximum time in seconds to wait for the start (only if rc_bg is set), 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_usercheck
Can be set to “NO” in an rc.d script, if the check action needs root privileges.
 
 
rcexec
Holds the full su(1) command used to run the daemon. Defaults to:
su -l -c ${daemon_class} -s /bin/sh ${daemon_user} -c
If daemon_rtable is set, the following route(8) command is prepended to rcexec:
route -T ${daemon_rtable}
All daemon_* variables are set in the following ways:
  1. Global defaults are provided by rc.subr:
    daemon_class=daemon 
    daemon_flags= 
    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_flags, 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 <robert@openbsd.org>, Antoine Jacoutot <ajacoutot@openbsd.org>, and Ingo Schwarze <schwarze@openbsd.org>.
September 7, 2016 OpenBSD-current