/[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.26 Revision 1.35
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/2.5 --> 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.26 2006/09/07 08:23:02 nightmorph 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 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
11<version>1.22</version> 17<version>4</version>
12<date>2006-09-07</date> 18<date>2011-08-17</date>
13 19
14<section> 20<section>
15<title>Runlevels</title> 21<title>Runlevels</title>
16<subsection> 22<subsection>
17<title>Booting your System</title> 23<title>Booting your System</title>
327<pre caption="Removing Postfix from the default runlevel"> 333<pre caption="Removing Postfix from the default runlevel">
328# <i>rc-update del postfix default</i> 334# <i>rc-update del postfix default</i>
329</pre> 335</pre>
330 336
331<p> 337<p>
332The <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
333list at which runlevels they will execute: 339list at which runlevels they will execute:
334</p> 340</p>
335 341
336<pre caption="Receiving init script information"> 342<pre caption="Receiving init script information">
337# <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.
338</pre> 349</p>
339 350
340</body> 351</body>
341</subsection> 352</subsection>
342</section> 353</section>
343<section> 354<section>
372configuration file called <path>/etc/conf.d/apache2</path>, which can contain 383configuration file called <path>/etc/conf.d/apache2</path>, which can contain
373the 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:
374</p> 385</p>
375 386
376<pre caption="Variable defined in /etc/conf.d/apache2"> 387<pre caption="Variable defined in /etc/conf.d/apache2">
377APACHE2_OPTS="-D PHP4" 388APACHE2_OPTS="-D PHP5"
378</pre> 389</pre>
379 390
380<p> 391<p>
381Such a configuration file contains variables and variables alone (just like 392Such a configuration file contains variables and variables alone (just like
382<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
427} 438}
428 439
429stop() { 440stop() {
430 <comment>(Commands necessary to stop the service)</comment> 441 <comment>(Commands necessary to stop the service)</comment>
431} 442}
432
433restart() {
434 <comment>(Commands necessary to restart the service)</comment>
435}
436</pre> 443</pre>
437 444
438<p> 445<p>
439Any 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
440other sections are optional. 447other sections are optional.
445<subsection> 452<subsection>
446<title>Dependencies</title> 453<title>Dependencies</title>
447<body> 454<body>
448 455
449<p> 456<p>
450There 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
451have 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
452<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
453you 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>.
454</p> 509</p>
455 510
456<p> 511<p>
457A <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
458not 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
502<subsection> 557<subsection>
503<title>Controlling the Order</title> 558<title>Controlling the Order</title>
504<body> 559<body>
505 560
506<p> 561<p>
507In 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
508started <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
509available 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
510<e>and</e> run 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
511same 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
512<c>before</c> or <c>after</c> settings. 567init script.
513</p>
514
515<p>
516As an example we view the settings of the Portmap service:
517</p> 568</p>
518 569
519<pre caption="The depend() function in the Portmap service"> 570<pre caption="The depend() function in the Portmap service">
520depend() { 571depend() {
521 need net 572 need net
535} 586}
536</pre> 587</pre>
537 588
538<p> 589<p>
539If your service must write to local disks, it should need <c>localmount</c>. If 590If your service must write to local disks, it should need <c>localmount</c>. If
540it places anything in <path>/var/run</path> such as a pidfile, then should 591it places anything in <path>/var/run</path> such as a pidfile, then it should
541start after <c>bootmisc</c>: 592start after <c>bootmisc</c>:
542</p> 593</p>
543 594
544<pre caption="Example depend() function"> 595<pre caption="Example depend() function">
545depend() { 596depend() {
561<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:
562</p> 613</p>
563 614
564<pre caption="Example start() function"> 615<pre caption="Example start() function">
565start() { 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
566 ebegin "Starting my_service" 622 ebegin "Starting my_service"
567 start-stop-daemon --start --exec /path/to/my_service \ 623 start-stop-daemon --start --exec /path/to/my_service \
568 --pidfile /path/to/my_pidfile 624 --pidfile /path/to/my_pidfile
569 eend $? 625 eend $?
570} 626}
578<c>start-stop-daemon</c> options, but this is not recommended unless the 634<c>start-stop-daemon</c> options, but this is not recommended unless the
579service is extremely verbose. Using <c>--quiet</c> may hinder debugging if the 635service is extremely verbose. Using <c>--quiet</c> may hinder debugging if the
580service fails to start. 636service fails to start.
581</p> 637</p>
582 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
583<note> 648<note>
584Make sure that <c>--exec</c> actually calls a service and not just a shell 649Make sure that <c>--exec</c> actually calls a service and not just a shell
585script that launches services and exits -- that's what the init script is 650script that launches services and exits -- that's what the init script is
586supposed to do. 651supposed to do.
587</note> 652</note>
591source code of the available init scripts in your <path>/etc/init.d</path> 656source code of the available init scripts in your <path>/etc/init.d</path>
592directory. 657directory.
593</p> 658</p>
594 659
595<p> 660<p>
596Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are 661Another function you can define is <c>stop()</c>. You are not obliged to define
597not obliged to define these functions! Our init system is intelligent enough to 662this function though! Our init system is intelligent enough to fill in this
598fill these functions by itself if you use <c>start-stop-daemon</c>. 663function by itself if you use <c>start-stop-daemon</c>.
599</p>
600
601<p> 664</p>
602Although you do not <e>have</e> to create a <c>stop()</c> function, here is an 665
603example: 666<p>
667Here is an example of a <c>stop()</c> function:
604</p> 668</p>
605 669
606<pre caption="Example stop() function"> 670<pre caption="Example stop() function">
607stop() { 671stop() {
608 ebegin "Stopping my_service" 672 ebegin "Stopping my_service"
638$ <i>man start-stop-daemon</i> 702$ <i>man start-stop-daemon</i>
639</pre> 703</pre>
640 704
641<p> 705<p>
642Gentoo's init script syntax is based on the Bourne Again Shell (bash) so you are 706Gentoo's init script syntax is based on the Bourne Again Shell (bash) so you are
643free to use bash-compatible constructs inside your init script. 707free to use bash-compatible constructs inside your init script. However, you may
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.
644</p> 712</p>
645 713
646</body> 714</body>
647</subsection> 715</subsection>
648<subsection> 716<subsection>
663 stop 731 stop
664 sleep 3 <comment># Wait 3 seconds before starting again</comment> 732 sleep 3 <comment># Wait 3 seconds before starting again</comment>
665 start 733 start
666} 734}
667</pre> 735</pre>
736
737<impo>
738The function <c>restart()</c> cannot be overridden in openrc!
739</impo>
668 740
669</body> 741</body>
670</subsection> 742</subsection>
671<subsection> 743<subsection>
672<title>Service Configuration Variables</title> 744<title>Service Configuration Variables</title>
747 local | offline 819 local | offline
748 net.eth0 | 820 net.eth0 |
749</pre> 821</pre>
750 822
751<p> 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>
752Now edit your bootloader configuration and add a new entry for the 847Now edit your bootloader configuration and add a new entry for the
753<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>:
754</p> 849</p>
755 850
756<pre caption="Adding an entry for the offline runlevel"> 851<pre caption="Adding an entry for the offline runlevel">

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

  ViewVC Help
Powered by ViewVC 1.1.20