doc/en/openrc-migration.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openrc-migration.xml,v 1.2 2008/04/14 08:39:42 nightmorph Exp $ -->

<guide link="/doc/en/openrc-migration.xml">
<title>Baselayout and OpenRC Migration Guide</title>

<author title="Author">
  <mail link="cardoe"/>
</author>
<author title="Author">
  <mail link="nightmorph"/>
</author>
<author title="Contributor">
  <mail link="uberlord"/>
</author>

<abstract>
This guide shows you how to migrate from baselayout-1 to baselayout-2 and
OpenRC.
</abstract>

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

<version>1.2</version>
<date>2008-04-14</date>

<chapter>
<title>Background</title>
<section>
<title>What's baselayout?</title>
<body>

<p>
Baselayout provides a basic set of files that are necessary for all systems to
function properly, such as <path>/etc/hosts</path>. It also provides the basic
filesystem layout used by Gentoo (i.e. <path>/etc</path>, <path>/var</path>,
<path>/usr</path>, <path>/home</path> directories).
</p>

</body>
</section>
<section>
<title>What's OpenRC?</title>
<body>

<p>
OpenRC is a dependency-based rc system that works with whatever init is provided
by the system, normally <path>/sbin/init</path>. However, it is <e>not</e> a
replacement for <path>/sbin/init</path>. The default init used by Gentoo Linux
is <c>sys-apps/sysvinit</c>, while Gentoo/FreeBSD uses the FreeBSD init provided
by <c>sys-freebsd/freebsd-sbin</c>.
</p>
</body>
</section>
<section>
<title>So why migrate?</title>
<body>

<p>
Originally Gentoo's rc system was built into baselayout 1 and written entirely
in bash. This led to several limitations. For example, certain system calls need
to be accessed during boot and this required C-based callouts to be added. These
callouts were each statically linked, causing the rc system to bloat over time.
</p>

<p>
Additionally, as Gentoo expanded to other platforms like
Gentoo/FreeBSD and Gentoo Embedded, it became impossible to require a bash-based
rc system. This led to a development of baselayout 2, which is written in
C and only requires a POSIX-compliant shell. During the development of
baselayout 2, it was determined that it was a better fit if baselayout merely
provided the base files and filesystem layout for Gentoo and the rc system
was broken off into its own package. Thus we have OpenRC.
</p>

<p>
OpenRC is primarily developed by <uri link="http://roy.marples.name/openrc">Roy
Marples</uri> and supports all current Gentoo variations (i.e. Gentoo Linux,
Gentoo/FreeBSD, Gentoo Embedded, and Gentoo Vserver) and other platforms such as
FreeBSD and NetBSD.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Migration to OpenRC</title>
<section>
<body>

<p>
Migration to OpenRC is fairly straightforward; it will be pulled in as part
of your regular upgrade process by your package manager. The most important
step actually comes after you install the new <c>>=sys-apps/baselayout-2</c>
and <c>sys-apps/openrc</c> packages. It is <e>critical</e> that you run 
<c>dispatch-conf</c> and ensure your <path>/etc</path>
is up to date before rebooting. <brite>Failure to do so will result in an unbootable
system</brite> and will require the use of the Gentoo LiveCD to perform the steps
below to repair your system.
</p>

<p>
Once you've finished updating your config files, there are a few things to
verify prior to rebooting.</p>
        
</body>
</section>

<section id="rc_conf">
<title>/etc/conf.d/rc</title>
<body>

<p>
<path>/etc/conf.d/rc</path> has been deprecated and any settings you have in
there will need to be migrated to the appropriate settings in
<path>/etc/rc.conf</path>. Please read through <path>/etc/rc.conf</path> and
<path>/etc/conf.d/rc</path> and migrate the settings. Once you are complete,
delete <path>/etc/conf.d/rc</path>.
</p>

</body>
</section>

<section id="modules">
<title>Kernel modules</title>
<body>

<p>
Normally, when you want certain kernel modules automatically loaded at boot, you
place them into <path>/etc/modules.autoload.d/kernel-2.6</path> along with any
parameters you wanted to pass to them. In baselayout-2, this file is not used
anymore. Instead, autoloaded modules and module parameters are placed in one
file, <path>/etc/conf.d/modules</path>, no matter the kernel version.
</p>

