Daemon Hammer

- Jail administration framework

News Overview Quick start Slow start Version History FAQ Author/Contact License Thanks Links Trackback

+ News

(2013-09-27)Due to changes in how the FreeBSD port system handles the install target, certain ports fail to install with the error "pkg_create: make_dist: tar command failed with code 256" in Jails installed with the current version of ezjail. ezjail from version 3.4 fixes this. Until then you should execute the command mkdir -p /var/ports/packages as a workaround in all jails you want to install ports in.

(2013-04-20) ezjail 3.3 is out. Besides several bug fixes, it allows to install ezjails in alternative zpool, copes with auto-configure interface syntax for IP addresses better and properly supports the new distribution server layout. Refer to the Version history for details. On a side note, the project home page was brushed and polished.

(2012-09-23) ezjail 3.2.3 is out. The 3.2.2 introduced an inconvenient bug that prevented ezjail-admin update to find /usr/src.

(2012-09-19) ezjail 3.2.2 is out. This release contains minor fixes in zfs code.

(2007-03-22) A mailing list has been created. An archive can be found here. Please subscribe to post.

+ Overview

A Jail in FreeBSD-speak is one or more tasks with the same kernel Jail-ID, bound on zero or more IP addresses, having the same chroot-environment. One usecase of the FreeBSD Jail Subsystem is to provide virtual FreeBSD-systems within a Host-system. ezjail is about making this as easy as possible, aiming for minimum system resource usage. All further references to the term Jail are to a virtual FreeBSD-system consisting of a host name, an IP-address and a Jail root.

The jail(8) man page outlines the way to create Jails, however, when you need several Jails, complete Jail Directory Trees quickly use much of your valuable hard disc space. ezjail avoids this by using FreeBSDs nullfs feature. Most of the base system (/bin, /boot, /sbin, /lib, /libexec, /rescue, /usr/{bin, include, lib, libexec, ports, sbin, share, src}) only exists in one copy in the Host-system and is being mounted read only into all Jails via nullfs. Those Jails are quite slim (around 2mb each) and only consist of some soft links into the basejail mount point and non-shared directories like /etc, /usr/local, etc.

The ezjail approach offers lots of advantages:

+ Quick start

To set up your first very simple ezjail, just install ezjail from sysutils/ezjail port or via pkg_add -r ezjail and enable it by setting ezjail_enable=YES in your in your /etc/rc.conf. Assuming your network interface is em0, just type (as root):

  ezjail-admin install
  ezjail-admin create example.com 'em0|'
  ezjail-admin start example.com 

and you're done. Get a shell in your new jail with the

  ezjail-admin console example.com

command. As with any vanilla FreeBSD installation, you might probably need to touch /etc/ and maybe copy your host's /etc/resolv.conf.

+ Slow start

ezjail comes with some sane defaults, but can be configured globally and per jail using the config file /usr/local/etc/ezjail.conf (copy the sample from /usr/local/etc/ezjail.conf.sample) and the per-jail config files under /usr/local/etc/ezjail/ (those are created automatically with the jails and managed by the ezjail-admin config command).


ezjail integrates nicely with zfs, ready to manage all jails in its own file system. So if your system has a zpool configured, tell ezjail to use zfs and which zpool to use for its house keeping:

while you're at it, you can tell ezjail to create all future jails in their own file system (which defaults to be a child of ezjail_jailzfs)

now the commands in the quick start example should set up a zfs hierarchy ready to use all the nifty features of zfs.


ezjail can help you with the otherwise tedious task of decorating the interior of new jails–those come as naked FreeBSD installations by default. A set of files to copy, packages to install and scripts to execute is called "flavour". ezjail comes with an example flavour called "example" that comes pre-tuned for the use in jails, with an appropriate rc.conf, make.conf, periodic.conf and /usr/local/etc/sudoers.

You are encouraged to copy the flavour and modify the contained script to suit your needs–flavours reside in the directory configured with the ezjail_flavours_dir variable, which defaults to /usr/jails/flavours. But just calling

  ezjail-admin create -f example example.com 'em0|'

should do. Note, that the flavour script is being run the first time the jail starts, so calling

  ezjail-admin console -f example.com

