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