News Overview Usage Config Version History TODO Details Flavours FAQ Author/Contact License Thanks Links Trackback
News(2008-07-10) ezjail 3.0 is in its finalization stage. It comes with a new backup and migration toolset (archive/restore), has an ez-attach feature (console), brings start/stop/restart shortcuts and adds a lot of polish to enhance user experience. It is available from CVS, considered quite robust and ready for beta testers. Estimated release date is July 16th. Feedback and bug reports are very welcome. Eventually a "mergemaster all jails" feature may also slip in the new version. Stay tuned.
(2007-07-31) After a year of hanging ezjail 2 out to dry, I decided – encountering no problems – to roll up ezjail-2.1. All new features have been tested by volunteers from CVS. Refer to Version History for a list of changes and the download link. Please report any issues you may have.
(2007-03-22) A mailing list has been created. An archive can be found here. Please subscribe to post.
OverviewA Jail in FreeBSD-speak is one or more tasks with the same kernel Jail-ID, bound on a single IP address, 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:
Usageezjail consists of two scripts: ezjail-admin and ezjail.sh, the first used to create, update and remove Jails, the latter one to start, stop and restart Jails.
The ezjail-admin utility knows 4 subcommands: create, delete, update and list. They are introduced in the order you will need them. This is a quick start only, so please refer to the man pages for details.
ezjail-admin update [-i]
To work with ezjail you need a basejail, containing the part of the world that is shared between Jails. Its location is specified in the config file. Refer to the ezjail-admin(1) and ezjail.conf(5) man page for more details. The ezjail-admin update sub command creates the basejail for you, along with a template Jail which will be copied for each new Jail you create.
From time to time it is a good idea to update the basejail. Normally this is necessary, when you update the Host-system, so it should not be a problem stop all Jails before doing so. Care has been taken not to break applications by removing the old basejail. The new world is being copied over the old one, so any installed libs will be found by applications depending on them after the update.
The name update may be misleading for novices to ezjail, but although you will most commonly use this command to update the basejail you will first encounter it to setup the ezjail environment.
The -i option tells ezjail-admin not to invoke make world to build the world but rather make
installworld, assuming you already did a make buildworld before, which will be the case, if you updated the
Host-system.
ezjail-admin create [-f FLAVOUR] [-x] [-r JAILROOT] JAILNAME JAILIP
After the basejail is set up you can start creating Jails. A host name and an IP to bind to are mandatory. Per default all Jails
are being created in /usr/jails and the Jail root is being derived from the JAILNAME given, however, you can alter the default
ezjail root dir in its config file or specify a root directory for the Jail via the -r option. If the Jails root lies outside
ezjails root, a soft link is created pointing to the Jails root. This helps keeping track of all your jails when you have to
spread them all over the place for whichever reason you have.
ezjail-admin checks, whether the JAILIP is configured on a local interface and gives a warning, if it isn't. You should ensure to have the IP configured in order to be able to connect to it.
The -x option is useful if you already created a Jail and deleted it via ezjail-admin delete without the -w option. In that way you can alter some properties of your jail (mostly the JAILIP).
If the -f switch is specified, the Flavour FLAVOUR is being looked for at [ezjails Jail root]/flavours and copied over the newly installed Jail.
After creating the jail you can start it with the ezjail.sh script. However, if you enabled ezjail in rc.conf,
all Jails in ezjails scope are being brought up on next system start up.
ezjail-admin delete [-w] JAILNAME
What this sub command does should be clear, however if you really want to remove the Jail, i.e. delete all files under the Jails root directory, you have to give the -w option. If you don't, you have the chance to recreate the Jail with different (or the same) properties via the ezjail-admin create -x command.
The ezjail.sh script normally (if installed from ports) is found in /usr/local/etc/rc.d/ezjail.sh. It takes sub commands
start, restart and stop and options in form of zero or more Jail host names. If no option is given, all
Jails currently in ezjails scope are being read. This usually happens at system startup, when all rc scripts are being started with
the start sub command without any options. If one more options are given, ezjail.sh only acts upon the Jails specified.
ezjail.sh uses the very resourceful /etc/rc.d/jail script to do the actual work, forcing it to be started despite the
lack of jail_enable rc.conf variable, so you don't have to set it. (It won't hurt if you do so).
ConfigTo enable ezjail (i.e. starting and stopping Jails in ezjails scope), you have to add the line
ezjail_enable="YES" to /etc/rc.conf. This is due to
$PREFIX/etc/rc.d/ezjail.sh
being an rc-script, giving all the auto-start capabilities that comes with it. However the ezjail-admin utility works without the
rc.conf variable set.
The config file at $PREFIX/etc/ezjail.conf controls ezjails behavior. As it is self explaining plus there is a man page,
I kindly ask to look up the options there.
Version HistorySince ezjail is useful under FreeBSD only, you might want to install it from ports sysutils/ezjail. A cvsweb is available
at ezjail cvsweb, plus there is a fresh checkout. The most current version is
available via cvs. Use 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):
create -a option – can be used to take (automated) backups of your jails and
reinstall them.jexec into a jail identified by its jail name. It can also
bring up non-running jails if run with the -f switch.-b (buildworld, installworld), -i
(installworld only) or (as a new option) -u to use freebsd-update to update your base jail.find .s its stuff. Using '*' never found dot-files and could have led to a "too many parameters" situation.lib32 packag on amd64 platforms when doing ezjail-admin
install.sudo now checks permissions on its sudoers file and stops, if it is not 0440. Fixed ezjails Makefile to install
sudoers to default flavour. (However, if you already installed ezjail, you might want to manually chmod 0440
${ezjail_flavours}/default/usr/local/etc/sudoers and all corresponding sudoers files in all jails.)sendmail_submit_enable, sendmail_outbound_enable and
sendmail_msp_queue_enable in the default-flavour rc.conf to allow
easier fine-grained control for sendmail.newfs won't be mistaken as used.fetch rather than
cron from my ezjail-admin update -P./etc/rc.d/jail./etc/periodic.conf now makes all periodic scripts log to files instead
of sending mails. Most often this is what you want in your jails.DESTDIR was ignored for sub targets in an ezjail-admin update -p under certain circumstances. See this report for more details. Thanks go to Simon L. Nielsen.tr parameters in the form [:alnum:] which were expanded to
the files : a l n u and m, if existing. Also an apparent bug in tr was
circumvented which incorrectly replaced A-Z to a-z in certain LANG settings. Thanks agains to Simon L. Nielsen.ezjail_ftphost was ignored when specified in PREFIX/etc/ezjail.conf. Thanks to Edwin Groothuis. V 2.0 ezjail-2.0.tar.bz2 (2006-05-31)cd /usr/ports/sysutils/ezjail; make install; ezjail-admin install; ezjail-admin create test.com
10.1.1.1 on a vanilla FreeBSD server, i.e. without installing /usr/src.rcorder on its config file list located in
PREFIX/etc/ezjail/ before processing them. That way you can manually construct a dependency tree and for example start your
name server Jail first and your data base-Jail before your web server Jail. However, some basic knowledge in bourne shell and the rcorder command is
required. Beware of circles.test_org.norun to
temporary exclude it from auto run process.ezjail_uglyperlhack (defaults to YES) which creates a soft link
from /usr/bin/perl to /usr/local/bin/perl in the base jail. This is useful since perl was expelled from
base system in FreeBSD 5 but still many scripts rely on #!/usr/bin/perl./usr/games and /usr/libdata have now become part of the basejail. Someone please kick me
for missing that until now. Saves another 100k in newjail. Hopefully I got them all by now ;) Thanks to Vivek Khera. V1.3.1 ezjail-1.3.1.tar.bz2 (2006-03-13)jail_list from rc.conf as it should due to a legacy name space clash. This led to
no ezjail being started at system startup when some non-ezjail-Jails exist in the system. Thanks to Cryx.fulljail to be created and refines the error message in case the user wants to
create basejail, newjail or flavours. V1.3 ezjail-1.3.tar.bz2 (2006-02-16)/boot and /rescue have now become part of the basejail. Someone please kick me for missing
that until now. New jails now are < 2 MB in size. V1.2 ezjail-1.2.tar.bz2 (2006-02-10)cvs co or cvs up of ports in the basejail by
providing the -p or -P option./lib and /libexec have now become part of the basejail. Someone please kick me for missing
that until now.tr -c [:alnum:] _, thanks go to Gunjin.PREFIX is provided now. Installing to / seems not too useful and should not be default. V1.1 ezjail-1.1.tar.bz2 (2005-10-26)#/bin/sh to #!/bin/sh, thanks go to Alex Samorukov.$PREFIXes$basejail/usr itself, since cpio creates missing intermediate
directories in 0700 which is bad V1.0 ezjail-1.0.tar.bz2 (2005-10-14) V0.1 ezjail-0.1.tar.bz2 (2005-09-26) V0.0 - Not packaged (2005-09-04) TODO DetailsI have spent a lot of time investigating all tools FreeBSD provides for an easy handling of Jails. A run across a few that really helped a lot. I wrote a blog entry in German about it. In short, the most important facts:
/etc/rc.d/jail restart have been fixed, reducing work left to do for
ezjail.sh. I use that script to do all the actual work, just feed it the jail names after parsing each config file. The
jail_JAILNAME_mount_enable variable allows me to use the next feature:/etc/fstab.JAILNAME entries that are being executed on Jail's start up. Adding lines of
the type /usr/jails/basejail /usr/jails/JAILNAME/basejail nullfs ro 0 0 gives the basejail inside my Jail for free./usr/ports/ and /usr/src/
regularly to /usr/jails/basejail/usr/{ports,src}. That way the inode-consuming ports are shared between all Jails. The
/etc/make.conf's WRKDIRPREFIX=/var/ports, DISTDIR=/var/ports/distfiles and
PACKAGES=/var/ports/packages entries are quite helpful. Having a WRKDIRPREFIX outside
/usr/ports also helps very much with tidying up after installing lots of ports with heavy dependencies ;) FlavoursVersion 1.2 of ezjail introduces the concept of Flavours. A flavour corresponds to a preconfigured Jail. Basically it is a directory being copied recursively over a new Jails root and a script being run on its first startup to do some initialization.
An example Flavour resides under /usr/local/share/examples/ezjail/default. For your convenience it is being copied to
ezjails jail root (default: /usr/jails/flavours/), by the ezjail-admin update command. In this location all other
flavours are being expected to reside, too.
Flavours will be copied recursively over any new Jail created with the ezjail-admin -f FLAVOUR command. In the example flavour an /ezjail.flavour script is provided which, if found by ezjail-admin, is being executed when the Jail starts up for the first time. The script demonstrates most of the common actions needed to prepare the Jail like creating groups, users, changing the ownership of files and installing packages. You may add your own code to do more post-install actions.
The default flavour demonstrates how to pkg_add some prefetched packages. Since no remote fetching of missing packages is requested,
you need to provide all package dependencies yourself. Although I tried hard to provide easy means to setup Flavours, essential features are missing in the
FreeBSD base system (like recursive package fetching without installing them). The portupgrade utility provides an pkg_fetch command,
but since it requires ruby I am not really recommending it for the host system.
If you have ports in base system and are not afraid of compiling things there (which I personally would not recommend, either), the lines
cd /usr/ports/<cat>/<port>; make PACKAGES=/usr/jails/flavours/<flav>/pkg/ package-recursive deinstall distclean
will install the port and all dependencies to the base system, make packages of the port and all dependencies, put them to the flavours pkg directory and
deinstall the port (unfortunally not its dependencies) from host system. You might also consider setting up a compile Jail to do this.
If you provide /usr/ports/ for your ezjails, the /ezjail.flavour can also install some ports for you. But note,
that Jail creation time increases dramatically in this case. Be sure to have a working /etc/resolv.conf etc. in the Jail before
trying to access the network.
FAQ
/usr/local/etc/rc.d/ezjail.sh start JAILNAMEjls. Unlike the command
jail which leaves you with an interactive shell in your Jail, rc.d/ezjail.sh is an rc-script. It is most commonly meant
to run at system startup and shutdown where entering an interactive shell would interrupt the boot process. If you want an interactive shell in your Jail after
starting it, combine the commands jls and jexec JID /bin/sh until it fits.ezjail_enable="YES" to
rc.conf./usr/jails/JAILNAME/var/log/console.log (or whatever your
ezjail root is). Most commonly you'll find reasons for your jails startup failure there./etc/rc.d/jail is broken in 6.1-RELEASE preventing more than
one ezjail to start up. Due to an
unrelated bug this issues an error message for an attempted ifconfig, which can be ignored. Fix: upgrade your system to
RELENG_6_1. There are very few things ezjail could do to workaround that problem without major structural changes.ezjail_root.work/-directories,
this might reveal attack vectors to the host system. A problem like ignoring ro flags when
mounting from fstab may give you an idea why I consider that boundary essential to system security.WRKDIRPREFIX none of the Jails can access, you might follow these instructions to mount ports via nullfs. Another way of doing this is to mv
/usr/ports/ /usr/jails/basejail/usr/ports/; ln -s /usr/jails/basejail/usr/ports /usr/ports; in host system. ezjail will not offer this
as an option./etc/ and /var/. It is being recreated everytime you ezjail-admin
update. So it is not meant to be modified by the user to distribute settings to all Jails to be created. A Flavour on the other hand is
set up by the user, contains all non-sharable files not in the base system that you think belongs to a newly created Jail (usually stuff in
/usr/local/ and your settings in /etc/). You may have several Flavours each customized for a certain job:
an httpd-Flavour, a shell-server only Flavour, a full featured bamp-server and so on. Flavours are never modified by ezjail, the template should not be
modified by the user./legacyjail Basically you only need to create an empty directory
/legacyjail/basejail/ and call ezjail-admin create -x -r /legacyjail JAILNAME JAILIP and your Jail
enjoys all of ezjails starting/stopping capabilities. (Please note, that the create -x feature is broken in V 1.3)./legacyjail with the path to your Jail).
cd /legacyjail
mkdir OLDBASE
for dir in bin boot lib libexec rescue sbin usr/bin usr/include usr/lib usr/libexec usr/ports usr/sbin usr/src usr/share; do
mv ${dir} OLDBASE/; ln -s /basejail/${dir} ${dir}
done
(#!)/usr/bin/perl. Since perl was expelled from the base system in
FreeBSD5.0, those scripts would not work, if FreeBSDs perl port would not create a soft link /usr/bin/perl ->
/usr/local/bin/perl. Of course, that won't work in a read only mounted /usr/bin. On my servers I
create the softlink in basejail, it won't hurt, if perl is not yet there.ezjail_uglyperlhack
is set to YES, which is the default./etc/localtime to the appropriate time zone file, in my case:
/usr/share/zoneinfo/Europe/Berlin.rm -rf
them as root. How do I get a clean start?man
chflags for more details. However, to reset everything to a state with no jails and no files lurking around use the following lines, on kern secure level 0, as root, on a standard ezjail.conf :
chflags -R noschg /usr/jails/
rm -rf /usr/jails/
rm -rf /usr/local/etc/ezjail/
rm /etc/fstab.*
ezjail is considered beer ware.
Thanks...are due to:
Links TrackbacksThanks for spreading the word go to
