Knoppix Custom Kernel Howto

From Knoppix Documentation Wiki
Jump to: navigation, search

by "Daniel R. Tarsky" <>

3.3 comments by Marc Haber <>

3.6 comments by Rich Ercolani <>

PREFACE provides excellent instructions for remastering your own projects at: Knoppix Remastering Howto

This document is a supplement to the Remastering Howto. In is in no way a replacement for it.

Booting Knoppix is proof that a synergy can be found between complex shell scripts and just turning on a computer and having it run. Most of the complex hardware autodetection is abstracted away from the shell scripts so you are left with a clear view of what can be modified, extended, or maybe just better left alone.


The Linux kernel in Knoppix 3.1 (12/12/2002) is a vanilla 2.4.20 kernel with xfs and a patch included on the CD which extends the amount of boot parameters possible. The knoppix kernel patch also makes changes for the initial ramdisk, which I am not too sure of. What I am sure of is the kernel seems to expect an initrd image of a specific size, so any changes I have been successful with making have only been in a copy of the original miniroot image. I started with a vanilla 2.4.20 kernel as well, but it's possible the patch can be applied to a different kernel version, or to just read the patch file and apply the changes by hand. It's only about a six-line patch.

Zug Schlus adds: The Linux Kernel in KNOPPIX 3.3 (2003-11-19) is a 2.4.22 with XFS patches. The command line buffer patch is included on the KNOPPIX CD in /usr/src and is the only patch that is really necessary. The later kernel seems to be able to cope with different miniroot sizes, as I have never had any problems with rebuilt miniroots.

Rincebrain adds: The Linux kernels in KNOPPIX 3.6 (2004-08-16) are 2.4.27 with the aforementioned patches, and 2.6.7, with apparently only a patch to modify boot arguments(?). Also, in 3.6, isolinux is used instead of the first solution mentioned in this HOWTO, so the kernels can be found at boot/isolinux/linux24 and boot/isolinux/linux26, respectively, and the miniroots can be found at boot/isolinux/minirt24.gz and boot/isolinux/minirt26.gz for 2.4 and 2.6 kernels, respectively. Experience with compiling one's own kernels and applying patches is suggested for making one's own KNOPPIX 3.6-based CD.

The startup scripts are critical and expect specific things to be available in the kernel (or as modules) in order for Knoppix to boot correctly. I will go over them in detail later on.


Zug Schlus adds: The Knoppix Remastering Howto now contains a script that mounts and unmounts the boot floppy and the initrd image automatically. So you just need to invoke that script, and you're set to go without having to follow the detailed instructions below.

