/[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.24 - (show annotations) (download) (as text)
Sun May 29 16:06:04 2005 UTC (9 years, 7 months ago) by swift
Branch: MAIN
Changes since 1.23: +5 -5 lines
File MIME type: application/xml
#94317 - Fix illegal syntaxis for init scripts (patch by curtis119)

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

  ViewVC Help
Powered by ViewVC 1.1.20