/[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.34 - (hide annotations) (download) (as text)
Sat Sep 3 07:18:26 2011 UTC (2 years, 11 months ago) by swift
Branch: MAIN
Changes since 1.33: +4 -4 lines
File MIME type: application/xml
Bug #372427 - Remove EVMS from documentation as it is not supported anymore

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

  ViewVC Help
Powered by ViewVC 1.1.20