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 The list is checked before running
496 .It Va required_files
497 Check for the readability of the listed files
501 The list is checked before running
503 .It Va required_modules
504 Ensure that the listed kernel modules are loaded
508 The list is checked after running
510 This is done after invoking the commands from
512 so that the missing modules are not loaded in vain
513 if the preliminary commands indicate a error condition.
514 A word in the list can have an optional
515 .Dq Li \&: Ns Ar modname
517 .Dq Li ~ Ns Ar pattern
523 parameter is passed to
529 option, respectively.
530 See the description of
532 in this document for details.
536 on each of the list variables
540 The list is checked after running
550 .It Va ${name}_chroot
559 A list of environment variables to run
562 This will be passed as arguments to the
565 .It Va ${name}_env_file
566 A file to source for environmental variables to run
569 Note that all the variables which are being assigned in this file are going
570 to be exported into the environment of
585 This is usually set in
590 The environment variable
592 can be used to override this.
601 .It Va ${name}_limits
602 Resource limits to apply to
604 This will be passed as arguments to the
607 By default, the resource limits are based on the login class defined in
608 .Va ${name}_login_class .
609 .It Va ${name}_login_class
610 Login class to use with
614 .It Va ${name}_oomprotect
617 from being killed when swap space is exhausted.
620 is used, no child processes are protected.
623 protect all child processes.
624 .It Va ${name}_program
625 Full path to the command.
628 if both are set, but has no effect if
633 should be set in the script while
651 Group to run the chrooted
654 .It Va ${name}_groups
655 Comma separated list of supplementary groups to run the chrooted
658 .It Va ${name}_prepend
659 Commands to be prepended to
661 This is a generic version of
666 .It Ar argument Ns Va _cmd
667 Shell commands which override the default method for
669 .It Ar argument Ns Va _precmd
670 Shell commands to run just before running
671 .Ar argument Ns Va _cmd
672 or the default method for
674 If this returns a non-zero exit code, the main method is not performed.
675 If the default method is being executed, this check is performed after
678 checks and process (non-)existence checks.
679 .It Ar argument Ns Va _postcmd
680 Shell commands to run if running
681 .Ar argument Ns Va _cmd
682 or the default method for
684 returned a zero exit code.
686 Signal to send the processes to stop in the default
692 Signal to send the processes to reload in the default
702 .Ar argument Ns Va _cmd
703 is not defined, then a default method is provided by
705 .Bl -tag -width ".Sy Argument" -offset indent
712 .Ic checkyesno Va rcvar
716 Determine the PIDs of
732 instead, and does not run
734 Another difference from
738 is not provided by default.
739 It can be enabled via
743 .Dl "extra_commands=reload"
753 or some other script specific status operation.
761 variable is used (if any).
762 This method always works, even if the appropriate
768 The following variables are available to the methods
770 .Ar argument Ns Va _cmd )
774 .Bl -tag -width ".Va rc_flags" -offset indent
778 after fast and force processing has been performed.
780 Flags to start the default command with.
783 unless overridden by the environment variable
785 This variable may be changed by the
786 .Ar argument Ns Va _precmd
801 .It Ic run_rc_script Ar file argument
806 and handle the return value from the script.
808 Various shell variables are unset before
811 .Bd -ragged -offset indent
815 .Va command_interpreter ,
822 .Ar argument Ns Va _cmd ,
823 .Ar argument Ns Va _precmd .
824 .Ar argument Ns Va _postcmd .
827 The startup behaviour of
829 depends upon the following checks:
836 it is sourced into the current shell.
840 appears to be a backup or scratch file
841 (e.g., with a suffix of
849 is not executable, ignore it.
854 .Va rc_fast_and_loose
861 into the current shell.
863 .It Ic stop_boot Op Ar always
864 Prevent booting to multiuser mode.
870 .Ic checkyesno Ar always
871 indicates a truth value, then a
873 signal is sent to the parent
874 process, which is assumed to be
876 Otherwise, the shell exits with a non-zero status.
877 .It Ic wait_for_pids Op Ar pid ...
878 Wait until all of the provided
880 do not exist any more, printing the list of outstanding
883 .It Ic warn Ar message
884 Display a warning message to
886 and log it to the system log
889 The warning message consists of the script name
893 .Dq Li ": WARNING: " ,
898 .Bl -tag -width ".Pa /etc/rc.subr" -compact
916 support functions appeared in