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 November 17, 2009
  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 .Bl -bullet
 330 .It
 331 Scripts are only executed if their
 332 .Xr basename 1
 333 matches the shell globbing pattern
 334 .Pa *.sh ,
 335 and they are executable.
 336 Any other files or directories present within the directory are silently
 337 ignored.
 338 .It
 339 When a script is executed at boot time, it is passed the string
 340 .Dq Li start
 341 as its first and only argument.
 342 At shutdown time, it is passed the string
 343 .Dq Li stop
 344 as its first and only argument.
 345 All
 346 .Nm rc.d/
 347 scripts are expected to handle these arguments appropriately.
 348 If no action needs to be taken at a given time
 349 (either boot time or shutdown time),
 350 the script should exit successfully and without producing an error message.
 351 .It
 352 The scripts within each directory are executed in lexicographical order.
 353 If a specific order is required,
 354 numbers may be used as a prefix to the existing filenames,
 355 so for example
 356 .Pa 100.foo
 357 would be executed before
 358 .Pa 200.bar ;
 359 without the numeric prefixes the opposite would be true.
 360 .It
 361 The output from each script is traditionally a space character,
 362 followed by the name of the software package being started or shut down,
 363 .Em without
 364 a trailing newline character (see the
 365 .Sx EXAMPLES
 366 section).
 367 .El
 368 .Sh SCRIPTS OF INTEREST
 369 When an automatic reboot is in progress,
 370 .Nm
 371 is invoked with the argument
 372 .Cm autoboot .
 373 One of the scripts run from
 374 .Pa /etc/rc.d/
 375 is
 376 .Pa /etc/rc.d/fsck .
 377 This script runs
 378 .Xr fsck 8
 379 with option
 380 .Fl p
 381 and
 382 .Fl F
 383 to
 384 .Dq preen
 385 all the disks of minor inconsistencies resulting
 386 from the last system shutdown.
 387 If this fails, then checks/repairs of serious inconsistencies
 388 caused by hardware or software failure will be performed
 389 in the background at the end of the booting process.
 390 If
 391 .Cm autoboot
 392 is not set, when going from single-user to multi-user mode for example,
 393 the script does not do anything.
 394 .Pp
 395 The
 396 .Pa /etc/rc.d/local
 397 script can execute scripts from multiple
 398 .Nm rc.d/
 399 directories.
 400 The default location includes
 401 .Pa /usr/local/etc/rc.d/ ,
 402 but these may be overridden with the
 403 .Va local_startup
 404 .Xr rc.conf 5
 405 variable.
 406 .Pp
 407 The
 408 .Pa /etc/rc.d/serial
 409 script is used to set any special configurations for serial devices.
 410 .Pp
 411 The
 412 .Nm rc.firewall
 413 script is used to configure rules for the kernel based firewall
 414 service.
 415 It has several possible options:
 416 .Pp
 417 .Bl -tag -width ".Ar filename" -compact -offset indent
 418 .It Cm open
 419 will allow anyone in
 420 .It Cm client
 421 will try to protect just this machine
 422 .It Cm simple
 423 will try to protect a whole network
 424 .It Cm closed
 425 totally disables IP services except via
 426 .Pa lo0
 427 interface
 428 .It Cm UNKNOWN
 429 disables the loading of firewall rules
 430 .It Ar filename
 431 will load the rules in the given filename (full path required).
 432 .El
 433 .Pp
 434 The
 435 .Pa /etc/rc.d/atm*
 436 scripts are used to configure ATM network interfaces.
 437 The interfaces are configured in three passes.
 438 The first pass performs the initial interface configuration.
 439 The second pass completes the interface configuration and defines PVCs and
 440 permanent ATMARP entries.
 441 The third pass starts any ATM daemons.
 442 .Pp
 443 Most daemons, including network related daemons, have their own script in
 444 .Pa /etc/rc.d/ ,
 445 which can be used to start, stop, and check the status of the service.
 446 .Pp
 447 Any architecture specific scripts, such as
 448 .Pa /etc/rc.d/apm
 449 for example, specifically check that they are on that architecture
 450 before starting the daemon.
 451 .Pp
 452 Following tradition, all startup files reside in
 453 .Pa /etc .
 454 .Sh FILES
 455 .Bl -tag -compact
 456 .It Pa /etc/rc
 457 .It Pa /etc/rc.conf
 458 .It Pa /etc/rc.conf.local
 459 .It Pa /etc/rc.d/
 460 .It Pa /etc/rc.firewall
 461 .It Pa /etc/rc.local
 462 .It Pa /etc/rc.shutdown
 463 .It Pa /etc/rc.subr
 464 .It Pa /var/run/dmesg.boot
 465 .Xr dmesg 8
 466 results soon after the
 467 .Nm
 468 process begins.
 469 Useful when
 470 .Xr dmesg 8
 471 buffer in the kernel no longer has this information.
 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
 485 \&. /etc/rc.subr
 486
 487 name="foo"
 488 rcvar=`set_rcvar`
 489 command="/usr/local/bin/foo"
 490
 491 load_rc_config $name
 492 run_rc_command "$1"
 493 .Ed
 494 .Pp
 495 Certain scripts may want to provide enhanced functionality.
 496 The user may access this functionality through additional commands.
 497 The script may list and define as many commands at it needs.
 498 .Bd -literal -offset indent
 499 #!/bin/sh
 500 #
 501
 502 # PROVIDE: foo
 503 # REQUIRE: bar_service_required_to_precede_foo
 504 # BEFORE:  baz_service_requiring_foo_to_precede_it
 505
 506 \&. /etc/rc.subr
 507
 508 name="foo"
 509 rcvar=`set_rcvar`
 510 command="/usr/local/bin/foo"
 511 extra_commands="nop hello"
 512 hello_cmd="echo Hello World."
 513 nop_cmd="do_nop"
 514
 515 do_nop()
 516 {
 517         echo "I do nothing."
 518 }
 519
 520 load_rc_config $name
 521 run_rc_command "$1"
 522 .Ed
 523 .Pp
 524 As all processes are killed by
 525 .Xr init 8
 526 at shutdown, the explicit
 527 .Xr kill 1
 528 is unnecessary, but is often included.
 529 .Sh SEE ALSO
 530 .Xr kill 1 ,
 531 .Xr rc.conf 5 ,
 532 .Xr init 8 ,
 533 .Xr rcorder 8 ,
 534 .Xr rc.subr 8 ,
 535 .Xr reboot 8 ,
 536 .Xr savecore 8
 537 .Sh HISTORY
 538 The
 539 .Nm
 540 utility appeared in
 541 .Bx 4.0 .