<p>
An example old style configuration would be:
</p>

<pre caption="/etc/modules.autoload.d/kernel-2.6">
ivtv
cx88_dvb video_br=2
</pre>

<p>
Converting the above example would result in the following:
</p>

<pre caption="/etc/conf.d/modules">
<comment># Modules autoloaded at boot</comment>
modules_2_6="ivtv cx88_dvb"
<comment># Module parameters</comment>
module_cx88_dvb_args_2_6="video_br=2"
</pre>

<p>
In the above examples, the modules and their parameters would only be passed
to 2.6.x series kernels. The new configuration allows for fine grained
control over the modules and parameters based on kernel version.
</p>

<p>
An in-depth example would be:
</p>

<pre caption="detailed example of /etc/conf.d/modules">
<comment># Always load ochi1394 and ieee1394, no matter the kernel version</comment>
modules="ohci1394 ieee1394"
<comment># Only load tun and usbserial for 2.6.x series kernels</comment>
modules_2_6="tun usbserial"
<comment># Only load cx88_dvb for 2.6.23 kernels</comment>
modules_2_6_23="cx88_dvb"
<comment># Only load ivtv for 2.6.23-gentoo-r5</comment>
modules_2_6_23_gentoo_r5="ivtv"

<comment># For 2.6.23-gentoo-r5, pass video_br=2 to cx88_dvb</comment>
module_cx88_dvb_args_2_6_23_gentoo_r5="video_br=2"
<comment># For 2.6.x series kernels, always pass vendor and product</comment>
module_usbserial_args_2_6="vendor=0x1410 product=0x2110"
<comment># Always pass debug to ieee1394</comment>
module_ieee1394_args="debug" 
</pre>

<note>
Please note the difference between <b>module_</b> and <b>modules_</b>.
</note>

</body>
</section>
<section id="volume">
<title>Volume management</title>
<body>

<p>
Volume management services for your block storage devices should be
automatically migrated for you when you switch to OpenRC and baselayout-2.
However, in case they aren't, you'll need to follow the instructions below.
</p>

<p>
Volume management services for your block storage devices are no longer run by
default. This means that lvm, raid, swap, device-mapper (dm), dm-crypt, evms, and the
like will not be run automatically. If you use these addons, you will have to
add the proper initscript to the <c>boot</c> runlevel. Otherwise, it's possible
your system will not boot. When you install the various volume management
services, they will install an appropriate initscript in
<path>/etc/init.d</path>. You must ensure the appropriate initscript is in the
<c>boot</c> runlevel.
</p>

<p>
While the OpenRC ebuild will attempt to do this migration for you, you should
verify that it migrated all the volume management services properly.
</p>

<pre caption="Check all services in boot runlevel">
# <i>ls -l /etc/runlevels/boot/</i>
</pre>

<p>
If you know you use mdraid, lvm, and swap but do not see them above, you would run
the following to add initscripts to the <c>boot</c> runlevel.
</p>

<pre caption="Adding missing volume management services to the boot runlevel">
# <i>rc-update add raid boot</i>
# <i>rc-update add lvm boot</i>
# <i>rc-update add swap boot</i>
</pre>

<p>
Also, make sure your root filesystem is mounted read/write, that your
filesystems are checked for errors, that your mountpoints are available, and
that the <path>/proc</path> pseudo-filesystem is started at boot. Here's a handy
shell script to make it happen:
</p>

<pre caption="Adding other critical services to the boot runlevel">
# <i>for x in root fsck mtab procfs ; do rc-update add $x boot ; done</i>
</pre>

</body>
</section>
<section>
<title>Clock</title>
<body>

<p>
Clock settings have been renamed from <path>/etc/conf.d/clock</path> to your
system's native tool for adjusting the clock. This means on Linux it will be
<path>/etc/conf.d/hwclock</path> and on FreeBSD it will be
<path>/etc/conf.d/adjkerntz</path>. The initscript in <path>/etc/init.d/</path>
has also been renamed accordingly, so make sure it's in the appropriate
runlevel.
</p>

<p>
Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
contents are instead found in the <path>/etc/timezone</path> file. Please review
both of these files to ensure their correctness.
</p>

</body>
</section>

<section>
<title>XSESSION</title>
<body>

