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_rc_config Ar command
69 .Ic mount_critical_filesystems Ar type
71 .Ic rc_usage Ar command ...
73 .Ic reverse_list Ar item ...
75 .Ic run_rc_command Ar argument
77 .Ic run_rc_script Ar file Ar argument
79 .Ic set_rcvar Op Ar base
81 .Ic wait_for_pids Op Ar pid ...
89 contains commonly used shell script functions and variable
90 definitions which are used by various scripts such as
92 Scripts required by ports in
93 .Pa /usr/local/etc/rc.d
95 be rewritten to make use of it.
99 functions were mostly imported from
101 and it is intended that they remain synced between the
103 With that in mind there are several variable
104 definitions that can help in this regard.
108 Its value will be either
112 depending on which OS it is running on.
118 The path and argument list to display only the
121 .Ar name Ns = Ns Ar value
124 The path and argument to write or modify
131 functions are accessed by sourcing
133 into the current shell.
135 The following shell functions are available:
137 .It Ic backup_file Ar action file current backup
138 Make a backup copy of
150 to archive the previous version of
152 otherwise save the previous version of
160 may be one of the following:
161 .Bl -tag -width ".Cm remove"
164 is now being backed up by or possibly re-entered into this backup mechanism.
166 is created, and if necessary, the
168 files are created as well.
171 has changed and needs to be backed up.
174 exists, it is copied to
178 (if the repository file is old),
185 is no longer being tracked by this backup mechanism.
188 is being used, an empty file is checked in and
196 .It Ic checkyesno Ar var
215 is not set correctly.
216 The values are case insensitive.
217 .It Ic check_pidfile Ar pidfile procname Op Ar interpreter
218 Parses the first word of the first line of
220 for a PID, and ensures that the process with that PID
221 is running and its first argument matches
223 Prints the matching PID if successful, otherwise nothing.
226 is provided, parse the first line of
228 ensure that the line is of the form
230 .Dl "#! interpreter [...]"
234 with its optional arguments and
236 appended as the process string to search for.
237 .It Ic check_process Ar procname Op Ar interpreter
238 Prints the PIDs of any processes that are running with a first
239 argument that matches
244 .It Ic debug Ar message
245 Display a debugging message to
247 log it to the system log using
250 return to the caller.
251 The error message consists of the script name
258 This function is intended to be used by developers
259 as an aid to debugging scripts.
260 It can be turned on or off
265 .It Ic err Ar exitval message
266 Display an error message to
268 log it to the system log
273 with an exit value of
275 The error message consists of the script name
282 .It Ic force_depend name
283 Output an advisory message and force the
290 component of the path to the script, usually
292 If the script fails for any reason it will output a warning
293 and return with a return value of 1.
296 .It Ic info Ar message
297 Display an informational message to
299 and log it to the system log using
301 The message consists of the script name
308 The display of this informational output can be
309 turned on or off by the
313 .It Ic load_rc_config Ar command
314 Source in the configuration files for
318 is sourced if it has not yet been read in.
320 .Pa /etc/rc.conf.d/ Ns Ar command
321 is sourced if it is an existing file.
322 The latter may also contain other variable assignments to override
324 arguments defined by the calling script, to provide an easy
325 mechanism for an administrator to override the behaviour of a given
327 script without requiring the editing of that script.
328 .It Ic mount_critical_filesystems Ar type
329 Go through a list of critical file systems,
333 .Va critical_filesystems_ Ns Ar type ,
334 mounting each one that
335 is not currently mounted.
336 .It Ic rc_usage Ar command ...
337 Print a usage message for
341 being the list of valid arguments
344 .Dq Bq Li fast | force | one .
346 .It Ic reverse_list Ar item ...
350 .It Ic run_rc_command Ar argument
353 method for the current
355 script, based on the settings of various shell variables.
357 is extremely flexible, and allows fully functional
359 scripts to be implemented in a small amount of shell code.
362 is searched for in the list of supported commands, which may be one
364 .Bl -tag -width ".Cm restart" -offset indent
367 This should check that the service is to be started as specified by
369 Also checks if the service is already running and refuses to start if
371 This latter check is not performed by standard
373 scripts if the system is starting directly to multi-user mode, to
374 speed up the boot process.
376 If the service is to be started as specified by
379 This should check that the service is running and complain if it is not.
385 Defaults to displaying the process ID of the program (if running).
389 variables are used to control the startup of the service (if any).
396 is set, also support:
397 .Bl -tag -width ".Cm restart" -offset indent
399 Wait for the command to exit.
401 Show the status of the process.
404 Other supported commands are listed in the optional variable
408 may have one of the following prefixes which alters its operation:
409 .Bl -tag -width ".Li force" -offset indent
411 Skip the check for an existing running process,
413 .Va rc_fast Ns = Ns Li YES .
420 .Va rc_force Ns = Ns Li YES .
422 .Ar argument Ns Va _precmd
423 returning non-zero, and ignores any of the
425 tests failing, and always returns a zero exit status.
431 but performs all the other prerequisite tests.
435 uses the following shell variables to control its behaviour.
436 Unless otherwise stated, these are optional.
437 .Bl -tag -width ".Va procname" -offset indent
439 The name of this script.
440 This is not optional.
446 to determine if this method should be run.
448 Full path to the command.
450 .Ar argument Ns Va _cmd
451 is defined for each supported keyword.
453 Optional arguments and/or shell directives for
455 .It Va command_interpreter
459 .Dl "#! command_interpreter [...]"
464 .Dl "command_interpreter [...] command"
466 so use that string to find the PID(s) of the running command
469 .It Va extra_commands
470 Extra commands/keywords/arguments supported.
473 Used to determine the PID(s) of the running command.
478 .Dl "check_pidfile $pidfile $procname"
485 .Dl "check_process $procname"
489 Process name to check for.
490 Defaults to the value of
493 Check for the existence of the listed directories
494 before running the default start method.
495 .It Va required_files
496 Check for the readability of the listed files
497 before running the default start method.
501 on each of the list variables
502 before running the default start method.
511 .It Va ${name}_chroot
523 This is usually set in
528 The environment variable
530 can be used to override this.
553 Group to run the chrooted
556 .It Va ${name}_groups
557 Comma separated list of supplementary groups to run the chrooted
560 .It Ar argument Ns Va _cmd
561 Shell commands which override the default method for
563 .It Ar argument Ns Va _precmd
564 Shell commands to run just before running
565 .Ar argument Ns Va _cmd
566 or the default method for
568 If this returns a non-zero exit code, the main method is not performed.
569 If the default method is being executed, this check is performed after
572 checks and process (non-)existence checks.
573 .It Ar argument Ns Va _postcmd
574 Shell commands to run if running
575 .Ar argument Ns Va _cmd
576 or the default method for
578 returned a zero exit code.
580 Signal to send the processes to stop in the default
586 Signal to send the processes to reload in the default
596 .Ar argument Ns Va _cmd
597 is not defined, then a default method is provided by
599 .Bl -tag -width ".Sy Argument" -offset indent
606 .Ic checkyesno Va rcvar
610 Determine the PIDs of
626 instead, and does not run
637 or some other script specific status operation.
645 variable is used (if any).
646 This method always works, even if the appropriate
652 The following variables are available to the methods
654 .Ar argument Ns Va _cmd )
658 .Bl -tag -width ".Va rc_flags" -offset indent
662 after fast and force processing has been performed.
664 Flags to start the default command with.
667 unless overridden by the environment variable
669 This variable may be changed by the
670 .Ar argument Ns Va _precmd
685 .It Ic run_rc_script Ar file argument
690 and handle the return value from the script.
692 Various shell variables are unset before
695 .Bd -ragged -offset indent
699 .Va command_interpreter ,
706 .Ar argument Ns Va _cmd ,
707 .Ar argument Ns Va _precmd .
708 .Ar argument Ns Va _postcmd .
711 The startup behaviour of
713 depends upon the following checks:
720 it is sourced into the current shell.
724 appears to be a backup or scratch file
725 (e.g., with a suffix of
733 is not executable, ignore it.
738 .Va rc_fast_and_loose
745 into the current shell.
747 .It Ic set_rcvar Op Ar base
748 Set the variable name required to start a service.
751 a daemon is usually controlled by an
753 variable consisting of a daemon's name postfixed by the string
755 This is not the case in
757 When the following line is included in a script
759 .Dl "rcvar=`set_rcvar`"
761 This function will use the value of the
763 variable, which should be defined by the calling script, to construct the appropriate
768 argument is set it will use
772 .It Ic wait_for_pids Op Ar pid ...
773 Wait until all of the provided
775 do not exist any more, printing the list of outstanding
778 .It Ic warn Ar message
779 Display a warning message to
781 and log it to the system log
784 The warning message consists of the script name
788 .Dq Li ": WARNING: " ,
793 .Bl -tag -width ".Pa /etc/rc.subr" -compact
811 support functions appeared in