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 July 24, 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 367and 368.Fl F 369to 370.Dq preen 371all the disks of minor inconsistencies resulting 372from the last system shutdown. 373If this fails, then checks/repairs of serious inconsistencies 374caused by hardware or software failure will be performed 375in the background at the end of the booting process. 376If 377.Cm autoboot 378is not set, when going from single-user to multi-user mode for example, 379the script does not do anything. 380.Pp 381The 382.Pa /etc/rc.d/localdaemons 383script can execute scripts from multiple 384.Nm rc.d/ 385directories. 386The default locations are 387.Pa /usr/pkg/etc/rc.d/ , 388.Pa /usr/local/etc/rc.d/ , 389.Pa /usr/pkg/xorg/etc/rc.d/ 390and 391.Pa /usr/X11R6/etc/rc.d/ , 392but these may be overridden with the 393.Va local_startup 394.Xr rc.conf 5 395variable. 396.Pp 397The 398.Pa /etc/rc.d/serial 399script is used to set any special configurations for serial devices. 400.Pp 401The 402.Pa /etc/rc.d/{net*,routing} 403scripts are used to start the network. 404The network is started in several passes. 405The first pass, 406.Pa /etc/rc.d/netif , 407configures the network 408interfaces. 409The 410.Pa /etc/rc.d/routing 411script starts routing and sets routing options. 412The 413.Pa /etc/rc.d/netoptions 414script sets additional networking options. 415Finally, the 416.Pa /etc/rc.d/network_ipv6 417script configures IPv6 interfaces and options. 418.Pp 419The 420.Nm rc.firewall 421script is used to configure rules for the 422.Xr ipfw 4 423kernel based firewall 424service. 425It has several possible options: 426.Pp 427.Bl -tag -width ".Ar filename" -compact -offset indent 428.It Cm open 429will allow anyone in 430.It Cm client 431will try to protect just this machine 432.It Cm simple 433will try to protect a whole network 434.It Cm closed 435totally disables IP services except via 436.Pa lo0 437interface 438.It Cm UNKNOWN 439disables the loading of firewall rules 440.It Ar filename 441will load the rules in the given filename (full path required). 442.El 443.Pp 444The 445.Pa /etc/rc.d/atm* 446scripts are used to configure ATM network interfaces. 447The interfaces are configured in three passes. 448The first pass performs the initial interface configuration. 449The second pass completes the interface configuration and defines PVCs and 450permanent ATMARP entries. 451The third pass starts any ATM daemons. 452.Pp 453Most daemons, including network related daemons, have their own script in 454.Pa /etc/rc.d/ , 455which can be used to start, stop, and check the status of the service. 456.Pp 457Any architecture specific scripts, such as 458.Pa /etc/rc.d/apm 459for example, specifically check that they are on that architecture 460before starting the daemon. 461.Pp 462Following tradition, all startup files reside in 463.Pa /etc . 464.Sh FILES 465.Bl -tag -compact 466.It Pa /etc/rc 467.It Pa /etc/rc.conf 468.It Pa /etc/rc.conf.local 469.It Pa /etc/rc.d/ 470.It Pa /etc/rc.firewall 471.It Pa /etc/rc.local 472.It Pa /etc/rc.shutdown 473.It Pa /etc/rc.shutdown.local 474.It Pa /etc/rc.subr 475.El 476.Sh EXAMPLES 477The following is a minimal 478.Nm rc.d/ 479style script. 480Most scripts require little more than the following. 481.Bd -literal -offset indent 482#!/bin/sh 483# 484 485# PROVIDE: foo 486# REQUIRE: bar_service_required_to_precede_foo 487# BEFORE: baz_service_requiring_foo_to_precede_it 488 489\&. /etc/rc.subr 490 491name="foo" 492rcvar=`set_rcvar` 493command="/usr/local/bin/foo" 494 495load_rc_config $name 496run_rc_command "$1" 497.Ed 498.Pp 499Certain scripts may want to provide enhanced functionality. 500The user may access this functionality through additional commands. 501The script may list and define as many commands at it needs. 502.Bd -literal -offset indent 503#!/bin/sh 504# 505 506# PROVIDE: foo 507# REQUIRE: bar_service_required_to_precede_foo 508# BEFORE: baz_service_requiring_foo_to_precede_it 509 510\&. /etc/rc.subr 511 512name="foo" 513rcvar=`set_rcvar` 514command="/usr/local/bin/foo" 515extra_commands="nop hello" 516hello_cmd="echo Hello World." 517nop_cmd="do_nop" 518 519do_nop() 520{ 521 echo "I do nothing." 522} 523 524load_rc_config $name 525run_rc_command "$1" 526.Ed 527.Pp 528The following is a simple, hypothetical example of an old-style 529.Pa /usr/local/etc/rc.d/ 530script, 531which would start a daemon at boot time, 532and kill it at shutdown time. 533.Bd -literal -offset indent 534#!/bin/sh - 535# 536# initialization/shutdown script for foobar package 537 538case "$1" in 539start) 540 /usr/local/sbin/foo -d && echo -n ' foo' 541 ;; 542stop) 543 kill `cat /var/run/foo.pid` && echo -n ' foo' 544 ;; 545*) 546 echo "unknown option: $1 - should be 'start' or 'stop'" >&2 547 ;; 548esac 549.Ed 550.Pp 551As all processes are killed by 552.Xr init 8 553at shutdown, the explicit 554.Xr kill 1 555is unnecessary, but is often included. 556.Sh SEE ALSO 557.Xr kill 1 , 558.Xr ipfw 4 , 559.Xr rc.conf 5 , 560.Xr init 8 , 561.Xr rcorder 8 , 562.Xr rcrun 8 , 563.Xr rc.subr 8 , 564.Xr reboot 8 , 565.Xr savecore 8 566.Sh HISTORY 567The 568.Nm 569utility appeared in 570.Bx 4.0 . 571The 572.Nm rc.d/ 573facility was implemented in 574.Nx 1.5 575and appeared in 576.Dx 1.0 . 577