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.
17 .\" 3. All advertising materials mentioning features or use of this software
18 .\" must display the following acknowledgement:
19 .\" This product includes software developed by the NetBSD
20 .\" Foundation, Inc. and its contributors.
21 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
22 .\" contributors may be used to endorse or promote products derived
23 .\" from this software without specific prior written permission.
25 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35 .\" POSSIBILITY OF SUCH DAMAGE.
44 .Nd functions used by system shell scripts
48 .Ic .\& Pa /etc/rc.subr
51 .Ic backup_file Ar action Ar file Ar current Ar backup
55 .Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter
57 .Ic check_process Ar procname Op Ar interpreter
61 .Ic err Ar exitval Ar message
63 .Ic force_depend Ar name
67 .Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file
69 .Ic load_rc_config Ar name
71 .Ic load_rc_config_var Ar name Ar var
73 .Ic mount_critical_filesystems Ar type
75 .Ic rc_usage Ar command ...
77 .Ic reverse_list Ar item ...
79 .Ic run_rc_command Ar argument
81 .Ic run_rc_script Ar file Ar argument
83 .Ic set_rcvar Op Ar base
85 .Ic wait_for_pids Op Ar pid ...
93 contains commonly used shell script functions and variable
94 definitions which are used by various scripts such as
96 Scripts required by ports in
97 .Pa /usr/local/etc/rc.d
99 be rewritten to make use of it.
103 functions were mostly imported from
105 and it is intended that they remain synced between the
107 With that in mind there are several variable
108 definitions that can help in this regard.
112 Its value will be either
116 depending on which OS it is running on.
122 The path and argument list to display only the
125 .Ar name Ns = Ns Ar value
128 The path and argument to write or modify
135 functions are accessed by sourcing
137 into the current shell.
139 The following shell functions are available:
141 .It Ic backup_file Ar action file current backup
142 Make a backup copy of
154 to archive the previous version of
156 otherwise save the previous version of
164 may be one of the following:
165 .Bl -tag -width ".Cm remove"
168 is now being backed up by or possibly re-entered into this backup mechanism.
170 is created, and if necessary, the
172 files are created as well.
175 has changed and needs to be backed up.
178 exists, it is copied to
182 (if the repository file is old),
189 is no longer being tracked by this backup mechanism.
192 is being used, an empty file is checked in and
200 .It Ic checkyesno Ar var
219 is not set correctly.
220 The values are case insensitive.
223 should be a variable name, not its value;
225 will expand the variable by itself.
226 .It Ic check_pidfile Ar pidfile procname Op Ar interpreter
227 Parses the first word of the first line of
229 for a PID, and ensures that the process with that PID
230 is running and its first argument matches
232 Prints the matching PID if successful, otherwise nothing.
235 is provided, parse the first line of
237 ensure that the line is of the form:
239 .Dl "#! interpreter [...]"
243 with its optional arguments and
245 appended as the process string to search for.
246 .It Ic check_process Ar procname Op Ar interpreter
247 Prints the PIDs of any processes that are running with a first
248 argument that matches
253 .It Ic debug Ar message
254 Display a debugging message to
256 log it to the system log using
259 return to the caller.
260 The error message consists of the script name
267 This function is intended to be used by developers
268 as an aid to debugging scripts.
269 It can be turned on or off
274 .It Ic err Ar exitval message
275 Display an error message to
277 log it to the system log
282 with an exit value of
284 The error message consists of the script name
291 .It Ic force_depend Ar name
292 Output an advisory message and force the
299 component of the path to the script, usually
301 If the script fails for any reason it will output a warning
302 and return with a return value of 1.
305 .It Ic info Ar message
306 Display an informational message to
308 and log it to the system log using
310 The message consists of the script name
317 The display of this informational output can be
318 turned on or off by the
322 .It Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file
325 as a kernel module unless it is already loaded.
326 For the purpose of checking the module status,
327 either the exact module name can be specified using
331 regular expression matching the module name can be supplied via
333 By default, the module is assumed to have the same name as
335 which is not always the case.
336 .It Ic load_rc_config Ar name
337 Source in the configuration files for
341 is sourced if it has not yet been read in.
343 .Pa /etc/rc.conf.d/ Ns Ar name
344 is sourced if it is an existing file.
345 The latter may also contain other variable assignments to override
347 arguments defined by the calling script, to provide an easy
348 mechanism for an administrator to override the behaviour of a given
350 script without requiring the editing of that script.
351 .It Ic load_rc_config_var Ar name Ar var
358 and set in the current shell, using
360 in a sub-shell to prevent unwanted side effects from other variable
362 .It Ic mount_critical_filesystems Ar type
363 Go through a list of critical file systems,
367 .Va critical_filesystems_ Ns Ar type ,
368 mounting each one that
369 is not currently mounted.
370 .It Ic rc_usage Ar command ...
371 Print a usage message for
375 being the list of valid arguments
378 .Dq Bq Li fast | force | one | quiet .
380 .It Ic reverse_list Ar item ...
384 .It Ic run_rc_command Ar argument
387 method for the current
389 script, based on the settings of various shell variables.
391 is extremely flexible, and allows fully functional
393 scripts to be implemented in a small amount of shell code.
396 is searched for in the list of supported commands, which may be one
398 .Bl -tag -width ".Cm restart" -offset indent
401 This should check that the service is to be started as specified by
403 Also checks if the service is already running and refuses to start if
405 This latter check is not performed by standard
407 scripts if the system is starting directly to multi-user mode, to
408 speed up the boot process.
410 If the service is to be started as specified by
413 This should check that the service is running and complain if it is not.
419 Defaults to displaying the process ID of the program (if running).
423 variables are used to control the startup of the service (if any).
430 is set, also support:
431 .Bl -tag -width ".Cm restart" -offset indent
433 Wait for the command to exit.
435 Show the status of the process.
438 Other supported commands are listed in the optional variable
442 may have one of the following prefixes which alters its operation:
443 .Bl -tag -width ".Li force" -offset indent
445 Skip the check for an existing running process,
447 .Va rc_fast Ns = Ns Li YES .
454 .Va rc_force Ns = Ns Li YES .
456 .Ar argument Ns Va _precmd
457 returning non-zero, and ignores any of the
459 tests failing, and always returns a zero exit status.
465 but performs all the other prerequisite tests.
467 Inhibits some verbose diagnostics.
468 Currently, this includes messages
474 and errors about usage of services that are not enabled in
476 This prefix also sets
477 .Va rc_quiet Ns = Ns Li YES .
480 is not intended to completely mask all debug and warning messages,
481 but only certain small classes of them.
485 uses the following shell variables to control its behaviour.
486 Unless otherwise stated, these are optional.
487 .Bl -tag -width ".Va procname" -offset indent
489 The name of this script.
490 This is not optional.
496 to determine if this method should be run.
498 Full path to the command.
500 .Ar argument Ns Va _cmd
501 is defined for each supported keyword.
503 .Va ${name}_program .
505 Optional arguments and/or shell directives for
507 .It Va command_interpreter
511 .Dl "#! command_interpreter [...]"
517 .Dl "command_interpreter [...] command"
519 so use that string to find the PID(s) of the running command
522 .It Va extra_commands
523 Extra commands/keywords/arguments supported.
526 Used to determine the PID(s) of the running command.
531 .Dl "check_pidfile $pidfile $procname"
538 .Dl "check_process $procname"
542 Process name to check for.
543 Defaults to the value of
546 Check for the existence of the listed directories
550 .It Va required_files
551 Check for the readability of the listed files
555 .It Va required_modules
556 Ensure that the listed kernel modules are loaded
560 This is done after invoking the commands from
562 so that the missing modules are not loaded in vain
563 if the preliminary commands indicate a error condition.
564 A word in the list can have an optional
565 .Dq Li : Ns Ar modname
567 .Dq Li ~ Ns Ar pattern
573 parameter is passed to
579 option, respectively.
580 See the description of
582 in this document for details.
586 on each of the list variables
598 .It Va ${name}_chroot
610 This is usually set in
615 The environment variable
617 can be used to override this.
626 .It Va ${name}_program
627 Full path to the command.
630 if both are set, but has no effect if
635 should be set in the script while
653 Group to run the chrooted
656 .It Va ${name}_groups
657 Comma separated list of supplementary groups to run the chrooted
660 .It Ar argument Ns Va _cmd
661 Shell commands which override the default method for
663 .It Ar argument Ns Va _precmd
664 Shell commands to run just before running
665 .Ar argument Ns Va _cmd
666 or the default method for
668 If this returns a non-zero exit code, the main method is not performed.
669 If the default method is being executed, this check is performed after
672 checks and process (non-)existence checks.
673 .It Ar argument Ns Va _postcmd
674 Shell commands to run if running
675 .Ar argument Ns Va _cmd
676 or the default method for
678 returned a zero exit code.
680 Signal to send the processes to stop in the default
686 Signal to send the processes to reload in the default
696 .Ar argument Ns Va _cmd
697 is not defined, then a default method is provided by
699 .Bl -tag -width ".Sy Argument" -offset indent
706 .Ic checkyesno Va rcvar
710 Determine the PIDs of
726 instead, and does not run
728 Another difference from
732 is not provided by default.
733 It can be enabled via
737 .Dl "extra_commands=reload"
747 or some other script specific status operation.
755 variable is used (if any).
756 This method always works, even if the appropriate
762 The following variables are available to the methods
764 .Ar argument Ns Va _cmd )
768 .Bl -tag -width ".Va rc_flags" -offset indent
772 after fast and force processing has been performed.
774 Flags to start the default command with.
777 unless overridden by the environment variable
779 This variable may be changed by the
780 .Ar argument Ns Va _precmd
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 set_rcvar Op Ar base
872 Set the variable name required to start a service.
875 a daemon is usually controlled by an
877 variable consisting of a daemon's name postfixed by the string
879 This is not the case in
881 When the following line is included in a script:
883 .Dl "rcvar=`set_rcvar`"
885 this function will use the value of the
887 variable, which should be defined by the calling script,
888 to construct the appropriate
893 argument is set it will use
897 .It Ic wait_for_pids Op Ar pid ...
898 Wait until all of the provided
900 do not exist any more, printing the list of outstanding
903 .It Ic warn Ar message
904 Display a warning message to
906 and log it to the system log
909 The warning message consists of the script name
913 .Dq Li ": WARNING: " ,
918 .Bl -tag -width ".Pa /etc/rc.subr" -compact
936 support functions appeared in