Building & administering jails on FreeBSD, Part 1

These instructions are now part of the FreeBSD handbook since docs/189901 was committed. Please refer to the instructions in the handbook.

The FreeBSD jail(8) manpage & Chapter 15 of the FreeBSD handbook do a great job of explaining jails & helping you get on your way with creating jails, this post builds on that information, covering alternative methods for getting your jails installed & adding what’s not covered already such as maintenance of jails (patching to be specific) & version upgrades.

  • Part 1 (this post :)) will cover alternative install methods & jail maintenance
  • Part 2 (not yet published) will cover upgrading to a new version FreeBSD

Once completed the information from these posts will be submitted for inclusion in the handbook.

So lets begin, when creating a “complete” jail you have two options for the source of the userland, compile from source code or use the prebuilt binaries from install media, both the jail manpage & handbook cover building from source code, we wont go over it again here.

One thing worth mentioning though is if you want to build from source code, create a src.conf file & disable items which are not required, this should speed up the time required to build world & reduce the amount of disk space used by jails.

Here are two sample src.conf files, which disable building items such as firewalls (no use unless you’re using vimage), acpi or documentation:
Sample src.conf #1
Sample src.conf #2

To install the userland from installation media
first create the root directory for the jail, eg
mkdir -p /usr/jails/mynewjail
set the $DESTDIR variable to this location
if using sh
export DESTDIR=/usr/jails/mynewjail
if using csh/tcsh
setenv DESTDIR /usr/jails/mynewjail
mount the media (using the 8.0-RELEASE cd 1 iso in this example)
mount -t cd9660 /dev/`mdconfig -f /some/path/to/8.0-RELEASE-i386-disc1.iso` /mnt

Extract the binaries from the tar balls on the install media into your declared destination, realistically, you’ll only need to extract base, but you can do a complete install if you wish to.
To install just base:
cd /mnt/8.0-RELEASE/base; ./

You are about to extract the base distribution into /usr/jails/mynewjail – are you SURE
you want to do this over your installed system (y/n)?

To install everything but kernel:
if using sh
cd /mnt/8.0-RELEASE; for dir in base catpages dict doc games info manpages ports; do (cd $dir ; ./ ; done
if using csh/tcsh
foreach dir ( base catpages dict doc games info manpages ports )

cd /mnt/8.0-RELEASE/$dir; ./


All configuration steps from here on to get up and running are as specified in the jail man page & handbook.

Keeping jails up to date with patches
On a host with default settings the freebsd-update(8) tool doesn’t work as
chflags(1) is not permitted in a jail, set sysctl security.jail.chflags_allowed to 1 to allow it & freebsd-update can be used.
The other option is to patch the userland manually from the host OS. All the needs to be done is the $DESTDIR has to be passed to the make install command eg.
In section 2b of the FreeBSD-SA-10:04.jail advisory you’re told to
# make obj && make depend && make && make install
after patching, instead you would issue
# make obj && make depend && make && make install DESTDIR=/usr/jails/mynewjail


Use the -b flag for freebsd-update from the host to update jails instead of taking drastic measures.