/[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.34 - (show annotations) (download) (as text)
Sun Aug 14 16:12:13 2011 UTC (3 years ago) by swift
Branch: MAIN
Changes since 1.33: +14 -10 lines
File MIME type: application/xml
Bug #213988 - Various fixes on OpenRC in handbook

1 <?xml version='1.0' encoding='UTF-8'?>
2 <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3
4 <!-- The content of this document is licensed under the CC-BY-SA license -->
5 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6
7 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.33 2011/08/12 19:34:56 swift Exp $ -->
8
9 <sections>
10
11 <abstract>
12 Gentoo uses a special initscript format which, amongst other features, allows
13 dependency-driven decisions and virtual initscripts. This chapter explains all
14 these aspects and explains how to deal with these scripts.
15 </abstract>
16
17 <version>3</version>
18 <date>2011-08-12</date>
19
20 <section>
21 <title>Runlevels</title>
22 <subsection>
23 <title>Booting your System</title>
24 <body>
25
26 <p>
27 When you boot your system, you will notice lots of text floating by. If you pay
28 close attention, you will notice this text is the same every time you reboot
29 your system. The sequence of all these actions is called the <e>boot
30 sequence</e> and is (more or less) statically defined.
31 </p>
32
33 <p>
34 First, your boot loader will load the kernel image you have defined in the
35 boot loader configuration into memory after which it tells the CPU to run the
36 kernel. When the kernel is loaded and run, it initializes all kernel-specific
37 structures and tasks and starts the <c>init</c> process.
38 </p>
39
40 <p>
41 This process then makes sure that all filesystems (defined in
42 <path>/etc/fstab</path>) are mounted and ready to be used. Then it executes
43 several scripts located in <path>/etc/init.d</path>, which will start the
44 services you need in order to have a successfully booted system.
45 </p>
46
47 <p>
48 Finally, 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.
51 This process will then make sure you are able to log on through these terminals
52 by running <c>login</c>.
53 </p>
54
55 </body>
56 </subsection>
57 <subsection>
58 <title>Init Scripts</title>
59 <body>
60
61 <p>
62 Now <c>init</c> doesn't just execute the scripts in <path>/etc/init.d</path>
63 randomly. Even more, it doesn't run all scripts in <path>/etc/init.d</path>,
64 only the scripts it is told to execute. It decides which scripts to execute by
65 looking into <path>/etc/runlevels</path>.
66 </p>
67
68 <p>
69 First, <c>init</c> runs all scripts from <path>/etc/init.d</path> that have
70 symbolic links inside <path>/etc/runlevels/boot</path>. Usually, it will
71 start the scripts in alphabetical order, but some scripts have dependency
72 information in them, telling the system that another script must be run before
73 they can be started.
74 </p>
75
76 <p>
77 When 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
79 in <path>/etc/runlevels/default</path>. Again, it will use the alphabetical
80 order to decide what script to run first, unless a script has dependency
81 information in it, in which case the order is changed to provide a valid
82 start-up sequence.
83 </p>
84
85 </body>
86 </subsection>
87 <subsection>
88 <title>How Init Works</title>
89 <body>
90
91 <p>
92 Of course <c>init</c> doesn't decide all that by itself. It needs a
93 configuration file that specifies what actions need to be taken. This
94 configuration file is <path>/etc/inittab</path>.
95 </p>
96
97 <p>
98 If you remember the boot sequence we have just described, you will remember
99 that <c>init</c>'s first action is to mount all filesystems. This is defined in
100 the following line from <path>/etc/inittab</path>:
101 </p>
102
103 <pre caption="The system initialisation line in /etc/inittab">
104 si::sysinit:/sbin/rc sysinit
105 </pre>
106
107 <p>
108 This line tells <c>init</c> that it must run <c>/sbin/rc sysinit</c> to
109 initialize the system. The <path>/sbin/rc</path> script takes care of the
110 initialisation, so you might say that <c>init</c> doesn't do much -- it
111 delegates the task of initialising the system to another process.
112 </p>
113
114 <p>
115 Second, <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">
120 rc::bootwait:/sbin/rc boot
121 </pre>
122
123 <p>
124 Again the <c>rc</c> script performs the necessary tasks. Note that the option
125 given to <c>rc</c> (<e>boot</e>) is the same as the subdirectory of
126 <path>/etc/runlevels</path> that is used.
127 </p>
128
129 <p>
130 Now <c>init</c> checks its configuration file to see what <e>runlevel</e> it
131 should run. To decide this, it reads the following line from
132 <path>/etc/inittab</path>:
133 </p>
134
135 <pre caption="The initdefault line">
136 id:3:initdefault:
137 </pre>
138
139 <p>
140 In this case (which the majority of Gentoo users will use), the <e>runlevel</e>
141 id is 3. Using this information, <c>init</c> checks what it must run to start
142 <e>runlevel 3</e>:
143 </p>
144
145 <pre caption="The runlevel definitions">
146 l0:0:wait:/sbin/rc shutdown
147 l1:S1:wait:/sbin/rc single
148 l2:2:wait:/sbin/rc nonetwork
149 l3:3:wait:/sbin/rc default
150 l4:4:wait:/sbin/rc default
151 l5:5:wait:/sbin/rc default
152 l6:6:wait:/sbin/rc reboot
153 </pre>
154
155 <p>
156 The line that defines level 3, again, uses the <c>rc</c> script to start the
157 services (now with argument <e>default</e>). Again note that the argument of
158 <c>rc</c> is the same as the subdirectory from <path>/etc/runlevels</path>.
159 </p>
160
161 <p>
162 When <c>rc</c> has finished, <c>init</c> decides what virtual consoles it should
163 activate and what commands need to be run at each console:
164 </p>
165
166 <pre caption="The virtual consoles definition">
167 c1:12345:respawn:/sbin/agetty 38400 tty1 linux
168 c2:12345:respawn:/sbin/agetty 38400 tty2 linux
169 c3:12345:respawn:/sbin/agetty 38400 tty3 linux
170 c4:12345:respawn:/sbin/agetty 38400 tty4 linux
171 c5:12345:respawn:/sbin/agetty 38400 tty5 linux
172 c6:12345:respawn:/sbin/agetty 38400 tty6 linux
173 </pre>
174
175
176 </body>
177 </subsection>
178 <subsection>
179 <title>What is a runlevel?</title>
180 <body>
181
182 <p>
183 You 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
185 your 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>
190 In Gentoo, there are seven runlevels defined: three internal runlevels, and four
191 user-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:
193 initialize the system, powering off the system and rebooting the system.
194 </p>
195
196 <p>
197 The 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
201 runlevels 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>
203 is used in case no network connectivity is required, and <path>single</path> is
204 used when you need to fix the system.
205 </p>
206
207 </body>
208 </subsection>
209 <subsection>
210 <title>Working with the Init Scripts</title>
211 <body>
212
213 <p>
214 The scripts that the <c>rc</c> process starts are called <e>init scripts</e>.
215 Each script in <path>/etc/init.d</path> can be executed with the arguments
216 <e>start</e>, <e>stop</e>, <e>restart</e>, <e>pause</e>, <e>zap</e>,
217 <e>status</e>, <e>ineed</e>, <e>iuse</e>, <e>needsme</e>, <e>usesme</e> or
218 <e>broken</e>.
219 </p>
220
221 <p>
222 To start, stop or restart a service (and all depending services), <c>start</c>,
223 <c>stop</c> and <c>restart</c> should be used:
224 </p>
225
226 <pre caption="Starting Postfix">
227 # <i>/etc/init.d/postfix start</i>
228 </pre>
229
230 <note>
231 Only the services that <e>need</e> the given service are stopped or restarted.
232 The other depending services (those that <e>use</e> the service but don't need
233 it) are left untouched.
234 </note>
235
236 <p>
237 If you want to stop a service, but not the services that depend on it, you can
238 use the <c>pause</c> argument:
239 </p>
240
241 <pre caption="Stopping Postfix but keep the depending services running">
242 # <i>/etc/init.d/postfix pause</i>
243 </pre>
244
245 <p>
246 If you want to see what status a service has (started, stopped, paused, ...) you
247 can use the <c>status</c> argument:
248 </p>
249
250 <pre caption="Status information for postfix">
251 # <i>/etc/init.d/postfix status</i>
252 </pre>
253
254 <p>
255 If the status information tells you that the service is running, but you know
256 that it is not, then you can reset the status information to "stopped" with the
257 <c>zap</c> argument:
258 </p>
259
260 <pre caption="Resetting status information for postfix">
261 # <i>/etc/init.d/postfix zap</i>
262 </pre>
263
264 <p>
265 To also ask what dependencies the service has, you can use <c>iuse</c> or
266 <c>ineed</c>. With <c>ineed</c> you can see the services that are really
267 necessary for the correct functioning of the service. <c>iuse</c> on the other
268 hand shows the services that can be used by the service, but are not necessary
269 for the correct functioning.
270 </p>
271
272 <pre caption="Requesting a list of all necessary services on which Postfix depends">
273 # <i>/etc/init.d/postfix ineed</i>
274 </pre>
275
276 <p>
277 Similarly, you can ask what services require the service (<c>needsme</c>) or can
278 use it (<c>usesme</c>):
279 </p>
280
281 <pre caption="Requesting a list of all services that require Postfix">
282 # <i>/etc/init.d/postfix needsme</i>
283 </pre>
284
285 <p>
286 Finally, you can ask what dependencies the service requires that are missing:
287 </p>
288
289 <pre caption="Requesting a list of missing dependencies for Postfix">
290 # <i>/etc/init.d/postfix broken</i>
291 </pre>
292
293 </body>
294 </subsection>
295 </section>
296 <section>
297 <title>Working with rc-update</title>
298 <subsection>
299 <title>What is rc-update?</title>
300 <body>
301
302 <p>
303 Gentoo's init system uses a dependency-tree to decide what service needs to be
304 started first. As this is a tedious task that we wouldn't want our users to
305 have to do manually, we have created tools that ease the administration of the
306 runlevels and init scripts.
307 </p>
308
309 <p>
310 With <c>rc-update</c> you can add and remove init scripts to a runlevel. The
311 <c>rc-update</c> tool will then automatically ask the <c>depscan.sh</c> script
312 to rebuild the dependency tree.
313 </p>
314
315 </body>
316 </subsection>
317 <subsection>
318 <title>Adding and Removing Services</title>
319 <body>
320
321 <p>
322 You have already added init scripts to the "default" runlevel during the
323 installation of Gentoo. At that time you might not have had a clue what the
324 "default" is for, but now you should. The <c>rc-update</c> script requires a
325 second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>.
326 </p>
327
328 <p>
329 To add or remove an init script, just give <c>rc-update</c> the <c>add</c> or
330 <c>del</c> argument, followed by the init script and the runlevel. For instance:
331 </p>
332
333 <pre caption="Removing Postfix from the default runlevel">
334 # <i>rc-update del postfix default</i>
335 </pre>
336
337 <p>
338 The <c>rc-update -v show</c> command will show all the available init scripts and
339 list at which runlevels they will execute:
340 </p>
341
342 <pre caption="Receiving init script information">
343 # <i>rc-update -v show</i>
344 </pre>
345
346 <p>
347 You can also run <c>rc-update show</c> (without <c>-v</c>) to just view enabled
348 init scripts and their runlevels.
349 </p>
350
351 </body>
352 </subsection>
353 </section>
354 <section>
355 <title>Configuring Services</title>
356 <subsection>
357 <title>Why the Need for Extra Configuration?</title>
358 <body>
359
360 <p>
361 Init scripts can be quite complex. It is therefore not really desirable to
362 have the users edit the init script directly, as it would make it more
363 error-prone. It is however important to be able to configure such a service. For
364 instance, you might want to give more options to the service itself.
365 </p>
366
367 <p>
368 A second reason to have this configuration outside the init script is to be
369 able to update the init scripts without the fear that your configuration
370 changes will be undone.
371 </p>
372
373 </body>
374 </subsection>
375 <subsection>
376 <title>The /etc/conf.d Directory</title>
377 <body>
378
379 <p>
380 Gentoo provides an easy way to configure such a service: every init script that
381 can be configured has a file in <path>/etc/conf.d</path>. For instance, the
382 apache2 initscript (called <path>/etc/init.d/apache2</path>) has a
383 configuration file called <path>/etc/conf.d/apache2</path>, which can contain
384 the options you want to give to the Apache 2 server when it is started:
385 </p>
386
387 <pre caption="Variable defined in /etc/conf.d/apache2">
388 APACHE2_OPTS="-D PHP5"
389 </pre>
390
391 <p>
392 Such a configuration file contains variables and variables alone (just like
393 <path>/etc/make.conf</path>), making it very easy to configure services. It also
394 allows us to provide more information about the variables (as comments).
395 </p>
396
397 </body>
398 </subsection>
399 </section>
400 <section>
401 <title>Writing Init Scripts</title>
402 <subsection>
403 <title>Do I Have To?</title>
404 <body>
405
406 <p>
407 No, writing an init script is usually not necessary as Gentoo provides
408 ready-to-use init scripts for all provided services. However, you might have
409 installed a service without using Portage, in which case you will most likely
410 have to create an init script.
411 </p>
412
413 <p>
414 Do not use the init script provided by the service if it isn't explicitly
415 written for Gentoo: Gentoo's init scripts are not compatible with the init
416 scripts used by other distributions!
417 </p>
418
419 </body>
420 </subsection>
421 <subsection>
422 <title>Layout</title>
423 <body>
424
425 <p>
426 The basic layout of an init script is shown below.
427 </p>
428
429 <pre caption="Basic layout of an init script">
430 #!/sbin/runscript
431
432 depend() {
433 <comment>(Dependency information)</comment>
434 }
435
436 start() {
437 <comment>(Commands necessary to start the service)</comment>
438 }
439
440 stop() {
441 <comment>(Commands necessary to stop the service)</comment>
442 }
443 </pre>
444
445 <p>
446 Any init script <e>requires</e> the <c>start()</c> function to be defined. All
447 other sections are optional.
448 </p>
449
450 </body>
451 </subsection>
452 <subsection>
453 <title>Dependencies</title>
454 <body>
455
456 <p>
457 There are two dependencies you can define: <c>use</c> and <c>need</c>. As we
458 have mentioned before, the <c>need</c> dependency is more strict than the
459 <c>use</c> dependency. Following this dependency type you enter the service
460 you depend on, or the <e>virtual</e> dependency.
461 </p>
462
463 <p>
464 A <e>virtual</e> dependency is a dependency that a service provides, but that is
465 not provided solely by that service. Your init script can depend on a system
466 logger, but there are many system loggers available (metalogd, syslog-ng,
467 sysklogd, ...). As you cannot <c>need</c> every single one of them (no sensible
468 system has all these system loggers installed and running) we made sure that
469 all these services <c>provide</c> a virtual dependency.
470 </p>
471
472 <p>
473 Let us take a look at the dependency information for the postfix service.
474 </p>
475
476 <pre caption="Dependency information for Postfix">
477 depend() {
478 need net
479 use logger dns
480 provide mta
481 }
482 </pre>
483
484 <p>
485 As you can see, the postfix service:
486 </p>
487
488 <ul>
489 <li>
490 requires the (virtual) <c>net</c> dependency (which is provided by, for
491 instance, <path>/etc/init.d/net.eth0</path>)
492 </li>
493 <li>
494 uses the (virtual) <c>logger</c> dependency (which is provided by, for
495 instance, <path>/etc/init.d/syslog-ng</path>)
496 </li>
497 <li>
498 uses the (virtual) <c>dns</c> dependency (which is provided by, for
499 instance, <path>/etc/init.d/named</path>)
500 </li>
501 <li>
502 provides the (virtual) <c>mta</c> dependency (which is common for all mail
503 servers)
504 </li>
505 </ul>
506
507 </body>
508 </subsection>
509 <subsection>
510 <title>Controlling the Order</title>
511 <body>
512
513 <p>
514 In some cases you might not require a service, but want your service to be
515 started <c>before</c> (or <c>after</c>) another service <e>if</e> it is
516 available on the system (note the conditional - this is no dependency anymore)
517 <e>and</e> run in the same runlevel (note the conditional - only services in the
518 same runlevel are involved). You can provide this information using the
519 <c>before</c> or <c>after</c> settings.
520 </p>
521
522 <p>
523 As an example we view the settings of the Portmap service:
524 </p>
525
526 <pre caption="The depend() function in the Portmap service">
527 depend() {
528 need net
529 before inetd
530 before xinetd
531 }
532 </pre>
533
534 <p>
535 You can also use the "*" glob to catch all services in the same runlevel,
536 although this isn't advisable.
537 </p>
538
539 <pre caption="Running an init script as first script in the runlevel">
540 depend() {
541 before *
542 }
543 </pre>
544
545 <p>
546 If your service must write to local disks, it should need <c>localmount</c>. If
547 it places anything in <path>/var/run</path> such as a pidfile, then it should
548 start after <c>bootmisc</c>:
549 </p>
550
551 <pre caption="Example depend() function">
552 depend() {
553 need localmount
554 after bootmisc
555 }
556 </pre>
557
558 </body>
559 </subsection>
560 <subsection>
561 <title>Standard Functions</title>
562 <body>
563
564 <p>
565 Next to the <c>depend()</c> functionality, you also need to define the
566 <c>start()</c> function. This one contains all the commands necessary to
567 initialize your service. It is advisable to use the <c>ebegin</c> and
568 <c>eend</c> functions to inform the user about what is happening:
569 </p>
570
571 <pre caption="Example start() function">
572 start() {
573 if [ "${RC_CMD}" = "restart" ];
574 then
575 <comment># Do something in case a restart requires more than stop, start</comment>
576 fi
577
578 ebegin "Starting my_service"
579 start-stop-daemon --start --exec /path/to/my_service \
580 --pidfile /path/to/my_pidfile
581 eend $?
582 }
583 </pre>
584
585 <p>
586 Both <c>--exec</c> and <c>--pidfile</c> should be used in start and stop
587 functions. If the service does not create a pidfile, then use
588 <c>--make-pidfile</c> if possible, though you should test this to be sure.
589 Otherwise, don't use pidfiles. You can also add <c>--quiet</c> to the
590 <c>start-stop-daemon</c> options, but this is not recommended unless the
591 service is extremely verbose. Using <c>--quiet</c> may hinder debugging if the
592 service fails to start.
593 </p>
594
595 <p>
596 Another notable setting used in the above example is to check the contents of
597 the <c>RC_CMD</c> variable. Unlike the previous init script system, the newer
598 <c>openrc</c> system does not support script-specific restart functionality.
599 Instead, the script needs to check the contents of the <c>RC_CMD</c> variable
600 to see if a function (be it <c>start()</c> or <c>stop()</c>) is called as part
601 of a restart or not.
602 </p>
603
604 <note>
605 Make sure that <c>--exec</c> actually calls a service and not just a shell
606 script that launches services and exits -- that's what the init script is
607 supposed to do.
608 </note>
609
610 <p>
611 If you need more examples of the <c>start()</c> function, please read the
612 source code of the available init scripts in your <path>/etc/init.d</path>
613 directory.
614 </p>
615
616 <p>
617 Another function you can define is <c>stop()</c>. You are not obliged to define
618 this function though! Our init system is intelligent enough to fill in this
619 function by itself if you use <c>start-stop-daemon</c>.
620 </p>
621
622 <p>
623 Here is an example of a <c>stop()</c> function:
624 </p>
625
626 <pre caption="Example stop() function">
627 stop() {
628 ebegin "Stopping my_service"
629 start-stop-daemon --stop --exec /path/to/my_service \
630 --pidfile /path/to/my_pidfile
631 eend $?
632 }
633 </pre>
634
635 <p>
636 If your service runs some other script (for example, bash, python, or perl),
637 and this script later changes names (for example, <c>foo.py</c> to <c>foo</c>),
638 then you will need to add <c>--name</c> to <c>start-stop-daemon</c>. You must
639 specify the name that your script will be changed to. In this example, a
640 service starts <c>foo.py</c>, which changes names to <c>foo</c>:
641 </p>
642
643 <pre caption="A service that starts the foo script">
644 start() {
645 ebegin "Starting my_script"
646 start-stop-daemon --start --exec /path/to/my_script \
647 --pidfile /path/to/my_pidfile --name foo
648 eend $?
649 }
650 </pre>
651
652 <p>
653 <c>start-stop-daemon</c> has an excellent man page available if you need more
654 information:
655 </p>
656
657 <pre caption="Getting the man page for start-stop-daemon">
658 $ <i>man start-stop-daemon</i>
659 </pre>
660
661 <p>
662 Gentoo's init script syntax is based on the Bourne Again Shell (bash) so you are
663 free to use bash-compatible constructs inside your init script. However, you may
664 want to write your init scripts to be POSIX-compliant. Future init script
665 systems may allow symlinking <path>/bin/sh</path> to other shells besides
666 bash. Init scripts that rely on bash-only features will then break these
667 configurations.
668 </p>
669
670 </body>
671 </subsection>
672 <subsection>
673 <title>Adding Custom Options</title>
674 <body>
675
676 <p>
677 If you want your init script to support more options than the ones we have
678 already encountered, you should add the option to the <c>opts</c> variable, and
679 create a function with the same name as the option. For instance, to support an
680 option called <c>restartdelay</c>:
681 </p>
682
683 <pre caption="Supporting the restartdelay option">
684 opts="${opts} restartdelay"
685
686 restartdelay() {
687 stop
688 sleep 3 <comment># Wait 3 seconds before starting again</comment>
689 start
690 }
691 </pre>
692
693 <impo>
694 The function <c>restart()</c> cannot be overridden in openrc!
695 </impo>
696
697 </body>
698 </subsection>
699 <subsection>
700 <title>Service Configuration Variables</title>
701 <body>
702
703 <p>
704 You don't have to do anything to support a configuration file in
705 <path>/etc/conf.d</path>: if your init script is executed, the following files
706 are automatically sourced (i.e. the variables are available to use):
707 </p>
708
709 <ul>
710 <li><path>/etc/conf.d/&lt;your init script&gt;</path></li>
711 <li><path>/etc/conf.d/basic</path></li>
712 <li><path>/etc/rc.conf</path></li>
713 </ul>
714
715 <p>
716 Also, if your init script provides a virtual dependency (such as <c>net</c>),
717 the file associated with that dependency (such as <path>/etc/conf.d/net</path>)
718 will be sourced too.
719 </p>
720
721 </body>
722 </subsection>
723 </section>
724 <section>
725 <title>Changing the Runlevel Behaviour</title>
726 <subsection>
727 <title>Who might benefit from this?</title>
728 <body>
729
730 <p>
731 Many laptop users know the situation: at home you need to start <c>net.eth0</c>
732 while you don't want to start <c>net.eth0</c> while you're on the road (as
733 there is no network available). With Gentoo you can alter the runlevel behaviour
734 to your own will.
735 </p>
736
737 <p>
738 For instance you can create a second "default" runlevel which you can boot that
739 has other init scripts assigned to it. You can then select at boottime what
740 default runlevel you want to use.
741 </p>
742
743 </body>
744 </subsection>
745 <subsection>
746 <title>Using softlevel</title>
747 <body>
748
749 <p>
750 First of all, create the runlevel directory for your second "default" runlevel.
751 As an example we create the <path>offline</path> runlevel:
752 </p>
753
754 <pre caption="Creating a runlevel directory">
755 # <i>mkdir /etc/runlevels/offline</i>
756 </pre>
757
758 <p>
759 Add the necessary init scripts to the newly created runlevels. For instance, if
760 you want to have an exact copy of your current <c>default</c> runlevel but
761 without <c>net.eth0</c>:
762 </p>
763
764 <pre caption="Adding the necessary init scripts">
765 <comment>(Copy all services from default runlevel to offline runlevel)</comment>
766 # <i>cd /etc/runlevels/default</i>
767 # <i>for service in *; do rc-update add $service offline; done</i>
768 <comment>(Remove unwanted service from offline runlevel)</comment>
769 # <i>rc-update del net.eth0 offline</i>
770 <comment>(Display active services for offline runlevel)</comment>
771 # <i>rc-update show offline</i>
772 <comment>(Partial sample Output)</comment>
773 acpid | offline
774 domainname | offline
775 local | offline
776 net.eth0 |
777 </pre>
778
779 <p>
780 Even though <c>net.eth0</c> has been removed from the offline runlevel,
781 <c>udev</c> might want to attempt to start any devices it detects and launch the
782 appropriate services, a functionality that is called <e>hotplugging</e>. By
783 default, Gentoo does not enable hotplugging.
784 </p>
785
786 <p>
787 If you do want to enable hotplugging, but only for a selected set of scripts,
788 use the <c>rc_hotplug</c> variable in <path>/etc/rc.conf</path>:
789 </p>
790
791 <pre caption="Disabling device initiated services in /etc/rc.conf">
792 <comment># Allow net.wlan as well as any other service, except those matching net.*
793 # to be hotplugged</comment>
794 rc_hotplug="net.wlan !net.*"
795 </pre>
796
797 <note>
798 For more information on device initiated services, please see the comments
799 inside <path>/etc/rc.conf</path>.
800 </note>
801
802 <p>
803 Now edit your bootloader configuration and add a new entry for the
804 <c>offline</c> runlevel. For instance, in <path>/boot/grub/grub.conf</path>:
805 </p>
806
807 <pre caption="Adding an entry for the offline runlevel">
808 title Gentoo Linux Offline Usage
809 root (hd0,0)
810 kernel (hd0,0)/kernel-2.4.25 root=/dev/hda3 <i>softlevel=offline</i>
811 </pre>
812
813 <p>
814 VoilĂ , you're all set now. If you boot your system and select the newly added
815 entry at boot, the <c>offline</c> runlevel will be used instead of the
816 <c>default</c> one.
817 </p>
818
819 </body>
820 </subsection>
821 <subsection>
822 <title>Using bootlevel</title>
823 <body>
824
825 <p>
826 Using <c>bootlevel</c> is completely analogous to <c>softlevel</c>. The only
827 difference here is that you define a second "boot" runlevel instead of a second
828 "default" runlevel.
829 </p>
830
831 </body>
832 </subsection>
833 </section>
834 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20