The kernel is one of the few package classes in portage that requires some manual intervention to complete the upgrade. Portage will download and install the kernel source for you, but then it is up to you to step in and compile the new kernel before any changes will take effect.

Although this guide is targeted at users upgrading from one kernel release to another, it will also be useful for users migrating from one kernel package to another.

gentoo-sources is used as an example in this document, however, the instructions here also apply to the other packages present in our tree.

Generally, upgrading from one minor kernel release to the next won't bring any major differences. There are several reasons to upgrade the kernel. One is to take advantage of a specific new feature or driver; another is to be protected against a security vulnerability, or just to maintain an up-to-date and healthy system.

Even if you choose not to update to every new kernel revision, it is recommended that you at least upgrade from time to time. It is strongly recommended that you immediately upgrade to a new kernel if that new release solves a security problem.

You upgrade the kernel sources like you would upgrade any other package - using the emerge utility. It will probably be the case that you want to upgrade your kernel when you see the upgrade appearing on your world updates list. For example:

# emerge -Dup world
Calculating dependencies ...done!
[ebuild    NS ] sys-kernel/gentoo-sources-2.6.9-r2 [2.6.8-r5]

You can then go ahead and install the update, e.g.:

# emerge -u gentoo-sources

The kernel sources will then be installed into a subdirectory of /usr/src. In the above example, the new kernel sources will be installed at /usr/src/linux-2.6.9-gentoo-r2.

Gentoo requires that the /usr/src/linux symbolic link points to the sources of the kernel you are running.

Portage can update the symlink automatically when you emerge new kernel sources. All you have to do is add the symlink flag to the USE variable in /etc/make.conf.

(Add the symlink keyword)
USE="symlink x86 3dnow 3dnowex X aac aalib adns alsa apache2"

If you really want to do it yourself, the following example shows you how to make the link point to linux-2.6.9-gentoo-r2:

# cd /usr/src
# ln -sfn linux-2.6.9-gentoo-r2 linux

For either of these options, you should refer to the instructions given in the Gentoo Handbook relating to Configuring the Kernel and Configuring the Bootloader. Below is an outline of the required actions:

If you are a genkernel user, you just need to repeat the stages you went through when installing your kernel for the first time.

Simply run genkernel in the normal way:

(For 2.4 kernels:)
# genkernel all

(For 2.6 kernels:)
# genkernel --udev all

You can also use extra parameters for other genkernel functionality. For example, if you wish to configure some extra kernel options using menuconfig and you wish genkernel to automatically update your grub boot loader configuration, then invoke genkernel as follows:

# genkernel --menuconfig --bootloader=grub all

For more info, follow the Gentoo Linux Genkernel Guide, or refer to the Gentoo Handbook. Many of the options can be set in the configuration file for genkernel, /etc/genkernel.conf.

To begin, open the menuconfig utility in the kernel source tree:

# cd /usr/src/linux
# make menuconfig

Select the options required for your hardware and operating environment. For additional information on kernel configuration, refer to the chapter entitled Configuring the Kernel of the Gentoo Handbook.

Next, compile your kernel and copy it over to your boot partition. Again, follow the Gentoo Handbook instructions outlined in the chapter on Configuring the Bootloader. If /boot is a separate partition, ensure it is mounted before copying the compiled kernel to this directory! Failing to do so would keep you from booting the system with your new kernel.

# make && make modules_install
# mount /boot
# cp arch/i386/boot/bzImage /boot/bzImage-2.6.9-gentoo-r2

Finally, you should update your boot loader configuration, adding an entry for the new kernel (don't delete the old one just yet!) and unmount the /boot partition. Again, refer to the Gentoo Handbook for detailed instructions on this procedure.

If you use any kernel modules that are not included in the kernel source tree but are provided elsewhere in portage (e.g. NVIDIA or ATI graphics drivers), then you must reinstall these after upgrading the kernel. This is as simple as re-merging the packages involved. For more information, refer to the chapter on Configuring the Kernel in the Gentoo Handbook. To ensure these packages will build against the source tree at /usr/src/linux, first uninstall the packages, then re-emerge them. If old sources for these packages are kept by portage, this uninstall/re-emerge procedure will make sure that they are rebuilt to work with the new kernel.

We provide you with an easy tool (sys-kernel/module-rebuild) which rebuilds all the kernel modules you have installed using separate ebuilds.

Next, close all applications and reboot your system. If you followed the above instructions correctly, the boot loader menu should include an entry for the new kernel. Select the new kernel and let the system boot.

Hopefully, your system successfully boots with the new kernel, and you can log in to resume whatever you were doing. If this is the case, then the upgrade is complete.

If you made a mistake and the system fails to boot with the new kernel, reboot the system and select the entry from the boot loader that corresponds to the last known working kernel. You can then restart from the Configuring, compiling, and installing the new kernel stage -- making the appropriate changes to correct your mistake. In some cases, you might not even need to reboot to do this (e.g. you missed a driver for an audio device, Ethernet adapter, etc.)

You may have noticed, that when installing the sources for your newer kernel, the sources for your existing kernel were not removed. This is by design -- it allows you to easily switch between running different kernels.

Switching between multiple kernels is as simple as leaving the kernel sources under /usr/src/ and leaving the bzImage binaries on your /boot partition (referenced by entries in your boot loader configuration). Every time you boot up, you will be presented with a choice of which kernel to boot into.

Continuing on from the last section, you may be happy with your new kernel and not have any need to keep older kernel versions around. To easily remove all sources for a particular kernel except for the newest one, you can take advantage of the prune option available through emerge. Continuing the example using gentoo-sources:

# emerge -P gentoo-sources

In most cases, temporary files used during compilation will still remain under the appropriate source directory under /usr/src. It is safe to remove these using rm.

You can also safely delete any modules that were used by this kernel. This can be done by removing the appropriate directories under /lib/modules/ that relate to the kernel versions you are removing. Be careful not to delete modules belonging to kernels that you still use!

Finally, you can mount your /boot partition and remove the bzImage file(s) for the kernel(s) you are pruning. You should also edit your boot loader configuration so that it no longer references such kernel(s).

It is sometimes possible to save time by re-using the configuration file from your old kernel when configuring the new one. Note that this is generally unsafe -- too many changes between every kernel release for this to be a reliable upgrade path.

The only situation where this is appropriate is when upgrading from one Gentoo kernel revision to another. For example, the changes made between gentoo-sources-2.6.9-r1 and gentoo-sources-2.6.9-r2 will be very small, so it is usually OK to use the following method. However, it is not appropriate to use it in the example used throughout this document: upgrading from 2.6.8 to 2.6.9. Too many changes between the official releases, and the method described below does not display enough context to the user, often resulting in the user running into problems because they disabled options that they really didn't want to.

To reuse your old .config, you simply need to copy it over and then run make oldconfig. In the following example, we take the configuration from gentoo-sources-2.6.9-r1 and import it into gentoo-sources-2.6.9-r2.

# cd /usr/src/linux-2.6.9-gentoo-r2
# cp ../linux-2.6.9-gentoo-r1/.config .
# make oldconfig

At this point, you may be asked to produce answers for configuration options which have changed between the two versions. Once you have done that, you can compile and install your kernel as normal, without having to go through the menuconfig configuration process.

With the rapid development of the Linux kernel, it is inevitable that some changes made from one kernel release to another may cause some problems. If you have any issues with the latest versions of Gentoo-supported kernels then please do report the issues to us.