/[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.24 - (show annotations) (download) (as text)
Thu Jan 13 04:28:00 2011 UTC (3 years, 6 months ago) by robbat2
Branch: MAIN
Changes since 1.23: +2 -2 lines
File MIME type: application/xml
Bump version post rc_sys addition.

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.23 2011/01/13 04:26:14 robbat2 Exp $ -->
4
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 <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>5</version>
31 <date>2011-01-12</date>
32
33 <chapter>
34 <title>Background</title>
35
36 <!-- =============================================================== -->
37 <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 <!-- =============================================================== -->
51
52 <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
64 </body>
65 </section>
66 <!-- =============================================================== -->
67
68 <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 <!-- =============================================================== -->
99
100 </chapter>
101 <chapter>
102 <title>Migration to OpenRC</title>
103
104 <!-- =============================================================== -->
105 <section>
106 <body>
107
108 <p>
109 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 </p>
118
119 <p>
120 Once you've finished updating your config files, there are a few things to
121 verify prior to rebooting.
122 </p>
123
124 </body>
125 </section>
126 <!-- =============================================================== -->
127
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 <!-- =============================================================== -->
143
144 <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 <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 <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 <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
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
216 <!-- =============================================================== -->
217 <section id="boot">
218 <title>Boot runlevel</title>
219 <body>
220
221 <p>
222 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 </p>
227
228 <p>
229 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 </p>
235
236 <p>
237 While the OpenRC ebuild will attempt to do this migration for you, you should
238 verify that it migrated all the volume management services properly:
239 </p>
240
241 <pre caption="Display all services in boot runlevel">
242 # <i>ls -l /etc/runlevels/boot/</i>
243 </pre>
244
245 <p>
246 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 </p>
249
250 <pre caption="Adding critical services to the boot runlevel">
251 # <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 # <i>rc-update add swap boot</i>
256 </pre>
257
258 <p>
259 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 </p>
262
263 <pre caption="Adding mdraid and lvm to the boot runlevel">
264 # <i>rc-update add mdraid boot</i>
265 # <i>rc-update add lvm boot</i>
266 </pre>
267
268 </body>
269 </section>
270 <!-- =============================================================== -->
271
272 <section>
273 <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 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 However, to be safe, check if <c>udev</c> is present:
281 </p>
282
283 <pre caption="Verifying udev">
284 # <i>ls -l /etc/runlevels/sysinit</i>
285 lrwxrwxrwx 1 root root 14 2009-01-29 08:00 /etc/runlevels/sysinit/udev -> \
286 /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 <pre caption="Adding udev to the sysinit runlevel">
294 # <i>rc-update add udev sysinit</i>
295 </pre>
296
297 </body>
298 </section>
299 <!-- =============================================================== -->
300
301 <section>
302 <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 to re-add them. Simply replace <c>eth0</c> with the name of your network
319 device.
320 </p>
321
322 <p>
323 Also, <path>/etc/conf.d/net</path> (oldnet) no longer uses bash-style arrays
324 for configuration. Please review
325 <path>/usr/share/doc/openrc-&lt;version&gt;/net.example</path> for configuration
326 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 </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 routes_eth0=( "default via 192.168.1.100" "10.0.0.0/8 via 192.168.1.2" )
334 </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 routes_eth0="default via 192.168.1.100
339 10.0.0.0/8 via 192.168.1.2"
340 </pre>
341
342 </body>
343 </section>
344 <!-- =============================================================== -->
345
346 <section>
347 <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 <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 runlevel.
360 </p>
361
362 <p>
363 Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
364 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 </p>
368
369 <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 </body>
380 </section>
381 <!-- =============================================================== -->
382
383 <section>
384 <title>XSESSION</title>
385 <body>
386
387 <p>
388 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 </p>
392
393 <p>
394 Here's an example of setting XSESSION for the whole system:
395 </p>
396
397 <pre caption="Setting XSESSION system-wide">
398 # <i>echo 'XSESSION="Xfce4"' > /etc/env.d/90xsession</i>
399 </pre>
400
401 <impo>
402 You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
403 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 </impo>
407
408 </body>
409 </section>
410 <!-- =============================================================== -->
411
412 <section>
413 <title>EDITOR and PAGER</title>
414 <body>
415
416 <p>
417 The EDITOR variable is no longer found in <path>/etc/rc.conf</path>. Both
418 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 </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 <!-- =============================================================== -->
433
434 <section>
435 <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 <!-- =============================================================== -->
454
455 <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 sub-type using the <b>rc_sys</b> variable in <path>/etc/rc.conf</path>.
469 </p>
470
471 <impo>
472 If you do not have any specific sub-type, please use the default of an empty
473 string <b>""</b>. If the variable is unset, you will be given a warning and we
474 will attempt to use the old detection algorithm.
475 </impo>
476
477 <pre caption="Setting system sub-type to none in /etc/rc.conf">
478 rc_sys=""
479 </pre>
480
481 <p>The detection algorithm had to be replaced with manual configuration due to
482 the introduction of new sub-types and changes to the kernel that made prior
483 detection unreliable.</p>
484
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>uml</ti>
518 <ti>Usermode Linux</ti>
519 <ti></ti>
520 </tr>
521 <tr>
522 <ti>vserver</ti>
523 <ti>Linux vserver</ti>
524 <ti></ti>
525 </tr>
526 <tr>
527 <ti>xen0</ti>
528 <ti>Xen0 Domain</ti>
529 <ti>Linux &amp; NetBSD</ti>
530 </tr>
531 <tr>
532 <ti>xenU</ti>
533 <ti>XenU Domain</ti>
534 <ti>Linux &amp; NetBSD</ti>
535 </tr>
536 </table>
537
538 </body>
539 </section>
540 <!-- =============================================================== -->
541
542 <section>
543 <title>Finishing up</title>
544 <body>
545
546 <p>
547 Once you've finished updating your config files and initscripts, the last thing
548 to do is <b>reboot</b>. This is necessary because system state information is
549 not preserved during the upgrade, so you'll need to provide it with a fresh
550 boot.
551 </p>
552
553 </body>
554 </section>
555 <!-- =============================================================== -->
556
557 </chapter>
558 <chapter>
559 <title>Changed functionality</title>
560 <!-- =============================================================== -->
561
562 <section>
563 <title>The pause action</title>
564 <body>
565
566 <p>
567 Previously it was possible to temporarily stop a service without taking down all
568 the depending services by using <c>/etc/init.d/service pause</c>. In OpenRC, the
569 <c>pause</c> action was removed; this functionality is supported by the
570 <c>/etc/init.d/service --nodeps stop</c>, which also works in the old
571 baselayout.
572 </p>
573
574 </body>
575 </section>
576 <!-- =============================================================== -->
577
578 </chapter>
579 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20