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

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

Parent Directory | Revision Log | View Patch Patch

Revision 1.4		Revision 1.35
		1	<?xml version='1.0' encoding='UTF-8'?>
		2	<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
		3
1	<!-- The content of this document is licensed under the CC-BY-SA license -->	4	<!-- The content of this document is licensed under the CC-BY-SA license -->
2	<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->	5	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
3		6
4	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.4 2003/12/03 15:03:41 swift Exp $ -->	7	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-rcscripts.xml,v 1.35 2011/08/17 07:57:23 swift Exp $ -->
5		8
6	<sections>	9	<sections>
		10
		11	<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	<version>4</version>
		18	<date>2011-08-17</date>
		19
7	<section>	20	<section>
8	<title>Runlevels</title>	21	<title>Runlevels</title>
9	<subsection>	22	<subsection>
10	<title>Booting your System</title>	23	<title>Booting your System</title>
11	<body>	24	<body>
…		…
18	</p>	31	</p>
19		32
20	<p>	33	<p>
21	First, your boot loader will load the kernel image you have defined in the	34	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	35	boot loader configuration into memory after which it tells the CPU to run the
23	kernel. When the kernel is loaded and run, it initialises all kernel-specific	36	kernel. When the kernel is loaded and run, it initializes all kernel-specific
24	structures and tasks and starts the <c>init</c> process.	37	structures and tasks and starts the <c>init</c> process.
25	</p>	38	</p>
26		39
27	<p>	40	<p>
28	This process then makes sure that all filesystems (defined in	41	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	42	<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	43	several scripts located in <path>/etc/init.d</path>, which will start the
31	services you need in order to have a succesfully booted system.	44	services you need in order to have a successfully booted system.
32	</p>	45	</p>
33		46
34	<p>	47	<p>
35	Finally, when all scripts are executed, <c>init</c> activates the terminals	48	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>,	49	(in most cases just the virtual consoles which are hidden beneath <c>Alt-F1</c>,
37	<c>Alt-F2</c>, etc.) attaching a special process called <c>agetty</c> to it.	50	<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	51	This process will then make sure you are able to log on through these terminals
39	by running <c>login</c>.	52	by running <c>login</c>.
40	</p>	53	</p>
41		54
…		…
46	<body>	59	<body>
47		60
48	<p>	61	<p>
49	Now <c>init</c> doesn't just execute the scripts in <path>/etc/init.d</path>	62	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>,	63	randomly. Even more, it doesn't run all scripts in <path>/etc/init.d</path>,
51	only the scripts it is told to execute. It decides what scripts to execute by	64	only the scripts it is told to execute. It decides which scripts to execute by
52	looking into <path>/etc/runlevels</path>.	65	looking into <path>/etc/runlevels</path>.
53	</p>	66	</p>
54		67
55	<p>	68	<p>
56	First, <c>init</c> runs all scripts from <path>/etc/init.d</path> that have	69	First, <c>init</c> runs all scripts from <path>/etc/init.d</path> that have
…		…
63	<p>	76	<p>
64	When all <path>/etc/runlevels/boot</path> referenced scripts are executed,	77	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	78	<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	79	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	80	order to decide what script to run first, unless a script has dependency
68	information in it, in which the order is changed to provide a valid start-up	81	information in it, in which case the order is changed to provide a valid
69	sequence.	82	start-up sequence.
70	</p>	83	</p>
71		84
72	</body>	85	</body>
73	</subsection>	86	</subsection>
74	<subsection>	87	<subsection>
…		…
80	configuration file that specifies what actions need to be taken. This	93	configuration file that specifies what actions need to be taken. This
81	configuration file is <path>/etc/inittab</path>.	94	configuration file is <path>/etc/inittab</path>.
82	</p>	95	</p>
83		96
84	<p>	97	<p>
85	If you remember the boot sequence we have just explained to you, you will	98	If you remember the boot sequence we have just described, you will remember
86	remember that <c>init</c>'s first action is to mount all filesystems. This is	99	that <c>init</c>'s first action is to mount all filesystems. This is defined in
87	defined in the following line from <path>/etc/inittab</path>:	100	the following line from <path>/etc/inittab</path>:
88	</p>	101	</p>
89		102
90	<pre caption="The system initialisation line in /etc/inittab">	103	<pre caption="The system initialisation line in /etc/inittab">
91	si::sysinit:/sbin/rc sysinit	104	si::sysinit:/sbin/rc sysinit
92	</pre>	105	</pre>
93		106
94	<p>	107	<p>
95	This line tells <c>init</c> that it must run <c>/sbin/rc sysinit</c> to	108	This line tells <c>init</c> that it must run <c>/sbin/rc sysinit</c> to
96	initialise the system. The <path>/sbin/rc</path> script takes care of the	109	initialize the system. The <path>/sbin/rc</path> script takes care of the
97	initialisation, so you might say that <c>init</c> doesn't do much -- it	110	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.	111	delegates the task of initialising the system to another process.
99	</p>	112	</p>
100		113
101	<p>	114	<p>
…		…
175		188
176	<p>	189	<p>
177	In Gentoo, there are seven runlevels defined: three internal runlevels, and four	190	In Gentoo, there are seven runlevels defined: three internal runlevels, and four
178	user-defined runlevels. The internal runlevels are called <e>sysinit</e>,	191	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:	192	<e>shutdown</e> and <e>reboot</e> and do exactly what their names imply:
180	initialise the system, powering off the system and rebooting the system.	193	initialize the system, powering off the system and rebooting the system.
181	</p>	194	</p>
182		195
183	<p>	196	<p>
184	The user-defined runlevels are those with an accompanying	197	The user-defined runlevels are those with an accompanying
185	<path>/etc/runlevels</path> subdirectory: <path>boot</path>,	198	<path>/etc/runlevels</path> subdirectory: <path>boot</path>,
…		…
268	<pre caption="Requesting a list of all services that require Postfix">	281	<pre caption="Requesting a list of all services that require Postfix">
269	# <i>/etc/init.d/postfix needsme</i>	282	# <i>/etc/init.d/postfix needsme</i>
270	</pre>	283	</pre>
271		284
272	<p>	285	<p>
273	Finally, you can ask what dependencies the service requires but that are	286	Finally, you can ask what dependencies the service requires that are missing:
274	missing:
275	</p>	287	</p>
276		288
277	<pre caption="Requesting a list of missing dependencies for Postfix">	289	<pre caption="Requesting a list of missing dependencies for Postfix">
278	# <i>/etc/init.d/postfix broken</i>	290	# <i>/etc/init.d/postfix broken</i>
279	</pre>	291	</pre>
…		…
287	<title>What is rc-update?</title>	299	<title>What is rc-update?</title>
288	<body>	300	<body>
289		301
290	<p>	302	<p>
291	Gentoo's init system uses a dependency-tree to decide what service needs to be	303	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	304	started first. As this is a tedious task that we wouldn't want our users to
293	manually, we have created tools that ease the administration of the runlevels	305	have to do manually, we have created tools that ease the administration of the
294	and init scripts.	306	runlevels and init scripts.
295	</p>	307	</p>
296		308
297	<p>	309	<p>
298	With <c>rc-update</c> you can add and remove init scripts to a runlevel. The	310	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	311	<c>rc-update</c> tool will then automatically ask the <c>depscan.sh</c> script
…		…
306	<title>Adding and Removing Services</title>	318	<title>Adding and Removing Services</title>
307	<body>	319	<body>
308		320
309	<p>	321	<p>
310	You have already added init scripts to the "default" runlevel during the	322	You have already added init scripts to the "default" runlevel during the
311	installation of Gentoo. At that time you might not had a clue what the	323	installation of Gentoo. At that time you might not have had a clue what the
312	"default" is for, but now you should. The <c>rc-update</c> script requires a	324	"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>.	325	second argument that defines the action: <e>add</e>, <e>del</e> or <e>show</e>.
314	</p>	326	</p>
315		327
316	<p>	328	<p>
…		…
321	<pre caption="Removing Postfix from the default runlevel">	333	<pre caption="Removing Postfix from the default runlevel">
322	# <i>rc-update del postfix default</i>	334	# <i>rc-update del postfix default</i>
323	</pre>	335	</pre>
324		336
325	<p>	337	<p>
326	The <c>rc-update show</c> command will show all the available init scripts and	338	The <c>rc-update -v show</c> command will show all the available init scripts and
327	list at which runlevels they will execute:	339	list at which runlevels they will execute:
328	</p>	340	</p>
329		341
330	<pre caption="Receiving init script information">	342	<pre caption="Receiving init script information">
331	# <i>rc-update show</i>	343	# <i>rc-update -v show</i>
		344	</pre>
		345
		346	<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.
332	</pre>	349	</p>
333		350
334	</body>	351	</body>
335	</subsection>	352	</subsection>
336	</section>	353	</section>
337	<section>	354	<section>
…		…
339	<subsection>	356	<subsection>
340	<title>Why the Need for Extra Configuration?</title>	357	<title>Why the Need for Extra Configuration?</title>
341	<body>	358	<body>
342		359
343	<p>	360	<p>
344	Init scripts can be quite complex. It is therefor not really interesting to have	361	Init scripts can be quite complex. It is therefore not really desirable to
345	the users directly edit the init script, as it would make it more error-prone.	362	have the users edit the init script directly, as it would make it more
346	It is however important to be able to configure such a service. For instance,	363	error-prone. It is however important to be able to configure such a service. For
347	you might want to give more options to the service itself.	364	instance, you might want to give more options to the service itself.
348	</p>
349
350	<p>	365	</p>
		366
		367	<p>
351	A second reason to have this configuration outside the init script is to be able	368	A second reason to have this configuration outside the init script is to be
352	to update the init scripts without being afraid that your configuration changes	369	able to update the init scripts without the fear that your configuration
353	are undone.	370	changes will be undone.
354	</p>	371	</p>
355		372
356	</body>	373	</body>
357	</subsection>	374	</subsection>
358	<subsection>	375	<subsection>
…		…
366	configuration file called <path>/etc/conf.d/apache2</path>, which can contain	383	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:	384	the options you want to give to the Apache 2 server when it is started:
368	</p>	385	</p>
369		386
370	<pre caption="Variable defined in /etc/conf.d/apache2">	387	<pre caption="Variable defined in /etc/conf.d/apache2">
371	APACHE2_OPTS="-D PHP4"	388	APACHE2_OPTS="-D PHP5"
372	</pre>	389	</pre>
373		390
374	<p>	391	<p>
375	Such a configuration file contains variables and variables alone (just like	392	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	393	<path>/etc/make.conf</path>), making it very easy to configure services. It also
…		…
385	<subsection>	402	<subsection>
386	<title>Do I Have To?</title>	403	<title>Do I Have To?</title>
387	<body>	404	<body>
388		405
389	<p>	406	<p>
390	No. Writing an init script is usually not necessary as Gentoo provides	407	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	408	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	409	installed a service without using Portage, in which case you will most likely
393	have to create an init script.	410	have to create an init script.
394	</p>	411	</p>
395		412
…		…
421	}	438	}
422		439
423	stop() {	440	stop() {
424	<comment>(Commands necessary to stop the service)</comment>	441	<comment>(Commands necessary to stop the service)</comment>
425	}	442	}
426
427	restart() {
428	<comment>(Commands necessary to restart the service)</comment>
429	}
430	</pre>	443	</pre>
431		444
432	<p>	445	<p>
433	Any init script <e>requires</e> the <c>start()</c> function to be defined. All	446	Any init script <e>requires</e> the <c>start()</c> function to be defined. All
434	other sections are optional.	447	other sections are optional.
…		…
439	<subsection>	452	<subsection>
440	<title>Dependencies</title>	453	<title>Dependencies</title>
441	<body>	454	<body>
442		455
443	<p>	456	<p>
444	There are two dependencies you can define: <c>use</c> and <c>need</c>. As we	457	There are two dependency-alike settings you can define that influence the
445	have mentioned before, the <c>need</c> dependency is more strict than the	458	start-up or sequencing of init scripts: <c>use</c> and <c>need</c>. Next to
446	<c>use</c> dependency. Following this dependency type you enter the service	459	these two, there are also two order-influencing methods called <c>before</c> and
447	you depend on, or the <e>virtual</e> dependency.	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>.
448	</p>	509	</p>
449		510
450	<p>	511	<p>
451	A <e>virtual</e> dependency is a dependency that a service provides, but that is	512	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	513	not provided solely by that service. Your init script can depend on a system
…		…
496	<subsection>	557	<subsection>
497	<title>Controlling the Order</title>	558	<title>Controlling the Order</title>
498	<body>	559	<body>
499		560
500	<p>	561	<p>
501	In some cases you might not require a service, but want your service to be	562	As we described in the previous section, you can tell the init system what order
502	started <c>before</c> (or <c>after</c>) another service <e>if</e> it is	563	it should use for starting (or stopping) scripts. This ordering is handled both
503	available on the system (note the conditional - this is no dependency anymore)	564	through the dependency settings <c>use</c> and <c>need</c>, but also through the
504	<e>and</e> ran in the same runlevel (note the conditional - only services in the	565	order settings <c>before</c> and <c>after</c>. As we have described these
505	same runlevel are involved). You can provide this information using the	566	earlier already, let's take a look at the Portmap service as an example of such
506	<c>before</c> or <c>after</c> settings.	567	init script.
507	</p>
508
509	<p>
510	As an example we view the settings of the Portmap service:
511	</p>	568	</p>
512		569
513	<pre caption="The depend() function in the Portmap service">	570	<pre caption="The depend() function in the Portmap service">
514	depend() {	571	depend() {
515	need net	572	need net
…		…
518	}	575	}
519	</pre>	576	</pre>
520		577
521	<p>	578	<p>
522	You can also use the "*" glob to catch all services in the same runlevel,	579	You can also use the "*" glob to catch all services in the same runlevel,
523	although this isn't adviseable.	580	although this isn't advisable.
524	</p>	581	</p>
525		582
526	<pre caption="Running an init script as first script in the runlevel">	583	<pre caption="Running an init script as first script in the runlevel">
527	depend() {	584	depend() {
528	before *	585	before *
529	}	586	}
530	</pre>	587	</pre>
531		588
		589	<p>
		590	If your service must write to local disks, it should need <c>localmount</c>. If
		591	it places anything in <path>/var/run</path> such as a pidfile, then it should
		592	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
