/[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.17 - (show annotations) (download) (as text)
Sat Oct 23 11:02:06 2004 UTC (9 years, 8 months ago) by swift
Branch: MAIN
Changes since 1.16: +2 -2 lines
File MIME type: application/xml
Fix english grammer issues

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

  ViewVC Help
Powered by ViewVC 1.1.20