At this point you should already have Knoppix copied off of your CD and in source and master directories on a hard drive. In addition to making the source and master partitions (from now on I'll just call them source and master directories because I just made two directories on one partition: /mnt/hda1/source and /mnt/hda1/master.) you will also want to make two folders on the root of this partition: boot and mroot. This will leave you with a partition having four folders: master, source, boot, and mroot. The first two you should already be familiar with. 'boot' will be where we will mount the boot.img file, and 'mroot' is where we will mount miniroot.gz, which is contained within the boot.img file. Are you with me so far? Good! Let's get started..

First of all, copy master/KNOPPIX/boot.img (or boot-en.img if you want english default keyboard settings) to the root of your partition, where the four folders above reside. Stash a copy away somewhere or make a boot.img.old. Sure, you still have a copy in master/KNOPPIX, but wasn't the one you just overwrote it with broken? oops! Hopefully you still have the original CD if things get too hairy. :)

Now for the fun part: 'mount boot.img boot -t msdos -o loop=/dev/loop0' will mount the boot floppy in the boot folder. Next, 'cp boot/miniroot.gz .', 'gunzip miniroot.gz', and 'mount miniroot mroot -t ext2 -o loop=/dev/loop1'.

Now we have the boot floppy with the original kernel, miniroot.gz, and config files in the boot folder. I suggest copying any other files you wish to modify to the root of your dev partition as well, or maybe make a bak or tmp folder to store your backups in. From here on, I will just assume you are backing up all original files and not bug you any more about it. Just be aware of what exactly you have modified on your boot floppy, and don't forget to unmount it before copying it back to your master folder.


Do not apply the knoppix-kernel patch until you have finished all kernel configuration. If you need to go back and tweak your kernel configuration later on, you will need to re-apply the knoppix-kernel patch after you save your new configuration and before you begin building your kernel. This is because the kernel patch makes changes to setup.c, which saving a new configuration can often overwrite.


When Knoppix boots, it loads the kernel from the boot floppy (which is really a floppy image on your CD which syslinux boots with floppy emulation) and then gunzips and mounts miniroot as a bare-bones root to begin booting the system with. What is interesting about miniroot is that it is the actual root environment for Knoppix. It only contains enough software (or 'brains') to find the compressed system image on the CD, mount it, and make all the rest of the important stuff available such as /lib, /etc and /usr for a normal boot process to occur. The only real directories are /cdrom, /etc, /mnt, /modules, /proc and /static. Everything else is symlinked to /KNOPPIX, which is where the compressed system image will be mounted once miniroot does it's job.

Aside from the symlinks, /modules and /static stick out as non-traditional directories. /static is where the special statically-linked ash shell resides, which also doubles as init and modutils. When miniroot is mounted as a boot/root environment, the kernel executes the linuxrc script on the 'root' of miniroot with the static ash-knoppix. Because ash-knoppix (or 'init' in this context) is statically linked with modutils, you may also need to recompile ash-knoppix to upgrade your modutils for any newer kernel versions that may require them. This is of course in addition to installing the new modutils in your Knoppix image source directory. The only modules in the /modules folder are the cloop module for the system image, and scsi modules in case you happen to boot your CD from a SCSI CD-ROM. If you don't need SCSI support or you don't need to boot from a SCSI CD-ROM, you can safely remove the scsi modules. If you do so, be sure to comment out the 'SCSIMODULES=' section of linuxrc and replace it with a dummy: SCSIMODULES="" so the script will skip SCSI autoprobing.

The cloop.o module must also be re-compiled for the new kernel you are installing. be sure to replace the existing one in /modules.

As linuxrc executes, it attempts to mount the base CD on /dev/hd1-99 and /dev/scd1-99, which means it has a pretty good chance of finding it. At this point the whole filesystem is still in ram, so the CD must first be mounted to get to the compressed /cdrom/KNOPPIX/KNOPPIX image file. Once the CD has been mounted, a second ramdisk is created with a dynamic size dependent on available and free memory which will be used for home directories and /var. Finally, cloop.o is loaded into the kernel and the compressed system image is mounted on /KNOPPIX, making all the symlinks work as part of the root filesystem. Next, more symlinks are created and important system files are copied to the ramdisk so they can be written to if need be. See the linuxrc script for specifics.

Zug Schlus adds: KNOPPIX 3.3 supports the boot options "toram" and "tohd" which copies the cloop image to a RAM disk or to a physical disk, freeing the CD ROM drive in the process so that it can be used from KNOPPIX with other CDs. The linuxrc script in the miniroot takes care of that as well. The toram features needs at least a Gig of RAM, so it is most useful when used with a custom KNOPPIX version that has most of the packages removed. It is extremely handy to have a 50 MB text-only KNOPPIX as a rescue system that fits nicely on a business card CD. Just be sure to keep the ash package installed since linuxrc uses the presence of /KNOPPIX/bin/ash to determine whether this is a CD boot or a boot from a HD-installed KNOPPIX version.

Once linuxrc is finished, it gives control back to the kernel init process which in turn starts running the rc boot scripts, most notably knoppix-autoconfig.


At this point, you probably have a pretty good idea where the kernel goes now, but let's just recap: your new kernel will replace vmlinuz in the boot directory you've created on your dev partition which contains master and source folders; boot and mroot folders. Replace the cloop and scsi modules in mroot/modules with whatever drivers you may need to get to the compressed system image and make any changes necessary in mroot/linuxrc to handle changes you may have made in the kernel or modules.

Now that all your modifications have been made to the miniroot and boot image which contains it, you are safe to 'umount mroot' (unmount miniroot), 'gzip miniroot' (recompress it), 'rm -f boot/miniroot.gz' (delete the original from the boot image), and 'cp miniroot.gz boot' to replace it with your modified miniroot. Now you are free to edit the boot message in boot/boot.msg or any boot parameters in boot/syslinux.cfg. When you are done, just 'umount boot' and copy your new boot.img to master/KNOPPIX. You can still leave the original if you wish. The actual boot image the CD boots from is specified when you run mkisofs to create your new CD image.

Zug Schlus adds: The script given in the Knoppix RemasteringHowto automatically re-builds the miniroot.gz after zeroing out the unused parts of the image. It will also automatically unmount both images and run syslinux on the new boot.img.


There are many alternative ways to boot. My Knoppix-based project in particular uses isolinux instead to bypass the need for floppy emulation, and also to take one of the layers of redundancy out of modifying the boot/miniroot scenario I have described above. ISOLINUX is made by the same people who made SYSLINUX and PXELINUX, so the Knoppix boot process can be easily adapted to use one of these other options. I will use my ISOLINUX experience as an example to help show how much easier it can be.

In your master folder, create a folder called 'isolinux' and copy the contents of the boot image file (mounted in the boot folder) to master/isolinux. Now, all your boot files are easily accessed in the isolinux folder and you will not need to loop-mount a floppy image any more. It's good to keep a boot.img file somewhere on your CD though, in case somebody has trouble with isolinux. However, I have not seen any issues with isolinux on any relatively modern (or even older) hardware. Put isolinux.bin in the master/isolinux folder and remove ldlinux.sys. That's all you need to change as far as CD layout. Now the boot message and options can easily be tweaked without the constant mounting and unmounting of the floppy image.

ISOLINUX can be downloaded from the syslinux package at [1] Using the latest versions the configuration file needs to be called isolinux.cfg not syslinux.cfg:

mv isolinux/syslinux.cfg isolinux/isolinux.cfg

To make these changes be effective when you are imaging your new Knoppix CD, change the -b and -c options for mkisofs to '-b isolinux/isolinux.bin' and '-c isolinux/'. Also, you will need to add these command-line options: '-no-emul-boot -boot-load-size 4 -boot-info-table'

Borrowing from the Remastering-HOWTO, here is my modified final mkisofs command after making the compressed image:

mkisofs -pad -l -r -J -v -V "Custom KNOPPIX" -b isolinux/isolinux.bin -c isolinux/ -hide-rr-moved -no-emul-boot -boot-load-size 4 -boot-info-table -o /some/where/myknoppix.iso /mnt/hda1/master

That's it! Now your boot environment is a bit easier to maintain, and your kernel can be any size you like. Now the only thing you have to mount with the loop device is miniroot when you need to change things in it. If you don't need the scsi modules, chances are you will only need to replace the cloop module after kernel replacements.


This document has hopefully shed some light on the somewhat esoteric process of replacing the stock Knoppix kernel with a custom kernel. Chances are if you are replacing the kernel, you are also going to be hacking around with the knoppix scripts, so here are a couple of things I have learned:

When Knoppix is running, it expects /KNOPPIX to exist. When you are chrooted to your source directory however, there is no /KNOPPIX. Solution: 'ln -sf / /KNOPPIX'.

If you are hacking on /etc/init.d/knoppix-autoconfig, you may want to run the script from your chroot dev environment rather than re-writing a CD and booting it. Unfortunately, running knoppix-autoconfig from your source directory may also cause a small issue when you decide to compress source/KNOPPIX and boot from your new CD
autoconfiguration will stick with whatever config files knoppix-autoconfig previously wrote. Yes, I have unwittingly made a custom Knoppix CD for myself which is tailored only for my hardware. Not what I was going for! :) The solution is to remove everything in /etc/sysconfig while you are still chrooted (leave the directory /etc/network-scripts, but remove everything in it too) and to remove /etc/X11/XF86Config and /etc/X11/XF86Config-4. Leave the .in files, as they are used to dynamically generate the configs during boot. Here is a simple script I keep in source/KNOPPIX/cleanhouse (or the root of my chroot env as /cleanhouse) to clean up after hacking : !#!/bin/sh
rm -f /etc/sysconfig/ /etc/sysconfig/network-scripts/ /etc/X11/XF86Config /etc/X11/XF86Config-4 /var/cache/apt/archives/.deb /var/cache/apt/archives/partial/
rm -rf /KNOPPIX
depmod -a
umount /proc
exit 0

-- Knoppix-custom-kernel-HOWTO Generated 01/14/2003

See also kernel image, kernel panic


Research miniroot a bit more and see what kernel mods may be necessary to change it's size. Creating one that is anything but the original 3MB seems to end badly for me.

3MB limit explained:


explains why there is a 3MB limit (technically it's 2.88 mb) on the boot size. In short: A floppy can have a maximum size of 2.88 MB (if formatted accordingly). The El Torito standard allows booting from a CDROM by emulating a floppy or a hard drive. A floppy emulation must have an exact size. Some BIOSes (my guess is mostly older ones) do not support hard drive emulation. So if you want to avoid the 2.88 MB limit, use ISOLINUX. Depending on the age of your BIOS, this will work fine.

Update explanation to apply to 3.6 and beyond. The quick notes listed are just that.