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.1 2003/11/20 10:52:35 swift Exp $ -->

<sections>
<section>
<title>Runlevels</title>
<subsection>
<title>What is a runlevel?</title>
<body>

<p>
When you boot your system, a number of tasks need to be performed before you are
able to log on. This "normal" boot operation is fully defined -- it will be the
same every time you restart your system. 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>

</body>
</subsection>
<subsection>
<title>Booting your System</title>
<body>

<p>
The process that takes care of the runlevels is called <c>init</c> and is also
the first process started by the Linux kernel. <c>init</c>'s configuration file
is called <path>/etc/inittab</path> and gets read immediately after <c>init</c>
is started. In this configuration file, the commands used to enter a certain 
runlevel are listed. For instance, after initialising the system (<e>si</e>), 
the <b>boot</b> runlevel is started:
</p>

<pre caption="System initialisation lines in /etc/inittab">
si::sysinit:/sbin/rc sysinit
rc::bootwait:/sbin/rc boot
</pre>

<p>
As you can see, <c>init</c> relies on the <c>rc</c> script. When started with 
the "boot" argument, <c>rc</c> starts all scripts in the
<path>/etc/runlevels/boot</path> directory. Don't think about the sequence used
to start the scripts -- we will explain later how Gentoo uses dependencies for
the init scripts.
</p>

<p>
When the <b>boot</b> runlevel is completed (the boot runlevel is an intermediate
one), <c>init</c> checks what runlevel it should start. If you have not defined
one as kernel parameter, it will  use the one defined in
<path>/etc/inittab</path>:
</p>

<pre caption="Default runlevel">
id:3:initdefault:
</pre>

<p>
In this case, the runlevel id is "3", and gets mapped to:
</p>

<pre caption="Mapping from number to readable commands in /etc/inittab">
l3:3:wait:/sbin/rc default
</pre>

<p>
In other words, the <c>rc</c> script is asked to activate the <b>default</b>
runlevel. Again, this results in executing all
<path>/etc/runlevels/default</path> scripts.
</p>

</body>
</subsection>
<subsection>
<title>Numbers and Names</title>
<body>

<p>
When you take a look at <path>/etc/inittab</path>, you will see the following
section:
</p>

<pre caption="Defining the runlevels in /etc/inittab">
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>
As you can see, there is a mapping of numbers to names (not vice versa). For
instance, 0 maps to "shutdown", 1 to "single" etc. Vice versa is not true, as
"default" is used by 3, 4 and 5. These numbers are the runlevel numbers. Most
distributions work with the numbers; Gentoo however decided to make it a bit
more userfriendly and continue with the naming.  
</p>

<p>
As you can see from the listings, Gentoo defines 7 runlevels. Three of them are
internal runlevels: <e>sysinit</e>, <e>shutdown</e> and <e>reboot</e>. The
<b>sysinit</b> runlevel mounts all necessary filesystems as defined in
<path>/etc/fstab</path>. The <b>shutdown</b> runlevel shuts down all running
services and powers down the system. The <b>reboot</b> runlevel acts like the
<e>shutdown</e> runlevel, but reboots the system instead of powering down.
</p>

<p>
The other four runlevels are <e>boot</e>, <e>default</e>, <e>nonetwork</e> and
<e>single</e>. Each of them has a subdirectory in <path>/etc/runlevels</path>
containing scripts that need to be started when the runlevel is activated.
</p>

</body>
</subsection>
<subsection>
<title>Working with the initscripts</title>
<body>

<p>
If you take a closer look to <path>/etc/runlevels/default</path>, you will
notice that it contains symbolic links to identically named scripts located in
<path>/etc/init.d</path> and not just scripts as we mentioned previously. For 
instance, <path>/etc/runlevels/default/postfix</path> is a symbolic link to
<path>/etc/init.d/postfix</path>. In general we can say that such a script
provides a service...
</p>

<p>
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>

