Building a custom, patched FreeBSD ISO install image
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.
- Decide what to build.
- Get a local copy of the FreeBSD CVS repository.
make releaseto do all the hard work.
mkisoimages.shto make an ISO image.
Before you start
Things you will need (and are expected to get yourself)
cvsupprogram (Minimal survival command: pkg_add -r cvsup-without-gui)
mkisofsprogram (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:
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.
host=to a suitable mirror
- Make sure the
base=directory exists before you run cvsup
prefix=to where you want to store your copy of the repository (it's about 2.4 GB in size). I chose
See the cvsup documentation and example supfiles in
/usr/share/examples/cvsup for further information. This is
my supfile, saved as
*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
make release to do all the hard work
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
NODOCDefining this skips making additional system documentation.
NOPORTREADMESDefining this skips creating (thousands) of ports README files.
LOCAL_PATCHESThis 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
R' below CHROOTDIR --
/backup/releng/R in my case. It should look like this when
# 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
The filesystem containing the CHROOTDIR directory must not be mounted
nodev mount option.
mkisoimages.sh to make an ISO image
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
# 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.
See the release(7) and build(7) man pages and the FreeBSD Release Engineering process document.
(c) James Raftery, 24 August 2004.