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