The complete Gentoo Linux 2.6 migration guide
What is new in Linux 2.6?
That is not an easy question to answer. Linux 2.6 is the result of over 2 years
of rapid development and stabilisation of new features, and is architecturally
quite different from its 2.4 counterpart. Some of the major changes are listed
Scheduler/Interactivity improvements: Linux feels very smooth on desktop
systems and copes much better than 2.4 while under load
Scalability: Linux now scales much better at both ends - on small embedded
devices and also systems with many processors
- Performance: Throughput from common applications is much improved
Hardware support: Linux now supports many more architectures and hardware
devices out-of-the-box than any other operating system.
Joseph Pranevich has written a very detailed document, The Wonderful World Of Linux
2.6 which you may be interested to glance over. If you are interested in
the more technical details, you can refer to The
post-halloween document - but do bear in mind that this is somewhat
Gentoo and 2.6
From the 2005.0 release of Gentoo Linux, the default kernel is the latest 2.6
series kernel. The default profile of the system is picked up from
/etc/portage/make.profile which on 2005.0 or above would be a symlink to
/usr/portage/profiles/default-linux/x86/2005.0 under which various
important settings are taken care of.
If you are using a 2.4 profile, please change it to one that supports a 2.6
kernel by doing the following.
Code Listing 1.1: Changing your profile
# rm -f /etc/portage/make.profile
# ln -snf /usr/portage/profiles/default-linux/x86/2005.1 /etc/portage/make.profile
What is udev?
In the past, Gentoo has instructed users to use devfs for managing the
/dev directory, which contains a series of device interfaces to
allow system applications to communicate with hardware (through the kernel).
devfs, whilst a good concept, has some internal problems, and has been
completely removed from the main stable tree as of 2.6.13.
udev is the new way of managing device nodes. It addresses issues with
previous device managers, and also attempts to solve some other problems.
The above may not mean much to you, but fear not, the hard working Gentoo
developers have put effort into making the migration from devfs very easy.
Please read the Gentoo udev Guide for
more information regarding the same.
What is ALSA?
With Linux 2.4, chances are that you used OSS (open sound system) drivers to
power your sound card. OSS has been replaced by a newer and better set of sound
ALSA, the Advanced Linux Sound Architecture, is a new set of sound drivers with
a new and improved API, present in the Linux 2.6 kernel. It is backwards
compatible with OSS applications, provided that you select the right kernel
If you do not have any sound/audio hardware, you can safely skip over any
ALSA-related instructions in this document.
What is LVM?
Logical Volume Management (LVM) exists as set of tools allowing you to
manage your disk storage in a very flexible manner. Amongst other things, it
allows powerful control over partitions (e.g. resizing without reboot), and
makes operations like device changes relatively simple. LVM acts as an
alternative to standard partition-based disk management.
LVM support has historically been implemented in Linux 2.4. Linux 2.6 features
a new version of LVM, named LVM2. The migration process requires you to
install new versions of the user-level tools (covered later in this document)
but will leave your data intact!
If you do not currently use LVM for data-storage management, then LVM2
migration does not apply to you. If this is the case, you can safely ignore
any parts of this document referencing LVM/LVM2. Upgrading to Linux 2.6 does
not require you to store your data on LVM partitions - you can keep your
data in the standard partition-format as it always has been.
If you are not a LVM user, but you think LVM2 sounds useful for you, you can
convert your disks to this format at a later date, by following the Gentoo LVM2 Installation Guide. For now, let us
just concentrate on getting a smooth 2.6 migration underway.
Get your system up-to-date
Some of the changes brought in with Linux 2.6 also required some changes in the
base system applications. Before continuing, you should ensure that your system
is relatively up-to-date, and to be perfectly sure, you should update all world
and system packages where updates are available.
In particular, make sure you have the latest stable versions of the following
sys-kernel/genkernel (only if you wish to use genkernel as opposed
to manual configuration)
Code Listing 2.1: Updating all world packages
# emerge --sync
# emerge -ua world
modutils vs module-init-tools
sys-apps/modutils is the package that provides tools such as
modprobe, rmmod and insmod for Linux 2.4.
Linux 2.6 introduces a new module format, and therefore requires new tools for
handling modules. These are bundled up into the
You should now remove modutils and install module-init-tools:
Code Listing 2.2: Switching from modutils to module-init-tools
# emerge --unmerge sys-apps/modutils
# emerge module-init-tools
Don't worry - even though you have just unmerged modutils, module-init-tools
provides backwards compatibility for Linux 2.4, so you will still be able to
boot into Linux 2.4 and handle modules for that kernel.
For the above reason, module-init-tools might already be installed and working
with your existing Linux 2.4 kernel. In this case, you don't need to worry
about this stage - your system is already ready to deal with Linux 2.6 modules.
There is no configuration involved here. Simply use emerge to install
Code Listing 2.3: Installing udev
# emerge -a udev
You should now read the Gentoo udev
Guide to get a more complete idea about the differences between udev and
Checking for essential device nodes
When the system boots up, the system requires some essential device nodes. As
udev is not included in the kernel, it is not activated immediately. To work
around this, you must ensure that you have some essential device nodes on your
Our installation stage files will have created the required devices during the
initial installation. However, some users have reported that this is not the
case. We will use this opportunity to check that the device files exist, and
create them if they do not.
As your existing device manager will be mounted at /dev, we cannot
access it directly. So we will bind-mount your root partition to another
location and access the /dev directory from there.
Code Listing 2.4: Bind-mounting your root partition and listing static devices
# mkdir -p /mnt/temp
# mount --rbind / /mnt/temp
# cd /mnt/temp/dev
# ls -l console null
If the above ls command reported that either console or
null do not exist, then you must create them yourself, as shown below.
Code Listing 2.5: Creating the missing console and null nodes
# mknod -m 660 console c 5 1
# mknod -m 660 null c 1 3
You should now unmount your bind-mounted root partition, even if you did not
have to create those devices:
Code Listing 2.6: Unmounting the bind-mounted root
# umount /mnt/temp
# rmdir /mnt/temp
Installing ALSA utilities
ALSA requires you to have some packages installed, so that applications can use
the ALSA API. These packages will also allow you to control the mixer and
volume levels. Install the required utilities as follows:
Code Listing 2.7: Installing ALSA utilities and libraries
# emerge -a alsa-lib alsa-utils alsa-tools alsa-headers alsa-oss
Installing the Linux 2.6 sources
Choosing and installing a kernel
The first thing you need to do is install sources of a 2.6 kernel of your
choice. The two Gentoo-supported 2.6 kernels are currently
gentoo-sources (for desktops) and hardened-sources (for
servers). There are others available, see the Gentoo Linux Kernel Guide for more
In this guide, we'll use gentoo-sources as an example. Install your
chosen set of kernel sources using the emerge utility:
Code Listing 3.1: Installing gentoo-sources
# emerge -a gentoo-sources
These are the packages that I would merge, in order:
Calculating dependencies ...done!
[ebuild NS ] sys-kernel/gentoo-sources-2.6.10-r4
Do you want me to merge these packages? [Yes/No] y
When performing the above emerge command, if you find that it wants to
install a 2.4 version of gentoo-sources (e.g. gentoo-sources-2.4.26),
then it means that the profile you are using is not designed for Linux 2.6
users. Please follow the Gentoo
Upgrading Document to switch to a 2.6-based profile, and retry installing
2.6 kernel sources.
Updating the /usr/src/linux symbolic link
Various components of the Gentoo utilities rely on /usr/src/linux
being a symbolic link to the kernel sources that you are running (or wish to
We will now update our /usr/src/linux link to point at the kernel
sources we just installed. Continuing our example:
Code Listing 3.2: Updating the /usr/src/linux softlink
# cd /usr/src
# ln -sfn linux-2.6.10-gentoo-r4 linux
Known pitfalls with Linux 2.6 migration
Before we get stuck into configuring the kernel, I'll attempt to detail the
most common errors that people make when migrating to Linux 2.6, as some of
these points will influence the way you configure the new kernel.
Not all of these points are relevant at this stage, but I will detail them all
here in one place, and you can refer back at your leisure.
Don't use "make oldconfig" with a 2.4 .config
If you don't understand what this means, don't worry, you won't make this
mistake if you follow the rest of this guide correctly.
You'll be asked many many questions, since there have been a large amount of
changes. Many people who do try a make oldconfig from a 2.4 config end
up creating an unworkable kernel (e.g. no output on-screen, no input from
keyboard, etc). Please save yourself the trouble, and use the traditional
menuconfig configuration method just this once.
Don't use ide-scsi for CD/DVD writing
In Linux 2.4, the only way to achieve good CD/DVD writing results was to enable
the (rather ugly) ide-scsi emulation. Thankfully, the IDE layer in Linux
2.6 has been extended to support CD/DVD writers much better.
You don't need to enable any extra options to support CD writing. Just be sure
not to enable ide-scsi as you used to.
PC Speaker is now a configurable option
You won't get your normal console beeps (or any response from the PC speaker at
all) unless you specifically enable the new PC speaker option
Code Listing 4.1: Location of PC speaker option
Device Drivers --->
Input device support --->
<*> PC Speaker support
By "PC speaker", I am referring to the analogue speaker that beeps once when
your system is powering up, I am not referring to normal sound hardware used
for playing music, etc.
New USB Storage block device driver sometimes problematic
Very recently, a new USB storage device driver has been added to the kernel.
At the time of writing, this driver ("ub") is still in its early stages and
some users find it to be unreliable. If you have problems accessing your USB
hard disk, USB flash disk, USB card reader, or USB digital camera, then you
could try reverting to the older SCSI-style driver:
Code Listing 4.2: Disabling ub
Device Drivers --->
Block devices --->
< > Low Performance USB Block driver
The older SCSI-style driver (USB Mass Storage support) is enabled by default.
It can be found under "Device Drivers --> USB support", but will generally
not come into effect while ub is also present.
usbdevfs renamed to usbfs
If you have edited your /etc/fstab file to customise the way that
the USB device filesystem gets mounted, you may have to modify the filesystem
type from usbdevfs to usbfs.
Recent 2.4 kernels will also allow you to use "usbfs" as well as "usbdevfs", so
you are not breaking any backwards compatibility by doing this.
Don't renice X
If you are a desktop 2.4 user, you may have hacked your system into running X
at a higher priority, as in some cases it seems to provide better desktop
There have been many scheduler changes in 2.6 which change this behaviour. If
you continue to run X at a higher priority, it will do exactly what it is
supposed to (run the display server at a very high priority) and you
will notice consequences such as sound stuttering and slow application load
times because your CPU is spending too long serving X and only X.
In Linux 2.6, you no longer need to renice desktop applications to get good
interactivity. Please remove your "niceness" hacks!
X11 config file should now use /dev/input/mice for PS/2 and USB mice
One of the changes that a default udev configuration introduces is different
organisation of the mouse device nodes. Previously, you would have had nodes
such as /dev/psaux and /dev/mouse. You will now have
nodes such as /dev/input/mouse0, /dev/input/mouse1,
and a collective /dev/input/mice node which combines movements
from all mice.
Since the old X configurations typically reference /dev/mouse or
/dev/psaux then you may get an error similar to the one shown
below when you attempt to start X11:
Code Listing 4.3: Common error when starting X on a udev system for the first time
(EE) xf86OpenSerial: Cannot open device /dev/mouse
No such file or directory.
(EE) Mouse0: cannot open input device
(EE) PreInit failed for input device "Mouse0"
No core pointer
To correct this, open your X11 config in a text editor, and update the mouse
InputDevice section to use the /dev/input/mice device. An
example is shown below:
Code Listing 4.4: Opening your X11 config file
# nano -w /etc/X11/xorg.conf
If you are still using XFree86, your config file will be
Code Listing 4.5: Sample mouse InputDevice section
Option "Protocol" "auto"
Option "Device" "/dev/input/mice"
If you are using a serial mouse, the new device path will be
/dev/tts/0 instead of /dev/ttyS0.
New Serial-ATA (SATA) drivers name the devices differently
If you used the original Serial ATA drivers under Linux 2.4, you probably
observed your SATA devices having names such as /dev/hde.
Linux 2.6 introduces some new SATA drivers (libata) which are based on the SCSI
subsystem. As these drivers are based on SCSI, your SATA disks will now show up
as SCSI devices. Your first SATA disk will be named /dev/sda. You will
need to update your /etc/fstab file to reflect this, and you will need
to bear this in mind when choosing the root/real_root kernel boot parameter
libata has been backported into recent versions of Linux 2.4, so you may
already be familiar with the new device naming.
bootsplash no longer maintained
If you used the gentoo-sources-2.4 kernel, you may have used the
bootsplash functionality in order to provide yourself with a colourful
The developer of bootsplash appears to have lost interest in his project, given
some design problems. However, Gentoo developer Michał Januszewski is
developing a successor, gensplash, which in included in the
gentoo-sources-2.6 kernel. You can follow Michał's
Gensplash in 5 easy steps document in order to familiarize yourself with
how gensplash is operated.
I2C drivers now included in the kernel
If you use lm-sensors to monitor system temperatures and power levels,
you previously needed to install the i2c package in order to provide
The I2C hardware drivers are now included in the Linux 2.6 kernel, no external
i2c package is required. Remember to compile support for your specific I2C
devices into the kernel configuration. You will then be able to use
lm-sensors as usual.
Configuring, building, and installing the kernel
As with Linux 2.4, you have two options for managing your new kernel build.
The default method is to configure your kernel manually. This may seem
daunting but is the preferred way as long as you know your system. If you
wish to configure your new kernel manually, please continue on to the next chapter.
The alternative option is to use our genkernel utility to
automatically configure, compile, and install a kernel for you. If you wish
to use genkernel then skip over the next chapter and proceed with
Default: Manual configuration
Configuring the kernel
We'll now get on with configuring the kernel. Open menuconfig in the usual way:
Code Listing 6.1: Invoking menuconfig
# cd /usr/src/linux
# make menuconfig
You will probably be familiar with using menuconfig from configuring 2.4
kernels. Fortunately, the front end has barely changed at all, but you will
observe much better organisation of kernel options, plus many new
options that weren't present in 2.4.
Be sure to enable the following important kernel options:
Code Listing 6.2: Required kernel options
File systems --->
Pseudo Filesystems --->
[*] /proc file system support
[*] Virtual memory file system support (former shm fs)
General setup --->
[*] Support for hot-pluggable devices
Device Drivers --->
<*> Sound card support
Advanced Linux Sound Architecture --->
<M> Advanced Linux Sound Architecture
<M> Sequencer support
<M> OSS Mixer API
[*] OSS Sequencer API
Device Drivers --->
Multi-device support (RAID and LVM) --->
[*] Multiple devices driver support (RAID and LVM)
<*> Device mapper support
Previously you may have included support for the /dev file system
(now marked OBSOLETE). Do not enable devfs support. We have installed udev,
which we will be using instead of devfs from now on.
Also, remember to enable support for the filesystems that you use, and the
hardware present in your system. Be sure to enable support for the IDE
controller on your motherboard if you wish to benefit from fast DMA disk
access. Refer to the Configuring the
Kernel section of the Gentoo
Handbook for additional guidance here.
Building the kernel
Now that we have configured the kernel, we can start the compilation process:
Code Listing 6.3: Compiling the kernel source
# make && make modules_install
You may recall having to run make dep with Linux 2.4 sources. This is no
Wait for the kernel compilation to complete (and observe the much more readable
Installing the kernel
The next step is mounting your /boot partition and copying the
kernel image over. You must then update your bootloader config manually.
Code Listing 6.4: Installing the kernel
# mount /boot
# cp arch/i386/boot/bzImage /boot/bzImage-2.6.10-gentoo-r4
Note that the above instructions are examples only, you should follow your
usual procedure of updating kernels by following the instructions in the Gentoo Handbook (see the Configuring the
When updating your bootloader config, do not remove the old entry pointing at
your 2.4 kernel. This way, you will easily be able to switch between the two if
something is not working.
Now continue onto the Module Configuration section.
Alternative: Using genkernel
If you prefer to use genkernel instead of manually configuring your kernel, you
will be happy to hear that using genkernel to produce 2.6 kernels is very
similar to the process you performed when producing your previous 2.4 kernel.
You should invoke genkernel as shown below:
Code Listing 7.1: Invoking genkernel with some common arguments
# genkernel --udev --menuconfig --bootloader=grub all
In the above example, we also take advantage of genkernel features to open
menuconfig to allow you to customise the kernel configuration (if you wish),
and to update the grub bootloader configuration after compilation.
You should choose genkernel arguments that suit you, but do not forget to
include the --udev argument! Refer to the Gentoo Linux Genkernel Guide and the Configuring the
Kernel chapter of the Gentoo
Handbook for additional information.
If you choose to update your bootloader config yourself, then you must remember
to include the udev kernel parameter. A sample grub config
section is shown below, but remember to adjust the real_root parameter
for your system.
Code Listing 7.2: Sample GRUB config for genkernel + udev
title Gentoo Linux (2.6 kernel)
kernel /kernel-2.6.10-gentoo-r4 udev root=/dev/ram0 init=/linuxrc ramdisk=8192 real_root=/dev/sda3
Installing external modules
Many users will additionally rely on kernel modules that are built outside of
the kernel tree. Common examples are the binary ATI and Nvidia graphics
drivers. You now need to install those modules, which will compile against the
2.6 sources found at /usr/src/linux. This is the usual case of
emerge packagename for all the external modules you are used to using
Refer again to the Configuring the
Kernel chapter of the Gentoo
Handbook for more info.
You may have decided to compile some kernel components as modules (as opposed
to compiled directly into the kernel) and would like to have them autoloaded on
bootup like you did with 2.4. Also, if you installed any external modules from
the portage tree (as described above) you will probably want to autoload them
To achieve this, edit /etc/conf.d/modules in your favorite text
editor and list the names of the modules you would like autoloaded.
Code Listing 8.1: Opening the module autoload list in nano
# nano -w /etc/conf.d/modules
Code Listing 8.2: Sample configuration entry to load the 3c59x and nvidia modules
LVM to LVM2 migration
Upgrading to LVM2 tools
If you do not use LVM to manage your disk storage, you can safely skip this
chapter and skip onto the next.
Fortunately, upgrading from the LVM1 user tools to the LVM2 versions is very
Code Listing 9.1: Upgrading user-tools from LVM1 to LVM2
# emerge --unmerge lvm-user
# emerge lvm2
You will need to re-emerge lvm-user if you plan to go back to booting a
2.4 kernel, as lvm2 by itself isn't enough for 2.4 kernels.
Booting into Linux 2.6
It's now time to boot into Linux 2.6. Close all applications and reboot:
Code Listing 10.1: Rebooting
# umount /boot
When you reboot, if you followed this document correctly so far, you will have
the option of either loading Linux 2.4 or Linux 2.6 from your bootloader.
Choose Linux 2.6.
Once the system has booted, check that things are working. If you made a
mistake in the kernel configuration, don't worry, you can skip back to the Configuring, building, and installing the kernel section,
make your change, recompile and install new kernel image, reboot, and try
Configuring and unmuting ALSA
We will now complete the ALSA configuration and unmute the audio channels. The
ALSA packages provide a useful utility to make this process relatively simple:
Code Listing 10.2: Invoking the automatic ALSA configuration utility
The process is straightforward: allow the /etc/modules.d/alsa file to be
automatically updated, and then allow ALSA to be reloaded. alsaconf will then
terminate, however you will need to run it multiple times if you have multiple
sound devices installed in your system.
You should now add alsasound to your boot runlevel, so that volumes will
be saved on shutdown and restored on bootup:
Code Listing 10.3: Adding alsasound to the boot runlevel
# rc-update add alsasound boot
The alsaconf utility chooses initial volume levels for your sound
devices. If these are inappropriate, you can modify them at any time with the
Any immediate problems?
At this stage you should refer back to the Known pitfalls
with Linux 2.6 migration section which may be helpful with any issues you
Header files and NPTL
By now you are running Linux 2.6 and hopefully have all issues ironed out. You
should now update your Linux kernel header files and re-merge glibc so that
userspace applications can take advantage of new Linux 2.6 features.
Code Listing 11.1: Updating to linux-headers
# emerge -u linux-headers
After updating your headers package, you should generally re-merge glibc.
There is a new feature here that you may be interested in - NPTL. NPTL is a new
threading model present in Linux 2.6, which features much quicker thread create
and destroy times. This won't make much of a difference to most systems, but
you may wish to enable it during this migration process! To enable NPTL, edit
/etc/portage/make.conf, adding nptl to your USE variable.
If you choose to also enable the "nptlonly" flag, be aware that you will no
longer be able to boot a 2.4 kernel.
Now re-merge glibc (you should do this even if you did not choose to enable
Code Listing 11.2: Reinstalling glibc against the new kernel headers
# emerge -a glibc
If you enabled NPTL, existing binaries will not use it until they are
recompiled. However, any binaries compiled from this point onwards will
use NPTL. You may wish to recompile all binaries now, e.g.:
Code Listing 11.3: Recompiling all packages on the system
# emerge -e world
Alternatively, you can just let your system "naturally" convert itself to NPTL
as you update to newer versions of packages when they are released.
With the incredible amount of work that went into Linux 2.6, it is sometimes
inevitable that things which used to work fine, no longer function as expected.
If you have any problems with your 2.6 kernel, and you can confirm that this
problem does not exist with Linux 2.4, then please open a bug with us on our
Bugzilla. We will investigate the
issue, and if we find that it is a problem in the mainline kernel, we may then
ask you to file a report at the central kernel bugzilla.
Hopefully you have just completed a smooth migration and you are enjoying the
benefits which Linux 2.6 brings over 2.4.
I would like to say a word of thanks to the many users who effectively 'tested'
this document while it was in its early stages, and provided feedback about how
the migration process went. Sorry that I did not reply to all the emails (there
were a lot!), but I did read every one, and refined this document where
appropriate. Enjoy your 2.6-enhanced systems :)
Removing Linux 2.4 from your system
After you have been running 2.6 for a while, you may decide that you no longer
have any requirement to be able to use Linux 2.4. The steps you can take to
clean up your system are detailed below. Only follow the procedure in this
section if you are sure that you don't want/need to use 2.4 again!
The 2.4 kernel source code can be removed, using the emerge utility as usual.
For example, assuming you have 2.4 versions of vanilla-sources and
gentoo-sources installed, you could use the following command to remove them
while keeping the 2.6 versions intact:
Code Listing 12.1: Example: Removing Linux 2.4 sources
# emerge --unmerge =vanilla-sources-2.4.* =gentoo-sources-2.4.*
Portage will not completely clean out your 2.4 kernel source installations,
because some temporary files are created during compilation. It is safe to
remove these remnants with the following command:
Code Listing 12.2: Removing remaining temporary files
# rm -rf /usr/src/linux-2.4.*
You can additionally remove modules and information files relating to your old
2.4 kernel installations, as these are no longer needed.
Code Listing 12.3: Removing previously-installed 2.4 modules
# rm -rf /lib/modules/2.4.*
The 2.4 kernel binaries you used to boot from can also be safely removed. You
should mount your /boot partition, and remove those images. You should
also update your bootloader configuration so that it no longer references these
deleted kernel images.
Some Linux 2.4 users will have previously installed the alsa-driver
package to benefit from the new audio capabilities included in Linux 2.6. If
you were one of these users, and you followed the advice given earlier in this
document about building ALSA with the 2.6 kernel sources (as opposed to using
the alsa-driver package), then you can safely remove this to prevent
Additionally, lm-sensors users will have previously used the i2c
package to provide the hardware drivers. As already mentioned, I2C drivers are
now included in the kernel, so this package can also be removed in order to
prevent future conflicts.
The devfs management daemon, devfsd, can also safely be removed, now
that we are using udev for device management.
Code Listing 12.4: Removing alsa-driver, i2c, and devfsd
# emerge --unmerge alsa-driver i2c devfsd
If you are LVM2 user, you may wish to convert your data into the LVM2 data
format in order to benefit from the advantages which LVM2 provides. However,
this operation will prevent you from ever accessing your LVM data from a 2.4
kernel. If you want to continue with the conversion (this is totally
optional!), then you should examine the vgconvert man page for
instructions on how to carry this out. An example is shown below, where
main is the volume group name.
Code Listing 12.5: Converting a LVM1 volume to LVM2 format
# vgconvert -M2 main