Build your own distro

From LXF Wiki

Revision as of 14:21, 16 May 2007; view current revision
←Older revision | Newer revision→

Making your own customised Linux distro is simpler than you might think - and rewarding too. Mike Saunders dons his overalls and hard hat, ready to show you how...

Creating something, from a simple meal to a complex painting, is rewarding and satisfying - especially if you love the end result. The feeling of being in control, trying out new ideas and then seeing your goals realised can't be beat. This is one of the joys of computing, especially programming, with the open source world a constant generator of code, concepts and communities to build upon. And creating your own customised Linux distro, however difficult it may seem initially, is one of the best ways to combine creativity with technical learning.

Yes, you can build your own distro with specific branding, programs and other tweaks - and it's not as tough as you might imagine. In fact, by following the right procedures, it's quite simple. Over the next six pages, we're going to look at the methods, tips and essential knowledge required for constructing your own personalised distro, with a focus on modifying the hugely popular Knoppix Live CD. We'll also have plenty of other tips and guides for customising any Linux flavour. With so many distros available, though, why make another?

  • Choice: Maybe none of the other distros fit your needs exactly. Perhaps you like Knoppix, for example, but want to remove bloated program A, add in lightweight program B and have a funky penguin backdrop. You can create a distro with what you want, and where you want it.
  • Learning experience: Understanding how a distro fits together, what vendors do to tweak their distros, and the obstacles along the way is valuable knowledge - especially if you ever plan to help out with a distro project.
  • Advocacy: If you're promoting a Linux-only software project, and would like to demonstrate it to Windows users, creating a themed Live CD containing your app is ideal. Similarly, if you're just advocating Linux in general, you can build a distro with a strong focus on your goals.

We'll start by looking at how the pieces of a distro fit together, the customisations and changes you can make, and then get hands-on with a full overhaul of Knoppix. We'll also take a look at Morphix (a Knoppix variant, files for which are on the coverdisc) together some other options. So, roll up your sleeves and let's go!

Table of contents

How does Knoppix work?

In this guide we'll be focusing mainly on Knoppix, as it's one of the best distros for modifying. We'll be using it to create our very own LXF branded distro, with our choice of software, branding and other specific touches. Additionally, as it's a Live CD you can see the results immediately - then later you can install it to your hard disk. Much of the information is applicable to other distros, though, and we've provided some guides if you'd rather take a different route.

As a Live CD (or DVD with version 4.0), the Debian-based Knoppix runs entirely in memory. No changes are made to the hard drive unless you explicitly request them. Recent Knoppix developments, such as the ability to save personal files to a USB memory key, have turned the distro from a mere demonstration to a full-blown distro in its own right. Here's how it goes from CD-in-drive to a graphical desktop OS:

  • Booting -- Initially, Knoppix starts up like any other distro - the bootloader prompt pops up, which then goes on to load the kernel. You can pass a number of options at the boot prompt to select different video modes or window managers. Once the kernel is revved up, the init scripts start their work, and this is where the first difference to a traditional distro should be noted.
  • Filesystem -- Whereas a normal distro mounts your filesystem and starts loading software from it, Knoppix uses a compressed loopback file. This is a single file which contains an entire filesystem, including /, /usr, /etc and all the usual suspects, and sits on the CD/DVD under the name 'KNOPPIX'. It is mounted via 'cloop' (compressed loop) which means the single file is opened up, and then effectively put into place as the root filesystem. Only the kernel knows this - to the user and software, it's just like a regular filesystem.
  • Desktop -- You can select the choice of desktop environment or window manager via the bootloader, but a couple of customisable things stay the same whatever you choose: the default HTML page and the background image. Changing those two is an instant way to give special branding for your distro - and in our walkthrough we'll show you how.

What we can change

Technically, we can customise every aspect of Knoppix, but some things are much more straightforward than others. The most immediately useful change to make, that of the software provided, can be achieved without (m)any nightmares thanks to the excellent Debian repositories on which Knoppix is built. You can remove packages, add new ones, and make changes to existing ones either with a full package build (requires a Debian system) or via the quicker method detailed in the box. Debian's package tools, apt-get and co, resolve dependencies automatically so you won't have to worry about broken software on your distro.

Aside from software, the other changes we can make straight away are in the cosmetic zone. This allows you to rebrand your distro with your own logos, desktop wallpapers and online help text. You can create a look and feel to your distro that's unique, without having to start completely from scratch. Lastly, we can make some technical changes to the underlying foundations of the distro - altering the startup scripts and configuration settings.

Simple .deb hacking

