Customizing Knoppix

Versions currently supported

Currently this document is written for Knoppix 5.0.1 and Knoppix 5.1.1
It also works with FCCU v11.0 CD

It has to be updated for 5.1.1 as aufs replaces unionfs

Principle

Some Knoppix versions < 5.1 are based on Unionfs (cf here or there)
See this pageto discover and understand unionfs.
Knoppix since version 5.1 moved to aufs (another unionfs) but the principles are the same and is it worth to have a look to unionfs presentation anyway.

The goal of the setup is to get control on an environment constituted of an original Knoppix CD and a USB stick of our own.

Knoppix has already such setup foreseen but slightly differently.

Basic Knoppix CD boot ends up into an unionfs constituted of

• RAM (starts empty)
• Knoppix CD

so everything is modifiable on run-time but every reboots start again from fresh CD.

Knoppix has also the possiblity to create a script on a USB stick so that the setup becomes:

• Image on USB stick
• Knoppix CD

so everything is again modifiable but changes are kept across reboots.

The problem with such a solution is that the USB image tends to grow unavoidably with the inherent entropy of a system in use (mainly /tmp).

Here we will start from this setup but with the following layout:

• RAM (starts empty)
• Image on USB stick
• Knoppix CD

Now we combine advantages of both worlds: a fresh state at boot time but under our control.

Creation

knoppix.sh

USB stick will have to hold a customised version of the script available on the Knoppix under /usr/sbin/knoppix-image
Customised because this is the whole goal of the operation, customising a Knoppix without remasterising the CD-Rom
The script goes in the root of the USB stick and has to be named knoppix.sh, this is a must!
Here is the diff between the original knoppix-image and our knoppix.sh script:

• Handle my_own.img image
• Skip the main user menu
• Call unionctl by ourselves and reroute /home through unionfs

This is slightly different between Knoppix v5.0.1 and v5.1.1.
Here is for Knoppix v5.0.1:

--- knoppix-image	2006-04-23 00:19:38.000000000 +0200
+++ knoppix.sh	2006-08-16 11:19:04.000000000 +0200
@@ -49,7 +49,7 @@
 [ -z "$LANGUAGE" ] && export LANGUAGE
 [ -z "$CHARSET" ] && export CHARSET

-IMAGE="$1"
+IMAGE="$1/my_own.img"
 [ -n "$IMAGE" -a -f "$IMAGE" ] || { $DIALOG --title ERROR --msgbox "Usage: $0 imagefile" 8 55; bailout; }
 [ "`id -u`" = "0" ] || { $DIALOG --title ERROR --msgbox "$0 must be run as in admin mode." 8 55; bailout; }

@@ -213,7 +213,9 @@
 esac

 SELECTION=""
-if $DIALOG --title "$TITLE" --timeout 20 --defaultno --checklist "$DESC1" 22 75 4 home "$MENU1" on system "$MENU2" on overwrite "$MENU3" off init "$MENU4" on 2>"$TMP"; then
+
+#if $DIALOG --title "$TITLE" --timeout 20 --defaultno --checklist "$DESC1" 22 75 4 home "$MENU1" on system "$MENU2" on overwrite "$MENU3" off init "$MENU4" on 2>"$TMP"; then
+if true 2>"$TMP"; then
  # if $DIALOG --title "$TITLE" --timeout 20 --defaultno --checklist "$DESC1" 22 75 4 home "$MENU1" on 2>"$TMP"; then
  SELECTION="$(<$TMP)"
  rm -f "$TMP"
@@ -314,3 +316,15 @@
 fi
 ;;
 esac
+
+#Add /home between CD-ROM and RAM
+unionctl /UNIONFS --add --after /ramdisk --mode ro /KNOPPIX.IMG
+
+#Reroute /home via unionfs
+#Originally /home is a symlink to only the ramdisk as
+#there is no /home at all on the CD-ROM but we want to
+#have /home as union of ramdisk and our extra layer
+rm -f /home
+ln -s /UNIONFS/home /home
+
+#All My own customisation will be done from here:

