NAME
  update-jail, jailtool - create chroot jails easily
SYNOPSIS
  jailtool    [-s] <jailfile>
  update-jail [-s] <jailfile>
DESCRIPTION
  JailTool is a script to create chroot jails easily. It is driven by simple .jail files that define how the jail
  should look like. It can make use of Perl CPAN .packlist files and Debian package information. The jail is copied
  from the base system. The amount of copied data can be configured.

  But, 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 ;-)
OPTIONS
  -s  Simulate a jail update.
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 fiddling
  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 whether 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 useful if you want to see
  whether 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 against each and
  every file to check whether 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 against the PRUNE list and dropped, if it is included. But before
  dropping it, it is checked against the GRAFT list, whether 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 whether 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 /usr/share/doc/jailtool/examples/ directory of the distribution.
AUTHOR
  update-jail (aka jailtool) was written by Georg Bauer <gb@bofh.ms> and is available at 
  http://www.westfalen.de/~gb/

  This manual page was written by Joao Eriberto Mota Filho <eriberto@debian.org> for the Debian
  project (but may be used by others).
