/[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.10 - (show annotations) (download) (as text)
Thu Jan 8 14:23:17 2004 UTC (10 years, 7 months ago) by swift
Branch: MAIN
Changes since 1.9: +4 -1 lines
File MIME type: application/xml
Add necessary xml constructs on top of all hb-files, tx to neysx

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: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.9 2004/01/06 15:28:51 swift 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 beneith <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 explained to you, you will
89 remember that <c>init</c>'s first action is to mount all filesystems. This is
90 defined in 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 but that are
277 missing:
278 </p>
279
280 <pre caption="Requesting a list of missing dependencies for Postfix">
281 # <i>/etc/init.d/postfix broken</i>
282 </pre>
283
284 </body>
285 </subsection>
286 </section>
287 <section>
288 <title>Working with rc-update</title>
289 <subsection>
290 <title>What is rc-update?</title>
291 <body>
292
293 <p>
294 Gentoo's init system uses a dependency-tree to decide what service needs to be
295 started first. As this is a tedious task that we wouldn't want our users to do
296 manually, we have created tools that ease the administration of the runlevels
297 and init scripts.
298 </p>
299
300 <p>
301 With <c>rc-update</c> you can add and remove init scripts to a runlevel. The
302 <c>rc-update</c> tool will then automatically ask the <c>depscan.sh</c> script
303 to rebuild the dependency tree.
304 </p>
305
306 </body>
307 </subsection>
308 <subsection>
309 <title>Adding and Removing Services</title>
310 <body>
311
312 <p>
313 You have already added init scripts to the "default" runlevel during the
314 installation of Gentoo. At that time you might not have had a clue what the
315 "default" is for, but now you should. The <c>rc-update</c> script requires a
316 second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>.
317 </p>
318
319 <p>
320 To add or remove an init script, just give <c>rc-update</c> the <c>add</c> or
321 <c>del</c> argument, followed by the init script and the runlevel. For instance:
322 </p>
323
324 <pre caption="Removing Postfix from the default runlevel">
325 # <i>rc-update del postfix default</i>
326 </pre>
327
328 <p>
329 The <c>rc-update show</c> command will show all the available init scripts and
330 list at which runlevels they will execute:
331 </p>
332
333 <pre caption="Receiving init script information">
334 # <i>rc-update show</i>
335 </pre>
336
337 </body>
338 </subsection>
339 </section>
340 <section>
341 <title>Configuring Services</title>
342 <subsection>
343 <title>Why the Need for Extra Configuration?</title>
344 <body>
345
346 <p>
347 Init scripts can be quite complex. It is therefore not really interesting to
348 have the users directly edit the init script, as it would make it more
349 error-prone. It is however important to be able to configure such a service. For
350 instance, you might want to give more options to the service itself.
351 </p>
352
353 <p>
354 A second reason to have this configuration outside the init script is to be able
355 to update the init scripts without being afraid that your configuration changes
356 are undone.
357 </p>
358
359 </body>
360 </subsection>
361 <subsection>
362 <title>The /etc/conf.d Directory</title>
363 <body>
364
365 <p>
366 Gentoo provides an easy way to configure such a service: every init script that
367 can be configured has a file in <path>/etc/conf.d</path>. For instance, the
368 apache2 initscript (called <path>/etc/init.d/apache2</path>) has a
369 configuration file called <path>/etc/conf.d/apache2</path>, which can contain
370 the options you want to give to the Apache 2 server when it is started:
371 </p>
372
373 <pre caption="Variable defined in /etc/conf.d/apache2">
374 APACHE2_OPTS="-D PHP4"
375 </pre>
376
377 <p>
378 Such a configuration file contains variables and variables alone (just like
379 <path>/etc/make.conf</path>), making it very easy to configure services. It also
380 allows us to provide more information about the variables (as comments).
381 </p>
382
383 </body>
384 </subsection>
385 </section>
386 <section>
387 <title>Writing Init Scripts</title>
388 <subsection>
389 <title>Do I Have To?</title>
390 <body>
391
392 <p>
393 No. Writing an init script is usually not necessary as Gentoo provides
394 ready-to-use init scripts for all provided services. However, you might have
395 installed a service without using Portage, in which case you will most likely
396 have to create an init script.
397 </p>
398
399 <p>
400 Do not use the init script provided by the service if it isn't explicitly
401 written for Gentoo: Gentoo's init scripts are not compatible with the init
402 scripts used by other distributions!
403 </p>
404
405 </body>
406 </subsection>
407 <subsection>
408 <title>Layout</title>
409 <body>
410
411 <p>
412 The basic layout of an init script is shown below.
413 </p>
414
415 <pre caption="Basic layout of an init script">
416 #!/sbin/runscript
417
418 depend() {
419 <comment>(Dependency information)</comment>
420 }
421
422 start() {
423 <comment>(Commands necessary to start the service)</comment>
424 }
425
426 stop() {
427 <comment>(Commands necessary to stop the service)</comment>
428 }
429
430 restart() {
431 <comment>(Commands necessary to restart the service)</comment>
432 }
433 </pre>
434
435 <p>
436 Any init script <e>requires</e> the <c>start()</c> function to be defined. All
437 other sections are optional.
438 </p>
439
440 </body>
441 </subsection>
442 <subsection>
443 <title>Dependencies</title>
444 <body>
445
446 <p>
447 There are two dependencies you can define: <c>use</c> and <c>need</c>. As we
448 have mentioned before, the <c>need</c> dependency is more strict than the
449 <c>use</c> dependency. Following this dependency type you enter the service
450 you depend on, or the <e>virtual</e> dependency.
451 </p>
452
453 <p>
454 A <e>virtual</e> dependency is a dependency that a service provides, but that is
455 not provided solely by that service. Your init script can depend on a system
456 logger, but there are many system loggers available (metalogd, syslog-ng,
457 sysklogd, ...). As you cannot <c>need</c> every single one of them (no sensible
458 system has all these system loggers installed and running) we made sure that
459 all these services <c>provide</c> a virtual dependency.
460 </p>
461
462 <p>
463 Let us take a look at the dependency information for the postfix service.
464 </p>
465
466 <pre caption="Dependency information for Postfix">
467 depend() {
468 need net
469 use logger dns
470 provide mta
471 }
472 </pre>
473
474 <p>
475 As you can see, the postfix service:
476 </p>
477
478 <ul>
479 <li>
480 requires the (virtual) <c>net</c> dependency (which is provided by, for
481 instance, <path>/etc/init.d/net.eth0</path>)
482 </li>
483 <li>
484 uses the (virtual) <c>logger</c> dependency (which is provided by, for
485 instance, <path>/etc/init.d/syslog-ng</path>)
486 </li>
487 <li>
488 uses the (virtual) <c>dns</c> dependency (which is provided by, for
489 instance, <path>/etc/init.d/named</path>)
490 </li>
491 <li>
492 provides the (virtual) <c>mta</c> dependency (which is common for all mail
493 servers)
494 </li>
495 </ul>
496
497 </body>
498 </subsection>
499 <subsection>
500 <title>Controlling the Order</title>
501 <body>
502
503 <p>
504 In some cases you might not require a service, but want your service to be
505 started <c>before</c> (or <c>after</c>) another service <e>if</e> it is
506 available on the system (note the conditional - this is no dependency anymore)
507 <e>and</e> ran in the same runlevel (note the conditional - only services in the
508 same runlevel are involved). You can provide this information using the
509 <c>before</c> or <c>after</c> settings.
510 </p>
511
512 <p>
513 As an example we view the settings of the Portmap service:
514 </p>
515
516 <pre caption="The depend() function in the Portmap service">
517 depend() {
518 need net
519 before inetd
520 before xinetd
521 }
522 </pre>
523
524 <p>
525 You can also use the "*" glob to catch all services in the same runlevel,
526 although this isn't adviseable.
527 </p>
528
529 <pre caption="Running an init script as first script in the runlevel">
530 depend() {
531 before *
532 }
533 </pre>
534
535 </body>
536 </subsection>
537 <subsection>
538 <title>Standard Functions</title>
539 <body>
540
541 <p>
542 Next to the <c>depend()</c> functionality, you also need to define the
543 <c>start()</c> function. This one contains all the commands necessary to
544 initialize your service. It is adviseable to use the <c>ebegin</c> and
545 <c>eend</c> functions to inform the user about what is happening:
546 </p>
547
548 <pre caption="Example start() function">
549 start() {
550 ebegin "Starting my_service"
551 start-stop-daemon --start --quiet --exec /path/to/my_service
552 eend $?
553 }
554 </pre>
555
556 <p>
557 If you need more examples of the <c>start()</c> function, please read the source
558 code of the available init scripts in your <path>/etc/init.d</path> directory.
559 As for <c>start-stop-daemon</c>, there is an excellent man page available if you
560 need more information:
561 </p>
562
563 <pre caption="Getting the man page for start-stop-daemon">
564 # <i>man start-stop-daemon</i>
565 </pre>
566
567 <p>
568 Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are
569 not obliged to define these functions! Our init system is intelligent enough to
570 fill these functions by itself if you use <c>start-stop-daemon</c>.
571 </p>
572
573 </body>
574 </subsection>
575 <subsection>
576 <title>Adding Custom Options</title>
577 <body>
578
579 <p>
580 If you want your init script to support more options than the ones we have
581 already encountered, you should add the option to the <c>opts</c> variable, and
582 create a function with the same name as the option. For instance, to support an
583 option called <c>restartdelay</c>:
584 </p>
585
586 <pre caption="Supporting the restartdelay option">
587 opts="${opts} restartdelay"
588
589 restartdelay() {
590 stop()
591 sleep 3 <comment># Wait 3 seconds before starting again</comment>
592 start()
593 }
594 </pre>
595
596 </body>
597 </subsection>
598 <subsection>
599 <title>Service Configuration Variables</title>
600 <body>
601
602 <p>
603 You don't have to do anything to support a configuration file in
604 <path>/etc/conf.d</path>: if your init script is executed, the following files
605 are automatically sourced (i.e. the variables are available to use):
606 </p>
607
608 <ul>
609 <li><path>/etc/conf.d/&lt;your init script&gt;</path></li>
610 <li><path>/etc/conf.d/basic</path></li>
611 <li><path>/etc/rc.conf</path></li>
612 </ul>
613
614 <p>
615 Also, if your init script provides a virtual dependency (such as <c>net</c>),
616 the file associated with that dependency (such as <path>/etc/conf.d/net</path>)
617 will be sourced too.
618 </p>
619
620 </body>
621 </subsection>
622 </section>
623 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20