en/handbook/hb-working-rcscripts.xml

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->

<!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.8 2004/01/06 09:57:49 swift Exp $ -->

<sections>
<section>
<title>Runlevels</title>
<subsection>
<title>Booting your System</title>
<body>

<p>
When you boot your system, you will notice lots of text floating by. If you pay
close attention, you will notice this text is the same every time you reboot
your system. The sequence of all these actions is called the <e>boot
sequence</e> and is (more or less) statically defined.
</p>

<p>
First, your boot loader will load the kernel image you have defined in the
boot loader configuration into memory after which it tells the CPU to run the
kernel. When the kernel is loaded and run, it initializes all kernel-specific
structures and tasks and starts the <c>init</c> process.
</p>

<p>
This process then makes sure that all filesystems (defined in
<path>/etc/fstab</path>) are mounted and ready to be used. Then it executes
several scripts located in <path>/etc/init.d</path>, which will start the
services you need in order to have a successfully booted system.
</p>

<p>
Finally, when all scripts are executed, <c>init</c> activates the terminals
(in most cases just the virtual consoles which are hidden beneith <c>Alt-F1</c>,
<c>Alt-F2</c>, etc.) attaching a special process called <c>agetty</c> to it. 
This process will then make sure you are able to log on through these terminals 
by running <c>login</c>.
</p>

</body>
</subsection>
<subsection>
<title>Init Scripts</title>
<body>

<p>
Now <c>init</c> doesn't just execute the scripts in <path>/etc/init.d</path>
randomly. Even more, it doesn't run all scripts in <path>/etc/init.d</path>,
only the scripts it is told to execute. It decides which scripts to execute by 
looking into <path>/etc/runlevels</path>.
</p>

<p>
First, <c>init</c> runs all scripts from <path>/etc/init.d</path> that have
symbolic links inside <path>/etc/runlevels/boot</path>. Usually, it will
start the scripts in alphabetical order, but some scripts have dependency
information in them, telling the system that another script must be run before
they can be started. 
</p>

<p>
When all <path>/etc/runlevels/boot</path> referenced scripts are executed,
<c>init</c> continues with running the scripts that have a symbolic link to them
in <path>/etc/runlevels/default</path>. Again, it will use the alphabetical
order to decide what script to run first, unless a script has dependency
information in it, in which case the order is changed to provide a valid 
start-up sequence.
</p>

</body>
</subsection>
<subsection>
<title>How Init Works</title>
<body>

<p>
Of course <c>init</c> doesn't decide all that by itself. It needs a
configuration file that specifies what actions need to be taken. This
configuration file is <path>/etc/inittab</path>.
</p>

<p>
If you remember the boot sequence we have just explained to you, you will
remember that <c>init</c>'s first action is to mount all filesystems. This is
defined in the following line from <path>/etc/inittab</path>:
</p>

<pre caption="The system initialisation line in /etc/inittab">
si::sysinit:/sbin/rc sysinit
</pre>

<p>
This line tells <c>init</c> that it must run <c>/sbin/rc sysinit</c> to
initialize the system. The <path>/sbin/rc</path> script takes care of the
initialisation, so you might say that <c>init</c> doesn't do much -- it
delegates the task of initialising the system to another process.
</p>

<p>
Second, <c>init</c> executed all scripts that had symbolic links in
<path>/etc/runlevels/boot</path>. This is defined in the following line:
</p>

<pre caption="The system initialisation, continued">
rc::bootwait:/sbin/rc boot
</pre>

<p>
Again the <c>rc</c> script performs the necessary tasks. Note that the option
given to <c>rc</c> (<e>boot</e>) is the same as the subdirectory of
<path>/etc/runlevels</path> that is used.
</p>

<p>
Now <c>init</c> checks its configuration file to see what <e>runlevel</e> it
should run. To decide this, it reads the following line from
<path>/etc/inittab</path>:
</p>

<pre caption="The initdefault line">
id:3:initdefault:
</pre>

<p>
In this case (which the majority of Gentoo users will use), the <e>runlevel</e>
id is 3. Using this information, <c>init</c> checks what it must run to start
<e>runlevel 3</e>:
</p>

<pre caption="The runlevel definitions">
l0:0:wait:/sbin/rc shutdown
l1:S1:wait:/sbin/rc single
l2:2:wait:/sbin/rc nonetwork
l3:3:wait:/sbin/rc default
l4:4:wait:/sbin/rc default
l5:5:wait:/sbin/rc default
l6:6:wait:/sbin/rc reboot
</pre>

<p>
The line that defines level 3, again, uses the <c>rc</c> script to start the
services (now with argument <e>default</e>). Again note that the argument of
<c>rc</c> is the same as the subdirectory from <path>/etc/runlevels</path>.
</p>

<p>
When <c>rc</c> has finished, <c>init</c> decides what virtual consoles it should
activate and what commands need to be run at each console:
</p>

