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