/[gentoo]/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml
Gentoo

Diff of /xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

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

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

  ViewVC Help
Powered by ViewVC 1.1.20