/[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.33 - (show annotations) (download) (as text)
Fri Sep 2 19:43:30 2011 UTC (2 years, 7 months ago) by swift
Branch: MAIN
Changes since 1.32: +8 -7 lines
File MIME type: application/xml
Bug #380583 - Roy does not maintain openrc anymore. Thanks to David for reporting and Jacob Godserv for the initial patch

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.32 2011/05/29 07:00:18 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>12</version>
31 <date>2011-09-02</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 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 </p>
93
94 </body>
95 </section>
96 </chapter>
97 <chapter>
98 <title>Migration to OpenRC</title>
99 <section>
100 <body>
101
102 <p>
103 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 </p>
112
113 <p>
114 Once you've finished updating your config files, there are a few things to
115 verify prior to rebooting.
116 </p>
117
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 <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 <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 <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
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 <section id="boot">
206 <title>Boot runlevel</title>
207 <body>
208
209 <p>
210 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 </p>
215
216 <p>
217 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 (dm), dm-crypt, evms, and the like. You must ensure the appropriate initscript
220 for these services is in the <c>boot</c> runlevel, otherwise it's possible that
221 your system will not boot!
222 </p>
223
224 <p>
225 While the OpenRC ebuild will attempt to do this migration for you, you should
226 verify that it migrated all the volume management services properly:
227 </p>
228
229 <pre caption="Display all services in boot runlevel">
230 # <i>ls -l /etc/runlevels/boot/</i>
231 </pre>
232
233 <p>
234 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 </p>
237
238 <pre caption="Adding critical services to the boot runlevel">
239 # <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 # <i>rc-update add swap boot</i>
244 </pre>
245
246 <p>
247 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 </p>
250
251 <pre caption="Adding mdraid and lvm to the boot runlevel">
252 # <i>rc-update add mdraid boot</i>
253 # <i>rc-update add lvm boot</i>
254 </pre>
255
256 </body>
257 </section>
258 <section>
259 <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 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 However, to be safe, check if <c>udev</c> is present:
267 </p>
268
269 <pre caption="Verifying udev">
270 # <i>ls -l /etc/runlevels/sysinit</i>
271 lrwxrwxrwx 1 root root 14 2009-01-29 08:00 /etc/runlevels/sysinit/udev -> \
272 /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 <pre caption="Adding udev to the sysinit runlevel">
280 # <i>rc-update add udev sysinit</i>
281 </pre>
282
283 </body>
284 </section>
285 <section>
286 <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 initscript and re-add it to the default runlevel, please perform the
293 following:
294 </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 # <i>rc-update add net.eth0 default</i>
300 </pre>
301
302 <p>
303 If you are missing any other network initscripts, follow the instructions above
304 to re-add them. Simply replace <c>eth0</c> with the name of your network
305 device.
306 </p>
307
308 <p>
309 Also, <path>/etc/conf.d/net</path> (oldnet) no longer uses bash-style arrays
310 for configuration. Please review
311 <path>/usr/share/doc/openrc-&lt;version&gt;/net.example</path> for configuration
312 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 </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 routes_eth0=( "default via 192.168.1.100" "10.0.0.0/8 via 192.168.1.2" )
320 </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 routes_eth0="default via 192.168.1.100
325 10.0.0.0/8 via 192.168.1.2"
326 </pre>
327
328 </body>
329 </section>
330 <section>
331 <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 <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 runlevel.
344 </p>
345
346 <p>
347 Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
348 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 </p>
352
353 <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 </body>
364 </section>
365 <section>
366 <title>XSESSION</title>
367 <body>
368
369 <p>
370 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 </p>
374
375 <p>
376 Here's an example of setting XSESSION for the whole system:
377 </p>
378
379 <pre caption="Setting XSESSION system-wide">
380 # <i>echo 'XSESSION="Xfce4"' > /etc/env.d/90xsession</i>
381 </pre>
382
383 <impo>
384 You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
385 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 </impo>
389
390 </body>
391 </section>
392 <section>
393 <title>EDITOR and PAGER</title>
394 <body>
395
396 <p>
397 The EDITOR variable is no longer found in <path>/etc/rc.conf</path>. Both
398 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 </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 <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 <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 <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 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 </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 <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 <pre caption="Setting system sub-type to none in /etc/rc.conf">
476 rc_sys=""
477 </pre>
478
479 <p>
480 The detection algorithm had to be replaced with manual configuration due to
481 the introduction of new sub-types and changes to the kernel that made prior
482 detection unreliable.
483 </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>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 <section>
536 <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 </chapter>
549
550 <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 <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 present. The duplicate rootfs item was actually added back during shutdown.
574 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 </chapter>
581 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20