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