/[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 - (show 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 <?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.31 2011/05/29 00:45:35 nightmorph 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>11</version>
31 <date>2011-05-28</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 and re-add it to the default runlevel, please perform the
292 following:
293 </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 # <i>rc-update add net.eth0 default</i>
299 </pre>
300
301 <p>
302 If you are missing any other network initscripts, follow the instructions above
303 to re-add them. Simply replace <c>eth0</c> with the name of your network
304 device.
305 </p>
306
307 <p>
308 Also, <path>/etc/conf.d/net</path> (oldnet) no longer uses bash-style arrays
309 for configuration. Please review
310 <path>/usr/share/doc/openrc-&lt;version&gt;/net.example</path> for configuration
311 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 </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 routes_eth0=( "default via 192.168.1.100" "10.0.0.0/8 via 192.168.1.2" )
319 </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 routes_eth0="default via 192.168.1.100
324 10.0.0.0/8 via 192.168.1.2"
325 </pre>
326
327 </body>
328 </section>
329 <section>
330 <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 <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 runlevel.
343 </p>
344
345 <p>
346 Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
347 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 </p>
351
352 <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 </body>
363 </section>
364 <section>
365 <title>XSESSION</title>
366 <body>
367
368 <p>
369 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 </p>
373
374 <p>
375 Here's an example of setting XSESSION for the whole system:
376 </p>
377
378 <pre caption="Setting XSESSION system-wide">
379 # <i>echo 'XSESSION="Xfce4"' > /etc/env.d/90xsession</i>
380 </pre>
381
382 <impo>
383 You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
384 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 </impo>
388
389 </body>
390 </section>
391 <section>
392 <title>EDITOR and PAGER</title>
393 <body>
394
395 <p>
396 The EDITOR variable is no longer found in <path>/etc/rc.conf</path>. Both
397 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 </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 <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 <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 <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 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 </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 <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 <pre caption="Setting system sub-type to none in /etc/rc.conf">
475 rc_sys=""
476 </pre>
477
478 <p>
479 The detection algorithm had to be replaced with manual configuration due to
480 the introduction of new sub-types and changes to the kernel that made prior
481 detection unreliable.
482 </p>
483
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 <section>
535 <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 </chapter>
548
549 <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 <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 present. The duplicate rootfs item was actually added back during shutdown.
573 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 </chapter>
580 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20