<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 it doesn't,
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 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 therefor 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
initialise 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 in herself 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.2	<!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.1 2003/11/20 10:52:35 swift Exp $ -->
5	swift	1.1
6			<sections>
7			<section>
8			<title>Runlevels</title>
9			<subsection>
10			<title>What is a runlevel?</title>
11			<body>
12
13	swift	1.2	<p>
14			When you boot your system, a number of tasks need to be performed before you are
15			able to log on. This "normal" boot operation is fully defined -- it will be the
16			same every time you restart your system. A <e>runlevel</e> is a state in which
17			your system is running and contains a collection of scripts (runlevel scripts or
18			<e>initscripts</e>) that must be executed when you enter or leave a runlevel.
19			</p>
20
21			</body>
22			</subsection>
23			<subsection>
24			<title>Booting your System</title>
25			<body>
26
27			<p>
28			The process that takes care of the runlevels is called <c>init</c> and is also
29			the first process started by the Linux kernel. <c>init</c>'s configuration file
30			is called <path>/etc/inittab</path> and gets read immediately after <c>init</c>
31			is started. In this configuration file, the commands used to enter a certain
32			runlevel are listed. For instance, after initialising the system (<e>si</e>),
33			the <b>boot</b> runlevel is started:
34			</p>
35
36			<pre caption="System initialisation lines in /etc/inittab">
37			si::sysinit:/sbin/rc sysinit
38			rc::bootwait:/sbin/rc boot
39			</pre>
40
41			<p>
42			As you can see, <c>init</c> relies on the <c>rc</c> script. When started with
43			the "boot" argument, <c>rc</c> starts all scripts in the
44			<path>/etc/runlevels/boot</path> directory. Don't think about the sequence used
45			to start the scripts -- we will explain later how Gentoo uses dependencies for
46			the init scripts.
47			</p>
48
49			<p>
50			When the <b>boot</b> runlevel is completed (the boot runlevel is an intermediate
51			one), <c>init</c> checks what runlevel it should start. If you have not defined
52			one as kernel parameter, it will use the one defined in
53			<path>/etc/inittab</path>:
54			</p>
55
56			<pre caption="Default runlevel">
57			id:3:initdefault:
58			</pre>
59
60			<p>
61			In this case, the runlevel id is "3", and gets mapped to:
62			</p>
63
64			<pre caption="Mapping from number to readable commands in /etc/inittab">
65			l3:3:wait:/sbin/rc default
66			</pre>
67
68			<p>
69			In other words, the <c>rc</c> script is asked to activate the <b>default</b>
70			runlevel. Again, this results in executing all
71			<path>/etc/runlevels/default</path> scripts.
72			</p>
73
74			</body>
75			</subsection>
76			<subsection>
77			<title>Numbers and Names</title>
78			<body>
79
80			<p>
81			When you take a look at <path>/etc/inittab</path>, you will see the following
82			section:
83			</p>
84
85			<pre caption="Defining the runlevels in /etc/inittab">
86			l0:0:wait:/sbin/rc shutdown
87			l1:S1:wait:/sbin/rc single
88			l2:2:wait:/sbin/rc nonetwork
89			l3:3:wait:/sbin/rc default
90			l4:4:wait:/sbin/rc default
91			l5:5:wait:/sbin/rc default
92			l6:6:wait:/sbin/rc reboot
93			</pre>
94
95			<p>
96			As you can see, there is a mapping of numbers to names (not vice versa). For
97			instance, 0 maps to "shutdown", 1 to "single" etc. Vice versa is not true, as
98			"default" is used by 3, 4 and 5. These numbers are the runlevel numbers. Most
99			distributions work with the numbers; Gentoo however decided to make it a bit
100			more userfriendly and continue with the naming.
101			</p>
102
103			<p>
104			As you can see from the listings, Gentoo defines 7 runlevels. Three of them are
105			internal runlevels: <e>sysinit</e>, <e>shutdown</e> and <e>reboot</e>. The
106			<b>sysinit</b> runlevel mounts all necessary filesystems as defined in
107			<path>/etc/fstab</path>. The <b>shutdown</b> runlevel shuts down all running
108			services and powers down the system. The <b>reboot</b> runlevel acts like the
109			<e>shutdown</e> runlevel, but reboots the system instead of powering down.
110			</p>
111
112			<p>
113			The other four runlevels are <e>boot</e>, <e>default</e>, <e>nonetwork</e> and
114			<e>single</e>. Each of them has a subdirectory in <path>/etc/runlevels</path>
115			containing scripts that need to be started when the runlevel is activated.
116			</p>
117	swift	1.1
118			</body>
119			</subsection>
120			<subsection>
121	swift	1.2	<title>Working with the initscripts</title>
122	swift	1.1	<body>
123
124	swift	1.2	<p>
125			If you take a closer look to <path>/etc/runlevels/default</path>, you will
126			notice that it contains symbolic links to identically named scripts located in
127			<path>/etc/init.d</path> and not just scripts as we mentioned previously. For
128			instance, <path>/etc/runlevels/default/postfix</path> is a symbolic link to
129			<path>/etc/init.d/postfix</path>. In general we can say that such a script
130			provides a service...
131			</p>
132
133			<p>
134			Each script in <path>/etc/init.d</path> can be executed with the arguments
135			<e>start</e>, <e>stop</e>, <e>restart</e>, <e>pause</e>, <e>zap</e>,
136			<e>status</e>, <e>ineed</e>, <e>iuse</e>, <e>needsme</e>, <e>usesme</e> or
137			<e>broken</e>.
138			</p>
139
140			<p>
141			To start, stop or restart a service (and all depending services), <c>start</c>,
142			<c>stop</c> and <c>restart</c> should be used:
143			</p>
144
145			<pre caption="Starting Postfix">
146			# <i>/etc/init.d/postfix start</i>
147			</pre>
148
149			<p>
150			If you want to stop a service, but not the services that depend on it, you can
151			use the <c>pause</c> argument:
152			</p>
153
154			<pre caption="Stopping Postfix but keep the depending services running">
155			# <i>/etc/init.d/postfix pause</i>
156			</pre>
157
158			<p>
159			If you want to see what status a service has (started, stopped, paused, ...) you
160			can use the <c>status</c> argument:
161			</p>
162
163			<pre caption="Status information for postfix">
164			# <i>/etc/init.d/postfix status</i>
165			</pre>
166
167			<p>
168			If the status information tells you that the service is running, but it doesn't,
169			then you can reset the status information to "stopped" with the <c>zap</c>
170			argument:
171			</p>
172
173			<pre caption="Resetting status information for postfix">
174			# <i>/etc/init.d/postfix zap</i>
175			</pre>
176
177			<p>
178			To also ask what dependencies the service has, you can use <c>iuse</c> or
179			<c>ineed</c>. With <c>ineed</c> you can see the services that are really
180			necessary for the correct functioning of the service. <c>iuse</c> on the other
181			hand shows the services that can be used by the service, but are not necessary
182			for the correct functioning.
183			</p>
184
185			<pre caption="Requesting a list of all necessary services on which Postfix depends">
186			# <i>/etc/init.d/postfix ineed</i>
187			</pre>
188
189			<p>
190			Similarly, you can ask what services require the service (<c>needsme</c>) or can
191			use it (<c>usesme</c>):
192			</p>
193
194			<pre caption="Requesting a list of all services that require Postfix">
195			# <i>/etc/init.d/postfix needsme</i>
196			</pre>
197
198			<p>
199			Finally, you can ask what dependencies the service requires but that are
200			missing:
201			</p>
202
203			<pre caption="Requesting a list of missing dependencies for Postfix">
204			# <i>/etc/init.d/postfix broken</i>
205			</pre>
206	swift	1.1
207			</body>
208			</subsection>
209			</section>
210			<section>
211			<title>Working with rc-update</title>
212			<subsection>
213			<title>What is rc-update?</title>
214			<body>
215
216	swift	1.2	<p>
217			Gentoo's init system uses a dependency-tree to decide what service needs to be
218			started first. As this is a tedious task that we wouldn't want our users to do
219			manually, we have created tools that ease the administration of the runlevels
220			and init scripts.
221			</p>
222
223			<p>
224			With <c>rc-update</c> you can add and remove init scripts to a runlevel. The
225			<c>rc-update</c> tool will then automatically ask the <c>depscan.sh</c> script
226			to rebuild the dependency tree.
227			</p>
228
229	swift	1.1	</body>
230			</subsection>
231			<subsection>
232			<title>Adding and Removing Services</title>
233			<body>
234
235	swift	1.2	<p>
236			You have already added init scripts to the "default" runlevel during the
237			installation of Gentoo. At that time you might not had a clue what the
238			"default" is for, but now you should. The <c>rc-update</c> script requires a
239			second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>.
240			</p>
241
242			<p>
243			To add or remove an init script, just give <c>rc-update</c> the <c>add</c> or
244			<c>del</c> argument, followed by the init script and the runlevel. For instance:
245			</p>
246
247			<pre caption="Removing Postfix from the default runlevel">
248			# <i>rc-update del postfix default</i>
249			</pre>
250
251			<p>
252			The <c>rc-update show</c> command will show all the available init scripts and
253			list at which runlevels they will execute:
254			</p>
255
256			<pre caption="Receiving init script information">
257			# <i>rc-update show</i>
258			</pre>
259	swift	1.1
260			</body>
261			</subsection>
262			</section>
263			<section>
264			<title>Configuring Services</title>
265			<subsection>
266	swift	1.2	<title>Why the Need for Extra Configuration?</title>
267	swift	1.1	<body>
268
269	swift	1.2	<p>
270			Init scripts can be quite complex. It is therefor not really interesting to have
271			the users directly edit the init script, as it would make it more error-prone.
272			It is however important to be able to configure such a service. For instance,
273			you might want to give more options to the service itself.
274			</p>
275
276			<p>
277			A second reason to have this configuration outside the init script is to be able
278			to update the init scripts without being afraid that your configuration changes
279			are undone.
280			</p>
281
282	swift	1.1	</body>
283			</subsection>
284			<subsection>
285			<title>The /etc/conf.d Directory</title>
286			<body>
287
288	swift	1.2	<p>
289			Gentoo provides an easy way to configure such a service: every init script that
290			can be configured has a file in <path>/etc/conf.d</path>. For instance, the
291			apache2 initscript (called <path>/etc/init.d/apache2</path>) has a
292			configuration file called <path>/etc/conf.d/apache2</path>, which can contain
293			the options you want to give to the Apache 2 server when it is started:
294			</p>
295
296			<pre caption="Variable defined in /etc/conf.d/apache2">
297			APACHE2_OPTS="-D PHP4"
298			</pre>
299
300			<p>
301			Such a configuration file contains variables and variables alone (just like
302			<path>/etc/make.conf</path>), making it very easy to configure services. It also
303			allows us to provide more information about the variables (as comments).
304			</p>
305
306	swift	1.1	</body>
307			</subsection>
308			</section>
309			<section>
310	swift	1.2	<title>Writing Init Scripts</title>
311	swift	1.1	<subsection>
312			<title>Do I Have To?</title>
313			<body>
314
315	swift	1.2	<p>
316			No. Writing an init script is usually not necessary as Gentoo provides
317			ready-to-use init scripts for all provided services. However, you might have
318			installed a service without using Portage, in which case you will most likely
319			have to create an init script.
320			</p>
321
322			<p>
323			Do not use the init script provided by the service if it isn't explicitly
324			written for Gentoo: Gentoo's init scripts are not compatible with the init
325			scripts used by other distributions!
326			</p>
327
328	swift	1.1	</body>
329			</subsection>
330			<subsection>
331			<title>Layout</title>
332			<body>
333
334	swift	1.2	<p>
335			The basic layout of an init script is shown below.
336			</p>
337
338			<pre caption="Basic layout of an init script">
339			#!/sbin/runscript
340
341			depend() {
342			<comment>(Dependency information)</comment>
343			}
344
345			start() {
346			<comment>(Commands necessary to start the service)</comment>
347			}
348
349			stop() {
350			<comment>(Commands necessary to stop the service)</comment>
351			}
352
353			restart() {
354			<comment>(Commands necessary to restart the service)</comment>
355			}
356			</pre>
357
358			<p>
359			Any init script <e>requires</e> the <c>start()</c> function to be defined. All
360			other sections are optional.
361			</p>
362
363	swift	1.1	</body>
364			</subsection>
365			<subsection>
366			<title>Dependencies</title>
367			<body>
368
369	swift	1.2	<p>
370			There are two dependencies you can define: <c>use</c> and <c>need</c>. As we
371			have mentioned before, the <c>need</c> dependency is more strict than the
372			<c>use</c> dependency. Following this dependency type you enter the service
373			you depend on, or the <e>virtual</e> dependency.
374			</p>
375
376			<p>
377			A <e>virtual</e> dependency is a dependency that a service provides, but that is
378			not provided solely by that service. Your init script can depend on a system
379			logger, but there are many system loggers available (metalogd, syslog-ng,
380			sysklogd, ...). As you cannot <c>need</c> every single one of them (no sensible
381			system has all these system loggers installed and running) we made sure that
382			all these services <c>provide</c> a virtual dependency.
383			</p>
384
385			<p>
386			Let us take a look at the dependency information for the postfix service.
387			</p>
388
389			<pre caption="Dependency information for Postfix">
390			depend() {
391			need net
392			use logger dns
393			provide mta
394			}
395			</pre>
396
397			<p>
398			As you can see, the postfix service:
399			</p>
400
401			<ul>
402			<li>
403			requires the (virtual) <c>net</c> dependency (which is provided by, for
404			instance, <path>/etc/init.d/net.eth0</path>)
405			</li>
406			<li>
407			uses the (virtual) <c>logger</c> dependency (which is provided by, for
408			instance, <path>/etc/init.d/syslog-ng</path>)
409			</li>
410			<li>
411			uses the (virtual) <c>dns</c> dependency (which is provided by, for
412			instance, <path>/etc/init.d/named</path>)
413			</li>
414			<li>
415			provides the (virtual) <c>mta</c> dependency (which is common for all mail
416			servers)
417			</li>
418			</ul>
419
420	swift	1.1	</body>
421			</subsection>
422			<subsection>
423			<title>Controlling the Order</title>
424			<body>
425
426	swift	1.2	<p>
427			In some cases you might not require a service, but want your service to be
428			started <c>before</c> (or <c>after</c>) another service <e>if</e> it is
429			available on the system (note the conditional - this is no dependency anymore)
430			<e>and</e> ran in the same runlevel (note the conditional - only services in the
431			same runlevel are involved). You can provide this information using the
432			<c>before</c> or <c>after</c> settings.
433			</p>
434
435			<p>
436			As an example we view the settings of the Portmap service:
437			</p>
438
439			<pre caption="The depend() function in the Portmap service">
440			depend() {
441			need net
442			before inetd
443			before xinetd
444			}
445			</pre>
446
447			<p>
448			You can also use the "*" glob to catch all services in the same runlevel,
449			although this isn't adviseable.
450			</p>
451
452			<pre caption="Running an init script as first script in the runlevel">
453			depend() {
454			before *
455			}
456			</pre>
457	swift	1.1
458			</body>
459			</subsection>
460			<subsection>
461			<title>Standard Functions</title>
462			<body>
463
464	swift	1.2	<p>
465			Next to the <c>depend()</c> functionality, you also need to define the
466			<c>start()</c> function. This one contains all the commands necessary to
467			initialise your service. It is adviseable to use the <c>ebegin</c> and
468			<c>eend</c> functions to inform the user about what is happening:
469			</p>
470
471			<pre caption="Example start() function">
472			start() {
473			ebegin "Starting my_service"
474			start-stop-daemon --start --quiet --exec /path/to/my_service
475			eend $?
476			}
477			</pre>
478
479			<p>
480			If you need more examples of the <c>start()</c> function, please read the source
481			code of the available init scripts in your <path>/etc/init.d</path> directory.
482			As for <c>start-stop-daemon</c>, there is an excellent man page available if you
483			need more information:
484			</p>
485
486			<pre caption="Getting the man page for start-stop-daemon">
487			# <i>man start-stop-daemon</i>
488			</pre>
489
490			<p>
491			Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are
492			not obliged to define these functions! Our init system is intelligent enough to
493			fill these functions in herself if you use <c>start-stop-daemon</c>.
494			</p>
495
496	swift	1.1	</body>
497			</subsection>
498			<subsection>
499			<title>Adding Custom Options</title>
500			<body>
501
502	swift	1.2	<p>
503			If you want your init script to support more options than the ones we have
504			already encountered, you should add the option to the <c>opts</c> variable, and
505			create a function with the same name as the option. For instance, to support an
506			option called <c>restartdelay</c>:
507			</p>
508
509			<pre caption="Supporting the restartdelay option">
510			opts="${opts} restartdelay"
511
512			restartdelay() {
513			stop()
514			sleep 3 <comment># Wait 3 seconds before starting again</comment>
515			start()
516			}
517			</pre>
518
519	swift	1.1	</body>
520			</subsection>
521			<subsection>
522			<title>Service Configuration Variables</title>
523			<body>
524	swift	1.2
525			<p>
526			You don't have to do anything to support a configuration file in
527			<path>/etc/conf.d</path>: if your init script is executed, the following files
528			are automatically sourced (i.e. the variables are available to use):
529			</p>
530
531			<ul>
532			<li><path>/etc/conf.d/<your init script></path></li>
533			<li><path>/etc/conf.d/basic</path></li>
534			<li><path>/etc/rc.conf</path></li>
535			</ul>
536
537			<p>
538			Also, if your init script provides a virtual dependency (such as <c>net</c>),
539			the file associated with that dependency (such as <path>/etc/conf.d/net</path>)
540			will be sourced too.
541			</p>
542	swift	1.1
543			</body>
544			</subsection>
545			</section>
546			</sections>