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 July 24, 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 and
 368 .Fl F
 369 to
 370 .Dq preen
 371 all the disks of minor inconsistencies resulting
 372 from the last system shutdown.
 373 If this fails, then checks/repairs of serious inconsistencies
 374 caused by hardware or software failure will be performed
 375 in the background at the end of the booting process.
 376 If
 377 .Cm autoboot
 378 is not set, when going from single-user to multi-user mode for example,
 379 the script does not do anything.
 380 .Pp
 381 The
 382 .Pa /etc/rc.d/localdaemons
 383 script can execute scripts from multiple
 384 .Nm rc.d/
 385 directories.
 386 The default locations are
 387 .Pa /usr/pkg/etc/rc.d/ ,
 388 .Pa /usr/local/etc/rc.d/ ,
 389 .Pa /usr/pkg/xorg/etc/rc.d/
 390 and
 391 .Pa /usr/X11R6/etc/rc.d/ ,
 392 but these may be overridden with the
 393 .Va local_startup
 394 .Xr rc.conf 5
 395 variable.
 396 .Pp
 397 The
 398 .Pa /etc/rc.d/serial
 399 script is used to set any special configurations for serial devices.
 400 .Pp
 401 The
 402 .Pa /etc/rc.d/{net*,routing}
 403 scripts are used to start the network.
 404 The network is started in several passes.
 405 The first pass,
 406 .Pa /etc/rc.d/netif ,
 407 configures the network
 408 interfaces.
 409 The
 410 .Pa /etc/rc.d/routing
 411 script starts routing and sets routing options.
 412 The
 413 .Pa /etc/rc.d/netoptions
 414 script sets additional networking options.
 415 Finally, the
 416 .Pa /etc/rc.d/network_ipv6
 417 script configures IPv6 interfaces and options.
 418 .Pp
 419 The
 420 .Nm rc.firewall
 421 script is used to configure rules for the
 422 .Xr ipfw 4
 423 kernel based firewall
 424 service.
 425 It has several possible options:
 426 .Pp
 427 .Bl -tag -width ".Ar filename" -compact -offset indent
 428 .It Cm open
 429 will allow anyone in
 430 .It Cm client
 431 will try to protect just this machine
 432 .It Cm simple
 433 will try to protect a whole network
 434 .It Cm closed
 435 totally disables IP services except via
 436 .Pa lo0
 437 interface
 438 .It Cm UNKNOWN
 439 disables the loading of firewall rules
 440 .It Ar filename
 441 will load the rules in the given filename (full path required).
 442 .El
 443 .Pp
 444 The
 445 .Pa /etc/rc.d/atm*
 446 scripts are used to configure ATM network interfaces.
 447 The interfaces are configured in three passes.
 448 The first pass performs the initial interface configuration.
 449 The second pass completes the interface configuration and defines PVCs and
 450 permanent ATMARP entries.
 451 The third pass starts any ATM daemons.
 452 .Pp
 453 Most daemons, including network related daemons, have their own script in
 454 .Pa /etc/rc.d/ ,
 455 which can be used to start, stop, and check the status of the service.
 456 .Pp
 457 Any architecture specific scripts, such as
 458 .Pa /etc/rc.d/apm
 459 for example, specifically check that they are on that architecture
 460 before starting the daemon.
 461 .Pp
 462 Following tradition, all startup files reside in
 463 .Pa /etc .
 464 .Sh FILES
 465 .Bl -tag -compact
 466 .It Pa /etc/rc
 467 .It Pa /etc/rc.conf
 468 .It Pa /etc/rc.conf.local
 469 .It Pa /etc/rc.d/
 470 .It Pa /etc/rc.firewall
 471 .It Pa /etc/rc.local
 472 .It Pa /etc/rc.shutdown
 473 .It Pa /etc/rc.shutdown.local
 474 .It Pa /etc/rc.subr
 475 .El
 476 .Sh EXAMPLES
 477 The following is a minimal
 478 .Nm rc.d/
 479 style script.
 480 Most scripts require little more than the following.
 481 .Bd -literal -offset indent
 482 #!/bin/sh
 483 #
 484
 485 # PROVIDE: foo
 486 # REQUIRE: bar_service_required_to_precede_foo
 487 # BEFORE:  baz_service_requiring_foo_to_precede_it
 488
 489 \&. /etc/rc.subr
 490
 491 name="foo"
 492 rcvar=`set_rcvar`
 493 command="/usr/local/bin/foo"
 494
 495 load_rc_config $name
 496 run_rc_command "$1"
 497 .Ed
 498 .Pp
 499 Certain scripts may want to provide enhanced functionality.
 500 The user may access this functionality through additional commands.
 501 The script may list and define as many commands at it needs.
 502 .Bd -literal -offset indent
 503 #!/bin/sh
 504 #
 505
 506 # PROVIDE: foo
 507 # REQUIRE: bar_service_required_to_precede_foo
 508 # BEFORE:  baz_service_requiring_foo_to_precede_it
 509
 510 \&. /etc/rc.subr
 511
 512 name="foo"
 513 rcvar=`set_rcvar`
 514 command="/usr/local/bin/foo"
 515 extra_commands="nop hello"
 516 hello_cmd="echo Hello World."
 517 nop_cmd="do_nop"
 518
 519 do_nop()
 520 {
 521         echo "I do nothing."
 522 }
 523
 524 load_rc_config $name
 525 run_rc_command "$1"
 526 .Ed
 527 .Pp
 528 The following is a simple, hypothetical example of an old-style
 529 .Pa /usr/local/etc/rc.d/
 530 script,
 531 which would start a daemon at boot time,
 532 and kill it at shutdown time.
 533 .Bd -literal -offset indent
 534 #!/bin/sh -
 535 #
 536 #    initialization/shutdown script for foobar package
 537
 538 case "$1" in
 539 start)
 540         /usr/local/sbin/foo -d && echo -n ' foo'
 541         ;;
 542 stop)
 543         kill `cat /var/run/foo.pid` && echo -n ' foo'
 544         ;;
 545 *)
 546         echo "unknown option: $1 - should be 'start' or 'stop'" >&2
 547         ;;
 548 esac
 549 .Ed
 550 .Pp
 551 As all processes are killed by
 552 .Xr init 8
 553 at shutdown, the explicit
 554 .Xr kill 1
 555 is unnecessary, but is often included.
 556 .Sh SEE ALSO
 557 .Xr kill 1 ,
 558 .Xr ipfw 4 ,
 559 .Xr rc.conf 5 ,
 560 .Xr init 8 ,
 561 .Xr rcorder 8 ,
 562 .Xr rcrun 8 ,
 563 .Xr rc.subr 8 ,
 564 .Xr reboot 8 ,
 565 .Xr savecore 8
 566 .Sh HISTORY
 567 The
 568 .Nm
 569 utility appeared in
 570 .Bx 4.0 .
 571 The
 572 .Nm rc.d/
 573 facility was implemented in
 574 .Nx 1.5
 575 and appeared in
 576 .Dx 1.0 .