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