Here is for Knoppix v5.1.1:

--- knoppix-image	2007-03-22 09:28:15.000000000 -0400
+++ knoppix.sh	2007-03-22 15:06:12.000000000 -0400
@@ -56,7 +56,7 @@
  case "$i" in
   -f*) FORCE="true" ;;
   -*)  $DIALOG --title ERROR --msgbox "Usage: $0 [-force] imagefile" 8 55; bailout ;;
-  *)   IMAGE="$i" ;;
+  *)   IMAGE="$i/my_own.img" ;;
  esac
 done
 
@@ -227,8 +227,8 @@
 
 SELECTION=""
 [ -n "$FORCE" ] && AUTO="--timeout 10" || AUTO="--timeout 20 --defaultno"
-$DIALOG --title "$TITLE" $AUTO --checklist "$DESC1" 22 75 4 home "$MENU1" on system "$MENU2" on overwrite "$MENU3" off init "$MENU4" on 2>"$TMP"
-RC="$?"
+#$DIALOG --title "$TITLE" $AUTO --checklist "$DESC1" 22 75 4 home "$MENU1" on system "$MENU2" on overwrite "$MENU3" off init "$MENU4" on 2>"$TMP"
+RC="0" > $TMP
 if [ "$RC" = "0" ] || [ "$RC" = "255" -a -n "$FORCE" ]; then
  SELECTION="$(<$TMP)"
  rm -f "$TMP"
@@ -329,3 +329,17 @@
 fi
 ;;
 esac
+
+#Add /home between CD-ROM and RAM
+#unionctl compatible script is wrong so we use aufs natively
+#FYI unionctl /UNIONFS --add --after /ramdisk --mode ro /KNOPPIX.IMG
+mount -o remount,add:1:/KNOPPIX.IMG=ro /UNIONFS /UNIONFS
+
+#Reroute /home via unionfs
+#Originally /home is a symlink to only the ramdisk as
+#there is no /home at all on the CD-ROM but we want to 
+#have /home as union of ramdisk and our extra layer
+rm -f /home
+ln -s /UNIONFS/home /home
+
+#All My own customisation will be done here

When later we will boot from the Knoppix CD, by giving the "myconf=scan" argument on the boot line, the CD will look for... a script called knoppix.sh
From this script we mount a filesystem image with our changes, the image is an ext3 fs and the file is at the root of the USB stick, named my_own.img

my_own.img

Name can change but must be adapted consequently in the knoppix.sh script.

To create the image my_own.img:
Create an empty file of the right size (here 10Mb)

$ dd if=/dev/zero of=my_own.img bs=1024 count=10240

Format it as ext3 (say yes when the system points out that you are about formatting a file instead of a partition)

$ mkfs -t ext3 my_own.img

Mount it in loopback mode somewhere (here /media/disk) as root

# mount -o loop my_own.img /media/disk

Place a file so we will be able to check if everything went right at next step:

# mkdir /media/disk/etc
# echo test > /media/disk/etc/my_own.txt

Umount the loopback image

# umount /media/disk

Reboot on the Knoppix with the boot command

knoppix myconf=scan

Now you can check the existence of a file /etc/my_own.txt, this will be the proof everything went well up to now.

Customisation

You can check the status of the unionfs we got so far by typing

# unionctl --list /UNIONFS

