/[gentoo]/xml/htdocs/doc/en/migration-to-2.6.xml
Gentoo

Diff of /xml/htdocs/doc/en/migration-to-2.6.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.1 Revision 1.10
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3 3
4<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/migration-to-2.6.xml,v 1.1 2004/11/09 22:05:05 neysx Exp $ --> 4<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/migration-to-2.6.xml,v 1.10 2005/01/16 15:56:35 swift Exp $ -->
5 5
6<guide link="/doc/en/migration-to-2.6.xml"> 6<guide link="/doc/en/migration-to-2.6.xml">
7 7
8<title>The complete Gentoo Linux 2.6 migration guide</title> 8<title>The complete Gentoo Linux 2.6 migration guide</title>
9 9
17 <mail link="svyatogor@gentoo.org">Sergey Kuleshov</mail> 17 <mail link="svyatogor@gentoo.org">Sergey Kuleshov</mail>
18</author> 18</author>
19<author title="Editor"> 19<author title="Editor">
20 <mail link="neysx@gentoo.org">Xavier Neys</mail> 20 <mail link="neysx@gentoo.org">Xavier Neys</mail>
21</author> 21</author>
22<author title="Editor">
23 <mail link="bennyc@gentoo.org">Benny Chuang</mail>
24</author>
22 25
23<abstract> 26<abstract>
24This document will aid you in the process of migrating from Linux 2.4 to Linux 27This document will aid you in the process of migrating from Linux 2.4 to Linux
252.6, devfs to udev and OSS to ALSA. 282.6, devfs to udev, OSS to ALSA, and LVM to LVM2.
26</abstract> 29</abstract>
27 30
28<version>0.1.0</version> 31<version>0.2.1</version>
29<date>November 9, 2004</date> 32<date>2005-01-11</date>
30 33
31<chapter> 34<chapter>
32<title>Introduction</title> 35<title>Introduction</title>
33 36
34<section> 37<section>
142ALSA-related instructions in this document. 145ALSA-related instructions in this document.
143</note> 146</note>
144 147
145</body> 148</body>
146</section> 149</section>
150<section>
151<title>What is LVM?</title>
152<body>
153
154<p>
155<e>Logical Volume Management</e> (LVM) exists as set of tools allowing you to
156manage your disk storage in a very flexible manner. Amongst other things, it
157allows powerful control over partitions (e.g. resizing without reboot), and
158makes operations like device changes relatively simple. LVM acts as an
159alternative to standard partition-based disk management.
160</p>
161
162<p>
163LVM support has historically been implemented in Linux 2.4. Linux 2.6 features
164a new version of LVM, named <e>LVM2</e>. The migration process requires you to
165install new versions of the user-level tools (covered later in this document)
166but will leave your data intact!
167</p>
168
169<p>
170<e>If you do not currently use LVM for data-storage management, then LVM2
171migration does not apply to you.</e> If this is the case, you can safely ignore
172any parts of this document referencing LVM/LVM2. Upgrading to Linux 2.6 does
173<e>not</e> require you to store your data on LVM partitions - you can keep
174your data in the standard partition-format as it always has been.
175</p>
176
177<p>
178If you are not a LVM user, but you think LVM2 sounds useful for you, you can
179convert your disks to this format at a later date, by following the
180<uri link="http://www.gentoo.org/doc/en/lvm2.xml">Gentoo LVM2 Installation
181Guide</uri>. For now, lets just concentrate on getting a smooth 2.6 migration
182underway.
183</p>
184
185</body>
186</section>
147</chapter> 187</chapter>
148 188
149<chapter> 189<chapter>
150<title>Preparation</title> 190<title>Preparation</title>
151<section> 191<section>
197<p> 237<p>
198You should now remove modutils and install module-init-tools: 238You should now remove modutils and install module-init-tools:
199</p> 239</p>
200 240
201<pre caption="Switching from modutils to module-init-tools"> 241<pre caption="Switching from modutils to module-init-tools">
202# <i>emerge unmerge modutils</i> 242# <i>emerge unmerge sys-apps/modutils</i>
203# <i>emerge module-init-tools</i> 243# <i>emerge module-init-tools</i>
204</pre> 244</pre>
205 245
206<note> 246<note>
207Don't worry - even though you have just unmerged modutils, module-init-tools 247Don't worry - even though you have just unmerged modutils, module-init-tools
208provides provides backwards compatibility for Linux 2.4, so you will still be 248provides backwards compatibility for Linux 2.4, so you will still be
209able to boot into Linux 2.4 and handle modules for that kernel. 249able to boot into Linux 2.4 and handle modules for that kernel.
210</note> 250</note>
211 251
212<note> 252<note>
213For the above reason, module-init-tools might already be installed and working 253For the above reason, module-init-tools might already be installed and working
226udev: 266udev:
227</p> 267</p>
228 268
229<pre caption="Installing udev"> 269<pre caption="Installing udev">
230# <i>emerge -a udev</i> 270# <i>emerge -a udev</i>
271</pre>
272
273<p>
274You should now read the
275<uri link="http://www.gentoo.org/doc/en/udev-guide.xml">Gentoo udev
276Guide</uri> to get a more complete idea about the differences between udev
277and devfs.
278</p>
279
280</body>
281</section>
282<section>
283<title>Checking for essential device nodes</title>
284<body>
285
286<p>
287When the system boots up, the system requires some essential device nodes. As
288udev is not included in the kernel, it is not activated immediately. To work
289around this, you must ensure that you have some essential device nodes on your
290disk.
291</p>
292
293<p>
294Our installation stage files will have created the required devices during the
295initial installation. However, some users have reported that this is not the
296case. We will use this opportunity to check that the device files exist, and
297create them if they do not.
298</p>
299
300<p>
301As your existing device manager will be mounted at /dev, we cannot access it
302directly. So we will bind-mount your root partition to another location and
303access the /dev directory from there.
304</p>
305
306<pre caption="Bind-mounting your root partition and listing static devices">
307# <i>mkdir -p /mnt/temp</i>
308# <i>mount -o bind / /mnt/temp</i>
309# <i>cd /mnt/temp/dev</i>
310# <i>ls -l console null</i>
311</pre>
312
313<p>
314If the above <e>ls</e> command reported that either <c>console</c> or
315<c>null</c> do not exist, then you must create them yourself, as shown below.
316</p>
317
318<pre caption="Creating the missing console and null nodes">
319# <i>mknod -m 660 console c 5 1</i>
320# <i>mknod -m 660 null c 1 3</i>
321</pre>
322
323<p>
324You should now unmount your bind-mounted root partition, even if you did not
325have to create those devices:
326</p>
327
328<pre caption="Unmounting the bind-mounted root">
329# <i>cd</i>
330# <i>umount /mnt/temp</i>
331# <i>rmdir /mnt/temp</i>
231</pre> 332</pre>
232 333
233</body> 334</body>
234</section> 335</section>
235<section> 336<section>
297just installed. Continuing our example: 398just installed. Continuing our example:
298</p> 399</p>
299 400
300<pre caption="Updating the /usr/src/linux softlink"> 401<pre caption="Updating the /usr/src/linux softlink">
301# <i>cd /usr/src</i> 402# <i>cd /usr/src</i>
302# <i>ln -sf linux-2.6.9-gentoo-r2 linux</i> 403# <i>ln -sfn linux-2.6.9-gentoo-r2 linux</i>
303</pre> 404</pre>
304 405
305</body> 406</body>
306</section> 407</section>
307</chapter> 408</chapter>
308 409
309<chapter> 410<chapter id="pitfalls">
310<title>Known pitfalls with Linux 2.6 migration</title> 411<title>Known pitfalls with Linux 2.6 migration</title>
311<section> 412<section>
312<body> 413<body>
313 414
314<p> 415<p>
452</p> 553</p>
453 554
454</body> 555</body>
455</section> 556</section>
456<section> 557<section>
457<title>X11 config file should now use /dev/input/mice</title> 558<title>X11 config file should now use /dev/input/mice for PS/2 and USB
559mice</title>
458<body> 560<body>
459 561
460<p> 562<p>
461One of the changes that a default udev configuration introduces is different 563One of the changes that a default udev configuration introduces is different
462organisation of the mouse device nodes. Previously, you would have had nodes 564organisation of the mouse device nodes. Previously, you would have had nodes
504EndSection 606EndSection
505</pre> 607</pre>
506 608
507</body> 609</body>
508</section> 610</section>
611<section>
612<title>New Serial-ATA (SATA) drivers name the devices differently</title>
613<body>
614
615<p>
616If you used the original Serial ATA drivers under Linux 2.4, you probably
617observed your SATA devices having names such as <c>/dev/hde</c>.
618</p>
619
620<p>
621Linux 2.6 introduces some new SATA drivers (libata) which are based on the
622SCSI subsystem. As these drivers are based on SCSI, your SATA disks will now
623show up as SCSI devices. Your first SATA disk will be named <c>/dev/sda</c>.
624You will need to update your <c>/etc/fstab</c> file to reflect this, and you
625will need to bear this in mind when choosing the root/real_root kernel boot
626parameter later on.
627</p>
628
629<note>
630libata has been backported into recent versions of Linux 2.4, so you may
631already be familiar with the new device naming.
632</note>
633
634</body>
635</section>
636<section>
637<title>bootsplash no longer maintained</title>
638<body>
639
640<p>
641If you used the <c>gentoo-sources-2.4</c> kernel, you may have used the
642<e>bootsplash</e> functionality in order to provide yourself with a colourful
643framebuffer console.
644</p>
645
646<p>
647The developer of bootsplash appears to have lost interest in his project, given
648some design problems. However, Gentoo developer <e>Michal Januszewski</e> is
649developing a successor, <c>gensplash</c>, which in included in the
650gentoo-dev-sources kernel. You can follow Michals
651<uri link="http://dev.gentoo.org/~spock/projects/gensplash/archive/gensplash-in-5-easy-steps.txt">
652Gensplash in 5 easy steps</uri> document in order to familiarize yourself with
653how gensplash is operated.
654</p>
655
656</body>
657</section>
658<section>
659<title>I2C drivers now included in the kernel</title>
660<body>
661
662<p>
663If you use <c>lm-sensors</c> to monitor system temperatures and power levels,
664you previously needed to install the <c>i2c</c> package in order to provide
665hardware support.
666</p>
667
668<p>
669The I2C hardware drivers are now included in the Linux 2.6 kernel, no external
670i2c package is required. Remember to compile support for your specific I2C
671devices into the kernel configuration. You will then be able to use
672<c>lm-sensors</c> as usual.
673</p>
674
675</body>
676</section>
677
678
509</chapter> 679</chapter>
510 680
511<chapter id="conf"> 681<chapter id="conf">
512<title>Configuring, building, and installing the kernel</title> 682<title>Configuring, building, and installing the kernel</title>
513<section> 683<section>
584 &lt;M&gt; Advanced Linux Sound Architecture 754 &lt;M&gt; Advanced Linux Sound Architecture
585 &lt;M&gt; Sequencer support 755 &lt;M&gt; Sequencer support
586 &lt;M&gt; OSS Mixer API 756 &lt;M&gt; OSS Mixer API
587 [*] OSS Sequencer API 757 [*] OSS Sequencer API
588<comment> (and dont forget to select your soundcard from the submenus!)</comment> 758<comment> (and dont forget to select your soundcard from the submenus!)</comment>
759
760<comment>(the following are required if you use LVM for disk management):</comment>
761Device Drivers ---&gt;
762 Multi-device support (RAID and LVM) ---&gt;
763 [*] Multiple devices driver support (RAID and LVM)
764 &lt;*&gt; Device mapper support
589</pre> 765</pre>
590 766
591<warn> 767<warn>
592Previously you may have included support for the <path>/dev</path> file system 768Previously you may have included support for the <path>/dev</path> file system
593(now marked OBSOLETE). Do not enable devfs support. We have installed udev, 769(now marked OBSOLETE). Do not enable devfs support. We have installed udev,
698link="/doc/en/genkernel.xml">Gentoo Linux Genkernel Guide</uri> and the <uri 874link="/doc/en/genkernel.xml">Gentoo Linux Genkernel Guide</uri> and the <uri
699link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=7">Configuring the 875link="/doc/en/handbook/handbook-x86.xml?part=1&amp;chap=7">Configuring the
700Kernel</uri> chapter of the <uri link="/doc/en/handbook/index.xml">Gentoo 876Kernel</uri> chapter of the <uri link="/doc/en/handbook/index.xml">Gentoo
701Handbook</uri> for additional information. 877Handbook</uri> for additional information.
702</p> 878</p>
879
880<p>
881If you choose to update your bootloader config yourself, then you must
882remember to include the <c>udev</c> kernel parameter. A sample <e>grub</e>
883config section is shown below, but remember to adjust the <e>real_root</e>
884parameter for your system.
885</p>
886
887<pre caption="Sample GRUB config for genkernel + udev">
888title=Gentoo Linux (2.6 kernel)
889root (hd0,0)
890kernel /kernel-2.6.9-gentoo-r2 <i>udev</i> root=/dev/ram0 init=/linuxrc ramdisk=8192 real_root=/dev/hda3
891initrd /initrd-2.6.9-gentoo-r2
892</pre>
703 893
704</body> 894</body>
705</section> 895</section>
706</chapter> 896</chapter>
707 897
765nvidia 955nvidia
766</pre> 956</pre>
767 957
768</body> 958</body>
769</section> 959</section>
770<section> 960</chapter>
771<title>Configuring the ALSA modules</title>
772<body>
773 961
774<p> 962<chapter>
775You will have noticed that we chose to compile ALSA as modules. We can now 963<title>LVM to LVM2 migration</title>
776configure ALSA's behaviour easily. However, we also need to configure which 964<section>
777modules are to be loaded. Open up <path>/etc/modules.d/alsa</path> in your text 965<title>Upgrading to LVM2 tools</title>
778editor: 966<body>
967
968<note>
969If you do not use LVM to manage your disk storage, you can safely skip
970this chapter and skip onto the next.
971</note>
972
779</p> 973<p>
780 974Fortunately, upgrading from the LVM1 user tools to the LVM2 versions is very
781<pre caption="Opening /etc/modules.d/alsa in nano"> 975simple:
782# <i>nano -w /etc/modules.d/alsa</i>
783</pre>
784
785<p> 976</p>
786Now look for the section marked as <e>IMPORTANT</e>. In most cases, you just 977
787need to uncomment and modify the snd-card-0 and snd-slot-0 aliases. 978<pre caption="Upgrading user-tools from LVM1 to LVM2">
979# <i>emerge unmerge lvm-user</i>
980# <i>emerge lvm2</i>
788</p> 981</pre>
789 982
790<pre caption="Sample section of /etc/modules.d/alsa"> 983<note>
791## IMPORTANT: 984The LVM2 tools are fully backwards-compatible with LVM1. Your disk data will
792## You need to customise this section for your specific sound card(s) 985not be touched. You are not breaking any backwards-compatibility by doing
793## and then run `update-modules' command. 986this, you will continue to be able to boot 2.4 as usual.
794## Read alsa-driver's INSTALL file in /usr/share/doc for more info. 987</note>
795##
796## ALSA portion
797
798# My laptop uses the snd-maestro3 driver
799alias snd-card-0 snd-maestro3
800
801## OSS/Free portion
802
803# Generally all you need to do is uncomment this line:
804alias sound-slot-0 snd-card-0
805</pre>
806
807<p>
808For more info on which driver name to use, consult the <uri
809link="/doc/en/alsa-guide.xml">Gentoo Linux ALSA Guide</uri>. Remember to prefix
810it with <e>snd-</e> in this file.
811</p>
812
813<p>
814Finally, set the <c>alsasound</c> init script to be executed on bootup:
815</p>
816
817<pre caption="Adding alsasound to default runlevel">
818# <i>rc-update add alsasound boot</i>
819</pre>
820 988
821</body> 989</body>
822</section> 990</section>
823</chapter> 991</chapter>
824 992
830<p> 998<p>
831It's now time to boot into Linux 2.6. Close all applications and reboot: 999It's now time to boot into Linux 2.6. Close all applications and reboot:
832</p> 1000</p>
833 1001
834<pre caption="Rebooting"> 1002<pre caption="Rebooting">
835# <i>modules-update</i>
836# <i>umount /boot</i> 1003# <i>umount /boot</i>
837# <i>reboot</i> 1004# <i>reboot</i>
838</pre> 1005</pre>
839 1006
840<p> 1007<p>
852</p> 1019</p>
853 1020
854</body> 1021</body>
855</section> 1022</section>
856<section> 1023<section>
857<title>Unmuting ALSA channels</title> 1024<title>Configuring and unmuting ALSA</title>
858<body> 1025<body>
859 1026
860<p>
861By default, ALSA channels are muted, so you won't hear anything when you go to
862play a sound. You need to unmute them now. Run the <c>alsamixer</c> program
863from a console and use the arrow keys to move around and adjust volumes, and
864the M key to mute and unmute. Read the <uri
865link="/doc/en/alsa-guide.xml">Gentoo Linux ALSA Guide</uri> for more complete
866documentation and other ways to do this.
867</p> 1027<p>
1028We will now complete the ALSA configuration and unmute the audio channels. The
1029ALSA packages provide a useful utility to make this process relatively simple:
1030</p>
868 1031
869<note> 1032<pre caption="Invoking the automatic ALSA configuration utility">
870The alsasound init script that we put in the default runlevel will save mixer 1033# <i>alsaconf</i>
871levels on shutdown and restore them on bootup. You won't need to set all these 1034</pre>
872volumes every time you boot! 1035
1036<p>
1037The process is straightforward: allow the <e>/etc/modules.d/alsa</e> file to
1038be automatically updated, and then allow ALSA to be reloaded. alsaconf will
1039then terminate, however you will need to run it multiple times if you have
1040multiple sound devices installed in your system.
1041</p>
1042
1043<p>
1044You should now add <c>alsasound</c> to your boot runlevel, so that volumes
1045will be saved on shutdown and restored on bootup:
1046</p>
1047
1048<pre caption="Adding alsasound to the boot runlevel">
1049# <i>rc-update add alsasound boot</i>
1050</pre>
1051
873</note> 1052<note>
1053The <c>alsaconf</c> utility chooses initial volume levels for your sound
1054devices. If these are inappropriate, you can modify them at any time with the
1055<c>alsamixer</c> utility.
1056</note>
1057
1058</body>
1059</section>
1060<section>
1061<title>Any immediate problems?</title>
1062<body>
1063
1064<p>
1065At this stage you should refer back to the <uri link="#pitfalls">Known
1066pitfalls with Linux 2.6 migration</uri> section which may be helpful with any
1067issues you encounter immediately.
1068</p>
874 1069
875</body> 1070</body>
876</section> 1071</section>
877</chapter> 1072</chapter>
878 1073
886should now update your Linux kernel header files and re-merge glibc so that 1081should now update your Linux kernel header files and re-merge glibc so that
887userspace applications can take advantage of new Linux 2.6 features. 1082userspace applications can take advantage of new Linux 2.6 features.
888</p> 1083</p>
889 1084
890<pre caption="Updating to linux26-headers"> 1085<pre caption="Updating to linux26-headers">
1086# <i>emerge unmerge linux-headers</i>
891# <i>emerge linux26-headers</i> 1087# <i>emerge linux26-headers</i>
892# <i>emerge unmerge linux-headers</i>
893</pre> 1088</pre>
894 1089
895<p> 1090<p>
896After updating your headers package, you should generally re-merge glibc. 1091After updating your headers package, you should generally re-merge glibc.
897There is a new feature here that you may be interested in - NPTL. NPTL is a new 1092There is a new feature here that you may be interested in - NPTL. NPTL is a new
968Thanks! 1163Thanks!
969</p> 1164</p>
970 1165
971</body> 1166</body>
972</section> 1167</section>
1168<section>
1169<title>Removing Linux 2.4 from your system</title>
1170<body>
1171
1172<p>
1173After you have been running 2.6 for a while, you may decide that you no longer
1174have any requirement to be able to use Linux 2.4. The steps you can take to
1175clean up your system are detailed below. <e>Only follow the procedure in this
1176section if you are sure that you don't want/need to use 2.4 again!</e>
1177</p>
1178
1179<p>
1180The 2.4 kernel source code can be removed, using the emerge utility as usual.
1181For example, assuming you have 2.4 versions of vanilla-sources and
1182gentoo-sources installed, you could use the following command to remove them
1183while keeping the 2.6 versions intact:
1184</p>
1185
1186<pre caption="Example: Removing Linux 2.4 sources">
1187# <i>emerge unmerge =vanilla-sources-2.4.* =gentoo-sources-2.4.*</i>
1188</pre>
1189
1190<p>
1191Portage will not completely clean out your 2.4 kernel source installations,
1192because some temporary files are created during compilation. It is safe to
1193remove these remnants with the following command:
1194</p>
1195
1196<pre caption="Removing remaining temporary files">
1197# <i>rm -rf /usr/src/linux-2.4.*</i>
1198</pre>
1199
1200<p>
1201You can additionally remove modules and information files relating to your
1202old 2.4 kernel installations, as these are no longer needed.
1203</p>
1204
1205<pre caption="Removing previously-installed 2.4 modules">
1206# <i>rm -rf /lib/modules/2.4.*</i>
1207</pre>
1208
1209<p>
1210The 2.4 kernel binaries you used to boot from can also be safely removed.
1211You should mount your <c>/boot</c> partition, and remove those images. You
1212should also update your bootloader configuration so that it no longer
1213references these deleted kernel images.
1214</p>
1215
1216<p>
1217Some Linux 2.4 users will have previously installed the <c>alsa-driver</c>
1218package to benefit from the new audio capabilities included in Linux 2.6. If
1219you were one of these users, and you followed the advice given earlier in this
1220document about building ALSA with the 2.6 kernel sources (as opposed to using
1221the <c>alsa-driver</c> package), then you can safely remove this to prevent
1222future conflicts.
1223</p>
1224
1225<p>
1226Additionally, <c>lm-sensors</c> users will have previously used the <c>i2c</c>
1227package to provide the hardware drivers. As already mentioned, I2C drivers are
1228now included in the kernel, so this package can also be removed in order to
1229prevent future conflicts.
1230</p>
1231
1232<p>
1233The devfs management daemon, <c>devfsd</c>, can also safely be removed, now
1234that we are using <c>udev</c> for device management.
1235</p>
1236
1237<pre caption="Removing alsa-driver, i2c, and devfsd">
1238# <i>emerge unmerge alsa-driver i2c devfsd</i>
1239</pre>
1240
1241<p>
1242If you are LVM2 user, you may wish to convert your data into the LVM2 data
1243format in order to benefit from the advantages which LVM2 provides.
1244However, this operation will prevent you from ever accessing your LVM data
1245from a 2.4 kernel. If you want to continue with the conversion (this is totally
1246optional!), then you should examine the <c>vgconvert</c> man page for
1247instructions on how to carry this out. An example is shown below, where
1248<c>main</c> is the volume group name.
1249</p>
1250
1251<pre caption="Converting a LVM1 volume to LVM2 format">
1252# <i>vgconvert -M2 main</i>
1253</pre>
1254
1255</body>
1256</section>
973</chapter> 1257</chapter>
974</guide> 1258</guide>

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.10

  ViewVC Help
Powered by ViewVC 1.1.20