<pre caption="The virtual consoles definition">
c1:12345:respawn:/sbin/agetty 38400 tty1 linux
c2:12345:respawn:/sbin/agetty 38400 tty2 linux
c3:12345:respawn:/sbin/agetty 38400 tty3 linux
c4:12345:respawn:/sbin/agetty 38400 tty4 linux
c5:12345:respawn:/sbin/agetty 38400 tty5 linux
c6:12345:respawn:/sbin/agetty 38400 tty6 linux
</pre>


</body>
</subsection>
<subsection>
<title>What is a runlevel?</title>
<body>

<p>
You have seen that <c>init</c> uses a numbering scheme to decide what
<e>runlevel</e> it should activate. A <e>runlevel</e> is a state in which
your system is running and contains a collection of scripts (runlevel scripts or
<e>initscripts</e>) that must be executed when you enter or leave a runlevel.
</p>

<p>
In Gentoo, there are seven runlevels defined: three internal runlevels, and four
user-defined runlevels. The internal runlevels are called <e>sysinit</e>,
<e>shutdown</e> and <e>reboot</e> and do exactly what their names imply:
initialize the system, powering off the system and rebooting the system.
</p>

<p>
The user-defined runlevels are those with an accompanying
<path>/etc/runlevels</path> subdirectory: <path>boot</path>,
<path>default</path>, <path>nonetwork</path> and <path>single</path>. The
<path>boot</path> runlevel starts all system-necessary services which all other
runlevels use. The remaining three runlevels differ in what services they start:
<path>default</path> is used for day-to-day operations, <path>nonetwork</path>
is used in case no network connectivity is required, and <path>single</path> is
used when you need to fix the system.
</p>

</body>
</subsection>
<subsection>
<title>Working with the Init Scripts</title>
<body>

<p>
The scripts that the <c>rc</c> process starts are called <e>init scripts</e>.
Each script in <path>/etc/init.d</path> can be executed with the arguments
<e>start</e>, <e>stop</e>, <e>restart</e>, <e>pause</e>, <e>zap</e>,
<e>status</e>, <e>ineed</e>, <e>iuse</e>, <e>needsme</e>, <e>usesme</e> or
<e>broken</e>.
</p>

<p>
To start, stop or restart a service (and all depending services), <c>start</c>,
<c>stop</c> and <c>restart</c> should be used:
</p>

<pre caption="Starting Postfix">
# <i>/etc/init.d/postfix start</i>
</pre>

<note>
Only the services that <e>need</e> the given service are stopped or restarted.
The other depending services (those that <e>use</e> the service but don't need
it) are left untouched.
</note>

<p>
If you want to stop a service, but not the services that depend on it, you can
use the <c>pause</c> argument:
</p>

<pre caption="Stopping Postfix but keep the depending services running">
# <i>/etc/init.d/postfix pause</i>
</pre>

<p>
If you want to see what status a service has (started, stopped, paused, ...) you
can use the <c>status</c> argument:
</p>

<pre caption="Status information for postfix">
# <i>/etc/init.d/postfix status</i>
</pre>

<p>
If the status information tells you that the service is running, but you know
that it is not, then you can reset the status information to "stopped" with the 
<c>zap</c> argument:
</p>

<pre caption="Resetting status information for postfix">
# <i>/etc/init.d/postfix zap</i>
</pre>

<p>
To also ask what dependencies the service has, you can use <c>iuse</c> or
<c>ineed</c>. With <c>ineed</c> you can see the services that are really
necessary for the correct functioning of the service. <c>iuse</c> on the other
hand shows the services that can be used by the service, but are not necessary
for the correct functioning.
</p>

<pre caption="Requesting a list of all necessary services on which Postfix depends">
# <i>/etc/init.d/postfix ineed</i>
</pre>

<p>
Similarly, you can ask what services require the service (<c>needsme</c>) or can
use it (<c>usesme</c>):
</p>

<pre caption="Requesting a list of all services that require Postfix">
# <i>/etc/init.d/postfix needsme</i>
</pre>

<p>
Finally, you can ask what dependencies the service requires but that are
missing:
</p>

<pre caption="Requesting a list of missing dependencies for Postfix">
# <i>/etc/init.d/postfix broken</i>
</pre>

</body>
</subsection>
</section>
<section>
<title>Working with rc-update</title>
<subsection>
<title>What is rc-update?</title>
<body>

<p>
Gentoo's init system uses a dependency-tree to decide what service needs to be
started first. As this is a tedious task that we wouldn't want our users to do
manually, we have created tools that ease the administration of the runlevels
and init scripts.
</p>

<p>
With <c>rc-update</c> you can add and remove init scripts to a runlevel. The
<c>rc-update</c> tool will then automatically ask the <c>depscan.sh</c> script
to rebuild the dependency tree.
</p>

</body>
</subsection>
<subsection>
<title>Adding and Removing Services</title>
<body>

