xref: /freebsd/share/man/man8/rc.subr.8 (revision d9f0ce31900a48d1a2bfc1c8c86f79d1e831451a)
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 February 4, 2016
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 enabled
383Return 0 if the service is enabled and 1 if it is not.
384This command does not print anything.
385.It Cm rcvar
386Display which
387.Xr rc.conf 5
388variables are used to control the startup of the service (if any).
389.El
390.Pp
391If
392.Va pidfile
393or
394.Va procname
395is set, also support:
396.Bl -tag -width ".Cm restart" -offset indent
397.It Cm poll
398Wait for the command to exit.
399.It Cm status
400Show the status of the process.
401.El
402.Pp
403Other supported commands are listed in the optional variable
404.Va extra_commands .
405.Pp
406.Ar argument
407may have one of the following prefixes which alters its operation:
408.Bl -tag -width ".Li force" -offset indent
409.It Li fast
410Skip the check for an existing running process,
411and sets
412.Va rc_fast Ns = Ns Li YES .
413.It Li force
414Skip the checks for
415.Va rcvar
416being set to
417.Dq Li YES ,
418and sets
419.Va rc_force Ns = Ns Li YES .
420This ignores
421.Ar argument Ns Va _precmd
422returning non-zero, and ignores any of the
423.Va required_*
424tests failing, and always returns a zero exit status.
425.It Li one
426Skip the checks for
427.Va rcvar
428being set to
429.Dq Li YES ,
430but performs all the other prerequisite tests.
431.It Li quiet
432Inhibits some verbose diagnostics.
433Currently, this includes messages
434.Qq Starting ${name}
435(as checked by
436.Ic check_startmsgs
437inside
438.Nm )
439and errors about usage of services that are not enabled in
440.Xr rc.conf 5 .
441This prefix also sets
442.Va rc_quiet Ns = Ns Li YES .
443.Em Please, note:
444.Va rc_quiet
445is not intended to completely mask all debug and warning messages,
446but only certain small classes of them.
447.El
448.Pp
449.Ic run_rc_command
450uses the following shell variables to control its behaviour.
451Unless otherwise stated, these are optional.
452.Bl -tag -width ".Va procname" -offset indent
453.It Va name
454The name of this script.
455This is not optional.
456.It Va rcvar
457The value of
458.Va rcvar
459is checked with
460.Ic checkyesno
461to determine if this method should be run.
462.It Va command
463Full path to the command.
464Not required if
465.Ar argument Ns Va _cmd
466is defined for each supported keyword.
467Can be overridden by
468.Va ${name}_program .
469.It Va command_args
470Optional arguments and/or shell directives for
471.Va command .
472.It Va command_interpreter
473.Va command
474is started with:
475.Pp
476.Dl "#! command_interpreter [...]"
477.Pp
478which results in its
479.Xr ps 1
480command being:
481.Pp
482.Dl "command_interpreter [...] command"
483.Pp
484so use that string to find the PID(s) of the running command
485rather than
486.Va command .
487.It Va extra_commands
488Extra commands/keywords/arguments supported.
489.It Va pidfile
490Path to PID file.
491Used to determine the PID(s) of the running command.
492If
493.Va pidfile
494is set, use:
495.Pp
496.Dl "check_pidfile $pidfile $procname"
497.Pp
498to find the PID.
499Otherwise, if
500.Va command
501is set, use:
502.Pp
503.Dl "check_process $procname"
504.Pp
505to find the PID.
506.It Va procname
507Process name to check for.
508Defaults to the value of
509.Va command .
510.It Va required_dirs
511Check for the existence of the listed directories
512before running the
513.Cm start
514method.
515.It Va required_files
516Check for the readability of the listed files
517before running the
518.Cm start
519method.
520.It Va required_modules
521Ensure that the listed kernel modules are loaded
522before running the
523.Cm start
524method.
525This is done after invoking the commands from
526.Va start_precmd
527so that the missing modules are not loaded in vain
528if the preliminary commands indicate a error condition.
529A word in the list can have an optional
530.Dq Li : Ns Ar modname
531or
532.Dq Li ~ Ns Ar pattern
533suffix.
534The
535.Ar modname
536or
537.Ar pattern
538parameter is passed to
539.Ic load_kld
540through a
541.Fl m
542or
543.Fl e
544option, respectively.
545See the description of
546.Ic load_kld
547in this document for details.
548.It Va required_vars
549Perform
550.Ic checkyesno
551on each of the list variables
552before running the
553.Cm start
554method.
555.It Va ${name}_chdir
556Directory to
557.Ic cd
558to before running
559.Va command ,
560if
561.Va ${name}_chroot
562is not provided.
563.It Va ${name}_chroot
564Directory to
565.Xr chroot 8
566to before running
567.Va command .
568Only supported after
569.Pa /usr
570is mounted.
571.It Va ${name}_env
572A list of environment variables to run
573.Va command
574with.
575This will be passed as arguments to
576.Xr env 1
577utility.
578.It Va ${name}_fib
579FIB
580.Pa Routing Table
581number to run
582.Va command
583with.
584See
585.Xr setfib 1
586for more details.
587.It Va ${name}_flags
588Arguments to call
589.Va command
590with.
591This is usually set in
592.Xr rc.conf 5 ,
593and not in the
594.Xr rc.d 8
595script.
596The environment variable
597.Sq Ev flags
598can be used to override this.
599.It Va ${name}_nice
600.Xr nice 1
601level to run
602.Va command
603as.
604Only supported after
605.Pa /usr
606is mounted.
607.It Va ${name}_oomprotect
608.Xr protect 1
609.Va command
610from being killed when swap space is exhausted.
611If
612.Em YES
613is used, no child processes are protected.
614If
615.Em ALL ,
616protect all child processes.
617.It Va ${name}_program
618Full path to the command.
619Overrides
620.Va command
621if both are set, but has no effect if
622.Va command
623is unset.
624As a rule,
625.Va command
626should be set in the script while
627.Va ${name}_program
628should be set in
629.Xr rc.conf 5 .
630.It Va ${name}_user
631User to run
632.Va command
633as, using
634.Xr chroot 8
635if
636.Va ${name}_chroot
637is set, otherwise
638uses
639.Xr su 1 .
640Only supported after
641.Pa /usr
642is mounted.
643.It Va ${name}_group
644Group to run the chrooted
645.Va command
646as.
647.It Va ${name}_groups
648Comma separated list of supplementary groups to run the chrooted
649.Va command
650with.
651.It Va ${name}_prepend
652Commands to be prepended to
653.Va command .
654This is a generic version of
655.Va ${name}_env ,
656.Va ${name}_fib ,
657or
658.Va ${name}_nice .
659.It Ar argument Ns Va _cmd
660Shell commands which override the default method for
661.Ar argument .
662.It Ar argument Ns Va _precmd
663Shell commands to run just before running
664.Ar argument Ns Va _cmd
665or the default method for
666.Ar argument .
667If this returns a non-zero exit code, the main method is not performed.
668If the default method is being executed, this check is performed after
669the
670.Va required_*
671checks and process (non-)existence checks.
672.It Ar argument Ns Va _postcmd
673Shell commands to run if running
674.Ar argument Ns Va _cmd
675or the default method for
676.Ar argument
677returned a zero exit code.
678.It Va sig_stop
679Signal to send the processes to stop in the default
680.Cm stop
681method.
682Defaults to
683.Dv SIGTERM .
684.It Va sig_reload
685Signal to send the processes to reload in the default
686.Cm reload
687method.
688Defaults to
689.Dv SIGHUP .
690.El
691.Pp
692For a given method
693.Ar argument ,
694if
695.Ar argument Ns Va _cmd
696is not defined, then a default method is provided by
697.Ic run_rc_command :
698.Bl -tag -width ".Sy Argument" -offset indent
699.It Sy Argument
700.Sy Default method
701.It Cm start
702If
703.Va command
704is not running and
705.Ic checkyesno Va rcvar
706succeeds, start
707.Va command .
708.It Cm stop
709Determine the PIDs of
710.Va command
711with
712.Ic check_pidfile
713or
714.Ic check_process
715(as appropriate),
716.Ic kill Va sig_stop
717those PIDs, and run
718.Ic wait_for_pids
719on those PIDs.
720.It Cm reload
721Similar to
722.Cm stop ,
723except that it uses
724.Va sig_reload
725instead, and does not run
726.Ic wait_for_pids .
727Another difference from
728.Cm stop
729is that
730.Cm reload
731is not provided by default.
732It can be enabled via
733.Va extra_commands
734if appropriate:
735.Pp
736.Dl "extra_commands=reload"
737.It Cm restart
738Runs the
739.Cm stop
740method, then the
741.Cm start
742method.
743.It Cm status
744Show the PID of
745.Va command ,
746or some other script specific status operation.
747.It Cm poll
748Wait for
749.Va command
750to exit.
751.It Cm rcvar
752Display which
753.Xr rc.conf 5
754variable is used (if any).
755This method always works, even if the appropriate
756.Xr rc.conf 5
757variable is set to
758.Dq Li NO .
759.El
760.Pp
761The following variables are available to the methods
762(such as
763.Ar argument Ns Va _cmd )
764as well as after
765.Ic run_rc_command
766has completed:
767.Bl -tag -width ".Va rc_flags" -offset indent
768.It Va rc_arg
769Argument provided to
770.Ic run_rc_command ,
771after fast and force processing has been performed.
772.It Va rc_flags
773Flags to start the default command with.
774Defaults to
775.Va ${name}_flags ,
776unless overridden by the environment variable
777.Sq Ev flags .
778This variable may be changed by the
779.Ar argument Ns Va _precmd
780method.
781.It Va rc_pid
782PID of
783.Va command
784(if appropriate).
785.It Va rc_fast
786Not empty if
787.Dq Li fast
788prefix was used.
789.It Va rc_force
790Not empty if
791.Dq Li force
792prefix was used.
793.El
794.It Ic run_rc_script Ar file argument
795Start the script
796.Ar file
797with an argument of
798.Ar argument ,
799and handle the return value from the script.
800.Pp
801Various shell variables are unset before
802.Ar file
803is started:
804.Bd -ragged -offset indent
805.Va name ,
806.Va command ,
807.Va command_args ,
808.Va command_interpreter ,
809.Va extra_commands ,
810.Va pidfile ,
811.Va rcvar ,
812.Va required_dirs ,
813.Va required_files ,
814.Va required_vars ,
815.Ar argument Ns Va _cmd ,
816.Ar argument Ns Va _precmd .
817.Ar argument Ns Va _postcmd .
818.Ed
819.Pp
820The startup behaviour of
821.Ar file
822depends upon the following checks:
823.Bl -enum
824.It
825If
826.Ar file
827ends in
828.Pa .sh ,
829it is sourced into the current shell.
830.It
831If
832.Ar file
833appears to be a backup or scratch file
834(e.g., with a suffix of
835.Pa ~ , # , .OLD ,
836or
837.Pa .orig ) ,
838ignore it.
839.It
840If
841.Ar file
842is not executable, ignore it.
843.It
844If the
845.Xr rc.conf 5
846variable
847.Va rc_fast_and_loose
848is empty,
849source
850.Ar file
851in a sub shell,
852otherwise source
853.Ar file
854into the current shell.
855.El
856.It Ic stop_boot Op Ar always
857Prevent booting to multiuser mode.
858If the
859.Va autoboot
860variable is set to
861.Ql yes ,
862or
863.Ic checkyesno Ar always
864indicates a truth value, then a
865.Dv SIGTERM
866signal is sent to the parent
867process, which is assumed to be
868.Xr rc 8 .
869Otherwise, the shell exits with a non-zero status.
870.It Ic wait_for_pids Op Ar pid ...
871Wait until all of the provided
872.Ar pids
873do not exist any more, printing the list of outstanding
874.Ar pids
875every two seconds.
876.It Ic warn Ar message
877Display a warning message to
878.Va stderr
879and log it to the system log
880using
881.Xr logger 1 .
882The warning message consists of the script name
883(from
884.Va $0 ) ,
885followed by
886.Dq Li ": WARNING: " ,
887and then
888.Ar message .
889.El
890.Sh FILES
891.Bl -tag -width ".Pa /etc/rc.subr" -compact
892.It Pa /etc/rc.subr
893The
894.Nm
895file resides in
896.Pa /etc .
897.El
898.Sh SEE ALSO
899.Xr rc.conf 5 ,
900.Xr rc 8
901.Sh HISTORY
902The
903.Nm
904script
905appeared in
906.Nx 1.3 .
907The
908.Xr rc.d 8
909support functions appeared in
910.Nx 1.5 .
911The
912.Nm
913script
914first appeared in
915.Fx 5.0 .
916