1.\" $NetBSD: rc.8,v 1.41 2024/12/31 01:53:59 snj Exp $ 2.\" 3.\" Copyright (c) 2000-2017 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Luke Mewburn. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd December 7, 2024 31.Dt RC 8 32.Os 33.Sh NAME 34.Nm rc , 35.Nm rc.local , 36.Nm rc.shutdown , 37.Nm rc.shutdown.final , 38.Nm rc.d/ 39.Nd startup and shutdown scripts 40.Sh SYNOPSIS 41.Nm rc 42.Nm rc.local 43.Nm rc.shutdown 44.Nm rc.d/ 45.Sh DESCRIPTION 46.Nm 47is the command script which controls the startup of various services, 48and is invoked by 49.Xr init 8 50as part of the process of entering the automatic reboot to multi-user startup, 51or after the single user mode shell has exited. 52If 53.Xr init 8 54is starting the automatic reboot process, 55.Nm 56is invoked with the argument of 57.Sq autoboot . 58.Pp 59.Nm rc.local 60is a command script to which local boot-time actions can be added. 61It is (nearly) the last thing invoked by 62.Nm rc 63during a normal boot. 64.Pp 65.Nm rc.shutdown 66is the command script which shuts down various services, and is invoked by 67.Xr shutdown 8 68as part of the process of shutting down the system. 69.Pp 70.Nm rc.d/ 71is the directory which contains various 72.Xr sh 1 73scripts, one for each service, 74which are called by 75.Nm 76at startup, 77.Nm rc.shutdown 78at shutdown, 79and as necessary during system operation to stop, start, restart, reload, 80or otherwise control the service. 81.Ss Operation of rc 82.Bl -enum 83.It 84Source 85.Pa /etc/rc.subr 86to load various 87.Xr rc.subr 8 88shell functions to use. 89.It 90If autobooting, set 91.Sy autoboot=yes 92and enable a flag 93.Sy ( rc_fast=yes ) , 94which prevents the 95.Nm rc.d 96scripts from performing the check for already running processes 97(thus speeding up the boot process). 98This 99.Sy rc_fast=yes 100speedup won't occur when 101.Nm 102is started up after exiting the single-user shell. 103.It 104Invoke 105.Xr rcorder 8 106to order the files in 107.Pa /etc/rc.d/ 108that do not have a 109.Dq nostart 110keyword (refer to 111.Xr rcorder 8 Ns 's 112.Fl s 113flag), 114and assigns the result to a variable. 115.It 116Calls each script in turn using 117.Fn run_rc_script 118(from 119.Xr rc.subr 8 ) , 120which sets 121.Dv $1 122to 123.Sq start , 124and sources the script in a sub-shell. 125If the script has a 126.Sq .sh 127suffix then it is sourced directly into the current shell. 128.It 129The output from the above steps is sent to a post-processor. 130If 131.Sy rc_silent 132is false, then the post-processor displays the output. 133If 134.Sy rc_silent 135is true, then the post-processor invokes the command specified in 136.Va rc_silent_cmd 137once for each line, without otherwise displaying the output. 138Useful values for 139.Va rc_silent_cmd 140include 141.Dq \&: 142to display nothing at all, and 143.Dq twiddle 144to display a spinning symbol on the console. 145Regardless of the value of 146.Sy rc_silent , 147the post-processor saves the output in 148.Pa /var/run/rc.log . 149.El 150.Ss Operation of rc.shutdown 151.Bl -enum 152.It 153Source 154.Pa /etc/rc.subr 155to load various 156.Xr rc.subr 8 157shell functions to use. 158.It 159Invoke 160.Xr rcorder 8 161to order the files in 162.Pa /etc/rc.d/ 163that have a 164.Dq shutdown 165keyword (refer to 166.Xr rcorder 8 Ns 's 167.Fl k 168flag), 169reverses that order, and assigns the result to a variable. 170.It 171Calls each script in turn using 172.Fn run_rc_script 173(from 174.Xr rc.subr 8 ) , 175which sets 176.Dv $1 177to 178.Sq stop , 179and sources the script in a sub-shell. 180If the script has a 181.Sq .sh 182suffix then it is sourced directly into the current shell. 183.It 184Runs 185.Pa /etc/rc.shutdown.final 186if it exists, passing the currently ongoing shutdown action, which 187will be one of: 188.Bl -bullet 189.It 190shutdown 191when going to single user mode. 192.It 193halt 194when halting the machine (but not powering it down). 195.It 196reboot 197when rebooting the machine. 198.It 199poweroff 200when halting the machine and powering it off. 201.El 202.Pp 203The script may be used to control additional 204actions, e.g. powering off external devices, restarting 205a UPS (in case main power is restored in the interval betweeen 206the computer powering off and the UPS running out of battery). 207.El 208.Ss Contents of rc.d/ 209.Nm rc.d/ 210is located in 211.Pa /etc/rc.d . 212The following file naming conventions are currently used in 213.Nm rc.d/ : 214.Bl -tag -width ALLUPPERCASExx -offset indent 215.It Pa ALLUPPERCASE 216Scripts that are 217.Sq placeholders 218to ensure that certain operations are performed before others. 219In order of startup, these are: 220.Bl -tag -width NETWORKINGxx 221.It Pa NETWORKING 222Ensure basic network services are running, including general 223network configuration 224.Pq Pa network 225and 226.Pa dhcpcd . 227.It Pa SERVERS 228Ensure basic services (such as 229.Pa NETWORKING , 230.Pa ppp , 231.Pa syslogd , 232and 233.Pa kdc ) 234exist for services that start early (such as 235.Pa named ) , 236because they're required by 237.Pa DAEMON 238below. 239.It Pa DAEMON 240Before all general purpose daemons such as 241.Pa dhcpd , 242.Pa lpd , 243and 244.Pa ntpd . 245.It Pa LOGIN 246Before user login services 247.Pa ( inetd , 248.Pa telnetd , 249.Pa rshd , 250.Pa sshd , 251and 252.Pa xdm ) , 253as well as before services which might run commands as users 254.Pa ( cron , 255.Pa postfix , 256and 257.Pa sendmail ) . 258.El 259.It Pa inline.sh 260Scripts that are sourced into the current shell rather than a sub-shell 261have a 262.Sq Pa .sh 263suffix. 264Extreme care must be taken in using this, as the startup sequence will 265terminate if the script causes the current shell process to terminate. 266.Pa /etc/rc.d/bootconf.sh 267uses this behaviour to allow the user to select a different 268configuration (including 269.Pa /etc/rc.conf ) 270early in the boot. 271.It Pa service 272Scripts that are sourced in a sub-shell. 273The boot does not stop if such a script terminates with a non-zero status, 274but a script can stop the boot if necessary by invoking the 275.Fn stop_boot 276function (from 277.Xr rc.subr 8 ) . 278.El 279.Pp 280Each script should contain 281.Xr rcorder 8 282keywords, especially an appropriate 283.Dq PROVIDE 284entry. 285.Pp 286The scripts are expected to support at least the following arguments: 287.Bl -tag -width restart -offset indent 288.It Sy start 289Start the service. 290This should check that the service is to be started as specified by 291.Xr rc.conf 5 . 292Also checks if the service is already running and refuses to start if 293it is. 294This latter check is not performed by standard 295.Nx 296scripts if the system is starting directly to multi-user mode, to 297speed up the boot process. 298.It Sy stop 299If the service is to be started as specified by 300.Xr rc.conf 5 , 301stop the service. 302This should check that the service is running and complain if it's not. 303.It Sy restart 304Perform a 305.Sy stop 306then a 307.Sy start . 308.It Sy status 309If the script starts a process (rather than performing a one-off 310operation), show the status of the process. 311Otherwise it's not necessary to support this argument. 312Defaults to displaying the process ID of the program (if running). 313.It Sy poll 314If the script starts a process (rather than performing a one-off 315operation), wait for the command to exit. 316Otherwise it's not necessary to support this argument. 317.It Sy rcvar 318Display which 319.Xr rc.conf 5 320variables are used to control the startup of the service (if any). 321.El 322.Pp 323Other arguments (such as 324.Sq reload , 325.Sq dumpdb , 326etc) can be added if necessary. 327.Pp 328The argument may have one of the following prefixes to alter its operation: 329.Bl -tag -width "force" -offset indent 330.It Sy fast 331Skip the check for an existing running process. 332Sets 333.Sy rc_fast=yes . 334.It Sy force 335Skips the 336.Xr rc.conf 5 337check, ignores a failure result from any of the prerequisite checks, 338executes the command, and always returns a zero exit status. 339Sets 340.Sy rc_force=yes . 341.It Sy one 342Skips the 343.Xr rc.conf 5 344check, but performs all other prerequisite tests. 345.El 346.Pp 347In order to simplify scripts, the 348.Fn run_rc_command 349function from 350.Xr rc.subr 8 351may be used. 352.Sh FILES 353.Bl -tag -width /etc/rc.shutdown -compact 354.It Pa /etc/rc 355Startup script called by 356.Xr init 8 . 357.It Pa /etc/rc.d/ 358Directory containing control scripts for each service. 359.It Pa /etc/rc.local 360Local startup script. 361.It Pa /etc/rc.shutdown 362Shutdown script called by 363.Xr shutdown 8 . 364.It Pa /etc/rc.subr 365Contains 366.Xr rc.subr 8 367functions used by various scripts. 368.It Pa /etc/rc.conf 369System startup configuration file. 370.It Pa /var/run/rc.log 371Log file created by 372.Nm . 373.El 374.Sh SEE ALSO 375.Xr rc.conf 5 , 376.Xr init 8 , 377.Xr rc.subr 8 , 378.Xr rcorder 8 , 379.Xr reboot 8 , 380.Xr shutdown 8 381.Rs 382.%A Luke Mewburn 383.%T The Design and Implementation of the NetBSD rc.d system 384.%I USENIX Association 385.%B Proceedings of the FREENIX Track: 2001 USENIX Annual Technical Conference 386.%D June 25-30, 2001 387.%U http://www.usenix.org/publications/library/proceedings/usenix01/freenix01/full_papers/mewburn/mewburn.pdf 388.Re 389.Sh HISTORY 390The 391.Nm 392command appeared in 393.Bx 4.0 . 394The 395.Pa /etc/rc.d 396support was implemented in 397.Nx 1.5 398by 399.An Luke Mewburn 400.Aq lukem@NetBSD.org . 401The post-processor, support for 402.Va rc_silent , 403and saving output to a file, was implemented in 404.Nx 6.0 405by 406.An Alan Barrett . 407