1.\" $NetBSD: rc.8,v 1.36 2010/05/14 16:19:58 jruoho Exp $ 2.\" 3.\" Copyright (c) 2000-2004 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 May 14, 2010 31.Dt RC 8 32.Os 33.Sh NAME 34.Nm rc , 35.Nm rc.local , 36.Nm rc.shutdown , 37.Nm rc.d/ 38.Nd startup and shutdown scripts 39.Sh SYNOPSIS 40.Nm rc 41.Nm rc.local 42.Nm rc.shutdown 43.Nm rc.d/ 44.Sh DESCRIPTION 45.Nm 46is the command script which controls the startup of various services, 47and is invoked by 48.Xr init 8 49as part of the process of entering the automatic reboot to multi-user startup, 50or after the single user mode shell has exited. 51If 52.Xr init 8 53is starting the automatic reboot process, 54.Nm 55is invoked with the argument of 56.Sq autoboot . 57.Pp 58.Nm rc.local 59is a command script to which local boot-time actions can be added. 60It is (nearly) the last thing invoked by 61.Nm rc 62during a normal boot. 63.Pp 64.Nm rc.shutdown 65is the command script which shuts down various services, and is invoked by 66.Xr shutdown 8 67as part of the process of shutting down the system. 68.Pp 69.Nm rc.d/ 70is the directory which contains various 71.Xr sh 1 72scripts, one for each service, 73which are called by 74.Nm 75at startup, 76.Nm rc.shutdown 77at shutdown, 78and as necessary during system operation to stop, start, restart, reload, 79or otherwise control the service. 80.Ss Operation of rc 81.Bl -enum 82.It 83Source 84.Pa /etc/rc.subr 85to load various 86.Xr rc.subr 8 87shell functions to use. 88.It 89If autobooting, set 90.Sy autoboot=yes 91and enable a flag 92.Sy ( rc_fast=yes ) , 93which prevents the 94.Nm rc.d 95scripts from performing the check for already running processes 96(thus speeding up the boot process). 97This 98.Sy rc_fast=yes 99speedup won't occur when 100.Nm 101is started up after exiting the single-user shell. 102.It 103Invoke 104.Xr rcorder 8 105to order the files in 106.Pa /etc/rc.d/ 107that do not have a 108.Dq nostart 109keyword (refer to 110.Xr rcorder 8 Ns 's 111.Fl s 112flag), 113and assigns the result to a variable. 114.It 115Calls each script in turn using 116.Fn run_rc_script 117(from 118.Xr rc.subr 8 ) , 119which sets 120.Dv $1 121to 122.Sq start , 123and sources the script in a subshell. 124If the script has a 125.Sq .sh 126suffix then it is sourced directly into the current shell. 127.It 128The output from the above steps is sent to a post-processor. 129If 130.Sy rc_silent 131is false, then the post-processor displays the output. 132If 133.Sy rc_silent 134is true, then the post-processor invokes the command specified in 135.Va rc_silent_cmd 136once for each line, without otherwise displaying the output. 137Useful values for 138.Va rc_silent_cmd 139include 140.Dq \&: 141to display nothing at all, and 142.Dq twiddle 143to display a spinning symbol on the console. 144Regardless of the value of 145.Sy rc_silent , 146the post-processor saves the output in 147.Pa /var/run/rc.log . 148.El 149.Ss Operation of rc.shutdown 150.Bl -enum 151.It 152Source 153.Pa /etc/rc.subr 154to load various 155.Xr rc.subr 8 156shell functions to use. 157.It 158Invoke 159.Xr rcorder 8 160to order the files in 161.Pa /etc/rc.d/ 162that have a 163.Dq shutdown 164keyword (refer to 165.Xr rcorder 8 Ns 's 166.Fl k 167flag), 168reverses that order, and assigns the result to a variable. 169.It 170Calls each script in turn using 171.Fn run_rc_script 172(from 173.Xr rc.subr 8 ) , 174which sets 175.Dv $1 176to 177.Sq stop , 178and sources the script in a subshell. 179If the script has a 180.Sq .sh 181suffix then it is sourced directly into the current shell. 182.El 183.Ss Contents of rc.d/ 184.Nm rc.d/ 185is located in 186.Pa /etc/rc.d . 187The following file naming conventions are currently used in 188.Nm rc.d/ : 189.Bl -tag -width ALLUPPERCASExx -offset indent 190.It Pa ALLUPPERCASE 191Scripts that are 192.Sq placeholders 193to ensure that certain operations are performed before others. 194In order of startup, these are: 195.Bl -tag -width NETWORKINGxx 196.It Pa NETWORKING 197Ensure basic network services are running, including general 198network configuration 199.Pq Pa network 200and 201.Pa dhclient . 202.It Pa SERVERS 203Ensure basic services (such as 204.Pa NETWORKING , 205.Pa ppp , 206.Pa syslogd , 207and 208.Pa kdc ) 209exist for services that start early (such as 210.Pa named ) , 211because they're required by 212.Pa DAEMON 213below. 214.It Pa DAEMON 215Before all general purpose daemons such as 216.Pa dhcpd , 217.Pa lpd , 218and 219.Pa ntpd . 220.It Pa LOGIN 221Before user login services 222.Pa ( inetd , 223.Pa telnetd , 224.Pa rshd , 225.Pa sshd , 226and 227.Pa xdm ) , 228as well as before services which might run commands as users 229.Pa ( cron , 230.Pa postfix , 231and 232.Pa sendmail ) . 233.El 234.It Pa foo.sh 235Scripts that are to be sourced into the current shell rather than a subshell 236have a 237.Sq Pa .sh 238suffix. 239Extreme care must be taken in using this, as the startup sequence will 240terminate if the script does. 241.Pa /etc/rc.d/bootconf.sh 242uses this behaviour to allow the user to select a different 243configuration (including 244.Pa /etc/rc.conf ) 245early in the boot. 246.It Pa bar 247Scripts that are sourced in a subshell. 248The boot does not stop if such a script terminates with a non-zero status, 249but a script can stop the boot if necessary by invoking the 250.Fn stop_boot 251function (from 252.Xr rc.subr 8 ) . 253.El 254.Pp 255Each script should contain 256.Xr rcorder 8 257keywords, especially an appropriate 258.Dq PROVIDE 259entry. 260.Pp 261The scripts are expected to support at least the following arguments: 262.Bl -tag -width restart -offset indent 263.It Sy start 264Start the service. 265This should check that the service is to be started as specified by 266.Xr rc.conf 5 . 267Also checks if the service is already running and refuses to start if 268it is. 269This latter check is not performed by standard 270.Nx 271scripts if the system is starting directly to multi-user mode, to 272speed up the boot process. 273.It Sy stop 274If the service is to be started as specified by 275.Xr rc.conf 5 , 276stop the service. 277This should check that the service is running and complain if it's not. 278.It Sy restart 279Perform a 280.Sy stop 281then a 282.Sy start . 283.It Sy status 284If the script starts a process (rather than performing a one-off 285operation), show the status of the process. 286Otherwise it's not necessary to support this argument. 287Defaults to displaying the process ID of the program (if running). 288.It Sy poll 289If the script starts a process (rather than performing a one-off 290operation), wait for the command to exit. 291Otherwise it's not necessary to support this argument. 292.It Sy rcvar 293Display which 294.Xr rc.conf 5 295variables are used to control the startup of the service (if any). 296.El 297.Pp 298Other arguments (such as 299.Sq reload , 300.Sq dumpdb , 301etc) can be added if necessary. 302.Pp 303The argument may have one of the following prefixes to alter its operation: 304.Bl -tag -width "force" -offset indent 305.It Sy fast 306Skip the check for an existing running process. 307Sets 308.Sy rc_fast=yes . 309.It Sy force 310Skips the 311.Xr rc.conf 5 312check, ignores a failure result from any of the prerequisite checks, 313executes the command, and always returns a zero exit status. 314Sets 315.Sy rc_force=yes . 316.It Sy one 317Skips the 318.Xr rc.conf 5 319check, but performs all other prerequisite tests. 320.El 321.Pp 322In order to simplify scripts, the 323.Fn run_rc_command 324function from 325.Xr rc.subr 8 326may be used. 327.Sh FILES 328.Bl -tag -width /etc/rc.shutdown -compact 329.It Pa /etc/rc 330Startup script called by 331.Xr init 8 . 332.It Pa /etc/rc.d/ 333Directory containing control scripts for each service. 334.It Pa /etc/rc.local 335Local startup script. 336.It Pa /etc/rc.shutdown 337Shutdown script called by 338.Xr shutdown 8 . 339.It Pa /etc/rc.subr 340Contains 341.Xr rc.subr 8 342functions used by various scripts. 343.It Pa /etc/rc.conf 344System startup configuration file. 345.It Pa /var/run/rc.log 346Log file created by 347.Nm . 348.El 349.Sh SEE ALSO 350.Xr rc.conf 5 , 351.Xr init 8 , 352.Xr rc.subr 8 , 353.Xr rcorder 8 , 354.Xr reboot 8 , 355.Xr shutdown 8 356.Rs 357.%A Luke Mewburn 358.%T The Design and Implementation of the NetBSD rc.d system 359.%I USENIX Association 360.%B Proceedings of the FREENIX Track: 2001 USENIX Annual Technical Conference 361.%D June 25-30, 2001 362.%U http://www.usenix.org/publications/library/proceedings/usenix01/freenix01/full_papers/mewburn/mewburn.pdf 363.Re 364.Sh HISTORY 365The 366.Nm 367command appeared in 368.Bx 4.0 . 369The 370.Pa /etc/rc.d 371support was implemented in 372.Nx 1.5 373by 374.An Luke Mewburn 375.Aq lukem@NetBSD.org . 376The post-processor, support for 377.Va rc_silent , 378and saving output to a file, was implemented in 379.Nx 6.0 380by 381.An Alan Barrett . 382