Creating custom kernels with Debian's kernel-packaging system

Jesse Goerz

         jwgoerz@users.sourceforge.net
         

Revision History
Revision v0.421 March 2002Revised by: jwg
Rewrite. Added use of fakeroot, compiling modules by themselves. General corrections, license change from GNU FDL to GNU GPL.
Revision v0.323 May 2001Revised by: jwg
Updated section on symlinks, program version checks, how to compile as a regular user rather than root, filled in the checklist, added troubleshooting section(needs work).
Revision v0.222 April 2001Revised by: jwg
Quick fix on grammatical and spelling errors.

This document is intended to help Debian newbies use the kernel-packaging system to create custom kernels. Copyright © 2001-2002 Jesse Goerz, NewbieDoc project. This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This manual is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

A copy of the GNU General Public License is available as /usr/doc/copyright/GPL in the Debian GNU/Linux distribution or on the World Wide Web at the GNU website. You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Thank you Erdmut Pfeifer and Oliver Elphick for your prompt responses to my questions about make xconfig on debian-user! I couldn't have completed this document without your help.

Thanks to Sebastiaan for pointing out that almost everything could be done as a regular user when you're a member of the src group. Thanks to Robert Voigt for actually following the instructions to the letter and relaying his test results by identifying specific weaknesses in this document.


Table of Contents
1. Introduction
2. What to install
3. Making sure you have everything you need
3.1. Adding user to group src
3.2. Setting up the source tree
3.3. Setting up the symlink
4. Configuring the kernel
4.1. make xconfig
4.2. make menuconfig
4.3. make config
5. Building the kernel image
5.1. Revisions
5.2. Flavours
5.3. Making the kernel image
6. What now?
6.1. Installing the debianized kernel
6.2. Clean up
7. Checklist
8. Troubleshooting

1. Introduction

I used to compile kernels manually, and it involved a series of steps to be taken in order; kernel-package was written to take all the required steps (it has grown beyond that now, but essentially, that is what it does). This is especially important to novices: make-kpkg takes all the steps required to compile a kernel, and installation of kernels is a snap. --Manoj Srivastava, from the manual of kernel-package

If you have ever compiled a kernel before you will be amazed at just how much of a snap using Debian's kernel-package is. This tutorial was designed to enable you to take advantage of Debian's kernel packaging system. What it does is simplify the compiling and installing of a custom kernel and its modules by creating a debianized package of the image. Then it's just a matter of installing the kernel with dpkg.

Note

Compiling a kernel is not an insignificant thing. What you are about to attempt is usually only accomplished by experienced Debian users and administrators.

Warning

You can make your system unbootable if you're not careful. I highly recommend you read the entire document, start to finish, at least once, and then build the kernel. (And even then, you may want to get more information.)

I'll be using the 2.2.19 kernel source as the basis of this document. You don't have to use that version but I recommend it if this is your first time. Whatever kernel version you choose, if you're new to kernel compiling, try and get one that has a different version then the one you are currently using. Although I'll cover what you need to do if you're compiling the same version you currently have installed, it'll cut out a few steps and make your life easier if you choose a differnet version. I'll cover how to find out what version you're using in the next section.

Please remember that, inevitably, someone will use this document and screw up their system. Don't let that be you. If you don't understand something, get more information before proceeding. If you happen to be reading this and you see something you know is a mistake, please let me know at .


2. What to install

