Gentoo Archives: gentoo-doc-cvs

From: Joshua Saddler <nightmorph@××××××××××××.org>
To: gentoo-doc-cvs@l.g.o
Subject: [gentoo-doc-cvs] cvs commit: metadoc.xml openrc-migration.xml
Date: Fri, 11 Apr 2008 23:59:56
Message-Id: E1JkT9r-0005by-Jf@stork.gentoo.org
1 nightmorph 08/04/11 23:59:51
2
3 Modified: metadoc.xml
4 Added: openrc-migration.xml
5 Log:
6 added new openrc/baselayout-2 migration guide written by myself, cardoe, and uberlord. it's part of our sysadmin and upgrade categories. stabilization of the package will follow about 30 days from now, in the mean time, now it's hitting ~arch, so lots of our users will need to read this guide.
7
8 Revision Changes Path
9 1.210 xml/htdocs/doc/en/metadoc.xml
10
11 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/metadoc.xml?rev=1.210&view=markup
12 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/metadoc.xml?rev=1.210&content-type=text/plain
13 diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/metadoc.xml?r1=1.209&r2=1.210
14
15 Index: metadoc.xml
16 ===================================================================
17 RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v
18 retrieving revision 1.209
19 retrieving revision 1.210
20 diff -u -r1.209 -r1.210
21 --- metadoc.xml 7 Apr 2008 05:48:48 -0000 1.209
22 +++ metadoc.xml 11 Apr 2008 23:59:51 -0000 1.210
23 @@ -1,8 +1,8 @@
24 <?xml version="1.0" encoding="UTF-8"?>
25 <!DOCTYPE metadoc SYSTEM "/dtd/metadoc.dtd">
26 -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.209 2008/04/07 05:48:48 nightmorph Exp $ -->
27 +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.210 2008/04/11 23:59:51 nightmorph Exp $ -->
28 <metadoc lang="en">
29 - <version>1.131</version>
30 + <version>1.132</version>
31 <members>
32 <lead>neysx</lead>
33 <member>cam</member>
34 @@ -408,6 +408,7 @@
35 <file id="pam-upgrade">/proj/en/base/pam/upgrade-0.99.xml</file>
36 <file id="embedded-handbook">/proj/en/base/embedded/handbook/index.xml</file>
37 <file id="texlive-migration-guide">/proj/en/tex/texlive-migration-guide.xml</file>
38 + <file id="openrc-migration">/doc/en/openrc-migration.xml</file>
39 </files>
40 <docs>
41 <doc fileid="name-logo">
42 @@ -879,6 +880,10 @@
43 <bug stopper="yes">115130</bug>
44 </bugs>
45 </doc>
46 + <doc fileid="openrc-migration">
47 + <memberof>sysadmin_specific</memberof>
48 + <memberof>upgrade</memberof>
49 + </doc>
50 <doc fileid="new-dev-training">
51 <memberof>project_devrel</memberof>
52 </doc>
53
54
55
56 1.1 xml/htdocs/doc/en/openrc-migration.xml
57
58 file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/openrc-migration.xml?rev=1.1&view=markup
59 plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/openrc-migration.xml?rev=1.1&content-type=text/plain
60
61 Index: openrc-migration.xml
62 ===================================================================
63 <?xml version='1.0' encoding='UTF-8'?>
64 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
65 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openrc-migration.xml,v 1.1 2008/04/11 23:59:51 nightmorph Exp $ -->
66
67 <guide link="/doc/en/openrc-migration.xml">
68 <title>Baselayout and OpenRC Migration Guide</title>
69
70 <author title="Author">
71 <mail link="cardoe"/>
72 </author>
73 <author title="Author">
74 <mail link="nightmorph"/>
75 </author>
76 <author title="Contributor">
77 <mail link="uberlord"/>
78 </author>
79
80 <abstract>
81 This guide shows you how to migrate from baselayout-1 to baselayout-2 and
82 OpenRC.
83 </abstract>
84
85 <!-- The content of this document is licensed under the CC-BY-SA license -->
86 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
87 <license/>
88
89 <version>1.0</version>
90 <date>2008-04-11</date>
91
92 <chapter>
93 <title>Background</title>
94 <section>
95 <title>What's baselayout?</title>
96 <body>
97
98 <p>
99 Baselayout provides a basic set of files that are necessary for all systems to
100 function properly, such as <path>/etc/hosts</path>. It also provides the basic
101 filesystem layout used by Gentoo (i.e. <path>/etc</path>, <path>/var</path>,
102 <path>/usr</path>, <path>/home</path> directories).
103 </p>
104
105 </body>
106 </section>
107 <section>
108 <title>What's OpenRC?</title>
109 <body>
110
111 <p>
112 OpenRC is a dependency-based rc system that works with whatever init is provided
113 by the system, normally <path>/sbin/init</path>. However, it is <e>not</e> a
114 replacement for <path>/sbin/init</path>. The default init used by Gentoo Linux
115 is <c>sys-apps/sysvinit</c>, while Gentoo/FreeBSD uses the FreeBSD init provided
116 by <c>sys-freebsd/freebsd-sbin</c>.
117 </p>
118 </body>
119 </section>
120 <section>
121 <title>So why migrate?</title>
122 <body>
123
124 <p>
125 Originally Gentoo's rc system was built into baselayout 1 and written entirely
126 in bash. This led to several limitations. For example, certain system calls need
127 to be accessed during boot and this required C-based callouts to be added. These
128 callouts were each statically linked, causing the rc system to bloat over time.
129 </p>
130
131 <p>
132 Additionally, as Gentoo expanded to other platforms like
133 Gentoo/FreeBSD and Gentoo Embedded, it became impossible to require a bash-based
134 rc system. This led to a development of baselayout 2, which is written in
135 C and only requires a POSIX-compliant shell. During the development of
136 baselayout 2, it was determined that it was a better fit if baselayout merely
137 provided the base files and filesystem layout for Gentoo and the rc system
138 was broken off into its own package. Thus we have OpenRC.
139 </p>
140
141 <p>
142 OpenRC is primarily developed by <uri link="http://roy.marples.name/openrc">Roy
143 Marples</uri> and supports all current Gentoo variations (i.e. Gentoo Linux,
144 Gentoo/FreeBSD, Gentoo Embedded, and Gentoo Vserver) and other platforms such as
145 FreeBSD and NetBSD.
146 </p>
147
148 </body>
149 </section>
150 </chapter>
151
152 <chapter>
153 <title>Migration to OpenRC</title>
154 <section>
155 <body>
156
157 <p>
158 Migration to OpenRC is fairly straightforward; it will be pulled in as part
159 of your regular upgrade process by your package manager. The most important
160 step actually comes after you install the new <c>>=sys-apps/baselayout-2</c>
161 and <c>sys-apps/openrc</c> packages. It is <e>critical</e> that you run
162 <c>dispatch-conf</c> and ensure your <path>/etc</path>
163 is up to date before rebooting. <brite>Failure to do so will result in an unbootable
164 system</brite> and will require the use of the Gentoo LiveCD to perform the steps
165 below to repair your system.
166 </p>
167
168 <p>
169 Once you've finished updating your config files, there are a few things to
170 verify prior to rebooting.</p>
171
172 </body>
173 </section>
174
175 <section id="rc_conf">
176 <title>/etc/conf.d/rc</title>
177 <body>
178
179 <p>
180 <path>/etc/conf.d/rc</path> has been deprecated and any settings you have in
181 there will need to be migrated to the appropriate settings in
182 <path>/etc/rc.conf</path>. Please read through <path>/etc/rc.conf</path> and
183 <path>/etc/conf.d/rc</path> and migrate the settings. Once you are complete,
184 delete <path>/etc/conf.d/rc</path>.
185 </p>
186
187 </body>
188 </section>
189
190 <section id="modules">
191 <title>Kernel modules</title>
192 <body>
193
194 <p>
195 Normally, when you want certain kernel modules automatically loaded at boot, you
196 place them into <path>/etc/modules.autoload.d/kernel-2.6</path> along with any
197 parameters you wanted to pass to them. In baselayout-2, this file is not used
198 anymore. Instead, autoloaded modules and module parameters are placed in one
199 file, <path>/etc/conf.d/modules</path>, no matter the kernel version.
200 </p>
201
202 <p>
203 An example old style configuration would be:
204 </p>
205
206 <pre caption="/etc/modules.autoload.d/kernel-2.6">
207 ivtv
208 cx88_dvb video_br=2
209 </pre>
210
211 <p>
212 Converting the above example would result in the following:
213 </p>
214
215 <pre caption="/etc/conf.d/modules">
216 <comment># Modules autoloaded at boot</comment>
217 modules_2_6="ivtv cx88_dvb"
218 <comment># Module parameters</comment>
219 module_cx88_dvb_args_2_6="video_br=2"
220 </pre>
221
222 <p>
223 In the above examples, the modules and their parameters would only be passed
224 to 2.6.x series kernels. The new configuration allows for fine grained
225 control over the modules and parameters based on kernel version.
226 </p>
227
228 <p>
229 An in-depth example would be:
230 </p>
231
232 <pre caption="detailed example of /etc/conf.d/modules">
233 <comment># Always load ochi1394 and ieee1394, no matter the kernel version</comment>
234 modules="ohci1394 ieee1394"
235 <comment># Only load tun and usbserial for 2.6.x series kernels</comment>
236 modules_2_6="tun usbserial"
237 <comment># Only load cx88_dvb for 2.6.23 kernels</comment>
238 modules_2_6_23="cx88_dvb"
239 <comment># Only load ivtv for 2.6.23-gentoo-r5</comment>
240 modules_2_6_23_gentoo_r5="ivtv"
241
242 <comment># For 2.6.23-gentoo-r5, pass video_br=2 to cx88_dvb</comment>
243 module_cx88_dvb_args_2_6_23_gentoo_r5="video_br=2"
244 <comment># For 2.6.x series kernels, always pass vendor and product</comment>
245 module_usbserial_args_2_6="vendor=0x1410 product=0x2110"
246 <comment># Always pass debug to ieee1394</comment>
247 module_ieee1394_args="debug"
248 </pre>
249
250 <note>
251 Please note the difference between <b>module_</b> and <b>modules_</b>.
252 </note>
253
254 </body>
255 </section>
256 <section id="volume">
257 <title>Volume management</title>
258 <body>
259
260 <p>
261 Volume management services for your block storage devices should be
262 automatically migrated for you when you switch to OpenRC and baselayout-2.
263 However, in case they aren't, you'll need to follow the instructions below.
264 </p>
265
266 <p>
267 Volume management services for your block storage devices are no longer run by
268 default. This means that lvm, raid, swap, device-mapper (dm), dm-crypt, evms, and the
269 like will not be run automatically. If you use these addons, you will have to
270 add the proper initscript to the <c>boot</c> runlevel. Otherwise, it's possible
271 your system will not boot. When you install the various volume management
272 services, they will install an appropriate initscript in
273 <path>/etc/init.d</path>. You must ensure the appropriate initscript is in the
274 <c>boot</c> runlevel.
275 </p>
276
277 <p>
278 While the OpenRC ebuild will attempt to do this migration for you, you should
279 verify that it migrated all the volume management services properly.
280 </p>
281
282 <pre caption="Check all services in boot runlevel">
283 # <i>ls -l /etc/runlevels/boot/</i>
284 </pre>
285
286 <p>
287 If you know you use mdraid, lvm, and swap but do not see them above, you would run
288 the following to add initscripts to the <c>boot</c> runlevel.
289 </p>
290
291 <pre caption="Adding missing volume management services to the boot runlevel">
292 # <i>rc-update add raid boot</i>
293 # <i>rc-update add lvm boot</i>
294 # <i>rc-update add swap boot</i>
295 </pre>
296
297 </body>
298 </section>
299 <section>
300 <title>Clock</title>
301 <body>
302
303 <p>
304 Clock settings have been renamed from <path>/etc/conf.d/clock</path> to your
305 system's native tool for adjusting the clock. This means on Linux it will be
306 <path>/etc/conf.d/hwclock</path> and on FreeBSD it will be
307 <path>/etc/conf.d/adjkerntz</path>.
308 </p>
309
310 <p>
311 Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
312 contents are instead found in the <path>/etc/timezone</path> file. Please review
313 both of these files to ensure their correctness.
314 </p>
315
316 </body>
317 </section>
318
319 <section>
320 <title>XSESSION</title>
321 <body>
322
323 <p>
324 The XSESSION variable is no longer found in <path>/etc/rc.conf</path>. The
325 <c>x11-apps/xinit</c> package now provides <path>/etc/env.d/90xsession</path>,
326 which can be used to set the XSESSION variable.
327 </p>
328
329 <p>
330 This variable will <b>NOT</b> be migrated for you by default, so you will need
331 to edit <path>/etc/env.d/90xsession</path>.
332 </p>
333
334 <impo>
335 You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
336 and then logout and login for it to take effect.
337 </impo>
338
339 </body>
340 </section>
341 <section>
342 <title>EDITOR</title>
343 <body>
344
345 <p>
346 The EDITOR variable is no longer found in <path>/etc/rc.conf</path>, and at this
347 time is not provided by any other package. Users are encouraged to set it as
348 needed in their <path>~/.bashrc</path> file or create
349 <path>/etc/env.d/99editor</path> and set it there.
350 </p>
351
352 <impo>
353 You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
354 and then logout and login for it to take effect. If you set the variable in
355 <path>~/.bashrc</path>, you can re-source the file with <c>source
356 ~/.bashrc</c>.
357 </impo>
358
359 </body>
360 </section>
361 <section>
362 <title>Finishing up</title>
363 <body>
364
365 <p>
366 Once you've finished updating your config files and initscripts, the last thing
367 to do is <b>reboot</b>. This is necessary because system state information is
368 not preserved during the upgrade, so you'll need to provide it with a fresh
369 boot.
370 </p>
371
372 </body>
373 </section>
374 </chapter>
375 </guide>
376
377
378
379 --
380 gentoo-doc-cvs@l.g.o mailing list