532	</body>	602	</body>
533	</subsection>	603	</subsection>
534	<subsection>	604	<subsection>
535	<title>Standard Functions</title>	605	<title>Standard Functions</title>
536	<body>	606	<body>
537		607
538	<p>	608	<p>
539	Next to the <c>depend()</c> functionality, you also need to define the	609	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	610	<c>start()</c> function. This one contains all the commands necessary to
541	initialise your service. It is adviseable to use the <c>ebegin</c> and	611	initialize your service. It is advisable to use the <c>ebegin</c> and
542	<c>eend</c> functions to inform the user about what is happening:	612	<c>eend</c> functions to inform the user about what is happening:
543	</p>	613	</p>
544		614
545	<pre caption="Example start() function">	615	<pre caption="Example start() function">
546	start() {	616	start() {
		617	if [ "${RC_CMD}" = "restart" ];
		618	then
		619	<comment># Do something in case a restart requires more than stop, start</comment>
		620	fi
		621
547	ebegin "Starting my_service"	622	ebegin "Starting my_service"
548	start-stop-daemon --start --quiet --exec /path/to/my_service	623	start-stop-daemon --start --exec /path/to/my_service \
		624	--pidfile /path/to/my_pidfile
549	eend $?	625	eend $?
550	}	626	}
551	</pre>	627	</pre>
552		628
553	<p>	629	<p>
		630	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	</p>
		638
		639	<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	<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>
