Building a custom, patched FreeBSD ISO install image

Why ?

I needed to install FreeBSD on a system (a Dell PowerEdge 400SC) with an LSILogic 1030 Ultra4 SCSI adapter. At that time support for this device was only available with an mpt driver patch that hadn't yet made it into FreeBSD. I needed to make install media that incorporated the mpt patch. I also wanted to have all published security patches included so I wouldn't have to apply them afterwards.

I found some articles on the web and it's from them I figured out what to do, but I found them slightly incomplete and bitsy. So I wrote this.

These instructions are tailored to my requirements. I want a custom `mini-install' CD. I don't have a need to make the other CDs in the standard distribution set.


  1. Decide what to build.
  2. Get a local copy of the FreeBSD CVS repository.
  3. Use make release to do all the hard work.
  4. Use to make an ISO image.

Before you start

Things you will need (and are expected to get yourself)

Deciding what to build

You can build a release based on pretty much any version of the sources that you can checkout from CVS, so you have plenty of options. For this exercise, here's what I chose:

Get a local copy of the FreeBSD CVS repository

This is not a cvsup tutorial, so this section is brief. The supfile I used is below. Please double-check the following points in your supfile before you do something silly.

See the cvsup documentation and example supfiles in /usr/share/examples/cvsup for further information. This is my supfile, saved as /root/cvs-supfile:

*default base=/var/db
*default prefix=/backup/ncvs
*default release=cvs
*default delete use-rel-suffix compress


As root, run cvsup. Then go for a very, very long coffee break.

# cvsup -g /root/cvs-supfile

Use make release to do all the hard work

The make release target in /usr/src/release/Makefile does the real work. It takes a number of options to tell it what to build, how, and where. See the release(7) man page for more information. The values for the first five options should look familiar -- they were decided upon a few steps ago. The ones we haven't seen before are

As root, do

# cd /usr/src/release
	BUILDNAME=5.2.1-RELEASE-p9-MPT CHROOTDIR=/backup/releng \
	CVSROOT=/backup/ncvs NODOC=yes NOPORTREADMES=yes \

This will install the `buildworld' into CHROOTDIR, checkout the specified system sources and ports from the CVS repository, apply the mpt patch, and compile the lot within CHROOTDIR. The result will be in a directory `R' below CHROOTDIR -- /backup/releng/R in my case. It should look like this when it's done:

# ls -l /backup/releng/R
total 6
drwxr-xr-x   5 root  wheel  512 Aug 23 23:14 cdrom
drwxr-xr-x  20 root  wheel  512 Aug 23 23:14 ftp
drwxr-xr-x  13 root  wheel  512 Aug 23 23:14 stage

Some important notes

Your build host needs to have support for memory-backed disks using either the md(4) or vn(4) driver. The GENERIC kernel includes this. If your build host is running a kernel you've configured yourself, you should check your kernel configuration file for an appropriate pseudo-device statement.

The filesystem containing the CHROOTDIR directory must not be mounted with the nodev mount option.

Use to make an ISO image

The script will make a bootable ISO image, ready to burn onto CD. ``FreeBSD5'' below is the ISO image label -- change it if you want. The third argument is the filename of the ISO image that will be created and the last argument is the path to CHROOTDIR/R/cdrom/disc1.

# sh /usr/src/release/i386/ -b FreeBSD5 \
	/backup/5.2.1-RELEASE-p9-MPT-miniinst.iso \

When that finishes, /backup/5.2.1-RELEASE-p9-MPT-miniinst.iso is ready to burn to CD, boot, and install FreeBSD.

More information

See the release(7) and build(7) man pages and the FreeBSD Release Engineering process document.

(c) James Raftery, 24 August 2004.

$Id: customfreebsdiso.html,v 1.6 2010/11/15 00:25:01 lecter Exp $