Gentoo - kernel upgrade

By: John McFarlane <john.mcfarlane@rockfloat.com>
Last updated: 03/28/2007 @ 19:18

Abstract:
This document will go thru a step by step upgrade of an existing kernel, or upgrade to an entirely new kernel version.



1. Introduction and terminology

Kernel upgrades can really be confusing when first learning how things work. Essentially there are two things you could be talking about when using the phrase kernel upgrade:
  1. Making changes to a particular kernel version (eg: include another kernel module or something)
  2. Upgrading from one kernel version to another, say from a.b.c to a.b.f. When upgrading, it's pretty much understood that the kernel configuration will probably change at least a little bit.
There are four things you'll need to pay attention to when upgrading your kernel:
  1. /usr/src/linux A symlink to the currently "active" kernel tree. This should always be linked to the kernel you want to use.
  2. /usr/src/linux-2.6.X-gentoo-rX The kernel source tree. This directory holds a patched version of the official kernel sources.
  3. /usr/src/linux-2.6.X-gentoo-rX/.config The kernel's configuration file. This file is what determines how the kernel is to be compiled.
  4. /usr/src/linux-2.6.X-gentoo-rX.config This [only by convention] holds a known good backup of the kernel config.
I'm finished with this step

2. Validate your backup

Because the kernel's configuration is held in a single file, before you make any changes you want to ensure you have a valid backup. Here are the steps you need to follow to validate your backup:
  1. Look to see what kernel version is currently active. This is done by looking at what the /usr/src/linux symlink is linked to. Let's say it's linux-2.6.X-gentoo-rX
  2. See if you have a known good backup for this kernel version. It should be located here: /usr/src/linux-2.6.X-gentoo-rX.config. If it exists then you probably were a good little boy last time you compiled your kernel. If not it looks like either this is your first time doing a kernel upgrade, or you were not a good little boy last time you did an upgrade. If you just got a guilty feeling... then the kernel nazi says: "No candy for you!"

    If it didn't exist, then you need to make a backup now:

    
    root# cp /usr/src/linux/.config /usr/src/linux-2.6.X-gentoo-rX.config
                        

  3. It's also handy to have a backup of the kernel itself. It's important to only do this if you're sure the kernel is bootable:
    
    root# cd /boot
    root# cp `uname -r` BACKUP
                    
    You could use it as a last resort if you ever find yourself stuck at a Grub subsystem prompt
I'm finished with this step

3. Mount boot

You'll need to eventually, why not now:

root# mount /boot
        
I'm finished with this step

4. Determine your purpose

You need to decide if you want to upgrade to a new kernel version, or simply reconfigure the same kernel version. If you want to make a change to the kernel version you already have... skip to the next section. Otherwise you need to update the symlink to point to the kernel version you do want to work with. Let's say you want to use linux-2.6.X-gentoo-rY:

root# cd /usr/src
root# rm linux
root# ln -s linux-2.6.X-gentoo-rY linux
        
Tip It's very important to NOT forget this next step when switching from one kernel version to another. If you're not upgrading to a new kernel version, you should be skipping to the next section.
Now you need to copy your old kernel configuration, into your new kernel source tree. Then you need to handle any configuration changes that the new version offers. For example, say the new kernel supports a super cool finger print reader, and additional encryption support was added. Before you can move on, you need to decide how you want to handle these two features (and any others).

root# cd /usr/src/linux
root# make oldconfig

# You will now be asked a series of questions.  For each you can answer with
# Y, M, N.  This is to compile it in, compile as a module, or don't support
# it at all.  If you just hit ENTER you will accept the default answer, often
# the best choice.

        
I'm finished with this step

5. Configure the kernel

Here's the fun part. You get to go thru the kernel and pick what you do and don't want. It's your chance to remove stuff you don't want, add stuff you do want... or change stuff to become modules. You can do this a few different ways, though I like to do it old school:

root# cd /usr/src/linux
root# make menuconfig
        
Here you use an ncurses type application to pick the stuff you want. I can't really help you here, just do what you need to do.

When you're finished, keep hitting exit until you receive a prompt to save your configuration. You DO want to save it. It will be saved to: /usr/src/linux/.config

I'm finished with this step

6. Compile the kernel

When you compile the kernel, it does two things:
  1. Compiles the kernel into a file named: bzImage
  2. Compiles certain things as kernel modules, that can be loaded and unloaded at runtime
Off we go:

root# cd /usr/src/linux
root# make && make modules_install
        
I'm finished with this step

7. Copy the new kernel to boot

The kenel lives in /boot. Let's say for example that you just compiled linux-2.6.X-gentoo-rX, then you will do:

root# cd /usr/src/linux
root# cp arch/i386/boot/bzImage /boot/linux-2.6.X-gentoo-rX
root# cp System.map /boot/System-map-linux-2.6.X-gentoo-rX
        
If you're making changes to the same kernel version, than you just overwrote the old kernel (all good because you have a backup).
I'm finished with this step

8. Update grub

If you are switching to a new kernel version, you need to update your grub configuration file. Use your editor of choice and add the new kernel into: /boot/grub/grub.conf

Then refresh the master boot record. Be sure to replace the part in red with your actual device:


root# grub-install --no-floppy /dev/sda
            
If you happen to have something like an HP DL series server with scsi disks... you might need to do something along the lines of this instead of the above command:

root# grub
grub> device (hd0) /dev/cciss/c0d0
grub> root (hd0,0)
grub> setup (hd0)
grub> quit
            

I'm finished with this step

9. Cross your fingers and reboot

Let's go thru a quick checklist:
  1. You validated your backups
  2. You compiled your new kernel
  3. You updated grub.conf
  4. You updated the MBR
Pull the trigger:
  
root# reboot
        
I'm finished with this step

10. Rinse and repeat

Keep performing the above steps as needed... till you get the kernel where you want it.
I'm finished with this step

11. Backup the known good configuration

Once you're booted into a kernel that you're happy with, you should backup it's configuration. Say the kernel you are happy with is version linux-2.6.X-gentoo-rY then you would do:

root# cd /usr/src
root# cp linux/.config linux-2.6.X-gentoo-rY.config
        
I'm finished with this step

Changelog: Date Description
03/28/2007 @ 19:18 Initial creation

This document was originally created on 02/11/2006


Conventions and tips for this howto document:
  1. Please remember that I'm no kernel expert, and making even the slightest wrong step in a kernel update can render your machine useless.
  2. Please always have a live-cd available and know how to use it - just in case something goes wrong :/

Disclaimer:
This page is not endorsed by gentoo.org or any other cool cats. Any information provided in this document is to be used at your own risk.