/[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.15 - (show annotations) (download) (as text)
Tue Feb 17 07:19:23 2009 UTC (5 years, 5 months ago) by nightmorph
Branch: MAIN
Changes since 1.14: +15 -10 lines
File MIME type: application/xml
~arch xinit no longer provides /etc/env.d/90xsession. users have to create the env file manually. updated openrc guide, bug 229769.

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

  ViewVC Help
Powered by ViewVC 1.1.20