/[gentoo]/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml
Gentoo

Contents of /xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.2 - (show annotations) (download) (as text)
Tue Dec 2 19:33:12 2003 UTC (10 years, 8 months ago) by swift
Branch: MAIN
Changes since 1.1: +449 -24 lines
File MIME type: application/xml
Finished draft

1 <!-- The content of this document is licensed under the CC-BY-SA license -->
2 <!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
3
4 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.1 2003/11/20 10:52:35 swift Exp $ -->
5
6 <sections>
7 <section>
8 <title>Runlevels</title>
9 <subsection>
10 <title>What is a runlevel?</title>
11 <body>
12
13 <p>
14 When you boot your system, a number of tasks need to be performed before you are
15 able to log on. This "normal" boot operation is fully defined -- it will be the
16 same every time you restart your system. A <e>runlevel</e> is a state in which
17 your system is running and contains a collection of scripts (runlevel scripts or
18 <e>initscripts</e>) that must be executed when you enter or leave a runlevel.
19 </p>
20
21 </body>
22 </subsection>
23 <subsection>
24 <title>Booting your System</title>
25 <body>
26
27 <p>
28 The process that takes care of the runlevels is called <c>init</c> and is also
29 the first process started by the Linux kernel. <c>init</c>'s configuration file
30 is called <path>/etc/inittab</path> and gets read immediately after <c>init</c>
31 is started. In this configuration file, the commands used to enter a certain
32 runlevel are listed. For instance, after initialising the system (<e>si</e>),
33 the <b>boot</b> runlevel is started:
34 </p>
35
36 <pre caption="System initialisation lines in /etc/inittab">
37 si::sysinit:/sbin/rc sysinit
38 rc::bootwait:/sbin/rc boot
39 </pre>
40
41 <p>
42 As you can see, <c>init</c> relies on the <c>rc</c> script. When started with
43 the "boot" argument, <c>rc</c> starts all scripts in the
44 <path>/etc/runlevels/boot</path> directory. Don't think about the sequence used
45 to start the scripts -- we will explain later how Gentoo uses dependencies for
46 the init scripts.
47 </p>
48
49 <p>
50 When the <b>boot</b> runlevel is completed (the boot runlevel is an intermediate
51 one), <c>init</c> checks what runlevel it should start. If you have not defined
52 one as kernel parameter, it will use the one defined in
53 <path>/etc/inittab</path>:
54 </p>
55
56 <pre caption="Default runlevel">
57 id:3:initdefault:
58 </pre>
59
60 <p>
61 In this case, the runlevel id is "3", and gets mapped to:
62 </p>
63
64 <pre caption="Mapping from number to readable commands in /etc/inittab">
65 l3:3:wait:/sbin/rc default
66 </pre>
67
68 <p>
69 In other words, the <c>rc</c> script is asked to activate the <b>default</b>
70 runlevel. Again, this results in executing all
71 <path>/etc/runlevels/default</path> scripts.
72 </p>
73
74 </body>
75 </subsection>
76 <subsection>
77 <title>Numbers and Names</title>
78 <body>
79
80 <p>
81 When you take a look at <path>/etc/inittab</path>, you will see the following
82 section:
83 </p>
84
85 <pre caption="Defining the runlevels in /etc/inittab">
86 l0:0:wait:/sbin/rc shutdown
87 l1:S1:wait:/sbin/rc single
88 l2:2:wait:/sbin/rc nonetwork
89 l3:3:wait:/sbin/rc default
90 l4:4:wait:/sbin/rc default
91 l5:5:wait:/sbin/rc default
92 l6:6:wait:/sbin/rc reboot
93 </pre>
94
95 <p>
96 As you can see, there is a mapping of numbers to names (not vice versa). For
97 instance, 0 maps to "shutdown", 1 to "single" etc. Vice versa is not true, as
98 "default" is used by 3, 4 and 5. These numbers are the runlevel numbers. Most
99 distributions work with the numbers; Gentoo however decided to make it a bit
100 more userfriendly and continue with the naming.
101 </p>
102
103 <p>
104 As you can see from the listings, Gentoo defines 7 runlevels. Three of them are
105 internal runlevels: <e>sysinit</e>, <e>shutdown</e> and <e>reboot</e>. The
106 <b>sysinit</b> runlevel mounts all necessary filesystems as defined in
107 <path>/etc/fstab</path>. The <b>shutdown</b> runlevel shuts down all running
108 services and powers down the system. The <b>reboot</b> runlevel acts like the
109 <e>shutdown</e> runlevel, but reboots the system instead of powering down.
110 </p>
111
112 <p>
113 The other four runlevels are <e>boot</e>, <e>default</e>, <e>nonetwork</e> and
114 <e>single</e>. Each of them has a subdirectory in <path>/etc/runlevels</path>
115 containing scripts that need to be started when the runlevel is activated.
116 </p>
117
118 </body>
119 </subsection>
120 <subsection>
121 <title>Working with the initscripts</title>
122 <body>
123
124 <p>
125 If you take a closer look to <path>/etc/runlevels/default</path>, you will
126 notice that it contains symbolic links to identically named scripts located in
127 <path>/etc/init.d</path> and not just scripts as we mentioned previously. For
128 instance, <path>/etc/runlevels/default/postfix</path> is a symbolic link to
129 <path>/etc/init.d/postfix</path>. In general we can say that such a script
130 provides a service...
131 </p>
132
133 <p>
134 Each script in <path>/etc/init.d</path> can be executed with the arguments
135 <e>start</e>, <e>stop</e>, <e>restart</e>, <e>pause</e>, <e>zap</e>,
136 <e>status</e>, <e>ineed</e>, <e>iuse</e>, <e>needsme</e>, <e>usesme</e> or
137 <e>broken</e>.
138 </p>
139
140 <p>
141 To start, stop or restart a service (and all depending services), <c>start</c>,
142 <c>stop</c> and <c>restart</c> should be used:
143 </p>
144
145 <pre caption="Starting Postfix">
146 # <i>/etc/init.d/postfix start</i>
147 </pre>
148
149 <p>
150 If you want to stop a service, but not the services that depend on it, you can
151 use the <c>pause</c> argument:
152 </p>
153
154 <pre caption="Stopping Postfix but keep the depending services running">
155 # <i>/etc/init.d/postfix pause</i>
156 </pre>
157
158 <p>
159 If you want to see what status a service has (started, stopped, paused, ...) you
160 can use the <c>status</c> argument:
161 </p>
162
163 <pre caption="Status information for postfix">
164 # <i>/etc/init.d/postfix status</i>
165 </pre>
166
167 <p>
168 If the status information tells you that the service is running, but it doesn't,
169 then you can reset the status information to "stopped" with the <c>zap</c>
170 argument:
171 </p>
172
173 <pre caption="Resetting status information for postfix">
174 # <i>/etc/init.d/postfix zap</i>
175 </pre>
176
177 <p>
178 To also ask what dependencies the service has, you can use <c>iuse</c> or
179 <c>ineed</c>. With <c>ineed</c> you can see the services that are really
180 necessary for the correct functioning of the service. <c>iuse</c> on the other
181 hand shows the services that can be used by the service, but are not necessary
182 for the correct functioning.
183 </p>
184
185 <pre caption="Requesting a list of all necessary services on which Postfix depends">
186 # <i>/etc/init.d/postfix ineed</i>
187 </pre>
188
189 <p>
190 Similarly, you can ask what services require the service (<c>needsme</c>) or can
191 use it (<c>usesme</c>):
192 </p>
193
194 <pre caption="Requesting a list of all services that require Postfix">
195 # <i>/etc/init.d/postfix needsme</i>
196 </pre>
197
198 <p>
199 Finally, you can ask what dependencies the service requires but that are
200 missing:
201 </p>
202
203 <pre caption="Requesting a list of missing dependencies for Postfix">
204 # <i>/etc/init.d/postfix broken</i>
205 </pre>
206
207 </body>
208 </subsection>
209 </section>
210 <section>
211 <title>Working with rc-update</title>
212 <subsection>
213 <title>What is rc-update?</title>
214 <body>
215
216 <p>
217 Gentoo's init system uses a dependency-tree to decide what service needs to be
218 started first. As this is a tedious task that we wouldn't want our users to do
219 manually, we have created tools that ease the administration of the runlevels
220 and init scripts.
221 </p>
222
223 <p>
224 With <c>rc-update</c> you can add and remove init scripts to a runlevel. The
225 <c>rc-update</c> tool will then automatically ask the <c>depscan.sh</c> script
226 to rebuild the dependency tree.
227 </p>
228
229 </body>
230 </subsection>
231 <subsection>
232 <title>Adding and Removing Services</title>
233 <body>
234
235 <p>
236 You have already added init scripts to the "default" runlevel during the
237 installation of Gentoo. At that time you might not had a clue what the
238 "default" is for, but now you should. The <c>rc-update</c> script requires a
239 second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>.
240 </p>
241
242 <p>
243 To add or remove an init script, just give <c>rc-update</c> the <c>add</c> or
244 <c>del</c> argument, followed by the init script and the runlevel. For instance:
245 </p>
246
247 <pre caption="Removing Postfix from the default runlevel">
248 # <i>rc-update del postfix default</i>
249 </pre>
250
251 <p>
252 The <c>rc-update show</c> command will show all the available init scripts and
253 list at which runlevels they will execute:
254 </p>
255
256 <pre caption="Receiving init script information">
257 # <i>rc-update show</i>
258 </pre>
259
260 </body>
261 </subsection>
262 </section>
263 <section>
264 <title>Configuring Services</title>
265 <subsection>
266 <title>Why the Need for Extra Configuration?</title>
267 <body>
268
269 <p>
270 Init scripts can be quite complex. It is therefor not really interesting to have
271 the users directly edit the init script, as it would make it more error-prone.
272 It is however important to be able to configure such a service. For instance,
273 you might want to give more options to the service itself.
274 </p>
275
276 <p>
277 A second reason to have this configuration outside the init script is to be able
278 to update the init scripts without being afraid that your configuration changes
279 are undone.
280 </p>
281
282 </body>
283 </subsection>
284 <subsection>
285 <title>The /etc/conf.d Directory</title>
286 <body>
287
288 <p>
289 Gentoo provides an easy way to configure such a service: every init script that
290 can be configured has a file in <path>/etc/conf.d</path>. For instance, the
291 apache2 initscript (called <path>/etc/init.d/apache2</path>) has a
292 configuration file called <path>/etc/conf.d/apache2</path>, which can contain
293 the options you want to give to the Apache 2 server when it is started:
294 </p>
295
296 <pre caption="Variable defined in /etc/conf.d/apache2">
297 APACHE2_OPTS="-D PHP4"
298 </pre>
299
300 <p>
301 Such a configuration file contains variables and variables alone (just like
302 <path>/etc/make.conf</path>), making it very easy to configure services. It also
303 allows us to provide more information about the variables (as comments).
304 </p>
305
306 </body>
307 </subsection>
308 </section>
309 <section>
310 <title>Writing Init Scripts</title>
311 <subsection>
312 <title>Do I Have To?</title>
313 <body>
314
315 <p>
316 No. Writing an init script is usually not necessary as Gentoo provides
317 ready-to-use init scripts for all provided services. However, you might have
318 installed a service without using Portage, in which case you will most likely
319 have to create an init script.
320 </p>
321
322 <p>
323 Do not use the init script provided by the service if it isn't explicitly
324 written for Gentoo: Gentoo's init scripts are not compatible with the init
325 scripts used by other distributions!
326 </p>
327
328 </body>
329 </subsection>
330 <subsection>
331 <title>Layout</title>
332 <body>
333
334 <p>
335 The basic layout of an init script is shown below.
336 </p>
337
338 <pre caption="Basic layout of an init script">
339 #!/sbin/runscript
340
341 depend() {
342 <comment>(Dependency information)</comment>
343 }
344
345 start() {
346 <comment>(Commands necessary to start the service)</comment>
347 }
348
349 stop() {
350 <comment>(Commands necessary to stop the service)</comment>
351 }
352
353 restart() {
354 <comment>(Commands necessary to restart the service)</comment>
355 }
356 </pre>
357
358 <p>
359 Any init script <e>requires</e> the <c>start()</c> function to be defined. All
360 other sections are optional.
361 </p>
362
363 </body>
364 </subsection>
365 <subsection>
366 <title>Dependencies</title>
367 <body>
368
369 <p>
370 There are two dependencies you can define: <c>use</c> and <c>need</c>. As we
371 have mentioned before, the <c>need</c> dependency is more strict than the
372 <c>use</c> dependency. Following this dependency type you enter the service
373 you depend on, or the <e>virtual</e> dependency.
374 </p>
375
376 <p>
377 A <e>virtual</e> dependency is a dependency that a service provides, but that is
378 not provided solely by that service. Your init script can depend on a system
379 logger, but there are many system loggers available (metalogd, syslog-ng,
380 sysklogd, ...). As you cannot <c>need</c> every single one of them (no sensible
381 system has all these system loggers installed and running) we made sure that
382 all these services <c>provide</c> a virtual dependency.
383 </p>
384
385 <p>
386 Let us take a look at the dependency information for the postfix service.
387 </p>
388
389 <pre caption="Dependency information for Postfix">
390 depend() {
391 need net
392 use logger dns
393 provide mta
394 }
395 </pre>
396
397 <p>
398 As you can see, the postfix service:
399 </p>
400
401 <ul>
402 <li>
403 requires the (virtual) <c>net</c> dependency (which is provided by, for
404 instance, <path>/etc/init.d/net.eth0</path>)
405 </li>
406 <li>
407 uses the (virtual) <c>logger</c> dependency (which is provided by, for
408 instance, <path>/etc/init.d/syslog-ng</path>)
409 </li>
410 <li>
411 uses the (virtual) <c>dns</c> dependency (which is provided by, for
412 instance, <path>/etc/init.d/named</path>)
413 </li>
414 <li>
415 provides the (virtual) <c>mta</c> dependency (which is common for all mail
416 servers)
417 </li>
418 </ul>
419
420 </body>
421 </subsection>
422 <subsection>
423 <title>Controlling the Order</title>
424 <body>
425
426 <p>
427 In some cases you might not require a service, but want your service to be
428 started <c>before</c> (or <c>after</c>) another service <e>if</e> it is
429 available on the system (note the conditional - this is no dependency anymore)
430 <e>and</e> ran in the same runlevel (note the conditional - only services in the
431 same runlevel are involved). You can provide this information using the
432 <c>before</c> or <c>after</c> settings.
433 </p>
434
435 <p>
436 As an example we view the settings of the Portmap service:
437 </p>
438
439 <pre caption="The depend() function in the Portmap service">
440 depend() {
441 need net
442 before inetd
443 before xinetd
444 }
445 </pre>
446
447 <p>
448 You can also use the "*" glob to catch all services in the same runlevel,
449 although this isn't adviseable.
450 </p>
451
452 <pre caption="Running an init script as first script in the runlevel">
453 depend() {
454 before *
455 }
456 </pre>
457
458 </body>
459 </subsection>
460 <subsection>
461 <title>Standard Functions</title>
462 <body>
463
464 <p>
465 Next to the <c>depend()</c> functionality, you also need to define the
466 <c>start()</c> function. This one contains all the commands necessary to
467 initialise your service. It is adviseable to use the <c>ebegin</c> and
468 <c>eend</c> functions to inform the user about what is happening:
469 </p>
470
471 <pre caption="Example start() function">
472 start() {
473 ebegin "Starting my_service"
474 start-stop-daemon --start --quiet --exec /path/to/my_service
475 eend $?
476 }
477 </pre>
478
479 <p>
480 If you need more examples of the <c>start()</c> function, please read the source
481 code of the available init scripts in your <path>/etc/init.d</path> directory.
482 As for <c>start-stop-daemon</c>, there is an excellent man page available if you
483 need more information:
484 </p>
485
486 <pre caption="Getting the man page for start-stop-daemon">
487 # <i>man start-stop-daemon</i>
488 </pre>
489
490 <p>
491 Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are
492 not obliged to define these functions! Our init system is intelligent enough to
493 fill these functions in herself if you use <c>start-stop-daemon</c>.
494 </p>
495
496 </body>
497 </subsection>
498 <subsection>
499 <title>Adding Custom Options</title>
500 <body>
501
502 <p>
503 If you want your init script to support more options than the ones we have
504 already encountered, you should add the option to the <c>opts</c> variable, and
505 create a function with the same name as the option. For instance, to support an
506 option called <c>restartdelay</c>:
507 </p>
508
509 <pre caption="Supporting the restartdelay option">
510 opts="${opts} restartdelay"
511
512 restartdelay() {
513 stop()
514 sleep 3 <comment># Wait 3 seconds before starting again</comment>
515 start()
516 }
517 </pre>
518
519 </body>
520 </subsection>
521 <subsection>
522 <title>Service Configuration Variables</title>
523 <body>
524
525 <p>
526 You don't have to do anything to support a configuration file in
527 <path>/etc/conf.d</path>: if your init script is executed, the following files
528 are automatically sourced (i.e. the variables are available to use):
529 </p>
530
531 <ul>
532 <li><path>/etc/conf.d/&lt;your init script&gt;</path></li>
533 <li><path>/etc/conf.d/basic</path></li>
534 <li><path>/etc/rc.conf</path></li>
535 </ul>
536
537 <p>
538 Also, if your init script provides a virtual dependency (such as <c>net</c>),
539 the file associated with that dependency (such as <path>/etc/conf.d/net</path>)
540 will be sourced too.
541 </p>
542
543 </body>
544 </subsection>
545 </section>
546 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20