<p>
The XSESSION variable is no longer found in <path>/etc/rc.conf</path>. The
<c>x11-apps/xinit</c> package now provides <path>/etc/env.d/90xsession</path>,
which can be used to set the XSESSION variable.
</p>

<p>
This variable will <b>NOT</b> be migrated for you by default, so you will need
to edit <path>/etc/env.d/90xsession</path>.
</p>

<impo>
You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
and then logout and login for it to take effect.
</impo>

</body>
</section>
<section>
<title>EDITOR</title>
<body>

<p>
The EDITOR variable is no longer found in <path>/etc/rc.conf</path>, and at this
time is not provided by any other package. Users are encouraged to set it as
needed in their <path>~/.bashrc</path> file or create
<path>/etc/env.d/99editor</path> and set it there. 
</p>

<impo>
You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
and then logout and login for it to take effect. If you set the variable in
<path>~/.bashrc</path>, you can re-source the file with <c>source
~/.bashrc</c>.
</impo>

</body>
</section>
<section>
<title>Finishing up</title>
<body>

<p>
Once you've finished updating your config files and initscripts, the last thing
to do is <b>reboot</b>. This is necessary because system state information is
not preserved during the upgrade, so you'll need to provide it with a fresh
boot.
</p>

</body>
</section>
</chapter>
</guide>
1	<?xml version='1.0' encoding='UTF-8'?>
2	<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openrc-migration.xml,v 1.2 2008/04/14 08:39:42 nightmorph Exp $ -->
4
5	<guide link="/doc/en/openrc-migration.xml">
6	<title>Baselayout and OpenRC Migration Guide</title>
7
8	<author title="Author">
9	<mail link="cardoe"/>
10	</author>
11	<author title="Author">
12	<mail link="nightmorph"/>
13	</author>
14	<author title="Contributor">
15	<mail link="uberlord"/>
16	</author>
17
18	<abstract>
19	This guide shows you how to migrate from baselayout-1 to baselayout-2 and
20	OpenRC.
21	</abstract>
22
23	<!-- The content of this document is licensed under the CC-BY-SA license -->
24	<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
25	<license/>
26
27	<version>1.2</version>
28	<date>2008-04-14</date>
29
30	<chapter>
31	<title>Background</title>
32	<section>
33	<title>What's baselayout?</title>
34	<body>
35
36	<p>
37	Baselayout provides a basic set of files that are necessary for all systems to
38	function properly, such as <path>/etc/hosts</path>. It also provides the basic
39	filesystem layout used by Gentoo (i.e. <path>/etc</path>, <path>/var</path>,
40	<path>/usr</path>, <path>/home</path> directories).
41	</p>
42
43	</body>
44	</section>
45	<section>
46	<title>What's OpenRC?</title>
47	<body>
48
49	<p>
50	OpenRC is a dependency-based rc system that works with whatever init is provided
51	by the system, normally <path>/sbin/init</path>. However, it is <e>not</e> a
52	replacement for <path>/sbin/init</path>. The default init used by Gentoo Linux
53	is <c>sys-apps/sysvinit</c>, while Gentoo/FreeBSD uses the FreeBSD init provided
54	by <c>sys-freebsd/freebsd-sbin</c>.
55	</p>
56	</body>
57	</section>
58	<section>
59	<title>So why migrate?</title>
60	<body>
61
62	<p>
63	Originally Gentoo's rc system was built into baselayout 1 and written entirely
64	in bash. This led to several limitations. For example, certain system calls need
65	to be accessed during boot and this required C-based callouts to be added. These
66	callouts were each statically linked, causing the rc system to bloat over time.
67	</p>
68
69	<p>
70	Additionally, as Gentoo expanded to other platforms like
71	Gentoo/FreeBSD and Gentoo Embedded, it became impossible to require a bash-based
72	rc system. This led to a development of baselayout 2, which is written in
73	C and only requires a POSIX-compliant shell. During the development of
74	baselayout 2, it was determined that it was a better fit if baselayout merely
75	provided the base files and filesystem layout for Gentoo and the rc system
76	was broken off into its own package. Thus we have OpenRC.
77	</p>
78
79	<p>
80	OpenRC is primarily developed by <uri link="http://roy.marples.name/openrc">Roy
81	Marples</uri> and supports all current Gentoo variations (i.e. Gentoo Linux,
82	Gentoo/FreeBSD, Gentoo Embedded, and Gentoo Vserver) and other platforms such as
83	FreeBSD and NetBSD.
84	</p>
85
86	</body>
87	</section>
88	</chapter>
89
90	<chapter>
91	<title>Migration to OpenRC</title>
92	<section>
93	<body>
94
95	<p>
96	Migration to OpenRC is fairly straightforward; it will be pulled in as part
97	of your regular upgrade process by your package manager. The most important
98	step actually comes after you install the new <c>>=sys-apps/baselayout-2</c>
99	and <c>sys-apps/openrc</c> packages. It is <e>critical</e> that you run
100	<c>dispatch-conf</c> and ensure your <path>/etc</path>
101	is up to date before rebooting. <brite>Failure to do so will result in an unbootable
102	system</brite> and will require the use of the Gentoo LiveCD to perform the steps
103	below to repair your system.
104	</p>
105
106	<p>
107	Once you've finished updating your config files, there are a few things to
108	verify prior to rebooting.</p>
109
110	</body>
111	</section>
112
113	<section id="rc_conf">
114	<title>/etc/conf.d/rc</title>
115	<body>
116
117	<p>
118	<path>/etc/conf.d/rc</path> has been deprecated and any settings you have in
119	there will need to be migrated to the appropriate settings in
120	<path>/etc/rc.conf</path>. Please read through <path>/etc/rc.conf</path> and
121	<path>/etc/conf.d/rc</path> and migrate the settings. Once you are complete,
122	delete <path>/etc/conf.d/rc</path>.
123	</p>
124
125	</body>
126	</section>
127
128	<section id="modules">
129	<title>Kernel modules</title>
130	<body>
131
132	<p>
133	Normally, when you want certain kernel modules automatically loaded at boot, you
134	place them into <path>/etc/modules.autoload.d/kernel-2.6</path> along with any
135	parameters you wanted to pass to them. In baselayout-2, this file is not used
136	anymore. Instead, autoloaded modules and module parameters are placed in one
137	file, <path>/etc/conf.d/modules</path>, no matter the kernel version.
138	</p>
139
140	<p>
141	An example old style configuration would be:
142	</p>
143
144	<pre caption="/etc/modules.autoload.d/kernel-2.6">
145	ivtv
146	cx88_dvb video_br=2
147	</pre>
148
149	<p>
150	Converting the above example would result in the following:
151	</p>
152
153	<pre caption="/etc/conf.d/modules">
154	<comment># Modules autoloaded at boot</comment>
155	modules_2_6="ivtv cx88_dvb"
156	<comment># Module parameters</comment>
157	module_cx88_dvb_args_2_6="video_br=2"
158	</pre>
159
160	<p>
161	In the above examples, the modules and their parameters would only be passed
162	to 2.6.x series kernels. The new configuration allows for fine grained
163	control over the modules and parameters based on kernel version.
164	</p>
165
166	<p>
167	An in-depth example would be:
168	</p>
169
170	<pre caption="detailed example of /etc/conf.d/modules">
171	<comment># Always load ochi1394 and ieee1394, no matter the kernel version</comment>
172	modules="ohci1394 ieee1394"
173	<comment># Only load tun and usbserial for 2.6.x series kernels</comment>
174	modules_2_6="tun usbserial"
175	<comment># Only load cx88_dvb for 2.6.23 kernels</comment>
176	modules_2_6_23="cx88_dvb"
177	<comment># Only load ivtv for 2.6.23-gentoo-r5</comment>
178	modules_2_6_23_gentoo_r5="ivtv"
179
180	<comment># For 2.6.23-gentoo-r5, pass video_br=2 to cx88_dvb</comment>
181	module_cx88_dvb_args_2_6_23_gentoo_r5="video_br=2"
182	<comment># For 2.6.x series kernels, always pass vendor and product</comment>
183	module_usbserial_args_2_6="vendor=0x1410 product=0x2110"
184	<comment># Always pass debug to ieee1394</comment>
185	module_ieee1394_args="debug"
186	</pre>
187
188	<note>
189	Please note the difference between <b>module_</b> and <b>modules_</b>.
190	</note>
191
192	</body>
193	</section>
194	<section id="volume">
195	<title>Volume management</title>
196	<body>
197
198	<p>
199	Volume management services for your block storage devices should be
200	automatically migrated for you when you switch to OpenRC and baselayout-2.
201	However, in case they aren't, you'll need to follow the instructions below.
202	</p>
203
204	<p>
205	Volume management services for your block storage devices are no longer run by
206	default. This means that lvm, raid, swap, device-mapper (dm), dm-crypt, evms, and the
207	like will not be run automatically. If you use these addons, you will have to
208	add the proper initscript to the <c>boot</c> runlevel. Otherwise, it's possible
209	your system will not boot. When you install the various volume management
210	services, they will install an appropriate initscript in
211	<path>/etc/init.d</path>. You must ensure the appropriate initscript is in the
212	<c>boot</c> runlevel.
213	</p>
214
215	<p>
216	While the OpenRC ebuild will attempt to do this migration for you, you should
217	verify that it migrated all the volume management services properly.
218	</p>
219
220	<pre caption="Check all services in boot runlevel">
221	# <i>ls -l /etc/runlevels/boot/</i>
222	</pre>
223
224	<p>
225	If you know you use mdraid, lvm, and swap but do not see them above, you would run
226	the following to add initscripts to the <c>boot</c> runlevel.
227	</p>
228
229	<pre caption="Adding missing volume management services to the boot runlevel">
230	# <i>rc-update add raid boot</i>
231	# <i>rc-update add lvm boot</i>
232	# <i>rc-update add swap boot</i>
233	</pre>
234
235	<p>
236	Also, make sure your root filesystem is mounted read/write, that your
237	filesystems are checked for errors, that your mountpoints are available, and
238	that the <path>/proc</path> pseudo-filesystem is started at boot. Here's a handy
239	shell script to make it happen:
240	</p>
241
242	<pre caption="Adding other critical services to the boot runlevel">
243	# <i>for x in root fsck mtab procfs ; do rc-update add $x boot ; done</i>
244	</pre>
245
246	</body>
247	</section>
248	<section>
249	<title>Clock</title>
250	<body>
251
252	<p>
253	Clock settings have been renamed from <path>/etc/conf.d/clock</path> to your
254	system's native tool for adjusting the clock. This means on Linux it will be
255	<path>/etc/conf.d/hwclock</path> and on FreeBSD it will be
256	<path>/etc/conf.d/adjkerntz</path>. The initscript in <path>/etc/init.d/</path>
257	has also been renamed accordingly, so make sure it's in the appropriate
258	runlevel.
259	</p>
260
261	<p>
262	Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
263	contents are instead found in the <path>/etc/timezone</path> file. Please review
264	both of these files to ensure their correctness.
265	</p>
266
267	</body>
268	</section>
269
270	<section>
271	<title>XSESSION</title>
272	<body>
273
274	<p>
275	The XSESSION variable is no longer found in <path>/etc/rc.conf</path>. The
276	<c>x11-apps/xinit</c> package now provides <path>/etc/env.d/90xsession</path>,
277	which can be used to set the XSESSION variable.
278	</p>
279
280	<p>
281	This variable will <b>NOT</b> be migrated for you by default, so you will need
282	to edit <path>/etc/env.d/90xsession</path>.
283	</p>
284
285	<impo>
286	You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
287	and then logout and login for it to take effect.
288	</impo>
289
290	</body>
291	</section>
292	<section>
293	<title>EDITOR</title>
294	<body>
295
296	<p>
297	The EDITOR variable is no longer found in <path>/etc/rc.conf</path>, and at this
298	time is not provided by any other package. Users are encouraged to set it as
299	needed in their <path>~/.bashrc</path> file or create
300	<path>/etc/env.d/99editor</path> and set it there.
301	</p>
302
303	<impo>
304	You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
305	and then logout and login for it to take effect. If you set the variable in
306	<path>~/.bashrc</path>, you can re-source the file with <c>source
307	~/.bashrc</c>.
308	</impo>
309
310	</body>
311	</section>
312	<section>
313	<title>Finishing up</title>
314	<body>
315
316	<p>
317	Once you've finished updating your config files and initscripts, the last thing
318	to do is <b>reboot</b>. This is necessary because system state information is
319	not preserved during the upgrade, so you'll need to provide it with a fresh
320	boot.
321	</p>
322
323	</body>
324	</section>
325	</chapter>
326	</guide>