/[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.29 - (hide annotations) (download) (as text)
Thu Apr 14 05:56:41 2011 UTC (3 years, 8 months ago) by nightmorph
Branch: MAIN
Changes since 1.28: +7 -10 lines
File MIME type: application/xml
usermode-sources is being removed from the tree; see email to gentoo-dev-announce

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

  ViewVC Help
Powered by ViewVC 1.1.20