Debian-Installer: Building images with a custom kernel

So you want to build a custom version of DebianInstaller? This page assumes basic familiarity with building Debian packages and the linux kernel from source. The techniques described here are aimed mostly at replacing the kernel, which is the most common piece to need to replace, but similar techniques can be used to replace any other udeb used by this modular installer with a custom version.

Note: these instructions have been updated to describe building udebs from the linux-2.6 source package, but have not yet been tested. If they work for you, please remove this note.

If you have questions about this document, mail the Debian Installer team at:

Step 1. Kernel udebs

These must be built using the linux-2.6 source package. The kernel handbook describes how to customise that. The kernel should be built with the following things built in:

!!! Note: this is outdated !!!
initrd support

Most everything else can be modular, and it's a good idea to enable pretty much everything.

If your custom kernel includes new kernel modules that are not in the standard kernel, you'll need to add them to a list in debian/installer/i386/modules/i386/. See the kernel-wedge documentation for details.

Step 2. Initrds and images

Unpack the debian-installer source package. Make sure the many build dependencies are satisfied. Check that build/config/i386.cfg has a KERNELVERSION field that matches the version of your custom kernel (other arches, replace i386 with your arch). Note that this version includes the kernel flavour. For example, if your kernel-image*.udeb produced in the previous step is named kernel-image-2.6.18-1-486-di_0.57_i386.udeb, then set KERNELVERSION to 2.6.18-1-486.

Copy the udebs that were produced in step 2 into the build/localudebs directory. Go to the build directory and type make list to see a list of possible targets. For example, if you want to build a mini.iso netinst image, use this command:

fakeroot make build_netinst

If you're looking to build a complete Debian CD, the target to use is build_cdrom_isolinux (and see step 3).

It turns out to be much easier to build a mini CD containing just d-i, which you can do with the build_monolithic target (after editing config/i386.cfg and uncommenting the monolithic image type from the first line).

You will need a network connection to install using this image.

Look in the build/dest directory for the images. The MANIFEST file will list every file you built and its purpose. Note that the build_cdrom_isolinux target does not produce an entire ISO image, but just the initrd to go on one. However, the build_monolithic target does produce a bootable ISO image, and the floppy targets do produce floppy images.

Step 2.5. Installing Your Custom Kernel on the Installation Machine

If you would like to install your custom kernel on the machine you've built your modified Debian Installer for, you can do the following. First, you'll need access to your kernel deb from Step 1. Options include thumb drives that you mount or on web servers that you access with wget. At the end of the installation process, after the GRUB install but before reboot, open a virtual terminal, get the kernel deb, chroot into /target, and install the kernel deb manually with dpkg -i. Finally, reboot.

Step 3. Building a full Debian CD image

If you have an initrd for a CD, and some kernel udebs, and a kernel deb, you probably want to stick them all on a Debian CD. There are two ways to do this. You can install the debian-cd package and read its documentation. Be warned that using debian-cd is difficult, and requires a local Debian mirror. Or you could try to remaster an existing Debian ISO using the technique described on DebianInstaller/Modify/CD.

Neither of these routes will be as relatively polished or easy as steps 1-3. We recommend that you don't try to build a full Debian CD unless you really absolutely need one, and have plenty of time to set up debian-cd. An alternative is to build a monolithic mini iso (as described in step 3).