/[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.32 - (hide annotations) (download) (as text)
Sun May 29 07:00:18 2011 UTC (3 years, 3 months ago) by nightmorph
Branch: MAIN
Changes since 1.31: +2 -2 lines
File MIME type: application/xml
typo fix, caught by ssuominen, via irc

1 nightmorph 1.1 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 nightmorph 1.32 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openrc-migration.xml,v 1.31 2011/05/29 00:45:35 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.31 <version>11</version>
31 nightmorph 1.30 <date>2011-05-28</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 nightmorph 1.30 initscript and re-add it to the default runlevel, please perform the
292     following:
293 nightmorph 1.9 </p>
294    
295     <pre caption="Adding back missing net.eth0 script">
296     # <i>cd /etc/init.d</i>
297     # <i>ln -s net.lo net.eth0</i>
298 nightmorph 1.32 # <i>rc-update add net.eth0 default</i>
299 nightmorph 1.9 </pre>
300    
301     <p>
302     If you are missing any other network initscripts, follow the instructions above
303 nightmorph 1.10 to re-add them. Simply replace <c>eth0</c> with the name of your network
304 nightmorph 1.9 device.
305     </p>
306    
307 nightmorph 1.10 <p>
308 robbat2 1.20 Also, <path>/etc/conf.d/net</path> (oldnet) no longer uses bash-style arrays
309     for configuration. Please review
310 nightmorph 1.17 <path>/usr/share/doc/openrc-&lt;version&gt;/net.example</path> for configuration
311 robbat2 1.20 instructions. Conversion should be relatively straight-forward, converting to
312     newlines for seperate entries, for example a static IP assignment would change
313     as follows:
314 nightmorph 1.10 </p>
315    
316     <pre caption="Old /etc/conf.d/net style">
317     config_eth0=( "192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255" )
318 robbat2 1.20 routes_eth0=( "default via 192.168.1.100" "10.0.0.0/8 via 192.168.1.2" )
319 nightmorph 1.10 </pre>
320    
321     <pre caption="New /etc/conf.d/net style">
322     config_eth0="192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255"
323 robbat2 1.20 routes_eth0="default via 192.168.1.100
324     10.0.0.0/8 via 192.168.1.2"
325 nightmorph 1.10 </pre>
326    
327 nightmorph 1.9 </body>
328     </section>
329     <section>
330 nightmorph 1.1 <title>Clock</title>
331     <body>
332    
333     <p>
334     Clock settings have been renamed from <path>/etc/conf.d/clock</path> to your
335     system's native tool for adjusting the clock. This means on Linux it will be
336     <path>/etc/conf.d/hwclock</path> and on FreeBSD it will be
337 nightmorph 1.16 <path>/etc/conf.d/adjkerntz</path>. Systems without a working real time clock
338     (RTC) chip should use <path>/etc/init.d/swclock</path>, which sets the system
339     time based on the mtime of a file which is created at system shutdown. The
340     initscripts in <path>/etc/init.d/</path> have also been renamed accordingly, so
341     make sure the appropriate script for your system has been added to the boot
342 nightmorph 1.2 runlevel.
343 nightmorph 1.1 </p>
344    
345     <p>
346     Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
347 vapier 1.8 contents are instead found in the <path>/etc/timezone</path> file. If it
348     doesn't exist, you will of course have to create it with your timezone. Please
349     review both of these files to ensure their correctness.
350 nightmorph 1.1 </p>
351    
352 nightmorph 1.9 <p>
353     The proper value for this file is the path relative to your timezone from
354     <path>/usr/share/zoneinfo</path>. For example, for someone living on the east
355     coast of the United States, the following would be a correct setting:
356     </p>
357    
358     <pre caption="/etc/timezone">
359     America/New_York
360     </pre>
361    
362 nightmorph 1.1 </body>
363     </section>
364     <section>
365     <title>XSESSION</title>
366     <body>
367    
368     <p>
369 nightmorph 1.15 The XSESSION variable is no longer found in <path>/etc/rc.conf</path>. Instead,
370     you can set the XSESSION variable per-user in <path>~/.bashrc</path> (or
371     equivalent), or system-wide in <path>/etc/env.d/</path>.
372 nightmorph 1.1 </p>
373    
374     <p>
375 nightmorph 1.15 Here's an example of setting XSESSION for the whole system:
376 nightmorph 1.1 </p>
377    
378 nightmorph 1.15 <pre caption="Setting XSESSION system-wide">
379     # <i>echo 'XSESSION="Xfce4"' > /etc/env.d/90xsession</i>
380     </pre>
381    
382 nightmorph 1.1 <impo>
383     You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
384 nightmorph 1.15 and then logout and login for it to take effect. If you set the variable in
385     <path>~/.bashrc</path>, you can re-source the file with <c>source
386     ~/.bashrc</c>.
387 nightmorph 1.1 </impo>
388    
389     </body>
390     </section>
391     <section>
392 nightmorph 1.15 <title>EDITOR and PAGER</title>
393 nightmorph 1.1 <body>
394    
395     <p>
396 vapier 1.7 The EDITOR variable is no longer found in <path>/etc/rc.conf</path>. Both
397 nightmorph 1.12 EDITOR and PAGER are set by default in <path>/etc/profile</path>. You should
398     change this as needed in your <path>~/.bashrc</path> (or equivalent) file or
399     create <path>/etc/env.d/99editor</path> and set the system default there.
400 nightmorph 1.1 </p>
401    
402     <impo>
403     You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
404     and then logout and login for it to take effect. If you set the variable in
405     <path>~/.bashrc</path>, you can re-source the file with <c>source
406     ~/.bashrc</c>.
407     </impo>
408    
409     </body>
410     </section>
411     <section>
412 nightmorph 1.11 <title>Boot log</title>
413     <body>
414    
415     <p>
416     Previously, you could log the boot process by using
417     <c>app-admin/showconsole</c>. However, OpenRC now handles all logging
418     internally, so there's no need for the hacks that <c>showconsole</c> employed.
419     You can safely unmerge <c>showconsole</c>. To continue logging boot messages,
420     just set the appropriate variable in <path>/etc/rc.conf</path>. Logs will appear
421     in <path>/var/log/rc.log</path>.
422     </p>
423    
424     <pre caption="Enabling boot logging in /etc/rc.conf">
425     rc_logger="YES"
426     </pre>
427    
428     </body>
429     </section>
430 nightmorph 1.31 <section id="rc_local">
431     <title>local.start and local.stop</title>
432     <body>
433    
434     <p>
435     With OpenRC, <path>/etc/conf.d/local.start</path> and <path>local.stop</path>
436     are deprecated. During the migration to OpenRC, the files are moved to
437     <path>/etc/local.d</path> and gain the suffix <path>.start</path> or
438     <path>.stop</path>. OpenRC then executes those in alphabetic order.
439     </p>
440    
441     </body>
442     </section>
443 robbat2 1.23 <section id="rc_sys">
444     <title>System sub-types: Virtualization special cases</title>
445     <body>
446    
447     <p>
448     In the early versions of OpenRC, we explictly detected multiple types of
449     virtualization, and used that detection to note when certain init scripts
450     should be skipped, using the <b>keyword</b> call in the <b>depend</b>
451     functions.
452     </p>
453    
454     <p>
455     However, as of the 0.7.0 release, you are required to explicitly configure the
456 robbat2 1.25 sub-type using the <b>rc_sys</b> variable in <path>/etc/rc.conf</path>. The
457     sub-type should be set to match the virtualization environment that the given
458     root is in. In general, the non-empty <b>rc_sys</b> value should be within the
459     virtual containers; The host node will have <b>rc_sys=""</b>.
460 robbat2 1.23 </p>
461    
462     <impo>
463     If you do not have any specific sub-type, please use the default of an empty
464     string <b>""</b>. If the variable is unset, you will be given a warning and we
465     will attempt to use the old detection algorithm.
466     </impo>
467    
468 robbat2 1.26 <note>
469     If you do not know what value your system was using with the automatic
470     detection, you should temporarily comment out the <b>rc_sys</b> variable and
471     run the detection command, <c>rc -S</c>.
472     </note>
473    
474 robbat2 1.23 <pre caption="Setting system sub-type to none in /etc/rc.conf">
475     rc_sys=""
476     </pre>
477    
478 nightmorph 1.29 <p>
479     The detection algorithm had to be replaced with manual configuration due to
480 robbat2 1.23 the introduction of new sub-types and changes to the kernel that made prior
481 nightmorph 1.29 detection unreliable.
482     </p>
483 robbat2 1.23
484     <table>
485     <tr>
486     <th>Subtype</th>
487     <th>Description</th>
488     <th>Notes</th>
489     </tr>
490     <tr>
491     <ti></ti>
492     <ti>Default, no sub-type</ti>
493     <ti>Not the same as unset; FreeBSD, Linux &amp; NetBSD</ti>
494     </tr>
495     <tr>
496     <ti>jail</ti>
497     <ti>FreeBSD jails</ti>
498     <ti></ti>
499     </tr>
500     <tr>
501     <ti>lxc</ti>
502     <ti>Linux Containers</ti>
503     <ti>Not auto-detected</ti>
504     </tr>
505     <tr>
506     <ti>openvz</ti>
507     <ti>Linux OpenVZ</ti>
508     <ti></ti>
509     </tr>
510     <tr>
511     <ti>prefix</ti>
512     <ti>Prefix</ti>
513     <ti>Not auto-detected; FreeBSD, Linux &amp; NetBSD</ti>
514     </tr>
515     <tr>
516     <ti>vserver</ti>
517     <ti>Linux vserver</ti>
518     <ti></ti>
519     </tr>
520     <tr>
521     <ti>xen0</ti>
522     <ti>Xen0 Domain</ti>
523     <ti>Linux &amp; NetBSD</ti>
524     </tr>
525     <tr>
526     <ti>xenU</ti>
527     <ti>XenU Domain</ti>
528     <ti>Linux &amp; NetBSD</ti>
529     </tr>
530     </table>
531    
532     </body>
533     </section>
534 nightmorph 1.11 <section>
535 nightmorph 1.1 <title>Finishing up</title>
536     <body>
537    
538     <p>
539     Once you've finished updating your config files and initscripts, the last thing
540     to do is <b>reboot</b>. This is necessary because system state information is
541     not preserved during the upgrade, so you'll need to provide it with a fresh
542     boot.
543     </p>
544    
545     </body>
546     </section>
547 nightmorph 1.28 </chapter>
548 robbat2 1.22
549 jkt 1.19 <chapter>
550     <title>Changed functionality</title>
551     <section>
552     <title>The pause action</title>
553     <body>
554    
555     <p>
556     Previously it was possible to temporarily stop a service without taking down all
557     the depending services by using <c>/etc/init.d/service pause</c>. In OpenRC, the
558     <c>pause</c> action was removed; this functionality is supported by the
559     <c>/etc/init.d/service --nodeps stop</c>, which also works in the old
560     baselayout.
561     </p>
562    
563     </body>
564     </section>
565 robbat2 1.27 <section>
566     <title>rootfs entry in /etc/mtab</title>
567     <body>
568    
569     <p>
570     Previously, the initial <b>rootfs</b> entry was removed from
571     <path>/etc/mtab</path>, and only the real root <path>/</path> entry was
572 nightmorph 1.28 present. The duplicate rootfs item was actually added back during shutdown.
573 robbat2 1.27 In OpenRC, both entries must be present for full support of initramfs and
574     tmpfs-on-root. This also means that less writing is required during shutdown.
575     </p>
576    
577     </body>
578     </section>
579 jkt 1.19 </chapter>
580 nightmorph 1.1 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20