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