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