• /UNIONFS is the merged view through unionfs and, by symlinks, most of the view you get from / (try ls -al /)
• /ramdisk is the RAM layer, everything you do on / or /UNIONFS goes to RAM and will be lost next reboot, be careful!!
• /KNOPPIX is the read-only content of the CD, mounted through a decompression layer (that's how you get gigs of files on a CD)
  If you boot from the DVD there is also a /KNOPPIX2, this is just because the DVD filesystem could not hold files of more than 2G (they are under /cdrom/KNOPPIX/)
• Between /ramdisk and /KNOPPIX is /KNOPPIX.IMG, this is our customisation layer.
  Through unionfs, this layer is set as read-only so all modifications will always go to RAM.
  To modify stuffs in the customisation layer, you have to do it via /KNOPPIX.IMG which is mounted with r/w accesses

So, a priori, every new or changed file has simply to be inserted in the /KNOPPIX.IMG layer

Exceptions

Note that unionfs seems to feature a caching system because sometimes changes done via /KNOPPIX.IMG do not appear through unionfs and a reboot could be required

/home

This directory is not present on the CD and is created on-the-fly.
Originally it is even not part of unionfs but only in /ramdisk but our knoppix.sh script rerouted it through unionfs.
So adding new files can be done simply by adding files (! owner and permissions) to /KNOPPIX.IMG/home/knoppix.
Modifying file to be created later on-the-fly is much more tricky.
These modifications have to be done via the knoppix.sh script.
We have first to understand when the knoppix.sh is executed:
The script is called by /etc/init.d/knoppix-autoconfig but most of the /home will be created later, by /etc/X11/Xsession.d/45xsession from /etc/skelfrom /etc/skel, /etc/sysconfig and /usr/share/knoppix and from the script itself.
One way could be to simply replace the 45xsession script by ours but this would break probably any tentative to run the next Knoppix version with our setup so it is better to change as few things as possible.

Drivers

Hardware was already discovered and drivers were already loaded when our script is called.
Depending of the driver some specific actions will have to be taken.
The driver must be compiled for the kernel used in the Knoppix CD.
For version 5.0.1 the kernel tree of the CD is broken and for version 5.1.1 the headers are even not present so if this is not impossible to compile a driver from the CD this is extremely challenging.
The DVD version contains the full kernel source tree so drivers should be compiled against the DVD (which runs the same kernel), this will save a lot of effort.

• The driver file should be copied to /KNOPPIX.IMG/lib/modules/...
• A call to depmod is required to generate new symbol tables and those will have also to be copied to /KNOPPIX.IMG/lib/modules/...
• If the driver did not exist on the CD, then we can simply load manually the driver with a modprobe from our script.
• If the system relies on udev to set automatically some rights or whatever and if udev rules were added, then it is wise to restart udev from knoppix.sh script so that next time the hardware is plugged these rules will be effective.
• If the driver is an updated version of an existing driver on the CD then things are slightly more complex with unionfs (note that this is solved with aufs):
  All drivers loaded during the boot are copied for a mysterious reason to /ramdisk
  So before calling depmod, better first to overwrite the old driver with the new one in /ramdisk
  The procedure will then be, from the knoppix.sh script: rmmod the driver, overwrite the old version with the new one in /ramdisk, modprobe the new one.

Exception examples

New driver

Here this is the case of a new driver, not available on the original Knoppix CD
Install the compiled driver under /KNOPPIX.IMG/lib/modules/2.6.17/kernel/drivers/...
Execute depmod and copy new /ramdisk/lib/modules/2.6.17/modules.* to /KNOPPIX.IMG
If there are configuration files, simply copy them to /KNOPPIX.IMG/etc
E.g. /KNOPPIX.IMG/etc/udev/rules.d/my_driver.rules

Then, we have to append the following to our knoppix.sh script:

• restarting udev so that it is aware of the new driver (for subsequent hotpluggings of the hardware)
• loading manually the driver (in case the hardware was already plugged when the Knoppix booted)

# My driver
/etc/init.d/udev restart
modprobe my_module

New shared library

Install the new lib and its symlink under /KNOPPIX.IMG/usr/local/lib
Regenerate the lib cache with ldconfig and copy it from /etc/ld.so.cache to /KNOPPIX.IMG/etc/

Fixing a driver

Here this is the case of a driver available on the original Knoppix CD v5.0.1 but not with the last firmware update (rendering the driver unusable): ipw2200

Install the last firmware under /KNOPPIX.IMG/usr/lib/hotplug/firmware/ipw2200-*.fw

Then we have to append the following to our knoppix.sh script:

• Simply force reloading of the driver, which will look again for its firmware

# ipw2200 driver
if lsmod | grep -q ipw2200; then
   rmmod ipw2200
   modprobe ipw2200
fi

This is solved on v5.1.1 so this example is here just for... the example.

Upgrading a driver

Here this is the case of a driver available on the original Knoppix CD but we want e.g. to upgrade it or use a patched version.
As said before, when using unionfs all drivers loaded during the boot are copied to /ramdisk so as we want to update them, we better have to update those in /ramdisk as well.
Install the compiled drivers under /KNOPPIX.IMG/lib/modules/2.6.17/kernel/drivers/... and /ramdisk/lib/modules/2.6.17/kernel/drivers/... and binaries under /KNOPPIX.IMG/usr/local/bin
Execute depmod and copy new /ramdisk/lib/modules/2.6.17/modules.* to /KNOPPIX.IMG

Then we have to append the following to our knoppix.sh script:

• Copy the driver to /ramdisk as well
• Force reloading of the updated driver

# my new version of driver
# Note that loaded drivers were copied also to /ramdisk so we need to change them there
if lsmod | grep -q old_driver; then
   rmmod old_drivers...
   /bin/cp /KNOPPIX.IMG/lib/modules/2.6.17/kernel/drivers/net/* /ramdisk/lib/modules/2.6.17/kernel/drivers/net/
   modprobe new_driver
fi

With aufs you don't need to do so!
Just rmmod + modprobe the module

Background customization

This is a good example of the said tricky changes to perform in the /home
Creation of the background has to be tracked in the booting scripts to understand where and what to change.

We put our new background in e.g. /home/knoppix/resources/my_background.png
Then we have to append the following to our knoppix.sh script:

# Customize background
# This is tricky, /etc/init.d/knoppix-autoconfig defines $BACKGROUND
# in /etc/sysconfig/knoppix
# Then knoppix-autconfig is calling us
# and later /etc/X11/Xsession.d uses the value
# to patch /home/knoppix/.kde/share/config/kdesktoprc
# so we modify /etc/sysconfig/knoppix
sed -i 's#^BACKGROUND=.*#BACKGROUND="/UNIONFS/home/knoppix/resources/my_background.png"#' /etc/sysconfig/knoppix

Software

We could install the Debian package but this means having to bring the new dpkg caches to the USB stick too.
For small stuffs this is much easier just to extract the soft from the Debian package and install it in /usr/local -> /KNOPPIX.IMG/usr/local/bin/my_soft (and the man page...) This is better to take it from the real Debian package as you benefit from the version control of dpkg and are sure you install a version compatible with the rest of the CD.

Help

Originally Knoppix prompts the user with an html help file open in a browser.
To hook our own file instead we do the following:

• We put our own help page under /home/knoppix/resources/help.html
• We change the icon on the desktop /home/knoppix/Desktop/Help.desktop

[Desktop Entry]
Name=CERTIFICATION HELP
Exec=konqueror --geometry 850x600+85+70 file:/UNIONFS/home/knoppix/resources/help.html
Type=Application
Icon=html
Terminal=0

• We make sure the help file will be automatically open

ln -s /home/knoppix/Desktop/Help.desktop /KNOPPIX.IMG/home/knoppix/.kde/Autostart/showindex.desktop

Misc icons

Icons positions can be defined in /KNOPPIX.IMG/home/knoppix/.kde/share/apps/kdesktop/IconPositions
Only position of new icons is required.
Additional icons useful to get on /KNOPPIX.IMG/home/knoppix/Desktop:
E.g. ethereal shortcut: "Exec=sudo ifconfig ath2 up; sudo ethereal -i ath2 -k -S -l"