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.

Overview

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

Before you start

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

The cvsup program (Minimal survival command: pkg_add -r cvsup-without-gui)
The mkisofs program (Minimal survival command: pkg_add -r cdrtools)
Some free disk space. I needed about 4.5 GB for the CVS repo. and an i386 release build.
A recent `buildworld' in /usr/obj. (Minimal survival command: cd /usr/src && make buildworld)

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:

CVS tag of the system sources to use: RELENG_5_2 (the security branch for 5.2.1-RELEASE, currently at patchlevel 9)
CVS tag of the ports to use: HEAD (the most current)
A name for the result: 5.2.1-RELEASE-p9-MPT (this will be the kernel version string)
Where to build it: /backup/releng

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.

Modify host= to a suitable mirror
Make sure the base= directory exists before you run cvsup
Change prefix= to where you want to store your copy of the repository (it's about 2.4 GB in size). I chose /backup/ncvs.

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 host=cvsup.ie.FreeBSD.org
*default base=/var/db
*default prefix=/backup/ncvs
*default release=cvs
*default delete use-rel-suffix compress

src-all
ports-all
doc-all
cvsroot-all

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

NODOC Defining this skips making additional system documentation.
NOPORTREADMES Defining this skips creating (thousands) of ports README files.
LOCAL_PATCHES This specifies the mpt driver patch. This is applied to the checked-out sources in the build area before they're compiled. It can be omitted if you don't need to add your own patches.

As root, do

# cd /usr/src/release
# make release RELEASETAG=RELENG_5_2 PORTSRELEASETAG=HEAD \
	BUILDNAME=5.2.1-RELEASE-p9-MPT CHROOTDIR=/backup/releng \
	CVSROOT=/backup/ncvs NODOC=yes NOPORTREADMES=yes \
	LOCAL_PATCHES=/home/james/mpt-patch

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 `mkisoimages.sh` to make an ISO image

The mkisoimages.sh 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/mkisoimages.sh -b FreeBSD5 \
	/backup/5.2.1-RELEASE-p9-MPT-miniinst.iso \
	/backup/releng/R/cdrom/disc1

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.