1 .\" $NetBSD: rc.subr.8,v 1.9 2002/07/08 16:14:55 atatat Exp $
2 .\" $FreeBSD: src/share/man/man8/rc.subr.8,v 1.3 2003/04/22 05:13:55 dougb Exp $
3 .\" Copyright (c) 2002 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.
42 .Nd functions used by system shell scripts
48 .Ic backup_file Ar action Ar file Ar current Ar backup
52 .Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter
54 .Ic check_process Ar procname Op Ar interpreter
58 .Ic err Ar exitval Ar message
60 .Ic force_depend Ar name
64 .Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file
66 .Ic load_rc_config Ar command
68 .Ic mount_critical_filesystems Ar type
70 .Ic rc_usage Ar command Op Ar ...
72 .Ic reverse_list Ar item Op Ar ...
74 .Ic run_rc_command Ar argument
76 .Ic run_rc_script Ar file Ar argument
78 .Ic set_rcvar Op Ar base
80 .Ic wait_for_pids Op Ar pid Op Ar ...
86 contains commonly used shell script functions and variable
87 definitions which are used by various scripts such as
92 functions were mostly imported from
94 and it is intended that they remain synced between the
95 two projects. With that in mind there are several variable
96 definitions that can help in this regard. They are:
99 Its value will be either
104 depending on which OS it is running on.
110 The path and argument list to display only the
112 values instead of a name=value pair.
114 The path and argument to write or modify
121 functions are accessed by sourcing
123 into the current shell.
125 The following shell functions are available:
128 .Ic backup_file Ar action Ar file Ar current Ar backup
130 Make a backup copy of
142 to archive the previous version of
144 otherwise save the previous version of
150 may be one of the following:
151 .Bl -tag -width remove
154 is now being backed up by or possibly re-entered into this backup mechanism.
156 is created, and if necessary, the
158 files are created as well.
161 has changed and needs to be backed up.
164 exists, it is copied to
168 (if the repository file is old),
175 is no longer being tracked by this backup mechanism.
178 is being used, an empty file is checked in and
186 .It Ic checkyesno Ar var
205 is not set correctly.
206 The values are case insensitive.
213 Parses the first word of the first line of
215 for a PID, and ensures that the process with that PID
216 is running and its first argument matches
218 Prints the matching PID if successful, otherwise nothing.
221 is provided, parse the first line of
223 ensure that the line is of the form
224 .Dl #! interpreter [...]
227 with its optional arguments and
229 appended as the process string to search for.
230 .It Ic check_process Ar procname Op Ar interpreter
231 Prints the PIDs of any processes that are running with a first
232 argument that matches
237 .It Ic debug Ar message
238 Display a debugging message to
240 log it to the system log using
243 return to the caller.
244 The error message consists of the script name
251 This function is intended to be used by developers
252 as an aid to debugging scripts. It can be turned on or off
257 .It Ic err Ar exitval Ar message
258 Display an error message to
260 log it to the system log
265 with an exit value of
267 The error message consists of the script name
274 .It Ic force_depend name
275 Output an advisory message and force the
277 service to start. The
281 component of the path to the script, usually
283 If the script fails for any reason it will output a warning
284 and return with a return value of 1. If it was successful
286 .It Ic info Ar message
287 Display an informational message to
289 and log it to the system log using
291 The message consists of the script name
298 The display of this informational output can be
299 turned on or off by the
303 .It Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file
306 as a kernel module unless it is already loaded.
307 For the purpose of checking the module status,
308 either the exact module name can be specified using
312 regular expression matching the module name can be supplied via
314 By default, the module is assumed to have the same name as
316 which is not always the case.
317 .It Ic load_rc_config Ar command
318 Source in the configuration files for
322 is sourced if it has not yet been read in.
324 .Pa /etc/rc.conf.d/ Ns Ar command
325 is sourced if it is an existing file.
326 The latter may also contain other variable assignments to override
328 arguments defined by the calling script, to provide an easy
329 mechanism for an administrator to override the behaviour of a given
331 script without requiring the editing of that script.
332 .It Ic mount_critical_filesystems Ar type
333 Go through a list of critical file systems,
337 .Sy critical_filesystems_ Ns Ar type ,
338 mounting each one that
339 is not currently mounted.
340 .It Ic rc_usage Ar command Op Ar ...
341 Print a usage message for
345 being the list of valid arguments
348 .Dq Bq Li fast | force | one | quiet .
350 .It Ic reverse_list Ar item Op Ar ...
354 .It Ic run_rc_command Ar argument
357 method for the current
359 script, based on the settings of various shell variables.
361 is extremely flexible, and allows fully functional
363 scripts to be implemented in a small amount of shell code.
366 is searched for in the list of supported commands, which may be one
368 .Dl start stop restart rcvar
369 as well as any word listed in the optional variable
379 may have one of the following prefixes which alters its operation:
380 .Bl -tag -width "Prefix" -offset indent -compact
384 Skip the check for an existing running process,
394 .Ar argument Ns Sy _precmd
395 returning non-zero, and ignores any of the
401 being set to yes, but performs all the other prerequisite tests.
403 Inhibits some verbose diagnostics.
404 Currently, this includes messages
407 .\".Ic check_startmsgs
410 and errors about usage of services that are not enabled in
412 This prefix also sets
413 .Va rc_quiet Ns = Ns Li YES .
416 is not intended to completely mask all debug and warning messages,
417 but only certain small classes of them.
421 uses the following shell variables to control its behaviour.
422 Unless otherwise stated, these are optional.
423 .Bl -tag -width procname -offset indent
425 The name of this script.
426 This is not optional.
432 to determine if this method should be run.
434 Full path to the command.
436 .Ar argument Ns Sy _cmd
437 is defined for each supported keyword.
439 Optional arguments and/or shell directives for
441 .It Sy command_interpreter
444 .Dl #! command_interpreter [...]
448 .Dl command_interpreter [...] command
449 so use that string to find the PID(s) of the running command
452 .It Sy extra_commands
453 Extra commands/keywords/arguments supported.
456 Used to determine the PID(s) of the running command.
460 .Dl check_pidfile $pidfile $procname
465 .Dl check_process $procname
468 Process name to check for.
469 Defaults to the value of
472 Check for the existence of the listed directories
473 before running the start method.
474 .It Sy required_files
475 Check for the readability of the listed files
476 before running the start method.
477 .It Sy required_modules
478 Ensure that the listed kernel modules are loaded
482 This is done after invoking the commands from
484 so that the missing modules are not loaded in vain
485 if the preliminary commands indicate a error condition.
486 A word in the list can have an optional
487 .Dq Li : Ns Ar modname
489 .Dq Li ~ Ns Ar pattern
495 parameter is passed to
501 option, respectively.
502 See the description of
504 in this document for details.
508 on each of the list variables
509 before running the default start method.
518 .It Sy ${name}_chroot
527 A list of environment variables to run
530 This will be passed as arguments to
537 This is usually set in
542 The environment variable
544 can be used to override this.
567 Group to run the chrooted
570 .It Sy ${name}_groups
571 Comma separated list of supplementary groups to run the chrooted
574 .It Va ${name}_prepend
575 Commands to be prepended to
577 This is a generic version of
581 .It Ar argument Ns Sy _cmd
582 Shell commands which override the default method for
584 .It Ar argument Ns Sy _precmd
585 Shell commands to run just before running
586 .Ar argument Ns Sy _cmd
587 or the default method for
589 If this returns a non-zero exit code, the main method is not performed.
590 If the default method is being executed, this check is performed after
593 checks and process (non-)existence checks.
594 .It Ar argument Ns Sy _postcmd
595 Shell commands to run if running
596 .Ar argument Ns Sy _cmd
597 or the default method for
599 returned a zero exit code.
601 Signal to send the processes to stop in the default
607 Signal to send the processes to reload in the default
617 .Ar argument Ns Sy _cmd
618 is not defined, then a default method is provided by
620 .Bl -tag -width "argument" -offset indent
627 .Ic checkyesno Sy rcvar
631 Determine the PIDs of
647 instead, and doesn't run
658 or some other script specific status operation.
666 variable is used (if any).
667 This method always works, even if the appropriate
673 The following variables are available to the methods
675 .Ar argument Ns Sy _cmd )
679 .Bl -tag -width "rc_flags" -offset indent
683 after fast and force processing has been performed.
685 Flags to start the default command with.
688 unless overridden by the environment variable
690 This variable may be changed by the
691 .Ar argument Ns Sy _precmd
706 .It Ic run_rc_script Ar file Ar argument
711 and handle the return value from the script.
713 Various shell variables are unset before
716 .Bd -ragged -offset indent
720 .Sy command_interpreter ,
727 .Ar argument Ns Sy _cmd ,
728 .Ar argument Ns Sy _precmd .
729 .Ar argument Ns Sy _postcmd .
732 The startup behaviour of
734 depends upon the following checks:
741 it is sourced into the current shell.
745 appears to be a backup or scratch file
746 (e.g., with a suffix of
756 is not executable, ignore it.
761 .Sy rc_fast_and_loose
768 into the current shell.
770 .It Ic set_rcvar Op Ar base
771 Set the variable name required to start a service. In
773 a daemon is usually controlled by an
775 variable consisting of a daemon's name optionally postfixed by the string
777 When the following line is included in a script
779 .Dl rcvar=`set_rcvar`
781 This function will use the value of the
783 variable, which should be defined by the calling script, to construct the appropriate
787 argument is set it will use
791 .It Ic wait_for_pids Op Ar pid Op Ar ...
792 Wait until all of the provided
794 don't exist any more, printing the list of outstanding
797 .It Ic warn Ar message
798 Display a warning message to
800 and log it to the system log
803 The warning message consists of the script name
812 .Bl -tag -width /etc/rc.subr -compact
828 support functions appeared in