/[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.9 - (hide annotations) (download) (as text)
Tue Jan 6 15:28:51 2004 UTC (10 years, 9 months ago) by swift
Branch: MAIN
Changes since 1.8: +2 -2 lines
File MIME type: application/xml
Fix typo, #37391

1 swift 1.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 swift 1.9 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.8 2004/01/06 09:57:49 swift Exp $ -->
5 swift 1.1
6     <sections>
7     <section>
8     <title>Runlevels</title>
9     <subsection>
10 swift 1.4 <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 swift 1.6 kernel. When the kernel is loaded and run, it initializes all kernel-specific
24 swift 1.4 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 swift 1.8 services you need in order to have a successfully booted system.
32 swift 1.4 </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 swift 1.1 <body>
47    
48 swift 1.2 <p>
49 swift 1.4 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 swift 1.7 only the scripts it is told to execute. It decides which scripts to execute by
52 swift 1.4 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 swift 1.7 information in it, in which case the order is changed to provide a valid
69     start-up sequence.
70 swift 1.2 </p>
71    
72     </body>
73     </subsection>
74     <subsection>
75 swift 1.4 <title>How Init Works</title>
76 swift 1.2 <body>
77    
78     <p>
79 swift 1.4 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 swift 1.2 </p>
83    
84 swift 1.4 <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 swift 1.2 si::sysinit:/sbin/rc sysinit
92     </pre>
93    
94     <p>
95 swift 1.4 This line tells <c>init</c> that it must run <c>/sbin/rc sysinit</c> to
96 swift 1.6 initialize the system. The <path>/sbin/rc</path> script takes care of the
97 swift 1.4 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 swift 1.2 </p>
100    
101     <p>
102 swift 1.4 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 swift 1.2 </p>
105    
106 swift 1.4 <pre caption="The system initialisation, continued">
107     rc::bootwait:/sbin/rc boot
108 swift 1.2 </pre>
109    
110     <p>
111 swift 1.4 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 swift 1.2 </p>
115    
116     <p>
117 swift 1.4 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 swift 1.2 </p>
121    
122 swift 1.4 <pre caption="The initdefault line">
123     id:3:initdefault:
124     </pre>
125 swift 1.2
126     <p>
127 swift 1.4 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 swift 1.2 </p>
131    
132 swift 1.4 <pre caption="The runlevel definitions">
133 swift 1.2 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 swift 1.4 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 swift 1.2 </p>
147    
148     <p>
149 swift 1.4 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 swift 1.2 </p>
152    
153 swift 1.4 <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 swift 1.1
163     </body>
164     </subsection>
165     <subsection>
166 swift 1.4 <title>What is a runlevel?</title>
167 swift 1.1 <body>
168    
169 swift 1.2 <p>
170 swift 1.4 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 swift 1.6 initialize the system, powering off the system and rebooting the system.
181 swift 1.4 </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 swift 1.2 </p>
193    
194 swift 1.4 </body>
195     </subsection>
196     <subsection>
197     <title>Working with the Init Scripts</title>
198     <body>
199    
200 swift 1.2 <p>
201 swift 1.4 The scripts that the <c>rc</c> process starts are called <e>init scripts</e>.
202 swift 1.2 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 swift 1.4
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 swift 1.2
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 swift 1.3 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 swift 1.2 </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 swift 1.1
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 swift 1.2 <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 swift 1.1 </body>
304     </subsection>
305     <subsection>
306     <title>Adding and Removing Services</title>
307     <body>
308    
309 swift 1.2 <p>
310     You have already added init scripts to the "default" runlevel during the
311 swift 1.7 installation of Gentoo. At that time you might not have had a clue what the
312 swift 1.2 "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 swift 1.1
334     </body>
335     </subsection>
336     </section>
337     <section>
338     <title>Configuring Services</title>
339     <subsection>
340 swift 1.2 <title>Why the Need for Extra Configuration?</title>
341 swift 1.1 <body>
342    
343 swift 1.2 <p>
344 swift 1.5 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 swift 1.2 </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 swift 1.1 </body>
357     </subsection>
358     <subsection>
359     <title>The /etc/conf.d Directory</title>
360     <body>
361    
362 swift 1.2 <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 swift 1.1 </body>
381     </subsection>
382     </section>
383     <section>
384 swift 1.2 <title>Writing Init Scripts</title>
385 swift 1.1 <subsection>
386     <title>Do I Have To?</title>
387     <body>
388    
389 swift 1.2 <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 swift 1.1 </body>
403     </subsection>
404     <subsection>
405     <title>Layout</title>
406     <body>
407    
408 swift 1.2 <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 swift 1.1 </body>
438     </subsection>
439     <subsection>
440     <title>Dependencies</title>
441     <body>
442    
443 swift 1.2 <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 swift 1.1 </body>
495     </subsection>
496     <subsection>
497     <title>Controlling the Order</title>
498     <body>
499    
500 swift 1.2 <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 swift 1.1
532     </body>
533     </subsection>
534     <subsection>
535     <title>Standard Functions</title>
536     <body>
537    
538 swift 1.2 <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 swift 1.6 initialize your service. It is adviseable to use the <c>ebegin</c> and
542 swift 1.2 <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 swift 1.9 fill these functions by itself if you use <c>start-stop-daemon</c>.
568 swift 1.2 </p>
569    
570 swift 1.1 </body>
571     </subsection>
572     <subsection>
573     <title>Adding Custom Options</title>
574     <body>
575    
576 swift 1.2 <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 swift 1.1 </body>
594     </subsection>
595     <subsection>
596     <title>Service Configuration Variables</title>
597     <body>
598 swift 1.2
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 swift 1.1
617     </body>
618     </subsection>
619     </section>
620     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20