diff options
Diffstat (limited to 'static/netbsd/man8/rc.subr.8')
| -rw-r--r-- | static/netbsd/man8/rc.subr.8 | 865 |
1 files changed, 865 insertions, 0 deletions
diff --git a/static/netbsd/man8/rc.subr.8 b/static/netbsd/man8/rc.subr.8 new file mode 100644 index 00000000..93d49d24 --- /dev/null +++ b/static/netbsd/man8/rc.subr.8 @@ -0,0 +1,865 @@ +.\" $NetBSD: rc.subr.8,v 1.32 2021/01/10 19:26:31 riastradh Exp $ +.\" +.\" Copyright (c) 2002-2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd December 17, 2012 +.Dt RC.SUBR 8 +.Os +.Sh NAME +.Nm rc.subr +.Nd functions used by system shell scripts +.Sh SYNOPSIS +.Bl -item +.It +.Li . /etc/rc.subr +.It +.Ic backup_file Ar action Ar file Ar current Ar backup +.It +.Ic basename Ar file Op Ar suffix +.It +.Ic checkyesno Ar var +.It +.Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter +.It +.Ic check_process Ar procname Op Ar interpreter +.It +.Ic collapse_backslash_newline +.It +.Ic dirname Ar file +.It +.Ic err Ar exitval Ar message +.It +.Ic load_rc_config Ar command +.It +.Ic load_rc_config_var Ar command Ar var +.It +.Ic mount_critical_filesystems Ar type +.It +.Ic no_rc_postprocess Ar command Op Ar arguments +.It +.Ic print_rc_metadata Ar string +.It +.Ic print_rc_normal Oo Fl n Oc Ar string +.It +.Ic rc_usage Ar command Op Ar ... +.It +.Ic reverse_list Ar item Op Ar ... +.It +.Ic run_rc_command Ar argument [parameters] +.It +.Ic run_rc_script Ar file Ar argument +.It +.Ic stop_boot +.It +.Ic twiddle +.It +.Ic wait_for_pids Op Ar pid Op Ar ... +.It +.Ic warn Ar message +.It +.Ic yesno_to_truefalse Ar var +.El +.Sh DESCRIPTION +.Nm +contains commonly used shell script functions which are used by +various scripts such as +.Xr rc 8 , +and the periodic system services which are controlled by +.Xr daily.conf 5 , +.Xr monthly.conf 5 , +.Xr security.conf 5 , +and +.Xr weekly.conf 5 . +.Pp +The +.Nm +functions are accessed by sourcing +.Pa /etc/rc.subr +into the current shell. +.Pp +The following shell functions are available: +.Bl -tag -width 4n +.It Ic backup_file Ar action Ar file Ar current Ar backup +Make a backup copy of +.Ar file +into +.Ar current . +If the +.Xr rc.conf 5 +variable +.Sy backup_uses_rcs +is +.Sq YES , +use +.Xr rcs 1 +to archive the previous version of +.Ar current , +otherwise save the previous version of +.Ar current +as +.Ar backup . +.Pp +.Ar action +may be one of the following: +.Bl -tag -width remove +.It Sy add +.Ar file +is now being backed up by or possibly re-entered into this backup mechanism. +.Ar current +is created, and if necessary, the +.Xr rcs 1 +files are created as well. +.It Sy update +.Ar file +has changed and needs to be backed up. +If +.Ar current +exists, it is copied to +.Ar backup +or checked into +.Xr rcs 1 +(if the repository file is old), +and then +.Ar file +is copied to +.Ar current . +.It Sy remove +.Ar file +is no longer being tracked by this backup mechanism. +If +.Xr rcs 1 +is being used, an empty file is checked in and +.Ar current +is removed, +otherwise +.Ar current +is moved to +.Ar backup . +.El +.It Ic basename Ar file Op Ar suffix +Just like +.Xr basename 1 , +except implemented using shell built-in commands, and usable before the +.Pa /usr/bin +direcory is available. +.It Ic checkyesno Ar var +Return 0 if +.Ar var +is defined to +.Sq YES , +.Sq TRUE , +.Sq ON , +or +.Sq 1 . +Return 1 if +.Ar var +is defined to +.Sq NO , +.Sq FALSE , +.Sq OFF , +or +.Sq 0 . +Otherwise, warn that +.Ar var +is not set correctly. +The values are case insensitive. +.Pp +Note that the warning message shown by this function when +.Ar var +is not set references a manual page where the user can find more information. +Its name is picked up from the +.Sy rcvar_manpage +variable. +.It Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter +Parses the first word of the first line of +.Ar pidfile +for a PID, and ensures that the process with that PID +is running and its first argument matches +.Ar procname . +Prints the matching PID if successful, otherwise nothing. +If +.Ar interpreter +is provided, parse the first line of +.Ar procname , +ensure that the line is of the form +.Dl #! interpreter [...] +and use +.Ar interpreter +with its optional arguments and +.Ar procname +appended as the process string to search for. +.It Ic check_process Ar procname Op Ar interpreter +Prints the PIDs of any processes that are running with a first +argument that matches +.Ar procname . +.Ar interpreter +is handled as per +.Ic check_pidfile . +.It Ic collapse_backslash_newline +Copy input to output, collapsing +.Ao backslash Ac Ns Ao newline Ac +to nothing, but leaving other backslashes alone. +.Ic dirname Ar file +Just like +.Xr dirname 1 , +except implemented using shell built-in commands, and usable before the +.Pa /usr/bin +direcory is available. +.It Ic err Ar exitval Ar message +Display an error message to +.Em stderr , +log it to the system log +using +.Xr logger 1 , +and +.Cm exit +with an exit value of +.Ar exitval . +The error message consists of the script name +(from +.Sy $0 ) , +followed by +.Dq ": ERROR: " , +and then +.Ar message . +.It Ic load_rc_config Ar command +Source in the +.Xr rc.conf 5 +configuration files for +.Ar command . +First, +.Pa /etc/rc.conf +is sourced if it has not yet been read in. +Then, +.Pa /etc/rc.conf.d/ Ns Ar command +is sourced if it is an existing file. +The latter may also contain other variable assignments to override +.Ic run_rc_command +arguments defined by the calling script, to provide an easy +mechanism for an administrator to override the behaviour of a given +.Xr rc.d 8 +script without requiring the editing of that script. +.It Ic load_rc_config_var Ar command Ar var +Read the +.Xr rc.conf 5 +variable +.Ar var +for +.Ar command +and set in the current shell, using +.Ic load_rc_config +in a sub-shell to prevent unwanted side effects from other variable +assignments. +.It Ic mount_critical_filesystems Ar type +Go through a list of critical file systems, +as found in the +.Xr rc.conf 5 +variable +.Sy critical_filesystems_ Ns Ar type , +mounting each one that +is not currently mounted. +.It Ic no_rc_postprocess Ar command Op Ar arguments +Execute the specified command with the specified arguments, +in such a way that its output bypasses the post-processor that +.Xr rc 8 +uses for most commands. +This implies that the output will not appear in the +.Pa /var/run/rc.log +file, and will appear on the console regardless of the +value of +.Va rc_silent . +This is expected to be useful for interactive commands, +and this mechanism is automatically used by +.Ic run_rc_command +when a script contains the +.Xr rcorder 8 +keyword +.Dq interactive . +.Pp +If invoked from a context that does not appear to be under the control of +.Xr rc 8 , +then the command is executed without special treatment. +.It Ic print_rc_metadata Ar string +Print the specified +.Ar string +in such a way that it should be handled as meta-data by the +.Xr rc 8 +post-processor. +If invoked from a context that does not appear to be under the control of +.Xr rc 8 , +then the +.Ar string +is discarded. +.Pp +Any +.Xr rc.d 8 +script may invoke this function with an argument that begins with +.Dq note: , +followed by one line of arbitrary text; +the text will be logged by +.Xr rc 8 +but will not be displayed on the console. +.Pp +The use of arguments that do not begin with +.Dq note: +is reserved for internal use by +.Xr rc 8 +and +.Nm . +.It Ic print_rc_normal Oo Fl n Oc Ar string +Print the specified +.Ar string +in such a way that it should be handled as normal output by the +.Xr rc 8 +post-processor. +If invoked from a context that does not appear to be under the control of +.Xr rc 8 , +then the +.Ar string +is printed to standard output. +.Pp +If the +.Fl n +flag is specified, then the string is printed without a newline. +.Pp +Intended use cases include: +.Bl -bullet +.It +An rc.d script can use +.Dq Sy print_rc_normal Fl n +to print a partial line in such a way that it appears +immediately instead of being buffered by +.Xr rc 8 Ap s +post-processor. +.It +An rc.d script that is run via the +.Sy no_rc_postprocess +function (so most of its output is invisible to +.Xr rc 8 Ap s +post-processor) can use +.Sy print_rc_normal +to force some of its output to be seen by the post-processor. +.El +.It Ic rc_usage Ar command Op Ar ... +Print a usage message for +.Sy $0 , +with +.Ar commands +being the list of valid arguments +prefixed by +.Dq "[fast|force|one]" . +.It Ic reverse_list Ar item Op Ar ... +Print the list of +.Ar items +in reverse order. +.It Ic run_rc_command Ar argument Op Ar parameter ... +Run the +.Ar argument +method for the current +.Xr rc.d 8 +script, based on the settings of various shell variables. +.Ic run_rc_command +is extremely flexible, and allows fully functional +.Xr 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. +.Pp +.Ar argument +is searched for in the list of supported commands, which may be one +of: +.Bl -tag -width restart -offset indent +.It Sy start +Start the service. +This should check that the service is to be started as specified by +.Xr 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 +.Nx +scripts if the system is starting directly to multi-user mode, to +speed up the boot process. +.It Sy stop +If the service is to be started as specified by +.Xr rc.conf 5 , +stop the service. +This should check that the service is running and complain if it's not. +.It Sy restart +Perform a +.Sy stop +then a +.Sy start . +Defaults to displaying the process ID of the program (if running). +.It Sy rcvar +Display which +.Xr rc.conf 5 +variables are used to control the startup of the service (if any). +.El +.Pp +If +.Sy pidfile +or +.Sy procname +is set, also support: +.Bl -tag -width restart -offset indent +.It Sy poll +Wait for the command to exit. +.It Sy status +Show the status of the process. +.El +.Pp +Other supported commands are listed in the optional variable +.Sy extra_commands . +.Pp +.Ar argument +may have one of the following prefixes which alters its operation: +.Bl -tag -width "Prefix" -offset indent +.It Sy fast +Skip the check for an existing running process, +and sets +.Sy rc_fast=YES . +.It Sy force +Skip the checks for +.Sy rcvar +being set to yes, +and sets +.Sy rc_force=YES . +This ignores +.Ar argument Ns Sy _precmd +returning non-zero, and ignores any of the +.Sy required_* +tests failing, and always returns a zero exit status. +.It Sy one +Skip the checks for +.Sy rcvar +being set to yes, but performs all the other prerequisite tests. +.El +.Pp +.Ic run_rc_command +uses the following shell variables to control its behaviour. +Unless otherwise stated, these are optional. +.Bl -tag -width procname -offset indent +.It Sy name +The name of this script. +This is not optional. +.It Sy rcvar +The value of +.Sy rcvar +is checked with +.Ic checkyesno +to determine if this method should be run. +.It Sy rcvar_manpage +The manual page containing information about +.Sy rcvar . +It will be part of the warning message shown when +.Sy rcvar +is undefined. +Defaults to +.Xr rc.conf 5 . +.It Sy command +Full path to the command. +Not required if +.Ar argument Ns Sy _cmd +is defined for each supported keyword. +.It Sy command_args +Optional arguments and/or shell directives for +.Sy command . +.It Sy command_interpreter +.Sy command +is started with +.Dl #! command_interpreter [...] +which results in its +.Xr ps 1 +command being +.Dl command_interpreter [...] command +so use that string to find the PID(s) of the running command +rather than +.Ql command . +.It Sy extra_commands +Extra commands/keywords/arguments supported. +.It Sy pidfile +Path to pid file. +Used to determine the PID(s) of the running command. +If +.Sy pidfile +is set, use +.Dl check_pidfile $pidfile $procname +to find the PID. +Otherwise, if +.Sy command +is set, use +.Dl check_process $procname +to find the PID. +.It Sy procname +Process name to check for. +Defaults to the value of +.Sy command . +.It Sy required_dirs +Check for the existence of the listed directories +before running the default start method. +.It Sy required_files +Check for the readability of the listed files +before running the default start method. +.It Sy required_vars +Perform +.Ic checkyesno +on each of the list variables +before running the default start method. +.It Sy ${name}_chdir +Directory to +.Ic cd +to before running +.Sy command , +if +.Sy ${name}_chroot +is not provided. +.It Sy ${name}_chroot +Directory to +.Xr chroot 8 +to before running +.Sy command . +Only supported after +.Pa /usr +is mounted. +.It Sy ${name}_env +List of additional or modified environment variables to set +when starting +.Sy command . +.It Sy ${name}_flags +Arguments to call +.Sy command +with. +This is usually set in +.Xr rc.conf 5 , +and not in the +.Xr rc.d 8 +script. +The environment variable +.Sq Ev flags +can be used to override this. +.It Sy ${name}_nice +.Xr nice 1 +level to run +.Sy command +as. +Only supported after +.Pa /usr +is mounted. +.It Sy ${name}_user +User to run +.Sy command +as, using +.Xr chroot 8 . +if +.Sy ${name}_chroot +is set, otherwise +uses +.Xr su 1 . +Only supported after +.Pa /usr +is mounted. +.It Sy ${name}_group +Group to run the chrooted +.Sy command +as. +.It Sy ${name}_groups +Comma separated list of supplementary groups to run the chrooted +.Sy command +with. +.It Ar argument Ns Sy _cmd +Shell commands which override the default method for +.Ar argument . +.It Ar argument Ns Sy _precmd +Shell commands to run just before running +.Ar argument Ns Sy _cmd +or the default method for +.Ar 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 +.Sy required_* +checks and process (non-)existence checks. +.It Ar argument Ns Sy _postcmd +Shell commands to run if running +.Ar argument Ns Sy _cmd +or the default method for +.Ar argument +returned a zero exit code. +.It Sy sig_stop +Signal to send the processes to stop in the default +.Sy stop +method. +Defaults to +.Dv SIGTERM . +.It Sy sig_reload +Signal to send the processes to reload in the default +.Sy reload +method. +Defaults to +.Dv SIGHUP . +.El +.Pp +For a given method +.Ar argument , +if +.Ar argument Ns Sy _cmd +is not defined, then a default method is provided by +.Sy run_rc_command : +.Bl -tag -width "argument" -offset indent +.It Sy Argument +.Sy Default method +.It Sy start +If +.Sy command +is not running and +.Ic checkyesno Sy rcvar +succeeds, start +.Sy command . +.It Sy stop +Determine the PIDs of +.Sy command +with +.Ic check_pidfile +or +.Ic check_process +(as appropriate), +.Ic kill Sy sig_stop +those PIDs, and run +.Ic wait_for_pids +on those PIDs. +.It Sy reload +Similar to +.Sy stop , +except that it uses +.Sy sig_reload +instead, and doesn't run +.Ic wait_for_pids . +.It Sy restart +Runs the +.Sy stop +method, then the +.Sy start +method. +.It Sy status +Show the PID of +.Sy command , +or some other script specific status operation. +.It Sy poll +Wait for +.Sy command +to exit. +.It Sy rcvar +Display which +.Xr rc.conf 5 +variable is used (if any). +This method always works, even if the appropriate +.Xr rc.conf 5 +variable is set to +.Sq NO . +.El +.Pp +The following variables are available to the methods +(such as +.Ar argument Ns Sy _cmd ) +as well as after +.Ic run_rc_command +has completed: +.Bl -tag -width "rc_flags" -offset indent +.It Sy rc_arg +Argument provided to +.Sy run_rc_command , +after fast and force processing has been performed. +.It Sy rc_flags +Flags to start the default command with. +Defaults to +.Sy ${name}_flags , +unless overridden by the environment variable +.Sq Ev flags . +This variable may be changed by the +.Ar argument Ns Sy _precmd +method. +.It Sy rc_pid +PID of +.Sy command +(if appropriate). +.It Sy rc_fast +Not empty if +.Dq fast +prefix was used. +.It Sy rc_force +Not empty if +.Dq force +prefix was used. +.El +.It Ic run_rc_script Ar file Ar argument +Start the script +.Ar file +with an argument of +.Ar argument , +and handle the return value from the script. +.Pp +Various shell variables are unset before +.Ar file +is started: +.Bd -ragged -offset indent +.Sy name , +.Sy command , +.Sy command_args , +.Sy command_interpreter , +.Sy extra_commands , +.Sy pidfile , +.Sy rcvar , +.Sy required_dirs , +.Sy required_files , +.Sy required_vars , +.Ar argument Ns Sy _cmd , +.Ar argument Ns Sy _precmd . +.Ar argument Ns Sy _postcmd . +.Ed +.Pp +The startup behaviour of +.Ar file +depends upon the following checks: +.Bl -enum +.It +If +.Ar file +ends in +.Pa .sh , +it is sourced into the current shell. +.It +If +.Ar file +appears to be a backup or scratch file +(e.g., with a suffix of +.Sq ~ , +.Sq # , +.Sq .OLD , +or +.Sq .orig ) , +ignore it. +.It +If +.Ar file +is not executable, ignore it. +.It +If the +.Xr rc.conf 5 +variable +.Sy rc_fast_and_loose +is empty, +source +.Ar file +in a sub shell, +otherwise source +.Ar file +into the current shell. +.It +If +.Ar file +contains the +.Xr rcorder 8 +keyword +.Dq interactive , +then the command is executed using +.Ic no_rc_postprocess . +.El +.It Ic stop_boot +Prevent booting to multiuser mode. +If the +.Sy autoboot +variable is +.Sq yes , +then a +.Sy SIGTERM +signal is sent to the parent +process (which is assumed to be +.Xr rc 8 ) . +Otherwise, the shell exits with status +.Li 1 . +.It Ic twiddle +Display one of the characters +.Sq \&/ , \&- , \&\e , \&| , +followed by a backspace. +Repeated calls to this function will create the appearance of a spinning +symbol, as a different character is displayed on each call. +Output is to +.Pa /dev/tty , +so this function may be useful even inside a script whose output +has been redirected. +.It Ic wait_for_pids Op Ar pid Op Ar ... +Wait until all of the provided +.Ar pids +don't exist any more, printing the list of outstanding +.Ar pids +every two seconds. +.It Ic warn Ar message +Display a warning message to +.Em stderr +and log it to the system log +using +.Xr logger 1 . +The warning message consists of the script name +(from +.Sy $0 ) , +followed by +.Dq ": WARNING: " , +and then +.Ar message . +.It Ic yesno_to_truefalse Ar var +Change the value of the specified variable from any of the +forms acceptable to the +.Ic checkyesno +function, to +.Dq true +or +.Dq false . +.El +.Sh FILES +.Bl -tag -width /etc/rc.subr -compact +.It Pa /etc/rc.subr +The +.Nm +file resides in +.Pa /etc . +.El +.Sh SEE ALSO +.Xr rc.conf 5 , +.Xr rc 8 +.Sh HISTORY +.Nm +appeared in +.Nx 1.3 . +The +.Xr rc.d 8 +support functions appeared in +.Nx 1.5 . +Support for the +.Xr rc 8 +post-processor appeared in +.Nx 6.0 . |