Introduction
------------

The jailtools distribution provides a collection of modules which attempt to
support the execution of programs within restricted environments, where such
environments are established using the chroot system call as provided on
various UNIX-like systems. Additional resource limits can also be applied to
jailed processes using various modules in the Python standard library. In
addition to the jailtools module which provides the core functionality,
support for communications between client software and jailed processes is
provided by the jailtalk module.

Warning!
--------

The restricted environment provided by the jailtools distribution has not been
verified as being completely secure. It is well known that the chroot system
call has various flaws which may permit processes to circumvent restrictions
on filesystem access. As is stated in the licensing conditions of this
software, no guarantees are made as to the suitability or behaviour of the
software: it is merely a convenient wrapper around chroot functionality which
may or may not provide useful isolation of jailed processes from the rest of
your system, even though the motivation was to seek such isolation for such
processes. Use this software at your own risk!

Quick Start
-----------

Try making a jail directory:

mkdir /tmp/test

Then try running Python as user identity (uid) 1000 in the jail:

sudo python -i jailtools.py /tmp/test 1000

Alternatively, copy a test program inside the jail:

cp tests/hello.py /tmp/test

Then try running the program in the jail:

sudo python jailtools.py /tmp/test 1000 --exec hello.py

Serving Jailed Processes
------------------------

The jailtalk module provides support for running a simple server which will
manage jail directories and run programs within them, thus providing a simple
framework for agent-based applications.

First make a directory to hold multiple jail directories:

mkdir /tmp/jails

Then try running the server using uid and group identifier (gid) 1000, and
specifying a filesystem location for the communications endpoint (a UNIX
domain socket):

sudo python jailtalk.py --server /tmp/jt /tmp/jails 1000 1000

In another terminal, try running a program in the jail environment:

python -u jailtalk.py /tmp/jt hello tests/hello.py

(Note that the -u option is essential to prevent buffering issues.)

References
----------

Usage of chroot is often referred to as "jailing" processes, although this
term is derived from a specific technology whose origins are slightly
different to those of chroot. More information can be found in the following
locations:

http://www.bpfh.net/simes/computing/chroot-break.html
http://www.unixwiz.net/techtips/chroot-practices.html

Contact, Copyright and Licence Information
------------------------------------------

The current Web page for jailtools at the time of release is:

http://www.boddie.org.uk/python/jailtools.html

Copyright and licence information can be found in the docs directory - see
docs/COPYING.txt and docs/LICENCE.txt for more information.

Dependencies
------------

The jailtools distribution has the following basic dependencies:

Package                     Release Information
-------                     -------------------

CMDsyntax                   0.91
parallel/pprocess           0.2.2

Release Procedures
------------------

Update the jailtools.py and jailtalk.py __version__ attributes.
Change the version number and package filename/directory in the documentation.
Change code examples in the documentation if appropriate.
Update the release notes (see above).
Check the setup.py file and ensure that all package directories are mentioned.
Check the release information in the PKG-INFO file and in the package
changelog (and other files).
Tag, export.
Generate the API documentation.
Remove generated .pyc files: rm `find . -name "*.pyc"`
Archive, upload.
Upload the introductory documentation.
Update PyPI entry.

Generating the API Documentation
--------------------------------

In order to prepare the API documentation, it is necessary to generate some
Web pages from the Python source code. For this, the epydoc application must
be available on your system. Then, inside the distribution directory, run the
apidocs.sh tool script as follows:

./tools/apidocs.sh

Some warnings may be generated by the script, but the result should be a new
apidocs directory within the distribution directory.

Making Packages
---------------

To make Debian-based packages:

  1. Create new package directories under packages if necessary.
  2. Make a symbolic link in the distribution's root directory to keep the
     Debian tools happy:

     ln -s packages/ubuntu-hoary/python2.4-jailtools/debian/

  3. Run the package builder:

     dpkg-buildpackage -rfakeroot

  4. Locate and tidy up the packages in the parent directory of the
     distribution's root directory.
