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. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\"     @(#)rc.8        8.2 (Berkeley) 12/11/93
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd December 25, 2013
  35 .Dt RC 8
  36 .Os
  37 .Sh NAME
  38 .Nm rc
  39 .Nd command scripts for auto-reboot and daemon startup
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Nm rc.conf
  43 .Nm rc.conf.local
  44 .Nm rc.d/
  45 .Nm rc.firewall
  46 .Nm rc.local
  47 .Nm rc.shutdown
  48 .Nm rc.subr
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 utility is the command script which controls the automatic boot process
  53 after being called by
  54 .Xr init 8 .
  55 The
  56 .Nm rc.local
  57 script contains commands which are pertinent only
  58 to a specific site.
  59 Typically, the
  60 .Pa /usr/local/etc/rc.d/
  61 mechanism is used instead of
  62 .Nm rc.local
  63 these days but if
  64 you want to use
  65 .Nm rc.local ,
  66 it is still supported.
  67 In this case, it should source
  68 .Pa /etc/rc.conf
  69 and contain additional custom startup code for your system.
  70 The best way to handle
  71 .Nm rc.local ,
  72 however, is to separate it out into
  73 .Nm rc.d/
  74 style scripts and place them under
  75 .Pa /usr/local/etc/rc.d/ .
  76 The
  77 .Nm rc.conf
  78 file contains the global system configuration information referenced
  79 by the startup scripts, while
  80 .Nm rc.conf.local
  81 contains the local system configuration.
  82 See
  83 .Xr rc.conf 5
  84 for more information.
  85 .Pp
  86 The
  87 .Nm rc.d/
  88 directories contain scripts which will be automatically
  89 executed at boot time and shutdown time.
  90 .Ss Operation of Nm
  91 .Bl -enum
  92 .It
  93 If autobooting, set
  94 .Va autoboot Ns = Ns Li yes
  95 and enable a flag
  96 .Pq Va rc_fast Ns = Ns Li yes ,
  97 which prevents the
  98 .Nm rc.d/
  99 scripts from performing the check for already running processes
 100 (thus speeding up the boot process).
 101 This
 102 .Va rc_fast Ns = Ns Li yes
 103 speedup will not occur when
 104 .Nm
 105 is started up after exiting the single-user shell.
 106 .It
 107 Determine whether the system is booting diskless,
 108 and if so run the
 109 .Pa /etc/rc.initdiskless
 110 script.
 111 .It
 112 Source
 113 .Pa /etc/rc.subr
 114 to load various
 115 .Xr rc.subr 8
 116 shell functions to use.
 117 .It
 118 Load the configuration files.
 119 .It
 120 Determine if booting in a jail,
 121 and add
 122 .Dq Li nojail
 123 (no jails allowed) or
 124 .Dq Li nojailvnet
 125 (only allow vnet-enabled jails) to the list of KEYWORDS to skip in
 126 .Xr rcorder 8 .
 127 .It
 128 If the file
 129 .Va ${firstboot_sentinel}
 130 does not exist, add
 131 .Dq Li firstboot
 132 to the list of KEYWORDS to skip in
 133 .Xr rcorder 8 .
 134 .It
 135 Invoke
 136 .Xr rcorder 8
 137 to order the files in
 138 .Pa /etc/rc.d/
 139 that do not have a
 140 .Dq Li nostart
 141 KEYWORD (refer to
 142 .Xr rcorder 8 Ns 's
 143 .Fl s
 144 flag).
 145 .It
 146 Call each script in turn using
 147 .Fn run_rc_script
 148 (from
 149 .Xr rc.subr 8 ) ,
 150 which sets
 151 .Va $1
 152 to
 153 .Dq Li start ,
 154 and sources the script in a subshell.
 155 If the script has a
 156 .Pa .sh
 157 suffix then it is sourced directly into the current shell.
 158 Stop processing when the script that is the value of the
 159 .Va $early_late_divider
 160 has been run.
 161 .It
 162 Check again to see if the file
 163 .Va ${firstboot_sentinel}
 164 exists (in case it is located on a newly mounted file system)
 165 and adjust the list of KEYWORDs to skip appropriately.
 166 .It
 167 Re-run
 168 .Xr rcorder 8 ,
 169 this time including the scripts in the
 170 .Va $local_startup
 171 directories.
 172 Ignore everything up to the
 173 .Va $early_late_divider ,
 174 then start executing the scripts as described above.
 175 .It
 176 If the file
 177 .Va ${firstboot_sentinel}
 178 exists, delete it.
 179 If the file
 180 .Va ${firstboot_sentinel}-reboot
 181 also exists (because it was created by a script), then delete it and reboot.
 182 .El
 183 .Ss Operation of Nm rc.shutdown
 184 .Bl -enum
 185 .It
 186 Source
 187 .Pa /etc/rc.subr
 188 to load various
 189 .Xr rc.subr 8
 190 shell functions to use.
 191 .It
 192 Load the configuration files.
 193 .It
 194 Invoke
 195 .Xr rcorder 8
 196 to order the files in
 197 .Pa /etc/rc.d/
 198 and the
 199 .Va $local_startup
 200 directories
 201 that have a
 202 .Dq Li shutdown
 203 KEYWORD (refer to
 204 .Xr rcorder 8 Ns 's
 205 .Fl k
 206 flag),
 207 reverse that order, and assign the result to a variable.
 208 .It
 209 Call each script in turn using
 210 .Fn run_rc_script
 211 (from
 212 .Xr rc.subr 8 ) ,
 213 which sets
 214 .Va $1
 215 to
 216 .Dq Li stop ,
 217 and sources the script in a subshell.
 218 If the script has a
 219 .Pa .sh
 220 suffix then it is sourced directly into the current shell.
 221 .El
 222 .Ss Contents of Nm rc.d/
 223 .Nm rc.d/
 224 is located in
 225 .Pa /etc/rc.d/ .
 226 The following file naming conventions are currently used in
 227 .Nm rc.d/ :
 228 .Bl -tag -width ".Pa ALLUPPERCASE" -offset indent
 229 .It Pa ALLUPPERCASE
 230 Scripts that are
 231 .Dq placeholders
 232 to ensure that certain operations are performed before others.
 233 In order of startup, these are:
 234 .Bl -tag -width ".Pa NETWORKING"
 235 .It Pa NETWORKING
 236 Ensure basic network services are running, including general
 237 network configuration.
 238 .It Pa SERVERS
 239 Ensure basic services
 240 exist for services that start early (such as
 241 .Pa nisdomain ) ,
 242 because they are required by
 243 .Pa DAEMON
 244 below.
 245 .It Pa DAEMON
 246 Check-point before all general purpose daemons such as
 247 .Pa lpd
 248 and
 249 .Pa ntpd .
 250 .It Pa LOGIN
 251 Check-point before user login services
 252 .Pa ( inetd
 253 and
 254 .Pa sshd ) ,
 255 as well as services which might run commands as users
 256 .Pa ( cron
 257 and
 258 .Pa sendmail ) .
 259 .El
 260 .It Pa foo.sh
 261 Scripts that are to be sourced into the current shell rather than a subshell
 262 have a
 263 .Pa .sh
 264 suffix.
 265 Extreme care must be taken in using this, as the startup sequence will
 266 terminate if the script does.
 267 .It Pa bar
 268 Scripts that are sourced in a subshell.
 269 The boot does not stop if such a script terminates with a non-zero status,
 270 but a script can stop the boot if necessary by invoking the
 271 .Fn stop_boot
 272 function (from
 273 .Xr rc.subr 8 ) .
 274 .El
 275 .Pp
 276 Each script should contain
 277 .Xr rcorder 8
 278 keywords, especially an appropriate
 279 .Dq Li PROVIDE
 280 entry, and if necessary
 281 .Dq Li REQUIRE
 282 and
 283 .Dq Li BEFORE
 284 keywords.
 285 .Pp
 286 Each script is expected to support at least the following arguments, which
 287 are automatically supported if it uses the
 288 .Fn run_rc_command
 289 function:
 290 .Bl -tag -width ".Cm restart" -offset indent
 291 .It Cm start
 292 Start the service.
 293 This should check that the service is to be started as specified by
 294 .Xr rc.conf 5 .
 295 Also checks if the service is already running and refuses to start if
 296 it is.
 297 This latter check is not performed by standard
 298 .Fx
 299 scripts if the system is starting directly to multi-user mode, to
 300 speed up the boot process.
 301 If
 302 .Cm forcestart
 303 is given, ignore the
 304 .Xr rc.conf 5
 305 check and start anyway.
 306 .It Cm stop
 307 If the service is to be started as specified by
 308 .Xr rc.conf 5 ,
 309 stop the service.
 310 This should check that the service is running and complain if it is not.
 311 If
 312 .Cm forcestop
 313 is given, ignore the
 314 .Xr rc.conf 5
 315 check and attempt to stop.
 316 .It Cm restart
 317 Perform a
 318 .Cm stop
 319 then a
 320 .Cm start .
 321 .It Cm status
 322 If the script starts a process (rather than performing a one-off
 323 operation), show the status of the process.
 324 Otherwise it is not necessary to support this argument.
 325 Defaults to displaying the process ID of the program (if running).
 326 .It Cm poll
 327 If the script starts a process (rather than performing a one-off
 328 operation), wait for the command to exit.
 329 Otherwise it is not necessary to support this argument.
 330 .It Cm enabled
 331 Return 0 if the service is enabled and 1 if it is not.
 332 This command does not print anything.
 333 .It Cm rcvar
 334 Display which
 335 .Xr rc.conf 5
 336 variables are used to control the startup of the service (if any).
 337 .El
 338 .Pp
 339 If a script must implement additional commands it can list them in
 340 the
 341 .Va extra_commands
 342 variable, and define their actions in a variable constructed from
 343 the command name (see the
 344 .Sx EXAMPLES
 345 section).
 346 .Pp
 347 The following key points apply to old-style scripts in
 348 .Pa /usr/local/etc/rc.d/ :
 349 .Bl -bullet
 350 .It
 351 Scripts are only executed if their
 352 .Xr basename 1
 353 matches the shell globbing pattern
 354 .Pa *.sh ,
 355 and they are executable.
 356 Any other files or directories present within the directory are silently
 357 ignored.
 358 .It
 359 When a script is executed at boot time, it is passed the string
 360 .Dq Li start
 361 as its first and only argument.
 362 At shutdown time, it is passed the string
 363 .Dq Li stop
 364 as its first and only argument.
 365 All
 366 .Nm rc.d/
 367 scripts are expected to handle these arguments appropriately.
 368 If no action needs to be taken at a given time
 369 (either boot time or shutdown time),
 370 the script should exit successfully and without producing an error message.
 371 .It
 372 The scripts within each directory are executed in lexicographical order.
 373 If a specific order is required,
 374 numbers may be used as a prefix to the existing filenames,
 375 so for example
 376 .Pa 100.foo
 377 would be executed before
 378 .Pa 200.bar ;
 379 without the numeric prefixes the opposite would be true.
 380 .It
 381 The output from each script is traditionally a space character,
 382 followed by the name of the software package being started or shut down,
 383 .Em without
 384 a trailing newline character (see the
 385 .Sx EXAMPLES
 386 section).
 387 .El
 388 .Sh SCRIPTS OF INTEREST
 389 When an automatic reboot is in progress,
 390 .Nm
 391 is invoked with the argument
 392 .Cm autoboot .
 393 One of the scripts run from
 394 .Pa /etc/rc.d/
 395 is
 396 .Pa /etc/rc.d/fsck .
 397 This script runs
 398 .Xr fsck 8
 399 with option
 400 .Fl p
 401 and
 402 .Fl F
 403 to
 404 .Dq preen
 405 all the disks of minor inconsistencies resulting
 406 from the last system shutdown.
 407 If this fails, then checks/repairs of serious inconsistencies
 408 caused by hardware or software failure will be performed
 409 in the background at the end of the booting process.
 410 If
 411 .Cm autoboot
 412 is not set, when going from single-user to multi-user mode for example,
 413 the script does not do anything.
 414 .Pp
 415 The
 416 .Pa /etc/rc.d/local
 417 script can execute scripts from multiple
 418 .Nm rc.d/
 419 directories.
 420 The default location includes
 421 .Pa /usr/local/etc/rc.d/ ,
 422 but these may be overridden with the
 423 .Va local_startup
 424 .Xr rc.conf 5
 425 variable.
 426 .Pp
 427 The
 428 .Pa /etc/rc.d/serial
 429 script is used to set any special configurations for serial devices.
 430 .Pp
 431 The
 432 .Nm rc.firewall
 433 script is used to configure rules for the kernel based firewall
 434 service.
 435 It has several possible options:
 436 .Pp
 437 .Bl -tag -width ".Ar filename" -compact -offset indent
 438 .It Cm open
 439 will allow anyone in
 440 .It Cm client
 441 will try to protect just this machine
 442 .It Cm simple
 443 will try to protect a whole network
 444 .It Cm closed
 445 totally disables IP services except via
 446 .Pa lo0
 447 interface
 448 .It Cm UNKNOWN
 449 disables the loading of firewall rules
 450 .It Ar filename
 451 will load the rules in the given filename (full path required).
 452 .El
 453 .Pp
 454 The
 455 .Pa /etc/rc.d/atm*
 456 scripts are used to configure ATM network interfaces.
 457 The interfaces are configured in three passes.
 458 The first pass performs the initial interface configuration.
 459 The second pass completes the interface configuration and defines PVCs and
 460 permanent ATMARP entries.
 461 The third pass starts any ATM daemons.
 462 .Pp
 463 Most daemons, including network related daemons, have their own script in
 464 .Pa /etc/rc.d/ ,
 465 which can be used to start, stop, and check the status of the service.
 466 .Pp
 467 Any architecture specific scripts, such as
 468 .Pa /etc/rc.d/apm
 469 for example, specifically check that they are on that architecture
 470 before starting the daemon.
 471 .Pp
 472 Following tradition, all startup files reside in
 473 .Pa /etc .
 474 .Sh FILES
 475 .Bl -tag -compact -width Pa
 476 .It Pa /etc/rc
 477 .It Pa /etc/rc.conf
 478 .It Pa /etc/rc.conf.local
 479 .It Pa /etc/rc.d/
 480 .It Pa /etc/rc.firewall
 481 .It Pa /etc/rc.local
 482 .It Pa /etc/rc.shutdown
 483 .It Pa /etc/rc.subr
 484 .It Pa /var/run/dmesg.boot
 485 .Xr dmesg 8
 486 results soon after the
 487 .Nm
 488 process begins.
 489 Useful when
 490 .Xr dmesg 8
 491 buffer in the kernel no longer has this information.
 492 .El
 493 .Sh EXAMPLES
 494 The following is a minimal
 495 .Nm rc.d/
 496 style script.
 497 Most scripts require little more than the following.
 498 .Bd -literal -offset indent
 499 #!/bin/sh
 500 #
 501
 502 # PROVIDE: foo
 503 # REQUIRE: bar_service_required_to_precede_foo
 504
 505 \&. /etc/rc.subr
 506
 507 name="foo"
 508 rcvar=foo_enable
 509 command="/usr/local/bin/foo"
 510
 511 load_rc_config $name
 512 run_rc_command "$1"
 513 .Ed
 514 .Pp
 515 Certain scripts may want to provide enhanced functionality.
 516 The user may access this functionality through additional commands.
 517 The script may list and define as many commands at it needs.
 518 .Bd -literal -offset indent
 519 #!/bin/sh
 520 #
 521
 522 # PROVIDE: foo
 523 # REQUIRE: bar_service_required_to_precede_foo
 524 # BEFORE:  baz_service_requiring_foo_to_precede_it
 525
 526 \&. /etc/rc.subr
 527
 528 name="foo"
 529 rcvar=foo_enable
 530 command="/usr/local/bin/foo"
 531 extra_commands="nop hello"
 532 hello_cmd="echo Hello World."
 533 nop_cmd="do_nop"
 534
 535 do_nop()
 536 {
 537         echo "I do nothing."
 538 }
 539
 540 load_rc_config $name
 541 run_rc_command "$1"
 542 .Ed
 543 .Pp
 544 As all processes are killed by
 545 .Xr init 8
 546 at shutdown, the explicit
 547 .Xr kill 1
 548 is unnecessary, but is often included.
 549 .Sh SEE ALSO
 550 .Xr kill 1 ,
 551 .Xr rc.conf 5 ,
 552 .Xr init 8 ,
 553 .Xr rc.subr 8 ,
 554 .Xr rcorder 8 ,
 555 .Xr reboot 8 ,
 556 .Xr savecore 8
 557 .Sh HISTORY
 558 The
 559 .Nm
 560 utility appeared in
 561 .Bx 4.0 .