build an OpenBSD Live-CD

This page describes how to build a Live-CD based on OpenBSD. There are already some tutorials available which describe this process, however here I explain how I did it. When I tried to follow some other HowTos I got stuck and that's why I summarised the method I used below.

If you find a mistake or have suggestions for improvement feel free to contact me.


Installing the base system

If you are not confident about the installation process have a look at the OpenBSD FAQ site. I created only one disklabel over the whole harddrive to avoid space problems on any disklabel while creating the Live-CD. This will not influence the Live-CD system since there will not be any disklabels on the CD-ROM anyway.

Adding application specific software

The next step is to install and configure all software that should be available on the Live-CD. Probably the easiest way to achieve this is to use packages, but any other way should work as well.
To be able to build an ISO image from the file system in the end the cdrtools package will be needed. The following line installs the cdrtools application suit directly from the FTP server.

# pkg_add$VER/packages/i386/cdrtools-2.01.tgz


Note: $VER is only a space holder and should be replaced with the actual version number of OpenBSD you are using. Also the version number of the cdrtools package is very likely to vary.

Cloning the filesystem

To be able to adopt some files later and to create the ISO image we will need a copy of all files that should go onto the Live-CD. Therefore we create a new folder which will hold all contents of the CD and also some backup directories will be created so that these files can be restored in their original version.
# mkdir /livecd
# mkdir /livecd/backups
# mkdir -p /livecd/backups/{var,etc,dev}

Now the actual root system can be copied to the newly created folder. I tared everything up and unpacked it later in the /livecd folder to avoid an endless loop which will occur when a recursive copy is done. Later on some cleaning up is done so that there are not any temporary files, the tar archive used for copying or unneeded source code left.
# tar -zcf /livecd.tgz /
# mv /livecd.tgz /livecd/
# tar -xvzf livecd.tgz

# rm /livecd/livecd.tgz
# rm -rf /livecd/livecd*
# rm -rf /livecd/usr/src/*
# rm /livecd/var/tmp
# rm /livecd/tmp

Note: During the packing process some warnings might occur. This is usually nothing critical. Some files simply can not be packet into the archive file. However this is okay since it does not make any sense to archive a socket file or something similar. These files will be generated or overwritten at boot time of the Live-CD anyway.

At this point also the file permissions should be checked. If they changed during the cloning it might lead to problems at boot time of the Live-CD.

Before adopting any files for the CD-boot process the backup directories should be filled:

# cp -pR /livecd/var /livecd/backups/var
# cp -pR /livecd/etc /livecd/backups/etc
# cp -pR /livecd/dev/MAKEDEV /livecd/backups/dev

Create a customized kernel

To adopt the kernel we will need the sources. Therefore they should be either copied from the OpenBSD CD-Rom or downloaded from the projects FTP server. As usual I extracted them inside the /usr/src/ directory.
# cd /usr/src
# tar -xvzf src.tar.gz
# tar -xvzf sys.tar.gz

Now the configuration of the kernel can be done. For safety reasons a backup of the original configuration is performed. Afterwards the RAMDISK_CD file can be adapted to the needs of the Live-CD system.

# cd /usr/src/sys/arch/i386/conf


# vi RAMDISK_CD #any editor could be used

Now the kernel configuration file will be adopted to build a system that can be booted directly from CD-Rom.

# comment out "config bsd swap generic"
# insert:
option MINIROOTSIZE=3800
config bsd root on cd0a


The next file we need to change is a Makefile which is located at /usr/src/distrib/i386/common/ The following lines have to be adopted.

@@ -33,8 +33,7 @@
newfs -m 0 -o space -i 524288 -c 80 ${VND_RDEV}
cp ${BOOT} ${.OBJDIR}/boot
- strip ${.OBJDIR}/boot
- strip -R .comment ${.OBJDIR}/boot
+ strip -s -R .comment -K cngetc ${.OBJDIR}/boot
dd if=${.OBJDIR}/boot of=${MOUNT_POINT}/boot bs=512
dd if=bsd.gz of=${MOUNT_POINT}/bsd bs=512
/usr/mdec/installboot -v ${MOUNT_POINT}/boot \

@@ -54,8 +53,7 @@
 bsd.gz: bsd.rd
cp bsd.rd bsd.strip
- strip bsd.strip
- strip -R .comment bsd.strip
+ strip -s -R .comment -K cngetc bsd.strip
gzip -c9 bsd.strip > bsd.gz

The lines with a minus in front have to be removed and the ones with a plus in fornt need to be added. All other lines are just for information, so that the right lines are changed.

Attention: There is a diff file available on onlamp, however it turned out that this files can not be directly applied. This means that the changes have to be done by hand with an editor.


The next step is to build and install the crunch package, which is needed to build the new system.

# cd /usr/src/distrib/crunch && make && make install


Finally the new kernel can be compiled.

# cd /usr/src/sys/arch/i386/conf
# config RAMDISK_CD
# cd ../compile/RAMDISK_CD/
# make clean
# make depend
# make
Attention: The device /devsvnd0c should not be used at this moment since complications will occur.

Since OpenBSD version 3.8 the libstubs library has to be compiled at this point.

# cd /usr/src/distrib/special/libstubs
# make
# make install

Now the actual boot image can be created. If this is done the first time the object folder ‘obj’ should be empty, however all files in this folder will be removed explicitly just to be sure. If the object folder is not empty then it will not be overwritten.

# cd /usr/src/distrib/i386/ramdisk_cd
# rm -rf obj/*
# make

