/[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.18 Revision 1.29
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.18 2004/11/09 13:01:52 swift Exp $ --> 7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.29 2007/03/08 06:52:27 nightmorph 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.17</version> 17<version>1.23</version>
12<date>October 23, 2004</date> 18<date>2007-03-07</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>
533depend() { 539depend() {
534 before * 540 before *
535} 541}
536</pre> 542</pre>
537 543
544<p>
545If your service must write to local disks, it should need <c>localmount</c>. If
546it places anything in <path>/var/run</path> such as a pidfile, then it should
547start after <c>bootmisc</c>:
548</p>
549
550<pre caption="Example depend() function">
551depend() {
552 need localmount
553 after bootmisc
554}
555</pre>
556
538</body> 557</body>
539</subsection> 558</subsection>
540<subsection> 559<subsection>
541<title>Standard Functions</title> 560<title>Standard Functions</title>
542<body> 561<body>
549</p> 568</p>
550 569
551<pre caption="Example start() function"> 570<pre caption="Example start() function">
552start() { 571start() {
553 ebegin "Starting my_service" 572 ebegin "Starting my_service"
554 start-stop-daemon --start --quiet --exec /path/to/my_service 573 start-stop-daemon --start --exec /path/to/my_service \
574 --pidfile /path/to/my_pidfile
555 eend $? 575 eend $?
556} 576}
557</pre> 577</pre>
558 578
559<p> 579<p>
580Both <c>--exec</c> and <c>--pidfile</c> should be used in start and stop
581functions. If the service does not create a pidfile, then use
582<c>--make-pidfile</c> if possible, though you should test this to be sure.
583Otherwise, don't use pidfiles. You can also add <c>--quiet</c> to the
584<c>start-stop-daemon</c> options, but this is not recommended unless the
585service is extremely verbose. Using <c>--quiet</c> may hinder debugging if the
586service fails to start.
587</p>
588
589<note>
590Make sure that <c>--exec</c> actually calls a service and not just a shell
591script that launches services and exits -- that's what the init script is
592supposed to do.
593</note>
594
595<p>
560If you need more examples of the <c>start()</c> function, please read the source 596If you need more examples of the <c>start()</c> function, please read the
561code of the available init scripts in your <path>/etc/init.d</path> directory. 597source code of the available init scripts in your <path>/etc/init.d</path>
562As for <c>start-stop-daemon</c>, there is an excellent man page available if you 598directory.
563need more information:
564</p>
565
566<pre caption="Getting the man page for start-stop-daemon">
567# <i>man start-stop-daemon</i>
568</pre> 599</p>
569 600
570<p> 601<p>
571Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are 602Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are
572not obliged to define these functions! Our init system is intelligent enough to 603not obliged to define these functions! Our init system is intelligent enough to
573fill these functions by itself if you use <c>start-stop-daemon</c>. 604fill these functions by itself if you use <c>start-stop-daemon</c>.
605</p>
606
607<p>
608Although you do not <e>have</e> to create a <c>stop()</c> function, here is an
609example:
610</p>
611
612<pre caption="Example stop() function">
613stop() {
614 ebegin "Stopping my_service"
615 start-stop-daemon --stop --exec /path/to/my_service \
616 --pidfile /path/to/my_pidfile
617 eend $?
618}
619</pre>
620
621<p>
622If your service runs some other script (for example, bash, python, or perl),
623and this script later changes names (for example, <c>foo.py</c> to <c>foo</c>),
624then you will need to add <c>--name</c> to <c>start-stop-daemon</c>. You must
625specify the name that your script will be changed to. In this example, a
626service starts <c>foo.py</c>, which changes names to <c>foo</c>:
627</p>
628
629<pre caption="A service that starts the foo script">
630start() {
631 ebegin "Starting my_script"
632 start-stop-daemon --start --exec /path/to/my_script \
633 --pidfile /path/to/my_pidfile --name foo
634 eend $?
635}
636</pre>
637
638<p>
639<c>start-stop-daemon</c> has an excellent man page available if you need more
640information:
641</p>
642
643<pre caption="Getting the man page for start-stop-daemon">
644$ <i>man start-stop-daemon</i>
645</pre>
646
647<p>
648Gentoo's init script syntax is based on the Bourne Again Shell (bash) so you are
649free to use bash-compatible constructs inside your init script.
574</p> 650</p>
575 651
576</body> 652</body>
577</subsection> 653</subsection>
578<subsection> 654<subsection>
588 664
589<pre caption="Supporting the restartdelay option"> 665<pre caption="Supporting the restartdelay option">
590opts="${opts} restartdelay" 666opts="${opts} restartdelay"
591 667
592restartdelay() { 668restartdelay() {
593 stop() 669 stop
594 sleep 3 <comment># Wait 3 seconds before starting again</comment> 670 sleep 3 <comment># Wait 3 seconds before starting again</comment>
595 start() 671 start
596} 672}
597</pre> 673</pre>
598 674
599</body> 675</body>
600</subsection> 676</subsection>
643</p> 719</p>
644 720
645</body> 721</body>
646</subsection> 722</subsection>
647<subsection> 723<subsection>
648<title>Using SOFTLEVEL</title> 724<title>Using softlevel</title>
649<body> 725<body>
650 726
651<p> 727<p>
652First of all, create the runlevel directory for your second "default" runlevel. 728First of all, create the runlevel directory for your second "default" runlevel.
653As an example we create the <path>offline</path> runlevel: 729As an example we create the <path>offline</path> runlevel:
662you want to have an exact copy of your current <c>default</c> runlevel but 738you want to have an exact copy of your current <c>default</c> runlevel but
663without <c>net.eth0</c>: 739without <c>net.eth0</c>:
664</p> 740</p>
665 741
666<pre caption="Adding the necessary init scripts"> 742<pre caption="Adding the necessary init scripts">
743<comment>(Copy all services from default runlevel to offline runlevel)</comment>
667# <i>ls /etc/runlevels/default</i> 744# <i>cd /etc/runlevels/default</i>
668acpid domainname local net.eth0 netmount postfix syslog-ng vixie-cron 745# <i>for service in *; do rc-update add $service offline; done</i>
669# <i>rc-update add acpid offline</i> 746<comment>(Remove unwanted service from offline runlevel)</comment>
670# <i>rc-update add domainname offline</i> 747# <i>rc-update del net.eth0 offline</i>
748<comment>(Display active services for offline runlevel)</comment>
671# <i>rc-update add local offline</i> 749# <i>rc-update show offline</i>
672# <i>rc-update add syslog-ng offline</i> 750<comment>(Partial sample Output)</comment>
673# <i>rc-update add vixie-cron offline</i> 751 acpid | offline
752 domainname | offline
753 local | offline
754 net.eth0 |
755</pre>
756
757<p>
758Even though <c>net.eth0</c> has been removed from the offline runlevel,
759<c>udev</c> will still attempt to start any devices it detects and launch the
760appropriate services. Therefore, you will need to add each network service you
761do not want started (as well as services for any other devices that may be
762started by udev) to <path>/etc/conf.d/rc</path> as shown.
674</pre> 763</p>
764
765<pre caption="Disabling device initiated services in /etc/conf.d/rc">
766RC_COLDPLUG="yes"
767<comment>(Next, specify the services you do not want automatically started)</comment>
768RC_PLUG_SERVICES="!net.eth0"
769</pre>
770
771<note>
772For more information on device initiated services, please see the comments
773inside <path>/etc/conf.d/rc</path>.
774</note>
675 775
676<p> 776<p>
677Now edit your bootloader configuration and add a new entry for the 777Now 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>: 778<c>offline</c> runlevel. For instance, in <path>/boot/grub/grub.conf</path>:
679</p> 779</p>
683 root (hd0,0) 783 root (hd0,0)
684 kernel (hd0,0)/kernel-2.4.25 root=/dev/hda3 <i>softlevel=offline</i> 784 kernel (hd0,0)/kernel-2.4.25 root=/dev/hda3 <i>softlevel=offline</i>
685</pre> 785</pre>
686 786
687<p> 787<p>
688Voila, you're all set now. If you boot your system and select the newly added 788Voilà, 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 789entry at boot, the <c>offline</c> runlevel will be used instead of the
690<c>default</c> one. 790<c>default</c> one.
691</p> 791</p>
692 792
693</body> 793</body>
694</subsection> 794</subsection>
695<subsection> 795<subsection>
696<title>Using BOOTLEVEL</title> 796<title>Using bootlevel</title>
697<body> 797<body>
698 798
699<p> 799<p>
700Using <c>bootlevel</c> is completely analogous to <c>softlevel</c>. The only 800Using <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 801difference here is that you define a second "boot" runlevel instead of a second

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

  ViewVC Help
Powered by ViewVC 1.1.20