/share/man/man8/rc.subr.8

  1.\" 	$NetBSD: rc.subr.8,v 1.12 2004/01/06 00:52:24 lukem Exp $
  2.\"
  3.\" Copyright (c) 2002-2004 The NetBSD Foundation, Inc.
  4.\" All rights reserved.
  5.\"
  6.\" This code is derived from software contributed to The NetBSD Foundation
  7.\" by Luke Mewburn.
  8.\"
  9.\" Redistribution and use in source and binary forms, with or without
 10.\" modification, are permitted provided that the following conditions
 11.\" are met:
 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.\"
 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.
 29.\"
 30.\" $FreeBSD$
 31.\"
 32.Dd January 14, 2012
 33.Dt RC.SUBR 8
 34.Os
 35.Sh NAME
 36.Nm rc.subr
 37.Nd functions used by system shell scripts
 38.Sh SYNOPSIS
 39.Bl -item -compact
 40.It
 41.Ic .\& Pa /etc/rc.subr
 42.Pp
 43.It
 44.Ic backup_file Ar action Ar file Ar current Ar backup
 45.It
 46.Ic checkyesno Ar var
 47.It
 48.Ic check_pidfile Ar pidfile Ar procname Op Ar interpreter
 49.It
 50.Ic check_process Ar procname Op Ar interpreter
 51.It
 52.Ic debug Ar message
 53.It
 54.Ic err Ar exitval Ar message
 55.It
 56.Ic force_depend Ar name
 57.It
 58.Ic info Ar message
 59.It
 60.Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file
 61.It
 62.Ic load_rc_config Ar name
 63.It
 64.Ic load_rc_config_var Ar name Ar var
 65.It
 66.Ic mount_critical_filesystems Ar type
 67.It
 68.Ic rc_usage Ar command ...
 69.It
 70.Ic reverse_list Ar item ...
 71.It
 72.Ic run_rc_command Ar argument
 73.It
 74.Ic run_rc_script Ar file Ar argument
 75.It
 76.Ic wait_for_pids Op Ar pid ...
 77.It
 78.Ic warn Ar message
 79.El
 80.Sh DESCRIPTION
 81The
 82.Nm
 83script
 84contains commonly used shell script functions and variable
 85definitions which are used by various scripts such as
 86.Xr rc 8 .
 87Scripts required by ports in
 88.Pa /usr/local/etc/rc.d
 89will also eventually
 90be rewritten to make use of it.
 91.Pp
 92The
 93.Nm
 94functions were mostly imported from
 95.Nx .
 96.Pp
 97They are accessed by sourcing
 98.Pa /etc/rc.subr
 99into the current shell.