<p>
You have already added init scripts to the "default" runlevel during the
installation of Gentoo. At that time you might not have had a clue what the
"default" is for, but now you should. The <c>rc-update</c> script requires a
second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>.
</p>

<p>
To add or remove an init script, just give <c>rc-update</c> the <c>add</c> or
<c>del</c> argument, followed by the init script and the runlevel. For instance:
</p>

<pre caption="Removing Postfix from the default runlevel">
# <i>rc-update del postfix default</i>
</pre>

<p>
The <c>rc-update show</c> command will show all the available init scripts and
list at which runlevels they will execute:
</p>

<pre caption="Receiving init script information">
# <i>rc-update show</i>
</pre>

</body>
</subsection>
</section>
<section>
<title>Configuring Services</title>
<subsection>
<title>Why the Need for Extra Configuration?</title>
<body>

<p>
Init scripts can be quite complex. It is therefore not really interesting to 
have the users directly edit the init script, as it would make it more 
error-prone. It is however important to be able to configure such a service. For
instance, you might want to give more options to the service itself.
</p>

<p>
A second reason to have this configuration outside the init script is to be able
to update the init scripts without being afraid that your configuration changes
are undone.
</p>

</body>
</subsection>
<subsection>
<title>The /etc/conf.d Directory</title>
<body>

<p>
Gentoo provides an easy way to configure such a service: every init script that
can be configured has a file in <path>/etc/conf.d</path>. For instance, the
apache2 initscript (called <path>/etc/init.d/apache2</path>) has a
configuration file called <path>/etc/conf.d/apache2</path>, which can contain
the options you want to give to the Apache 2 server when it is started:
</p>

<pre caption="Variable defined in /etc/conf.d/apache2">
APACHE2_OPTS="-D PHP4"
</pre>

<p>
Such a configuration file contains variables and variables alone (just like
<path>/etc/make.conf</path>), making it very easy to configure services. It also
allows us to provide more information about the variables (as comments).
</p>

</body>
</subsection>
</section>
<section>
<title>Writing Init Scripts</title>
<subsection>
<title>Do I Have To?</title>
<body>

<p>
No. Writing an init script is usually not necessary as Gentoo provides
ready-to-use init scripts for all provided services. However, you might have
installed a service without using Portage, in which case you will most likely
have to create an init script.
</p>

<p>
Do not use the init script provided by the service if it isn't explicitly
written for Gentoo: Gentoo's init scripts are not compatible with the init
scripts used by other distributions!
</p>

</body>
</subsection>
<subsection>
<title>Layout</title>
<body>

<p>
The basic layout of an init script is shown below.
</p>

<pre caption="Basic layout of an init script">
#!/sbin/runscript

depend() {
  <comment>(Dependency information)</comment>
}

start() {
  <comment>(Commands necessary to start the service)</comment>
}

stop() {
  <comment>(Commands necessary to stop the service)</comment>
}

restart() {
  <comment>(Commands necessary to restart the service)</comment>
}
</pre>

<p>
Any init script <e>requires</e> the <c>start()</c> function to be defined. All
other sections are optional.
</p>

</body>
</subsection>
<subsection>
<title>Dependencies</title>
<body>

<p>
There are two dependencies you can define: <c>use</c> and <c>need</c>. As we
have mentioned before, the <c>need</c> dependency is more strict than the
<c>use</c> dependency. Following this dependency type you enter the service
you depend on, or the <e>virtual</e> dependency.
</p>

<p>
A <e>virtual</e> dependency is a dependency that a service provides, but that is
not provided solely by that service. Your init script can depend on a system
logger, but there are many system loggers available (metalogd, syslog-ng,
sysklogd, ...). As you cannot <c>need</c> every single one of them (no sensible
system has all these system loggers installed and running) we made sure that
all these services <c>provide</c> a virtual dependency.
</p>

<p>
Let us take a look at the dependency information for the postfix service.
</p>

<pre caption="Dependency information for Postfix">
depend() {
  need net
  use logger dns
  provide mta
}
</pre>

<p>
As you can see, the postfix service:
</p>

<ul>
  <li>
    requires the (virtual) <c>net</c> dependency (which is provided by, for
    instance, <path>/etc/init.d/net.eth0</path>)
  </li>
  <li>
    uses the (virtual) <c>logger</c> dependency (which is provided by, for 
    instance, <path>/etc/init.d/syslog-ng</path>)
  </li>
  <li>
    uses the (virtual) <c>dns</c> dependency (which is provided by, for
    instance, <path>/etc/init.d/named</path>)
  </li>
  <li>
    provides the (virtual) <c>mta</c> dependency (which is common for all mail 
    servers)
  </li>
</ul>

</body>
</subsection>
<subsection>
<title>Controlling the Order</title>
<body>

