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