/[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.20 - (hide annotations) (download) (as text)
Thu Jan 13 03:19:01 2011 UTC (3 years, 8 months ago) by robbat2
Branch: MAIN
Changes since 1.19: +14 -9 lines
File MIME type: application/xml
Explicitly state that bash arrays with multiple entries should be converted to newlines.

1 nightmorph 1.1 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 robbat2 1.20 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openrc-migration.xml,v 1.19 2010/12/01 09:47:36 jkt 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 robbat2 1.20 <author title="Author">
15     <mail link="robbat2"/>
16     </author>
17 nightmorph 1.1 <author title="Contributor">
18     <mail link="uberlord"/>
19     </author>
20    
21     <abstract>
22     This guide shows you how to migrate from baselayout-1 to baselayout-2 and
23     OpenRC.
24     </abstract>
25    
26     <!-- The content of this document is licensed under the CC-BY-SA license -->
27     <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
28     <license/>
29    
30 robbat2 1.20 <version>4</version>
31     <date>2011-01-12</date>
32 nightmorph 1.1
33     <chapter>
34     <title>Background</title>
35     <section>
36     <title>What's baselayout?</title>
37     <body>
38    
39     <p>
40     Baselayout provides a basic set of files that are necessary for all systems to
41     function properly, such as <path>/etc/hosts</path>. It also provides the basic
42     filesystem layout used by Gentoo (i.e. <path>/etc</path>, <path>/var</path>,
43     <path>/usr</path>, <path>/home</path> directories).
44     </p>
45    
46     </body>
47     </section>
48     <section>
49     <title>What's OpenRC?</title>
50     <body>
51    
52     <p>
53     OpenRC is a dependency-based rc system that works with whatever init is provided
54     by the system, normally <path>/sbin/init</path>. However, it is <e>not</e> a
55     replacement for <path>/sbin/init</path>. The default init used by Gentoo Linux
56     is <c>sys-apps/sysvinit</c>, while Gentoo/FreeBSD uses the FreeBSD init provided
57     by <c>sys-freebsd/freebsd-sbin</c>.
58     </p>
59 nightmorph 1.16
60 nightmorph 1.1 </body>
61     </section>
62     <section>
63     <title>So why migrate?</title>
64     <body>
65    
66     <p>
67     Originally Gentoo's rc system was built into baselayout 1 and written entirely
68     in bash. This led to several limitations. For example, certain system calls need
69     to be accessed during boot and this required C-based callouts to be added. These
70     callouts were each statically linked, causing the rc system to bloat over time.
71     </p>
72    
73     <p>
74     Additionally, as Gentoo expanded to other platforms like
75     Gentoo/FreeBSD and Gentoo Embedded, it became impossible to require a bash-based
76     rc system. This led to a development of baselayout 2, which is written in
77     C and only requires a POSIX-compliant shell. During the development of
78     baselayout 2, it was determined that it was a better fit if baselayout merely
79     provided the base files and filesystem layout for Gentoo and the rc system
80     was broken off into its own package. Thus we have OpenRC.
81     </p>
82    
83     <p>
84     OpenRC is primarily developed by <uri link="http://roy.marples.name/openrc">Roy
85     Marples</uri> and supports all current Gentoo variations (i.e. Gentoo Linux,
86     Gentoo/FreeBSD, Gentoo Embedded, and Gentoo Vserver) and other platforms such as
87     FreeBSD and NetBSD.
88     </p>
89    
90     </body>
91     </section>
92     </chapter>
93    
94     <chapter>
95     <title>Migration to OpenRC</title>
96     <section>
97     <body>
98    
99     <p>
100 nightmorph 1.4 Migration to OpenRC is fairly straightforward; it will be pulled in as part of
101     your regular upgrade process by your package manager. The most important step
102     actually comes after you install the new <c>>=sys-apps/baselayout-2</c> and
103     <c>sys-apps/openrc</c> packages. It is <e>critical</e> that you run
104     <c>dispatch-conf</c> and ensure your <path>/etc</path> is up to date before
105     rebooting. <brite>Failure to do so will result in an unbootable system</brite>
106     and will require the use of the Gentoo LiveCD to perform the steps below to
107     repair your system.
108 nightmorph 1.1 </p>
109    
110     <p>
111     Once you've finished updating your config files, there are a few things to
112 nightmorph 1.4 verify prior to rebooting.
113     </p>
114 nightmorph 1.1
115     </body>
116     </section>
117    
118     <section id="rc_conf">
119     <title>/etc/conf.d/rc</title>
120     <body>
121    
122     <p>
123     <path>/etc/conf.d/rc</path> has been deprecated and any settings you have in
124     there will need to be migrated to the appropriate settings in
125     <path>/etc/rc.conf</path>. Please read through <path>/etc/rc.conf</path> and
126     <path>/etc/conf.d/rc</path> and migrate the settings. Once you are complete,
127     delete <path>/etc/conf.d/rc</path>.
128     </p>
129    
130     </body>
131     </section>
132     <section id="modules">
133     <title>Kernel modules</title>
134     <body>
135    
136     <p>
137     Normally, when you want certain kernel modules automatically loaded at boot, you
138     place them into <path>/etc/modules.autoload.d/kernel-2.6</path> along with any
139     parameters you wanted to pass to them. In baselayout-2, this file is not used
140     anymore. Instead, autoloaded modules and module parameters are placed in one
141     file, <path>/etc/conf.d/modules</path>, no matter the kernel version.
142     </p>
143    
144     <p>
145     An example old style configuration would be:
146     </p>
147    
148     <pre caption="/etc/modules.autoload.d/kernel-2.6">
149     ivtv
150     cx88_dvb video_br=2
151     </pre>
152    
153     <p>
154     Converting the above example would result in the following:
155     </p>
156    
157     <pre caption="/etc/conf.d/modules">
158     <comment># Modules autoloaded at boot</comment>
159     modules_2_6="ivtv cx88_dvb"
160     <comment># Module parameters</comment>
161     module_cx88_dvb_args_2_6="video_br=2"
162     </pre>
163    
164     <p>
165     In the above examples, the modules and their parameters would only be passed
166     to 2.6.x series kernels. The new configuration allows for fine grained
167     control over the modules and parameters based on kernel version.
168     </p>
169    
170     <p>
171     An in-depth example would be:
172     </p>
173    
174     <pre caption="detailed example of /etc/conf.d/modules">
175     <comment># Always load ochi1394 and ieee1394, no matter the kernel version</comment>
176     modules="ohci1394 ieee1394"
177     <comment># Only load tun and usbserial for 2.6.x series kernels</comment>
178     modules_2_6="tun usbserial"
179     <comment># Only load cx88_dvb for 2.6.23 kernels</comment>
180     modules_2_6_23="cx88_dvb"
181     <comment># Only load ivtv for 2.6.23-gentoo-r5</comment>
182     modules_2_6_23_gentoo_r5="ivtv"
183    
184     <comment># For 2.6.23-gentoo-r5, pass video_br=2 to cx88_dvb</comment>
185     module_cx88_dvb_args_2_6_23_gentoo_r5="video_br=2"
186     <comment># For 2.6.x series kernels, always pass vendor and product</comment>
187     module_usbserial_args_2_6="vendor=0x1410 product=0x2110"
188     <comment># Always pass debug to ieee1394</comment>
189     module_ieee1394_args="debug"
190     </pre>
191    
192 nightmorph 1.18 <impo>
193     The <b>module*</b> variables are not cumulative. The more version-specific
194     variables will override the more general variables.
195     </impo>
196    
197 nightmorph 1.1 <note>
198     Please note the difference between <b>module_</b> and <b>modules_</b>.
199     </note>
200    
201     </body>
202     </section>
203 nightmorph 1.5 <section id="boot">
204     <title>Boot runlevel</title>
205 nightmorph 1.1 <body>
206    
207     <p>
208 nightmorph 1.5 The <c>boot</c> runlevel performs several important steps for every machine. For
209     example, making sure your root filesystem is mounted read/write, that your
210     filesystems are checked for errors, that your mountpoints are available, and
211     that the <path>/proc</path> pseudo-filesystem is started at boot.
212 nightmorph 1.1 </p>
213    
214     <p>
215 nightmorph 1.5 With OpenRC, volume management services for your block storage devices are no
216     longer run automatically at boot. This includes lvm, raid, swap, device-mapper
217     (dm), dm-crypt, evms, and the like. You must ensure the appropriate initscript
218     for these services is in the <c>boot</c> runlevel, otherwise it's possible that
219     your system will not boot!
220 nightmorph 1.1 </p>
221    
222     <p>
223     While the OpenRC ebuild will attempt to do this migration for you, you should
224 nightmorph 1.5 verify that it migrated all the volume management services properly:
225 nightmorph 1.1 </p>
226    
227 nightmorph 1.5 <pre caption="Display all services in boot runlevel">
228 nightmorph 1.1 # <i>ls -l /etc/runlevels/boot/</i>
229     </pre>
230    
231     <p>
232 nightmorph 1.5 If you don't see root, procfs, mtab, swap, and fsck in the above listing,
233     perform the following to add them to the <c>boot</c> runlevel:
234 nightmorph 1.1 </p>
235    
236 nightmorph 1.9 <pre caption="Adding critical services to the boot runlevel">
237 nightmorph 1.5 # <i>rc-update add root boot</i>
238     # <i>rc-update add procfs boot</i>
239     # <i>rc-update add mtab boot</i>
240     # <i>rc-update add fsck boot</i>
241 nightmorph 1.1 # <i>rc-update add swap boot</i>
242     </pre>
243    
244 nightmorph 1.2 <p>
245 nightmorph 1.5 If you know you use mdraid and lvm but do not see them above, you would run
246     the following to add initscripts to the <c>boot</c> runlevel:
247 nightmorph 1.2 </p>
248    
249 nightmorph 1.17 <pre caption="Adding mdraid and lvm to the boot runlevel">
250     # <i>rc-update add mdraid boot</i>
251 nightmorph 1.5 # <i>rc-update add lvm boot</i>
252 nightmorph 1.2 </pre>
253    
254 nightmorph 1.1 </body>
255     </section>
256     <section>
257 nightmorph 1.13 <title>Udev</title>
258     <body>
259    
260     <p>
261     OpenRC no longer starts <c>udev</c> by default, but it does need to be present
262 nightmorph 1.14 in the <c>sysinit</c> runlevel to be started. The OpenRC ebuild should detect if
263     <c>udev</c> was previously enabled and add it to the <c>sysinit</c> runlevel.
264 nightmorph 1.13 However, to be safe, check if <c>udev</c> is present:
265     </p>
266    
267     <pre caption="Verifying udev">
268 nightmorph 1.14 # <i>ls -l /etc/runlevels/sysinit</i>
269     lrwxrwxrwx 1 root root 14 2009-01-29 08:00 /etc/runlevels/sysinit/udev -> \
270 nightmorph 1.13 /etc/init.d/udev
271     </pre>
272    
273     <p>
274     If <c>udev</c> is not listed, add it to the correct runlevel:
275     </p>
276    
277 nightmorph 1.14 <pre caption="Adding udev to the sysinit runlevel">
278     # <i>rc-update add udev sysinit</i>
279 nightmorph 1.13 </pre>
280    
281     </body>
282     </section>
283     <section>
284 nightmorph 1.9 <title>Network</title>
285     <body>
286    
287     <p>
288     Due to baselayout and OpenRC being broken into two different packages, your
289     net.eth0 initscript may disappear during the upgrade process. To replace this
290     initscript please perform the following:
291     </p>
292    
293     <pre caption="Adding back missing net.eth0 script">
294     # <i>cd /etc/init.d</i>
295     # <i>ln -s net.lo net.eth0</i>
296     </pre>
297    
298     <p>
299     If you are missing any other network initscripts, follow the instructions above
300 nightmorph 1.10 to re-add them. Simply replace <c>eth0</c> with the name of your network
301 nightmorph 1.9 device.
302     </p>
303    
304 nightmorph 1.10 <p>
305 robbat2 1.20 Also, <path>/etc/conf.d/net</path> (oldnet) no longer uses bash-style arrays
306     for configuration. Please review
307 nightmorph 1.17 <path>/usr/share/doc/openrc-&lt;version&gt;/net.example</path> for configuration
308 robbat2 1.20 instructions. Conversion should be relatively straight-forward, converting to
309     newlines for seperate entries, for example a static IP assignment would change
310     as follows:
311 nightmorph 1.10 </p>
312    
313     <pre caption="Old /etc/conf.d/net style">
314     config_eth0=( "192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255" )
315 robbat2 1.20 routes_eth0=( "default via 192.168.1.100" "10.0.0.0/8 via 192.168.1.2" )
316 nightmorph 1.10 </pre>
317    
318     <pre caption="New /etc/conf.d/net style">
319     config_eth0="192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255"
320 robbat2 1.20 routes_eth0="default via 192.168.1.100
321     10.0.0.0/8 via 192.168.1.2"
322 nightmorph 1.10 </pre>
323    
324 nightmorph 1.9 </body>
325     </section>
326     <section>
327 nightmorph 1.1 <title>Clock</title>
328     <body>
329    
330     <p>
331     Clock settings have been renamed from <path>/etc/conf.d/clock</path> to your
332     system's native tool for adjusting the clock. This means on Linux it will be
333     <path>/etc/conf.d/hwclock</path> and on FreeBSD it will be
334 nightmorph 1.16 <path>/etc/conf.d/adjkerntz</path>. Systems without a working real time clock
335     (RTC) chip should use <path>/etc/init.d/swclock</path>, which sets the system
336     time based on the mtime of a file which is created at system shutdown. The
337     initscripts in <path>/etc/init.d/</path> have also been renamed accordingly, so
338     make sure the appropriate script for your system has been added to the boot
339 nightmorph 1.2 runlevel.
340 nightmorph 1.1 </p>
341    
342     <p>
343     Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
344 vapier 1.8 contents are instead found in the <path>/etc/timezone</path> file. If it
345     doesn't exist, you will of course have to create it with your timezone. Please
346     review both of these files to ensure their correctness.
347 nightmorph 1.1 </p>
348    
349 nightmorph 1.9 <p>
350     The proper value for this file is the path relative to your timezone from
351     <path>/usr/share/zoneinfo</path>. For example, for someone living on the east
352     coast of the United States, the following would be a correct setting:
353     </p>
354    
355     <pre caption="/etc/timezone">
356     America/New_York
357     </pre>
358    
359 nightmorph 1.1 </body>
360     </section>
361     <section>
362     <title>XSESSION</title>
363     <body>
364    
365     <p>
366 nightmorph 1.15 The XSESSION variable is no longer found in <path>/etc/rc.conf</path>. Instead,
367     you can set the XSESSION variable per-user in <path>~/.bashrc</path> (or
368     equivalent), or system-wide in <path>/etc/env.d/</path>.
369 nightmorph 1.1 </p>
370    
371     <p>
372 nightmorph 1.15 Here's an example of setting XSESSION for the whole system:
373 nightmorph 1.1 </p>
374    
375 nightmorph 1.15 <pre caption="Setting XSESSION system-wide">
376     # <i>echo 'XSESSION="Xfce4"' > /etc/env.d/90xsession</i>
377     </pre>
378    
379 nightmorph 1.1 <impo>
380     You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
381 nightmorph 1.15 and then logout and login for it to take effect. If you set the variable in
382     <path>~/.bashrc</path>, you can re-source the file with <c>source
383     ~/.bashrc</c>.
384 nightmorph 1.1 </impo>
385    
386     </body>
387     </section>
388     <section>
389 nightmorph 1.15 <title>EDITOR and PAGER</title>
390 nightmorph 1.1 <body>
391    
392     <p>
393 vapier 1.7 The EDITOR variable is no longer found in <path>/etc/rc.conf</path>. Both
394 nightmorph 1.12 EDITOR and PAGER are set by default in <path>/etc/profile</path>. You should
395     change this as needed in your <path>~/.bashrc</path> (or equivalent) file or
396     create <path>/etc/env.d/99editor</path> and set the system default there.
397 nightmorph 1.1 </p>
398    
399     <impo>
400     You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
401     and then logout and login for it to take effect. If you set the variable in
402     <path>~/.bashrc</path>, you can re-source the file with <c>source
403     ~/.bashrc</c>.
404     </impo>
405    
406     </body>
407     </section>
408     <section>
409 nightmorph 1.11 <title>Boot log</title>
410     <body>
411    
412     <p>
413     Previously, you could log the boot process by using
414     <c>app-admin/showconsole</c>. However, OpenRC now handles all logging
415     internally, so there's no need for the hacks that <c>showconsole</c> employed.
416     You can safely unmerge <c>showconsole</c>. To continue logging boot messages,
417     just set the appropriate variable in <path>/etc/rc.conf</path>. Logs will appear
418     in <path>/var/log/rc.log</path>.
419     </p>
420    
421     <pre caption="Enabling boot logging in /etc/rc.conf">
422     rc_logger="YES"
423     </pre>
424    
425     </body>
426     </section>
427     <section>
428 nightmorph 1.1 <title>Finishing up</title>
429     <body>
430    
431     <p>
432     Once you've finished updating your config files and initscripts, the last thing
433     to do is <b>reboot</b>. This is necessary because system state information is
434     not preserved during the upgrade, so you'll need to provide it with a fresh
435     boot.
436     </p>
437    
438     </body>
439     </section>
440     </chapter>
441 jkt 1.19 <chapter>
442     <title>Changed functionality</title>
443     <section>
444     <title>The pause action</title>
445     <body>
446    
447     <p>
448     Previously it was possible to temporarily stop a service without taking down all
449     the depending services by using <c>/etc/init.d/service pause</c>. In OpenRC, the
450     <c>pause</c> action was removed; this functionality is supported by the
451     <c>/etc/init.d/service --nodeps stop</c>, which also works in the old
452     baselayout.
453     </p>
454    
455     </body>
456     </section>
457     </chapter>
458 nightmorph 1.1 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20