/[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.4 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.4 2003/12/03 15:03:41 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>Booting your System</title> 17<title>Booting your System</title>
11<body> 18<body>
18</p> 25</p>
19 26
20<p> 27<p>
21First, your boot loader will load the kernel image you have defined in the 28First, your boot loader will load the kernel image you have defined in the
22boot loader configuration into memory after which it tells the CPU to run the 29boot loader configuration into memory after which it tells the CPU to run the
23kernel. When the kernel is loaded and run, it initialises all kernel-specific 30kernel. When the kernel is loaded and run, it initializes all kernel-specific
24structures and tasks and starts the <c>init</c> process. 31structures and tasks and starts the <c>init</c> process.
25</p> 32</p>
26 33
27<p> 34<p>
28This process then makes sure that all filesystems (defined in 35This process then makes sure that all filesystems (defined in
29<path>/etc/fstab</path>) are mounted and ready to be used. Then it executes 36<path>/etc/fstab</path>) are mounted and ready to be used. Then it executes
30several scripts located in <path>/etc/init.d</path>, which will start the 37several scripts located in <path>/etc/init.d</path>, which will start the
31services you need in order to have a succesfully booted system. 38services you need in order to have a successfully booted system.
32</p> 39</p>
33 40
34<p> 41<p>
35Finally, when all scripts are executed, <c>init</c> activates the terminals 42Finally, when all scripts are executed, <c>init</c> activates the terminals
36(in most cases just the virtual consoles which are hidden beneith <c>Alt-F1</c>, 43(in most cases just the virtual consoles which are hidden beneath <c>Alt-F1</c>,
37<c>Alt-F2</c>, etc.) attaching a special process called <c>agetty</c> to it. 44<c>Alt-F2</c>, etc.) attaching a special process called <c>agetty</c> to it.
38This process will then make sure you are able to log on through these terminals 45This process will then make sure you are able to log on through these terminals
39by running <c>login</c>. 46by running <c>login</c>.
40</p> 47</p>
41 48
46<body> 53<body>
47 54
48<p> 55<p>
49Now <c>init</c> doesn't just execute the scripts in <path>/etc/init.d</path> 56Now <c>init</c> doesn't just execute the scripts in <path>/etc/init.d</path>
50randomly. Even more, it doesn't run all scripts in <path>/etc/init.d</path>, 57randomly. Even more, it doesn't run all scripts in <path>/etc/init.d</path>,
51only the scripts it is told to execute. It decides what scripts to execute by 58only the scripts it is told to execute. It decides which scripts to execute by
52looking into <path>/etc/runlevels</path>. 59looking into <path>/etc/runlevels</path>.
53</p> 60</p>
54 61
55<p> 62<p>
56First, <c>init</c> runs all scripts from <path>/etc/init.d</path> that have 63First, <c>init</c> runs all scripts from <path>/etc/init.d</path> that have
63<p> 70<p>
64When all <path>/etc/runlevels/boot</path> referenced scripts are executed, 71When all <path>/etc/runlevels/boot</path> referenced scripts are executed,
65<c>init</c> continues with running the scripts that have a symbolic link to them 72<c>init</c> continues with running the scripts that have a symbolic link to them
66in <path>/etc/runlevels/default</path>. Again, it will use the alphabetical 73in <path>/etc/runlevels/default</path>. Again, it will use the alphabetical
67order to decide what script to run first, unless a script has dependency 74order to decide what script to run first, unless a script has dependency
68information in it, in which the order is changed to provide a valid start-up 75information in it, in which case the order is changed to provide a valid
69sequence. 76start-up sequence.
70</p> 77</p>
71 78
72</body> 79</body>
73</subsection> 80</subsection>
74<subsection> 81<subsection>
80configuration file that specifies what actions need to be taken. This 87configuration file that specifies what actions need to be taken. This
81configuration file is <path>/etc/inittab</path>. 88configuration file is <path>/etc/inittab</path>.
82</p> 89</p>
83 90
84<p> 91<p>
85If you remember the boot sequence we have just explained to you, you will 92If you remember the boot sequence we have just described, you will remember
86remember that <c>init</c>'s first action is to mount all filesystems. This is 93that <c>init</c>'s first action is to mount all filesystems. This is defined in
87defined in the following line from <path>/etc/inittab</path>: 94the following line from <path>/etc/inittab</path>:
88</p> 95</p>
89 96
90<pre caption="The system initialisation line in /etc/inittab"> 97<pre caption="The system initialisation line in /etc/inittab">
91si::sysinit:/sbin/rc sysinit 98si::sysinit:/sbin/rc sysinit
92</pre> 99</pre>
93 100
94<p> 101<p>
95This line tells <c>init</c> that it must run <c>/sbin/rc sysinit</c> to 102This line tells <c>init</c> that it must run <c>/sbin/rc sysinit</c> to
96initialise the system. The <path>/sbin/rc</path> script takes care of the 103initialize the system. The <path>/sbin/rc</path> script takes care of the
97initialisation, so you might say that <c>init</c> doesn't do much -- it 104initialisation, so you might say that <c>init</c> doesn't do much -- it
98delegates the task of initialising the system to another process. 105delegates the task of initialising the system to another process.
99</p> 106</p>
100 107
101<p> 108<p>
175 182
176<p> 183<p>
177In Gentoo, there are seven runlevels defined: three internal runlevels, and four 184In Gentoo, there are seven runlevels defined: three internal runlevels, and four
178user-defined runlevels. The internal runlevels are called <e>sysinit</e>, 185user-defined runlevels. The internal runlevels are called <e>sysinit</e>,
179<e>shutdown</e> and <e>reboot</e> and do exactly what their names imply: 186<e>shutdown</e> and <e>reboot</e> and do exactly what their names imply:
180initialise the system, powering off the system and rebooting the system. 187initialize the system, powering off the system and rebooting the system.
181</p> 188</p>
182 189
183<p> 190<p>
184The user-defined runlevels are those with an accompanying 191The user-defined runlevels are those with an accompanying
185<path>/etc/runlevels</path> subdirectory: <path>boot</path>, 192<path>/etc/runlevels</path> subdirectory: <path>boot</path>,
268<pre caption="Requesting a list of all services that require Postfix"> 275<pre caption="Requesting a list of all services that require Postfix">
269# <i>/etc/init.d/postfix needsme</i> 276# <i>/etc/init.d/postfix needsme</i>
270</pre> 277</pre>
271 278
272<p> 279<p>
273Finally, you can ask what dependencies the service requires but that are 280Finally, you can ask what dependencies the service requires that are missing:
274missing:
275</p> 281</p>
276 282
277<pre caption="Requesting a list of missing dependencies for Postfix"> 283<pre caption="Requesting a list of missing dependencies for Postfix">
278# <i>/etc/init.d/postfix broken</i> 284# <i>/etc/init.d/postfix broken</i>
279</pre> 285</pre>
287<title>What is rc-update?</title> 293<title>What is rc-update?</title>
288<body> 294<body>
289 295
290<p> 296<p>
291Gentoo'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
292started 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
293manually, 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
294and init scripts. 300runlevels and init scripts.
295</p> 301</p>
296 302
297<p> 303<p>
298With <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
299<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
306<title>Adding and Removing Services</title> 312<title>Adding and Removing Services</title>
307<body> 313<body>
308 314
309<p> 315<p>
310You have already added init scripts to the "default" runlevel during the 316You have already added init scripts to the "default" runlevel during the
311installation 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
312"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
313second 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>.
314</p> 320</p>
315 321
316<p> 322<p>
339<subsection> 345<subsection>
340<title>Why the Need for Extra Configuration?</title> 346<title>Why the Need for Extra Configuration?</title>
341<body> 347<body>
342 348
343<p> 349<p>
344Init 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
345the 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
346It 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
347you might want to give more options to the service itself. 353instance, you might want to give more options to the service itself.
348</p>
349
350<p> 354</p>
355
356<p>
351A 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
352to update the init scripts without being afraid that your configuration changes 358able to update the init scripts without the fear that your configuration
353are undone. 359changes will be undone.
354</p> 360</p>
355 361
356</body> 362</body>
357</subsection> 363</subsection>
358<subsection> 364<subsection>
385<subsection> 391<subsection>
386<title>Do I Have To?</title> 392<title>Do I Have To?</title>
387<body> 393<body>
388 394
389<p> 395<p>
390No. Writing an init script is usually not necessary as Gentoo provides 396No, writing an init script is usually not necessary as Gentoo provides
391ready-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
392installed 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
393have to create an init script. 399have to create an init script.
394</p> 400</p>
395 401
499 505
500<p> 506<p>
501In 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
502started <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
503available on the system (note the conditional - this is no dependency anymore) 509available on the system (note the conditional - this is no dependency anymore)
504<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
505same runlevel are involved). You can provide this information using the 511same runlevel are involved). You can provide this information using the
506<c>before</c> or <c>after</c> settings. 512<c>before</c> or <c>after</c> settings.
507</p> 513</p>
508 514
509<p> 515<p>
518} 524}
519</pre> 525</pre>
520 526
521<p> 527<p>
522You 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,
523although this isn't adviseable. 529although this isn't advisable.
524</p> 530</p>
525 531
526<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">
527depend() { 533depend() {
528 before * 534 before *
536<body> 542<body>
537 543
538<p> 544<p>
539Next 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
540<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
541initialise 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
542<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:
543</p> 549</p>
544 550
545<pre caption="Example start() function"> 551<pre caption="Example start() function">
546start() { 552start() {
562</pre> 568</pre>
563 569
564<p> 570<p>
565Other 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
566not 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
567fill 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>.
568</p> 574</p>
569 575
570</body> 576</body>
571</subsection> 577</subsection>
572<subsection> 578<subsection>
615</p> 621</p>
616 622
617</body> 623</body>
618</subsection> 624</subsection>
619</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>
620</sections> 708</sections>

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

  ViewVC Help
Powered by ViewVC 1.1.20