Knoppix and other Debian-based distros use .deb files for software packaging. These are usually generated from source code by a complex system of scripts; however, you can make quick changes to .deb files without all that hassle. This allows you to edit the contents (eg changing documentation or images) in a snap. Say you want to change the splash logo of the FooBar program with your own branding:

$ ar x foobar_1.2.3_i386.deb
$ tar xfvz data.tar.gz

This extracts the compressed data contents of the .deb package (data.tar.gz). With most programs, it'll produce a familiar directory tree containing usr/ and possibly others. (This is how files in the .deb's are placed on the system.) Jump into the resulting directories and hack away - eg edit a splash screen in usr/share/foobar/splash.png. Once done:

$ tar cfvz data.tar.gz usr/
$ ar r foobar_1.2.3_i386.deb data.tar.gz

The first line puts all the package's data files back into data.tar.gz - you may have to specify more than /usr if other directories were produced when you extracted earlier. The second squeezes it all back into the .deb file, ready for installing on your custom distro or redistributing!


Before we get going, you'll need to have a few things prepared beforehand. The most important of these is the Knoppix disc, which you can download from the project's website ( There you can grab the Knoppix 4.0 CD ISO image for burning to a CD-R. Note that as with all distros, you can't just copy the ISO file onto a CD - you need to burn it as a full disc image. Your favourite CD-writing software should offer you this option, but if not, you can use the trusty command line 'cdrecord' utility. See its man page for details on direct-to-disc burning.

Next up is the RAM requirements. At an absolute minimum, you want 128 MB, and even then some parts of the rebuilding process will be slow. This isn't a crisis; you can leave it running overnight if it's taking a while, but the more RAM you have the better. The rebuilding process actually requires 1 GB of memory, but you can make that up by adding virtual memory (swap) on top of your real RAM. It should be noted here that you /can/ use the Knoppix DVD, as supplied on last month's coverdisc, but the RAM requirements for editing that are 5 GB - out of reach for most of us.

Lastly, you'll need some free space on a Linux partition on your hard drive. This can be a freshly formatted partition, or one you currently use, such as / or /home. For the CD, you'll need 3 GB free, and for the DVD, you should have a whopping 15 GB. So, once you have the disc, a healthy supply of RAM and plenty of free disk space, you're ready to go. Over the page we'll go through the customisation process step-by-step, detailing the exact commands to be entered from start to finish. In the words of Mario, let's-a go!

Modifying any distro

Almost any distro can be altered and customised, providing you have the know-how. You may have noticed that the distros we feature on our coverdiscs are always modified slightly - the actual distro contents haven't been changed, but we tweak the disc layout to add our HTML menus and additional software. Most recent distros adhere to a sensible layout and design, so rebranding and altering them isn't too taxing.

Your first step is to get the ISO image file(s) of the distro. Say, for instance, you have the ISO that makes the Ubuntu CD, either by downloading it or via 'dd if=/dev/cdrom of=discimage.iso' from a real disc. With the 'loopback' mount system, you can access the ISO file as if it was an actual CD in the drive. This is achieved with the 'loop' option to mount:

$ mount -o loop -t iso9660 discimage.iso /mnt/loop/

After this, in /mnt/loop you have the contents of the disc, just as if you'd written it to a CD-R and mounted it normally. You can then copy the entire contents of /mnt/loop to a temporary folder, recursively make all the files writable ('chmod -R +w *') and then hack away. The methods for changing packages and editing startup scripts vary from distro to distro - consult its docs first.

Once you've made your changes to the copied disc contents, you're ready to assemble them back into a disc image with 'mkisofs'. The most crucial point to consider is making the disc bootable; most distros use isolinux, so you'll need to give mkisofs the right options:

mkisofs -rdlJ -allow-leading-dots -hide-rr-moved -dir-mode 555 -p "preparer" -publisher "publisher" -A "Disc name" -V VOLNAMe -o output.iso -b isolinux/isolinux.bin -c isolinux/ -no-emul-boot -boot-load-size 4 -boot-info-table disc_contents/

This produces the 'output.iso' file to be burned to disc, generated from the files in the 'disc_contents' directory. For a bootable disc, the filenames following the -b and -c options may need to be changed depending on your distro. See the manual page for mkisofs ('man mkisofs') for all the details. When this is done, you'll have a distro CD similar to the original, but with your own alterations.

Step-by-step guide

1. Starting Knoppix and making space

Drop your Knoppix 4.0 CD into the drive, restart your PC and set it to boot from the CD drive. (This can usually be achieved by hitting F1, F2 or Del when the PC starts, and then changing the boot device order in the BIOS settings.) After the distro has started up, you should land at a KDE desktop. As all the work is done in the terminal, you can select a different desktop or window manager at boot time - in fact, this is a good idea on low memory machines. Fire up a terminal window (in KDE, K menu > KNOPPIX > Root Shell).

First you should make sure your Internet connection is working. You can configure networking either with the traditional command-line tools, or via K menu > KNOPPIX > Network/Internet. Following this, mount the hard drive partition you prepared earlier, making sure it has 3 GB of free space, and create a temporary working directory on it:

$ mkdir /mnt/drive
$ mount -rw /dev/hda1 /mnt/drive
$ mkdir /mnt/drive/knoppix-tmp

Note: you may need to change 'hda1' in the second line to 'hda2', or whatever the number is of the partition you prepared. Also note: you must mount it read+write (-rw option).

2. Swap space and copying files

As mentioned, you'll need 1 GB of memory (real plus virtual). If you have less than 1 GB of real RAM, create a swap file for virtual memory - here we make a 750 MB one to add to our 256 MB of real RAM:

$ cd /mnt/drive/knoppix-tmp
$ dd if=/dev/zero of=swapfile bs=1M count=750
$ mkswap swapfile
$ swapon swapfile

Now make two directories for the Knoppix sources and your final CD, both containing folders called KNOPPIX. Then copy all the Knoppix distro files over, ready to modify (this may take a while):

$ mkdir -p /mnt/drive/knoppix-tmp/master/KNOPPIX
$ mkdir -p /mnt/drive/knoppix-tmp/source/KNOPPIX
$ cp -Rp /KNOPPIX/* /mnt/drive/knoppix-tmp/source/KNOPPIX
$ cp -ar /cdrom/boot /mnt/drive/knoppix-tmp/master/boot
$ cp /cdrom/index.html /mnt/drive/knoppix-tmp/master/
$ cd /cdrom && find . -size -10000k -type f -exec cp -p --parents '{}' /mnt/drive/knoppix-tmp/master/

(Note on the last line: on the DVD version you should use a size of 15000k, and copy the KNOPPIX2 directory with 'cp /cdrom/KNOPPIX/KNOPPIX2 /mnt/drive/knoppix-tmp/master/KNOPPIX/'.)

3. Jumping inside the distro

So now you've copied the Knoppix software into source/KNOPPIX, and additional support files for making the distro in master/. This is where the fun begins! Using the 'chroot' program, you can create a session inside the Knoppix copy - in other words, start using it like it was a standalone distro. 'chroot' means 'change root' and sets your root directory, /, to whatever you specify. So we're going to chroot into our Knoppix copy, allowing us to use and modify it like we were already running it:

$ chroot /mnt/drive/knoppix-tmp/source/KNOPPIX

After this, anything you change will affect how your final distro turns out. What you see as the '/' directory in this chrooted state is actually /mnt/drive/knoppix-tmp/source/KNOPPIX. If you want to add software from the Debian repositories, you'll have to set up networking:

$ mount -t proc /proc proc

Then open up a second root terminal window, so you're temporarily not in the chroot environment, enter this and exit (it can't be done in the chroot):

$ cp /etc/dhcpc/resolv.conf /mnt/drive/knoppix-tmp/source/KNOPPIX/etc/dhcpc/resolv.conf

4. Changing the software

Now you can start adding and removing software, via Debian's excellent apt-get tool. First, enter 'apt-get update' (NOT upgrade!) to update the package list. Then type 'dpkg-query -l' to get a list of installed packages - you can pipe this though a text pager for easier viewing with 'dpkg-query -l | less'. To remove a package, enter 'apt-get remove --purge packagename'. To install new packages from the internet, enter 'apt-get install programname'. Debian's software repositories are huge, so you can customise your distro as much as you like. For instance, to remove the Zile editor and install Nano:

$ apt-get remove --purge zile
$ apt-get install nano

Once you're done, enter 'apt-get clean' to remove cached download files.

5. Customising behaviour

With the software selection sorted out, it's time to poke around the system and modify other settings. In /etc/skel you can find default configuration files for new users (enter 'ls -a' to see them all). In /etc/init.d you'll find the startup scripts for programs, some of which are launched at boot time. You can add other scripts to /etc/rc5.d to load a program before X is started up. And of course, /etc itself is home to all manner of configuration files you can tweak to your liking - although if in doubt, it's best not to tamper with them.

While you're in the chrooted environment, you can test out X software by entering:

$ export DISPLAY=localhost:0

And then running the program. This makes X programs connect to and display on the already existing display, rather than try to find a running X server in the chroot. Some of the changes will have to be made outside of the chroot; as an example, we'll give the default background image our own lick of paint. Open up a separate root shell, and enter:

$ chmod +w /mnt/drive/knoppix-tmp/master/KNOPPIX/background.jpg
$ gimp /mnt/drive/knoppix-tmp/master/KNOPPIX/background.jpg

With this, you can edit the background picture, adding your own logo or designs. Of course, you can replace the file completely. The bootloader splash-screen is located in /mnt/drive/knoppix-tmp/master/boot/isolinux/logo.16 - you'll need the 'syslinux' package to edit it. Convert the format, edit and re-convert as follows:

$ cd /mnt/drive/knoppix-tmp/master/boot/isolinux ; chmod +w logo.16
$ lss16toppm < logo.16 > logo.ppm
$ gimp logo.ppm (save as 14 colour indexed GIF)
$ giftopnm < logo.gif > logo.ppm
$ ppmtolss16 < logo.ppm > logo.lss

Lastly, you may want to change the help file which pops up when some WMs/desktops start (such as the default KDE). This can be found in /mnt/drive/knoppix-tmp/master/index.html.

6. Remaking the compressed image

When you're finished with the changes, leave the chroot by entering 'umount /proc' and then hitting Ctrl+D. This will quit the chrooted session. You may want to have a quick peek around the directories you've just been working in, to remove temporary files. Now comes the penultimate major step: recreating the compressed filesystem image. In the 'How does Knoppix work?' section earlier on, we saw that the Live CD uses a compressed file representing a filesystem to store the software - so we have to recreate that:

$ mkisofs -R -U -V "filesystem" -publisher "MyName" -hide-rr-moved -cache-inodes -no-bak -pad /mnt/drive/knoppix-tmp/source/KNOPPIX | /usr/bin/create_compressed_fs - 65536 > /mnt/drive/knoppix-tmp/master/KNOPPIX/KNOPPIX

Phew. You can change the publisher name, but otherwise this command must be entered exactly to the letter. Depending on the speed of your machine, this could take some time to finish.

7. Build the final ISO

So here comes the big moment - making the final disc image. We'll construct the ISO image containing the customised Knoppix we made, ready for use or distribution. First, we need to update the MD5 checksums for the disc, which is important for integrity checking (ie making sure you don't hand out duff discs):

$ cd /mnt/drive/knoppix-tmp/master
$ find -type f -not -name md5sums -not -name -not -name isolinux.bin -exec md5sum '{}' \; > KNOPPIX/md5sums

Another large command follows, I'm afraid, but this is the very last - the command that constructs the ISO file itself. When this is complete, it's ready to burn to disc. This uses the 'mkisofs' tool to take our newly modified Knoppix files, mix in the bootable bits, and produce a disc image.

$ cd /mnt/drive/knoppix-tmp/master
$ mkisofs -pad -l -r -J -v -V "MYDISTRO" -no-emul-boot -boot-load-size 4 -boot-info-table -b boot/isolinux/isolinux.bin -c boot/isolinux/ -hide-rr-moved -o /mnt/drive/knoppix-tmp/mydistro.iso /mnt/drive/knoppix-tmp/master

When this completes, you'll have a shiny new ISO image of your distro in /mnt/drive/knoppix-tmp/mydistro.iso. You can then test it out by writing it to a CD-R, or alternatively give it a quick run-through in a PC 'emulator' such as VMware or QEMU. If all works well, you can then upload the ISO image somewhere, and share your hard graft with others.

Testing times

If you're going to start a project around your new distro, or hand it out to people, it's important to do a spot of testing first. This doesn't demand the massive QA procedures that the likes of Debian go through - after all, you're already using a very solid distro as your base. Nonetheless, it's worth checking that all the main software you installed works correctly, and that any changes you made to the lower-level components (such as the init scripts) don't cause any problems. If you're handing out the CD to advocate using Linux, for example, you don't want to end up a 24x7 support team...

What if something's broken? Luckily, you don't have to go through the entire process again. If you still have the files on your hard drive partition, you can start up Knoppix again, mount the drive (step 1), add swap (step 2), and chroot in (step 3). After fixing any problems, you can rebuild the ISO with steps 6 and 7, and cross your fingers. If you have any Knoppix-specific problems, there's an excellent forum for getting help on customising Knoppix at Explain what you're trying to do, what went wrong, and someone should be able to help out.

Top five brain-wrongs

Avoid these when making a distro...

1. Lame name: While 'Joe's Hyper Plasma Spatula Orgasmix LiGNUx 0.54C3a1' may sound cool initially, it's a mouthful. Go for something snappy and rememberable like 'Plasma Linux 1.0'.

2. App tangle: Instead of suffocating the user in a squillion text editors, try to choose one good example of each program. In other words, Nano.

3. Inconsistency: If possible, stick to one toolkit, eg GTK ot Qt. Having multiple toolkits in use simultaneously will make the desktop look like a disjointed mess-tavern.

4. Themegraine: Endless bright colours may be OK if you're Bridget Riley, but chances are you're not. Opt for easy-on-the-eye instead of headache-inducing PlayBus lookalikes.

5. Distribandwidth: Find good hosting, or consider BitTorrent. Nothing miffs an intrigued potential user more than life-wastingly slow 5 k/sec downloads.

And that's it!

Hopefully, you've now got your own branded Linux distro, and have picked up some useful Linux knowledge along the way. There are many ways to go further, though - you can try Linux From Scratch (see the box) or join another distro project. Because of their organisation and politics, it's hard to get Debian or Fedora, for example, to make sweeping changes to their distros, but smaller projects are more adaptable and willing to try out new ideas. See to gauge which distros are scaling the popularity cliff.

Alternatively, if you plan to progress with your hand-rolled distro, and are looking for others to get involved, try posting to some newsgroups and/or forums around the net. The LXF website has an Announcements forum in which you can let others know of your plans, along with a busy Help forum where you can sort out any difficulties you may encounter. Who knows, your distro may even be on the magazine coverdisc someday... Good luck!

Scratching an itch

While Knoppix provides a straightforward route for customising a distro, there are plenty of other options if you want to dig deeper. Linux From Scratch (LFS) is a 'meta distro' - that is, it's not an installable Linux system in itself, but a framework and guide for making your own installation from the raw materials. This provides enormous scope for modifications and customisations, at the expense of more time and effort. Yet by doing everything from the start you learn a huge amount about the workings of Linux, and it gives you the opportunity to make even deeper changes. Many current distro developers started off by giving LFS a try, which then spurred on their interest in joining a project.

LFS is supplied as a set of source code tutorials along with an exhaustive online guidebook. You start by creating the bare-bones of a Linux installation from your current distro, adding piece-by-piece the necessary components to get it up and running (eg the compiler toolchain). Neatly divided into sections, the guide explains how to compile each program, and gives you plenty of scope to make your own tweaks. There's also BLFS (Beyond Linux From Scratch) which eases you into more advanced topics such as compiling the mammoth Gnome desktop. Pop over to to find out more.

The Morphix alternative

Morphix is a Live CD based on Knoppix (so therefore based on Debian too), which sports a rather spiffy customisation system via a GUI. Some work at the command line is still required, but most of the tweaking and tuning can be done through a graphical interface. The software for this is called Intellibuild (commonly shortened to iBuild).

iBuild uses templates which allow you to select packages from the Debian repositories, and change other aspects of the distro such as the splash screen and startup scripts. To run it, you'll need recent versions of chroot, cloop-utils, Python, PyGTK, python-vte and mkisofs. As with Knoppix, you should have 3 GB of free space and 1 GB of memory (adding swap onto your real RAM).

First, install the iBuild package, either by building from source or installing the supplied .deb package. (If you receive errors, you may need to copy the files in src/iGui/ to /usr/lib/ibuild or wherever you configured it to install.) Then mount your Morphix disc, and as root:

cd ~ ; mkdir ibuild ; cd ibuild
mkdir -p prebuilt/mainmod ; cd prebuilt/mainmod
cp /mnt/cdrom/PATH/TO/BareX.mod.iso.bz2 .
bunzip2 BareX.mod.iso.bz2

Change 'PATH TO' in the 'cp' line to where BareX.mod.iso.bz2 is on the disc. Now we need to make some working directories, and copy over the files from the Morphix Base image. Make sure you've downloaded the Morphix ISO image (MorphixBase-0.5-pre5.iso) and enter:

mkdir -p ~/ibuild/prebuilt/base/temp
mkdir -p ~/ibuild/prebuilt/base/0.5pre5
cd ~/ibuilt/prebuilt/base
mount -o loop MorphixBase-0.5-pre5.iso temp
cp -a temp/* 0.5-pre5/.
umount /temp

Now, with the base Morphix files in place, and iBuild installed, you can run '' and get started. There are templates you can tweak, such as the 'fireflux.xml' in /usr/share/ibuild/config (or /usr/local/share/ibuild/config) which have the package set and cosmetic features pre-defined. When you're ready to go, hit Build in the bottom-right corner! You'll find the resulting ISO in the ~/ibuild/release/ directory.