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