1 .\" $NetBSD: rc.subr.8,v 1.12 2004/01/06 00:52:24 lukem Exp $
3 .\" Copyright (c) 2002-2004 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
6 .\" This code is derived from software contributed to The NetBSD Foundation
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
32 .Dd September 18, 2016
37 .Nd functions used by system shell scripts
41 .Ic .\& Pa /etc/rc.subr
44 .Ic backup_file Ar action Ar file Ar current Ar backup
48 .Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter
50 .Ic check_process Ar procname Op Ar interpreter
54 .Ic err Ar exitval Ar message
56 .Ic force_depend Ar name
60 .Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file
62 .Ic load_rc_config Ar name
64 .Ic load_rc_config_var Ar name Ar var
66 .Ic mount_critical_filesystems Ar type
68 .Ic rc_usage Ar command ...
70 .Ic reverse_list Ar item ...
72 .Ic run_rc_command Ar argument
74 .Ic run_rc_script Ar file Ar argument
76 .Ic wait_for_pids Op Ar pid ...
84 contains commonly used shell script functions and variable
85 definitions which are used by various scripts such as
87 Scripts required by ports in
88 .Pa /usr/local/etc/rc.d
90 be rewritten to make use of it.
94 functions were mostly imported from
97 They are accessed by sourcing
99 into the current shell.
101 The following shell functions are available:
103 .It Ic backup_file Ar action file current backup
104 Make a backup copy of
108 Save the previous version of
116 may be one of the following:
117 .Bl -tag -width ".Cm remove"
120 is now being backed up by or possibly re-entered into this backup mechanism.
125 has changed and needs to be backed up.
128 exists, it is copied to
136 is no longer being tracked by this backup mechanism.
141 .It Ic checkyesno Ar var
160 is not set correctly.
161 The values are case insensitive.
164 should be a variable name, not its value;
166 will expand the variable by itself.
167 .It Ic check_pidfile Ar pidfile procname Op Ar interpreter
168 Parses the first word of the first line of
170 for a PID, and ensures that the process with that PID
171 is running and its first argument matches
173 Prints the matching PID if successful, otherwise nothing.
176 is provided, parse the first line of
178 ensure that the line is of the form:
180 .Dl "#! interpreter [...]"
184 with its optional arguments and
186 appended as the process string to search for.
187 .It Ic check_process Ar procname Op Ar interpreter
188 Prints the PIDs of any processes that are running with a first
189 argument that matches
194 .It Ic debug Ar message
195 Display a debugging message to
197 log it to the system log using
200 return to the caller.
201 The error message consists of the script name
208 This function is intended to be used by developers
209 as an aid to debugging scripts.
210 It can be turned on or off
215 .It Ic err Ar exitval message
216 Display an error message to
218 log it to the system log
223 with an exit value of
225 The error message consists of the script name
232 .It Ic force_depend Ar name
233 Output an advisory message and force the
240 component of the path to the script, usually
242 If the script fails for any reason it will output a warning
243 and return with a return value of 1.
246 .It Ic info Ar message
247 Display an informational message to
249 and log it to the system log using
251 The message consists of the script name
258 The display of this informational output can be
259 turned on or off by the
263 .It Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file
266 as a kernel module unless it is already loaded.
267 For the purpose of checking the module status,
268 either the exact module name can be specified using
272 regular expression matching the module name can be supplied via
274 By default, the module is assumed to have the same name as
276 which is not always the case.
277 .It Ic load_rc_config Ar name
278 Source in the configuration files for
282 is sourced if it has not yet been read in.
284 .Pa /etc/rc.conf.d/ Ns Ar name
285 is sourced if it is an existing file.
286 The latter may also contain other variable assignments to override
288 arguments defined by the calling script, to provide an easy
289 mechanism for an administrator to override the behaviour of a given
291 script without requiring the editing of that script.
292 .It Ic load_rc_config_var Ar name Ar var
299 and set in the current shell, using
301 in a sub-shell to prevent unwanted side effects from other variable
303 .It Ic mount_critical_filesystems Ar type
304 Go through a list of critical file systems,
308 .Va critical_filesystems_ Ns Ar type ,
309 mounting each one that
310 is not currently mounted.
311 .It Ic rc_usage Ar command ...
312 Print a usage message for
316 being the list of valid arguments
319 .Dq Bq Li fast | force | one | quiet .
321 .It Ic reverse_list Ar item ...
325 .It Ic run_rc_command Ar argument
328 method for the current
330 script, based on the settings of various shell variables.
332 is extremely flexible, and allows fully functional
334 scripts to be implemented in a small amount of shell code.
337 is searched for in the list of supported commands, which may be one
339 .Bl -tag -width ".Cm restart" -offset indent
342 This should check that the service is to be started as specified by
344 Also checks if the service is already running and refuses to start if
346 This latter check is not performed by standard
348 scripts if the system is starting directly to multi-user mode, to
349 speed up the boot process.
351 If the service is to be started as specified by
354 This should check that the service is running and complain if it is not.
360 Defaults to displaying the process ID of the program (if running).
362 Return 0 if the service is enabled and 1 if it is not.
363 This command does not print anything.
367 variables are used to control the startup of the service (if any).
374 is set, also support:
375 .Bl -tag -width ".Cm restart" -offset indent
377 Wait for the command to exit.
379 Show the status of the process.
382 Other supported commands are listed in the optional variable
386 may have one of the following prefixes which alters its operation:
387 .Bl -tag -width ".Li force" -offset indent
389 Skip the check for an existing running process,
391 .Va rc_fast Ns = Ns Li YES .
398 .Va rc_force Ns = Ns Li YES .
400 .Ar argument Ns Va _precmd
401 returning non-zero, and ignores any of the
403 tests failing, and always returns a zero exit status.
409 but performs all the other prerequisite tests.
411 Inhibits some verbose diagnostics.
412 Currently, this includes messages
418 and errors about usage of services that are not enabled in
420 This prefix also sets
421 .Va rc_quiet Ns = Ns Li YES .
424 is not intended to completely mask all debug and warning messages,
425 but only certain small classes of them.
429 uses the following shell variables to control its behaviour.
430 Unless otherwise stated, these are optional.
431 .Bl -tag -width ".Va procname" -offset indent
433 The name of this script.
434 This is not optional.
440 to determine if this method should be run.
442 Full path to the command.
444 .Ar argument Ns Va _cmd
445 is defined for each supported keyword.
447 .Va ${name}_program .
449 Optional arguments and/or shell directives for
451 .It Va command_interpreter
455 .Dl "#! command_interpreter [...]"
461 .Dl "command_interpreter [...] command"
463 so use that string to find the PID(s) of the running command
466 .It Va extra_commands
467 Extra commands/keywords/arguments supported.
470 Used to determine the PID(s) of the running command.
475 .Dl "check_pidfile $pidfile $procname"
482 .Dl "check_process $procname"
486 Process name to check for.
487 Defaults to the value of
490 Check for the existence of the listed directories
494 .It Va required_files
495 Check for the readability of the listed files
499 .It Va required_modules
500 Ensure that the listed kernel modules are loaded
504 This is done after invoking the commands from
506 so that the missing modules are not loaded in vain
507 if the preliminary commands indicate a error condition.
508 A word in the list can have an optional
509 .Dq Li : Ns Ar modname
511 .Dq Li ~ Ns Ar pattern
517 parameter is passed to
523 option, respectively.
524 See the description of
526 in this document for details.
530 on each of the list variables
542 .It Va ${name}_chroot
551 A list of environment variables to run
554 This will be passed as arguments to
570 This is usually set in
575 The environment variable
577 can be used to override this.
586 .It Va ${name}_oomprotect
589 from being killed when swap space is exhausted.
592 is used, no child processes are protected.
595 protect all child processes.
596 .It Va ${name}_program
597 Full path to the command.
600 if both are set, but has no effect if
605 should be set in the script while
623 Group to run the chrooted
626 .It Va ${name}_groups
627 Comma separated list of supplementary groups to run the chrooted
630 .It Va ${name}_prepend
631 Commands to be prepended to
633 This is a generic version of
638 .It Ar argument Ns Va _cmd
639 Shell commands which override the default method for
641 .It Ar argument Ns Va _precmd
642 Shell commands to run just before running
643 .Ar argument Ns Va _cmd
644 or the default method for
646 If this returns a non-zero exit code, the main method is not performed.
647 If the default method is being executed, this check is performed after
650 checks and process (non-)existence checks.
651 .It Ar argument Ns Va _postcmd
652 Shell commands to run if running
653 .Ar argument Ns Va _cmd
654 or the default method for
656 returned a zero exit code.
658 Signal to send the processes to stop in the default
664 Signal to send the processes to reload in the default
674 .Ar argument Ns Va _cmd
675 is not defined, then a default method is provided by
677 .Bl -tag -width ".Sy Argument" -offset indent
684 .Ic checkyesno Va rcvar
688 Determine the PIDs of
704 instead, and does not run
706 Another difference from
710 is not provided by default.
711 It can be enabled via
715 .Dl "extra_commands=reload"
725 or some other script specific status operation.
733 variable is used (if any).
734 This method always works, even if the appropriate
740 The following variables are available to the methods
742 .Ar argument Ns Va _cmd )
746 .Bl -tag -width ".Va rc_flags" -offset indent
750 after fast and force processing has been performed.
752 Flags to start the default command with.
755 unless overridden by the environment variable
757 This variable may be changed by the
758 .Ar argument Ns Va _precmd
773 .It Ic run_rc_script Ar file argument
778 and handle the return value from the script.
780 Various shell variables are unset before
783 .Bd -ragged -offset indent
787 .Va command_interpreter ,
794 .Ar argument Ns Va _cmd ,
795 .Ar argument Ns Va _precmd .
796 .Ar argument Ns Va _postcmd .
799 The startup behaviour of
801 depends upon the following checks:
808 it is sourced into the current shell.
812 appears to be a backup or scratch file
813 (e.g., with a suffix of
821 is not executable, ignore it.
826 .Va rc_fast_and_loose
833 into the current shell.
835 .It Ic stop_boot Op Ar always
836 Prevent booting to multiuser mode.
842 .Ic checkyesno Ar always
843 indicates a truth value, then a
845 signal is sent to the parent
846 process, which is assumed to be
848 Otherwise, the shell exits with a non-zero status.
849 .It Ic wait_for_pids Op Ar pid ...
850 Wait until all of the provided
852 do not exist any more, printing the list of outstanding
855 .It Ic warn Ar message
856 Display a warning message to
858 and log it to the system log
861 The warning message consists of the script name
865 .Dq Li ": WARNING: " ,
870 .Bl -tag -width ".Pa /etc/rc.subr" -compact
888 support functions appeared in