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.
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 the
557 .It Va ${name}_env_file
558 A file to source for environmental variables to run
561 Note that all the variables which are being assigned in this file are going
562 to be exported into the environment of
577 This is usually set in
582 The environment variable
584 can be used to override this.
593 .It Va ${name}_limits
594 Resource limits to apply to
596 This will be passed as arguments to the
599 By default, the resource limits are based on the login class defined in
600 .Va ${name}_login_class .
601 .It Va ${name}_login_class
602 Login class to use with
606 .It Va ${name}_oomprotect
609 from being killed when swap space is exhausted.
612 is used, no child processes are protected.
615 protect all child processes.
616 .It Va ${name}_program
617 Full path to the command.
620 if both are set, but has no effect if
625 should be set in the script while
643 Group to run the chrooted
646 .It Va ${name}_groups
647 Comma separated list of supplementary groups to run the chrooted
650 .It Va ${name}_prepend
651 Commands to be prepended to
653 This is a generic version of
658 .It Ar argument Ns Va _cmd
659 Shell commands which override the default method for
661 .It Ar argument Ns Va _precmd
662 Shell commands to run just before running
663 .Ar argument Ns Va _cmd
664 or the default method for
666 If this returns a non-zero exit code, the main method is not performed.
667 If the default method is being executed, this check is performed after
670 checks and process (non-)existence checks.
671 .It Ar argument Ns Va _postcmd
672 Shell commands to run if running
673 .Ar argument Ns Va _cmd
674 or the default method for
676 returned a zero exit code.
678 Signal to send the processes to stop in the default
684 Signal to send the processes to reload in the default
694 .Ar argument Ns Va _cmd
695 is not defined, then a default method is provided by
697 .Bl -tag -width ".Sy Argument" -offset indent
704 .Ic checkyesno Va rcvar
708 Determine the PIDs of
724 instead, and does not run
726 Another difference from
730 is not provided by default.
731 It can be enabled via
735 .Dl "extra_commands=reload"
745 or some other script specific status operation.
753 variable is used (if any).
754 This method always works, even if the appropriate
760 The following variables are available to the methods
762 .Ar argument Ns Va _cmd )
766 .Bl -tag -width ".Va rc_service" -offset indent
770 after fast and force processing has been performed.
772 Flags to start the default command with.
775 unless overridden by the environment variable
777 This variable may be changed by the
778 .Ar argument Ns Va _precmd
781 Path to the service script being executed, in case it needs to re-invoke itself.
795 .It Ic run_rc_script Ar file argument
800 and handle the return value from the script.
802 Various shell variables are unset before
805 .Bd -ragged -offset indent
809 .Va command_interpreter ,
816 .Ar argument Ns Va _cmd ,
817 .Ar argument Ns Va _precmd .
818 .Ar argument Ns Va _postcmd .
821 The startup behaviour of
823 depends upon the following checks:
830 it is sourced into the current shell.
834 appears to be a backup or scratch file
835 (e.g., with a suffix of
843 is not executable, ignore it.
848 .Va rc_fast_and_loose
855 into the current shell.
857 .It Ic stop_boot Op Ar always
858 Prevent booting to multiuser mode.
864 .Ic checkyesno Ar always
865 indicates a truth value, then a
867 signal is sent to the parent
868 process, which is assumed to be
870 Otherwise, the shell exits with a non-zero status.
871 .It Ic wait_for_pids Op Ar pid ...
872 Wait until all of the provided
874 do not exist any more, printing the list of outstanding
877 .It Ic warn Ar message
878 Display a warning message to
880 and log it to the system log
883 The warning message consists of the script name
887 .Dq Li ": WARNING: " ,
892 .Bl -tag -width ".Pa /etc/rc.subr" -compact
910 support functions appeared in