= 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: debian-boot@lists.debian.org.

== Step 1. Kernel udebs ==

These must be built using the linux-2.6 source package. The [[https://kernel-team.pages.debian.net/kernel-handbook/ch-common-tasks.html#s-common-official|kernel handbook]] describes how to customise that. The kernel should be built with the following things built in:{{{
!!! Note: this is outdated !!!
initrd support
tmpfs
ext2}}}

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).