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