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 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 -width ".Pa /etc/rc.shutdown.local" 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.shutdown.local 471.It Pa /etc/rc.subr 472.El 473.Sh EXAMPLES 474The following is a minimal 475.Nm rc.d/ 476style script. 477Most scripts require little more than the following. 478.Bd -literal -offset indent 479#!/bin/sh 480# 481 482# PROVIDE: foo 483# REQUIRE: bar_service_required_to_precede_foo 484# BEFORE: baz_service_requiring_foo_to_precede_it 485 486\&. /etc/rc.subr 487 488name="foo" 489rcvar=`set_rcvar` 490command="/usr/local/bin/foo" 491 492load_rc_config $name 493run_rc_command "$1" 494.Ed 495.Pp 496Certain scripts may want to provide enhanced functionality. 497The user may access this functionality through additional commands. 498The script may list and define as many commands at it needs. 499.Bd -literal -offset indent 500#!/bin/sh 501# 502 503# PROVIDE: foo 504# REQUIRE: bar_service_required_to_precede_foo 505# BEFORE: baz_service_requiring_foo_to_precede_it 506 507\&. /etc/rc.subr 508 509name="foo" 510rcvar=`set_rcvar` 511command="/usr/local/bin/foo" 512extra_commands="nop hello" 513hello_cmd="echo Hello World." 514nop_cmd="do_nop" 515 516do_nop() 517{ 518 echo "I do nothing." 519} 520 521load_rc_config $name 522run_rc_command "$1" 523.Ed 524.Pp 525The following is a simple, hypothetical example of an old-style 526.Pa /usr/local/etc/rc.d/ 527script, 528which would start a daemon at boot time, 529and kill it at shutdown time. 530.Bd -literal -offset indent 531#!/bin/sh - 532# 533# initialization/shutdown script for foobar package 534 535case "$1" in 536start) 537 /usr/local/sbin/foo -d && echo -n ' foo' 538 ;; 539stop) 540 kill `cat /var/run/foo.pid` && echo -n ' foo' 541 ;; 542*) 543 echo "unknown option: $1 - should be 'start' or 'stop'" >&2 544 ;; 545esac 546.Ed 547.Pp 548As all processes are killed by 549.Xr init 8 550at shutdown, the explicit 551.Xr kill 1 552is unnecessary, but is often included. 553.Sh SEE ALSO 554.Xr kill 1 , 555.Xr ipfw 4 , 556.Xr rc.conf 5 , 557.Xr init 8 , 558.Xr rcorder 8 , 559.Xr rcrun 8 , 560.Xr rc.subr 8 , 561.Xr reboot 8 , 562.Xr savecore 8 563.Sh HISTORY 564The 565.Nm 566utility appeared in 567.Bx 4.0 . 568The 569.Nm rc.d/ 570facility was implemented in 571.Nx 1.5 572and appeared in 573.Dx 1.0 . 574