Scroll to navigation

update-jail(8) create chroot jails easily update-jail(8)

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

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).

02 Sep 2018 update-jail-1.1