/[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.27 - (hide annotations) (download) (as text)
Mon Jan 17 07:56:56 2011 UTC (3 years, 8 months ago) by robbat2
Branch: MAIN
Changes since 1.26: +20 -3 lines
File MIME type: application/xml
Bug #219038: Document rootfs duplicate "/" entry in /etc/mtab under OpenRC.

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

  ViewVC Help
Powered by ViewVC 1.1.20