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 targetted at users upgrading from one kernel release to another, it will also be useful for users migrating from one kernel package to another.

gentoo-dev-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. Reasons for upgrading kernel are generally either to take advantage of a specific new feature or driver, 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     U ] sys-kernel/gentoo-dev-sources-2.6.9-r2 [2.6.8-r5]

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

# emerge -u gentoo-dev-sources

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

Gentoo requires you to maintain a symbolic link, located at /usr/src/linux. This should point to the sources of the kernel you are running.

In this case, we need to update the symbolic link to point at the kernel sources that we are about to upgrade to. Continuing our example:

# cd /usr/src
# ln -sf 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. A quick summary is provided here.

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:

# genkernel 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 bootloader config, then invoke genkernel as follows:

# genkernel --menuconfig --bootloader=grub all

For more info, follow the Gentoo Linux Genkernel Guide, or refer to the handbook.

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. Refer to the Gentoo Handbook for additional guidance on this.

Next, compile your kernel and copy it over to your boot partition. Again, follow the handbook instructions here, but don't forget to mount your /boot partition first! In the initial installation, you would have already mounted this at a much earlier stage.

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

Finally, you should update your bootloader config, adding an entry for the new kernel (don't delete the old one just yet!) and unmount the /boot partition. Again, refer to the handbook for instructions here.

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 on every kernel upgrade. This is as simple as re-merging the packages involved. Refer again to the Gentoo Handbook Configuring the Kernel chapter for more info here. Re-merging these packages will ensure they build against the source tree at /usr/src/linux - therefore they will actually being installed for the kernel we just compiled.

Next, close all applications and reboot your system. If you followed the above instructions correctly, you will see an entry for your new kernel on your bootloader. Select the new kernel and let the system boot.

Hopefully, your system will boot without problem and you can log in and start working as usual. If everything is working, then the upgrade is complete at this stage.

If you have made a mistake and your system will not boot into the new kernel, then you can simply reboot and boot into your previous 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 (e.g. you just missed a network driver) then you might not even need to reboot to do this.

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 and 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 bootloader config). 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 advantages of emerge's prune option. Continuing the example using gentoo-dev-sources:

# emerge -P gentoo-dev-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 and System.map files for the kernel(s) you are pruning. You should also edit your bootloader config so that it no longer references this kernel.

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.