/[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.35
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/2.5 -->
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.35 2011/08/17 07:57:23 swift Exp $ -->
5 8
6<sections> 9<sections>
10
11<abstract>
12Gentoo uses a special initscript format which, amongst other features, allows
13dependency-driven decisions and virtual initscripts. This chapter explains all
14these aspects and explains how to deal with these scripts.
15</abstract>
16
17<version>4</version>
18<date>2011-08-17</date>
19
7<section> 20<section>
8<title>Runlevels</title> 21<title>Runlevels</title>
9<subsection> 22<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> 23<title>Booting your System</title>
25<body> 24<body>
26 25
27<p> 26<p>
28The process that takes care of the runlevels is called <c>init</c> and is also 27When 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 28close 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> 29your 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 30sequence</e> and is (more or less) statically defined.
32runlevel are listed. For instance, after initialising the system (<e>si</e>), 31</p>
33the <b>boot</b> runlevel is started: 32
34</p> 33<p>
34First, your boot loader will load the kernel image you have defined in the
35boot loader configuration into memory after which it tells the CPU to run the
36kernel. When the kernel is loaded and run, it initializes all kernel-specific
37structures and tasks and starts the <c>init</c> process.
38</p>
35 39
40<p>
41This process then makes sure that all filesystems (defined in
42<path>/etc/fstab</path>) are mounted and ready to be used. Then it executes
43several scripts located in <path>/etc/init.d</path>, which will start the
44services you need in order to have a successfully booted system.
45</p>
46
47<p>
48Finally, when all scripts are executed, <c>init</c> activates the terminals
49(in most cases just the virtual consoles which are hidden beneath <c>Alt-F1</c>,
50<c>Alt-F2</c>, etc.) attaching a special process called <c>agetty</c> to it.
51This process will then make sure you are able to log on through these terminals
52by running <c>login</c>.
53</p>
54
55</body>
56</subsection>
57<subsection>
58<title>Init Scripts</title>
59<body>
60
61<p>
62Now <c>init</c> doesn't just execute the scripts in <path>/etc/init.d</path>
63randomly. Even more, it doesn't run all scripts in <path>/etc/init.d</path>,
64only the scripts it is told to execute. It decides which scripts to execute by
65looking into <path>/etc/runlevels</path>.
66</p>
67
68<p>
69First, <c>init</c> runs all scripts from <path>/etc/init.d</path> that have
70symbolic links inside <path>/etc/runlevels/boot</path>. Usually, it will
71start the scripts in alphabetical order, but some scripts have dependency
72information in them, telling the system that another script must be run before
73they can be started.
74</p>
75
76<p>
77When all <path>/etc/runlevels/boot</path> referenced scripts are executed,
78<c>init</c> continues with running the scripts that have a symbolic link to them
79in <path>/etc/runlevels/default</path>. Again, it will use the alphabetical
80order to decide what script to run first, unless a script has dependency
81information in it, in which case the order is changed to provide a valid
82start-up sequence.
83</p>
84
85</body>
86</subsection>
87<subsection>
88<title>How Init Works</title>
89<body>
90
91<p>
92Of course <c>init</c> doesn't decide all that by itself. It needs a
93configuration file that specifies what actions need to be taken. This
94configuration file is <path>/etc/inittab</path>.
95</p>
96
97<p>
98If you remember the boot sequence we have just described, you will remember
99that <c>init</c>'s first action is to mount all filesystems. This is defined in
100the following line from <path>/etc/inittab</path>:
101</p>
102
36<pre caption="System initialisation lines in /etc/inittab"> 103<pre caption="The system initialisation line in /etc/inittab">
37si::sysinit:/sbin/rc sysinit 104si::sysinit:/sbin/rc sysinit
105</pre>
106
107<p>
108This line tells <c>init</c> that it must run <c>/sbin/rc sysinit</c> to
109initialize the system. The <path>/sbin/rc</path> script takes care of the
110initialisation, so you might say that <c>init</c> doesn't do much -- it
111delegates the task of initialising the system to another process.
112</p>
113
114<p>
115Second, <c>init</c> executed all scripts that had symbolic links in
116<path>/etc/runlevels/boot</path>. This is defined in the following line:
117</p>
118
119<pre caption="The system initialisation, continued">
38rc::bootwait:/sbin/rc boot 120rc::bootwait:/sbin/rc boot
39</pre> 121</pre>
40 122
41<p> 123<p>
42As you can see, <c>init</c> relies on the <c>rc</c> script. When started with 124Again the <c>rc</c> script performs the necessary tasks. Note that the option
43the "boot" argument, <c>rc</c> starts all scripts in the 125given 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 126<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> 127</p>
50When the <b>boot</b> runlevel is completed (the boot runlevel is an intermediate 128
51one), <c>init</c> checks what runlevel it should start. If you have not defined 129<p>
52one as kernel parameter, it will use the one defined in 130Now <c>init</c> checks its configuration file to see what <e>runlevel</e> it
131should run. To decide this, it reads the following line from
53<path>/etc/inittab</path>: 132<path>/etc/inittab</path>:
54</p> 133</p>
55 134
56<pre caption="Default runlevel"> 135<pre caption="The initdefault line">
57id:3:initdefault: 136id:3:initdefault:
58</pre> 137</pre>
59 138
60<p> 139<p>
61In this case, the runlevel id is "3", and gets mapped to: 140In this case (which the majority of Gentoo users will use), the <e>runlevel</e>
62</p> 141id is 3. Using this information, <c>init</c> checks what it must run to start
63 142<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> 143</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 144
74</body> 145<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 146l0:0:wait:/sbin/rc shutdown
87l1:S1:wait:/sbin/rc single 147l1:S1:wait:/sbin/rc single
88l2:2:wait:/sbin/rc nonetwork 148l2:2:wait:/sbin/rc nonetwork
89l3:3:wait:/sbin/rc default 149l3:3:wait:/sbin/rc default
90l4:4:wait:/sbin/rc default 150l4:4:wait:/sbin/rc default
91l5:5:wait:/sbin/rc default 151l5:5:wait:/sbin/rc default
92l6:6:wait:/sbin/rc reboot 152l6:6:wait:/sbin/rc reboot
93</pre> 153</pre>
94 154
95<p> 155<p>
96As you can see, there is a mapping of numbers to names (not vice versa). For 156The 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 157services (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 158<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> 159</p>
104As you can see from the listings, Gentoo defines 7 runlevels. Three of them are 160
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> 161<p>
111 162When <c>rc</c> has finished, <c>init</c> decides what virtual consoles it should
163activate and what commands need to be run at each console:
112<p> 164</p>
113The other four runlevels are <e>boot</e>, <e>default</e>, <e>nonetwork</e> and 165
114<e>single</e>. Each of them has a subdirectory in <path>/etc/runlevels</path> 166<pre caption="The virtual consoles definition">
115containing scripts that need to be started when the runlevel is activated. 167c1:12345:respawn:/sbin/agetty 38400 tty1 linux
168c2:12345:respawn:/sbin/agetty 38400 tty2 linux
169c3:12345:respawn:/sbin/agetty 38400 tty3 linux
170c4:12345:respawn:/sbin/agetty 38400 tty4 linux
171c5:12345:respawn:/sbin/agetty 38400 tty5 linux
172c6:12345:respawn:/sbin/agetty 38400 tty6 linux
116</p> 173</pre>
117 174
175
118</body> 176</body>
119</subsection>
120<subsection> 177</subsection>
178<subsection>
179<title>What is a runlevel?</title>
180<body>
181
182<p>
183You have seen that <c>init</c> uses a numbering scheme to decide what
184<e>runlevel</e> it should activate. A <e>runlevel</e> is a state in which
185your system is running and contains a collection of scripts (runlevel scripts or
186<e>initscripts</e>) that must be executed when you enter or leave a runlevel.
187</p>
188
189<p>
190In Gentoo, there are seven runlevels defined: three internal runlevels, and four
191user-defined runlevels. The internal runlevels are called <e>sysinit</e>,
192<e>shutdown</e> and <e>reboot</e> and do exactly what their names imply:
193initialize the system, powering off the system and rebooting the system.
194</p>
195
196<p>
197The user-defined runlevels are those with an accompanying
198<path>/etc/runlevels</path> subdirectory: <path>boot</path>,
199<path>default</path>, <path>nonetwork</path> and <path>single</path>. The
200<path>boot</path> runlevel starts all system-necessary services which all other
201runlevels use. The remaining three runlevels differ in what services they start:
202<path>default</path> is used for day-to-day operations, <path>nonetwork</path>
203is used in case no network connectivity is required, and <path>single</path> is
204used when you need to fix the system.
205</p>
206
207</body>
208</subsection>
209<subsection>
121<title>Working with the initscripts</title> 210<title>Working with the Init Scripts</title>
122<body> 211<body>
123 212
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> 213<p>
132 214The 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 215Each 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>, 216<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 217<e>status</e>, <e>ineed</e>, <e>iuse</e>, <e>needsme</e>, <e>usesme</e> or
137<e>broken</e>. 218<e>broken</e>.
138</p> 219</p>
143</p> 224</p>
144 225
145<pre caption="Starting Postfix"> 226<pre caption="Starting Postfix">
146# <i>/etc/init.d/postfix start</i> 227# <i>/etc/init.d/postfix start</i>
147</pre> 228</pre>
229
230<note>
231Only the services that <e>need</e> the given service are stopped or restarted.
232The other depending services (those that <e>use</e> the service but don't need
233it) are left untouched.
234</note>
148 235
149<p> 236<p>
150If you want to stop a service, but not the services that depend on it, you can 237If you want to stop a service, but not the services that depend on it, you can
151use the <c>pause</c> argument: 238use the <c>pause</c> argument:
152</p> 239</p>
194<pre caption="Requesting a list of all services that require Postfix"> 281<pre caption="Requesting a list of all services that require Postfix">
195# <i>/etc/init.d/postfix needsme</i> 282# <i>/etc/init.d/postfix needsme</i>
196</pre> 283</pre>
197 284
198<p> 285<p>
199Finally, you can ask what dependencies the service requires but that are 286Finally, you can ask what dependencies the service requires that are missing:
200missing:
201</p> 287</p>
202 288
203<pre caption="Requesting a list of missing dependencies for Postfix"> 289<pre caption="Requesting a list of missing dependencies for Postfix">
204# <i>/etc/init.d/postfix broken</i> 290# <i>/etc/init.d/postfix broken</i>
205</pre> 291</pre>
213<title>What is rc-update?</title> 299<title>What is rc-update?</title>
214<body> 300<body>
215 301
216<p> 302<p>
217Gentoo's init system uses a dependency-tree to decide what service needs to be 303Gentoo'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 304started 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 305have to do manually, we have created tools that ease the administration of the
220and init scripts. 306runlevels and init scripts.
221</p> 307</p>
222 308
223<p> 309<p>
224With <c>rc-update</c> you can add and remove init scripts to a runlevel. The 310With <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 311<c>rc-update</c> tool will then automatically ask the <c>depscan.sh</c> script
232<title>Adding and Removing Services</title> 318<title>Adding and Removing Services</title>
233<body> 319<body>
234 320
235<p> 321<p>
236You have already added init scripts to the "default" runlevel during the 322You 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 323installation 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 324"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>. 325second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>.
240</p> 326</p>
241 327
242<p> 328<p>
247<pre caption="Removing Postfix from the default runlevel"> 333<pre caption="Removing Postfix from the default runlevel">
248# <i>rc-update del postfix default</i> 334# <i>rc-update del postfix default</i>
249</pre> 335</pre>
250 336
251<p> 337<p>
252The <c>rc-update show</c> command will show all the available init scripts and 338The <c>rc-update -v show</c> command will show all the available init scripts and
253list at which runlevels they will execute: 339list at which runlevels they will execute:
254</p> 340</p>
255 341
256<pre caption="Receiving init script information"> 342<pre caption="Receiving init script information">
257# <i>rc-update show</i> 343# <i>rc-update -v show</i>
344</pre>
345
346<p>
347You can also run <c>rc-update show</c> (without <c>-v</c>) to just view enabled
348init scripts and their runlevels.
258</pre> 349</p>
259 350
260</body> 351</body>
261</subsection> 352</subsection>
262</section> 353</section>
263<section> 354<section>
265<subsection> 356<subsection>
266<title>Why the Need for Extra Configuration?</title> 357<title>Why the Need for Extra Configuration?</title>
267<body> 358<body>
268 359
269<p> 360<p>
270Init scripts can be quite complex. It is therefor not really interesting to have 361Init 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. 362have 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, 363error-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. 364instance, you might want to give more options to the service itself.
274</p>
275
276<p> 365</p>
366
367<p>
277A second reason to have this configuration outside the init script is to be able 368A 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 369able to update the init scripts without the fear that your configuration
279are undone. 370changes will be undone.
280</p> 371</p>
281 372
282</body> 373</body>
283</subsection> 374</subsection>
284<subsection> 375<subsection>
292configuration file called <path>/etc/conf.d/apache2</path>, which can contain 383configuration 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: 384the options you want to give to the Apache 2 server when it is started:
294</p> 385</p>
295 386
296<pre caption="Variable defined in /etc/conf.d/apache2"> 387<pre caption="Variable defined in /etc/conf.d/apache2">
297APACHE2_OPTS="-D PHP4" 388APACHE2_OPTS="-D PHP5"
298</pre> 389</pre>
299 390
300<p> 391<p>
301Such a configuration file contains variables and variables alone (just like 392Such 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 393<path>/etc/make.conf</path>), making it very easy to configure services. It also
311<subsection> 402<subsection>
312<title>Do I Have To?</title> 403<title>Do I Have To?</title>
313<body> 404<body>
314 405
315<p> 406<p>
316No. Writing an init script is usually not necessary as Gentoo provides 407No, writing an init script is usually not necessary as Gentoo provides
317ready-to-use init scripts for all provided services. However, you might have 408ready-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 409installed a service without using Portage, in which case you will most likely
319have to create an init script. 410have to create an init script.
320</p> 411</p>
321 412
347} 438}
348 439
349stop() { 440stop() {
350 <comment>(Commands necessary to stop the service)</comment> 441 <comment>(Commands necessary to stop the service)</comment>
351} 442}
352
353restart() {
354 <comment>(Commands necessary to restart the service)</comment>
355}
356</pre> 443</pre>
357 444
358<p> 445<p>
359Any init script <e>requires</e> the <c>start()</c> function to be defined. All 446Any init script <e>requires</e> the <c>start()</c> function to be defined. All
360other sections are optional. 447other sections are optional.
365<subsection> 452<subsection>
366<title>Dependencies</title> 453<title>Dependencies</title>
367<body> 454<body>
368 455
369<p> 456<p>
370There are two dependencies you can define: <c>use</c> and <c>need</c>. As we 457There are two dependency-alike settings you can define that influence the
371have mentioned before, the <c>need</c> dependency is more strict than the 458start-up or sequencing of init scripts: <c>use</c> and <c>need</c>. Next to
372<c>use</c> dependency. Following this dependency type you enter the service 459these two, there are also two order-influencing methods called <c>before</c> and
373you depend on, or the <e>virtual</e> dependency. 460<c>after</c>. These last two are no dependencies per se - they do not make the
461original init script fail if the selected one isn't scheduled to start (or fails
462to start).
463</p>
464
465<ul>
466 <li>
467 The <c>use</c> settings informs the init system that this script <e>uses</e>
468 functionality offered by the selected script, but does not directly depend
469 on it. A good example would be <c>use logger</c> or <c>use dns</c>. If those
470 services are available, they will be put in good use, but if you do not have
471 a logger or DNS server the services will still work. If the services exist,
472 then they are started before the script that <c>use</c>'s them.
473 </li>
474 <li>
475 The <c>need</c> setting is a hard dependency. It means that the script that
476 is <c>need</c>'ing another script will not start before the other script is
477 launched successfully. Also, if that other script is restarted, then this
478 one will be restarted as well.
479 </li>
480 <li>
481 When using <c>before</c>, then the given script is launched before the
482 selected one <e>if</e> the selected one is part of the init level. So an
483 init script <path>xdm</path> that defines <c>before alsasound</c> will start
484 before the <path>alsasound</path> script, but only if <path>alsasound</path>
485 is scheduled to start as well in the same init level. If
486 <path>alsasound</path> is not scheduled to start too, then this particular
487 setting has no effect and <path>xdm</path> will be started when the init
488 system deems it most appropriate.
489 </li>
490 <li>
491 Similarly, <c>after</c> informs the init system that the given script should
492 be launched after the selected one <e>if</e> the selected one is part of the
493 init level. If not, then the setting has no effect and the script will be
494 launched by the init system when it deems it most appropriate.
495 </li>
496</ul>
497
498<p>
499It should be clear from the above that <c>need</c> is the only "true" dependency
500setting as it affects if the script will be started or not. All the others are
501merely pointers towards the init system to clarify in which order scripts can be
502(or should be) launched.
503</p>
504
505<p>
506Now, if you look at many of Gentoo's available init scripts, you will notice
507that some have dependencies on things that are no init scripts. These "things"
508we call <e>virtuals</e>.
374</p> 509</p>
375 510
376<p> 511<p>
377A <e>virtual</e> dependency is a dependency that a service provides, but that is 512A <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 513not provided solely by that service. Your init script can depend on a system
422<subsection> 557<subsection>
423<title>Controlling the Order</title> 558<title>Controlling the Order</title>
424<body> 559<body>
425 560
426<p> 561<p>
427In some cases you might not require a service, but want your service to be 562As we described in the previous section, you can tell the init system what order
428started <c>before</c> (or <c>after</c>) another service <e>if</e> it is 563it should use for starting (or stopping) scripts. This ordering is handled both
429available on the system (note the conditional - this is no dependency anymore) 564through the dependency settings <c>use</c> and <c>need</c>, but also through the
430<e>and</e> ran in the same runlevel (note the conditional - only services in the 565order settings <c>before</c> and <c>after</c>. As we have described these
431same runlevel are involved). You can provide this information using the 566earlier already, let's take a look at the Portmap service as an example of such
432<c>before</c> or <c>after</c> settings. 567init script.
433</p>
434
435<p>
436As an example we view the settings of the Portmap service:
437</p> 568</p>
438 569
439<pre caption="The depend() function in the Portmap service"> 570<pre caption="The depend() function in the Portmap service">
440depend() { 571depend() {
441 need net 572 need net
444} 575}
445</pre> 576</pre>
446 577
447<p> 578<p>
448You can also use the "*" glob to catch all services in the same runlevel, 579You can also use the "*" glob to catch all services in the same runlevel,
449although this isn't adviseable. 580although this isn't advisable.
450</p> 581</p>
451 582
452<pre caption="Running an init script as first script in the runlevel"> 583<pre caption="Running an init script as first script in the runlevel">
453depend() { 584depend() {
454 before * 585 before *
455} 586}
456</pre> 587</pre>
457 588
589<p>
590If your service must write to local disks, it should need <c>localmount</c>. If
591it places anything in <path>/var/run</path> such as a pidfile, then it should
592start after <c>bootmisc</c>:
593</p>
594
595<pre caption="Example depend() function">
596depend() {
597 need localmount
598 after bootmisc
599}
600</pre>
601
458</body> 602</body>
459</subsection> 603</subsection>
460<subsection> 604<subsection>
461<title>Standard Functions</title> 605<title>Standard Functions</title>
462<body> 606<body>
463 607
464<p> 608<p>
465Next to the <c>depend()</c> functionality, you also need to define the 609Next 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 610<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 611initialize 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: 612<c>eend</c> functions to inform the user about what is happening:
469</p> 613</p>
470 614
471<pre caption="Example start() function"> 615<pre caption="Example start() function">
472start() { 616start() {
617 if [ "${RC_CMD}" = "restart" ];
618 then
619 <comment># Do something in case a restart requires more than stop, start</comment>
620 fi
621
473 ebegin "Starting my_service" 622 ebegin "Starting my_service"
474 start-stop-daemon --start --quiet --exec /path/to/my_service 623 start-stop-daemon --start --exec /path/to/my_service \
624 --pidfile /path/to/my_pidfile
475 eend $? 625 eend $?
476} 626}
477</pre> 627</pre>
478 628
479<p> 629<p>
630Both <c>--exec</c> and <c>--pidfile</c> should be used in start and stop
631functions. If the service does not create a pidfile, then use
632<c>--make-pidfile</c> if possible, though you should test this to be sure.
633Otherwise, don't use pidfiles. You can also add <c>--quiet</c> to the
634<c>start-stop-daemon</c> options, but this is not recommended unless the
635service is extremely verbose. Using <c>--quiet</c> may hinder debugging if the
636service fails to start.
637</p>
638
639<p>
640Another notable setting used in the above example is to check the contents of
641the <c>RC_CMD</c> variable. Unlike the previous init script system, the newer
642<c>openrc</c> system does not support script-specific restart functionality.
643Instead, the script needs to check the contents of the <c>RC_CMD</c> variable
644to see if a function (be it <c>start()</c> or <c>stop()</c>) is called as part
645of a restart or not.
646</p>
647
648<note>
649Make sure that <c>--exec</c> actually calls a service and not just a shell
650script that launches services and exits -- that's what the init script is
651supposed to do.
652</note>
653
654<p>
480If you need more examples of the <c>start()</c> function, please read the source 655If you need more examples of the <c>start()</c> function, please read the
481code of the available init scripts in your <path>/etc/init.d</path> directory. 656source code of the available init scripts in your <path>/etc/init.d</path>
657directory.
658</p>
659
660<p>
661Another function you can define is <c>stop()</c>. You are not obliged to define
662this function though! Our init system is intelligent enough to fill in this
663function by itself if you use <c>start-stop-daemon</c>.
664</p>
665
666<p>
667Here is an example of a <c>stop()</c> function:
668</p>
669
670<pre caption="Example stop() function">
671stop() {
672 ebegin "Stopping my_service"
673 start-stop-daemon --stop --exec /path/to/my_service \
674 --pidfile /path/to/my_pidfile
675 eend $?
676}
677</pre>
678
679<p>
680If your service runs some other script (for example, bash, python, or perl),
681and this script later changes names (for example, <c>foo.py</c> to <c>foo</c>),
682then you will need to add <c>--name</c> to <c>start-stop-daemon</c>. You must
683specify the name that your script will be changed to. In this example, a
684service starts <c>foo.py</c>, which changes names to <c>foo</c>:
685</p>
686
687<pre caption="A service that starts the foo script">
688start() {
689 ebegin "Starting my_script"
690 start-stop-daemon --start --exec /path/to/my_script \
691 --pidfile /path/to/my_pidfile --name foo
692 eend $?
693}
694</pre>
695
696<p>
482As for <c>start-stop-daemon</c>, there is an excellent man page available if you 697<c>start-stop-daemon</c> has an excellent man page available if you need more
483need more information: 698information:
484</p> 699</p>
485 700
486<pre caption="Getting the man page for start-stop-daemon"> 701<pre caption="Getting the man page for start-stop-daemon">
487# <i>man start-stop-daemon</i> 702$ <i>man start-stop-daemon</i>
488</pre> 703</pre>
489 704
490<p> 705<p>
491Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are 706Gentoo's init script syntax is based on the Bourne Again Shell (bash) so you are
492not obliged to define these functions! Our init system is intelligent enough to 707free to use bash-compatible constructs inside your init script. However, you may
493fill these functions in herself if you use <c>start-stop-daemon</c>. 708want to write your init scripts to be POSIX-compliant. Future init script
709systems may allow symlinking <path>/bin/sh</path> to other shells besides
710bash. Init scripts that rely on bash-only features will then break these
711configurations.
494</p> 712</p>
495 713
496</body> 714</body>
497</subsection> 715</subsection>
498<subsection> 716<subsection>
508 726
509<pre caption="Supporting the restartdelay option"> 727<pre caption="Supporting the restartdelay option">
510opts="${opts} restartdelay" 728opts="${opts} restartdelay"
511 729
512restartdelay() { 730restartdelay() {
513 stop() 731 stop
514 sleep 3 <comment># Wait 3 seconds before starting again</comment> 732 sleep 3 <comment># Wait 3 seconds before starting again</comment>
515 start() 733 start
516} 734}
517</pre> 735</pre>
736
737<impo>
738The function <c>restart()</c> cannot be overridden in openrc!
739</impo>
518 740
519</body> 741</body>
520</subsection> 742</subsection>
521<subsection> 743<subsection>
522<title>Service Configuration Variables</title> 744<title>Service Configuration Variables</title>
541</p> 763</p>
542 764
543</body> 765</body>
544</subsection> 766</subsection>
545</section> 767</section>
768<section>
769<title>Changing the Runlevel Behaviour</title>
770<subsection>
771<title>Who might benefit from this?</title>
772<body>
773
774<p>
775Many laptop users know the situation: at home you need to start <c>net.eth0</c>
776while you don't want to start <c>net.eth0</c> while you're on the road (as
777there is no network available). With Gentoo you can alter the runlevel behaviour
778to your own will.
779</p>
780
781<p>
782For instance you can create a second "default" runlevel which you can boot that
783has other init scripts assigned to it. You can then select at boottime what
784default runlevel you want to use.
785</p>
786
787</body>
788</subsection>
789<subsection>
790<title>Using softlevel</title>
791<body>
792
793<p>
794First of all, create the runlevel directory for your second "default" runlevel.
795As an example we create the <path>offline</path> runlevel:
796</p>
797
798<pre caption="Creating a runlevel directory">
799# <i>mkdir /etc/runlevels/offline</i>
800</pre>
801
802<p>
803Add the necessary init scripts to the newly created runlevels. For instance, if
804you want to have an exact copy of your current <c>default</c> runlevel but
805without <c>net.eth0</c>:
806</p>
807
808<pre caption="Adding the necessary init scripts">
809<comment>(Copy all services from default runlevel to offline runlevel)</comment>
810# <i>cd /etc/runlevels/default</i>
811# <i>for service in *; do rc-update add $service offline; done</i>
812<comment>(Remove unwanted service from offline runlevel)</comment>
813# <i>rc-update del net.eth0 offline</i>
814<comment>(Display active services for offline runlevel)</comment>
815# <i>rc-update show offline</i>
816<comment>(Partial sample Output)</comment>
817 acpid | offline
818 domainname | offline
819 local | offline
820 net.eth0 |
821</pre>
822
823<p>
824Even though <c>net.eth0</c> has been removed from the offline runlevel,
825<c>udev</c> might want to attempt to start any devices it detects and launch the
826appropriate services, a functionality that is called <e>hotplugging</e>. By
827default, Gentoo does not enable hotplugging.
828</p>
829
830<p>
831If you do want to enable hotplugging, but only for a selected set of scripts,
832use the <c>rc_hotplug</c> variable in <path>/etc/rc.conf</path>:
833</p>
834
835<pre caption="Disabling device initiated services in /etc/rc.conf">
836<comment># Allow net.wlan as well as any other service, except those matching net.*
837# to be hotplugged</comment>
838rc_hotplug="net.wlan !net.*"
839</pre>
840
841<note>
842For more information on device initiated services, please see the comments
843inside <path>/etc/rc.conf</path>.
844</note>
845
846<p>
847Now edit your bootloader configuration and add a new entry for the
848<c>offline</c> runlevel. For instance, in <path>/boot/grub/grub.conf</path>:
849</p>
850
851<pre caption="Adding an entry for the offline runlevel">
852title Gentoo Linux Offline Usage
853 root (hd0,0)
854 kernel (hd0,0)/kernel-2.4.25 root=/dev/hda3 <i>softlevel=offline</i>
855</pre>
856
857<p>
858VoilĂ , you're all set now. If you boot your system and select the newly added
859entry at boot, the <c>offline</c> runlevel will be used instead of the
860<c>default</c> one.
861</p>
862
863</body>
864</subsection>
865<subsection>
866<title>Using bootlevel</title>
867<body>
868
869<p>
870Using <c>bootlevel</c> is completely analogous to <c>softlevel</c>. The only
871difference here is that you define a second "boot" runlevel instead of a second
872"default" runlevel.
873</p>
874
875</body>
876</subsection>
877</section>
546</sections> 878</sections>

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

  ViewVC Help
Powered by ViewVC 1.1.20