/[gentoo]/xml/htdocs/doc/en/openrc-migration.xml
Gentoo

Contents of /xml/htdocs/doc/en/openrc-migration.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.15 - (hide annotations) (download) (as text)
Tue Feb 17 07:19:23 2009 UTC (5 years, 6 months ago) by nightmorph
Branch: MAIN
Changes since 1.14: +15 -10 lines
File MIME type: application/xml
~arch xinit no longer provides /etc/env.d/90xsession. users have to create the env file manually. updated openrc guide, bug 229769.

1 nightmorph 1.1 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 nightmorph 1.15 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openrc-migration.xml,v 1.14 2009/02/12 00:59:32 nightmorph Exp $ -->
4 nightmorph 1.1
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 nightmorph 1.15 <version>1.9</version>
28     <date>2009-02-16</date>
29 nightmorph 1.1
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 nightmorph 1.4 Migration to OpenRC is fairly straightforward; it will be pulled in as part of
97     your regular upgrade process by your package manager. The most important step
98     actually comes after you install the new <c>>=sys-apps/baselayout-2</c> and
99     <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> is up to date before
101     rebooting. <brite>Failure to do so will result in an unbootable system</brite>
102     and will require the use of the Gentoo LiveCD to perform the steps below to
103     repair your system.
104 nightmorph 1.1 </p>
105    
106     <p>
107     Once you've finished updating your config files, there are a few things to
108 nightmorph 1.4 verify prior to rebooting.
109     </p>
110 nightmorph 1.1
111     </body>
112     </section>
113    
114     <section id="rc_conf">
115     <title>/etc/conf.d/rc</title>
116     <body>
117    
118     <p>
119     <path>/etc/conf.d/rc</path> has been deprecated and any settings you have in
120     there will need to be migrated to the appropriate settings in
121     <path>/etc/rc.conf</path>. Please read through <path>/etc/rc.conf</path> and
122     <path>/etc/conf.d/rc</path> and migrate the settings. Once you are complete,
123     delete <path>/etc/conf.d/rc</path>.
124     </p>
125    
126     </body>
127     </section>
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 nightmorph 1.5 <section id="boot">
195     <title>Boot runlevel</title>
196 nightmorph 1.1 <body>
197    
198     <p>
199 nightmorph 1.5 The <c>boot</c> runlevel performs several important steps for every machine. For
200     example, making sure your root filesystem is mounted read/write, that your
201     filesystems are checked for errors, that your mountpoints are available, and
202     that the <path>/proc</path> pseudo-filesystem is started at boot.
203 nightmorph 1.1 </p>
204    
205     <p>
206 nightmorph 1.5 With OpenRC, volume management services for your block storage devices are no
207     longer run automatically at boot. This includes lvm, raid, swap, device-mapper
208     (dm), dm-crypt, evms, and the like. You must ensure the appropriate initscript
209     for these services is in the <c>boot</c> runlevel, otherwise it's possible that
210     your system will not boot!
211 nightmorph 1.1 </p>
212    
213     <p>
214     While the OpenRC ebuild will attempt to do this migration for you, you should
215 nightmorph 1.5 verify that it migrated all the volume management services properly:
216 nightmorph 1.1 </p>
217    
218 nightmorph 1.5 <pre caption="Display all services in boot runlevel">
219 nightmorph 1.1 # <i>ls -l /etc/runlevels/boot/</i>
220     </pre>
221    
222     <p>
223 nightmorph 1.5 If you don't see root, procfs, mtab, swap, and fsck in the above listing,
224     perform the following to add them to the <c>boot</c> runlevel:
225 nightmorph 1.1 </p>
226    
227 nightmorph 1.9 <pre caption="Adding critical services to the boot runlevel">
228 nightmorph 1.5 # <i>rc-update add root boot</i>
229     # <i>rc-update add procfs boot</i>
230     # <i>rc-update add mtab boot</i>
231     # <i>rc-update add fsck boot</i>
232 nightmorph 1.1 # <i>rc-update add swap boot</i>
233     </pre>
234    
235 nightmorph 1.2 <p>
236 nightmorph 1.5 If you know you use mdraid and lvm but do not see them above, you would run
237     the following to add initscripts to the <c>boot</c> runlevel:
238 nightmorph 1.2 </p>
239    
240 nightmorph 1.6 <pre caption="Adding raid and lvm to the boot runlevel">
241 nightmorph 1.5 # <i>rc-update add raid boot</i>
242     # <i>rc-update add lvm boot</i>
243 nightmorph 1.2 </pre>
244    
245 nightmorph 1.1 </body>
246     </section>
247     <section>
248 nightmorph 1.13 <title>Udev</title>
249     <body>
250    
251     <p>
252     OpenRC no longer starts <c>udev</c> by default, but it does need to be present
253 nightmorph 1.14 in the <c>sysinit</c> runlevel to be started. The OpenRC ebuild should detect if
254     <c>udev</c> was previously enabled and add it to the <c>sysinit</c> runlevel.
255 nightmorph 1.13 However, to be safe, check if <c>udev</c> is present:
256     </p>
257    
258     <pre caption="Verifying udev">
259 nightmorph 1.14 # <i>ls -l /etc/runlevels/sysinit</i>
260     lrwxrwxrwx 1 root root 14 2009-01-29 08:00 /etc/runlevels/sysinit/udev -> \
261 nightmorph 1.13 /etc/init.d/udev
262     </pre>
263    
264     <p>
265     If <c>udev</c> is not listed, add it to the correct runlevel:
266     </p>
267    
268 nightmorph 1.14 <pre caption="Adding udev to the sysinit runlevel">
269     # <i>rc-update add udev sysinit</i>
270 nightmorph 1.13 </pre>
271    
272     </body>
273     </section>
274     <section>
275 nightmorph 1.9 <title>Network</title>
276     <body>
277    
278     <p>
279     Due to baselayout and OpenRC being broken into two different packages, your
280     net.eth0 initscript may disappear during the upgrade process. To replace this
281     initscript please perform the following:
282     </p>
283    
284     <pre caption="Adding back missing net.eth0 script">
285     # <i>cd /etc/init.d</i>
286     # <i>ln -s net.lo net.eth0</i>
287     </pre>
288    
289     <p>
290     If you are missing any other network initscripts, follow the instructions above
291 nightmorph 1.10 to re-add them. Simply replace <c>eth0</c> with the name of your network
292 nightmorph 1.9 device.
293     </p>
294    
295 nightmorph 1.10 <p>
296     Also, <path>/etc/conf.d/net</path> no longer uses bash-style arrays for
297     configuration. Please review <path>/usr/share/doc/openrc/net.example</path> for
298     configuration instructions. Conversion should be relatively straight-forward,
299     for example a static IP assignment would change as follows:
300     </p>
301    
302     <pre caption="Old /etc/conf.d/net style">
303     config_eth0=( "192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255" )
304     routes_eth0=( "default via 192.168.1.100" )
305     </pre>
306    
307     <pre caption="New /etc/conf.d/net style">
308     config_eth0="192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255"
309     routes_eth0="default via 192.168.1.100"
310     </pre>
311    
312 nightmorph 1.9 </body>
313     </section>
314     <section>
315 nightmorph 1.1 <title>Clock</title>
316     <body>
317    
318     <p>
319     Clock settings have been renamed from <path>/etc/conf.d/clock</path> to your
320     system's native tool for adjusting the clock. This means on Linux it will be
321     <path>/etc/conf.d/hwclock</path> and on FreeBSD it will be
322 nightmorph 1.2 <path>/etc/conf.d/adjkerntz</path>. The initscript in <path>/etc/init.d/</path>
323     has also been renamed accordingly, so make sure it's in the appropriate
324     runlevel.
325 nightmorph 1.1 </p>
326    
327     <p>
328     Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
329 vapier 1.8 contents are instead found in the <path>/etc/timezone</path> file. If it
330     doesn't exist, you will of course have to create it with your timezone. Please
331     review both of these files to ensure their correctness.
332 nightmorph 1.1 </p>
333    
334 nightmorph 1.9 <p>
335     The proper value for this file is the path relative to your timezone from
336     <path>/usr/share/zoneinfo</path>. For example, for someone living on the east
337     coast of the United States, the following would be a correct setting:
338     </p>
339    
340     <pre caption="/etc/timezone">
341     America/New_York
342     </pre>
343    
344 nightmorph 1.1 </body>
345     </section>
346     <section>
347     <title>XSESSION</title>
348     <body>
349    
350     <p>
351 nightmorph 1.15 The XSESSION variable is no longer found in <path>/etc/rc.conf</path>. Instead,
352     you can set the XSESSION variable per-user in <path>~/.bashrc</path> (or
353     equivalent), or system-wide in <path>/etc/env.d/</path>.
354 nightmorph 1.1 </p>
355    
356     <p>
357 nightmorph 1.15 Here's an example of setting XSESSION for the whole system:
358 nightmorph 1.1 </p>
359    
360 nightmorph 1.15 <pre caption="Setting XSESSION system-wide">
361     # <i>echo 'XSESSION="Xfce4"' > /etc/env.d/90xsession</i>
362     </pre>
363    
364 nightmorph 1.1 <impo>
365     You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
366 nightmorph 1.15 and then logout and login for it to take effect. If you set the variable in
367     <path>~/.bashrc</path>, you can re-source the file with <c>source
368     ~/.bashrc</c>.
369 nightmorph 1.1 </impo>
370    
371     </body>
372     </section>
373     <section>
374 nightmorph 1.15 <title>EDITOR and PAGER</title>
375 nightmorph 1.1 <body>
376    
377     <p>
378 vapier 1.7 The EDITOR variable is no longer found in <path>/etc/rc.conf</path>. Both
379 nightmorph 1.12 EDITOR and PAGER are set by default in <path>/etc/profile</path>. You should
380     change this as needed in your <path>~/.bashrc</path> (or equivalent) file or
381     create <path>/etc/env.d/99editor</path> and set the system default there.
382 nightmorph 1.1 </p>
383    
384     <impo>
385     You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
386     and then logout and login for it to take effect. If you set the variable in
387     <path>~/.bashrc</path>, you can re-source the file with <c>source
388     ~/.bashrc</c>.
389     </impo>
390    
391     </body>
392     </section>
393     <section>
394 nightmorph 1.11 <title>Boot log</title>
395     <body>
396    
397     <p>
398     Previously, you could log the boot process by using
399     <c>app-admin/showconsole</c>. However, OpenRC now handles all logging
400     internally, so there's no need for the hacks that <c>showconsole</c> employed.
401     You can safely unmerge <c>showconsole</c>. To continue logging boot messages,
402     just set the appropriate variable in <path>/etc/rc.conf</path>. Logs will appear
403     in <path>/var/log/rc.log</path>.
404     </p>
405    
406     <pre caption="Enabling boot logging in /etc/rc.conf">
407     rc_logger="YES"
408     </pre>
409    
410     </body>
411     </section>
412     <section>
413 nightmorph 1.1 <title>Finishing up</title>
414     <body>
415    
416     <p>
417     Once you've finished updating your config files and initscripts, the last thing
418     to do is <b>reboot</b>. This is necessary because system state information is
419     not preserved during the upgrade, so you'll need to provide it with a fresh
420     boot.
421     </p>
422    
423     </body>
424     </section>
425     </chapter>
426     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20