/[gentoo]/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml
Gentoo

Contents of /xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.36 - (hide annotations) (download) (as text)
Sat Sep 17 12:45:11 2011 UTC (3 years ago) by swift
Branch: MAIN
Changes since 1.35: +7 -7 lines
File MIME type: application/xml
Bug #382373 - Use extra_commands instead of opts. Reported by Thomas Kahle

1 swift 1.10 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE sections SYSTEM "/dtd/book.dtd">
3    
4 swift 1.1 <!-- The content of this document is licensed under the CC-BY-SA license -->
5 neysx 1.25 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
6 swift 1.1
7 swift 1.36 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.35 2011/08/17 07:57:23 swift Exp $ -->
8 swift 1.1
9     <sections>
10 swift 1.18
11 neysx 1.27 <abstract>
12     Gentoo uses a special initscript format which, amongst other features, allows
13     dependency-driven decisions and virtual initscripts. This chapter explains all
14     these aspects and explains how to deal with these scripts.
15     </abstract>
16    
17 swift 1.36 <version>5</version>
18     <date>2011-09-17</date>
19 swift 1.18
20 swift 1.1 <section>
21     <title>Runlevels</title>
22     <subsection>
23 swift 1.4 <title>Booting your System</title>
24     <body>
25    
26     <p>
27     When you boot your system, you will notice lots of text floating by. If you pay
28     close attention, you will notice this text is the same every time you reboot
29     your system. The sequence of all these actions is called the <e>boot
30     sequence</e> and is (more or less) statically defined.
31     </p>
32    
33     <p>
34     First, your boot loader will load the kernel image you have defined in the
35     boot loader configuration into memory after which it tells the CPU to run the
36 swift 1.6 kernel. When the kernel is loaded and run, it initializes all kernel-specific
37 swift 1.4 structures and tasks and starts the <c>init</c> process.
38     </p>
39    
40     <p>
41     This process then makes sure that all filesystems (defined in
42     <path>/etc/fstab</path>) are mounted and ready to be used. Then it executes
43     several scripts located in <path>/etc/init.d</path>, which will start the
44 swift 1.8 services you need in order to have a successfully booted system.
45 swift 1.4 </p>
46    
47     <p>
48     Finally, when all scripts are executed, <c>init</c> activates the terminals
49 swift 1.14 (in most cases just the virtual consoles which are hidden beneath <c>Alt-F1</c>,
50 swift 1.4 <c>Alt-F2</c>, etc.) attaching a special process called <c>agetty</c> to it.
51     This process will then make sure you are able to log on through these terminals
52     by running <c>login</c>.
53     </p>
54    
55     </body>
56     </subsection>
57     <subsection>
58     <title>Init Scripts</title>
59 swift 1.1 <body>
60    
61 swift 1.2 <p>
62 swift 1.4 Now <c>init</c> doesn't just execute the scripts in <path>/etc/init.d</path>
63     randomly. Even more, it doesn't run all scripts in <path>/etc/init.d</path>,
64 swift 1.7 only the scripts it is told to execute. It decides which scripts to execute by
65 swift 1.4 looking into <path>/etc/runlevels</path>.
66     </p>
67    
68     <p>
69     First, <c>init</c> runs all scripts from <path>/etc/init.d</path> that have
70     symbolic links inside <path>/etc/runlevels/boot</path>. Usually, it will
71     start the scripts in alphabetical order, but some scripts have dependency
72     information in them, telling the system that another script must be run before
73     they can be started.
74     </p>
75    
76     <p>
77     When all <path>/etc/runlevels/boot</path> referenced scripts are executed,
78     <c>init</c> continues with running the scripts that have a symbolic link to them
79     in <path>/etc/runlevels/default</path>. Again, it will use the alphabetical
80     order to decide what script to run first, unless a script has dependency
81 swift 1.7 information in it, in which case the order is changed to provide a valid
82     start-up sequence.
83 swift 1.2 </p>
84    
85     </body>
86     </subsection>
87     <subsection>
88 swift 1.4 <title>How Init Works</title>
89 swift 1.2 <body>
90    
91     <p>
92 swift 1.4 Of course <c>init</c> doesn't decide all that by itself. It needs a
93     configuration file that specifies what actions need to be taken. This
94     configuration file is <path>/etc/inittab</path>.
95 swift 1.2 </p>
96    
97 swift 1.4 <p>
98 neysx 1.16 If you remember the boot sequence we have just described, you will remember
99     that <c>init</c>'s first action is to mount all filesystems. This is defined in
100     the following line from <path>/etc/inittab</path>:
101 swift 1.4 </p>
102    
103     <pre caption="The system initialisation line in /etc/inittab">
104 swift 1.2 si::sysinit:/sbin/rc sysinit
105     </pre>
106    
107     <p>
108 swift 1.4 This line tells <c>init</c> that it must run <c>/sbin/rc sysinit</c> to
109 swift 1.6 initialize the system. The <path>/sbin/rc</path> script takes care of the
110 swift 1.4 initialisation, so you might say that <c>init</c> doesn't do much -- it
111     delegates the task of initialising the system to another process.
112 swift 1.2 </p>
113    
114     <p>
115 swift 1.4 Second, <c>init</c> executed all scripts that had symbolic links in
116     <path>/etc/runlevels/boot</path>. This is defined in the following line:
117 swift 1.2 </p>
118    
119 swift 1.4 <pre caption="The system initialisation, continued">
120     rc::bootwait:/sbin/rc boot
121 swift 1.2 </pre>
122    
123     <p>
124 swift 1.4 Again the <c>rc</c> script performs the necessary tasks. Note that the option
125     given to <c>rc</c> (<e>boot</e>) is the same as the subdirectory of
126     <path>/etc/runlevels</path> that is used.
127 swift 1.2 </p>
128    
129     <p>
130 swift 1.4 Now <c>init</c> checks its configuration file to see what <e>runlevel</e> it
131     should run. To decide this, it reads the following line from
132     <path>/etc/inittab</path>:
133 swift 1.2 </p>
134    
135 swift 1.4 <pre caption="The initdefault line">
136     id:3:initdefault:
137     </pre>
138 swift 1.2
139     <p>
140 swift 1.4 In this case (which the majority of Gentoo users will use), the <e>runlevel</e>
141     id is 3. Using this information, <c>init</c> checks what it must run to start
142     <e>runlevel 3</e>:
143 swift 1.2 </p>
144    
145 swift 1.4 <pre caption="The runlevel definitions">
146 swift 1.2 l0:0:wait:/sbin/rc shutdown
147     l1:S1:wait:/sbin/rc single
148     l2:2:wait:/sbin/rc nonetwork
149     l3:3:wait:/sbin/rc default
150     l4:4:wait:/sbin/rc default
151     l5:5:wait:/sbin/rc default
152     l6:6:wait:/sbin/rc reboot
153     </pre>
154    
155     <p>
156 swift 1.4 The line that defines level 3, again, uses the <c>rc</c> script to start the
157     services (now with argument <e>default</e>). Again note that the argument of
158     <c>rc</c> is the same as the subdirectory from <path>/etc/runlevels</path>.
159 swift 1.2 </p>
160    
161     <p>
162 swift 1.4 When <c>rc</c> has finished, <c>init</c> decides what virtual consoles it should
163     activate and what commands need to be run at each console:
164 swift 1.2 </p>
165    
166 swift 1.4 <pre caption="The virtual consoles definition">
167     c1:12345:respawn:/sbin/agetty 38400 tty1 linux
168     c2:12345:respawn:/sbin/agetty 38400 tty2 linux
169     c3:12345:respawn:/sbin/agetty 38400 tty3 linux
170     c4:12345:respawn:/sbin/agetty 38400 tty4 linux
171     c5:12345:respawn:/sbin/agetty 38400 tty5 linux
172     c6:12345:respawn:/sbin/agetty 38400 tty6 linux
173     </pre>
174    
175 swift 1.1
176     </body>
177     </subsection>
178     <subsection>
179 swift 1.4 <title>What is a runlevel?</title>
180 swift 1.1 <body>
181    
182 swift 1.2 <p>
183 swift 1.4 You have seen that <c>init</c> uses a numbering scheme to decide what
184     <e>runlevel</e> it should activate. A <e>runlevel</e> is a state in which
185     your system is running and contains a collection of scripts (runlevel scripts or
186     <e>initscripts</e>) that must be executed when you enter or leave a runlevel.
187     </p>
188    
189     <p>
190     In Gentoo, there are seven runlevels defined: three internal runlevels, and four
191     user-defined runlevels. The internal runlevels are called <e>sysinit</e>,
192     <e>shutdown</e> and <e>reboot</e> and do exactly what their names imply:
193 swift 1.6 initialize the system, powering off the system and rebooting the system.
194 swift 1.4 </p>
195    
196     <p>
197     The user-defined runlevels are those with an accompanying
198     <path>/etc/runlevels</path> subdirectory: <path>boot</path>,
199     <path>default</path>, <path>nonetwork</path> and <path>single</path>. The
200     <path>boot</path> runlevel starts all system-necessary services which all other
201     runlevels use. The remaining three runlevels differ in what services they start:
202     <path>default</path> is used for day-to-day operations, <path>nonetwork</path>
203     is used in case no network connectivity is required, and <path>single</path> is
204     used when you need to fix the system.
205 swift 1.2 </p>
206    
207 swift 1.4 </body>
208     </subsection>
209     <subsection>
210     <title>Working with the Init Scripts</title>
211     <body>
212    
213 swift 1.2 <p>
214 swift 1.4 The scripts that the <c>rc</c> process starts are called <e>init scripts</e>.
215 swift 1.2 Each script in <path>/etc/init.d</path> can be executed with the arguments
216     <e>start</e>, <e>stop</e>, <e>restart</e>, <e>pause</e>, <e>zap</e>,
217     <e>status</e>, <e>ineed</e>, <e>iuse</e>, <e>needsme</e>, <e>usesme</e> or
218     <e>broken</e>.
219     </p>
220    
221     <p>
222     To start, stop or restart a service (and all depending services), <c>start</c>,
223     <c>stop</c> and <c>restart</c> should be used:
224     </p>
225    
226     <pre caption="Starting Postfix">
227     # <i>/etc/init.d/postfix start</i>
228     </pre>
229 swift 1.4
230     <note>
231     Only the services that <e>need</e> the given service are stopped or restarted.
232     The other depending services (those that <e>use</e> the service but don't need
233     it) are left untouched.
234     </note>
235 swift 1.2
236     <p>
237     If you want to stop a service, but not the services that depend on it, you can
238     use the <c>pause</c> argument:
239     </p>
240    
241     <pre caption="Stopping Postfix but keep the depending services running">
242     # <i>/etc/init.d/postfix pause</i>
243     </pre>
244    
245     <p>
246     If you want to see what status a service has (started, stopped, paused, ...) you
247     can use the <c>status</c> argument:
248     </p>
249    
250     <pre caption="Status information for postfix">
251     # <i>/etc/init.d/postfix status</i>
252     </pre>
253    
254     <p>
255 swift 1.3 If the status information tells you that the service is running, but you know
256     that it is not, then you can reset the status information to "stopped" with the
257     <c>zap</c> argument:
258 swift 1.2 </p>
259    
260     <pre caption="Resetting status information for postfix">
261     # <i>/etc/init.d/postfix zap</i>
262     </pre>
263    
264     <p>
265     To also ask what dependencies the service has, you can use <c>iuse</c> or
266     <c>ineed</c>. With <c>ineed</c> you can see the services that are really
267     necessary for the correct functioning of the service. <c>iuse</c> on the other
268     hand shows the services that can be used by the service, but are not necessary
269     for the correct functioning.
270     </p>
271    
272     <pre caption="Requesting a list of all necessary services on which Postfix depends">
273     # <i>/etc/init.d/postfix ineed</i>
274     </pre>
275    
276     <p>
277     Similarly, you can ask what services require the service (<c>needsme</c>) or can
278     use it (<c>usesme</c>):
279     </p>
280    
281     <pre caption="Requesting a list of all services that require Postfix">
282     # <i>/etc/init.d/postfix needsme</i>
283     </pre>
284    
285     <p>
286 neysx 1.16 Finally, you can ask what dependencies the service requires that are missing:
287 swift 1.2 </p>
288    
289     <pre caption="Requesting a list of missing dependencies for Postfix">
290     # <i>/etc/init.d/postfix broken</i>
291     </pre>
292 swift 1.1
293     </body>
294     </subsection>
295     </section>
296     <section>
297     <title>Working with rc-update</title>
298     <subsection>
299     <title>What is rc-update?</title>
300     <body>
301    
302 swift 1.2 <p>
303     Gentoo's init system uses a dependency-tree to decide what service needs to be
304 neysx 1.16 started first. As this is a tedious task that we wouldn't want our users to
305     have to do manually, we have created tools that ease the administration of the
306     runlevels and init scripts.
307 swift 1.2 </p>
308    
309     <p>
310     With <c>rc-update</c> you can add and remove init scripts to a runlevel. The
311     <c>rc-update</c> tool will then automatically ask the <c>depscan.sh</c> script
312     to rebuild the dependency tree.
313     </p>
314    
315 swift 1.1 </body>
316     </subsection>
317     <subsection>
318     <title>Adding and Removing Services</title>
319     <body>
320    
321 swift 1.2 <p>
322     You have already added init scripts to the "default" runlevel during the
323 swift 1.7 installation of Gentoo. At that time you might not have had a clue what the
324 swift 1.2 "default" is for, but now you should. The <c>rc-update</c> script requires a
325     second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>.
326     </p>
327    
328     <p>
329     To add or remove an init script, just give <c>rc-update</c> the <c>add</c> or
330     <c>del</c> argument, followed by the init script and the runlevel. For instance:
331     </p>
332    
333     <pre caption="Removing Postfix from the default runlevel">
334     # <i>rc-update del postfix default</i>
335     </pre>
336    
337     <p>
338 nightmorph 1.30 The <c>rc-update -v show</c> command will show all the available init scripts and
339 swift 1.2 list at which runlevels they will execute:
340     </p>
341    
342     <pre caption="Receiving init script information">
343 nightmorph 1.30 # <i>rc-update -v show</i>
344 swift 1.2 </pre>
345 swift 1.1
346 nightmorph 1.30 <p>
347     You can also run <c>rc-update show</c> (without <c>-v</c>) to just view enabled
348     init scripts and their runlevels.
349     </p>
350    
351 swift 1.1 </body>
352     </subsection>
353     </section>
354     <section>
355     <title>Configuring Services</title>
356     <subsection>
357 swift 1.2 <title>Why the Need for Extra Configuration?</title>
358 swift 1.1 <body>
359    
360 swift 1.2 <p>
361 neysx 1.16 Init scripts can be quite complex. It is therefore not really desirable to
362     have the users edit the init script directly, as it would make it more
363 swift 1.5 error-prone. It is however important to be able to configure such a service. For
364     instance, you might want to give more options to the service itself.
365 swift 1.2 </p>
366    
367     <p>
368 neysx 1.16 A second reason to have this configuration outside the init script is to be
369     able to update the init scripts without the fear that your configuration
370     changes will be undone.
371 swift 1.2 </p>
372    
373 swift 1.1 </body>
374     </subsection>
375     <subsection>
376     <title>The /etc/conf.d Directory</title>
377     <body>
378    
379 swift 1.2 <p>
380     Gentoo provides an easy way to configure such a service: every init script that
381     can be configured has a file in <path>/etc/conf.d</path>. For instance, the
382     apache2 initscript (called <path>/etc/init.d/apache2</path>) has a
383     configuration file called <path>/etc/conf.d/apache2</path>, which can contain
384     the options you want to give to the Apache 2 server when it is started:
385     </p>
386    
387     <pre caption="Variable defined in /etc/conf.d/apache2">
388 nightmorph 1.31 APACHE2_OPTS="-D PHP5"
389 swift 1.2 </pre>
390    
391     <p>
392     Such a configuration file contains variables and variables alone (just like
393     <path>/etc/make.conf</path>), making it very easy to configure services. It also
394     allows us to provide more information about the variables (as comments).
395     </p>
396    
397 swift 1.1 </body>
398     </subsection>
399     </section>
400     <section>
401 swift 1.2 <title>Writing Init Scripts</title>
402 swift 1.1 <subsection>
403     <title>Do I Have To?</title>
404     <body>
405    
406 swift 1.2 <p>
407 neysx 1.16 No, writing an init script is usually not necessary as Gentoo provides
408 swift 1.2 ready-to-use init scripts for all provided services. However, you might have
409     installed a service without using Portage, in which case you will most likely
410     have to create an init script.
411     </p>
412    
413     <p>
414     Do not use the init script provided by the service if it isn't explicitly
415     written for Gentoo: Gentoo's init scripts are not compatible with the init
416     scripts used by other distributions!
417     </p>
418    
419 swift 1.1 </body>
420     </subsection>
421     <subsection>
422     <title>Layout</title>
423     <body>
424    
425 swift 1.2 <p>
426     The basic layout of an init script is shown below.
427     </p>
428    
429     <pre caption="Basic layout of an init script">
430     #!/sbin/runscript
431    
432     depend() {
433     <comment>(Dependency information)</comment>
434     }
435    
436     start() {
437     <comment>(Commands necessary to start the service)</comment>
438     }
439    
440     stop() {
441     <comment>(Commands necessary to stop the service)</comment>
442     }
443     </pre>
444    
445     <p>
446     Any init script <e>requires</e> the <c>start()</c> function to be defined. All
447     other sections are optional.
448     </p>
449    
450 swift 1.1 </body>
451     </subsection>
452     <subsection>
453     <title>Dependencies</title>
454     <body>
455    
456 swift 1.2 <p>
457 swift 1.35 There are two dependency-alike settings you can define that influence the
458     start-up or sequencing of init scripts: <c>use</c> and <c>need</c>. Next to
459     these two, there are also two order-influencing methods called <c>before</c> and
460     <c>after</c>. These last two are no dependencies per se - they do not make the
461     original init script fail if the selected one isn't scheduled to start (or fails
462     to start).
463     </p>
464    
465     <ul>
466     <li>
467     The <c>use</c> settings informs the init system that this script <e>uses</e>
468     functionality offered by the selected script, but does not directly depend
469     on it. A good example would be <c>use logger</c> or <c>use dns</c>. If those
470     services are available, they will be put in good use, but if you do not have
471     a logger or DNS server the services will still work. If the services exist,
472     then they are started before the script that <c>use</c>'s them.
473     </li>
474     <li>
475     The <c>need</c> setting is a hard dependency. It means that the script that
476     is <c>need</c>'ing another script will not start before the other script is
477     launched successfully. Also, if that other script is restarted, then this
478     one will be restarted as well.
479     </li>
480     <li>
481     When using <c>before</c>, then the given script is launched before the
482     selected one <e>if</e> the selected one is part of the init level. So an
483     init script <path>xdm</path> that defines <c>before alsasound</c> will start
484     before the <path>alsasound</path> script, but only if <path>alsasound</path>
485     is scheduled to start as well in the same init level. If
486     <path>alsasound</path> is not scheduled to start too, then this particular
487     setting has no effect and <path>xdm</path> will be started when the init
488     system deems it most appropriate.
489     </li>
490     <li>
491     Similarly, <c>after</c> informs the init system that the given script should
492     be launched after the selected one <e>if</e> the selected one is part of the
493     init level. If not, then the setting has no effect and the script will be
494     launched by the init system when it deems it most appropriate.
495     </li>
496     </ul>
497    
498     <p>
499     It should be clear from the above that <c>need</c> is the only "true" dependency
500     setting as it affects if the script will be started or not. All the others are
501     merely pointers towards the init system to clarify in which order scripts can be
502     (or should be) launched.
503     </p>
504    
505     <p>
506     Now, if you look at many of Gentoo's available init scripts, you will notice
507     that some have dependencies on things that are no init scripts. These "things"
508     we call <e>virtuals</e>.
509 swift 1.2 </p>
510    
511     <p>
512     A <e>virtual</e> dependency is a dependency that a service provides, but that is
513     not provided solely by that service. Your init script can depend on a system
514     logger, but there are many system loggers available (metalogd, syslog-ng,
515     sysklogd, ...). As you cannot <c>need</c> every single one of them (no sensible
516     system has all these system loggers installed and running) we made sure that
517     all these services <c>provide</c> a virtual dependency.
518     </p>
519    
520     <p>
521     Let us take a look at the dependency information for the postfix service.
522     </p>
523    
524     <pre caption="Dependency information for Postfix">
525     depend() {
526     need net
527     use logger dns
528     provide mta
529     }
530     </pre>
531    
532     <p>
533     As you can see, the postfix service:
534     </p>
535    
536     <ul>
537     <li>
538     requires the (virtual) <c>net</c> dependency (which is provided by, for
539     instance, <path>/etc/init.d/net.eth0</path>)
540     </li>
541     <li>
542     uses the (virtual) <c>logger</c> dependency (which is provided by, for
543     instance, <path>/etc/init.d/syslog-ng</path>)
544     </li>
545     <li>
546     uses the (virtual) <c>dns</c> dependency (which is provided by, for
547     instance, <path>/etc/init.d/named</path>)
548     </li>
549     <li>
550     provides the (virtual) <c>mta</c> dependency (which is common for all mail
551     servers)
552     </li>
553     </ul>
554    
555 swift 1.1 </body>
556     </subsection>
557     <subsection>
558     <title>Controlling the Order</title>
559     <body>
560    
561 swift 1.2 <p>
562 swift 1.35 As we described in the previous section, you can tell the init system what order
563     it should use for starting (or stopping) scripts. This ordering is handled both
564     through the dependency settings <c>use</c> and <c>need</c>, but also through the
565     order settings <c>before</c> and <c>after</c>. As we have described these
566     earlier already, let's take a look at the Portmap service as an example of such
567     init script.
568 swift 1.2 </p>
569    
570     <pre caption="The depend() function in the Portmap service">
571     depend() {
572     need net
573     before inetd
574     before xinetd
575     }
576     </pre>
577    
578     <p>
579     You can also use the "*" glob to catch all services in the same runlevel,
580 neysx 1.16 although this isn't advisable.
581 swift 1.2 </p>
582    
583     <pre caption="Running an init script as first script in the runlevel">
584     depend() {
585     before *
586     }
587     </pre>
588 swift 1.1
589 nightmorph 1.26 <p>
590     If your service must write to local disks, it should need <c>localmount</c>. If
591 nightmorph 1.28 it places anything in <path>/var/run</path> such as a pidfile, then it should
592 nightmorph 1.26 start after <c>bootmisc</c>:
593     </p>
594    
595     <pre caption="Example depend() function">
596     depend() {
597     need localmount
598     after bootmisc
599     }
600     </pre>
601    
602 swift 1.1 </body>
603     </subsection>
604     <subsection>
605     <title>Standard Functions</title>
606     <body>
607    
608 swift 1.2 <p>
609     Next to the <c>depend()</c> functionality, you also need to define the
610     <c>start()</c> function. This one contains all the commands necessary to
611 neysx 1.16 initialize your service. It is advisable to use the <c>ebegin</c> and
612 swift 1.2 <c>eend</c> functions to inform the user about what is happening:
613     </p>
614    
615     <pre caption="Example start() function">
616     start() {
617 swift 1.33 if [ "${RC_CMD}" = "restart" ];
618     then
619     <comment># Do something in case a restart requires more than stop, start</comment>
620     fi
621    
622 swift 1.2 ebegin "Starting my_service"
623 nightmorph 1.26 start-stop-daemon --start --exec /path/to/my_service \
624     --pidfile /path/to/my_pidfile
625 swift 1.2 eend $?
626     }
627     </pre>
628    
629     <p>
630 nightmorph 1.26 Both <c>--exec</c> and <c>--pidfile</c> should be used in start and stop
631     functions. If the service does not create a pidfile, then use
632     <c>--make-pidfile</c> if possible, though you should test this to be sure.
633     Otherwise, don't use pidfiles. You can also add <c>--quiet</c> to the
634     <c>start-stop-daemon</c> options, but this is not recommended unless the
635     service is extremely verbose. Using <c>--quiet</c> may hinder debugging if the
636     service fails to start.
637 swift 1.2 </p>
638    
639 swift 1.33 <p>
640     Another notable setting used in the above example is to check the contents of
641     the <c>RC_CMD</c> variable. Unlike the previous init script system, the newer
642     <c>openrc</c> system does not support script-specific restart functionality.
643     Instead, the script needs to check the contents of the <c>RC_CMD</c> variable
644     to see if a function (be it <c>start()</c> or <c>stop()</c>) is called as part
645     of a restart or not.
646     </p>
647    
648 nightmorph 1.26 <note>
649     Make sure that <c>--exec</c> actually calls a service and not just a shell
650     script that launches services and exits -- that's what the init script is
651     supposed to do.
652     </note>
653    
654     <p>
655     If you need more examples of the <c>start()</c> function, please read the
656     source code of the available init scripts in your <path>/etc/init.d</path>
657     directory.
658     </p>
659 swift 1.2
660     <p>
661 swift 1.33 Another function you can define is <c>stop()</c>. You are not obliged to define
662     this function though! Our init system is intelligent enough to fill in this
663     function by itself if you use <c>start-stop-daemon</c>.
664 swift 1.2 </p>
665    
666 swift 1.21 <p>
667 swift 1.33 Here is an example of a <c>stop()</c> function:
668 nightmorph 1.26 </p>
669    
670     <pre caption="Example stop() function">
671     stop() {
672     ebegin "Stopping my_service"
673     start-stop-daemon --stop --exec /path/to/my_service \
674     --pidfile /path/to/my_pidfile
675     eend $?
676     }
677     </pre>
678    
679     <p>
680     If your service runs some other script (for example, bash, python, or perl),
681     and this script later changes names (for example, <c>foo.py</c> to <c>foo</c>),
682     then you will need to add <c>--name</c> to <c>start-stop-daemon</c>. You must
683     specify the name that your script will be changed to. In this example, a
684     service starts <c>foo.py</c>, which changes names to <c>foo</c>:
685     </p>
686    
687     <pre caption="A service that starts the foo script">
688     start() {
689     ebegin "Starting my_script"
690     start-stop-daemon --start --exec /path/to/my_script \
691     --pidfile /path/to/my_pidfile --name foo
692     eend $?
693     }
694     </pre>
695    
696     <p>
697     <c>start-stop-daemon</c> has an excellent man page available if you need more
698     information:
699     </p>
700    
701     <pre caption="Getting the man page for start-stop-daemon">
702     $ <i>man start-stop-daemon</i>
703     </pre>
704    
705     <p>
706 swift 1.21 Gentoo's init script syntax is based on the Bourne Again Shell (bash) so you are
707 nightmorph 1.32 free to use bash-compatible constructs inside your init script. However, you may
708     want to write your init scripts to be POSIX-compliant. Future init script
709     systems may allow symlinking <path>/bin/sh</path> to other shells besides
710     bash. Init scripts that rely on bash-only features will then break these
711     configurations.
712 swift 1.21 </p>
713    
714 swift 1.1 </body>
715     </subsection>
716     <subsection>
717     <title>Adding Custom Options</title>
718     <body>
719    
720 swift 1.2 <p>
721     If you want your init script to support more options than the ones we have
722 swift 1.36 already encountered, you should add the option to the <c>extra_commands</c>
723     variable, and create a function with the same name as the option. For instance,
724     to support an option called <c>restartdelay</c>:
725 swift 1.2 </p>
726    
727     <pre caption="Supporting the restartdelay option">
728 swift 1.36 extra_commands="restartdelay"
729 swift 1.2
730     restartdelay() {
731 swift 1.24 stop
732 swift 1.2 sleep 3 <comment># Wait 3 seconds before starting again</comment>
733 swift 1.24 start
734 swift 1.2 }
735     </pre>
736    
737 swift 1.33 <impo>
738     The function <c>restart()</c> cannot be overridden in openrc!
739     </impo>
740    
741 swift 1.1 </body>
742     </subsection>
743     <subsection>
744     <title>Service Configuration Variables</title>
745     <body>
746 swift 1.2
747     <p>
748     You don't have to do anything to support a configuration file in
749     <path>/etc/conf.d</path>: if your init script is executed, the following files
750     are automatically sourced (i.e. the variables are available to use):
751     </p>
752    
753     <ul>
754     <li><path>/etc/conf.d/&lt;your init script&gt;</path></li>
755     <li><path>/etc/conf.d/basic</path></li>
756     <li><path>/etc/rc.conf</path></li>
757     </ul>
758    
759     <p>
760     Also, if your init script provides a virtual dependency (such as <c>net</c>),
761     the file associated with that dependency (such as <path>/etc/conf.d/net</path>)
762     will be sourced too.
763     </p>
764 swift 1.1
765     </body>
766     </subsection>
767     </section>
768 swift 1.12 <section>
769     <title>Changing the Runlevel Behaviour</title>
770     <subsection>
771     <title>Who might benefit from this?</title>
772     <body>
773    
774     <p>
775     Many laptop users know the situation: at home you need to start <c>net.eth0</c>
776     while you don't want to start <c>net.eth0</c> while you're on the road (as
777     there is no network available). With Gentoo you can alter the runlevel behaviour
778     to your own will.
779     </p>
780    
781     <p>
782     For instance you can create a second "default" runlevel which you can boot that
783     has other init scripts assigned to it. You can then select at boottime what
784 dertobi123 1.15 default runlevel you want to use.
785 swift 1.12 </p>
786    
787     </body>
788     </subsection>
789     <subsection>
790 neysx 1.22 <title>Using softlevel</title>
791 swift 1.12 <body>
792    
793     <p>
794     First of all, create the runlevel directory for your second "default" runlevel.
795     As an example we create the <path>offline</path> runlevel:
796     </p>
797    
798     <pre caption="Creating a runlevel directory">
799     # <i>mkdir /etc/runlevels/offline</i>
800     </pre>
801    
802     <p>
803     Add the necessary init scripts to the newly created runlevels. For instance, if
804     you want to have an exact copy of your current <c>default</c> runlevel but
805     without <c>net.eth0</c>:
806     </p>
807    
808     <pre caption="Adding the necessary init scripts">
809 neysx 1.22 <comment>(Copy all services from default runlevel to offline runlevel)</comment>
810 neysx 1.23 # <i>cd /etc/runlevels/default</i>
811     # <i>for service in *; do rc-update add $service offline; done</i>
812 neysx 1.22 <comment>(Remove unwanted service from offline runlevel)</comment>
813     # <i>rc-update del net.eth0 offline</i>
814     <comment>(Display active services for offline runlevel)</comment>
815     # <i>rc-update show offline</i>
816     <comment>(Partial sample Output)</comment>
817     acpid | offline
818     domainname | offline
819     local | offline
820     net.eth0 |
821 swift 1.12 </pre>
822    
823     <p>
824 nightmorph 1.29 Even though <c>net.eth0</c> has been removed from the offline runlevel,
825 swift 1.34 <c>udev</c> might want to attempt to start any devices it detects and launch the
826     appropriate services, a functionality that is called <e>hotplugging</e>. By
827     default, Gentoo does not enable hotplugging.
828 nightmorph 1.29 </p>
829    
830 swift 1.34 <p>
831     If you do want to enable hotplugging, but only for a selected set of scripts,
832     use the <c>rc_hotplug</c> variable in <path>/etc/rc.conf</path>:
833     </p>
834    
835     <pre caption="Disabling device initiated services in /etc/rc.conf">
836     <comment># Allow net.wlan as well as any other service, except those matching net.*
837     # to be hotplugged</comment>
838     rc_hotplug="net.wlan !net.*"
839 nightmorph 1.29 </pre>
840    
841     <note>
842     For more information on device initiated services, please see the comments
843 swift 1.34 inside <path>/etc/rc.conf</path>.
844 nightmorph 1.29 </note>
845    
846     <p>
847 swift 1.12 Now edit your bootloader configuration and add a new entry for the
848     <c>offline</c> runlevel. For instance, in <path>/boot/grub/grub.conf</path>:
849     </p>
850    
851     <pre caption="Adding an entry for the offline runlevel">
852     title Gentoo Linux Offline Usage
853     root (hd0,0)
854     kernel (hd0,0)/kernel-2.4.25 root=/dev/hda3 <i>softlevel=offline</i>
855     </pre>
856    
857     <p>
858 neysx 1.22 VoilĂ , you're all set now. If you boot your system and select the newly added
859 swift 1.12 entry at boot, the <c>offline</c> runlevel will be used instead of the
860     <c>default</c> one.
861     </p>
862    
863     </body>
864     </subsection>
865     <subsection>
866 neysx 1.22 <title>Using bootlevel</title>
867 swift 1.12 <body>
868    
869     <p>
870     Using <c>bootlevel</c> is completely analogous to <c>softlevel</c>. The only
871     difference here is that you define a second "boot" runlevel instead of a second
872     "default" runlevel.
873     </p>
874    
875     </body>
876     </subsection>
877     </section>
878 swift 1.1 </sections>

  ViewVC Help
Powered by ViewVC 1.1.20