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