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 located at
242 (scripts stored in other locations such as
243 .Pa /usr/local/etc/rc.d
244 cannot be controlled with
247 If the script fails for any reason it will output a warning
248 and return with a return value of 1.
251 .It Ic info Ar message
252 Display an informational message to
254 and log it to the system log using
256 The message consists of the script name
263 The display of this informational output can be
264 turned on or off by the
268 .It Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file
271 as a kernel module unless it is already loaded.
272 For the purpose of checking the module status,
273 either the exact module name can be specified using
277 regular expression matching the module name can be supplied via
279 By default, the module is assumed to have the same name as
281 which is not always the case.
282 .It Ic load_rc_config Ar name
283 Source in the configuration files for
287 is sourced if it has not yet been read in.
289 .Pa /etc/rc.conf.d/ Ns Ar name
290 is sourced if it is an existing file.
291 The latter may also contain other variable assignments to override
293 arguments defined by the calling script, to provide an easy
294 mechanism for an administrator to override the behaviour of a given
296 script without requiring the editing of that script.
297 .It Ic load_rc_config_var Ar name Ar var
304 and set in the current shell, using
306 in a sub-shell to prevent unwanted side effects from other variable
308 .It Ic mount_critical_filesystems Ar type
309 Go through a list of critical file systems,
313 .Va critical_filesystems_ Ns Ar type ,
314 mounting each one that
315 is not currently mounted.
316 .It Ic rc_usage Ar command ...
317 Print a usage message for
321 being the list of valid arguments
324 .Dq Bq Li fast | force | one | quiet .
326 .It Ic reverse_list Ar item ...
330 .It Ic run_rc_command Ar argument
333 method for the current
335 script, based on the settings of various shell variables.
337 is extremely flexible, and allows fully functional
339 scripts to be implemented in a small amount of shell code.
342 is searched for in the list of supported commands, which may be one
344 .Bl -tag -width ".Cm restart" -offset indent
347 This should check that the service is to be started as specified by
349 Also checks if the service is already running and refuses to start if
351 This latter check is not performed by standard
353 scripts if the system is starting directly to multi-user mode, to
354 speed up the boot process.
356 If the service is to be started as specified by
359 This should check that the service is running and complain if it is not.
365 Defaults to displaying the process ID of the program (if running).
367 Return 0 if the service is enabled and 1 if it is not.
368 This command does not print anything.
372 variables are used to control the startup of the service (if any).
379 is set, also support:
380 .Bl -tag -width ".Cm restart" -offset indent
382 Wait for the command to exit.
384 Show the status of the process.
387 Other supported commands are listed in the optional variable
391 may have one of the following prefixes which alters its operation:
392 .Bl -tag -width ".Li force" -offset indent
394 Skip the check for an existing running process,
396 .Va rc_fast Ns = Ns Li YES .
403 .Va rc_force Ns = Ns Li YES .
405 .Ar argument Ns Va _precmd
406 returning non-zero, and ignores any of the
408 tests failing, and always returns a zero exit status.
414 but performs all the other prerequisite tests.
416 Inhibits some verbose diagnostics.
417 Currently, this includes messages
423 and errors about usage of services that are not enabled in
425 This prefix also sets
426 .Va rc_quiet Ns = Ns Li YES .
429 is not intended to completely mask all debug and warning messages,
430 but only certain small classes of them.
434 uses the following shell variables to control its behaviour.
435 Unless otherwise stated, these are optional.
436 .Bl -tag -width ".Va procname" -offset indent
438 The name of this script.
439 This is not optional.
445 to determine if this method should be run.
447 Full path to the command.
449 .Ar argument Ns Va _cmd
450 is defined for each supported keyword.
452 .Va ${name}_program .
454 Optional arguments and/or shell directives for
456 .It Va command_interpreter
460 .Dl "#! command_interpreter [...]"
466 .Dl "command_interpreter [...] command"
468 so use that string to find the PID(s) of the running command
471 .It Va extra_commands
472 Extra commands/keywords/arguments supported.
475 Used to determine the PID(s) of the running command.
480 .Dl "check_pidfile $pidfile $procname"
487 .Dl "check_process $procname"
491 Process name to check for.
492 Defaults to the value of
495 Check for the existence of the listed directories
499 .It Va required_files
500 Check for the readability of the listed files
504 .It Va required_modules
505 Ensure that the listed kernel modules are loaded
509 This is done after invoking the commands from
511 so that the missing modules are not loaded in vain
512 if the preliminary commands indicate a error condition.
513 A word in the list can have an optional
514 .Dq Li \&: Ns Ar modname
516 .Dq Li ~ Ns Ar pattern
522 parameter is passed to
528 option, respectively.
529 See the description of
531 in this document for details.
535 on each of the list variables
547 .It Va ${name}_chroot
556 A list of environment variables to run
559 Those variables will be passed as arguments to the
562 .Ar argument Ns Va _cmd
564 In that case the contents of
566 will be exported via the
570 which puts some limitations on the names of variables
571 (e.g., a variable name may not start with a digit).
572 .It Va ${name}_env_file
573 A file to source for environmental variables to run
576 Note that all the variables which are being assigned in this file are going
577 to be exported into the environment of
592 This is usually set in
597 The environment variable
599 can be used to override this.
608 .It Va ${name}_limits
609 Resource limits to apply to
611 This will be passed as arguments to the
614 By default, the resource limits are based on the login class defined in
615 .Va ${name}_login_class .
616 .It Va ${name}_login_class
617 Login class to use with
621 .It Va ${name}_oomprotect
624 from being killed when swap space is exhausted.
627 is used, no child processes are protected.
630 protect all child processes.
631 .It Va ${name}_program
632 Full path to the command.
635 if both are set, but has no effect if
640 should be set in the script while
658 Group to run the chrooted
661 .It Va ${name}_groups
662 Comma separated list of supplementary groups to run the chrooted
665 .It Va ${name}_prepend
666 Commands to be prepended to
668 This is a generic version of
673 .It Ar argument Ns Va _cmd
674 Shell commands which override the default method for
676 .It Ar argument Ns Va _precmd
677 Shell commands to run just before running
678 .Ar argument Ns Va _cmd
679 or the default method for
681 If this returns a non-zero exit code, the main method is not performed.
682 If the default method is being executed, this check is performed after
685 checks and process (non-)existence checks.
686 .It Ar argument Ns Va _postcmd
687 Shell commands to run if running
688 .Ar argument Ns Va _cmd
689 or the default method for
691 returned a zero exit code.
693 Signal to send the processes to stop in the default
699 Signal to send the processes to reload in the default
709 .Ar argument Ns Va _cmd
710 is not defined, then a default method is provided by
712 .Bl -tag -width ".Sy Argument" -offset indent
719 .Ic checkyesno Va rcvar
723 Determine the PIDs of
739 instead, and does not run
741 Another difference from
745 is not provided by default.
746 It can be enabled via
750 .Dl "extra_commands=reload"
760 or some other script specific status operation.
768 variable is used (if any).
769 This method always works, even if the appropriate
775 The following variables are available to the methods
777 .Ar argument Ns Va _cmd )
781 .Bl -tag -width ".Va rc_service" -offset indent
785 after fast and force processing has been performed.
787 Flags to start the default command with.
790 unless overridden by the environment variable
792 This variable may be changed by the
793 .Ar argument Ns Va _precmd
796 Path to the service script being executed, in case it needs to re-invoke itself.
810 .It Ic run_rc_script Ar file argument
815 and handle the return value from the script.
817 Various shell variables are unset before
820 .Bd -ragged -offset indent
824 .Va command_interpreter ,
831 .Ar argument Ns Va _cmd ,
832 .Ar argument Ns Va _precmd .
833 .Ar argument Ns Va _postcmd .
836 The startup behaviour of
838 depends upon the following checks:
845 it is sourced into the current shell.
849 appears to be a backup or scratch file
850 (e.g., with a suffix of
858 is not executable, ignore it.
863 .Va rc_fast_and_loose
870 into the current shell.
872 .It Ic stop_boot Op Ar always
873 Prevent booting to multiuser mode.
883 .Ic checkyesno Ar always
884 indicates a truth value, then a
886 signal is sent to the parent
887 process, which is assumed to be
889 Otherwise, the shell exits with a non-zero status.
890 .It Ic wait_for_pids Op Ar pid ...
891 Wait until all of the provided
893 do not exist any more, printing the list of outstanding
896 .It Ic warn Ar message
897 Display a warning message to
899 and log it to the system log
902 The warning message consists of the script name
906 .Dq Li ": WARNING: " ,
911 .Bl -tag -width ".Pa /etc/rc.subr" -compact
929 support functions appeared in