554	If you need more examples of the <c>start()</c> function, please read the source	655	If you need more examples of the <c>start()</c> function, please read the
555	code of the available init scripts in your <path>/etc/init.d</path> directory.	656	source code of the available init scripts in your <path>/etc/init.d</path>
		657	directory.
		658	</p>
		659
		660	<p>
		661	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	</p>
		665
		666	<p>
		667	Here is an example of a <c>stop()</c> function:
		668	</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>
556	As for <c>start-stop-daemon</c>, there is an excellent man page available if you	697	<c>start-stop-daemon</c> has an excellent man page available if you need more
557	need more information:	698	information:
558	</p>	699	</p>
559		700
560	<pre caption="Getting the man page for start-stop-daemon">	701	<pre caption="Getting the man page for start-stop-daemon">
561	# <i>man start-stop-daemon</i>	702	$ <i>man start-stop-daemon</i>
562	</pre>	703	</pre>
563		704
564	<p>	705	<p>
565	Other functions you can define are: <c>stop()</c> and <c>restart()</c>. You are	706	Gentoo's init script syntax is based on the Bourne Again Shell (bash) so you are
566	not obliged to define these functions! Our init system is intelligent enough to	707	free to use bash-compatible constructs inside your init script. However, you may
567	fill these functions in herself if you use <c>start-stop-daemon</c>.	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.
568	</p>	712	</p>
569		713
570	</body>	714	</body>
571	</subsection>	715	</subsection>
572	<subsection>	716	<subsection>
…		…
582		726
583	<pre caption="Supporting the restartdelay option">	727	<pre caption="Supporting the restartdelay option">
584	opts="${opts} restartdelay"	728	opts="${opts} restartdelay"
585		729
586	restartdelay() {	730	restartdelay() {
587	stop()	731	stop
588	sleep 3 <comment># Wait 3 seconds before starting again</comment>	732	sleep 3 <comment># Wait 3 seconds before starting again</comment>
589	start()	733	start
590	}	734	}
591	</pre>	735	</pre>
		736
		737	<impo>
		738	The function <c>restart()</c> cannot be overridden in openrc!
		739	</impo>
