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