Getting in deep with dfsbuild

Posted by malcolm on Sun 29 May 2005 at 03:55

Steve's article Building Debian CD-ROMS Part 1 - dfsbuild convinced me that dfsbuild was the tool to put together a rescue CD for my laptop. The default configuration wasn't quite what I wanted, as my wireless card needs a patched kernel. I also needed to include some extra files so that networking would work "out of the box".

Making it happen involved getting elbow deep in the code that makes DFS work. As the DFS documentation doesn't cover these things, I thought I'd share what I found.

How to include extra files

The [createfiles] and [appendfiles] sections of the DFS config file dfs.cfg let you specify text to add to files on the CD image. Unfortunately, you can't include blank lines, or the characters "=" or ":". There's also no way to copy binary files to the image (I contacted DFS' author John Goerzen and now there is a wishlist bug #308876 filed about these limitations).

Luckily, there was another way to change the files included on the CD.

Modifying the CD image

When dfsbuild has finished, it doesn't erase the directory containing the files for the CD image. The root of the CD filesystem is the directory image under wdir, the dfsbuild working directory.

As long as you have specified the option compress = no in dfs.cfg, you can modify the files here to your heart's content before rebuilding the CD image.

If you want an i386 boot CD, the command to build an ISO image dfs.iso is
cd wdir
mkisofs -b boot/grub/stage2_eltorito -no-emul-boot -boot-load-size 1 -boot-info-table -pad -R -o dfs.iso image
If you need a compressed image, you can still create one. Use the mkzftree command and then run mkisofs with the "-z" flag.

Using a custom kernel

I built my custom kernel using make-kpkg, so I included it on the CD using the unpackdebs command in dfs.cfg. Like the standard Debian kernels, my kernel boots using an initial RAM disk initrd.

It turns out that DFS has its own special initrd, and that the initrd from the kernel package is ignored. This means that your kernel should have built-in drivers for mounting the root file system from the CD, not modules (i.e. iso9660 and any necessary IDE/SCSI drivers).

This didn't present a problem for me, so after adding a few key files and running mkisofs, I had a working DFS CD for my laptop.

Actually, that's a lie. Once I discovered that DFS had its own initrd, I had to satisfy my curiosity about what DFS was doing under the hood before I could go on with building my CD.

More DFS internals

The directory structure under image is the familiar Debian one. DFS has its own directories under /opt, including the RAM disk used for writable files once the system is running.
# RAM disk mount point
/opt/dfsruntime/runtimemnt
# files and directories to copy to the RAM disk
/opt/dfsruntime/runtimerd
The initrd image that mounts the root filesystem from CD and bootstraps the system is included at /opt/dfsruntime/initrd.dfs. You can inspect the contents of the initrd by mounting the image
cd wdir/image
mount -t cramfs -o loop opt/dfsruntime/initrd.dfs /mnt
One thing to note is that DFS' startup scripts are binaries. The DFS components and dfsbuild itself are written in the compiled functional programming language OCaml. The initrd startup script /sbin/init performs the equivalent of the following shell commands:
mount -n -t iso9660 -o ro cd_dev /realroot
cd /realroot
pivot_root . initrd
chroot .
# run the main DFS startup script
/opt/dfsruntime/startup
The main DFS startup script /opt/dfsruntime/startup completes the process with the following operations:
umount -n /initrd
mount -n -t tmpfs none /opt/dfsruntime/runtimemnt
cp -a /opt/dfsruntime/runtimerd/* /opt/dfsruntime/runtimemnt
echo "proc  /proc   proc    defaults        0 0\n" >/etc/fstab
# start the normal Linux init process
/sbin/init
As you can see, the operation of DFS is quite simple. DFS, bootcd and the various installer projects all have their strengths and weaknesses, so I expect there'll be some productive cross-fertilisation between them as they evolve.

This article can be found online at the Debian Administration website at the following bookmarkable URL:

http://www.debian-administration.org/articles/149