First you need to install the following packages in order to follow along with this document.

  1. kernel-package

  2. dpkg-dev

  3. debianutils

  4. binutils

  5. libc6-dev

  6. gcc

  7. make

  8. kernel-source-2.2.19

  9. task-tcltk-dev (alternatively, libncurses5-dev)

  10. bin86 (pc's only)

You can install these by simply doing this (as the root user):

bash# apt-get install kernel-package dpkg-dev debianutils binutils libc6-dev gcc make kernel-source-2.2.19 task-tcltk-dev bin86

Note

Note that bin86 is only required for PC's (not Macs or Alphas). Also, you can download any version of the kernel sources you wish but I chose 2.2.19 because it's the most current in Potato at the time of writing. I also recommend you choose a kernel version which is not the same as your current version. I will cover what to do if you must use the same version in later sections.

Note

A note about kernel source packages. The Debian maintainers have done an excellent job in packaging the kernel source into .deb files. I recommend you use those rather than source packages from other resources. The primary reason is the maintainers' packages unzip into a directory named kernel-source-Version. For some reason, the "official" kernel sources unzip into a directory called linux. This can cause problems if you're not careful when you do your unzipping. The only reason I can see not to use the Debian kernel source packages is if they don't have the version you need for some hardware requirement. If that's the case, the next section will cover how to avoid messing up your kernel sources.

To find out the current version of your kernel do this:

bash$ uname -r

3. Making sure you have everything you need


3.2. Setting up the source tree

The source tree is just another name for the directory which contains all the source code you will be compiling. Change to the directory /usr/src where all the source files are kept so we can check to see if we have everything we need. Do this:

bash$ cd /usr/src

In that directory you'll see the bzipped tar file which you installed using apt-get (or gzipped, depending on whether you used apt-get or not):

bash:/usr/src$  ls
kernel-source-2.2.19.tar.bz2

Warning

If you downloaded kernel sources from anywhere other than the Debian site you need to make sure you do not have a symlink called linux in your /usr/src directory. If you do you should remove that symlink before unzipping any sources. If you do not remove it before unzipping there is a good chance you will overwrite old source files and you will probably get a mess which may or may not compile correctly. Jump ahead to the section called Setting up the symlink. If you downloaded the sources using the apt-get command from the "What to install" section, you can ignore this warning.

To unzip the tar file using bzip do (this should be done as a regular user!):

bash:/usr/src$  tar -xIf kernel-source-2.2.19.tar.bz2

Note

The version of tar in stable (aka Potato) uses the -I option for bzip2 compression. If you're using a newer version of tar there's a chance it uses the -j option for bzip2 compression.

To unzip the tar file using gzip do (this should be done as a regular user!):

bash:/usr/src$  tar -xzf kernel-source-2.2.19.tar.gz

This should create a directory called kernel-source-2.2.19. Inside that directory you should find another called Documentation. Change into that directory and look for a file called Changes. Open that file with your favorite text editor and look for the section called Current Minimal Requirements. Here's what mine looked like:

The changes document above lists the program in the first column, the required version in the 2nd, and the way to check for the version in the 3rd. Note that you may not need all the packages listed if you aren't currently using them in your system (i.e. you won't need pcmcia-cs if you're not using any pcmcia cards).

Note

This documentation was written by a kernel developer based on the distribution of Linux he/she was working on. What that means is some of these commands may not work for determining versions installed on your Debian system. If that's the case, try finding the version command to use by following the example below.

bash:/usr/src$ man program_name

Substituting program_name for the program you're wondering about.


3.3. Setting up the symlink

Once you have everything you need installed (cross your fingers) you need to set up a symlink to the source tree.

bash:/usr/src$  cd /usr/src

Before you make a symlink called linux check to make sure you don't already have one in that directory by following Example 2. If you already have one there, it's probably because you have installed or compiled kernel source before. Make sure you remove the old link and make a new one which points to the source tree you wish to compile.

In that same directory (/usr/srcyou need to create a "soft link" or symlink to the source tree. You do that like this:

bash:/usr/src$  ln -s kernel-source-2.2.19 linux

The format for this is ln -s name_of_kernel_source_tree linux.

The directory that was created when you unzipped your kernel source is what is substituted for name_of_kernel_source_tree.

To make sure you did it correctly it's a good idea to do an ls -l. It should look like the example below.

Example 2. Symlink

bash:/usr/src# ls -l
total 66908
-rw-r--r--    1 root     root     15433132 Apr  7 21:38 kernel-source-2.2.19.tar.bz2
drwxr-sr-x   15 jesse  (1)src          4096 May 23 16:30 kernel-source-2.2.19
lrwxrwxrwx    1 jesse    src            20 May 23 19:16 linux -> kernel-source-2.2.19
                                                               (2)
(1)
Notice that the group for the kernel source tree and the link are both src. This will allow you to compile the source without being the root user. You should be in the src group because of what you did in the "Adding user to group src" section.
(2)
Notice the little arrow which shows the link is pointing to the kernel source tree.

Now that you have the symlink set up we can move on to configuring the kernel.


4. Configuring the kernel

4.1. make xconfig

There are several programs to configure the kernel. The first one we will cover is called xconfig. You can start the program with the make xconfig command. We need to make sure we start it in the /usr/src/linux directory. So it should look something like this:

bash:/usr/src$ cd linux

And then do:

bash:/usr/src/linux$ make xconfig

If you get an error check out the "Troubleshooting" section. If everything goes well you'll get a window that looks like this:

Covering how to configure all the options available for the kernel is way beyond the scope of this document. To find out more about the options you can configure, please reference The Linux Documentation Project's kernel-howto, the documentation in /usr/src/linux/Documentation, and your hardware documentation. I hope to add a section here in the future listing the most common "constant" options.

Once you are done configuring the kernel to your wishes and have pressed the "Save and Exit" button, you can move on to the next section, "Building the kernel image."


5. Building the kernel image

Building the kernel is usually what takes the longest amount of time. If you have an older machine with a slower processor it can take as long as a couple of hours. It is possible to build your kernel on a fast machine and then later copy it to the slower machine, but I won't be covering that here. I built kernel 2.2.19 on my high-speed-low-drag pentium 120 with 128MB of RAM and it took about 20-25 minutes. Not to shabby. (and yes, "high-speed-low-drag" is an industry term)

To build the kernel we will be using a program called make-kpkg. Before we start using it, we need to talk about revisions and flavours. I will only be covering these subjects lightly. It's a good idea to reference the documentation that was installed with this package.

Tip

make-kpkg is part of the "kernel-package" package. The relevant documents should be located in /usr/share/doc/kernel-package/. It's not a bad idea to also consult man make-kpkg.


5.2. Flavours

The flavours option is a lot like revisions in that they create information which is added to the package name. They also follow the same naming rules: It may contain only alphanumerics and the characters "-" "+" "." Do not use uppercase letters or hyphens. The primary reason to use the flavour option is if you're compiling a kernel with the same version number as the one you are currently running.

Caution

You will need to do make-kpkg clean FIRST if you wish to recompile the kernel-image using a flavour. There are also module conflict issues you need to worry about.

If you followed my advice and got a kernel version different than the one you are currently running, you won't have to worry about the flavours option. If you don't have a choice then please consult the flavours documentation. In future versions I hope to cover this in more detail. If you are knowledgable about this and would like to coauthor please contact me at .

Tip

Please read /usr/share/doc/kernel-package/Flavours if you are compiling a custom kernel with the same version number as the one you are currently running. You can find out which version you are running on the bottom of this page.

Tip

You can get by without using the flavours options if you're willing to get rid of your old modules and overwrite your current kernel. I don't recommend this because if you make a mistake, your only recourse is a boot floppy (if you made one!) and some repairs with utilities you probably aren't that familiar with. I try to avoid stuff like that as much as possible. If you're adventurous and want to give it a try, go for it. Just make sure your important data is backed up and you have a current boot floppy.


5.3. Making the kernel image

Before we make the kernel the first thing we need to do is make a boot disk. This way, if anything gets screwed up we will still be able to boot the machine and (hopefully) fix it without having to reinstall. You can make a boot disk by grabbing a floppy disk which you don't mind erasing and doing this (as the root user):

bash# mkboot path_to_kernel

Replace path_to_kernel with the appropriate information. This is usually something like /boot/vmlinuz-2.2.17. The directory /boot is where your current kernel is (unless you put it somewhere else). vmlinuz is the name of your kernel and its version will be appended to the end. (unless you have compiled a kernel before, in which case it may be bzImage or zImage.)

Finally! The time has arrived. We are now ready to make the kernel image and modules. Execute the command (as a regular user):

bash$ cd /usr/src/linux

And then do:

bash:/usr/src/linux$ make-kpkg --revision=custom.1.0 kernel_image

Do not change the kernel_image target with your kernel version. That command should be executed exactly as above (unless you used a different revision number).

Now all you can do is wait for the computer to finish. Take a few minutes off and enjoy yourself while the computer does its fair share of the work.

Tip

If you've already used this document to install a kernel as a Debian package you'll need to make sure you increment your revision number by some amount. For example you would change the above revision number to 1.1 or maybe 2.0. You'll need to do this because dpkg will not upgrade your previous kernel because it sees the same revision number and thinks it's already current. You will also need to move you're old modules "out of the way" by renaming their folder to something like 2.2.19-old. The modules are located in /lib/modules/.


6. What now?

6.1. Installing the debianized kernel

Once the kernel image is done compiling you will need to install the kernel and the modules. First check to make sure your kernel compiled successfully by changing into the /usr/src directory like this:

bash:/usr/src/linux# cd ..
bash:/usr/src# ls
custom-kernel.config                     kernel-source-2.2.19    kernel-source-2.2.19.tar.bz2
(1)kernel-image-2.2.19_custom.1.0_i386.deb  linux
(1)
There it is! Notice that it added our revision option to the end of the filename along with the automatically determined architecture.

Now to install the kernel and all its modules simply do this:

bash:/usr/src# dpkg -i kernel-image-2.2.19_custom.1.0_i386.deb

As part of the post-installation process it will ask you if you want to install the modules. You definitely want to say yes.

Warning

If you are using the flavour option or are installing a kernel version which is the same as the one you are currently running you should immediately jump to another terminal and move your current modules "out of the way." If you don't there is a very good possibility you will end up with module conflicts and a broken or wacky-acting system. Please reference the Flavour documentation in /usr/share/doc/kernel-package/Flavour.

Caution

The command to move your modules "out of the way" is (as root user):
bash:/lib/modules# mv 2.2.19 2.2.19-old
Substituting your version number for 2.2.19.

The post-installation should then ask you if you want to make a boot disk. If you made one earlier then you can say no here. Otherwise, grab a floppy you don't mind erasing, and say yes.

Next the post-installation should ask you if you want to run lilo. The documentation says it is a bit buggy but I didn't notice any problems. Say yes.

Warning

If you haven't made a boot disk yet then you need to do so. If for whatever reason the post-install wacks lilo you will not be able to reboot without it. Also, if you are using loadlin or some other bootloader you will probably want to reference the documentation in /usr/share/doc/kernel-package before answering this question. Your answer should most likely be no.

If everything went well then all you need to do is reboot and see if it works. If the reboot fails, insert your boot floppy and reboot. In future versions I hope to cover more troubleshooting issues, but for now, seek out help wherever you can find it;-)


6.2. Clean up

Congratulations on compiling your first kernel with kernel-package. No sweat eh? There are a couple more things we need to do to clean things up before you can enjoy that new kernel.

First, since we didn't create an epoch with our custom kernel package we need to put it on hold so dselect or apt-get doesn't try to "upgrade" it. You can do that by doing this (as the root user):

bash# echo "kernel-image-2.2.19 hold" | dpkg --set-selections

Substitute the name of your kernel image for the above. Also, the "|" character is made by typing Shift-\. To check that the package is indeed on hold do this (again, as root):

bash# dpkg --get-selections | grep kernel-image

If you put it on hold successfully it should look like this:

bash# dpkg --get-selections | grep kernel-image
kernel-image-2.2.19     hold

Next, you need to get rid of the symlink you created in the /usr/src directory. It's not really necessary but it's a good idea. There are several reasons most people remove the link:

  1. The next time you decide to download a kernel it might not be from a Debian archive. When you go to unzip the source it will overwrite your old source tree right through the old symlink you left in place last time. Bummer.

  2. The next time you download the kernel source from the Debian archive, you'll unzip the source into it's own tree without problems. But... seeing you already have a symlink called linux in the src directory, you figure you're fine and go ahead and compile. Forgetting, of course, that it's linked to your old source tree.

  3. When you download patches or other source (that you need to run special hardware) into a specific source tree, you don't want anything else messing with it. By removing the symlink you just might prevent #1 from happening.

Again, it's not necessary to remove the link. I would recommend it. It's easy to recreate, and you don't hurt anything by removing it. To remove the link do this (as root user):

bash# cd /usr/src
bash:/usr/src# rm linux

Finally, it's not required, but a good idea is to backup the custom debianized kernel you created onto whatever medium you choose. As a minimum, create another boot disk, this time using the new kernel you just created. Grab another floppy you don't mind being erased. It's not a good idea to overwrite the original boot disk you created. You haven't been using your new kernel long enough to determine if it's going to work the way you want it to. If you installed kernel-2.2.19 like I did just do (otherwise substitute your information) (as root user):

bash# mkboot /boot/vmlinuz-2.2.19

One final note. If you happen to need to rebuild your kernel, because you just bought a new sound card or you want to enable a new feature which you just realized you forgot to put in the first time, all you have to do is make-kpkg clean and increment your kernel image one revision. Your new command should look something like this:

bash$ cd /usr/src/linux

And then do:

bash:/usr/src/linux$ make-kpkg clean

And reconfigure your kernel:

bash:/usr/src/linux$ make xconfig

And then do:

bash:/usr/src/linux$ make-kpkg --revision=custom.2.0 kernel_image

7. Checklist

  1. Install dependencies

    1. kernel-package, dpkg-dev, debianutils, libc6-dev, gcc, make, kernel-source-x.x.xx, binutils, task-tcltk-dev or libncurses5-dev, bin86 (pc's only)

  2. Setup source tree.

    1. If not already, add user to source. Use addgroup user group. Logout, Login.

    2. Use groups to confirm.

    3. Double check symlink.

  3. Configure kernel.

    1. Load old config file if available.

    2. make xconfig, menuconfig, oldconfig, config.

    3. Save config file somewhere else for later retrieval.

  4. Make kernel image.

    1. If this is a recompile check old revision # and make-kpkg clean.

    2. Do I have a boot floppy?

    3. make-kpkg --revision=custom.X.X kernel_image

  5. Install image.

    1. If this is a recompile mv /lib/modules/X.X.XX /lib/modules/X.X.XX-old if necessary.

    2. Hold package. echo "kernel-image-2.2.19 hold" | dpkg --set-selections

    3. Remove symlink.

    4. Backup kernel image, make another boot floppy.


8. Troubleshooting

Fixing make xconfig error. NEED to get this updated

bash:/usr/src/linux# make xconfig
rm -f include/asm
( cd include ; ln -sf asm-i386 asm)
make -C scripts kconfig.tk
make[1]: Entering directory `/usr/src/kernel-source-2.2.19/scripts'
cat header.tk >> ./kconfig.tk
./tkparse < ../arch/i386/config.in >> kconfig.tk
echo "set defaults \"arch/i386/defconfig\"" >> kconfig.tk
echo "set ARCH \"i386\"" >> kconfig.tk
cat tail.tk >> kconfig.tk
chmod 755 kconfig.tk
make[1]: Leaving directory `/usr/src/kernel-source-2.2.19/scripts'
wish -f scripts/kconfig.tk
Xlib: connection to ":0.0" refused by server
Xlib: Client is not authorized to connect to Server
Application initialization failed: couldn't connect to display ":0"
Error in startup script: invalid command name "button"
    while executing
"button .ref"
    (file "scripts/kconfig.tk" line 51)
make: *** [xconfig] Error 1

It turns out this is a normal security precaution in Debian. If you get this, the way to fix it, is to do this:

bash:/usr/src/linux# xauth merge ~user/.Xauthority

And then try it again:

bash:/usr/src/linux# make xconfig

Replacing user with the username you are logged in as. Do not put root there. Put your username. You may currently be logged on as root (in the terminal) but you should have logged into X-windows as a regular user.

Caution

There are some security issues to doing this. I don't know what they are, but I do know that there was a huge discussion about it on the debian-user mailing list. If you're worried about it check the archives.