Remove last traces of 'DragonFly' keywords in RCNG scripts.
[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 $
3d352d22 37.\" $DragonFly: src/share/man/man8/rc.8,v 1.6 2005/12/10 00:11:08 swildner Exp $
65abf490 38.Dd November 4, 2002
984263bc
MD
39.Dt RC 8
40.Os
41.Sh NAME
42.Nm rc
65abf490 43.Nd command scripts for auto-reboot and daemon startup
984263bc
MD
44.Sh SYNOPSIS
45.Nm
46.Nm rc.conf
47.Nm rc.conf.local
65abf490 48.Nm rc.d/
984263bc 49.Nm rc.firewall
984263bc
MD
50.Nm rc.local
51.Nm rc.shutdown
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
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
984263bc 66.Nm rc.local
65abf490
RG
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
984263bc
MD
84.Nm rc.conf.local
85contains the local system configuration.
86See
65abf490
RG
87.Xr rc.conf 5
88for more information.
984263bc
MD
89.Pp
90The
65abf490 91.Nm rc.d/
984263bc
MD
92directories contain scripts which will be automatically
93executed at boot time and shutdown time.
65abf490
RG
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.
984263bc 248.Pp
65abf490
RG
249Each script is expected to support at least the following arguments, which
250are automatically supported if it uses the
251.Fn run_rc_command
252function:
253.Bl -tag -width ".Cm restart" -offset indent
254.It Cm start
255Start the service.
256This should check that the service is to be started as specified by
257.Xr rc.conf 5 .
258Also checks if the service is already running and refuses to start if
259it is.
260This latter check is not performed by standard
9bb2a92d 261.Dx
65abf490
RG
262scripts if the system is starting directly to multi-user mode, to
263speed up the boot process.
264If
265.Cm forcestart
266is given, ignore the
267.Xr rc.conf 5
268check and start anyway.
269.It Cm stop
270If the service is to be started as specified by
271.Xr rc.conf 5 ,
272stop the service.
273This should check that the service is running and complain if it is not.
274If
275.Cm forcestop
276is given, ignore the
277.Xr rc.conf 5
278check and attempt to stop.
279.It Cm restart
280Perform a
281.Cm stop
282then a
283.Cm start .
284.It Cm status
285If the script starts a process (rather than performing a one-off
286operation), show the status of the process.
287Otherwise it is not necessary to support this argument.
288Defaults to displaying the process ID of the program (if running).
289.It Cm poll
290If the script starts a process (rather than performing a one-off
291operation), wait for the command to exit.
292Otherwise it is not necessary to support this argument.
293.It Cm rcvar
294Display which
295.Xr rc.conf 5
296variables are used to control the startup of the service (if any).
297.El
298.Pp
299If a script must implement additional commands it can list them in
300the
301.Va extra_commands
302variable, and define their actions in a variable constructed from
303the command name (see the
304.Sx EXAMPLES
305section).
306.Pp
307The following key points apply to old-style scripts in
308.Pa /usr/local/etc/rc.d/ :
309.Pp
310.Bl -bullet
984263bc
MD
311.It
312Scripts are only executed if their
313.Xr basename 1
314matches the shell globbing pattern
315.Pa *.sh ,
316and they are executable.
317Any other files or directories present within the directory are silently
318ignored.
319.It
320When a script is executed at boot time, it is passed the string
65abf490 321.Dq Li start
984263bc
MD
322as its first and only argument.
323At shutdown time, it is passed the string
65abf490 324.Dq Li stop
984263bc
MD
325as its first and only argument.
326All
65abf490 327.Nm rc.d/
984263bc
MD
328scripts are expected to handle these arguments appropriately.
329If no action needs to be taken at a given time
65abf490 330(either boot time or shutdown time),
984263bc
MD
331the script should exit successfully and without producing an error message.
332.It
333The scripts within each directory are executed in lexicographical order.
334If a specific order is required,
335numbers may be used as a prefix to the existing filenames,
336so for example
337.Pa 100.foo
338would be executed before
339.Pa 200.bar ;
340without the numeric prefixes the opposite would be true.
65abf490 341.It
984263bc
MD
342The output from each script is traditionally a space character,
343followed by the name of the software package being started or shut down,
344.Em without
345a trailing newline character (see the
346.Sx EXAMPLES
347section).
65abf490
RG
348.El
349.Sh SCRIPTS OF INTEREST
984263bc
MD
350When an automatic reboot is in progress,
351.Nm
352is invoked with the argument
65abf490
RG
353.Cm autoboot .
354One of the scripts run from
355.Pa /etc/rc.d/
356is
357.Pa /etc/rc.d/fsck .
358This script runs
984263bc
MD
359.Xr fsck 8
360with option
361.Fl p
65abf490
RG
362and
363.Fl F
364to
365.Dq preen
366all the disks of minor inconsistencies resulting
367from the last system shutdown.
368If this fails, then checks/repairs of serious inconsistencies
369caused by hardware or software failure will be performed
370in the background at the end of the booting process.
371If
372.Cm autoboot
373is not set, when going from single-user to multi-user mode for example,
374the script does not do anything.
984263bc 375.Pp
65abf490
RG
376The
377.Nm rc.early
378script is run very early in the startup process, immediately before the
379file system check.
380The
381.Nm rc.early
382script is deprecated.
383Any commands in this
384file should be separated out into
385.Nm rc.d/
386style scripts and integrated into the
984263bc 387.Nm
65abf490 388system.
984263bc 389.Pp
65abf490
RG
390The
391.Pa /etc/rc.d/local
392script can execute scripts from multiple
393.Nm rc.d/
394directories.
395The default locations are
396.Pa /usr/local/etc/rc.d/
397and
398.Pa /usr/X11R6/etc/rc.d/ ,
399but these may be overridden with the
400.Va local_startup
401.Xr rc.conf 5
402variable.
984263bc 403.Pp
65abf490
RG
404The
405.Pa /etc/rc.d/serial
406script is used to set any special configurations for serial devices.
984263bc 407.Pp
65abf490 408The
65abf490
RG
409.Pa /etc/rc.d/network*
410scripts are used to start the network.
411The network is started in several passes.
412The first pass,
413.Pa /etc/rc.d/network1 ,
414sets the hostname and domainname and configures the network
415interfaces.
416The
417.Pa /etc/rc.d/network2
418script starts routing and sets routing options.
419The
420.Pa /etc/rc.d/network3
421script sets additional networking options.
422Finally, the
423.Pa /etc/rc.d/network_ipv6
424script configures IPv6 interfaces and options.
984263bc 425.Pp
65abf490
RG
426The
427.Nm rc.firewall
428script is used to configure rules for the kernel based firewall
984263bc
MD
429service.
430It has several possible options:
431.Pp
65abf490
RG
432.Bl -tag -width ".Ar filename" -compact -offset indent
433.It Cm open
434will allow anyone in
435.It Cm client
436will try to protect just this machine
437.It Cm simple
438will try to protect a whole network
439.It Cm closed
440totally disables IP services except via
441.Pa lo0
442interface
443.It Cm UNKNOWN
444disables the loading of firewall rules
445.It Ar filename
984263bc
MD
446will load the rules in the given filename (full path required).
447.El
448.Pp
65abf490
RG
449The
450.Pa /etc/rc.d/atm*
451scripts are used to configure ATM network interfaces.
984263bc
MD
452The interfaces are configured in three passes.
453The first pass performs the initial interface configuration.
454The second pass completes the interface configuration and defines PVCs and
455permanent ATMARP entries.
456The third pass starts any ATM daemons.
457.Pp
65abf490
RG
458Most daemons, including network related daemons, have their own script in
459.Pa /etc/rc.d/ ,
460which can be used to start, stop, and check the status of the service.
984263bc 461.Pp
65abf490
RG
462Any architecture specific scripts, such as
463.Pa /etc/rc.d/apm
464for example, specifically check that they are on that architecture
465before starting the daemon.
984263bc 466.Pp
65abf490 467Following tradition, all startup files reside in
984263bc
MD
468.Pa /etc .
469.Sh EXAMPLES
65abf490
RG
470The following is a minimal
471.Nm rc.d/
472style script.
473Most scripts require little more than the following.
474.Bd -literal -offset indent
475#!/bin/sh
476#
477
478# PROVIDE: foo
479# REQUIRE: bar_service_required_to_precede_foo
480# BEFORE: baz_service_requiring_foo_to_precede_it
65abf490
RG
481
482\&. /etc/rc.subr
483
484name="foo"
485rcvar=`set_rcvar`
486command="/usr/local/bin/foo"
487
488load_rc_config $name
489run_rc_command "$1"
490.Ed
491.Pp
492Certain scripts may want to provide enhanced functionality.
493The user may access this functionality through additional commands.
494The script may list and define as many commands at it needs.
495.Bd -literal -offset indent
496#!/bin/sh
497#
498
499# PROVIDE: foo
500# REQUIRE: bar_service_required_to_precede_foo
501# BEFORE: baz_service_requiring_foo_to_precede_it
65abf490
RG
502
503\&. /etc/rc.subr
504
505name="foo"
506rcvar=`set_rcvar`
507command="/usr/local/bin/foo"
508extra_commands="nop hello"
509hello_cmd="echo Hello World."
510nop_cmd="do_nop"
511
512do_nop()
513{
514 echo "I do nothing."
515}
516
517load_rc_config $name
518run_rc_command "$1"
519.Ed
520.Pp
521The following is a simple, hypothetical example of an old-style
522.Pa /usr/local/etc/rc.d/
984263bc
MD
523script,
524which would start a daemon at boot time,
525and kill it at shutdown time.
526.Bd -literal -offset indent
527#!/bin/sh -
528#
529# initialization/shutdown script for foobar package
530
531case "$1" in
532start)
533 /usr/local/sbin/foo -d && echo -n ' foo'
534 ;;
535stop)
536 kill `cat /var/run/foo.pid` && echo -n ' foo'
537 ;;
538*)
539 echo "unknown option: $1 - should be 'start' or 'stop'" >&2
540 ;;
541esac
542.Ed
543.Pp
544As all processes are killed by
545.Xr init 8
546at shutdown, the explicit
547.Xr kill 1
548is unnecessary, but is often included.
65abf490
RG
549.Sh FILES
550.Bl -tag -compact
551.It Pa /etc/rc
552.It Pa /etc/rc.conf
553.It Pa /etc/rc.conf.local
554.It Pa /etc/rc.d/
555.It Pa /etc/rc.firewall
556.It Pa /etc/rc.local
557.It Pa /etc/rc.shutdown
558.It Pa /etc/rc.subr
559.El
984263bc
MD
560.Sh SEE ALSO
561.Xr kill 1 ,
562.Xr rc.conf 5 ,
563.Xr init 8 ,
65abf490
RG
564.Xr rc.subr 8 ,
565.Xr rcorder 8 ,
984263bc
MD
566.Xr reboot 8 ,
567.Xr savecore 8
568.Sh HISTORY
569The
570.Nm
65abf490 571utility appeared in
984263bc 572.Bx 4.0 .