<p>
In some cases you might not require a service, but want your service to be
started <c>before</c> (or <c>after</c>) another service <e>if</e> it is
available on the system (note the conditional - this is no dependency anymore)
<e>and</e> ran in the same runlevel (note the conditional - only services in the
same runlevel are involved). You can provide this information using the 
<c>before</c> or <c>after</c> settings.
</p>

<p>
As an example we view the settings of the Portmap service:
</p>

<pre caption="The depend() function in the Portmap service">
depend() {
  need net
  before inetd
  before xinetd
}
</pre>

<p>
You can also use the "*" glob to catch all services in the same runlevel,
although this isn't adviseable.
</p>

<pre caption="Running an init script as first script in the runlevel">
depend() {
  before *
}
</pre>

</body>
</subsection>
<subsection>
<title>Standard Functions</title>
<body>

<p>
Next to the <c>depend()</c> functionality, you also need to define the
<c>start()</c> function. This one contains all the commands necessary to
initialize your service. It is adviseable to use the <c>ebegin</c> and
<c>eend</c> functions to inform the user about what is happening:
</p>

<pre caption="Example start() function">
start() {
  ebegin "Starting my_service"
  start-stop-daemon --start --quiet --exec /path/to/my_service
  eend $?
}
</pre>

<p>
If you need more examples of the <c>start()</c> function, please read the source
code of the available init scripts in your <path>/etc/init.d</path> directory.
As for <c>start-stop-daemon</c>, there is an excellent man page available if you
need more information:
</p>

<pre caption="Getting the man page for start-stop-daemon">
# <i>man start-stop-daemon</i>
</pre>

<p>
Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are
not obliged to define these functions! Our init system is intelligent enough to
fill these functions by itself if you use <c>start-stop-daemon</c>.
</p>

</body>
</subsection>
<subsection>
<title>Adding Custom Options</title>
<body>

<p>
If you want your init script to support more options than the ones we have
already encountered, you should add the option to the <c>opts</c> variable, and
create a function with the same name as the option. For instance, to support an
option called <c>restartdelay</c>:
</p>

<pre caption="Supporting the restartdelay option">
opts="${opts} restartdelay"

restartdelay() {
  stop()
  sleep 3    <comment># Wait 3 seconds before starting again</comment>
  start()
}
</pre>

</body>
</subsection>
<subsection>
<title>Service Configuration Variables</title>
<body>

<p>
You don't have to do anything to support a configuration file in
<path>/etc/conf.d</path>: if your init script is executed, the following files
are automatically sourced (i.e. the variables are available to use):
</p>

<ul>
  <li><path>/etc/conf.d/&lt;your init script&gt;</path></li>
  <li><path>/etc/conf.d/basic</path></li>
  <li><path>/etc/rc.conf</path></li>
</ul>

<p>
Also, if your init script provides a virtual dependency (such as <c>net</c>),
the file associated with that dependency (such as <path>/etc/conf.d/net</path>)
will be sourced too.
</p>

