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