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