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