/[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.15 Revision 1.35
1<?xml version='1.0' encoding='UTF-8'?> 1<?xml version='1.0' encoding='UTF-8'?>
2<!DOCTYPE sections SYSTEM "/dtd/book.dtd"> 2<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3 3
4<!-- 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 -->
5<!-- See http://creativecommons.org/licenses/by-sa/1.0 --> 5<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6 6
7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.15 2004/08/28 19:26:18 dertobi123 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 $ -->
8 8
9<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
10<section> 20<section>
11<title>Runlevels</title> 21<title>Runlevels</title>
12<subsection> 22<subsection>
13<title>Booting your System</title> 23<title>Booting your System</title>
14<body> 24<body>
83configuration file that specifies what actions need to be taken. This 93configuration file that specifies what actions need to be taken. This
84configuration file is <path>/etc/inittab</path>. 94configuration file is <path>/etc/inittab</path>.
85</p> 95</p>
86 96
87<p> 97<p>
88If 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
89remember 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
90defined in the following line from <path>/etc/inittab</path>: 100the following line from <path>/etc/inittab</path>:
91</p> 101</p>
92 102
93<pre caption="The system initialisation line in /etc/inittab"> 103<pre caption="The system initialisation line in /etc/inittab">
94si::sysinit:/sbin/rc sysinit 104si::sysinit:/sbin/rc sysinit
95</pre> 105</pre>
271<pre caption="Requesting a list of all services that require Postfix"> 281<pre caption="Requesting a list of all services that require Postfix">
272# <i>/etc/init.d/postfix needsme</i> 282# <i>/etc/init.d/postfix needsme</i>
273</pre> 283</pre>
274 284
275<p> 285<p>
276Finally, you can ask what dependencies the service requires but that are 286Finally, you can ask what dependencies the service requires that are missing:
277missing:
278</p> 287</p>
279 288
280<pre caption="Requesting a list of missing dependencies for Postfix"> 289<pre caption="Requesting a list of missing dependencies for Postfix">
281# <i>/etc/init.d/postfix broken</i> 290# <i>/etc/init.d/postfix broken</i>
282</pre> 291</pre>
290<title>What is rc-update?</title> 299<title>What is rc-update?</title>
291<body> 300<body>
292 301
293<p> 302<p>
294Gentoo'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
295started 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
296manually, 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
297and init scripts. 306runlevels and init scripts.
298</p> 307</p>
299 308
300<p> 309<p>
301With <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
302<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
324<pre caption="Removing Postfix from the default runlevel"> 333<pre caption="Removing Postfix from the default runlevel">
325# <i>rc-update del postfix default</i> 334# <i>rc-update del postfix default</i>
326</pre> 335</pre>
327 336
328<p> 337<p>
329The <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
330list at which runlevels they will execute: 339list at which runlevels they will execute:
331</p> 340</p>
332 341
333<pre caption="Receiving init script information"> 342<pre caption="Receiving init script information">
334# <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.
335</pre> 349</p>
336 350
337</body> 351</body>
338</subsection> 352</subsection>
339</section> 353</section>
340<section> 354<section>
342<subsection> 356<subsection>
343<title>Why the Need for Extra Configuration?</title> 357<title>Why the Need for Extra Configuration?</title>
344<body> 358<body>
345 359
346<p> 360<p>
347Init 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
348have 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
349error-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
350instance, you might want to give more options to the service itself. 364instance, you might want to give more options to the service itself.
351</p> 365</p>
352 366
353<p> 367<p>
354A 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
355to update the init scripts without being afraid that your configuration changes 369able to update the init scripts without the fear that your configuration
356are undone. 370changes will be undone.
357</p> 371</p>
358 372
359</body> 373</body>
360</subsection> 374</subsection>
361<subsection> 375<subsection>
369configuration file called <path>/etc/conf.d/apache2</path>, which can contain 383configuration file called <path>/etc/conf.d/apache2</path>, which can contain
370the 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:
371</p> 385</p>
372 386
373<pre caption="Variable defined in /etc/conf.d/apache2"> 387<pre caption="Variable defined in /etc/conf.d/apache2">
374APACHE2_OPTS="-D PHP4" 388APACHE2_OPTS="-D PHP5"
375</pre> 389</pre>
376 390
377<p> 391<p>
378Such a configuration file contains variables and variables alone (just like 392Such a configuration file contains variables and variables alone (just like
379<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
388<subsection> 402<subsection>
389<title>Do I Have To?</title> 403<title>Do I Have To?</title>
390<body> 404<body>
391 405
392<p> 406<p>
393No. Writing an init script is usually not necessary as Gentoo provides 407No, writing an init script is usually not necessary as Gentoo provides
394ready-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
395installed 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
396have to create an init script. 410have to create an init script.
397</p> 411</p>
398 412
424} 438}
425 439
426stop() { 440stop() {
427 <comment>(Commands necessary to stop the service)</comment> 441 <comment>(Commands necessary to stop the service)</comment>
428} 442}
429
430restart() {
431 <comment>(Commands necessary to restart the service)</comment>
432}
433</pre> 443</pre>
434 444
435<p> 445<p>
436Any 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
437other sections are optional. 447other sections are optional.
442<subsection> 452<subsection>
443<title>Dependencies</title> 453<title>Dependencies</title>
444<body> 454<body>
445 455
446<p> 456<p>
447There 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
448have 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
449<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
450you 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>.
451</p> 509</p>
452 510
453<p> 511<p>
454A <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
455not 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
499<subsection> 557<subsection>
500<title>Controlling the Order</title> 558<title>Controlling the Order</title>
501<body> 559<body>
502 560
503<p> 561<p>
504In 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
505started <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
506available 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
507<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
508same 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
509<c>before</c> or <c>after</c> settings. 567init script.
510</p>
511
512<p>
513As an example we view the settings of the Portmap service:
514</p> 568</p>
515 569
516<pre caption="The depend() function in the Portmap service"> 570<pre caption="The depend() function in the Portmap service">
517depend() { 571depend() {
518 need net 572 need net
521} 575}
522</pre> 576</pre>
523 577
524<p> 578<p>
525You 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,
526although this isn't adviseable. 580although this isn't advisable.
527</p> 581</p>
528 582
529<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">
530depend() { 584depend() {
531 before * 585 before *
532} 586}
533</pre> 587</pre>
534 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
535</body> 602</body>
536</subsection> 603</subsection>
537<subsection> 604<subsection>
538<title>Standard Functions</title> 605<title>Standard Functions</title>
539<body> 606<body>
540 607
541<p> 608<p>
542Next 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
543<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
544initialize 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
545<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:
546</p> 613</p>
547 614
548<pre caption="Example start() function"> 615<pre caption="Example start() function">
549start() { 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
550 ebegin "Starting my_service" 622 ebegin "Starting my_service"
551 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
552 eend $? 625 eend $?
553} 626}
554</pre> 627</pre>
555 628
556<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>
557If 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
558code 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>
559As 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
560need more information: 698information:
561</p> 699</p>
562 700
563<pre caption="Getting the man page for start-stop-daemon"> 701<pre caption="Getting the man page for start-stop-daemon">
564# <i>man start-stop-daemon</i> 702$ <i>man start-stop-daemon</i>
565</pre> 703</pre>
566 704
567<p> 705<p>
568Other 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
569not 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
570fill these functions by itself 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.
571</p> 712</p>
572 713
573</body> 714</body>
574</subsection> 715</subsection>
575<subsection> 716<subsection>
585 726
586<pre caption="Supporting the restartdelay option"> 727<pre caption="Supporting the restartdelay option">
587opts="${opts} restartdelay" 728opts="${opts} restartdelay"
588 729
589restartdelay() { 730restartdelay() {
590 stop() 731 stop
591 sleep 3 <comment># Wait 3 seconds before starting again</comment> 732 sleep 3 <comment># Wait 3 seconds before starting again</comment>
592 start() 733 start
593} 734}
594</pre> 735</pre>
736
737<impo>
738The function <c>restart()</c> cannot be overridden in openrc!
739</impo>
595 740
596</body> 741</body>
597</subsection> 742</subsection>
598<subsection> 743<subsection>
599<title>Service Configuration Variables</title> 744<title>Service Configuration Variables</title>
640</p> 785</p>
641 786
642</body> 787</body>
643</subsection> 788</subsection>
644<subsection> 789<subsection>
645<title>Using SOFTLEVEL</title> 790<title>Using softlevel</title>
646<body> 791<body>
647 792
648<p> 793<p>
649First of all, create the runlevel directory for your second "default" runlevel. 794First of all, create the runlevel directory for your second "default" runlevel.
650As an example we create the <path>offline</path> runlevel: 795As an example we create the <path>offline</path> runlevel:
659you want to have an exact copy of your current <c>default</c> runlevel but 804you want to have an exact copy of your current <c>default</c> runlevel but
660without <c>net.eth0</c>: 805without <c>net.eth0</c>:
661</p> 806</p>
662 807
663<pre caption="Adding the necessary init scripts"> 808<pre caption="Adding the necessary init scripts">
809<comment>(Copy all services from default runlevel to offline runlevel)</comment>
664# <i>ls /etc/runlevels/default</i> 810# <i>cd /etc/runlevels/default</i>
665acpid domainname local net.eth0 netmount postfix syslog-ng vixie-cron 811# <i>for service in *; do rc-update add $service offline; done</i>
666# <i>rc-update add acpid offline</i> 812<comment>(Remove unwanted service from offline runlevel)</comment>
667# <i>rc-update add domainname offline</i> 813# <i>rc-update del net.eth0 offline</i>
814<comment>(Display active services for offline runlevel)</comment>
668# <i>rc-update add local offline</i> 815# <i>rc-update show offline</i>
669# <i>rc-update add syslog-ng offline</i> 816<comment>(Partial sample Output)</comment>
670# <i>rc-update add vixie-cron offline</i> 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.
671</pre> 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>
672 845
673<p> 846<p>
674Now edit your bootloader configuration and add a new entry for the 847Now edit your bootloader configuration and add a new entry for the
675<c>offline</c> runlevel. For instance, in <path>/boot/grub/grub.conf</path>: 848<c>offline</c> runlevel. For instance, in <path>/boot/grub/grub.conf</path>:
676</p> 849</p>
680 root (hd0,0) 853 root (hd0,0)
681 kernel (hd0,0)/kernel-2.4.25 root=/dev/hda3 <i>softlevel=offline</i> 854 kernel (hd0,0)/kernel-2.4.25 root=/dev/hda3 <i>softlevel=offline</i>
682</pre> 855</pre>
683 856
684<p> 857<p>
685Voila, you're all set now. If you boot your system and select the newly added 858Voilà, you're all set now. If you boot your system and select the newly added
686entry at boot, the <c>offline</c> runlevel will be used instead of the 859entry at boot, the <c>offline</c> runlevel will be used instead of the
687<c>default</c> one. 860<c>default</c> one.
688</p> 861</p>
689 862
690</body> 863</body>
691</subsection> 864</subsection>
692<subsection> 865<subsection>
693<title>Using BOOTLEVEL</title> 866<title>Using bootlevel</title>
694<body> 867<body>
695 868
696<p> 869<p>
697Using <c>bootlevel</c> is completely analogous to <c>softlevel</c>. The only 870Using <c>bootlevel</c> is completely analogous to <c>softlevel</c>. The only
698difference here is that you define a second "boot" runlevel instead of a second 871difference here is that you define a second "boot" runlevel instead of a second

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

  ViewVC Help
Powered by ViewVC 1.1.20