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