100.Pp
101The following shell functions are available:
102.Bl -tag -width 4n
103.It Ic backup_file Ar action file current backup
104Make a backup copy of
105.Ar file
106into
107.Ar current .
108If the
109.Xr rc.conf 5
110variable
111.Va backup_uses_rcs
112is
113.Dq Li YES ,
114use
115.Xr rcs 1
116to archive the previous version of
117.Ar current ,
118otherwise save the previous version of
119.Ar current
120as
121.Ar backup .
122.Pp
123The
124.Ar action
125argument
126may be one of the following:
127.Bl -tag -width ".Cm remove"
128.It Cm add
129.Ar file
130is now being backed up by or possibly re-entered into this backup mechanism.
131.Ar current
132is created, and if necessary, the
133.Xr rcs 1
134files are created as well.
135.It Cm update
136.Ar file
137has changed and needs to be backed up.
138If
139.Ar current
140exists, it is copied to
141.Ar backup
142or checked into
143.Xr rcs 1
144(if the repository file is old),
145and then
146.Ar file
147is copied to
148.Ar current .
149.It Cm remove
150.Ar file
151is no longer being tracked by this backup mechanism.
152If
153.Xr rcs 1
154is being used, an empty file is checked in and
155.Ar current
156is removed,
157otherwise
158.Ar current
159is moved to
160.Ar backup .
161.El
162.It Ic checkyesno Ar var
163Return 0 if
164.Ar var
165is defined to
166.Dq Li YES ,
167.Dq Li TRUE ,
168.Dq Li ON ,
169or
170.Ql 1 .
171Return 1 if
172.Ar var
173is defined to
174.Dq Li NO ,
175.Dq Li FALSE ,
176.Dq Li OFF ,
177or
178.Ql 0 .
179Otherwise, warn that
180.Ar var
181is not set correctly.
182The values are case insensitive.
183.Sy Note :
184.Ar var
185should be a variable name, not its value;
186.Ic checkyesno
187will expand the variable by itself.
188.It Ic check_pidfile Ar pidfile procname Op Ar interpreter
189Parses the first word of the first line of
190.Ar pidfile
191for a PID, and ensures that the process with that PID
192is running and its first argument matches
193.Ar procname .
194Prints the matching PID if successful, otherwise nothing.
195If
196.Ar interpreter
197is provided, parse the first line of
198.Ar procname ,
199ensure that the line is of the form:
200.Pp
201.Dl "#! interpreter [...]"
202.Pp
203and use
204.Ar interpreter
205with its optional arguments and
206.Ar procname
207appended as the process string to search for.
208.It Ic check_process Ar procname Op Ar interpreter
209Prints the PIDs of any processes that are running with a first
210argument that matches
211.Ar procname .
212.Ar interpreter
213is handled as per
214.Ic check_pidfile .
215.It Ic debug Ar message
216Display a debugging message to
217.Va stderr ,
218log it to the system log using
219.Xr logger 1 ,
220and
221return to the caller.
222The error message consists of the script name
223(from
224.Va $0 ) ,
225followed by
226.Dq Li ": DEBUG: " ,
227and then
228.Ar message .
229This function is intended to be used by developers
230as an aid to debugging scripts.
231It can be turned on or off
232by the
233.Xr rc.conf 5
234variable
235.Va rc_debug .
236.It Ic err Ar exitval message
237Display an error message to
238.Va stderr ,
239log it to the system log
240using
241.Xr logger 1 ,
242and
243.Ic exit
244with an exit value of
245.Ar exitval .
246The error message consists of the script name
247(from
248.Va $0 ) ,
249followed by
250.Dq Li ": ERROR: " ,
251and then
252.Ar message .
253.It Ic force_depend Ar name
254Output an advisory message and force the
255.Ar name
256service to start.
257The
258.Ar name
259argument is the
260.Xr basename 1
261component of the path to the script, usually
262.Pa /etc/rc.d/name .
263If the script fails for any reason it will output a warning
264and return with a return value of 1.
265If it was successful
266it will return 0.
267.It Ic info Ar message
268Display an informational message to
269.Va stdout ,
270and log it to the system log using
271.Xr logger 1 .
272The message consists of the script name
273(from
274.Va $0 ) ,
275followed by
276.Dq Li ": INFO: " ,
277and then
278.Ar message .
279The display of this informational output can be
280turned on or off by the
281.Xr rc.conf 5
282variable
283.Va rc_info .
284.It Ic load_kld Oo Fl e Ar regex Oc Oo Fl m Ar module Oc Ar file
285Load
286.Ar file
287as a kernel module unless it is already loaded.
288For the purpose of checking the module status,
289either the exact module name can be specified using
290.Fl m ,
291or an
292.Xr egrep 1
293regular expression matching the module name can be supplied via
294.Fl e .
295By default, the module is assumed to have the same name as
296.Ar file ,
297which is not always the case.
298.It Ic load_rc_config Ar name
299Source in the configuration files for
300.Ar name .
301First,
302.Pa /etc/rc.conf
303is sourced if it has not yet been read in.
304Then,
305.Pa /etc/rc.conf.d/ Ns Ar name
306is sourced if it is an existing file.
307The latter may also contain other variable assignments to override
308.Ic run_rc_command
309arguments defined by the calling script, to provide an easy
310mechanism for an administrator to override the behaviour of a given
311.Xr rc.d 8
312script without requiring the editing of that script.
313.It Ic load_rc_config_var Ar name Ar var
314Read the
315.Xr rc.conf 5
316variable
317.Ar var
318for
319.Ar name
320and set in the current shell, using
321.Ic load_rc_config
322in a sub-shell to prevent unwanted side effects from other variable
323assignments.
324.It Ic mount_critical_filesystems Ar type
325Go through a list of critical file systems,
326as found in the
327.Xr rc.conf 5
328variable
329.Va critical_filesystems_ Ns Ar type ,
330mounting each one that
331is not currently mounted.
332.It Ic rc_usage Ar command ...
333Print a usage message for
334.Va $0 ,
335with
336.Ar commands
337being the list of valid arguments
338prefixed by
339.Sm off
340.Dq Bq Li fast | force | one | quiet .
341.Sm on
342.It Ic reverse_list Ar item ...
343Print the list of
344.Ar items
345in reverse order.
346.It Ic run_rc_command Ar argument
347Run the
348.Ar argument
349method for the current
350.Xr rc.d 8
351script, based on the settings of various shell variables.
352.Ic run_rc_command
353is extremely flexible, and allows fully functional
354.Xr rc.d 8
355scripts to be implemented in a small amount of shell code.
356.Pp
357.Ar argument
358is searched for in the list of supported commands, which may be one
359of:
360.Bl -tag -width ".Cm restart" -offset indent
361.It Cm start
362Start the service.
363This should check that the service is to be started as specified by
364.Xr rc.conf 5 .
365Also checks if the service is already running and refuses to start if
366it is.
367This latter check is not performed by standard
368.Fx
369scripts if the system is starting directly to multi-user mode, to
370speed up the boot process.
371.It Cm stop
372If the service is to be started as specified by
373.Xr rc.conf 5 ,
374stop the service.
375This should check that the service is running and complain if it is not.
376.It Cm restart
377Perform a
378.Cm stop
379then a
380.Cm start .
381Defaults to displaying the process ID of the program (if running).
382.It Cm rcvar
383Display which
384.Xr rc.conf 5
385variables are used to control the startup of the service (if any).
386.El
387.Pp
388If
389.Va pidfile
390or
391.Va procname
392is set, also support:
393.Bl -tag -width ".Cm restart" -offset indent
394.It Cm poll
395Wait for the command to exit.
396.It Cm status
397Show the status of the process.
398.El
399.Pp
400Other supported commands are listed in the optional variable
401.Va extra_commands .
402.Pp
403.Ar argument
404may have one of the following prefixes which alters its operation:
405.Bl -tag -width ".Li force" -offset indent
406.It Li fast
407Skip the check for an existing running process,
408and sets
409.Va rc_fast Ns = Ns Li YES .
410.It Li force
411Skip the checks for
412.Va rcvar
413being set to
414.Dq Li YES ,
415and sets
416.Va rc_force Ns = Ns Li YES .
417This ignores
418.Ar argument Ns Va _precmd
419returning non-zero, and ignores any of the
420.Va required_*
421tests failing, and always returns a zero exit status.
422.It Li one
423Skip the checks for
424.Va rcvar
425being set to
426.Dq Li YES ,
427but performs all the other prerequisite tests.
428.It Li quiet
429Inhibits some verbose diagnostics.
430Currently, this includes messages
431.Qq Starting ${name}
432(as checked by
433.Ic check_startmsgs
434inside
435.Nm )
436and errors about usage of services that are not enabled in
437.Xr rc.conf 5 .
438This prefix also sets
439.Va rc_quiet Ns = Ns Li YES .
440.Em Please, note:
441.Va rc_quiet
442is not intended to completely mask all debug and warning messages,
443but only certain small classes of them.
444.El
445.Pp
446.Ic run_rc_command
447uses the following shell variables to control its behaviour.
448Unless otherwise stated, these are optional.
449.Bl -tag -width ".Va procname" -offset indent
450.It Va name
451The name of this script.
452This is not optional.
453.It Va rcvar
454The value of
455.Va rcvar
456is checked with
457.Ic checkyesno
458to determine if this method should be run.
459.It Va command
460Full path to the command.
461Not required if
462.Ar argument Ns Va _cmd
463is defined for each supported keyword.
464Can be overridden by
465.Va ${name}_program .
466.It Va command_args
467Optional arguments and/or shell directives for
468.Va command .
469.It Va command_interpreter
470.Va command
471is started with:
472.Pp
473.Dl "#! command_interpreter [...]"
474.Pp
475which results in its
476.Xr ps 1
477command being:
478.Pp
479.Dl "command_interpreter [...] command"
480.Pp
481so use that string to find the PID(s) of the running command
482rather than
483.Va command .
484.It Va extra_commands
485Extra commands/keywords/arguments supported.
486.It Va pidfile
487Path to PID file.
488Used to determine the PID(s) of the running command.
489If
490.Va pidfile
491is set, use:
492.Pp
493.Dl "check_pidfile $pidfile $procname"
494.Pp
495to find the PID.
496Otherwise, if
497.Va command
498is set, use:
499.Pp
500.Dl "check_process $procname"
501.Pp
502to find the PID.
503.It Va procname
504Process name to check for.
505Defaults to the value of
506.Va command .
507.It Va required_dirs
508Check for the existence of the listed directories
509before running the
510.Cm start
511method.
512.It Va required_files
513Check for the readability of the listed files
514before running the
515.Cm start
516method.
517.It Va required_modules
518Ensure that the listed kernel modules are loaded
519before running the
520.Cm start
521method.
522This is done after invoking the commands from
523.Va start_precmd
524so that the missing modules are not loaded in vain
525if the preliminary commands indicate a error condition.
526A word in the list can have an optional
527.Dq Li : Ns Ar modname
528or
529.Dq Li ~ Ns Ar pattern
530suffix.
531The
532.Ar modname
533or
534.Ar pattern
535parameter is passed to
536.Ic load_kld
537through a
538.Fl m
539or
540.Fl e
541option, respectively.
542See the description of
543.Ic load_kld
544in this document for details.
545.It Va required_vars
546Perform
547.Ic checkyesno
548on each of the list variables
549before running the
550.Cm start
551method.
552.It Va ${name}_chdir
553Directory to
554.Ic cd
555to before running
556.Va command ,
557if
558.Va ${name}_chroot
559is not provided.
560.It Va ${name}_chroot
561Directory to
562.Xr chroot 8
563to before running
564.Va command .
565Only supported after
566.Pa /usr
567is mounted.
568.It Va ${name}_flags
569Arguments to call
570.Va command
571with.
572This is usually set in
573.Xr rc.conf 5 ,
574and not in the
575.Xr rc.d 8
576script.
577The environment variable
578.Sq Ev flags
579can be used to override this.
580.It Va ${name}_nice
581.Xr nice 1
582level to run
583.Va command
584as.
585Only supported after
586.Pa /usr
587is mounted.
588.It Va ${name}_program
589Full path to the command.
590Overrides
591.Va command
592if both are set, but has no effect if
593.Va command
594is unset.
595As a rule,
596.Va command
597should be set in the script while
598.Va ${name}_program
599should be set in
600.Xr rc.conf 5 .
601.It Va ${name}_user
602User to run
603.Va command
604as, using
605.Xr chroot 8
606if
607.Va ${name}_chroot
608is set, otherwise
609uses
610.Xr su 1 .
611Only supported after
612.Pa /usr
613is mounted.
614.It Va ${name}_group
615Group to run the chrooted
616.Va command
617as.
618.It Va ${name}_groups
619Comma separated list of supplementary groups to run the chrooted
620.Va command
621with.
622.It Ar argument Ns Va _cmd
623Shell commands which override the default method for
624.Ar argument .
625.It Ar argument Ns Va _precmd
626Shell commands to run just before running
627.Ar argument Ns Va _cmd
628or the default method for
629.Ar argument .
630If this returns a non-zero exit code, the main method is not performed.
631If the default method is being executed, this check is performed after
632the
633.Va required_*
634checks and process (non-)existence checks.
635.It Ar argument Ns Va _postcmd
636Shell commands to run if running
637.Ar argument Ns Va _cmd
638or the default method for
639.Ar argument
640returned a zero exit code.
641.It Va sig_stop
642Signal to send the processes to stop in the default
643.Cm stop
644method.
645Defaults to
646.Dv SIGTERM .
647.It Va sig_reload
648Signal to send the processes to reload in the default
649.Cm reload
650method.
651Defaults to
652.Dv SIGHUP .
653.El
654.Pp
655For a given method
656.Ar argument ,
657if
658.Ar argument Ns Va _cmd
659is not defined, then a default method is provided by
660.Ic run_rc_command :
661.Bl -tag -width ".Sy Argument" -offset indent
662.It Sy Argument
663.Sy Default method
664.It Cm start
665If
666.Va command
667is not running and
668.Ic checkyesno Va rcvar
669succeeds, start
670.Va command .
671.It Cm stop
672Determine the PIDs of
673.Va command
674with
675.Ic check_pidfile
676or
677.Ic check_process
678(as appropriate),
679.Ic kill Va sig_stop
680those PIDs, and run
681.Ic wait_for_pids
682on those PIDs.
683.It Cm reload
684Similar to
685.Cm stop ,
686except that it uses
687.Va sig_reload
688instead, and does not run
689.Ic wait_for_pids .
690Another difference from
691.Cm stop
692is that
693.Cm reload
694is not provided by default.
695It can be enabled via
696.Va extra_commands
697if appropriate:
698.Pp
699.Dl "extra_commands=reload"
700.It Cm restart
701Runs the
702.Cm stop
703method, then the
704.Cm start
705method.
706.It Cm status
707Show the PID of
708.Va command ,
709or some other script specific status operation.
710.It Cm poll
711Wait for
712.Va command
713to exit.
714.It Cm rcvar
715Display which
716.Xr rc.conf 5
717variable is used (if any).
718This method always works, even if the appropriate
719.Xr rc.conf 5
720variable is set to
721.Dq Li NO .
722.El
723.Pp
724The following variables are available to the methods
725(such as
726.Ar argument Ns Va _cmd )
727as well as after
728.Ic run_rc_command
729has completed:
730.Bl -tag -width ".Va rc_flags" -offset indent
731.It Va rc_arg
732Argument provided to
733.Ic run_rc_command ,
734after fast and force processing has been performed.
735.It Va rc_flags
736Flags to start the default command with.
737Defaults to
738.Va ${name}_flags ,
739unless overridden by the environment variable
740.Sq Ev flags .
741This variable may be changed by the
742.Ar argument Ns Va _precmd
743method.
744.It Va rc_pid
745PID of
746.Va command
747(if appropriate).
748.It Va rc_fast
749Not empty if
750.Dq Li fast
751prefix was used.
752.It Va rc_force
753Not empty if
754.Dq Li force
755prefix was used.
756.El
757.It Ic run_rc_script Ar file argument
758Start the script
759.Ar file
760with an argument of
761.Ar argument ,
762and handle the return value from the script.
763.Pp
764Various shell variables are unset before
765.Ar file
766is started:
767.Bd -ragged -offset indent
768.Va name ,
769.Va command ,
770.Va command_args ,
771.Va command_interpreter ,
772.Va extra_commands ,
773.Va pidfile ,
774.Va rcvar ,
775.Va required_dirs ,
776.Va required_files ,
777.Va required_vars ,
778.Ar argument Ns Va _cmd ,
779.Ar argument Ns Va _precmd .
780.Ar argument Ns Va _postcmd .
781.Ed
782.Pp
783The startup behaviour of
784.Ar file
785depends upon the following checks:
786.Bl -enum
787.It
788If
789.Ar file
790ends in
791.Pa .sh ,
792it is sourced into the current shell.
793.It
794If
795.Ar file
796appears to be a backup or scratch file
797(e.g., with a suffix of
798.Pa ~ , # , .OLD ,
799or
800.Pa .orig ) ,
801ignore it.
802.It
803If
804.Ar file
805is not executable, ignore it.
806.It
807If the
808.Xr rc.conf 5
809variable
810.Va rc_fast_and_loose
811is empty,
812source
813.Ar file
814in a sub shell,
815otherwise source
816.Ar file
817into the current shell.
818.El
819.It Ic stop_boot Op Ar always
820Prevent booting to multiuser mode.
821If the
822.Va autoboot
823variable is set to
824.Ql yes ,
825or
826.Ic checkyesno Ar always
827indicates a truth value, then a
828.Dv SIGTERM
829signal is sent to the parent
830process, which is assumed to be
831.Xr rc 8 .
832Otherwise, the shell exits with a non-zero status.
833.It Ic wait_for_pids Op Ar pid ...
834Wait until all of the provided
835.Ar pids
836do not exist any more, printing the list of outstanding
837.Ar pids
838every two seconds.
839.It Ic warn Ar message
840Display a warning message to
841.Va stderr
842and log it to the system log
843using
844.Xr logger 1 .
845The warning message consists of the script name
846(from
847.Va $0 ) ,
848followed by
849.Dq Li ": WARNING: " ,
850and then
851.Ar message .
852.El
853.Sh FILES
854.Bl -tag -width ".Pa /etc/rc.subr" -compact
855.It Pa /etc/rc.subr
856The
857.Nm
858file resides in
859.Pa /etc .
860.El
861.Sh SEE ALSO
862.Xr rc.conf 5 ,
863.Xr rc 8
864.Sh HISTORY
865The
866.Nm
867script
868appeared in
869.Nx 1.3 .
870The
871.Xr rc.d 8
872support functions appeared in
873.Nx 1.5 .
874The
875.Nm
876script
877first appeared in
878.Fx 5.0 .