592		740
593	</body>	741	</body>
594	</subsection>	742	</subsection>
595	<subsection>	743	<subsection>
596	<title>Service Configuration Variables</title>	744	<title>Service Configuration Variables</title>
…		…
615	</p>	763	</p>
616		764
617	</body>	765	</body>
618	</subsection>	766	</subsection>
619	</section>	767	</section>
		768	<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	default runlevel you want to use.
		785	</p>
		786
		787	</body>
		788	</subsection>
		789	<subsection>
		790	<title>Using softlevel</title>
		791	<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	<comment>(Copy all services from default runlevel to offline runlevel)</comment>
		810	# <i>cd /etc/runlevels/default</i>
		811	# <i>for service in *; do rc-update add $service offline; done</i>
		812	<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	</pre>
		822
		823	<p>
		824	Even though <c>net.eth0</c> has been removed from the offline runlevel,
		825	<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	</p>
		829
		830	<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	</pre>
		840
		841	<note>
		842	For more information on device initiated services, please see the comments
		843	inside <path>/etc/rc.conf</path>.
		844	</note>
		845
		846	<p>
		847	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	Voilà, you're all set now. If you boot your system and select the newly added
		859	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	<title>Using bootlevel</title>
		867	<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>
620	</sections>	878	</sections>

 Legend:



Removed from v.1.4
 


changed lines


 
Added in v.1.35
 Legend:



Removed from v.1.4
 


changed lines


 
Added in v.1.35
-Removed from v.1.4
+Added in v.1.35

	ViewVC Help
Powered by ViewVC 1.1.20