/[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.3 Revision 1.18
1<?xml version='1.0' encoding='UTF-8'?>
2<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
1<!-- The content of this document is licensed under the CC-BY-SA license --> 4<!-- The content of this document is licensed under the CC-BY-SA license -->
2<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> 5<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
3 6
4<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.3 2003/12/03 13:42:05 swift Exp $ --> 7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.18 2004/11/09 13:01:52 swift Exp $ -->
5 8
6<sections> 9<sections>
10
11<version>1.17</version>
12<date>October 23, 2004</date>
13
7<section> 14<section>
8<title>Runlevels</title> 15<title>Runlevels</title>
9<subsection> 16<subsection>
10<title>What is a runlevel?</title>
11<body>
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
21</body>
22</subsection>
23<subsection>
24<title>Booting your System</title> 17<title>Booting your System</title>
25<body> 18<body>
26 19
27<p> 20<p>
28The process that takes care of the runlevels is called <c>init</c> and is also 21When you boot your system, you will notice lots of text floating by. If you pay
29the first process started by the Linux kernel. <c>init</c>'s configuration file 22close attention, you will notice this text is the same every time you reboot
30is called <path>/etc/inittab</path> and gets read immediately after <c>init</c> 23your system. The sequence of all these actions is called the <e>boot
31is started. In this configuration file, the commands used to enter a certain 24sequence</e> and is (more or less) statically defined.
32runlevel are listed. For instance, after initialising the system (<e>si</e>), 25</p>
33the <b>boot</b> runlevel is started: 26
34</p> 27<p>
28First, your boot loader will load the kernel image you have defined in the
29boot loader configuration into memory after which it tells the CPU to run the
30kernel. When the kernel is loaded and run, it initializes all kernel-specific
31structures and tasks and starts the <c>init</c> process.
32</p>
35 33
34<p>
35This process then makes sure that all filesystems (defined in
36<path>/etc/fstab</path>) are mounted and ready to be used. Then it executes
37several scripts located in <path>/etc/init.d</path>, which will start the
38services you need in order to have a successfully booted system.
39</p>
40
41<p>
42Finally, 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.
45This process will then make sure you are able to log on through these terminals
46by running <c>login</c>.
47</p>
48
49</body>
50</subsection>
51<subsection>
52<title>Init Scripts</title>
53<body>
54
55<p>
56Now <c>init</c> doesn't just execute the scripts in <path>/etc/init.d</path>
57randomly. Even more, it doesn't run all scripts in <path>/etc/init.d</path>,
58only the scripts it is told to execute. It decides which scripts to execute by
59looking into <path>/etc/runlevels</path>.
60</p>
61
62<p>
63First, <c>init</c> runs all scripts from <path>/etc/init.d</path> that have
64symbolic links inside <path>/etc/runlevels/boot</path>. Usually, it will
65start the scripts in alphabetical order, but some scripts have dependency
66information in them, telling the system that another script must be run before
67they can be started.
68</p>
69
70<p>
71When 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
73in <path>/etc/runlevels/default</path>. Again, it will use the alphabetical
74order to decide what script to run first, unless a script has dependency
75information in it, in which case the order is changed to provide a valid
76start-up sequence.
77</p>
78
79</body>
80</subsection>
81<subsection>
82<title>How Init Works</title>
83<body>
84
85<p>
86Of course <c>init</c> doesn't decide all that by itself. It needs a
87configuration file that specifies what actions need to be taken. This
88configuration file is <path>/etc/inittab</path>.
89</p>
90
91<p>
92If you remember the boot sequence we have just described, you will remember
93that <c>init</c>'s first action is to mount all filesystems. This is defined in
94the following line from <path>/etc/inittab</path>:
95</p>
96
36<pre caption="System initialisation lines in /etc/inittab"> 97<pre caption="The system initialisation line in /etc/inittab">
37si::sysinit:/sbin/rc sysinit 98si::sysinit:/sbin/rc sysinit
99</pre>
100
101<p>
102This line tells <c>init</c> that it must run <c>/sbin/rc sysinit</c> to
103initialize the system. The <path>/sbin/rc</path> script takes care of the
104initialisation, so you might say that <c>init</c> doesn't do much -- it
105delegates the task of initialising the system to another process.
106</p>
107
108<p>
109Second, <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">
38rc::bootwait:/sbin/rc boot 114rc::bootwait:/sbin/rc boot
39</pre> 115</pre>
40 116
41<p> 117<p>
42As you can see, <c>init</c> relies on the <c>rc</c> script. When started with 118Again the <c>rc</c> script performs the necessary tasks. Note that the option
43the "boot" argument, <c>rc</c> starts all scripts in the 119given to <c>rc</c> (<e>boot</e>) is the same as the subdirectory of
44<path>/etc/runlevels/boot</path> directory. Don't think about the sequence used 120<path>/etc/runlevels</path> that is used.
45to start the scripts -- we will explain later how Gentoo uses dependencies for
46the init scripts.
47</p>
48
49<p> 121</p>
50When the <b>boot</b> runlevel is completed (the boot runlevel is an intermediate 122
51one), <c>init</c> checks what runlevel it should start. If you have not defined 123<p>
52one as kernel parameter, it will use the one defined in 124Now <c>init</c> checks its configuration file to see what <e>runlevel</e> it
125should run. To decide this, it reads the following line from
53<path>/etc/inittab</path>: 126<path>/etc/inittab</path>:
54</p> 127</p>
55 128
56<pre caption="Default runlevel"> 129<pre caption="The initdefault line">
57id:3:initdefault: 130id:3:initdefault:
58</pre> 131</pre>
59 132
60<p> 133<p>
61In this case, the runlevel id is "3", and gets mapped to: 134In this case (which the majority of Gentoo users will use), the <e>runlevel</e>
62</p> 135id is 3. Using this information, <c>init</c> checks what it must run to start
63 136<e>runlevel 3</e>:
64<pre caption="Mapping from number to readable commands in /etc/inittab">
65l3:3:wait:/sbin/rc default
66</pre>
67
68<p> 137</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 138
74</body> 139<pre caption="The runlevel definitions">
75</subsection>
76<subsection>
77<title>Numbers and Names</title>
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 140l0:0:wait:/sbin/rc shutdown
87l1:S1:wait:/sbin/rc single 141l1:S1:wait:/sbin/rc single
88l2:2:wait:/sbin/rc nonetwork 142l2:2:wait:/sbin/rc nonetwork
89l3:3:wait:/sbin/rc default 143l3:3:wait:/sbin/rc default
90l4:4:wait:/sbin/rc default 144l4:4:wait:/sbin/rc default
91l5:5:wait:/sbin/rc default 145l5:5:wait:/sbin/rc default
92l6:6:wait:/sbin/rc reboot 146l6:6:wait:/sbin/rc reboot
93</pre> 147</pre>
94 148
95<p> 149<p>
96As you can see, there is a mapping of numbers to names (not vice versa). For 150The line that defines level 3, again, uses the <c>rc</c> script to start the
97instance, 0 maps to "shutdown", 1 to "single" etc. Vice versa is not true, as 151services (now with argument <e>default</e>). Again note that the argument of
98"default" is used by 3, 4 and 5. These numbers are the runlevel numbers. Most 152<c>rc</c> is the same as the subdirectory from <path>/etc/runlevels</path>.
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> 153</p>
104As you can see from the listings, Gentoo defines 7 runlevels. Three of them are 154
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> 155<p>
111 156When <c>rc</c> has finished, <c>init</c> decides what virtual consoles it should
157activate and what commands need to be run at each console:
112<p> 158</p>
113The other four runlevels are <e>boot</e>, <e>default</e>, <e>nonetwork</e> and 159
114<e>single</e>. Each of them has a subdirectory in <path>/etc/runlevels</path> 160<pre caption="The virtual consoles definition">
115containing scripts that need to be started when the runlevel is activated. 161c1:12345:respawn:/sbin/agetty 38400 tty1 linux
162c2:12345:respawn:/sbin/agetty 38400 tty2 linux
163c3:12345:respawn:/sbin/agetty 38400 tty3 linux
164c4:12345:respawn:/sbin/agetty 38400 tty4 linux
165c5:12345:respawn:/sbin/agetty 38400 tty5 linux
166c6:12345:respawn:/sbin/agetty 38400 tty6 linux
116</p> 167</pre>
117 168
169
118</body> 170</body>
119</subsection>
120<subsection> 171</subsection>
172<subsection>
173<title>What is a runlevel?</title>
174<body>
175
176<p>
177You 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
179your 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>
184In Gentoo, there are seven runlevels defined: three internal runlevels, and four
185user-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:
187initialize the system, powering off the system and rebooting the system.
188</p>
189
190<p>
191The 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
195runlevels 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>
197is used in case no network connectivity is required, and <path>single</path> is
198used when you need to fix the system.
199</p>
200
201</body>
202</subsection>
203<subsection>
121<title>Working with the initscripts</title> 204<title>Working with the Init Scripts</title>
122<body> 205<body>
123 206
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> 207<p>
132 208The scripts that the <c>rc</c> process starts are called <e>init scripts</e>.
133<p>
134Each script in <path>/etc/init.d</path> can be executed with the arguments 209Each 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>, 210<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 211<e>status</e>, <e>ineed</e>, <e>iuse</e>, <e>needsme</e>, <e>usesme</e> or
137<e>broken</e>. 212<e>broken</e>.
138</p> 213</p>
143</p> 218</p>
144 219
145<pre caption="Starting Postfix"> 220<pre caption="Starting Postfix">
146# <i>/etc/init.d/postfix start</i> 221# <i>/etc/init.d/postfix start</i>
147</pre> 222</pre>
223
224<note>
225Only the services that <e>need</e> the given service are stopped or restarted.
226The other depending services (those that <e>use</e> the service but don't need
227it) are left untouched.
228</note>
148 229
149<p> 230<p>
150If you want to stop a service, but not the services that depend on it, you can 231If you want to stop a service, but not the services that depend on it, you can
151use the <c>pause</c> argument: 232use the <c>pause</c> argument:
152</p> 233</p>
194<pre caption="Requesting a list of all services that require Postfix"> 275<pre caption="Requesting a list of all services that require Postfix">
195# <i>/etc/init.d/postfix needsme</i> 276# <i>/etc/init.d/postfix needsme</i>
196</pre> 277</pre>
197 278
198<p> 279<p>
199Finally, you can ask what dependencies the service requires but that are 280Finally, you can ask what dependencies the service requires that are missing:
200missing:
201</p> 281</p>
202 282
203<pre caption="Requesting a list of missing dependencies for Postfix"> 283<pre caption="Requesting a list of missing dependencies for Postfix">
204# <i>/etc/init.d/postfix broken</i> 284# <i>/etc/init.d/postfix broken</i>
205</pre> 285</pre>
213<title>What is rc-update?</title> 293<title>What is rc-update?</title>
214<body> 294<body>
215 295
216<p> 296<p>
217Gentoo's init system uses a dependency-tree to decide what service needs to be 297Gentoo'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 298started first. As this is a tedious task that we wouldn't want our users to
219manually, we have created tools that ease the administration of the runlevels 299have to do manually, we have created tools that ease the administration of the
220and init scripts. 300runlevels and init scripts.
221</p> 301</p>
222 302
223<p> 303<p>
224With <c>rc-update</c> you can add and remove init scripts to a runlevel. The 304With <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 305<c>rc-update</c> tool will then automatically ask the <c>depscan.sh</c> script
232<title>Adding and Removing Services</title> 312<title>Adding and Removing Services</title>
233<body> 313<body>
234 314
235<p> 315<p>
236You have already added init scripts to the "default" runlevel during the 316You have already added init scripts to the "default" runlevel during the
237installation of Gentoo. At that time you might not had a clue what the 317installation of Gentoo. At that time you might not have had a clue what the
238"default" is for, but now you should. The <c>rc-update</c> script requires a 318"default" is for, but now you should. The <c>rc-update</c> script requires a
239second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>. 319second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>.
240</p> 320</p>
241 321
242<p> 322<p>
265<subsection> 345<subsection>
266<title>Why the Need for Extra Configuration?</title> 346<title>Why the Need for Extra Configuration?</title>
267<body> 347<body>
268 348
269<p> 349<p>
270Init scripts can be quite complex. It is therefor not really interesting to have 350Init scripts can be quite complex. It is therefore not really desirable to
271the users directly edit the init script, as it would make it more error-prone. 351have the users edit the init script directly, as it would make it more
272It is however important to be able to configure such a service. For instance, 352error-prone. It is however important to be able to configure such a service. For
273you might want to give more options to the service itself. 353instance, you might want to give more options to the service itself.
274</p>
275
276<p> 354</p>
355
356<p>
277A second reason to have this configuration outside the init script is to be able 357A second reason to have this configuration outside the init script is to be
278to update the init scripts without being afraid that your configuration changes 358able to update the init scripts without the fear that your configuration
279are undone. 359changes will be undone.
280</p> 360</p>
281 361
282</body> 362</body>
283</subsection> 363</subsection>
284<subsection> 364<subsection>
311<subsection> 391<subsection>
312<title>Do I Have To?</title> 392<title>Do I Have To?</title>
313<body> 393<body>
314 394
315<p> 395<p>
316No. Writing an init script is usually not necessary as Gentoo provides 396No, writing an init script is usually not necessary as Gentoo provides
317ready-to-use init scripts for all provided services. However, you might have 397ready-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 398installed a service without using Portage, in which case you will most likely
319have to create an init script. 399have to create an init script.
320</p> 400</p>
321 401
425 505
426<p> 506<p>
427In some cases you might not require a service, but want your service to be 507In some cases you might not require a service, but want your service to be
428started <c>before</c> (or <c>after</c>) another service <e>if</e> it is 508started <c>before</c> (or <c>after</c>) another service <e>if</e> it is
429available on the system (note the conditional - this is no dependency anymore) 509available 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 510<e>and</e> run in the same runlevel (note the conditional - only services in the
431same runlevel are involved). You can provide this information using the 511same runlevel are involved). You can provide this information using the
432<c>before</c> or <c>after</c> settings. 512<c>before</c> or <c>after</c> settings.
433</p> 513</p>
434 514
435<p> 515<p>
444} 524}
445</pre> 525</pre>
446 526
447<p> 527<p>
448You can also use the "*" glob to catch all services in the same runlevel, 528You can also use the "*" glob to catch all services in the same runlevel,
449although this isn't adviseable. 529although this isn't advisable.
450</p> 530</p>
451 531
452<pre caption="Running an init script as first script in the runlevel"> 532<pre caption="Running an init script as first script in the runlevel">
453depend() { 533depend() {
454 before * 534 before *
462<body> 542<body>
463 543
464<p> 544<p>
465Next to the <c>depend()</c> functionality, you also need to define the 545Next 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 546<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 547initialize your service. It is advisable to use the <c>ebegin</c> and
468<c>eend</c> functions to inform the user about what is happening: 548<c>eend</c> functions to inform the user about what is happening:
469</p> 549</p>
470 550
471<pre caption="Example start() function"> 551<pre caption="Example start() function">
472start() { 552start() {
488</pre> 568</pre>
489 569
490<p> 570<p>
491Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are 571Other 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 572not 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>. 573fill these functions by itself if you use <c>start-stop-daemon</c>.
494</p> 574</p>
495 575
496</body> 576</body>
497</subsection> 577</subsection>
498<subsection> 578<subsection>
541</p> 621</p>
542 622
543</body> 623</body>
544</subsection> 624</subsection>
545</section> 625</section>
626<section>
627<title>Changing the Runlevel Behaviour</title>
628<subsection>
629<title>Who might benefit from this?</title>
630<body>
631
632<p>
633Many laptop users know the situation: at home you need to start <c>net.eth0</c>
634while you don't want to start <c>net.eth0</c> while you're on the road (as
635there is no network available). With Gentoo you can alter the runlevel behaviour
636to your own will.
637</p>
638
639<p>
640For instance you can create a second "default" runlevel which you can boot that
641has other init scripts assigned to it. You can then select at boottime what
642default runlevel you want to use.
643</p>
644
645</body>
646</subsection>
647<subsection>
648<title>Using SOFTLEVEL</title>
649<body>
650
651<p>
652First of all, create the runlevel directory for your second "default" runlevel.
653As an example we create the <path>offline</path> runlevel:
654</p>
655
656<pre caption="Creating a runlevel directory">
657# <i>mkdir /etc/runlevels/offline</i>
658</pre>
659
660<p>
661Add the necessary init scripts to the newly created runlevels. For instance, if
662you want to have an exact copy of your current <c>default</c> runlevel but
663without <c>net.eth0</c>:
664</p>
665
666<pre caption="Adding the necessary init scripts">
667# <i>ls /etc/runlevels/default</i>
668acpid domainname local net.eth0 netmount postfix syslog-ng vixie-cron
669# <i>rc-update add acpid offline</i>
670# <i>rc-update add domainname offline</i>
671# <i>rc-update add local offline</i>
672# <i>rc-update add syslog-ng offline</i>
673# <i>rc-update add vixie-cron offline</i>
674</pre>
675
676<p>
677Now edit your bootloader configuration and add a new entry for the
678<c>offline</c> runlevel. For instance, in <path>/boot/grub/grub.conf</path>:
679</p>
680
681<pre caption="Adding an entry for the offline runlevel">
682title Gentoo Linux Offline Usage
683 root (hd0,0)
684 kernel (hd0,0)/kernel-2.4.25 root=/dev/hda3 <i>softlevel=offline</i>
685</pre>
686
687<p>
688Voila, you're all set now. If you boot your system and select the newly added
689entry at boot, the <c>offline</c> runlevel will be used instead of the
690<c>default</c> one.
691</p>
692
693</body>
694</subsection>
695<subsection>
696<title>Using BOOTLEVEL</title>
697<body>
698
699<p>
700Using <c>bootlevel</c> is completely analogous to <c>softlevel</c>. The only
701difference here is that you define a second "boot" runlevel instead of a second
702"default" runlevel.
703</p>
704
705</body>
706</subsection>
707</section>
546</sections> 708</sections>

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.18

  ViewVC Help
Powered by ViewVC 1.1.20