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