Run the
argument method for the current
rc.d(8) script, based on the settings of various shell variables.
run_rc_command is extremely flexible, and allows fully functional
rc.d(8) scripts to be implemented in a small amount of shell code. The optional set of parameters is passed verbatim to the command, but not to its pre/post hooks.
argument is searched for in the list of supported commands, which may be one of:
start
Start the service. This should check that the service is to be started as specified by
rc.conf(5). Also checks if the service is already running and refuses to start if it is. This latter check is not performed by standard
NetBSD scripts if the system is starting directly to multi-user mode, to speed up the boot process.
stop
If the service is to be started as specified by
rc.conf(5), stop the service. This should check that the service is running and complain if it's not.
restart
Perform a stop then a start. Defaults to displaying the process ID of the program (if running).
rcvar
Display which
rc.conf(5) variables are used to control the startup of the service (if any).
If
pidfile or
procname is set, also support:
poll
Wait for the command to exit.
status
Show the status of the process.
Other supported commands are listed in the optional variable
extra_commands.
argument may have one of the following prefixes which alters its operation:
fast
Skip the check for an existing running process, and sets rc_fast=YES.
force
Skip the checks for rcvar being set to yes, and sets rc_force=YES. This ignores argument_precmd returning non-zero, and ignores any of the required_* tests failing, and always returns a zero exit status.
one
Skip the checks for rcvar being set to yes, but performs all the other prerequisite tests.
run_rc_command uses the following shell variables to control its behaviour. Unless otherwise stated, these are optional.
name
The name of this script. This is not optional.
rcvar
The value of rcvar is checked with checkyesno to determine if this method should be run.
rcvar_manpage
The manual page containing information about
rcvar. It will be part of the warning message shown when
rcvar is undefined. Defaults to
rc.conf(5).
command
Full path to the command. Not required if argument_cmd is defined for each supported keyword.
command_args
Optional arguments and/or shell directives for command.
command_interpreter
command is started with
#! command_interpreter [...]
which results in its
ps(1) command being
command_interpreter [...] command
so use that string to find the PID(s) of the running command rather than ‘command'.
extra_commands
Extra commands/keywords/arguments supported.
pidfile
Path to pid file. Used to determine the PID(s) of the running command. If
pidfile is set, use
check_pidfile $pidfile $procname
to find the PID. Otherwise, if
command is set, use
check_process $procname
to find the PID.
procname
Process name to check for. Defaults to the value of command.
required_dirs
Check for the existence of the listed directories before running the default start method.
required_files
Check for the readability of the listed files before running the default start method.
required_vars
Perform checkyesno on each of the list variables before running the default start method.
${name}_chdir
Directory to cd to before running command, if ${name}_chroot is not provided.
${name}_chroot
Directory to
chroot(8) to before running
command. Only supported after
/usr is mounted.
${name}_env
List of additional or modified environment variables to set when starting command.
${name}_flags
Arguments to call
command with. This is usually set in
rc.conf(5), and not in the
rc.d(8) script. The environment variable ‘
flags' can be used to override this.
${name}_nice
nice(1) level to run
command as. Only supported after
/usr is mounted.
${name}_user
User to run
command as, using
chroot(8). if
${name}_chroot is set, otherwise uses
su(1). Only supported after
/usr is mounted.
${name}_group
Group to run the chrooted command as.
${name}_groups
Comma separated list of supplementary groups to run the chrooted command with.
argument_cmd
Shell commands which override the default method for argument.
argument_precmd
Shell commands to run just before running argument_cmd or the default method for argument. If this returns a non-zero exit code, the main method is not performed. If the default method is being executed, this check is performed after the required_* checks and process (non-)existence checks.
argument_postcmd
Shell commands to run if running argument_cmd or the default method for argument returned a zero exit code.
sig_stop
Signal to send the processes to stop in the default stop method. Defaults to SIGTERM.
sig_reload
Signal to send the processes to reload in the default reload method. Defaults to SIGHUP.
For a given method
argument, if
argument_cmd is not defined, then a default method is provided by
run_rc_command:
start
If command is not running and checkyesno rcvar succeeds, start command.
stop
Determine the PIDs of command with check_pidfile or check_process (as appropriate), kill sig_stop those PIDs, and run wait_for_pids on those PIDs.
reload
Similar to stop, except that it uses sig_reload instead, and doesn't run wait_for_pids.
restart
Runs the stop method, then the start method.
status
Show the PID of command, or some other script specific status operation.
poll
Wait for command to exit.
rcvar
Display which
rc.conf(5) variable is used (if any). This method always works, even if the appropriate
rc.conf(5) variable is set to ‘NO'.
The following variables are available to the methods (such as
argument_cmd) as well as after
run_rc_command has completed:
rc_arg
Argument provided to run_rc_command, after fast and force processing has been performed.
rc_flags
Flags to start the default command with. Defaults to ${name}_flags, unless overridden by the environment variable ‘flags'. This variable may be changed by the argument_precmd method.
rc_pid
PID of command (if appropriate).
rc_fast
Not empty if “fast” prefix was used.
rc_force
Not empty if “force” prefix was used.