JailTool - a simple way to build chroot Jails with Debian
=========================================================

Why I wrote this
----------------

There are several tools available for building chroot jails. So why should
anybody in his right mind build another one? This is maybe the question you
are asking. Well, I had a quite different approach to the problem, I think. I
have these nice shiny Debian boxes up and running, using all sorts of lists
of installed packages. There are the dpkg registry, the CPAN registry and -
of course - lot's of directories and files and init-scripts and stuff. But all
are layed out in a nice and standard way. So why not use that information?
Why not use a declarative approach to set up a jail? Say what you want from
your standard system, what to leave out and how to configure it. What you get
is a _very_ easy way to set up a chroot jail _including_ shared libraries and
_including_ a nice and easy upgrade facility, if your master environment is
updated because of security problems or release updates!

I think it's a very neat solution. You might think otherwise - if you do, just
tell me what is bad or stupid or maybe even insecure. I will try to fix it.
You can write me that this is the best invention after sliced bread, too ;-)

Where to get the newest version?
--------------------------------

You can always find the newest version of this script at the following URL:

http://www.westfalen.de/~gb/jailtool.tar.gz

What license is it under?
-------------------------

This software is under the GNU Public License Version 2 or newer. A copy
of version 2 of the GPL is included for your reference in the LICENSE file.

How to install update-jail
--------------------------

Just copy the update-jail script into /usr/local/sbin or wherever you keep
your administrative scripts. And install rsync, as this is used to copy
the files.

How to build a jail
-------------------

Easy and simple. You just build a .jail file. You put in all declarations of
including and excluding steps. You run update-jail on it. That's it. Isn't that
easy? :-)

You run update-jail just with one parameter: the .jail file. Everything is in
the .jail file. No switches outside, no additional config files, no fiddeling
around with other tools to prepare your system. You have to run the script
as root, of course. If you don't trust me (and you shouldn't!), look first
through the source to see wether this does something bad.

There is a simulation switch -s that you can use to simulate a jail update
run prior to do the real thing. This is especially usefull if you want to see
wether you excluded all irrelevant parts without dropping something essential.

The .jail file has a very simple format: Every line starting with a declaration
tag, is remembered. And process. Lines following a different format, are
regarded as comments. You could put a # before comment lines, if you want, to
avoid confusion.

These are the declaration tags currently used by update-jail:

TARGET=<path-for-chroot-jail>

  This is just the path that should be created by the update-jail program.
  This is where your jail will be created and where you should chroot into.

NAME=<name-of-chroot-jail>

  This is the name of the jail that should be created. This name is used
  for example for start/stop init.d scripts that are created by update-jail.
  If you just create a shell environment for remote uses, just don't include
  this declaration and no script will be generated.

START=<path-to-start-script>

  This is the start command for the chrooted daemon, if you create a daemon
  environment. This will just be copied to the generated start/stop script.

STOP=<path-to-stop-script>

  This is the stop command. Same as with the start command.

DEB=<name-of-debian-package>

  This is one of the more complex declarations. This declaration uses the
  dpkg database to include files and remember configuration files. It uses
  the <package>.list file to include single files and the <package>.conffiles
  file to include configuration files. Dependencies are currently _not_
  honored, so you have to add one DEB declaration for every package you need
  and every package that one needs. Or you can add the relevant files or
  directories with some of the other declarations.

PERL=<name-of-local-perl-package>

  This includes all files from the .packlist of the locally installed perl
  package into the lists of files to be included.

  ATTENTION: this only works with fully qualified .packlist files - some
  packages just include basenames of files, this won't work. The files have
  to be in fully qualified notation, to be useable. And you have to include
  the package names in require notation without extension. So to use the
  XML::Stream module, you have to put PERL=XML/Stream in the .jail file!

FILE=<path-to-file-to-copy>

  If you want to keep a single file, you can use this declaration. This can
  be used to enforce copying a file, even if it is a configuration file!

CONFFILE=<path-to-configuration-file>

  This adds a single configuration file. Configuration files are only copied
  if they don't already exist. If they already exist, the are left as is.

DIR=<path-to-directory-to-keep>

  This adds a single directory that should be created. Only the directory is
  added, not it's content.

RECURSE=<absolute-path-to-copy>

  This adds a directory including it's content to the FILES list. Directories
  and files starting with a "." are _not_ copied! You have to add them
  manually as single declarations (use RECURSE for directories and FILE for
  simple files).

RECURSEONCE=<absolute-path-to-copy-once>

  This adds a directory including it's content to the CONFFILES list, so that
  all files are only copied once. Again, directories and files starting with
  a "." are not copied.

DEVICE=<path-to-device-to-create>

  This adds a single device to the list of devices to be created.

PRUNE=<partial-path-to-delete-from-chroot-jail>

  This adds a partial path specifier to a list that is checked agains each and
  every file to check wether this file should be included or not. This helps
  with weeding out unimportant stuff like unused locales and other cruft.

GRAFT=<partial-path-to-keep-in-prune>

  This adds a partial path specifier to a list that defines exclusions from
  the PRUNE list.

The order in that declarations are taken into account is as follows:

1) fill FILES and CONFFILES via all the content fetching declarations
2) all remembered files are copied from the base system
3) all configfiles that don't exist are copied from the base system
4) all devices are created in the jail.
5) the start/stop script is created

PRUNE and GRAFT are used when copying FILES and CONFFILES: every file is
checked agains the PRUNE list and dropped, if it is included. But before
dropping it, it is checked agains the GRAFT list, wether it is included. If it
is, it is kept. So you install actually: (FILES+CONFFILES)-PRUNE+GRAFT. DEB,
PERL, DIR, RECURSE and RECURSEONCE are actually only alternative ways to add to
the FILES and CONFFILES.

So the following "formulas" are in effect:

FILES=(FILE+DIR+RECURSE+DEB(.list)+PERL)-PRUNE+GRAFT
CONFFILES=(CONFFILE+RECURSEONCE+DEB(.conffiles))-PRUNE+GRAFT

When copying files, every entry in the FILE list (remember, this list is
filled by FILE, DEB, PERL, RECURSE*), it is checked wether it is a directory.
If it is, this directory is just created with the same identical rights and
mode as in the base system. The content is not automatically included! For
RECURSE*, the content is added by adding all files in the tree to the FILES
list, before doing any pruning and grafting. _Everything_ goes into the big
lists of files and conffiles.

All copies are done with rsync, so that even big files that just change a bit
are copied efficiently! Modes, rights and other stuff are copied, too - even
with devices and other stuff. Devices are not copied with rsync, of course, but
are added via mknod.

There are examples in the examples/ directory of the distribution.

Can it be used on other systems?
--------------------------------

I don't really know. It could be used, if you can live without the DEB
stuff and if your system keeps init.d-Scripts in /etc/init.d/ - otherwise
you could hack the script to use a different init.d-path (easy) or a different
package repository (medium complexity). I don't have other systems running,
so I can't do the porting to other platforms. But if you add stuff in an
easy to use way (for example add a RPM declaration to use a RPM repository),
I would be happy to add it to the script.

Are there any known bugs?
-------------------------

Not yet. But there are bound to be tons of unknown bugs in it. Although I use
this script on a regular basis, I can't make any guarantees for fitness for
any purpose than to use up disk space.


bye, Georg Bauer
<gb@bofh.ms>