/[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.20 Revision 1.34
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.20 2004/11/20 22:23:30 neysx Exp $ --> 7<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.34 2011/08/14 16:12:13 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.17</version> 17<version>3</version>
12<date>2004-10-23</date> 18<date>2011-08-12</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
426 <comment>(Commands necessary to start the service)</comment> 437 <comment>(Commands necessary to start the service)</comment>
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}
432
433restart() {
434 <comment>(Commands necessary to restart the service)</comment>
435} 442}
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
533depend() { 540depend() {
534 before * 541 before *
535} 542}
536</pre> 543</pre>
537 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
538</body> 558</body>
539</subsection> 559</subsection>
540<subsection> 560<subsection>
541<title>Standard Functions</title> 561<title>Standard Functions</title>
542<body> 562<body>
548<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:
549</p> 569</p>
550 570
551<pre caption="Example start() function"> 571<pre caption="Example start() function">
552start() { 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
553 ebegin "Starting my_service" 578 ebegin "Starting my_service"
554 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
555 eend $? 581 eend $?
556} 582}
557</pre> 583</pre>
558 584
559<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>
560If 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
561code 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>
562As 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
563need more information: 654information:
564</p> 655</p>
565 656
566<pre caption="Getting the man page for start-stop-daemon"> 657<pre caption="Getting the man page for start-stop-daemon">
567# <i>man start-stop-daemon</i> 658$ <i>man start-stop-daemon</i>
568</pre> 659</pre>
569 660
570<p> 661<p>
571Other 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
572not 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
573fill these functions by itself 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.
574</p> 668</p>
575 669
576</body> 670</body>
577</subsection> 671</subsection>
578<subsection> 672<subsection>
588 682
589<pre caption="Supporting the restartdelay option"> 683<pre caption="Supporting the restartdelay option">
590opts="${opts} restartdelay" 684opts="${opts} restartdelay"
591 685
592restartdelay() { 686restartdelay() {
593 stop() 687 stop
594 sleep 3 <comment># Wait 3 seconds before starting again</comment> 688 sleep 3 <comment># Wait 3 seconds before starting again</comment>
595 start() 689 start
596} 690}
597</pre> 691</pre>
692
693<impo>
694The function <c>restart()</c> cannot be overridden in openrc!
695</impo>
598 696
599</body> 697</body>
600</subsection> 698</subsection>
601<subsection> 699<subsection>
602<title>Service Configuration Variables</title> 700<title>Service Configuration Variables</title>
643</p> 741</p>
644 742
645</body> 743</body>
646</subsection> 744</subsection>
647<subsection> 745<subsection>
648<title>Using SOFTLEVEL</title> 746<title>Using softlevel</title>
649<body> 747<body>
650 748
651<p> 749<p>
652First of all, create the runlevel directory for your second "default" runlevel. 750First of all, create the runlevel directory for your second "default" runlevel.
653As an example we create the <path>offline</path> runlevel: 751As an example we create the <path>offline</path> runlevel:
662you want to have an exact copy of your current <c>default</c> runlevel but 760you want to have an exact copy of your current <c>default</c> runlevel but
663without <c>net.eth0</c>: 761without <c>net.eth0</c>:
664</p> 762</p>
665 763
666<pre caption="Adding the necessary init scripts"> 764<pre caption="Adding the necessary init scripts">
765<comment>(Copy all services from default runlevel to offline runlevel)</comment>
667# <i>ls /etc/runlevels/default</i> 766# <i>cd /etc/runlevels/default</i>
668acpid domainname local net.eth0 netmount postfix syslog-ng vixie-cron 767# <i>for service in *; do rc-update add $service offline; done</i>
669# <i>rc-update add acpid offline</i> 768<comment>(Remove unwanted service from offline runlevel)</comment>
670# <i>rc-update add domainname offline</i> 769# <i>rc-update del net.eth0 offline</i>
770<comment>(Display active services for offline runlevel)</comment>
671# <i>rc-update add local offline</i> 771# <i>rc-update show offline</i>
672# <i>rc-update add syslog-ng offline</i> 772<comment>(Partial sample Output)</comment>
673# <i>rc-update add vixie-cron offline</i> 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> might want to attempt to start any devices it detects and launch the
782appropriate services, a functionality that is called <e>hotplugging</e>. By
783default, Gentoo does not enable hotplugging.
674</pre> 784</p>
785
786<p>
787If you do want to enable hotplugging, but only for a selected set of scripts,
788use the <c>rc_hotplug</c> variable in <path>/etc/rc.conf</path>:
789</p>
790
791<pre caption="Disabling device initiated services in /etc/rc.conf">
792<comment># Allow net.wlan as well as any other service, except those matching net.*
793# to be hotplugged</comment>
794rc_hotplug="net.wlan !net.*"
795</pre>
796
797<note>
798For more information on device initiated services, please see the comments
799inside <path>/etc/rc.conf</path>.
800</note>
675 801
676<p> 802<p>
677Now edit your bootloader configuration and add a new entry for the 803Now 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>: 804<c>offline</c> runlevel. For instance, in <path>/boot/grub/grub.conf</path>:
679</p> 805</p>
683 root (hd0,0) 809 root (hd0,0)
684 kernel (hd0,0)/kernel-2.4.25 root=/dev/hda3 <i>softlevel=offline</i> 810 kernel (hd0,0)/kernel-2.4.25 root=/dev/hda3 <i>softlevel=offline</i>
685</pre> 811</pre>
686 812
687<p> 813<p>
688Voila, you're all set now. If you boot your system and select the newly added 814Voilà, 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 815entry at boot, the <c>offline</c> runlevel will be used instead of the
690<c>default</c> one. 816<c>default</c> one.
691</p> 817</p>
692 818
693</body> 819</body>
694</subsection> 820</subsection>
695<subsection> 821<subsection>
696<title>Using BOOTLEVEL</title> 822<title>Using bootlevel</title>
697<body> 823<body>
698 824
699<p> 825<p>
700Using <c>bootlevel</c> is completely analogous to <c>softlevel</c>. The only 826Using <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 827difference here is that you define a second "boot" runlevel instead of a second

Legend:
Removed from v.1.20  
changed lines
  Added in v.1.34

  ViewVC Help
Powered by ViewVC 1.1.20