/[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.8 Revision 1.33
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.8 2004/01/06 09:57:49 swift Exp $ --> 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 $ -->
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>3</version>
18<date>2011-08-12</date>
19
7<section> 20<section>
8<title>Runlevels</title> 21<title>Runlevels</title>
9<subsection> 22<subsection>
10<title>Booting your System</title> 23<title>Booting your System</title>
11<body> 24<body>
31services you need in order to have a successfully booted system. 44services you need in order to have a successfully booted system.
32</p> 45</p>
33 46
34<p> 47<p>
35Finally, when all scripts are executed, <c>init</c> activates the terminals 48Finally, 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>, 49(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. 50<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 51This process will then make sure you are able to log on through these terminals
39by running <c>login</c>. 52by running <c>login</c>.
40</p> 53</p>
41 54
80configuration file that specifies what actions need to be taken. This 93configuration file that specifies what actions need to be taken. This
81configuration file is <path>/etc/inittab</path>. 94configuration file is <path>/etc/inittab</path>.
82</p> 95</p>
83 96
84<p> 97<p>
85If you remember the boot sequence we have just explained to you, you will 98If 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 99that <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>: 100the following line from <path>/etc/inittab</path>:
88</p> 101</p>
89 102
90<pre caption="The system initialisation line in /etc/inittab"> 103<pre caption="The system initialisation line in /etc/inittab">
91si::sysinit:/sbin/rc sysinit 104si::sysinit:/sbin/rc sysinit
92</pre> 105</pre>
268<pre caption="Requesting a list of all services that require Postfix"> 281<pre caption="Requesting a list of all services that require Postfix">
269# <i>/etc/init.d/postfix needsme</i> 282# <i>/etc/init.d/postfix needsme</i>
270</pre> 283</pre>
271 284
272<p> 285<p>
273Finally, you can ask what dependencies the service requires but that are 286Finally, you can ask what dependencies the service requires that are missing:
274missing:
275</p> 287</p>
276 288
277<pre caption="Requesting a list of missing dependencies for Postfix"> 289<pre caption="Requesting a list of missing dependencies for Postfix">
278# <i>/etc/init.d/postfix broken</i> 290# <i>/etc/init.d/postfix broken</i>
279</pre> 291</pre>
287<title>What is rc-update?</title> 299<title>What is rc-update?</title>
288<body> 300<body>
289 301
290<p> 302<p>
291Gentoo'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
292started 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
293manually, 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
294and init scripts. 306runlevels and init scripts.
295</p> 307</p>
296 308
297<p> 309<p>
298With <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
299<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
321<pre caption="Removing Postfix from the default runlevel"> 333<pre caption="Removing Postfix from the default runlevel">
322# <i>rc-update del postfix default</i> 334# <i>rc-update del postfix default</i>
323</pre> 335</pre>
324 336
325<p> 337<p>
326The <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
327list at which runlevels they will execute: 339list at which runlevels they will execute:
328</p> 340</p>
329 341
330<pre caption="Receiving init script information"> 342<pre caption="Receiving init script information">
331# <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.
332</pre> 349</p>
333 350
334</body> 351</body>
335</subsection> 352</subsection>
336</section> 353</section>
337<section> 354<section>
339<subsection> 356<subsection>
340<title>Why the Need for Extra Configuration?</title> 357<title>Why the Need for Extra Configuration?</title>
341<body> 358<body>
342 359
343<p> 360<p>
344Init scripts can be quite complex. It is therefore not really interesting to 361Init scripts can be quite complex. It is therefore not really desirable to
345have the users directly edit the init script, as it would make it more 362have the users edit the init script directly, as it would make it more
346error-prone. It is however important to be able to configure such a service. For 363error-prone. It is however important to be able to configure such a service. For
347instance, you might want to give more options to the service itself. 364instance, you might want to give more options to the service itself.
348</p> 365</p>
349 366
350<p> 367<p>
351A 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
352to update the init scripts without being afraid that your configuration changes 369able to update the init scripts without the fear that your configuration
353are undone. 370changes will be undone.
354</p> 371</p>
355 372
356</body> 373</body>
357</subsection> 374</subsection>
358<subsection> 375<subsection>
366configuration file called <path>/etc/conf.d/apache2</path>, which can contain 383configuration file called <path>/etc/conf.d/apache2</path>, which can contain
367the 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:
368</p> 385</p>
369 386
370<pre caption="Variable defined in /etc/conf.d/apache2"> 387<pre caption="Variable defined in /etc/conf.d/apache2">
371APACHE2_OPTS="-D PHP4" 388APACHE2_OPTS="-D PHP5"
372</pre> 389</pre>
373 390
374<p> 391<p>
375Such a configuration file contains variables and variables alone (just like 392Such a configuration file contains variables and variables alone (just like
376<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
385<subsection> 402<subsection>
386<title>Do I Have To?</title> 403<title>Do I Have To?</title>
387<body> 404<body>
388 405
389<p> 406<p>
390No. Writing an init script is usually not necessary as Gentoo provides 407No, writing an init script is usually not necessary as Gentoo provides
391ready-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
392installed 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
393have to create an init script. 410have to create an init script.
394</p> 411</p>
395 412
420 <comment>(Commands necessary to start the service)</comment> 437 <comment>(Commands necessary to start the service)</comment>
421} 438}
422 439
423stop() { 440stop() {
424 <comment>(Commands necessary to stop the service)</comment> 441 <comment>(Commands necessary to stop the service)</comment>
425}
426
427restart() {
428 <comment>(Commands necessary to restart the service)</comment>
429} 442}
430</pre> 443</pre>
431 444
432<p> 445<p>
433Any 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
499 512
500<p> 513<p>
501In some cases you might not require a service, but want your service to be 514In 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 515started <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) 516available 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 517<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 518same runlevel are involved). You can provide this information using the
506<c>before</c> or <c>after</c> settings. 519<c>before</c> or <c>after</c> settings.
507</p> 520</p>
508 521
509<p> 522<p>
518} 531}
519</pre> 532</pre>
520 533
521<p> 534<p>
522You can also use the "*" glob to catch all services in the same runlevel, 535You can also use the "*" glob to catch all services in the same runlevel,
523although this isn't adviseable. 536although this isn't advisable.
524</p> 537</p>
525 538
526<pre caption="Running an init script as first script in the runlevel"> 539<pre caption="Running an init script as first script in the runlevel">
527depend() { 540depend() {
528 before * 541 before *
529} 542}
530</pre> 543</pre>
531 544
545<p>
546If your service must write to local disks, it should need <c>localmount</c>. If
547it places anything in <path>/var/run</path> such as a pidfile, then it should
548start after <c>bootmisc</c>:
549</p>
550
551<pre caption="Example depend() function">
552depend() {
553 need localmount
554 after bootmisc
555}
556</pre>
557
532</body> 558</body>
533</subsection> 559</subsection>
534<subsection> 560<subsection>
535<title>Standard Functions</title> 561<title>Standard Functions</title>
536<body> 562<body>
537 563
538<p> 564<p>
539Next to the <c>depend()</c> functionality, you also need to define the 565Next 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 566<c>start()</c> function. This one contains all the commands necessary to
541initialize your service. It is adviseable to use the <c>ebegin</c> and 567initialize 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: 568<c>eend</c> functions to inform the user about what is happening:
543</p> 569</p>
544 570
545<pre caption="Example start() function"> 571<pre caption="Example start() function">
546start() { 572start() {
573 if [ "${RC_CMD}" = "restart" ];
574 then
575 <comment># Do something in case a restart requires more than stop, start</comment>
576 fi
577
547 ebegin "Starting my_service" 578 ebegin "Starting my_service"
548 start-stop-daemon --start --quiet --exec /path/to/my_service 579 start-stop-daemon --start --exec /path/to/my_service \
580 --pidfile /path/to/my_pidfile
549 eend $? 581 eend $?
550} 582}
551</pre> 583</pre>
552 584
553<p> 585<p>
586Both <c>--exec</c> and <c>--pidfile</c> should be used in start and stop
587functions. 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.
589Otherwise, 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
591service is extremely verbose. Using <c>--quiet</c> may hinder debugging if the
592service fails to start.
593</p>
594
595<p>
596Another notable setting used in the above example is to check the contents of
597the <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.
599Instead, the script needs to check the contents of the <c>RC_CMD</c> variable
600to see if a function (be it <c>start()</c> or <c>stop()</c>) is called as part
601of a restart or not.
602</p>
603
604<note>
605Make sure that <c>--exec</c> actually calls a service and not just a shell
606script that launches services and exits -- that's what the init script is
607supposed to do.
608</note>
609
610<p>
554If you need more examples of the <c>start()</c> function, please read the source 611If you need more examples of the <c>start()</c> function, please read the
555code of the available init scripts in your <path>/etc/init.d</path> directory. 612source code of the available init scripts in your <path>/etc/init.d</path>
613directory.
614</p>
615
616<p>
617Another function you can define is <c>stop()</c>. You are not obliged to define
618this function though! Our init system is intelligent enough to fill in this
619function by itself if you use <c>start-stop-daemon</c>.
620</p>
621
622<p>
623Here is an example of a <c>stop()</c> function:
624</p>
625
626<pre caption="Example stop() function">
627stop() {
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>
636If your service runs some other script (for example, bash, python, or perl),
637and this script later changes names (for example, <c>foo.py</c> to <c>foo</c>),
638then you will need to add <c>--name</c> to <c>start-stop-daemon</c>. You must
639specify the name that your script will be changed to. In this example, a
640service 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">
644start() {
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>
556As for <c>start-stop-daemon</c>, there is an excellent man page available if you 653<c>start-stop-daemon</c> has an excellent man page available if you need more
557need more information: 654information:
558</p> 655</p>
559 656
560<pre caption="Getting the man page for start-stop-daemon"> 657<pre caption="Getting the man page for start-stop-daemon">
561# <i>man start-stop-daemon</i> 658$ <i>man start-stop-daemon</i>
562</pre> 659</pre>
563 660
564<p> 661<p>
565Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are 662Gentoo's init script syntax is based on the Bourne Again Shell (bash) so you are
566not obliged to define these functions! Our init system is intelligent enough to 663free to use bash-compatible constructs inside your init script. However, you may
567fill these functions in herself if you use <c>start-stop-daemon</c>. 664want to write your init scripts to be POSIX-compliant. Future init script
665systems may allow symlinking <path>/bin/sh</path> to other shells besides
666bash. Init scripts that rely on bash-only features will then break these
667configurations.
568</p> 668</p>
569 669
570</body> 670</body>
571</subsection> 671</subsection>
572<subsection> 672<subsection>
582 682
583<pre caption="Supporting the restartdelay option"> 683<pre caption="Supporting the restartdelay option">
584opts="${opts} restartdelay" 684opts="${opts} restartdelay"
585 685
586restartdelay() { 686restartdelay() {
587 stop() 687 stop
588 sleep 3 <comment># Wait 3 seconds before starting again</comment> 688 sleep 3 <comment># Wait 3 seconds before starting again</comment>
589 start() 689 start
590} 690}
591</pre> 691</pre>
692
693<impo>
694The function <c>restart()</c> cannot be overridden in openrc!
695</impo>
592 696
593</body> 697</body>
594</subsection> 698</subsection>
595<subsection> 699<subsection>
596<title>Service Configuration Variables</title> 700<title>Service Configuration Variables</title>
615</p> 719</p>
616 720
617</body> 721</body>
618</subsection> 722</subsection>
619</section> 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>
731Many laptop users know the situation: at home you need to start <c>net.eth0</c>
732while you don't want to start <c>net.eth0</c> while you're on the road (as
733there is no network available). With Gentoo you can alter the runlevel behaviour
734to your own will.
735</p>
736
737<p>
738For instance you can create a second "default" runlevel which you can boot that
739has other init scripts assigned to it. You can then select at boottime what
740default runlevel you want to use.
741</p>
742
743</body>
744</subsection>
745<subsection>
746<title>Using softlevel</title>
747<body>
748
749<p>
750First of all, create the runlevel directory for your second "default" runlevel.
751As 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>
759Add the necessary init scripts to the newly created runlevels. For instance, if
760you want to have an exact copy of your current <c>default</c> runlevel but
761without <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>
780Even though <c>net.eth0</c> has been removed from the offline runlevel,
781<c>udev</c> will still attempt to start any devices it detects and launch the
782appropriate services. Therefore, you will need to add each network service you
783do not want started (as well as services for any other devices that may be
784started by udev) to <path>/etc/conf.d/rc</path> as shown.
785</p>
786
787<pre caption="Disabling device initiated services in /etc/conf.d/rc">
788RC_COLDPLUG="yes"
789<comment>(Next, specify the services you do not want automatically started)</comment>
790RC_PLUG_SERVICES="!net.eth0"
791</pre>
792
793<note>
794For more information on device initiated services, please see the comments
795inside <path>/etc/conf.d/rc</path>.
796</note>
797
798<p>
799Now edit your bootloader configuration and add a new entry for the
800<c>offline</c> runlevel. For instance, in <path>/boot/grub/grub.conf</path>:
801</p>
802
803<pre caption="Adding an entry for the offline runlevel">
804title Gentoo Linux Offline Usage
805 root (hd0,0)
806 kernel (hd0,0)/kernel-2.4.25 root=/dev/hda3 <i>softlevel=offline</i>
807</pre>
808
809<p>
810VoilĂ , you're all set now. If you boot your system and select the newly added
811entry at boot, the <c>offline</c> runlevel will be used instead of the
812<c>default</c> one.
813</p>
814
815</body>
816</subsection>
817<subsection>
818<title>Using bootlevel</title>
819<body>
820
821<p>
822Using <c>bootlevel</c> is completely analogous to <c>softlevel</c>. The only
823difference here is that you define a second "boot" runlevel instead of a second
824"default" runlevel.
825</p>
826
827</body>
828</subsection>
829</section>
620</sections> 830</sections>

Legend:
Removed from v.1.8  
changed lines
  Added in v.1.33

  ViewVC Help
Powered by ViewVC 1.1.20