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