is a nice idea. You can use the shell to further configure the new jail.

The basejail

All jails share a read only mounted copy of the FreeBSD base system, in ezjail this is called basejail. The quick start section gave a glimpse on the most simple way to install just the basics, but no ports tree, no man pages (pre FreeBSD-9) and no sources. You can run the ezjail-admin install command with the options -P, -M and -S again to install these distribution packages without installing the base system again, or just call ezjail-admin install -spm from start. ezjail uses the portsnap command to provide (and later update) the ports tree. If you do not want to install the OS version running in the host system, call

  ezjail-admin install -r 2.2.8-RELEASE

If you want to install your base system from source, use the ezjail-admin setup command (also called ezjail-admin update); assuming you have already built your world for the host system, you would just call

  ezjail-admin setup -i

to run a make installworld from your source directory, which defaults to /usr/src. To run a make buildworld before the installworld, call

  ezjail-admin setup -b

For binary installations, ezjail uses the freebsd-update tool to keep the basejail up to date,

  ezjail-admin update -u

should do the trick.

Image and crypto jails

Before the dawn of zfs, simple means to set limits on jails, like quotas, were hard to achieve. ezjail's answer were image jails, file backed "memory" disc images containing an ufs with the jail's content. When geom appeared with the very useful gbde and geli crypto layers for geom, encrypting image jails became possible. ezjail would handle creating and later attaching and detaching those images for you.

Now simple image jails are not as hot anymore and personally I would recommend using geli to encrypt the provider for your zpool to apply proper crypto to all your jails. Still, there may be valid use cases for image jail. Call

  ezjail-admin create -i -s 2G example.com

to create a two gigabyte md-image with an ufs file system and install the jail inside. To configure the jail without starting it, use the attach and detach subcommands of ezjail-admin config, like this

  ezjail-admin config -i attach example.com
  cd /usr/jails/example.com
  … do your thing …
  ezjail-admin config -i detach example.com

Should the file system need some love, e.g. after a spontanous reboot or system crash, call

  ezjail-admin config -i fsck example.com

to tidy up the mess–it ain't zfs, after all. By default ufs soft updates are enabled, so background fsck should occur for minor wrinkles, when an image jail starts.

To create encrypted image jails, use the -c switch and either pass bde or eli and follow the instructions on screen:

  ezjail-admin create -c eli -i 16G example.com

Note, that ezjail creates image jails by filling them from /dev/zero or /dev/random, for performance reasons (reduce seeks with this file system inside a file system hack) and for security reasons (do not leak information about which blocks have been written for crypto jails), so creating huge image jails may take a while. Also note, that crypto jails would block the boot process (unless the passphrase is provided via a file or some fetch magic via stdin). So they are being marked as attachblocking and not started during boot time. You need to start them using ezjail-admin startcrypto.

Further reading

To get further details about all the options for ezjail-admin and all knobs and bolts, I recommend the excellent man pages: ezjail-admin, an overview over ezjail and the ezjail config file.

+ Version History

Since ezjail is useful under FreeBSD only, you might want to install it from ports sysutils/ezjail. An ezjail cvsweb (deprecated) and ezjail gitweb are available, plus there is a fresh checkout. The most current version is available via cvs. Use git clone git://erdgeist.org/ezjail or the legacy view cvs -d :pserver:anoncvs@cvs.erdgeist.org:/home/cvsroot co ezjail with an empty passwort to check it out. Just type sudo make install to install it. Older versions may be found here (checksums in tooltips):

Version history


County Jail

+ Author/Contact

ezjail was written by Dirk Engling with lot of support from the ezjail community. We like to hear from happy customers. My personal address is erdgeist@erdgeist.org. Requests should go to the project mailing list ezjail@erdgeist.org. You can subscribe to that list at ezjail-subscribe@erdgeist.org. There is an IRC channel #ezjail on ircnet. Please send bug reports, comments and feature requests. Donations are welcome... in form of beer. See...

+ License

ezjail is considered beer ware.

+ Thanks

...are due to:

+ Links

+ Trackbacks

Thanks for spreading the word go to

FreeBSD Banner Valid XHTML 1.1