/[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.2 - (hide annotations) (download) (as text)
Tue Dec 2 19:33:12 2003 UTC (10 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.1: +449 -24 lines
File MIME type: application/xml
Finished draft

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.2 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.1 2003/11/20 10:52:35 swift Exp $ -->
5 swift 1.1
6     <sections>
7     <section>
8     <title>Runlevels</title>
9     <subsection>
10     <title>What is a runlevel?</title>
11     <body>
12    
13 swift 1.2 <p>
14     When you boot your system, a number of tasks need to be performed before you are
15     able to log on. This "normal" boot operation is fully defined -- it will be the
16     same every time you restart your system. A <e>runlevel</e> is a state in which
17     your system is running and contains a collection of scripts (runlevel scripts or
18     <e>initscripts</e>) that must be executed when you enter or leave a runlevel.
19     </p>
20    
21     </body>
22     </subsection>
23     <subsection>
24     <title>Booting your System</title>
25     <body>
26    
27     <p>
28     The process that takes care of the runlevels is called <c>init</c> and is also
29     the first process started by the Linux kernel. <c>init</c>'s configuration file
30     is called <path>/etc/inittab</path> and gets read immediately after <c>init</c>
31     is started. In this configuration file, the commands used to enter a certain
32     runlevel are listed. For instance, after initialising the system (<e>si</e>),
33     the <b>boot</b> runlevel is started:
34     </p>
35    
36     <pre caption="System initialisation lines in /etc/inittab">
37     si::sysinit:/sbin/rc sysinit
38     rc::bootwait:/sbin/rc boot
39     </pre>
40    
41     <p>
42     As you can see, <c>init</c> relies on the <c>rc</c> script. When started with
43     the "boot" argument, <c>rc</c> starts all scripts in the
44     <path>/etc/runlevels/boot</path> directory. Don't think about the sequence used
45     to start the scripts -- we will explain later how Gentoo uses dependencies for
46     the init scripts.
47     </p>
48    
49     <p>
50     When the <b>boot</b> runlevel is completed (the boot runlevel is an intermediate
51     one), <c>init</c> checks what runlevel it should start. If you have not defined
52     one as kernel parameter, it will use the one defined in
53     <path>/etc/inittab</path>:
54     </p>
55    
56     <pre caption="Default runlevel">
57     id:3:initdefault:
58     </pre>
59    
60     <p>
61     In this case, the runlevel id is "3", and gets mapped to:
62     </p>
63    
64     <pre caption="Mapping from number to readable commands in /etc/inittab">
65     l3:3:wait:/sbin/rc default
66     </pre>
67    
68     <p>
69     In other words, the <c>rc</c> script is asked to activate the <b>default</b>
70     runlevel. Again, this results in executing all
71     <path>/etc/runlevels/default</path> scripts.
72     </p>
73    
74     </body>
75     </subsection>
76     <subsection>
77     <title>Numbers and Names</title>
78     <body>
79    
80     <p>
81     When you take a look at <path>/etc/inittab</path>, you will see the following
82     section:
83     </p>
84    
85     <pre caption="Defining the runlevels in /etc/inittab">
86     l0:0:wait:/sbin/rc shutdown
87     l1:S1:wait:/sbin/rc single
88     l2:2:wait:/sbin/rc nonetwork
89     l3:3:wait:/sbin/rc default
90     l4:4:wait:/sbin/rc default
91     l5:5:wait:/sbin/rc default
92     l6:6:wait:/sbin/rc reboot
93     </pre>
94    
95     <p>
96     As you can see, there is a mapping of numbers to names (not vice versa). For
97     instance, 0 maps to "shutdown", 1 to "single" etc. Vice versa is not true, as
98     "default" is used by 3, 4 and 5. These numbers are the runlevel numbers. Most
99     distributions work with the numbers; Gentoo however decided to make it a bit
100     more userfriendly and continue with the naming.
101     </p>
102    
103     <p>
104     As you can see from the listings, Gentoo defines 7 runlevels. Three of them are
105     internal runlevels: <e>sysinit</e>, <e>shutdown</e> and <e>reboot</e>. The
106     <b>sysinit</b> runlevel mounts all necessary filesystems as defined in
107     <path>/etc/fstab</path>. The <b>shutdown</b> runlevel shuts down all running
108     services and powers down the system. The <b>reboot</b> runlevel acts like the
109     <e>shutdown</e> runlevel, but reboots the system instead of powering down.
110     </p>
111    
112     <p>
113     The other four runlevels are <e>boot</e>, <e>default</e>, <e>nonetwork</e> and
114     <e>single</e>. Each of them has a subdirectory in <path>/etc/runlevels</path>
115     containing scripts that need to be started when the runlevel is activated.
116     </p>
117 swift 1.1
118     </body>
119     </subsection>
120     <subsection>
121 swift 1.2 <title>Working with the initscripts</title>
122 swift 1.1 <body>
123    
124 swift 1.2 <p>
125     If you take a closer look to <path>/etc/runlevels/default</path>, you will
126     notice that it contains symbolic links to identically named scripts located in
127     <path>/etc/init.d</path> and not just scripts as we mentioned previously. For
128     instance, <path>/etc/runlevels/default/postfix</path> is a symbolic link to
129     <path>/etc/init.d/postfix</path>. In general we can say that such a script
130     provides a service...
131     </p>
132    
133     <p>
134     Each script in <path>/etc/init.d</path> can be executed with the arguments
135     <e>start</e>, <e>stop</e>, <e>restart</e>, <e>pause</e>, <e>zap</e>,
136     <e>status</e>, <e>ineed</e>, <e>iuse</e>, <e>needsme</e>, <e>usesme</e> or
137     <e>broken</e>.
138     </p>
139    
140     <p>
141     To start, stop or restart a service (and all depending services), <c>start</c>,
142     <c>stop</c> and <c>restart</c> should be used:
143     </p>
144    
145     <pre caption="Starting Postfix">
146     # <i>/etc/init.d/postfix start</i>
147     </pre>
148    
149     <p>
150     If you want to stop a service, but not the services that depend on it, you can
151     use the <c>pause</c> argument:
152     </p>
153    
154     <pre caption="Stopping Postfix but keep the depending services running">
155     # <i>/etc/init.d/postfix pause</i>
156     </pre>
157    
158     <p>
159     If you want to see what status a service has (started, stopped, paused, ...) you
160     can use the <c>status</c> argument:
161     </p>
162    
163     <pre caption="Status information for postfix">
164     # <i>/etc/init.d/postfix status</i>
165     </pre>
166    
167     <p>
168     If the status information tells you that the service is running, but it doesn't,
169     then you can reset the status information to "stopped" with the <c>zap</c>
170     argument:
171     </p>
172    
173     <pre caption="Resetting status information for postfix">
174     # <i>/etc/init.d/postfix zap</i>
175     </pre>
176    
177     <p>
178     To also ask what dependencies the service has, you can use <c>iuse</c> or
179     <c>ineed</c>. With <c>ineed</c> you can see the services that are really
180     necessary for the correct functioning of the service. <c>iuse</c> on the other
181     hand shows the services that can be used by the service, but are not necessary
182     for the correct functioning.
183     </p>
184    
185     <pre caption="Requesting a list of all necessary services on which Postfix depends">
186     # <i>/etc/init.d/postfix ineed</i>
187     </pre>
188    
189     <p>
190     Similarly, you can ask what services require the service (<c>needsme</c>) or can
191     use it (<c>usesme</c>):
192     </p>
193    
194     <pre caption="Requesting a list of all services that require Postfix">
195     # <i>/etc/init.d/postfix needsme</i>
196     </pre>
197    
198     <p>
199     Finally, you can ask what dependencies the service requires but that are
200     missing:
201     </p>
202    
203     <pre caption="Requesting a list of missing dependencies for Postfix">
204     # <i>/etc/init.d/postfix broken</i>
205     </pre>
206 swift 1.1
207     </body>
208     </subsection>
209     </section>
210     <section>
211     <title>Working with rc-update</title>
212     <subsection>
213     <title>What is rc-update?</title>
214     <body>
215    
216 swift 1.2 <p>
217     Gentoo's init system uses a dependency-tree to decide what service needs to be
218     started first. As this is a tedious task that we wouldn't want our users to do
219     manually, we have created tools that ease the administration of the runlevels
220     and init scripts.
221     </p>
222    
223     <p>
224     With <c>rc-update</c> you can add and remove init scripts to a runlevel. The
225     <c>rc-update</c> tool will then automatically ask the <c>depscan.sh</c> script
226     to rebuild the dependency tree.
227     </p>
228    
229 swift 1.1 </body>
230     </subsection>
231     <subsection>
232     <title>Adding and Removing Services</title>
233     <body>
234    
235 swift 1.2 <p>
236     You have already added init scripts to the "default" runlevel during the
237     installation of Gentoo. At that time you might not had a clue what the
238     "default" is for, but now you should. The <c>rc-update</c> script requires a
239     second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>.
240     </p>
241    
242     <p>
243     To add or remove an init script, just give <c>rc-update</c> the <c>add</c> or
244     <c>del</c> argument, followed by the init script and the runlevel. For instance:
245     </p>
246    
247     <pre caption="Removing Postfix from the default runlevel">
248     # <i>rc-update del postfix default</i>
249     </pre>
250    
251     <p>
252     The <c>rc-update show</c> command will show all the available init scripts and
253     list at which runlevels they will execute:
254     </p>
255    
256     <pre caption="Receiving init script information">
257     # <i>rc-update show</i>
258     </pre>
259 swift 1.1
260     </body>
261     </subsection>
262     </section>
263     <section>
264     <title>Configuring Services</title>
265     <subsection>
266 swift 1.2 <title>Why the Need for Extra Configuration?</title>
267 swift 1.1 <body>
268    
269 swift 1.2 <p>
270     Init scripts can be quite complex. It is therefor not really interesting to have
271     the users directly edit the init script, as it would make it more error-prone.
272     It is however important to be able to configure such a service. For instance,
273     you might want to give more options to the service itself.
274     </p>
275    
276     <p>
277     A second reason to have this configuration outside the init script is to be able
278     to update the init scripts without being afraid that your configuration changes
279     are undone.
280     </p>
281    
282 swift 1.1 </body>
283     </subsection>
284     <subsection>
285     <title>The /etc/conf.d Directory</title>
286     <body>
287    
288 swift 1.2 <p>
289     Gentoo provides an easy way to configure such a service: every init script that
290     can be configured has a file in <path>/etc/conf.d</path>. For instance, the
291     apache2 initscript (called <path>/etc/init.d/apache2</path>) has a
292     configuration file called <path>/etc/conf.d/apache2</path>, which can contain
293     the options you want to give to the Apache 2 server when it is started:
294     </p>
295    
296     <pre caption="Variable defined in /etc/conf.d/apache2">
297     APACHE2_OPTS="-D PHP4"
298     </pre>
299    
300     <p>
301     Such a configuration file contains variables and variables alone (just like
302     <path>/etc/make.conf</path>), making it very easy to configure services. It also
303     allows us to provide more information about the variables (as comments).
304     </p>
305    
306 swift 1.1 </body>
307     </subsection>
308     </section>
309     <section>
310 swift 1.2 <title>Writing Init Scripts</title>
311 swift 1.1 <subsection>
312     <title>Do I Have To?</title>
313     <body>
314    
315 swift 1.2 <p>
316     No. Writing an init script is usually not necessary as Gentoo provides
317     ready-to-use init scripts for all provided services. However, you might have
318     installed a service without using Portage, in which case you will most likely
319     have to create an init script.
320     </p>
321    
322     <p>
323     Do not use the init script provided by the service if it isn't explicitly
324     written for Gentoo: Gentoo's init scripts are not compatible with the init
325     scripts used by other distributions!
326     </p>
327    
328 swift 1.1 </body>
329     </subsection>
330     <subsection>
331     <title>Layout</title>
332     <body>
333    
334 swift 1.2 <p>
335     The basic layout of an init script is shown below.
336     </p>
337    
338     <pre caption="Basic layout of an init script">
339     #!/sbin/runscript
340    
341     depend() {
342     <comment>(Dependency information)</comment>
343     }
344    
345     start() {
346     <comment>(Commands necessary to start the service)</comment>
347     }
348    
349     stop() {
350     <comment>(Commands necessary to stop the service)</comment>
351     }
352    
353     restart() {
354     <comment>(Commands necessary to restart the service)</comment>
355     }
356     </pre>
357    
358     <p>
359     Any init script <e>requires</e> the <c>start()</c> function to be defined. All
360     other sections are optional.
361     </p>
362    
363 swift 1.1 </body>
364     </subsection>
365     <subsection>
366     <title>Dependencies</title>
367     <body>
368    
369 swift 1.2 <p>
370     There are two dependencies you can define: <c>use</c> and <c>need</c>. As we
371     have mentioned before, the <c>need</c> dependency is more strict than the
372     <c>use</c> dependency. Following this dependency type you enter the service
373     you depend on, or the <e>virtual</e> dependency.
374     </p>
375    
376     <p>
377     A <e>virtual</e> dependency is a dependency that a service provides, but that is
378     not provided solely by that service. Your init script can depend on a system
379     logger, but there are many system loggers available (metalogd, syslog-ng,
380     sysklogd, ...). As you cannot <c>need</c> every single one of them (no sensible
381     system has all these system loggers installed and running) we made sure that
382     all these services <c>provide</c> a virtual dependency.
383     </p>
384    
385     <p>
386     Let us take a look at the dependency information for the postfix service.
387     </p>
388    
389     <pre caption="Dependency information for Postfix">
390     depend() {
391     need net
392     use logger dns
393     provide mta
394     }
395     </pre>
396    
397     <p>
398     As you can see, the postfix service:
399     </p>
400    
401     <ul>
402     <li>
403     requires the (virtual) <c>net</c> dependency (which is provided by, for
404     instance, <path>/etc/init.d/net.eth0</path>)
405     </li>
406     <li>
407     uses the (virtual) <c>logger</c> dependency (which is provided by, for
408     instance, <path>/etc/init.d/syslog-ng</path>)
409     </li>
410     <li>
411     uses the (virtual) <c>dns</c> dependency (which is provided by, for
412     instance, <path>/etc/init.d/named</path>)
413     </li>
414     <li>
415     provides the (virtual) <c>mta</c> dependency (which is common for all mail
416     servers)
417     </li>
418     </ul>
419    
420 swift 1.1 </body>
421     </subsection>
422     <subsection>
423     <title>Controlling the Order</title>
424     <body>
425    
426 swift 1.2 <p>
427     In some cases you might not require a service, but want your service to be
428     started <c>before</c> (or <c>after</c>) another service <e>if</e> it is
429     available on the system (note the conditional - this is no dependency anymore)
430     <e>and</e> ran in the same runlevel (note the conditional - only services in the
431     same runlevel are involved). You can provide this information using the
432     <c>before</c> or <c>after</c> settings.
433     </p>
434    
435     <p>
436     As an example we view the settings of the Portmap service:
437     </p>
438    
439     <pre caption="The depend() function in the Portmap service">
440     depend() {
441     need net
442     before inetd
443     before xinetd
444     }
445     </pre>
446    
447     <p>
448     You can also use the "*" glob to catch all services in the same runlevel,
449     although this isn't adviseable.
450     </p>
451    
452     <pre caption="Running an init script as first script in the runlevel">
453     depend() {
454     before *
455     }
456     </pre>
457 swift 1.1
458     </body>
459     </subsection>
460     <subsection>
461     <title>Standard Functions</title>
462     <body>
463    
464 swift 1.2 <p>
465     Next to the <c>depend()</c> functionality, you also need to define the
466     <c>start()</c> function. This one contains all the commands necessary to
467     initialise your service. It is adviseable to use the <c>ebegin</c> and
468     <c>eend</c> functions to inform the user about what is happening:
469     </p>
470    
471     <pre caption="Example start() function">
472     start() {
473     ebegin "Starting my_service"
474     start-stop-daemon --start --quiet --exec /path/to/my_service
475     eend $?
476     }
477     </pre>
478    
479     <p>
480     If you need more examples of the <c>start()</c> function, please read the source
481     code of the available init scripts in your <path>/etc/init.d</path> directory.
482     As for <c>start-stop-daemon</c>, there is an excellent man page available if you
483     need more information:
484     </p>
485    
486     <pre caption="Getting the man page for start-stop-daemon">
487     # <i>man start-stop-daemon</i>
488     </pre>
489    
490     <p>
491     Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are
492     not obliged to define these functions! Our init system is intelligent enough to
493     fill these functions in herself if you use <c>start-stop-daemon</c>.
494     </p>
495    
496 swift 1.1 </body>
497     </subsection>
498     <subsection>
499     <title>Adding Custom Options</title>
500     <body>
501    
502 swift 1.2 <p>
503     If you want your init script to support more options than the ones we have
504     already encountered, you should add the option to the <c>opts</c> variable, and
505     create a function with the same name as the option. For instance, to support an
506     option called <c>restartdelay</c>:
507     </p>
508    
509     <pre caption="Supporting the restartdelay option">
510     opts="${opts} restartdelay"
511    
512     restartdelay() {
513     stop()
514     sleep 3 <comment># Wait 3 seconds before starting again</comment>
515     start()
516     }
517     </pre>
518    
519 swift 1.1 </body>
520     </subsection>
521     <subsection>
522     <title>Service Configuration Variables</title>
523     <body>
524 swift 1.2
525     <p>
526     You don't have to do anything to support a configuration file in
527     <path>/etc/conf.d</path>: if your init script is executed, the following files
528     are automatically sourced (i.e. the variables are available to use):
529     </p>
530    
531     <ul>
532     <li><path>/etc/conf.d/&lt;your init script&gt;</path></li>
533     <li><path>/etc/conf.d/basic</path></li>
534     <li><path>/etc/rc.conf</path></li>
535     </ul>
536    
537     <p>
538     Also, if your init script provides a virtual dependency (such as <c>net</c>),
539     the file associated with that dependency (such as <path>/etc/conf.d/net</path>)
540     will be sourced too.
541     </p>
542 swift 1.1
543     </body>
544     </subsection>
545     </section>
546     </sections>

  ViewVC Help
Powered by ViewVC 1.1.20