1 |
nightmorph |
1.1 |
<?xml version='1.0' encoding='UTF-8'?> |
2 |
|
|
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
3 |
nightmorph |
1.14 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openrc-migration.xml,v 1.13 2009/02/11 09:09:40 nightmorph Exp $ --> |
4 |
nightmorph |
1.1 |
|
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 |
nightmorph |
1.13 |
<version>1.8</version> |
28 |
|
|
<date>2009-02-11</date> |
29 |
nightmorph |
1.1 |
|
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 |
nightmorph |
1.4 |
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 |
nightmorph |
1.1 |
</p> |
105 |
|
|
|
106 |
|
|
<p> |
107 |
|
|
Once you've finished updating your config files, there are a few things to |
108 |
nightmorph |
1.4 |
verify prior to rebooting. |
109 |
|
|
</p> |
110 |
nightmorph |
1.1 |
|
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 |
nightmorph |
1.5 |
<section id="boot"> |
195 |
|
|
<title>Boot runlevel</title> |
196 |
nightmorph |
1.1 |
<body> |
197 |
|
|
|
198 |
|
|
<p> |
199 |
nightmorph |
1.5 |
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 |
nightmorph |
1.1 |
</p> |
204 |
|
|
|
205 |
|
|
<p> |
206 |
nightmorph |
1.5 |
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 |
nightmorph |
1.1 |
</p> |
212 |
|
|
|
213 |
|
|
<p> |
214 |
|
|
While the OpenRC ebuild will attempt to do this migration for you, you should |
215 |
nightmorph |
1.5 |
verify that it migrated all the volume management services properly: |
216 |
nightmorph |
1.1 |
</p> |
217 |
|
|
|
218 |
nightmorph |
1.5 |
<pre caption="Display all services in boot runlevel"> |
219 |
nightmorph |
1.1 |
# <i>ls -l /etc/runlevels/boot/</i> |
220 |
|
|
</pre> |
221 |
|
|
|
222 |
|
|
<p> |
223 |
nightmorph |
1.5 |
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 |
nightmorph |
1.1 |
</p> |
226 |
|
|
|
227 |
nightmorph |
1.9 |
<pre caption="Adding critical services to the boot runlevel"> |
228 |
nightmorph |
1.5 |
# <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 |
nightmorph |
1.1 |
# <i>rc-update add swap boot</i> |
233 |
|
|
</pre> |
234 |
|
|
|
235 |
nightmorph |
1.2 |
<p> |
236 |
nightmorph |
1.5 |
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 |
nightmorph |
1.2 |
</p> |
239 |
|
|
|
240 |
nightmorph |
1.6 |
<pre caption="Adding raid and lvm to the boot runlevel"> |
241 |
nightmorph |
1.5 |
# <i>rc-update add raid boot</i> |
242 |
|
|
# <i>rc-update add lvm boot</i> |
243 |
nightmorph |
1.2 |
</pre> |
244 |
|
|
|
245 |
nightmorph |
1.1 |
</body> |
246 |
|
|
</section> |
247 |
|
|
<section> |
248 |
nightmorph |
1.13 |
<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 |
nightmorph |
1.14 |
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 |
nightmorph |
1.13 |
However, to be safe, check if <c>udev</c> is present: |
256 |
|
|
</p> |
257 |
|
|
|
258 |
|
|
<pre caption="Verifying udev"> |
259 |
nightmorph |
1.14 |
# <i>ls -l /etc/runlevels/sysinit</i> |
260 |
|
|
lrwxrwxrwx 1 root root 14 2009-01-29 08:00 /etc/runlevels/sysinit/udev -> \ |
261 |
nightmorph |
1.13 |
/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 |
nightmorph |
1.14 |
<pre caption="Adding udev to the sysinit runlevel"> |
269 |
|
|
# <i>rc-update add udev sysinit</i> |
270 |
nightmorph |
1.13 |
</pre> |
271 |
|
|
|
272 |
|
|
</body> |
273 |
|
|
</section> |
274 |
|
|
<section> |
275 |
nightmorph |
1.9 |
<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 |
nightmorph |
1.10 |
to re-add them. Simply replace <c>eth0</c> with the name of your network |
292 |
nightmorph |
1.9 |
device. |
293 |
|
|
</p> |
294 |
|
|
|
295 |
nightmorph |
1.10 |
<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 |
nightmorph |
1.9 |
</body> |
313 |
|
|
</section> |
314 |
|
|
<section> |
315 |
nightmorph |
1.1 |
<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 |
nightmorph |
1.2 |
<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 |
nightmorph |
1.1 |
</p> |
326 |
|
|
|
327 |
|
|
<p> |
328 |
|
|
Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its |
329 |
vapier |
1.8 |
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 |
nightmorph |
1.1 |
</p> |
333 |
|
|
|
334 |
nightmorph |
1.9 |
<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 |
nightmorph |
1.1 |
</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>. The |
352 |
|
|
<c>x11-apps/xinit</c> package now provides <path>/etc/env.d/90xsession</path>, |
353 |
|
|
which can be used to set the XSESSION variable. |
354 |
|
|
</p> |
355 |
|
|
|
356 |
|
|
<p> |
357 |
|
|
This variable will <b>NOT</b> be migrated for you by default, so you will need |
358 |
|
|
to edit <path>/etc/env.d/90xsession</path>. |
359 |
|
|
</p> |
360 |
|
|
|
361 |
|
|
<impo> |
362 |
|
|
You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>, |
363 |
|
|
and then logout and login for it to take effect. |
364 |
|
|
</impo> |
365 |
|
|
|
366 |
|
|
</body> |
367 |
|
|
</section> |
368 |
|
|
<section> |
369 |
vapier |
1.7 |
<title>EDITOR / PAGER</title> |
370 |
nightmorph |
1.1 |
<body> |
371 |
|
|
|
372 |
|
|
<p> |
373 |
vapier |
1.7 |
The EDITOR variable is no longer found in <path>/etc/rc.conf</path>. Both |
374 |
nightmorph |
1.12 |
EDITOR and PAGER are set by default in <path>/etc/profile</path>. You should |
375 |
|
|
change this as needed in your <path>~/.bashrc</path> (or equivalent) file or |
376 |
|
|
create <path>/etc/env.d/99editor</path> and set the system default there. |
377 |
nightmorph |
1.1 |
</p> |
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 |
nightmorph |
1.11 |
<title>Boot log</title> |
390 |
|
|
<body> |
391 |
|
|
|
392 |
|
|
<p> |
393 |
|
|
Previously, you could log the boot process by using |
394 |
|
|
<c>app-admin/showconsole</c>. However, OpenRC now handles all logging |
395 |
|
|
internally, so there's no need for the hacks that <c>showconsole</c> employed. |
396 |
|
|
You can safely unmerge <c>showconsole</c>. To continue logging boot messages, |
397 |
|
|
just set the appropriate variable in <path>/etc/rc.conf</path>. Logs will appear |
398 |
|
|
in <path>/var/log/rc.log</path>. |
399 |
|
|
</p> |
400 |
|
|
|
401 |
|
|
<pre caption="Enabling boot logging in /etc/rc.conf"> |
402 |
|
|
rc_logger="YES" |
403 |
|
|
</pre> |
404 |
|
|
|
405 |
|
|
</body> |
406 |
|
|
</section> |
407 |
|
|
<section> |
408 |
nightmorph |
1.1 |
<title>Finishing up</title> |
409 |
|
|
<body> |
410 |
|
|
|
411 |
|
|
<p> |
412 |
|
|
Once you've finished updating your config files and initscripts, the last thing |
413 |
|
|
to do is <b>reboot</b>. This is necessary because system state information is |
414 |
|
|
not preserved during the upgrade, so you'll need to provide it with a fresh |
415 |
|
|
boot. |
416 |
|
|
</p> |
417 |
|
|
|
418 |
|
|
</body> |
419 |
|
|
</section> |
420 |
|
|
</chapter> |
421 |
|
|
</guide> |