/[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.1 - (hide annotations) (download) (as text)
Fri Apr 11 23:59:51 2008 UTC (6 years, 4 months ago) by nightmorph
Branch: MAIN
File MIME type: application/xml
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.

1 nightmorph 1.1 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3     <!-- $Header: $ -->
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.0</version>
28     <date>2008-04-11</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
97     of your regular upgrade process by your package manager. The most important
98     step actually comes after you install the new <c>>=sys-apps/baselayout-2</c>
99     and <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>
101     is up to date before rebooting. <brite>Failure to do so will result in an unbootable
102     system</brite> and will require the use of the Gentoo LiveCD to perform the steps
103     below to 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.</p>
109    
110     </body>
111     </section>
112    
113     <section id="rc_conf">
114     <title>/etc/conf.d/rc</title>
115     <body>
116    
117     <p>
118     <path>/etc/conf.d/rc</path> has been deprecated and any settings you have in
119     there will need to be migrated to the appropriate settings in
120     <path>/etc/rc.conf</path>. Please read through <path>/etc/rc.conf</path> and
121     <path>/etc/conf.d/rc</path> and migrate the settings. Once you are complete,
122     delete <path>/etc/conf.d/rc</path>.
123     </p>
124    
125     </body>
126     </section>
127    
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="volume">
195     <title>Volume management</title>
196     <body>
197    
198     <p>
199     Volume management services for your block storage devices should be
200     automatically migrated for you when you switch to OpenRC and baselayout-2.
201     However, in case they aren't, you'll need to follow the instructions below.
202     </p>
203    
204     <p>
205     Volume management services for your block storage devices are no longer run by
206     default. This means that lvm, raid, swap, device-mapper (dm), dm-crypt, evms, and the
207     like will not be run automatically. If you use these addons, you will have to
208     add the proper initscript to the <c>boot</c> runlevel. Otherwise, it's possible
209     your system will not boot. When you install the various volume management
210     services, they will install an appropriate initscript in
211     <path>/etc/init.d</path>. You must ensure the appropriate initscript is in the
212     <c>boot</c> runlevel.
213     </p>
214    
215     <p>
216     While the OpenRC ebuild will attempt to do this migration for you, you should
217     verify that it migrated all the volume management services properly.
218     </p>
219    
220     <pre caption="Check all services in boot runlevel">
221     # <i>ls -l /etc/runlevels/boot/</i>
222     </pre>
223    
224     <p>
225     If you know you use mdraid, lvm, and swap but do not see them above, you would run
226     the following to add initscripts to the <c>boot</c> runlevel.
227     </p>
228    
229     <pre caption="Adding missing volume management services to the boot runlevel">
230     # <i>rc-update add raid boot</i>
231     # <i>rc-update add lvm boot</i>
232     # <i>rc-update add swap boot</i>
233     </pre>
234    
235     </body>
236     </section>
237     <section>
238     <title>Clock</title>
239     <body>
240    
241     <p>
242     Clock settings have been renamed from <path>/etc/conf.d/clock</path> to your
243     system's native tool for adjusting the clock. This means on Linux it will be
244     <path>/etc/conf.d/hwclock</path> and on FreeBSD it will be
245     <path>/etc/conf.d/adjkerntz</path>.
246     </p>
247    
248     <p>
249     Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
250     contents are instead found in the <path>/etc/timezone</path> file. Please review
251     both of these files to ensure their correctness.
252     </p>
253    
254     </body>
255     </section>
256    
257     <section>
258     <title>XSESSION</title>
259     <body>
260    
261     <p>
262     The XSESSION variable is no longer found in <path>/etc/rc.conf</path>. The
263     <c>x11-apps/xinit</c> package now provides <path>/etc/env.d/90xsession</path>,
264     which can be used to set the XSESSION variable.
265     </p>
266    
267     <p>
268     This variable will <b>NOT</b> be migrated for you by default, so you will need
269     to edit <path>/etc/env.d/90xsession</path>.
270     </p>
271    
272     <impo>
273     You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
274     and then logout and login for it to take effect.
275     </impo>
276    
277     </body>
278     </section>
279     <section>
280     <title>EDITOR</title>
281     <body>
282    
283     <p>
284     The EDITOR variable is no longer found in <path>/etc/rc.conf</path>, and at this
285     time is not provided by any other package. Users are encouraged to set it as
286     needed in their <path>~/.bashrc</path> file or create
287     <path>/etc/env.d/99editor</path> and set it there.
288     </p>
289    
290     <impo>
291     You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
292     and then logout and login for it to take effect. If you set the variable in
293     <path>~/.bashrc</path>, you can re-source the file with <c>source
294     ~/.bashrc</c>.
295     </impo>
296    
297     </body>
298     </section>
299     <section>
300     <title>Finishing up</title>
301     <body>
302    
303     <p>
304     Once you've finished updating your config files and initscripts, the last thing
305     to do is <b>reboot</b>. This is necessary because system state information is
306     not preserved during the upgrade, so you'll need to provide it with a fresh
307     boot.
308     </p>
309    
310     </body>
311     </section>
312     </chapter>
313     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20