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