</body>
</subsection>
</section>
</sections>
1	swift	1.1	<!-- The content of this document is licensed under the CC-BY-SA license -->
2			<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->
3
4	swift	1.9	<!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.8 2004/01/06 09:57:49 swift Exp $ -->
5	swift	1.1
6			<sections>
7			<section>
8			<title>Runlevels</title>
9			<subsection>
10	swift	1.4	<title>Booting your System</title>
11			<body>
12
13			<p>
14			When you boot your system, you will notice lots of text floating by. If you pay
15			close attention, you will notice this text is the same every time you reboot
16			your system. The sequence of all these actions is called the <e>boot
17			sequence</e> and is (more or less) statically defined.
18			</p>
19
20			<p>
21			First, your boot loader will load the kernel image you have defined in the
22			boot loader configuration into memory after which it tells the CPU to run the
23	swift	1.6	kernel. When the kernel is loaded and run, it initializes all kernel-specific
24	swift	1.4	structures and tasks and starts the <c>init</c> process.
25			</p>
26
27			<p>
28			This process then makes sure that all filesystems (defined in
29			<path>/etc/fstab</path>) are mounted and ready to be used. Then it executes
30			several scripts located in <path>/etc/init.d</path>, which will start the
31	swift	1.8	services you need in order to have a successfully booted system.
32	swift	1.4	</p>
33
34			<p>
35			Finally, 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>,
37			<c>Alt-F2</c>, etc.) attaching a special process called <c>agetty</c> to it.
38			This process will then make sure you are able to log on through these terminals
39			by running <c>login</c>.
40			</p>
41
42			</body>
43			</subsection>
44			<subsection>
45			<title>Init Scripts</title>
46	swift	1.1	<body>
47
48	swift	1.2	<p>
49	swift	1.4	Now <c>init</c> doesn't just execute the scripts in <path>/etc/init.d</path>
50			randomly. Even more, it doesn't run all scripts in <path>/etc/init.d</path>,
51	swift	1.7	only the scripts it is told to execute. It decides which scripts to execute by
52	swift	1.4	looking into <path>/etc/runlevels</path>.
53			</p>
54
55			<p>
56			First, <c>init</c> runs all scripts from <path>/etc/init.d</path> that have
57			symbolic links inside <path>/etc/runlevels/boot</path>. Usually, it will
58			start the scripts in alphabetical order, but some scripts have dependency
59			information in them, telling the system that another script must be run before
60			they can be started.
61			</p>
62
63			<p>
64			When all <path>/etc/runlevels/boot</path> referenced scripts are executed,
65			<c>init</c> continues with running the scripts that have a symbolic link to them
66			in <path>/etc/runlevels/default</path>. Again, it will use the alphabetical
67			order to decide what script to run first, unless a script has dependency
68	swift	1.7	information in it, in which case the order is changed to provide a valid
69			start-up sequence.
70	swift	1.2	</p>
71
72			</body>
73			</subsection>
74			<subsection>
75	swift	1.4	<title>How Init Works</title>
76	swift	1.2	<body>
77
78			<p>
79	swift	1.4	Of course <c>init</c> doesn't decide all that by itself. It needs a
80			configuration file that specifies what actions need to be taken. This
81			configuration file is <path>/etc/inittab</path>.
82	swift	1.2	</p>
83
84	swift	1.4	<p>
85			If you remember the boot sequence we have just explained to you, you will
86			remember that <c>init</c>'s first action is to mount all filesystems. This is
87			defined in the following line from <path>/etc/inittab</path>:
88			</p>
89
90			<pre caption="The system initialisation line in /etc/inittab">
91	swift	1.2	si::sysinit:/sbin/rc sysinit
92			</pre>
93
94			<p>
95	swift	1.4	This line tells <c>init</c> that it must run <c>/sbin/rc sysinit</c> to
96	swift	1.6	initialize the system. The <path>/sbin/rc</path> script takes care of the
97	swift	1.4	initialisation, so you might say that <c>init</c> doesn't do much -- it
98			delegates the task of initialising the system to another process.
99	swift	1.2	</p>
100
101			<p>
102	swift	1.4	Second, <c>init</c> executed all scripts that had symbolic links in
103			<path>/etc/runlevels/boot</path>. This is defined in the following line:
104	swift	1.2	</p>
105
106	swift	1.4	<pre caption="The system initialisation, continued">
107			rc::bootwait:/sbin/rc boot
108	swift	1.2	</pre>
109
110			<p>
111	swift	1.4	Again the <c>rc</c> script performs the necessary tasks. Note that the option
112			given to <c>rc</c> (<e>boot</e>) is the same as the subdirectory of
113			<path>/etc/runlevels</path> that is used.
114	swift	1.2	</p>
115
116			<p>
117	swift	1.4	Now <c>init</c> checks its configuration file to see what <e>runlevel</e> it
118			should run. To decide this, it reads the following line from
119			<path>/etc/inittab</path>:
120	swift	1.2	</p>
121
122	swift	1.4	<pre caption="The initdefault line">
123			id:3:initdefault:
124			</pre>
125	swift	1.2
126			<p>
127	swift	1.4	In this case (which the majority of Gentoo users will use), the <e>runlevel</e>
128			id is 3. Using this information, <c>init</c> checks what it must run to start
129			<e>runlevel 3</e>:
130	swift	1.2	</p>
131
132	swift	1.4	<pre caption="The runlevel definitions">
133	swift	1.2	l0:0:wait:/sbin/rc shutdown
134			l1:S1:wait:/sbin/rc single
135			l2:2:wait:/sbin/rc nonetwork
136			l3:3:wait:/sbin/rc default
137			l4:4:wait:/sbin/rc default
138			l5:5:wait:/sbin/rc default
139			l6:6:wait:/sbin/rc reboot
140			</pre>
141
142			<p>
143	swift	1.4	The line that defines level 3, again, uses the <c>rc</c> script to start the
144			services (now with argument <e>default</e>). Again note that the argument of
145			<c>rc</c> is the same as the subdirectory from <path>/etc/runlevels</path>.
146	swift	1.2	</p>
147
148			<p>
149	swift	1.4	When <c>rc</c> has finished, <c>init</c> decides what virtual consoles it should
150			activate and what commands need to be run at each console:
151	swift	1.2	</p>
152
153	swift	1.4	<pre caption="The virtual consoles definition">
154			c1:12345:respawn:/sbin/agetty 38400 tty1 linux
155			c2:12345:respawn:/sbin/agetty 38400 tty2 linux
156			c3:12345:respawn:/sbin/agetty 38400 tty3 linux
157			c4:12345:respawn:/sbin/agetty 38400 tty4 linux
158			c5:12345:respawn:/sbin/agetty 38400 tty5 linux
159			c6:12345:respawn:/sbin/agetty 38400 tty6 linux
160			</pre>
161
162	swift	1.1
163			</body>
164			</subsection>
165			<subsection>
166	swift	1.4	<title>What is a runlevel?</title>
167	swift	1.1	<body>
168
169	swift	1.2	<p>
170	swift	1.4	You have seen that <c>init</c> uses a numbering scheme to decide what
171			<e>runlevel</e> it should activate. A <e>runlevel</e> is a state in which
172			your system is running and contains a collection of scripts (runlevel scripts or
173			<e>initscripts</e>) that must be executed when you enter or leave a runlevel.
174			</p>
175
176			<p>
177			In Gentoo, there are seven runlevels defined: three internal runlevels, and four
178			user-defined runlevels. The internal runlevels are called <e>sysinit</e>,
179			<e>shutdown</e> and <e>reboot</e> and do exactly what their names imply:
180	swift	1.6	initialize the system, powering off the system and rebooting the system.
181	swift	1.4	</p>
182
183			<p>
184			The user-defined runlevels are those with an accompanying
185			<path>/etc/runlevels</path> subdirectory: <path>boot</path>,
186			<path>default</path>, <path>nonetwork</path> and <path>single</path>. The
187			<path>boot</path> runlevel starts all system-necessary services which all other
188			runlevels use. The remaining three runlevels differ in what services they start:
189			<path>default</path> is used for day-to-day operations, <path>nonetwork</path>
190			is used in case no network connectivity is required, and <path>single</path> is
191			used when you need to fix the system.
192	swift	1.2	</p>
193
194	swift	1.4	</body>
195			</subsection>
196			<subsection>
197			<title>Working with the Init Scripts</title>
198			<body>
199
200	swift	1.2	<p>
201	swift	1.4	The scripts that the <c>rc</c> process starts are called <e>init scripts</e>.
202	swift	1.2	Each script in <path>/etc/init.d</path> can be executed with the arguments
203			<e>start</e>, <e>stop</e>, <e>restart</e>, <e>pause</e>, <e>zap</e>,
204			<e>status</e>, <e>ineed</e>, <e>iuse</e>, <e>needsme</e>, <e>usesme</e> or
205			<e>broken</e>.
206			</p>
207
208			<p>
209			To start, stop or restart a service (and all depending services), <c>start</c>,
210			<c>stop</c> and <c>restart</c> should be used:
211			</p>
212
213			<pre caption="Starting Postfix">
214			# <i>/etc/init.d/postfix start</i>
215			</pre>
216	swift	1.4
217			<note>
218			Only the services that <e>need</e> the given service are stopped or restarted.
219			The other depending services (those that <e>use</e> the service but don't need
220			it) are left untouched.
221			</note>
222	swift	1.2
223			<p>
224			If you want to stop a service, but not the services that depend on it, you can
225			use the <c>pause</c> argument:
226			</p>
227
228			<pre caption="Stopping Postfix but keep the depending services running">
229			# <i>/etc/init.d/postfix pause</i>
230			</pre>
231
232			<p>
233			If you want to see what status a service has (started, stopped, paused, ...) you
234			can use the <c>status</c> argument:
235			</p>
236
237			<pre caption="Status information for postfix">
238			# <i>/etc/init.d/postfix status</i>
239			</pre>
240
241			<p>
242	swift	1.3	If the status information tells you that the service is running, but you know
243			that it is not, then you can reset the status information to "stopped" with the
244			<c>zap</c> argument:
245	swift	1.2	</p>
246
247			<pre caption="Resetting status information for postfix">
248			# <i>/etc/init.d/postfix zap</i>
249			</pre>
250
251			<p>
252			To also ask what dependencies the service has, you can use <c>iuse</c> or
253			<c>ineed</c>. With <c>ineed</c> you can see the services that are really
254			necessary for the correct functioning of the service. <c>iuse</c> on the other
255			hand shows the services that can be used by the service, but are not necessary
256			for the correct functioning.
257			</p>
258
259			<pre caption="Requesting a list of all necessary services on which Postfix depends">
260			# <i>/etc/init.d/postfix ineed</i>
261			</pre>
262
263			<p>
264			Similarly, you can ask what services require the service (<c>needsme</c>) or can
265			use it (<c>usesme</c>):
266			</p>
267
268			<pre caption="Requesting a list of all services that require Postfix">
269			# <i>/etc/init.d/postfix needsme</i>
270			</pre>
271
272			<p>
273			Finally, you can ask what dependencies the service requires but that are
274			missing:
275			</p>
276
277			<pre caption="Requesting a list of missing dependencies for Postfix">
278			# <i>/etc/init.d/postfix broken</i>
279			</pre>
280	swift	1.1
281			</body>
282			</subsection>
283			</section>
284			<section>
285			<title>Working with rc-update</title>
286			<subsection>
287			<title>What is rc-update?</title>
288			<body>
289
290	swift	1.2	<p>
291			Gentoo's init system uses a dependency-tree to decide what service needs to be
292			started first. As this is a tedious task that we wouldn't want our users to do
293			manually, we have created tools that ease the administration of the runlevels
294			and init scripts.
295			</p>
296
297			<p>
298			With <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
300			to rebuild the dependency tree.
301			</p>
302
303	swift	1.1	</body>
304			</subsection>
305			<subsection>
306			<title>Adding and Removing Services</title>
307			<body>
308
309	swift	1.2	<p>
310			You have already added init scripts to the "default" runlevel during the
311	swift	1.7	installation of Gentoo. At that time you might not have had a clue what the
312	swift	1.2	"default" is for, but now you should. The <c>rc-update</c> script requires a
313			second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>.
314			</p>
315
316			<p>
317			To add or remove an init script, just give <c>rc-update</c> the <c>add</c> or
318			<c>del</c> argument, followed by the init script and the runlevel. For instance:
319			</p>
320
321			<pre caption="Removing Postfix from the default runlevel">
322			# <i>rc-update del postfix default</i>
323			</pre>
324
325			<p>
326			The <c>rc-update show</c> command will show all the available init scripts and
327			list at which runlevels they will execute:
328			</p>
329
330			<pre caption="Receiving init script information">
331			# <i>rc-update show</i>
332			</pre>
333	swift	1.1
334			</body>
335			</subsection>
336			</section>
337			<section>
338			<title>Configuring Services</title>
339			<subsection>
340	swift	1.2	<title>Why the Need for Extra Configuration?</title>
341	swift	1.1	<body>
342
343	swift	1.2	<p>
344	swift	1.5	Init scripts can be quite complex. It is therefore not really interesting to
345			have the users directly edit the init script, as it would make it more
346			error-prone. It is however important to be able to configure such a service. For
347			instance, you might want to give more options to the service itself.
348	swift	1.2	</p>
349
350			<p>
351			A second reason to have this configuration outside the init script is to be able
352			to update the init scripts without being afraid that your configuration changes
353			are undone.
354			</p>
355
356	swift	1.1	</body>
357			</subsection>
358			<subsection>
359			<title>The /etc/conf.d Directory</title>
360			<body>
361
362	swift	1.2	<p>
363			Gentoo provides an easy way to configure such a service: every init script that
364			can be configured has a file in <path>/etc/conf.d</path>. For instance, the
365			apache2 initscript (called <path>/etc/init.d/apache2</path>) has a
366			configuration file called <path>/etc/conf.d/apache2</path>, which can contain
367			the options you want to give to the Apache 2 server when it is started:
368			</p>
369
370			<pre caption="Variable defined in /etc/conf.d/apache2">
371			APACHE2_OPTS="-D PHP4"
372			</pre>
373
374			<p>
375			Such 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
377			allows us to provide more information about the variables (as comments).
378			</p>
379
380	swift	1.1	</body>
381			</subsection>
382			</section>
383			<section>
384	swift	1.2	<title>Writing Init Scripts</title>
385	swift	1.1	<subsection>
386			<title>Do I Have To?</title>
387			<body>
388
389	swift	1.2	<p>
390			No. Writing an init script is usually not necessary as Gentoo provides
391			ready-to-use init scripts for all provided services. However, you might have
392			installed a service without using Portage, in which case you will most likely
393			have to create an init script.
394			</p>
395
396			<p>
397			Do not use the init script provided by the service if it isn't explicitly
398			written for Gentoo: Gentoo's init scripts are not compatible with the init
399			scripts used by other distributions!
400			</p>
401
402	swift	1.1	</body>
403			</subsection>
404			<subsection>
405			<title>Layout</title>
406			<body>
407
408	swift	1.2	<p>
409			The basic layout of an init script is shown below.
410			</p>
411
412			<pre caption="Basic layout of an init script">
413			#!/sbin/runscript
414
415			depend() {
416			<comment>(Dependency information)</comment>
417			}
418
419			start() {
420			<comment>(Commands necessary to start the service)</comment>
421			}
422
423			stop() {
424			<comment>(Commands necessary to stop the service)</comment>
425			}
426
427			restart() {
428			<comment>(Commands necessary to restart the service)</comment>
429			}
430			</pre>
431
432			<p>
433			Any init script <e>requires</e> the <c>start()</c> function to be defined. All
434			other sections are optional.
435			</p>
436
437	swift	1.1	</body>
438			</subsection>
439			<subsection>
440			<title>Dependencies</title>
441			<body>
442
443	swift	1.2	<p>
444			There are two dependencies you can define: <c>use</c> and <c>need</c>. As we
445			have mentioned before, the <c>need</c> dependency is more strict than the
446			<c>use</c> dependency. Following this dependency type you enter the service
447			you depend on, or the <e>virtual</e> dependency.
448			</p>
449
450			<p>
451			A <e>virtual</e> dependency is a dependency that a service provides, but that is
452			not provided solely by that service. Your init script can depend on a system
453			logger, but there are many system loggers available (metalogd, syslog-ng,
454			sysklogd, ...). As you cannot <c>need</c> every single one of them (no sensible
455			system has all these system loggers installed and running) we made sure that
456			all these services <c>provide</c> a virtual dependency.
457			</p>
458
459			<p>
460			Let us take a look at the dependency information for the postfix service.
461			</p>
462
463			<pre caption="Dependency information for Postfix">
464			depend() {
465			need net
466			use logger dns
467			provide mta
468			}
469			</pre>
470
471			<p>
472			As you can see, the postfix service:
473			</p>
474
475			<ul>
476			<li>
477			requires the (virtual) <c>net</c> dependency (which is provided by, for
478			instance, <path>/etc/init.d/net.eth0</path>)
479			</li>
480			<li>
481			uses the (virtual) <c>logger</c> dependency (which is provided by, for
482			instance, <path>/etc/init.d/syslog-ng</path>)
483			</li>
484			<li>
485			uses the (virtual) <c>dns</c> dependency (which is provided by, for
486			instance, <path>/etc/init.d/named</path>)
487			</li>
488			<li>
489			provides the (virtual) <c>mta</c> dependency (which is common for all mail
490			servers)
491			</li>
492			</ul>
493
494	swift	1.1	</body>
495			</subsection>
496			<subsection>
497			<title>Controlling the Order</title>
498			<body>
499
500	swift	1.2	<p>
501			In some cases you might not require a service, but want your service to be
502			started <c>before</c> (or <c>after</c>) another service <e>if</e> it is
503			available 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
505			same runlevel are involved). You can provide this information using the
506			<c>before</c> or <c>after</c> settings.
507			</p>
508
509			<p>
510			As an example we view the settings of the Portmap service:
511			</p>
512
513			<pre caption="The depend() function in the Portmap service">
514			depend() {
515			need net
516			before inetd
517			before xinetd
518			}
519			</pre>
520
521			<p>
522			You can also use the "*" glob to catch all services in the same runlevel,
523			although this isn't adviseable.
524			</p>
525
526			<pre caption="Running an init script as first script in the runlevel">
527			depend() {
528			before *
529			}
530			</pre>
531	swift	1.1
532			</body>
533			</subsection>
534			<subsection>
535			<title>Standard Functions</title>
536			<body>
537
538	swift	1.2	<p>
539			Next 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
541	swift	1.6	initialize your service. It is adviseable to use the <c>ebegin</c> and
542	swift	1.2	<c>eend</c> functions to inform the user about what is happening:
543			</p>
544
545			<pre caption="Example start() function">
546			start() {
547			ebegin "Starting my_service"
548			start-stop-daemon --start --quiet --exec /path/to/my_service
549			eend $?
550			}
551			</pre>
552
553			<p>
554			If you need more examples of the <c>start()</c> function, please read the source
555			code of the available init scripts in your <path>/etc/init.d</path> directory.
556			As for <c>start-stop-daemon</c>, there is an excellent man page available if you
557			need more information:
558			</p>
559
560			<pre caption="Getting the man page for start-stop-daemon">
561			# <i>man start-stop-daemon</i>
562			</pre>
563
564			<p>
565			Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are
566			not obliged to define these functions! Our init system is intelligent enough to
567	swift	1.9	fill these functions by itself if you use <c>start-stop-daemon</c>.
568	swift	1.2	</p>
569
570	swift	1.1	</body>
571			</subsection>
572			<subsection>
573			<title>Adding Custom Options</title>
574			<body>
575
576	swift	1.2	<p>
577			If you want your init script to support more options than the ones we have
578			already encountered, you should add the option to the <c>opts</c> variable, and
579			create a function with the same name as the option. For instance, to support an
580			option called <c>restartdelay</c>:
581			</p>
582
583			<pre caption="Supporting the restartdelay option">
584			opts="${opts} restartdelay"
585
586			restartdelay() {
587			stop()
588			sleep 3 <comment># Wait 3 seconds before starting again</comment>
589			start()
590			}
591			</pre>
592
593	swift	1.1	</body>
594			</subsection>
595			<subsection>
596			<title>Service Configuration Variables</title>
597			<body>
598	swift	1.2
599			<p>
600			You don't have to do anything to support a configuration file in
601			<path>/etc/conf.d</path>: if your init script is executed, the following files
602			are automatically sourced (i.e. the variables are available to use):
603			</p>
604
605			<ul>
606			<li><path>/etc/conf.d/<your init script></path></li>
607			<li><path>/etc/conf.d/basic</path></li>
608			<li><path>/etc/rc.conf</path></li>
609			</ul>
610
611			<p>
612			Also, if your init script provides a virtual dependency (such as <c>net</c>),
613			the file associated with that dependency (such as <path>/etc/conf.d/net</path>)
614			will be sourced too.
615			</p>
616	swift	1.1
617			</body>
618			</subsection>
619			</section>
620			</sections>