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