/[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.21 - (show annotations) (download) (as text)
Thu Jan 13 03:34:13 2011 UTC (3 years, 7 months ago) by robbat2
Branch: MAIN
Changes since 1.20: +16 -16 lines
File MIME type: application/xml
Fix the conf.d/modules example which implied loading was cumulative, while the documentation correctly said it was not. Reported by WilliamH.

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.20 2011/01/13 03:19:01 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>4</version>
31 <date>2011-01-12</date>
32
33 <chapter>
34 <title>Background</title>
35 <section>
36 <title>What's baselayout?</title>
37 <body>
38
39 <p>
40 Baselayout provides a basic set of files that are necessary for all systems to
41 function properly, such as <path>/etc/hosts</path>. It also provides the basic
42 filesystem layout used by Gentoo (i.e. <path>/etc</path>, <path>/var</path>,
43 <path>/usr</path>, <path>/home</path> directories).
44 </p>
45
46 </body>
47 </section>
48 <section>
49 <title>What's OpenRC?</title>
50 <body>
51
52 <p>
53 OpenRC is a dependency-based rc system that works with whatever init is provided
54 by the system, normally <path>/sbin/init</path>. However, it is <e>not</e> a
55 replacement for <path>/sbin/init</path>. The default init used by Gentoo Linux
56 is <c>sys-apps/sysvinit</c>, while Gentoo/FreeBSD uses the FreeBSD init provided
57 by <c>sys-freebsd/freebsd-sbin</c>.
58 </p>
59
60 </body>
61 </section>
62 <section>
63 <title>So why migrate?</title>
64 <body>
65
66 <p>
67 Originally Gentoo's rc system was built into baselayout 1 and written entirely
68 in bash. This led to several limitations. For example, certain system calls need
69 to be accessed during boot and this required C-based callouts to be added. These
70 callouts were each statically linked, causing the rc system to bloat over time.
71 </p>
72
73 <p>
74 Additionally, as Gentoo expanded to other platforms like
75 Gentoo/FreeBSD and Gentoo Embedded, it became impossible to require a bash-based
76 rc system. This led to a development of baselayout 2, which is written in
77 C and only requires a POSIX-compliant shell. During the development of
78 baselayout 2, it was determined that it was a better fit if baselayout merely
79 provided the base files and filesystem layout for Gentoo and the rc system
80 was broken off into its own package. Thus we have OpenRC.
81 </p>
82
83 <p>
84 OpenRC is primarily developed by <uri link="http://roy.marples.name/openrc">Roy
85 Marples</uri> and supports all current Gentoo variations (i.e. Gentoo Linux,
86 Gentoo/FreeBSD, Gentoo Embedded, and Gentoo Vserver) and other platforms such as
87 FreeBSD and NetBSD.
88 </p>
89
90 </body>
91 </section>
92 </chapter>
93
94 <chapter>
95 <title>Migration to OpenRC</title>
96 <section>
97 <body>
98
99 <p>
100 Migration to OpenRC is fairly straightforward; it will be pulled in as part of
101 your regular upgrade process by your package manager. The most important step
102 actually comes after you install the new <c>>=sys-apps/baselayout-2</c> and
103 <c>sys-apps/openrc</c> packages. It is <e>critical</e> that you run
104 <c>dispatch-conf</c> and ensure your <path>/etc</path> is up to date before
105 rebooting. <brite>Failure to do so will result in an unbootable system</brite>
106 and will require the use of the Gentoo LiveCD to perform the steps below to
107 repair your system.
108 </p>
109
110 <p>
111 Once you've finished updating your config files, there are a few things to
112 verify prior to rebooting.
113 </p>
114
115 </body>
116 </section>
117
118 <section id="rc_conf">
119 <title>/etc/conf.d/rc</title>
120 <body>
121
122 <p>
123 <path>/etc/conf.d/rc</path> has been deprecated and any settings you have in
124 there will need to be migrated to the appropriate settings in
125 <path>/etc/rc.conf</path>. Please read through <path>/etc/rc.conf</path> and
126 <path>/etc/conf.d/rc</path> and migrate the settings. Once you are complete,
127 delete <path>/etc/conf.d/rc</path>.
128 </p>
129
130 </body>
131 </section>
132 <section id="modules">
133 <title>Kernel modules</title>
134 <body>
135
136 <p>
137 Normally, when you want certain kernel modules automatically loaded at boot, you
138 place them into <path>/etc/modules.autoload.d/kernel-2.6</path> along with any
139 parameters you wanted to pass to them. In baselayout-2, this file is not used
140 anymore. Instead, autoloaded modules and module parameters are placed in one
141 file, <path>/etc/conf.d/modules</path>, no matter the kernel version.
142 </p>
143
144 <p>
145 An example old style configuration would be:
146 </p>
147
148 <pre caption="/etc/modules.autoload.d/kernel-2.6">
149 ivtv
150 cx88_dvb video_br=2
151 </pre>
152
153 <p>
154 Converting the above example would result in the following:
155 </p>
156
157 <pre caption="/etc/conf.d/modules">
158 <comment># Modules autoloaded at boot</comment>
159 modules_2_6="ivtv cx88_dvb"
160 <comment># Module parameters</comment>
161 module_cx88_dvb_args_2_6="video_br=2"
162 </pre>
163
164 <p>
165 In the above examples, the modules and their parameters would only be passed
166 to 2.6.x series kernels. The new configuration allows for fine grained
167 control over the modules and parameters based on kernel version.
168 </p>
169
170 <impo>
171 The <b>module*</b> variables are not cumulative. The more version-specific
172 variables will override the more general variables.
173 </impo>
174
175 <note>
176 Please note the difference between <b>module_</b> and <b>modules_</b>.
177 </note>
178
179 <p>
180 An in-depth example would be:
181 </p>
182
183 <pre caption="detailed example of /etc/conf.d/modules">
184 <comment># Only load ivtv for 2.6.23-gentoo-r5</comment>
185 modules_2_6_23_gentoo_r5="ivtv"
186 <comment># Only load cx88_dvb for 2.6.23 kernels (other than -gentoo-r5)</comment>
187 modules_2_6_23="cx88_dvb"
188 <comment># Only load tun and usbserial for 2.6.x series kernels where x != 23</comment>
189 modules_2_6="tun usbserial"
190 <comment># Otherwise load ochi1394 and ieee1394</comment>
191 modules="ohci1394 ieee1394"
192
193 <comment># For 2.6.23-gentoo-r5, pass video_br=2 to cx88_dvb</comment>
194 module_cx88_dvb_args_2_6_23_gentoo_r5="video_br=2"
195 <comment># For 2.6.x series kernels, always pass vendor and product</comment>
196 module_usbserial_args_2_6="vendor=0x1410 product=0x2110"
197 <comment># Always pass debug to ieee1394</comment>
198 module_ieee1394_args="debug"
199 </pre>
200
201 </body>
202 </section>
203 <section id="boot">
204 <title>Boot runlevel</title>
205 <body>
206
207 <p>
208 The <c>boot</c> runlevel performs several important steps for every machine. For
209 example, making sure your root filesystem is mounted read/write, that your
210 filesystems are checked for errors, that your mountpoints are available, and
211 that the <path>/proc</path> pseudo-filesystem is started at boot.
212 </p>
213
214 <p>
215 With OpenRC, volume management services for your block storage devices are no
216 longer run automatically at boot. This includes lvm, raid, swap, device-mapper
217 (dm), dm-crypt, evms, and the like. You must ensure the appropriate initscript
218 for these services is in the <c>boot</c> runlevel, otherwise it's possible that
219 your system will not boot!
220 </p>
221
222 <p>
223 While the OpenRC ebuild will attempt to do this migration for you, you should
224 verify that it migrated all the volume management services properly:
225 </p>
226
227 <pre caption="Display all services in boot runlevel">
228 # <i>ls -l /etc/runlevels/boot/</i>
229 </pre>
230
231 <p>
232 If you don't see root, procfs, mtab, swap, and fsck in the above listing,
233 perform the following to add them to the <c>boot</c> runlevel:
234 </p>
235
236 <pre caption="Adding critical services to the boot runlevel">
237 # <i>rc-update add root boot</i>
238 # <i>rc-update add procfs boot</i>
239 # <i>rc-update add mtab boot</i>
240 # <i>rc-update add fsck boot</i>
241 # <i>rc-update add swap boot</i>
242 </pre>
243
244 <p>
245 If you know you use mdraid and lvm but do not see them above, you would run
246 the following to add initscripts to the <c>boot</c> runlevel:
247 </p>
248
249 <pre caption="Adding mdraid and lvm to the boot runlevel">
250 # <i>rc-update add mdraid boot</i>
251 # <i>rc-update add lvm boot</i>
252 </pre>
253
254 </body>
255 </section>
256 <section>
257 <title>Udev</title>
258 <body>
259
260 <p>
261 OpenRC no longer starts <c>udev</c> by default, but it does need to be present
262 in the <c>sysinit</c> runlevel to be started. The OpenRC ebuild should detect if
263 <c>udev</c> was previously enabled and add it to the <c>sysinit</c> runlevel.
264 However, to be safe, check if <c>udev</c> is present:
265 </p>
266
267 <pre caption="Verifying udev">
268 # <i>ls -l /etc/runlevels/sysinit</i>
269 lrwxrwxrwx 1 root root 14 2009-01-29 08:00 /etc/runlevels/sysinit/udev -> \
270 /etc/init.d/udev
271 </pre>
272
273 <p>
274 If <c>udev</c> is not listed, add it to the correct runlevel:
275 </p>
276
277 <pre caption="Adding udev to the sysinit runlevel">
278 # <i>rc-update add udev sysinit</i>
279 </pre>
280
281 </body>
282 </section>
283 <section>
284 <title>Network</title>
285 <body>
286
287 <p>
288 Due to baselayout and OpenRC being broken into two different packages, your
289 net.eth0 initscript may disappear during the upgrade process. To replace this
290 initscript please perform the following:
291 </p>
292
293 <pre caption="Adding back missing net.eth0 script">
294 # <i>cd /etc/init.d</i>
295 # <i>ln -s net.lo net.eth0</i>
296 </pre>
297
298 <p>
299 If you are missing any other network initscripts, follow the instructions above
300 to re-add them. Simply replace <c>eth0</c> with the name of your network
301 device.
302 </p>
303
304 <p>
305 Also, <path>/etc/conf.d/net</path> (oldnet) no longer uses bash-style arrays
306 for configuration. Please review
307 <path>/usr/share/doc/openrc-&lt;version&gt;/net.example</path> for configuration
308 instructions. Conversion should be relatively straight-forward, converting to
309 newlines for seperate entries, for example a static IP assignment would change
310 as follows:
311 </p>
312
313 <pre caption="Old /etc/conf.d/net style">
314 config_eth0=( "192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255" )
315 routes_eth0=( "default via 192.168.1.100" "10.0.0.0/8 via 192.168.1.2" )
316 </pre>
317
318 <pre caption="New /etc/conf.d/net style">
319 config_eth0="192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255"
320 routes_eth0="default via 192.168.1.100
321 10.0.0.0/8 via 192.168.1.2"
322 </pre>
323
324 </body>
325 </section>
326 <section>
327 <title>Clock</title>
328 <body>
329
330 <p>
331 Clock settings have been renamed from <path>/etc/conf.d/clock</path> to your
332 system's native tool for adjusting the clock. This means on Linux it will be
333 <path>/etc/conf.d/hwclock</path> and on FreeBSD it will be
334 <path>/etc/conf.d/adjkerntz</path>. Systems without a working real time clock
335 (RTC) chip should use <path>/etc/init.d/swclock</path>, which sets the system
336 time based on the mtime of a file which is created at system shutdown. The
337 initscripts in <path>/etc/init.d/</path> have also been renamed accordingly, so
338 make sure the appropriate script for your system has been added to the boot
339 runlevel.
340 </p>
341
342 <p>
343 Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
344 contents are instead found in the <path>/etc/timezone</path> file. If it
345 doesn't exist, you will of course have to create it with your timezone. Please
346 review both of these files to ensure their correctness.
347 </p>
348
349 <p>
350 The proper value for this file is the path relative to your timezone from
351 <path>/usr/share/zoneinfo</path>. For example, for someone living on the east
352 coast of the United States, the following would be a correct setting:
353 </p>
354
355 <pre caption="/etc/timezone">
356 America/New_York
357 </pre>
358
359 </body>
360 </section>
361 <section>
362 <title>XSESSION</title>
363 <body>
364
365 <p>
366 The XSESSION variable is no longer found in <path>/etc/rc.conf</path>. Instead,
367 you can set the XSESSION variable per-user in <path>~/.bashrc</path> (or
368 equivalent), or system-wide in <path>/etc/env.d/</path>.
369 </p>
370
371 <p>
372 Here's an example of setting XSESSION for the whole system:
373 </p>
374
375 <pre caption="Setting XSESSION system-wide">
376 # <i>echo 'XSESSION="Xfce4"' > /etc/env.d/90xsession</i>
377 </pre>
378
379 <impo>
380 You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
381 and then logout and login for it to take effect. If you set the variable in
382 <path>~/.bashrc</path>, you can re-source the file with <c>source
383 ~/.bashrc</c>.
384 </impo>
385
386 </body>
387 </section>
388 <section>
389 <title>EDITOR and PAGER</title>
390 <body>
391
392 <p>
393 The EDITOR variable is no longer found in <path>/etc/rc.conf</path>. Both
394 EDITOR and PAGER are set by default in <path>/etc/profile</path>. You should
395 change this as needed in your <path>~/.bashrc</path> (or equivalent) file or
396 create <path>/etc/env.d/99editor</path> and set the system default there.
397 </p>
398
399 <impo>
400 You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
401 and then logout and login for it to take effect. If you set the variable in
402 <path>~/.bashrc</path>, you can re-source the file with <c>source
403 ~/.bashrc</c>.
404 </impo>
405
406 </body>
407 </section>
408 <section>
409 <title>Boot log</title>
410 <body>
411
412 <p>
413 Previously, you could log the boot process by using
414 <c>app-admin/showconsole</c>. However, OpenRC now handles all logging
415 internally, so there's no need for the hacks that <c>showconsole</c> employed.
416 You can safely unmerge <c>showconsole</c>. To continue logging boot messages,
417 just set the appropriate variable in <path>/etc/rc.conf</path>. Logs will appear
418 in <path>/var/log/rc.log</path>.
419 </p>
420
421 <pre caption="Enabling boot logging in /etc/rc.conf">
422 rc_logger="YES"
423 </pre>
424
425 </body>
426 </section>
427 <section>
428 <title>Finishing up</title>
429 <body>
430
431 <p>
432 Once you've finished updating your config files and initscripts, the last thing
433 to do is <b>reboot</b>. This is necessary because system state information is
434 not preserved during the upgrade, so you'll need to provide it with a fresh
435 boot.
436 </p>
437
438 </body>
439 </section>
440 </chapter>
441 <chapter>
442 <title>Changed functionality</title>
443 <section>
444 <title>The pause action</title>
445 <body>
446
447 <p>
448 Previously it was possible to temporarily stop a service without taking down all
449 the depending services by using <c>/etc/init.d/service pause</c>. In OpenRC, the
450 <c>pause</c> action was removed; this functionality is supported by the
451 <c>/etc/init.d/service --nodeps stop</c>, which also works in the old
452 baselayout.
453 </p>
454
455 </body>
456 </section>
457 </chapter>
458 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20