/[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.18 - (show annotations) (download) (as text)
Tue Jul 20 08:51:25 2010 UTC (4 years, 2 months ago) by nightmorph
Branch: MAIN
Changes since 1.17: +8 -3 lines
File MIME type: application/xml
add note on module variable priority, bug 269349

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

  ViewVC Help
Powered by ViewVC 1.1.20