/[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.19 - (hide annotations) (download) (as text)
Wed Dec 1 09:47:36 2010 UTC (3 years, 7 months ago) by jkt
Branch: MAIN
Changes since 1.18: +20 -3 lines
File MIME type: application/xml
#219038, document `/etc/init.d/foo --nodeps stop` as a replacement for `/etc/init.d/foo pause`

1 nightmorph 1.1 <?xml version='1.0' encoding='UTF-8'?>
2     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 jkt 1.19 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openrc-migration.xml,v 1.18 2010/07/20 08:51:25 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 jkt 1.19 <version>3</version>
28     <date>2010-12-01</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 nightmorph 1.16
57 nightmorph 1.1 </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 nightmorph 1.4 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 nightmorph 1.1 </p>
106    
107     <p>
108     Once you've finished updating your config files, there are a few things to
109 nightmorph 1.4 verify prior to rebooting.
110     </p>
111 nightmorph 1.1
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 nightmorph 1.18 <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 nightmorph 1.1 <note>
195     Please note the difference between <b>module_</b> and <b>modules_</b>.
196     </note>
197    
198     </body>
199     </section>
200 nightmorph 1.5 <section id="boot">
201     <title>Boot runlevel</title>
202 nightmorph 1.1 <body>
203    
204     <p>
205 nightmorph 1.5 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 nightmorph 1.1 </p>
210    
211     <p>
212 nightmorph 1.5 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 nightmorph 1.1 </p>
218    
219     <p>
220     While the OpenRC ebuild will attempt to do this migration for you, you should
221 nightmorph 1.5 verify that it migrated all the volume management services properly:
222 nightmorph 1.1 </p>
223    
224 nightmorph 1.5 <pre caption="Display all services in boot runlevel">
225 nightmorph 1.1 # <i>ls -l /etc/runlevels/boot/</i>
226     </pre>
227    
228     <p>
229 nightmorph 1.5 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 nightmorph 1.1 </p>
232    
233 nightmorph 1.9 <pre caption="Adding critical services to the boot runlevel">
234 nightmorph 1.5 # <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 nightmorph 1.1 # <i>rc-update add swap boot</i>
239     </pre>
240    
241 nightmorph 1.2 <p>
242 nightmorph 1.5 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 nightmorph 1.2 </p>
245    
246 nightmorph 1.17 <pre caption="Adding mdraid and lvm to the boot runlevel">
247     # <i>rc-update add mdraid boot</i>
248 nightmorph 1.5 # <i>rc-update add lvm boot</i>
249 nightmorph 1.2 </pre>
250    
251 nightmorph 1.1 </body>
252     </section>
253     <section>
254 nightmorph 1.13 <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 nightmorph 1.14 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 nightmorph 1.13 However, to be safe, check if <c>udev</c> is present:
262     </p>
263    
264     <pre caption="Verifying udev">
265 nightmorph 1.14 # <i>ls -l /etc/runlevels/sysinit</i>
266     lrwxrwxrwx 1 root root 14 2009-01-29 08:00 /etc/runlevels/sysinit/udev -> \
267 nightmorph 1.13 /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 nightmorph 1.14 <pre caption="Adding udev to the sysinit runlevel">
275     # <i>rc-update add udev sysinit</i>
276 nightmorph 1.13 </pre>
277    
278     </body>
279     </section>
280     <section>
281 nightmorph 1.9 <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 nightmorph 1.10 to re-add them. Simply replace <c>eth0</c> with the name of your network
298 nightmorph 1.9 device.
299     </p>
300    
301 nightmorph 1.10 <p>
302     Also, <path>/etc/conf.d/net</path> no longer uses bash-style arrays for
303 nightmorph 1.17 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 nightmorph 1.10 </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 nightmorph 1.9 </body>
320     </section>
321     <section>
322 nightmorph 1.1 <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 nightmorph 1.16 <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 nightmorph 1.2 runlevel.
335 nightmorph 1.1 </p>
336    
337     <p>
338     Additionally, the <c>TIMEZONE</c> variable is no longer in this file. Its
339 vapier 1.8 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 nightmorph 1.1 </p>
343    
344 nightmorph 1.9 <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 nightmorph 1.1 </body>
355     </section>
356     <section>
357     <title>XSESSION</title>
358     <body>
359    
360     <p>
361 nightmorph 1.15 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 nightmorph 1.1 </p>
365    
366     <p>
367 nightmorph 1.15 Here's an example of setting XSESSION for the whole system:
368 nightmorph 1.1 </p>
369    
370 nightmorph 1.15 <pre caption="Setting XSESSION system-wide">
371     # <i>echo 'XSESSION="Xfce4"' > /etc/env.d/90xsession</i>
372     </pre>
373    
374 nightmorph 1.1 <impo>
375     You must run <c>env-update</c> after creating a file in <path>/etc/env.d</path>,
376 nightmorph 1.15 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 nightmorph 1.1 </impo>
380    
381     </body>
382     </section>
383     <section>
384 nightmorph 1.15 <title>EDITOR and PAGER</title>
385 nightmorph 1.1 <body>
386    
387     <p>
388 vapier 1.7 The EDITOR variable is no longer found in <path>/etc/rc.conf</path>. Both
389 nightmorph 1.12 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 nightmorph 1.1 </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 nightmorph 1.11 <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 nightmorph 1.1 <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 jkt 1.19 <chapter>
437     <title>Changed functionality</title>
438     <section>
439     <title>The pause action</title>
440     <body>
441    
442     <p>
443     Previously it was possible to temporarily stop a service without taking down all
444     the depending services by using <c>/etc/init.d/service pause</c>. In OpenRC, the
445     <c>pause</c> action was removed; this functionality is supported by the
446     <c>/etc/init.d/service --nodeps stop</c>, which also works in the old
447     baselayout.
448     </p>
449    
450     </body>
451     </section>
452     </chapter>
453 nightmorph 1.1 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20