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 [...]"
465 .Dl "command_interpreter [...] command"
467 so use that string to find the PID(s) of the running command
470 .It Va extra_commands
471 Extra commands/keywords/arguments supported.
474 Used to determine the PID(s) of the running command.
479 .Dl "check_pidfile $pidfile $procname"
486 .Dl "check_process $procname"
490 Process name to check for.
491 Defaults to the value of
494 Check for the existence of the listed directories
495 before running the default start method.
496 .It Va required_files
497 Check for the readability of the listed files
498 before running the default start method.
502 on each of the list variables
503 before running the default start method.
512 .It Va ${name}_chroot
524 This is usually set in
529 The environment variable
531 can be used to override this.
554 Group to run the chrooted
557 .It Va ${name}_groups
558 Comma separated list of supplementary groups to run the chrooted
561 .It Ar argument Ns Va _cmd
562 Shell commands which override the default method for
564 .It Ar argument Ns Va _precmd
565 Shell commands to run just before running
566 .Ar argument Ns Va _cmd
567 or the default method for
569 If this returns a non-zero exit code, the main method is not performed.
570 If the default method is being executed, this check is performed after
573 checks and process (non-)existence checks.
574 .It Ar argument Ns Va _postcmd
575 Shell commands to run if running
576 .Ar argument Ns Va _cmd
577 or the default method for
579 returned a zero exit code.
581 Signal to send the processes to stop in the default
587 Signal to send the processes to reload in the default
597 .Ar argument Ns Va _cmd
598 is not defined, then a default method is provided by
600 .Bl -tag -width ".Sy Argument" -offset indent
607 .Ic checkyesno Va rcvar
611 Determine the PIDs of
627 instead, and does not run
629 Another difference from
633 is not provided by default.
634 It can be enabled via
638 .Dl "extra_commands=reload"
648 or some other script specific status operation.
656 variable is used (if any).
657 This method always works, even if the appropriate
663 The following variables are available to the methods
665 .Ar argument Ns Va _cmd )
669 .Bl -tag -width ".Va rc_flags" -offset indent
673 after fast and force processing has been performed.
675 Flags to start the default command with.
678 unless overridden by the environment variable
680 This variable may be changed by the
681 .Ar argument Ns Va _precmd
696 .It Ic run_rc_script Ar file argument
701 and handle the return value from the script.
703 Various shell variables are unset before
706 .Bd -ragged -offset indent
710 .Va command_interpreter ,
717 .Ar argument Ns Va _cmd ,
718 .Ar argument Ns Va _precmd .
719 .Ar argument Ns Va _postcmd .
722 The startup behaviour of
724 depends upon the following checks:
731 it is sourced into the current shell.
735 appears to be a backup or scratch file
736 (e.g., with a suffix of
744 is not executable, ignore it.
749 .Va rc_fast_and_loose
756 into the current shell.
758 .It Ic set_rcvar Op Ar base
759 Set the variable name required to start a service.
762 a daemon is usually controlled by an
764 variable consisting of a daemon's name postfixed by the string
766 This is not the case in
768 When the following line is included in a script:
770 .Dl "rcvar=`set_rcvar`"
772 this function will use the value of the
774 variable, which should be defined by the calling script,
775 to construct the appropriate
780 argument is set it will use
784 .It Ic wait_for_pids Op Ar pid ...
785 Wait until all of the provided
787 do not exist any more, printing the list of outstanding
790 .It Ic warn Ar message
791 Display a warning message to
793 and log it to the system log
796 The warning message consists of the script name
800 .Dq Li ": WARNING: " ,
805 .Bl -tag -width ".Pa /etc/rc.subr" -compact
823 support functions appeared in