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