xref: /freebsd/share/man/man8/rc.8 (revision 74bf4e164ba5851606a27d4feff27717452583e5)
1.\" Copyright (c) 1980, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Portions of this manual page are Copyrighted by
5.\"	The NetBSD Foundation.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. All advertising materials mentioning features or use of this software
16.\"    must display the following acknowledgement:
17.\"	This product includes software developed by the University of
18.\"	California, Berkeley and its contributors.
19.\" 4. Neither the name of the University nor the names of its contributors
20.\"    may be used to endorse or promote products derived from this software
21.\"    without specific prior written permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\"     @(#)rc.8	8.2 (Berkeley) 12/11/93
36.\" $FreeBSD$
37.\"
38.Dd November 4, 2002
39.Dt RC 8
40.Os
41.Sh NAME
42.Nm rc
43.Nd command scripts for auto-reboot and daemon startup
44.Sh SYNOPSIS
45.Nm
46.Nm rc.conf
47.Nm rc.conf.local
48.Nm rc.d/
49.Nm rc.firewall
50.Nm rc.local
51.Nm rc.shutdown
52.Nm rc.subr
53.Sh DESCRIPTION
54The
55.Nm
56utility is the command script which controls the automatic boot process
57after being called by
58.Xr init 8 .
59The
60.Nm rc.local
61script contains commands which are pertinent only
62to a specific site.
63Typically, the
64.Pa /usr/local/etc/rc.d/
65mechanism is used instead of
66.Nm rc.local
67these days but if
68you want to use
69.Nm rc.local ,
70it is still supported.
71In this case, it should source
72.Pa /etc/rc.conf
73and contain additional custom startup code for your system.
74The best way to handle
75.Nm rc.local ,
76however, is to separate it out into
77.Nm rc.d/
78style scripts and place them under
79.Pa /usr/local/etc/rc.d/ .
80The
81.Nm rc.conf
82file contains the global system configuration information referenced
83by the startup scripts, while
84.Nm rc.conf.local
85contains the local system configuration.
86See
87.Xr rc.conf 5
88for more information.
89.Pp
90The
91.Nm rc.d/
92directories contain scripts which will be automatically
93executed at boot time and shutdown time.
94.Ss Operation of Nm
95.Bl -enum
96.It
97Source
98.Pa /etc/rc.subr
99to load various
100.Xr rc.subr 8
101shell functions to use.
102.It
103If autobooting, set
104.Va autoboot Ns = Ns Li yes
105and enable a flag
106.Pq Va rc_fast Ns = Ns Li yes ,
107which prevents the
108.Nm rc.d/
109scripts from performing the check for already running processes
110(thus speeding up the boot process).
111This
112.Va rc_fast Ns = Ns Li yes
113speedup will not occur when
114.Nm
115is started up after exiting the single-user shell.
116.It
117Invoke
118.Xr rcorder 8
119to order the files in
120.Pa /etc/rc.d/
121that do not have a
122.Dq Li nostart
123keyword (refer to
124.Xr rcorder 8 Ns 's
125.Fl s
126flag),
127and assign the result to a variable.
128.It
129Call each script in turn using
130.Fn run_rc_script
131(from
132.Xr rc.subr 8 ) ,
133which sets
134.Va $1
135to
136.Dq Li start ,
137and sources the script in a subshell.
138If the script has a
139.Pa .sh
140suffix then it is sourced directly into the current shell.
141.El
142.Ss Operation of Nm rc.shutdown
143.Bl -enum
144.It
145Source
146.Pa /etc/rc.subr
147to load various
148.Xr rc.subr 8
149shell functions to use.
150.It
151Invoke
152.Xr rcorder 8
153to order the files in
154.Pa /etc/rc.d/
155that have a
156.Dq Li shutdown
157keyword (refer to
158.Xr rcorder 8 Ns 's
159.Fl k
160flag),
161reverse that order, and assign the result to a variable.
162.It
163Call each script in turn using
164.Fn run_rc_script
165(from
166.Xr rc.subr 8 ) ,
167which sets
168.Va $1
169to
170.Dq Li stop ,
171and sources the script in a subshell.
172If the script has a
173.Pa .sh
174suffix then it is sourced directly into the current shell.
175.El
176.Ss Contents of Nm rc.d/
177.Nm rc.d/
178is located in
179.Pa /etc/rc.d/ .
180The following file naming conventions are currently used in
181.Nm rc.d/ :
182.Bl -tag -width ".Pa ALLUPPERCASE" -offset indent
183.It Pa ALLUPPERCASE
184Scripts that are
185.Dq placeholders
186to ensure that certain operations are performed before others.
187In order of startup, these are:
188.Bl -tag -width ".Pa NETWORKING"
189.It Pa NETWORKING
190Ensure basic network services are running, including general
191network configuration
192.Pq Pa network1 , network2 , network3 .
193.It Pa SERVERS
194Ensure basic services (such as
195.Pa NETWORKING , ppp-user , syslogd ,
196and
197.Pa isdnd )
198exist for services that start early (such as
199.Pa named ) ,
200because they are required by
201.Pa DAEMON
202below.
203.It Pa DAEMON
204Check-point before all general purpose daemons such as
205.Pa lpd
206and
207.Pa ntpd .
208.It Pa LOGIN
209Check-point before user login services
210.Pa ( inetd
211and
212.Pa sshd ) ,
213as well as services which might run commands as users
214.Pa ( cron
215and
216.Pa sendmail ) .
217.El
218.It Pa foo.sh
219Scripts that are to be sourced into the current shell rather than a subshell
220have a
221.Pa .sh
222suffix.
223Extreme care must be taken in using this, as the startup sequence will
224terminate if the script does.
225.It Pa bar
226Scripts that are sourced in a subshell.
227These can stop the boot if necessary with the following shell
228commands:
229.Bd -literal -offset indent
230if [ "$autoboot" = yes ]; then
231	kill -TERM $$
232fi
233exit 1
234.Ed
235.Pp
236Note that this should be used extremely sparingly!
237.El
238.Pp
239Each script should contain
240.Xr rcorder 8
241keywords, especially an appropriate
242.Dq Li PROVIDE
243entry, and if necessary
244.Dq Li REQUIRE
245and
246.Dq Li BEFORE
247keywords.
248In addition, all scripts must have a
249.Dq Li "# KEYWORD: FreeBSD"
250line.
251.Pp
252Each script is expected to support at least the following arguments, which
253are automatically supported if it uses the
254.Fn run_rc_command
255function:
256.Bl -tag -width ".Cm restart" -offset indent
257.It Cm start
258Start the service.
259This should check that the service is to be started as specified by
260.Xr rc.conf 5 .
261Also checks if the service is already running and refuses to start if
262it is.
263This latter check is not performed by standard
264.Fx
265scripts if the system is starting directly to multi-user mode, to
266speed up the boot process.
267If
268.Cm forcestart
269is given, ignore the
270.Xr rc.conf 5
271check and start anyway.
272.It Cm stop
273If the service is to be started as specified by
274.Xr rc.conf 5 ,
275stop the service.
276This should check that the service is running and complain if it is not.
277If
278.Cm forcestop
279is given, ignore the
280.Xr rc.conf 5
281check and attempt to stop.
282.It Cm restart
283Perform a
284.Cm stop
285then a
286.Cm start .
287.It Cm status
288If the script starts a process (rather than performing a one-off
289operation), show the status of the process.
290Otherwise it is not necessary to support this argument.
291Defaults to displaying the process ID of the program (if running).
292.It Cm poll
293If the script starts a process (rather than performing a one-off
294operation), wait for the command to exit.
295Otherwise it is not necessary to support this argument.
296.It Cm rcvar
297Display which
298.Xr rc.conf 5
299variables are used to control the startup of the service (if any).
300.El
301.Pp
302If a script must implement additional commands it can list them in
303the
304.Va extra_commands
305variable, and define their actions in a variable constructed from
306the command name (see the
307.Sx EXAMPLES
308section).
309.Pp
310The following key points apply to old-style scripts in
311.Pa /usr/local/etc/rc.d/ :
312.Pp
313.Bl -bullet
314.It
315Scripts are only executed if their
316.Xr basename 1
317matches the shell globbing pattern
318.Pa *.sh ,
319and they are executable.
320Any other files or directories present within the directory are silently
321ignored.
322.It
323When a script is executed at boot time, it is passed the string
324.Dq Li start
325as its first and only argument.
326At shutdown time, it is passed the string
327.Dq Li stop
328as its first and only argument.
329All
330.Nm rc.d/
331scripts are expected to handle these arguments appropriately.
332If no action needs to be taken at a given time
333(either boot time or shutdown time),
334the script should exit successfully and without producing an error message.
335.It
336The scripts within each directory are executed in lexicographical order.
337If a specific order is required,
338numbers may be used as a prefix to the existing filenames,
339so for example
340.Pa 100.foo
341would be executed before
342.Pa 200.bar ;
343without the numeric prefixes the opposite would be true.
344.It
345The output from each script is traditionally a space character,
346followed by the name of the software package being started or shut down,
347.Em without
348a trailing newline character (see the
349.Sx EXAMPLES
350section).
351.El
352.Sh SCRIPTS OF INTEREST
353When an automatic reboot is in progress,
354.Nm
355is invoked with the argument
356.Cm autoboot .
357One of the scripts run from
358.Pa /etc/rc.d/
359is
360.Pa /etc/rc.d/fsck .
361This script runs
362.Xr fsck 8
363with option
364.Fl p
365and
366.Fl F
367to
368.Dq preen
369all the disks of minor inconsistencies resulting
370from the last system shutdown.
371If this fails, then checks/repairs of serious inconsistencies
372caused by hardware or software failure will be performed
373in the background at the end of the booting process.
374If
375.Cm autoboot
376is not set, when going from single-user to multi-user mode for example,
377the script does not do anything.
378.Pp
379The
380.Nm rc.early
381script is run very early in the startup process, immediately before the
382file system check.
383The
384.Nm rc.early
385script is deprecated.
386Any commands in this
387file should be separated out into
388.Nm rc.d/
389style scripts and integrated into the
390.Nm
391system.
392.Pp
393The
394.Pa /etc/rc.d/local
395script can execute scripts from multiple
396.Nm rc.d/
397directories.
398The default locations are
399.Pa /usr/local/etc/rc.d/
400and
401.Pa /usr/X11R6/etc/rc.d/ ,
402but these may be overridden with the
403.Va local_startup
404.Xr rc.conf 5
405variable.
406.Pp
407The
408.Pa /etc/rc.d/serial
409script is used to set any special configurations for serial devices.
410.Pp
411The
412.Pa /etc/rc.d/network*
413scripts are used to start the network.
414The network is started in several passes.
415The first pass,
416.Pa /etc/rc.d/network1 ,
417sets the hostname and domainname and configures the network
418interfaces.
419The
420.Pa /etc/rc.d/network2
421script starts routing and sets routing options.
422The
423.Pa /etc/rc.d/network3
424script sets additional networking options.
425Finally, the
426.Pa /etc/rc.d/network_ipv6
427script configures IPv6 interfaces and options.
428.Pp
429The
430.Nm rc.firewall
431script is used to configure rules for the kernel based firewall
432service.
433It has several possible options:
434.Pp
435.Bl -tag -width ".Ar filename" -compact -offset indent
436.It Cm open
437will allow anyone in
438.It Cm client
439will try to protect just this machine
440.It Cm simple
441will try to protect a whole network
442.It Cm closed
443totally disables IP services except via
444.Pa lo0
445interface
446.It Cm UNKNOWN
447disables the loading of firewall rules
448.It Ar filename
449will load the rules in the given filename (full path required).
450.El
451.Pp
452The
453.Pa /etc/rc.d/atm*
454scripts are used to configure ATM network interfaces.
455The interfaces are configured in three passes.
456The first pass performs the initial interface configuration.
457The second pass completes the interface configuration and defines PVCs and
458permanent ATMARP entries.
459The third pass starts any ATM daemons.
460.Pp
461Most daemons, including network related daemons, have their own script in
462.Pa /etc/rc.d/ ,
463which can be used to start, stop, and check the status of the service.
464.Pp
465Any architecture specific scripts, such as
466.Pa /etc/rc.d/apm
467for example, specifically check that they are on that architecture
468before starting the daemon.
469.Pp
470Following tradition, all startup files reside in
471.Pa /etc .
472.Sh EXAMPLES
473The following is a minimal
474.Nm rc.d/
475style script.
476Most scripts require little more than the following.
477.Bd -literal -offset indent
478#!/bin/sh
479#
480
481# PROVIDE: foo
482# REQUIRE: bar_service_required_to_precede_foo
483# BEFORE:  baz_service_requiring_foo_to_precede_it
484# KEYWORD: FreeBSD
485
486\&. /etc/rc.subr
487
488name="foo"
489rcvar=`set_rcvar`
490command="/usr/local/bin/foo"
491
492load_rc_config $name
493run_rc_command "$1"
494.Ed
495.Pp
496Certain scripts may want to provide enhanced functionality.
497The user may access this functionality through additional commands.
498The script may list and define as many commands at it needs.
499.Bd -literal -offset indent
500#!/bin/sh
501#
502
503# PROVIDE: foo
504# REQUIRE: bar_service_required_to_precede_foo
505# BEFORE:  baz_service_requiring_foo_to_precede_it
506# KEYWORD: FreeBSD
507
508\&. /etc/rc.subr
509
510name="foo"
511rcvar=`set_rcvar`
512command="/usr/local/bin/foo"
513extra_commands="nop hello"
514hello_cmd="echo Hello World."
515nop_cmd="do_nop"
516
517do_nop()
518{
519	echo "I do nothing."
520}
521
522load_rc_config $name
523run_rc_command "$1"
524.Ed
525.Pp
526The following is a simple, hypothetical example of an old-style
527.Pa /usr/local/etc/rc.d/
528script,
529which would start a daemon at boot time,
530and kill it at shutdown time.
531.Bd -literal -offset indent
532#!/bin/sh -
533#
534#    initialization/shutdown script for foobar package
535
536case "$1" in
537start)
538	/usr/local/sbin/foo -d && echo -n ' foo'
539	;;
540stop)
541	kill `cat /var/run/foo.pid` && echo -n ' foo'
542	;;
543*)
544	echo "unknown option: $1 - should be 'start' or 'stop'" >&2
545	;;
546esac
547.Ed
548.Pp
549As all processes are killed by
550.Xr init 8
551at shutdown, the explicit
552.Xr kill 1
553is unnecessary, but is often included.
554.Sh FILES
555.Bl -tag -compact
556.It Pa /etc/rc
557.It Pa /etc/rc.conf
558.It Pa /etc/rc.conf.local
559.It Pa /etc/rc.d/
560.It Pa /etc/rc.firewall
561.It Pa /etc/rc.local
562.It Pa /etc/rc.shutdown
563.It Pa /etc/rc.subr
564.It Pa /var/run/dmesg.boot
565.Xr dmesg 1
566results soon after the
567.Nm
568process begins.
569Useful when dmesg buffer in the kernel no longer has this information.
570.El
571.Sh SEE ALSO
572.Xr kill 1 ,
573.Xr rc.conf 5 ,
574.Xr init 8 ,
575.Xr rcorder 8 ,
576.Xr rc.subr 8 ,
577.Xr reboot 8 ,
578.Xr savecore 8
579.Sh HISTORY
580The
581.Nm
582utility appeared in
583.Bx 4.0 .
584