/[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.28 - (show annotations) (download) (as text)
Wed Mar 2 09:03:23 2011 UTC (3 years, 1 month ago) by nightmorph
Branch: MAIN
Changes since 1.27: +4 -41 lines
File MIME type: application/xml
remove markup spam. no content change, so no revbump.

1 <?xml version='1.0' encoding='UTF-8'?>
2 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openrc-migration.xml,v 1.27 2011/01/17 07:56:56 robbat2 Exp $ -->
4
5 <guide>
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 <author title="Author">
15 <mail link="robbat2"/>
16 </author>
17 <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 <version>8</version>
31 <date>2011-01-17</date>
32
33 <chapter>
34 <title>Background</title>
35
36 <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
50 <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
62 </body>
63 </section>
64
65 <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 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 </p>
111
112 <p>
113 Once you've finished updating your config files, there are a few things to
114 verify prior to rebooting.
115 </p>
116
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 <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 <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 <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
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 <section id="boot">
205 <title>Boot runlevel</title>
206 <body>
207
208 <p>
209 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 </p>
214
215 <p>
216 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 </p>
222
223 <p>
224 While the OpenRC ebuild will attempt to do this migration for you, you should
225 verify that it migrated all the volume management services properly:
226 </p>
227
228 <pre caption="Display all services in boot runlevel">
229 # <i>ls -l /etc/runlevels/boot/</i>
230 </pre>
231
232 <p>
233 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 </p>
236
237 <pre caption="Adding critical services to the boot runlevel">
238 # <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 # <i>rc-update add swap boot</i>
243 </pre>
244
245 <p>
246 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 </p>
249
250 <pre caption="Adding mdraid and lvm to the boot runlevel">
251 # <i>rc-update add mdraid boot</i>
252 # <i>rc-update add lvm boot</i>
253 </pre>
254
255 </body>
256 </section>
257 <section>
258 <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 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 However, to be safe, check if <c>udev</c> is present:
266 </p>
267
268 <pre caption="Verifying udev">
269 # <i>ls -l /etc/runlevels/sysinit</i>
270 lrwxrwxrwx 1 root root 14 2009-01-29 08:00 /etc/runlevels/sysinit/udev -> \
271 /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 <pre caption="Adding udev to the sysinit runlevel">
279 # <i>rc-update add udev sysinit</i>
280 </pre>
281
282 </body>
283 </section>
284 <section>
285 <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 to re-add them. Simply replace <c>eth0</c> with the name of your network
302 device.
303 </p>
304
305 <p>
306 Also, <path>/etc/conf.d/net</path> (oldnet) no longer uses bash-style arrays
307 for configuration. Please review
308 <path>/usr/share/doc/openrc-&lt;version&gt;/net.example</path> for configuration
309 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 </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 routes_eth0=( "default via 192.168.1.100" "10.0.0.0/8 via 192.168.1.2" )
317 </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 routes_eth0="default via 192.168.1.100
322 10.0.0.0/8 via 192.168.1.2"
323 </pre>
324
325 </body>
326 </section>
327 <section>
328 <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 <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 runlevel.
341 </p>
342
343 <p>
344 Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
345 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 </p>
349
350 <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 </body>
361 </section>
362 <section>
363 <title>XSESSION</title>
364 <body>
365
366 <p>
367 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 </p>
371
372 <p>
373 Here's an example of setting XSESSION for the whole system:
374 </p>
375
376 <pre caption="Setting XSESSION system-wide">
377 # <i>echo 'XSESSION="Xfce4"' > /etc/env.d/90xsession</i>
378 </pre>
379
380 <impo>
381 You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
382 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 </impo>
386
387 </body>
388 </section>
389 <section>
390 <title>EDITOR and PAGER</title>
391 <body>
392
393 <p>
394 The EDITOR variable is no longer found in <path>/etc/rc.conf</path>. Both
395 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 </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 <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 <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 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 </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 <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 <pre caption="Setting system sub-type to none in /etc/rc.conf">
460 rc_sys=""
461 </pre>
462
463 <p>The detection algorithm had to be replaced with manual configuration due to
464 the introduction of new sub-types and changes to the kernel that made prior
465 detection unreliable.</p>
466
467 <table>
468 <tr>
469 <th>Subtype</th>
470 <th>Description</th>
471 <th>Notes</th>
472 </tr>
473 <tr>
474 <ti></ti>
475 <ti>Default, no sub-type</ti>
476 <ti>Not the same as unset; FreeBSD, Linux &amp; NetBSD</ti>
477 </tr>
478 <tr>
479 <ti>jail</ti>
480 <ti>FreeBSD jails</ti>
481 <ti></ti>
482 </tr>
483 <tr>
484 <ti>lxc</ti>
485 <ti>Linux Containers</ti>
486 <ti>Not auto-detected</ti>
487 </tr>
488 <tr>
489 <ti>openvz</ti>
490 <ti>Linux OpenVZ</ti>
491 <ti></ti>
492 </tr>
493 <tr>
494 <ti>prefix</ti>
495 <ti>Prefix</ti>
496 <ti>Not auto-detected; FreeBSD, Linux &amp; NetBSD</ti>
497 </tr>
498 <tr>
499 <ti>uml</ti>
500 <ti>Usermode Linux</ti>
501 <ti></ti>
502 </tr>
503 <tr>
504 <ti>vserver</ti>
505 <ti>Linux vserver</ti>
506 <ti></ti>
507 </tr>
508 <tr>
509 <ti>xen0</ti>
510 <ti>Xen0 Domain</ti>
511 <ti>Linux &amp; NetBSD</ti>
512 </tr>
513 <tr>
514 <ti>xenU</ti>
515 <ti>XenU Domain</ti>
516 <ti>Linux &amp; NetBSD</ti>
517 </tr>
518 </table>
519
520 </body>
521 </section>
522 <section>
523 <title>Finishing up</title>
524 <body>
525
526 <p>
527 Once you've finished updating your config files and initscripts, the last thing
528 to do is <b>reboot</b>. This is necessary because system state information is
529 not preserved during the upgrade, so you'll need to provide it with a fresh
530 boot.
531 </p>
532
533 </body>
534 </section>
535 </chapter>
536
537 <chapter>
538 <title>Changed functionality</title>
539 <section>
540 <title>The pause action</title>
541 <body>
542
543 <p>
544 Previously it was possible to temporarily stop a service without taking down all
545 the depending services by using <c>/etc/init.d/service pause</c>. In OpenRC, the
546 <c>pause</c> action was removed; this functionality is supported by the
547 <c>/etc/init.d/service --nodeps stop</c>, which also works in the old
548 baselayout.
549 </p>
550
551 </body>
552 </section>
553 <section>
554 <title>rootfs entry in /etc/mtab</title>
555 <body>
556
557 <p>
558 Previously, the initial <b>rootfs</b> entry was removed from
559 <path>/etc/mtab</path>, and only the real root <path>/</path> entry was
560 present. The duplicate rootfs item was actually added back during shutdown.
561 In OpenRC, both entries must be present for full support of initramfs and
562 tmpfs-on-root. This also means that less writing is required during shutdown.
563 </p>
564
565 </body>
566 </section>
567 </chapter>
568 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20