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$
  37 .\"
  38 .Dd May 18, 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 If autobooting, set
  98 .Va autoboot Ns = Ns Li yes
  99 and enable a flag
 100 .Pq Va rc_fast Ns = Ns Li yes ,
 101 which prevents the
 102 .Nm rc.d/
 103 scripts from performing the check for already running processes
 104 (thus speeding up the boot process).
 105 This
 106 .Va rc_fast Ns = Ns Li yes
 107 speedup will not occur when
 108 .Nm
 109 is started up after exiting the single-user shell.
 110 .It
 111 Determine whether the system is booting diskless,
 112 and if so run the
 113 .Pa /etc/rc.initdiskless
 114 script.
 115 .It
 116 Source
 117 .Pa /etc/rc.subr
 118 to load various
 119 .Xr rc.subr 8
 120 shell functions to use.
 121 .It
 122 Load the configuration files.
 123 .It
 124 Determine if booting in a jail,
 125 and add
 126 .Dq Li nojail
 127 to the list of KEYWORDS to skip in
 128 .Xr rcorder 8 .
 129 .It
 130 Invoke
 131 .Xr rcorder 8
 132 to order the files in
 133 .Pa /etc/rc.d/
 134 that do not have a
 135 .Dq Li nostart
 136 KEYWORD (refer to
 137 .Xr rcorder 8 Ns 's
 138 .Fl s
 139 flag).
 140 .It
 141 Call each script in turn using
 142 .Fn run_rc_script
 143 (from
 144 .Xr rc.subr 8 ) ,
 145 which sets
 146 .Va $1
 147 to
 148 .Dq Li start ,
 149 and sources the script in a subshell.
 150 If the script has a
 151 .Pa .sh
 152 suffix then it is sourced directly into the current shell.
 153 Stop processing when the script that is the value of the
 154 .Va $early_late_divider
 155 has been run.
 156 .It
 157 Re-run
 158 .Xr rcorder 8 ,
 159 this time including the scripts in the
 160 .Va $local_startup
 161 directories.
 162 Ignore everything up to the
 163 .Va $early_late_divider ,
 164 then start executing the scripts as described above.
 165 .El
 166 .Ss Operation of Nm rc.shutdown
 167 .Bl -enum
 168 .It
 169 Source
 170 .Pa /etc/rc.subr
 171 to load various
 172 .Xr rc.subr 8
 173 shell functions to use.
 174 .It
 175 Load the configuration files.
 176 .It
 177 Invoke
 178 .Xr rcorder 8
 179 to order the files in
 180 .Pa /etc/rc.d/
 181 and the
 182 .Va $local_startup
 183 directories
 184 that have a
 185 .Dq Li shutdown
 186 KEYWORD (refer to
 187 .Xr rcorder 8 Ns 's
 188 .Fl k
 189 flag),
 190 reverse that order, and assign the result to a variable.
 191 .It
 192 Call each script in turn using
 193 .Fn run_rc_script
 194 (from
 195 .Xr rc.subr 8 ) ,
 196 which sets
 197 .Va $1
 198 to
 199 .Dq Li stop ,
 200 and sources the script in a subshell.
 201 If the script has a
 202 .Pa .sh
 203 suffix then it is sourced directly into the current shell.
 204 .El
 205 .Ss Contents of Nm rc.d/
 206 .Nm rc.d/
 207 is located in
 208 .Pa /etc/rc.d/ .
 209 The following file naming conventions are currently used in
 210 .Nm rc.d/ :
 211 .Bl -tag -width ".Pa ALLUPPERCASE" -offset indent
 212 .It Pa ALLUPPERCASE
 213 Scripts that are
 214 .Dq placeholders
 215 to ensure that certain operations are performed before others.
 216 In order of startup, these are:
 217 .Bl -tag -width ".Pa NETWORKING"
 218 .It Pa NETWORKING
 219 Ensure basic network services are running, including general
 220 network configuration.
 221 .It Pa SERVERS
 222 Ensure basic services
 223 exist for services that start early (such as
 224 .Pa named ) ,
 225 because they are required by
 226 .Pa DAEMON
 227 below.
 228 .It Pa DAEMON
 229 Check-point before all general purpose daemons such as
 230 .Pa lpd
 231 and
 232 .Pa ntpd .
 233 .It Pa LOGIN
 234 Check-point before user login services
 235 .Pa ( inetd
 236 and
 237 .Pa sshd ) ,
 238 as well as services which might run commands as users
 239 .Pa ( cron
 240 and
 241 .Pa sendmail ) .
 242 .El
 243 .It Pa foo.sh
 244 Scripts that are to be sourced into the current shell rather than a subshell
 245 have a
 246 .Pa .sh
 247 suffix.
 248 Extreme care must be taken in using this, as the startup sequence will
 249 terminate if the script does.
 250 .It Pa bar
 251 Scripts that are sourced in a subshell.
 252 The boot does not stop if such a script terminates with a non-zero status,
 253 but a script can stop the boot if necessary by invoking the
 254 .Fn stop_boot
 255 function (from
 256 .Xr rc.subr 8 ).
 257 .El
 258 .Pp
 259 Each script should contain
 260 .Xr rcorder 8
 261 keywords, especially an appropriate
 262 .Dq Li PROVIDE
 263 entry, and if necessary
 264 .Dq Li REQUIRE
 265 and
 266 .Dq Li BEFORE
 267 keywords.
 268 .Pp
 269 Each script is expected to support at least the following arguments, which
 270 are automatically supported if it uses the
 271 .Fn run_rc_command
 272 function:
 273 .Bl -tag -width ".Cm restart" -offset indent
 274 .It Cm start
 275 Start the service.
 276 This should check that the service is to be started as specified by
 277 .Xr rc.conf 5 .
 278 Also checks if the service is already running and refuses to start if
 279 it is.
 280 This latter check is not performed by standard
 281 .Fx
 282 scripts if the system is starting directly to multi-user mode, to
 283 speed up the boot process.
 284 If
 285 .Cm forcestart
 286 is given, ignore the
 287 .Xr rc.conf 5
 288 check and start anyway.
 289 .It Cm stop
 290 If the service is to be started as specified by
 291 .Xr rc.conf 5 ,
 292 stop the service.
 293 This should check that the service is running and complain if it is not.
 294 If
 295 .Cm forcestop
 296 is given, ignore the
 297 .Xr rc.conf 5
 298 check and attempt to stop.
 299 .It Cm restart
 300 Perform a
 301 .Cm stop
 302 then a
 303 .Cm start .
 304 .It Cm status
 305 If the script starts a process (rather than performing a one-off
 306 operation), show the status of the process.
 307 Otherwise it is not necessary to support this argument.
 308 Defaults to displaying the process ID of the program (if running).
 309 .It Cm poll
 310 If the script starts a process (rather than performing a one-off
 311 operation), wait for the command to exit.
 312 Otherwise it is not necessary to support this argument.
 313 .It Cm rcvar
 314 Display which
 315 .Xr rc.conf 5
 316 variables are used to control the startup of the service (if any).
 317 .El
 318 .Pp
 319 If a script must implement additional commands it can list them in
 320 the
 321 .Va extra_commands
 322 variable, and define their actions in a variable constructed from
 323 the command name (see the
 324 .Sx EXAMPLES
 325 section).
 326 .Pp
 327 The following key points apply to old-style scripts in
 328 .Pa /usr/local/etc/rc.d/ :
 329 .Pp
 330 .Bl -bullet
 331 .It
 332 Scripts are only executed if their
 333 .Xr basename 1
 334 matches the shell globbing pattern
 335 .Pa *.sh ,
 336 and they are executable.
 337 Any other files or directories present within the directory are silently
 338 ignored.
 339 .It
 340 When a script is executed at boot time, it is passed the string
 341 .Dq Li start
 342 as its first and only argument.
 343 At shutdown time, it is passed the string
 344 .Dq Li stop
 345 as its first and only argument.
 346 All
 347 .Nm rc.d/
 348 scripts are expected to handle these arguments appropriately.
 349 If no action needs to be taken at a given time
 350 (either boot time or shutdown time),
 351 the script should exit successfully and without producing an error message.
 352 .It
 353 The scripts within each directory are executed in lexicographical order.
 354 If a specific order is required,
 355 numbers may be used as a prefix to the existing filenames,
 356 so for example
 357 .Pa 100.foo
 358 would be executed before
 359 .Pa 200.bar ;
 360 without the numeric prefixes the opposite would be true.
 361 .It
 362 The output from each script is traditionally a space character,
 363 followed by the name of the software package being started or shut down,
 364 .Em without
 365 a trailing newline character (see the
 366 .Sx EXAMPLES
 367 section).
 368 .El
 369 .Sh SCRIPTS OF INTEREST
 370 When an automatic reboot is in progress,
 371 .Nm
 372 is invoked with the argument
 373 .Cm autoboot .
 374 One of the scripts run from
 375 .Pa /etc/rc.d/
 376 is
 377 .Pa /etc/rc.d/fsck .
 378 This script runs
 379 .Xr fsck 8
 380 with option
 381 .Fl p
 382 and
 383 .Fl F
 384 to
 385 .Dq preen
 386 all the disks of minor inconsistencies resulting
 387 from the last system shutdown.
 388 If this fails, then checks/repairs of serious inconsistencies
 389 caused by hardware or software failure will be performed
 390 in the background at the end of the booting process.
 391 If
 392 .Cm autoboot
 393 is not set, when going from single-user to multi-user mode for example,
 394 the script does not do anything.
 395 .Pp
 396 The
 397 .Nm rc.early
 398 script is run very early in the startup process, immediately before the
 399 file system check.
 400 The
 401 .Nm rc.early
 402 script is deprecated.
 403 Any commands in this
 404 file should be separated out into
 405 .Nm rc.d/
 406 style scripts and integrated into the
 407 .Nm
 408 system.
 409 .Pp
 410 The
 411 .Pa /etc/rc.d/local
 412 script can execute scripts from multiple
 413 .Nm rc.d/
 414 directories.
 415 The default location includes
 416 .Pa /usr/local/etc/rc.d/ ,
 417 but these may be overridden with the
 418 .Va local_startup
 419 .Xr rc.conf 5
 420 variable.
 421 .Pp
 422 The
 423 .Pa /etc/rc.d/serial
 424 script is used to set any special configurations for serial devices.
 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 .It Pa /var/run/dmesg.boot
 480 .Xr dmesg 8
 481 results soon after the
 482 .Nm
 483 process begins.
 484 Useful when
 485 .Xr dmesg 8
 486 buffer in the kernel no longer has this information.
 487 .El
 488 .Sh EXAMPLES
 489 The following is a minimal
 490 .Nm rc.d/
 491 style script.
 492 Most scripts require little more than the following.
 493 .Bd -literal -offset indent
 494 #!/bin/sh
 495 #
 496
 497 # PROVIDE: foo
 498 # REQUIRE: bar_service_required_to_precede_foo
 499
 500 \&. /etc/rc.subr
 501
 502 name="foo"
 503 rcvar=`set_rcvar`
 504 command="/usr/local/bin/foo"
 505
 506 load_rc_config $name
 507 run_rc_command "$1"
 508 .Ed
 509 .Pp
 510 Certain scripts may want to provide enhanced functionality.
 511 The user may access this functionality through additional commands.
 512 The script may list and define as many commands at it needs.
 513 .Bd -literal -offset indent
 514 #!/bin/sh
 515 #
 516
 517 # PROVIDE: foo
 518 # REQUIRE: bar_service_required_to_precede_foo
 519 # BEFORE:  baz_service_requiring_foo_to_precede_it
 520
 521 \&. /etc/rc.subr
 522
 523 name="foo"
 524 rcvar=`set_rcvar`
 525 command="/usr/local/bin/foo"
 526 extra_commands="nop hello"
 527 hello_cmd="echo Hello World."
 528 nop_cmd="do_nop"
 529
 530 do_nop()
 531 {
 532         echo "I do nothing."
 533 }
 534
 535 load_rc_config $name
 536 run_rc_command "$1"
 537 .Ed
 538 .Pp
 539 As all processes are killed by
 540 .Xr init 8
 541 at shutdown, the explicit
 542 .Xr kill 1
 543 is unnecessary, but is often included.
 544 .Sh SEE ALSO
 545 .Xr kill 1 ,
 546 .Xr rc.conf 5 ,
 547 .Xr init 8 ,
 548 .Xr rcorder 8 ,
 549 .Xr rc.subr 8 ,
 550 .Xr reboot 8 ,
 551 .Xr savecore 8
 552 .Sh HISTORY
 553 The
 554 .Nm
 555 utility appeared in
 556 .Bx 4.0 .