/[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.8 - (show annotations) (download) (as text)
Tue Jan 6 09:57:49 2004 UTC (10 years, 7 months ago) by swift
Branch: MAIN
Changes since 1.7: +2 -2 lines
File MIME type: application/xml
Fix typos, #37377

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.7 2003/12/16 18:36:04 swift Exp $ -->
5
6 <sections>
7 <section>
8 <title>Runlevels</title>
9 <subsection>
10 <title>Booting your System</title>
11 <body>
12
13 <p>
14 When you boot your system, you will notice lots of text floating by. If you pay
15 close attention, you will notice this text is the same every time you reboot
16 your system. The sequence of all these actions is called the <e>boot
17 sequence</e> and is (more or less) statically defined.
18 </p>
19
20 <p>
21 First, your boot loader will load the kernel image you have defined in the
22 boot loader configuration into memory after which it tells the CPU to run the
23 kernel. When the kernel is loaded and run, it initializes all kernel-specific
24 structures and tasks and starts the <c>init</c> process.
25 </p>
26
27 <p>
28 This process then makes sure that all filesystems (defined in
29 <path>/etc/fstab</path>) are mounted and ready to be used. Then it executes
30 several scripts located in <path>/etc/init.d</path>, which will start the
31 services you need in order to have a successfully booted system.
32 </p>
33
34 <p>
35 Finally, when all scripts are executed, <c>init</c> activates the terminals
36 (in most cases just the virtual consoles which are hidden beneith <c>Alt-F1</c>,
37 <c>Alt-F2</c>, etc.) attaching a special process called <c>agetty</c> to it.
38 This process will then make sure you are able to log on through these terminals
39 by running <c>login</c>.
40 </p>
41
42 </body>
43 </subsection>
44 <subsection>
45 <title>Init Scripts</title>
46 <body>
47
48 <p>
49 Now <c>init</c> doesn't just execute the scripts in <path>/etc/init.d</path>
50 randomly. Even more, it doesn't run all scripts in <path>/etc/init.d</path>,
51 only the scripts it is told to execute. It decides which scripts to execute by
52 looking into <path>/etc/runlevels</path>.
53 </p>
54
55 <p>
56 First, <c>init</c> runs all scripts from <path>/etc/init.d</path> that have
57 symbolic links inside <path>/etc/runlevels/boot</path>. Usually, it will
58 start the scripts in alphabetical order, but some scripts have dependency
59 information in them, telling the system that another script must be run before
60 they can be started.
61 </p>
62
63 <p>
64 When all <path>/etc/runlevels/boot</path> referenced scripts are executed,
65 <c>init</c> continues with running the scripts that have a symbolic link to them
66 in <path>/etc/runlevels/default</path>. Again, it will use the alphabetical
67 order to decide what script to run first, unless a script has dependency
68 information in it, in which case the order is changed to provide a valid
69 start-up sequence.
70 </p>
71
72 </body>
73 </subsection>
74 <subsection>
75 <title>How Init Works</title>
76 <body>
77
78 <p>
79 Of course <c>init</c> doesn't decide all that by itself. It needs a
80 configuration file that specifies what actions need to be taken. This
81 configuration file is <path>/etc/inittab</path>.
82 </p>
83
84 <p>
85 If you remember the boot sequence we have just explained to you, you will
86 remember that <c>init</c>'s first action is to mount all filesystems. This is
87 defined in the following line from <path>/etc/inittab</path>:
88 </p>
89
90 <pre caption="The system initialisation line in /etc/inittab">
91 si::sysinit:/sbin/rc sysinit
92 </pre>
93
94 <p>
95 This line tells <c>init</c> that it must run <c>/sbin/rc sysinit</c> to
96 initialize the system. The <path>/sbin/rc</path> script takes care of the
97 initialisation, so you might say that <c>init</c> doesn't do much -- it
98 delegates the task of initialising the system to another process.
99 </p>
100
101 <p>
102 Second, <c>init</c> executed all scripts that had symbolic links in
103 <path>/etc/runlevels/boot</path>. This is defined in the following line:
104 </p>
105
106 <pre caption="The system initialisation, continued">
107 rc::bootwait:/sbin/rc boot
108 </pre>
109
110 <p>
111 Again the <c>rc</c> script performs the necessary tasks. Note that the option
112 given to <c>rc</c> (<e>boot</e>) is the same as the subdirectory of
113 <path>/etc/runlevels</path> that is used.
114 </p>
115
116 <p>
117 Now <c>init</c> checks its configuration file to see what <e>runlevel</e> it
118 should run. To decide this, it reads the following line from
119 <path>/etc/inittab</path>:
120 </p>
121
122 <pre caption="The initdefault line">
123 id:3:initdefault:
124 </pre>
125
126 <p>
127 In this case (which the majority of Gentoo users will use), the <e>runlevel</e>
128 id is 3. Using this information, <c>init</c> checks what it must run to start
129 <e>runlevel 3</e>:
130 </p>
131
132 <pre caption="The runlevel definitions">
133 l0:0:wait:/sbin/rc shutdown
134 l1:S1:wait:/sbin/rc single
135 l2:2:wait:/sbin/rc nonetwork
136 l3:3:wait:/sbin/rc default
137 l4:4:wait:/sbin/rc default
138 l5:5:wait:/sbin/rc default
139 l6:6:wait:/sbin/rc reboot
140 </pre>
141
142 <p>
143 The line that defines level 3, again, uses the <c>rc</c> script to start the
144 services (now with argument <e>default</e>). Again note that the argument of
145 <c>rc</c> is the same as the subdirectory from <path>/etc/runlevels</path>.
146 </p>
147
148 <p>
149 When <c>rc</c> has finished, <c>init</c> decides what virtual consoles it should
150 activate and what commands need to be run at each console:
151 </p>
152
153 <pre caption="The virtual consoles definition">
154 c1:12345:respawn:/sbin/agetty 38400 tty1 linux
155 c2:12345:respawn:/sbin/agetty 38400 tty2 linux
156 c3:12345:respawn:/sbin/agetty 38400 tty3 linux
157 c4:12345:respawn:/sbin/agetty 38400 tty4 linux
158 c5:12345:respawn:/sbin/agetty 38400 tty5 linux
159 c6:12345:respawn:/sbin/agetty 38400 tty6 linux
160 </pre>
161
162
163 </body>
164 </subsection>
165 <subsection>
166 <title>What is a runlevel?</title>
167 <body>
168
169 <p>
170 You have seen that <c>init</c> uses a numbering scheme to decide what
171 <e>runlevel</e> it should activate. A <e>runlevel</e> is a state in which
172 your system is running and contains a collection of scripts (runlevel scripts or
173 <e>initscripts</e>) that must be executed when you enter or leave a runlevel.
174 </p>
175
176 <p>
177 In Gentoo, there are seven runlevels defined: three internal runlevels, and four
178 user-defined runlevels. The internal runlevels are called <e>sysinit</e>,
179 <e>shutdown</e> and <e>reboot</e> and do exactly what their names imply:
180 initialize the system, powering off the system and rebooting the system.
181 </p>
182
183 <p>
184 The user-defined runlevels are those with an accompanying
185 <path>/etc/runlevels</path> subdirectory: <path>boot</path>,
186 <path>default</path>, <path>nonetwork</path> and <path>single</path>. The
187 <path>boot</path> runlevel starts all system-necessary services which all other
188 runlevels use. The remaining three runlevels differ in what services they start:
189 <path>default</path> is used for day-to-day operations, <path>nonetwork</path>
190 is used in case no network connectivity is required, and <path>single</path> is
191 used when you need to fix the system.
192 </p>
193
194 </body>
195 </subsection>
196 <subsection>
197 <title>Working with the Init Scripts</title>
198 <body>
199
200 <p>
201 The scripts that the <c>rc</c> process starts are called <e>init scripts</e>.
202 Each script in <path>/etc/init.d</path> can be executed with the arguments
203 <e>start</e>, <e>stop</e>, <e>restart</e>, <e>pause</e>, <e>zap</e>,
204 <e>status</e>, <e>ineed</e>, <e>iuse</e>, <e>needsme</e>, <e>usesme</e> or
205 <e>broken</e>.
206 </p>
207
208 <p>
209 To start, stop or restart a service (and all depending services), <c>start</c>,
210 <c>stop</c> and <c>restart</c> should be used:
211 </p>
212
213 <pre caption="Starting Postfix">
214 # <i>/etc/init.d/postfix start</i>
215 </pre>
216
217 <note>
218 Only the services that <e>need</e> the given service are stopped or restarted.
219 The other depending services (those that <e>use</e> the service but don't need
220 it) are left untouched.
221 </note>
222
223 <p>
224 If you want to stop a service, but not the services that depend on it, you can
225 use the <c>pause</c> argument:
226 </p>
227
228 <pre caption="Stopping Postfix but keep the depending services running">
229 # <i>/etc/init.d/postfix pause</i>
230 </pre>
231
232 <p>
233 If you want to see what status a service has (started, stopped, paused, ...) you
234 can use the <c>status</c> argument:
235 </p>
236
237 <pre caption="Status information for postfix">
238 # <i>/etc/init.d/postfix status</i>
239 </pre>
240
241 <p>
242 If the status information tells you that the service is running, but you know
243 that it is not, then you can reset the status information to "stopped" with the
244 <c>zap</c> argument:
245 </p>
246
247 <pre caption="Resetting status information for postfix">
248 # <i>/etc/init.d/postfix zap</i>
249 </pre>
250
251 <p>
252 To also ask what dependencies the service has, you can use <c>iuse</c> or
253 <c>ineed</c>. With <c>ineed</c> you can see the services that are really
254 necessary for the correct functioning of the service. <c>iuse</c> on the other
255 hand shows the services that can be used by the service, but are not necessary
256 for the correct functioning.
257 </p>
258
259 <pre caption="Requesting a list of all necessary services on which Postfix depends">
260 # <i>/etc/init.d/postfix ineed</i>
261 </pre>
262
263 <p>
264 Similarly, you can ask what services require the service (<c>needsme</c>) or can
265 use it (<c>usesme</c>):
266 </p>
267
268 <pre caption="Requesting a list of all services that require Postfix">
269 # <i>/etc/init.d/postfix needsme</i>
270 </pre>
271
272 <p>
273 Finally, you can ask what dependencies the service requires but that are
274 missing:
275 </p>
276
277 <pre caption="Requesting a list of missing dependencies for Postfix">
278 # <i>/etc/init.d/postfix broken</i>
279 </pre>
280
281 </body>
282 </subsection>
283 </section>
284 <section>
285 <title>Working with rc-update</title>
286 <subsection>
287 <title>What is rc-update?</title>
288 <body>
289
290 <p>
291 Gentoo's init system uses a dependency-tree to decide what service needs to be
292 started first. As this is a tedious task that we wouldn't want our users to do
293 manually, we have created tools that ease the administration of the runlevels
294 and init scripts.
295 </p>
296
297 <p>
298 With <c>rc-update</c> you can add and remove init scripts to a runlevel. The
299 <c>rc-update</c> tool will then automatically ask the <c>depscan.sh</c> script
300 to rebuild the dependency tree.
301 </p>
302
303 </body>
304 </subsection>
305 <subsection>
306 <title>Adding and Removing Services</title>
307 <body>
308
309 <p>
310 You have already added init scripts to the "default" runlevel during the
311 installation of Gentoo. At that time you might not have had a clue what the
312 "default" is for, but now you should. The <c>rc-update</c> script requires a
313 second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>.
314 </p>
315
316 <p>
317 To add or remove an init script, just give <c>rc-update</c> the <c>add</c> or
318 <c>del</c> argument, followed by the init script and the runlevel. For instance:
319 </p>
320
321 <pre caption="Removing Postfix from the default runlevel">
322 # <i>rc-update del postfix default</i>
323 </pre>
324
325 <p>
326 The <c>rc-update show</c> command will show all the available init scripts and
327 list at which runlevels they will execute:
328 </p>
329
330 <pre caption="Receiving init script information">
331 # <i>rc-update show</i>
332 </pre>
333
334 </body>
335 </subsection>
336 </section>
337 <section>
338 <title>Configuring Services</title>
339 <subsection>
340 <title>Why the Need for Extra Configuration?</title>
341 <body>
342
343 <p>
344 Init scripts can be quite complex. It is therefore not really interesting to
345 have the users directly edit the init script, as it would make it more
346 error-prone. It is however important to be able to configure such a service. For
347 instance, you might want to give more options to the service itself.
348 </p>
349
350 <p>
351 A second reason to have this configuration outside the init script is to be able
352 to update the init scripts without being afraid that your configuration changes
353 are undone.
354 </p>
355
356 </body>
357 </subsection>
358 <subsection>
359 <title>The /etc/conf.d Directory</title>
360 <body>
361
362 <p>
363 Gentoo provides an easy way to configure such a service: every init script that
364 can be configured has a file in <path>/etc/conf.d</path>. For instance, the
365 apache2 initscript (called <path>/etc/init.d/apache2</path>) has a
366 configuration file called <path>/etc/conf.d/apache2</path>, which can contain
367 the options you want to give to the Apache 2 server when it is started:
368 </p>
369
370 <pre caption="Variable defined in /etc/conf.d/apache2">
371 APACHE2_OPTS="-D PHP4"
372 </pre>
373
374 <p>
375 Such a configuration file contains variables and variables alone (just like
376 <path>/etc/make.conf</path>), making it very easy to configure services. It also
377 allows us to provide more information about the variables (as comments).
378 </p>
379
380 </body>
381 </subsection>
382 </section>
383 <section>
384 <title>Writing Init Scripts</title>
385 <subsection>
386 <title>Do I Have To?</title>
387 <body>
388
389 <p>
390 No. Writing an init script is usually not necessary as Gentoo provides
391 ready-to-use init scripts for all provided services. However, you might have
392 installed a service without using Portage, in which case you will most likely
393 have to create an init script.
394 </p>
395
396 <p>
397 Do not use the init script provided by the service if it isn't explicitly
398 written for Gentoo: Gentoo's init scripts are not compatible with the init
399 scripts used by other distributions!
400 </p>
401
402 </body>
403 </subsection>
404 <subsection>
405 <title>Layout</title>
406 <body>
407
408 <p>
409 The basic layout of an init script is shown below.
410 </p>
411
412 <pre caption="Basic layout of an init script">
413 #!/sbin/runscript
414
415 depend() {
416 <comment>(Dependency information)</comment>
417 }
418
419 start() {
420 <comment>(Commands necessary to start the service)</comment>
421 }
422
423 stop() {
424 <comment>(Commands necessary to stop the service)</comment>
425 }
426
427 restart() {
428 <comment>(Commands necessary to restart the service)</comment>
429 }
430 </pre>
431
432 <p>
433 Any init script <e>requires</e> the <c>start()</c> function to be defined. All
434 other sections are optional.
435 </p>
436
437 </body>
438 </subsection>
439 <subsection>
440 <title>Dependencies</title>
441 <body>
442
443 <p>
444 There are two dependencies you can define: <c>use</c> and <c>need</c>. As we
445 have mentioned before, the <c>need</c> dependency is more strict than the
446 <c>use</c> dependency. Following this dependency type you enter the service
447 you depend on, or the <e>virtual</e> dependency.
448 </p>
449
450 <p>
451 A <e>virtual</e> dependency is a dependency that a service provides, but that is
452 not provided solely by that service. Your init script can depend on a system
453 logger, but there are many system loggers available (metalogd, syslog-ng,
454 sysklogd, ...). As you cannot <c>need</c> every single one of them (no sensible
455 system has all these system loggers installed and running) we made sure that
456 all these services <c>provide</c> a virtual dependency.
457 </p>
458
459 <p>
460 Let us take a look at the dependency information for the postfix service.
461 </p>
462
463 <pre caption="Dependency information for Postfix">
464 depend() {
465 need net
466 use logger dns
467 provide mta
468 }
469 </pre>
470
471 <p>
472 As you can see, the postfix service:
473 </p>
474
475 <ul>
476 <li>
477 requires the (virtual) <c>net</c> dependency (which is provided by, for
478 instance, <path>/etc/init.d/net.eth0</path>)
479 </li>
480 <li>
481 uses the (virtual) <c>logger</c> dependency (which is provided by, for
482 instance, <path>/etc/init.d/syslog-ng</path>)
483 </li>
484 <li>
485 uses the (virtual) <c>dns</c> dependency (which is provided by, for
486 instance, <path>/etc/init.d/named</path>)
487 </li>
488 <li>
489 provides the (virtual) <c>mta</c> dependency (which is common for all mail
490 servers)
491 </li>
492 </ul>
493
494 </body>
495 </subsection>
496 <subsection>
497 <title>Controlling the Order</title>
498 <body>
499
500 <p>
501 In some cases you might not require a service, but want your service to be
502 started <c>before</c> (or <c>after</c>) another service <e>if</e> it is
503 available on the system (note the conditional - this is no dependency anymore)
504 <e>and</e> ran in the same runlevel (note the conditional - only services in the
505 same runlevel are involved). You can provide this information using the
506 <c>before</c> or <c>after</c> settings.
507 </p>
508
509 <p>
510 As an example we view the settings of the Portmap service:
511 </p>
512
513 <pre caption="The depend() function in the Portmap service">
514 depend() {
515 need net
516 before inetd
517 before xinetd
518 }
519 </pre>
520
521 <p>
522 You can also use the "*" glob to catch all services in the same runlevel,
523 although this isn't adviseable.
524 </p>
525
526 <pre caption="Running an init script as first script in the runlevel">
527 depend() {
528 before *
529 }
530 </pre>
531
532 </body>
533 </subsection>
534 <subsection>
535 <title>Standard Functions</title>
536 <body>
537
538 <p>
539 Next to the <c>depend()</c> functionality, you also need to define the
540 <c>start()</c> function. This one contains all the commands necessary to
541 initialize your service. It is adviseable to use the <c>ebegin</c> and
542 <c>eend</c> functions to inform the user about what is happening:
543 </p>
544
545 <pre caption="Example start() function">
546 start() {
547 ebegin "Starting my_service"
548 start-stop-daemon --start --quiet --exec /path/to/my_service
549 eend $?
550 }
551 </pre>
552
553 <p>
554 If you need more examples of the <c>start()</c> function, please read the source
555 code of the available init scripts in your <path>/etc/init.d</path> directory.
556 As for <c>start-stop-daemon</c>, there is an excellent man page available if you
557 need more information:
558 </p>
559
560 <pre caption="Getting the man page for start-stop-daemon">
561 # <i>man start-stop-daemon</i>
562 </pre>
563
564 <p>
565 Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are
566 not obliged to define these functions! Our init system is intelligent enough to
567 fill these functions in herself if you use <c>start-stop-daemon</c>.
568 </p>
569
570 </body>
571 </subsection>
572 <subsection>
573 <title>Adding Custom Options</title>
574 <body>
575
576 <p>
577 If you want your init script to support more options than the ones we have
578 already encountered, you should add the option to the <c>opts</c> variable, and
579 create a function with the same name as the option. For instance, to support an
580 option called <c>restartdelay</c>:
581 </p>
582
583 <pre caption="Supporting the restartdelay option">
584 opts="${opts} restartdelay"
585
586 restartdelay() {
587 stop()
588 sleep 3 <comment># Wait 3 seconds before starting again</comment>
589 start()
590 }
591 </pre>
592
593 </body>
594 </subsection>
595 <subsection>
596 <title>Service Configuration Variables</title>
597 <body>
598
599 <p>
600 You don't have to do anything to support a configuration file in
601 <path>/etc/conf.d</path>: if your init script is executed, the following files
602 are automatically sourced (i.e. the variables are available to use):
603 </p>
604
605 <ul>
606 <li><path>/etc/conf.d/&lt;your init script&gt;</path></li>
607 <li><path>/etc/conf.d/basic</path></li>
608 <li><path>/etc/rc.conf</path></li>
609 </ul>
610
611 <p>
612 Also, if your init script provides a virtual dependency (such as <c>net</c>),
613 the file associated with that dependency (such as <path>/etc/conf.d/net</path>)
614 will be sourced too.
615 </p>
616
617 </body>
618 </subsection>
619 </section>
620 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20