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