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