The freshly compiled kernel and boot image can now be copied to the Live-CD folder on our system, from which the ISO image will be created later on.

# cd /usr/src/distrib/i386/ramdisk_cd/
# cp bsd /livecd/
# cp cdrom38.fs /livecd/ 

Adopting boot scripts and configuration files

A very important file for a proper system start-up is the file system table file which is located at /etc/fstab. Since the whole root file system is located on the CD-Rom and not on a hard drive anymore it must be adopted as shown bellow.

# Comment out all lines and add the following:

/dev/cd0a / cd9660 ro,noatime 0 0

After the initial boot process the /etc/rc script will be executed. In this file we need to create the ramdisk (Memory File System) where we can run the Live-CD system on. This should be done after the "rm -f /fastboot # XXX (root now writeable)" line.



rm -f /fastboot # XXX (root now writeable)
#adoption for livecd
echo 'mounting mfs'
mount_mfs -s 51200 -o async,nosuid,nodev,noatime swap /var
mount_mfs -i 4096 -s 6144 -o async,nosuid,nodev,noatime swap /etc
mount_mfs -i 128 -s 2048 -o async,noatime swap /dev
mount_mfs -s 6144 -o async,nosuid,nodev,noatime swap /tmp
mount_mfs -s 8192 -o async,nosuid,nodev,noatime swap /home
mount_mfs -s 8192 -o async,nosuid,nodev,noatime swap /root
sleep 2
echo -n 'copying files: '
echo -n 'var '
cp -pR /backups/var/* /var
echo -n 'etc '
cp -pR /backups/etc/* /etc
echo 'dev '
cp -pR /backups/dev/* /dev
echo 'creating device nodes ...'
cd /dev && ./MAKEDEV all


In my Live-CDs I also include a script which stores all settings, this means the whole /etc directory, to an USB pen drive. Of course all files will be packed as a tar archive to save space on the USB device. The etc2usb script can be downloaded here.

If you also want to reuse the settings which were saved with the etc2usb script the following lines should also be included at this position of the rc file.

# check settings
echo -n 'looking for usb-pen drive '
mount /dev/sd0i /mnt

if [ $? = 0 ]; then
   #device sucessfully mounted
   tar -pxzf /mnt/settings.tgz -C /
   if [ $? = 0 ]; then
      echo 'Settings copied from USB.'
      echo 'Error while extracting settings from USB!'
   umount /mnt
   echo 'using Settings from CD-Rom'
# end of settings-check


If the Live-CD should run on other machines as well it is very likeley that they use different network interface cards. As a matter of fact the network interface name (e.g. rl0, pcn0, ...) depends on the driver used, so if another driver is used it will have a different name. This could result in problems when it comes to configuration files which contain the network interface name. Also the /etc/hostname* files in the /etc directory will need to be renamed to work properly, otherwise your network configuration will not work.

To solve this problem I wrote a script which returnes the name of a network interface. I usually place it in the /backup directory but it will work anywhere on the Live-CD. You can download the script here.

This script should be called from the rc script we just adopted. So here are some examples how I used it:

# adopt interface names
ext_if=`/backups/ 1`
export ext_if
int_if=`/backups/ 2`
export int_if

# replace interface names in pf config
sed "s/ext_if=\"pcn0/ext_if=\"$ext_if/" /etc/pf.conf.tmp > /etc/pf.conf.tmp1
sed "s/int_if=\"pcn1/int_if=\"$int_if/" /etc/pf.conf.tmp1 > /etc/pf.conf
rm /etc/pf.conf.tmp
rm /etc/pf.conf.tmp1

# rename /etc/hostname*
mv /etc/hostname.pcn0 /etc/hostname.$ext_if
mv /etc/hostname.pcn1 /etc/hostname.$int_if

#set dhcp-server interface
sed "s/interface=pcn1/interface=$int_if/" /etc/dnsmasq.conf.tmp > /etc/dnsmasq.conf
rm /etc/dnsmasq.conf.tmp

Here the interface names inside the /etc/pf.conf file will be replaced with the ones that are found in the current running system. Later on the /etc/hostname files will be renamed and also inside the /etc/dnsmasq.conf file the interface names will be actualised.
To avoid overwriting the config files the original config files are saved as a *.tmp file and the interface names will be replaced using sed and saved to the actual config file which will be used by the programs at a later point in time.

Create an ISO image

Finally the ISO image can be created.
mkisofs -vrTJV "OpenBSD-LiveCD" -b cdrom38.fs -c boot.catalog
        -R -v -o /tmp/livecd.iso /livecd/

This command would create an ISO file, with the label 'OpenBSD-LiveCD', the name livecd.iso and place it in the /tmp folder, out of the /livecd directory.

References & Acknoledgements

First of all I want to thank Theo de Raadt and the whole team of developers who work on and maintain the OpenBSD project. I also want to thank Kevin Lo, who is an OpenBSD developer and wrote an article about Live-CDs on onlamp, and Andreas Bihlmaier for their personal support.

OpenBSD project Homepage
Onlamp article about OpenBSD LiveCDs by Kevin Lo
Andreas Bihlmaier's post about building an OpenBSD LiveCD

How to Make a Bootable, Full System OpenBSD 3.2 CDROM

other similar projects

In recent days some other OpenBSD Live-CDs got published on the internet. Initially I created my first OpenBSD Live-CD for my BSc project in the time between October 2005 and May 2006 - however this little writeup took me a little longer...

OliveBSD - targets desktop users, very easy to use
Anonym.OS - a very secure and anonymizing desktop solution

last updated 02 November 2008