JailTools - create and manage jails (containers)

What is JailTools?

It’s a tool to isolate programs from your host system. So called jails contain a directory structure similar to a normal OS (they contains /home, /etc, /dev, etc) and it is possible to control internet access for the programs inside the jail (you can easily remove internet access from jails).

What is JailTools in technical terms?

It provides a slim OS-level virtualization solution for the GNU/linux operating system. It uses linux’s chroot and namespace features.

Purpose

As is, chroots are a pain to setup manually, you have to create a basic directory structure and copy over the dependencies of the program you want to use (especially if it’s a dynamically linked program/library).

JailTools makes that process easy by automating most of the work and then provides means to interface with jails.

It has tools for copying applications and libraries to the jail, so as to also copy the shared objects they depend on to run correctly.

JailTools creates a minimal filesystem (about 2MB in size) which is meant to include only the bare minimum for applications or libraries to do their job. This way, in case the service is compromized, adversaries will only get access to that filesystem rather than the host system directly.

Also, jailTools makes it trivial to "re-enter" an already started jail and start jails as a daemon.

Compilation and Installation

JailTools relies on busybox and to compile busybox the slim musl libc library is used. Busybox is compiled statically to limit to a maximum the amount of shared objects required for bare jails. JailTools is now embedded as script command inside the compiled busybox (which we renamed 'jt'). It is possible to call busybox from the 'jt' executable by doing : jt busybox <command>

Quick steps :

1. compilation requirements: git, gcc, GNU make (and GNU autotools as some of the extra dependencies rely on them)

2. get the source code with git clone https://github.com/nniro/jailTools

3. alternatively, you can recursively get all the dependencies and extra tools by doing : git clone --recurse-submodules https://github.com/nniro/jailTools

4. make will download, configure and compile musl and busybox.

5. install the super script with install.sh

Elaborated steps :

Step 1:

Get jailTools from the git repository:

git clone https://github.com/nniro/jailTools

This will clone the git repository to the directory jailTools.

Step 2:

The project relies on musl (libc) and busybox. The latter provides the underlying filesystem shell and commands inside each jail. Both of these dependencies are automatically cloned by the Makefile process. We don’t use already installed versions because we want statically linked versions of both of these to save space.

To compile, just run make. This will compile musl and then use it to statically link busybox.

Step 3:

The installation script install.sh will copy the super script jt to a location of your choice. It only installs the super script, not the whole jailTools directory.

If you want to use jailTools for your user only, just clone the git repository, compile and do this:

sh ./install.sh ~/bin

This will install the super script inside your user’s bin directory. Make sure that you have /home/<youruser>/bin in your "PATH" environment variable.

System wide installation:

In case you want to make the project available for all users on the system. These are the steps to do so.

Important

No longer true, see next "Important" block --- It is currently not possible to start jails or access them in any matter that does not require super user privileges. This means that users would need root access in order to fully use jails created with jailTools. The only way an unprivileged user could access a started jail is through network services like telnet or ssh.

Important

It is now possible to run jails as an unprivileged user when the linux user namespace is available. Note however that not all features work in that case. It is also possible to run a new shell from an already running jail even as an unprivileged user. This is actually the recommended way : First start a jail as a daemon or just with start (this will setup superuser only features for the jail) with a privileged user and then you can access the jail with an unprivileged user with the shell command to start your applications.

just do :

sudo sh install.sh /usr/local/bin

Usage

Here is a list of available commands when calling jt:

• new

  creates a new jail directory

• cp

  copy files or directories (with their shared object dependencies) into the jail

• start, stop, daemon, shell All take the <path> argument

  these are per jail specific commands. You can provide these with a single argument which is the path of the jail to run this command.

Creating a new jail

Synopsis :

jt new <path and name> <optional jail's main username> <optional jail's main group>

Both internal username and group are used inside the jail itself, and will be added to /etc/\{passwd,shadow\} and /etc/group respectively, inside the chroot. The main user will be exactly the same UID as the user that created the jail, same goes for the group. If they are not explicitely added, they will be created with the same name as the jail.

Important

The jail name is initially the directory in which the jail resides. That name can be changed inside the configuration file rootCustomConfig.sh.

Example :

jt new /path/to/example foo bar

This will create a new directory called example containing the jail and once running, the user’s UID and GID will be mapped to foo and bar respectively. Inside the jail directory /path/to/example there are 3 notable scripts : . startRoot.sh (don’t run this directly, use the super script jt) . rootCustomConfig.sh (where you place your configuration and custom scripting) . update.sh (this contains the files which are copied by the cp or cpDep command so you can reproduce and update your jail)

The script startRoot.sh is not meant to be edited. Make your changes in the script rootCustomConfig.sh.

As is, the jailTools creates a jail with only basic apps and a shell (provided by busybox).

Jail commands

A newly created jail includes 2 ways to start the chroot :

• sudo jt start

  This starts the jail and provides you with an interactive shell inside it.

Tip	You usually want to make this start your programs automatically. This is mostly for applications like firefox, games or anything that you use directly.

• sudo jt daemon

  This starts the jail in daemon mode. When started, the jailed is
  placed in the background and puts you back into the calling shell.
  It will stay running even after you close your terminal.
  The only way to gain access is through the shell command or,
  if available, network shell providers like ssh or telnet.

Tip	You usually want to make this start your services automatically. This is mostly for starting servers and any application that run in the background.

Tip

It’s also a good idea to start your jail with sudo jt daemon as is and then you can, as an unprivileged user start your program with jt shell <command>; starting the daemon with sudo makes it possible to setup the firewall and set the networking parameters. All that is left is to start programs that require those accesses as your normal user (using jt shell <command>).

How to install applications in a jail

To add more applications to the jail, use jt cp command.

Here we show how to copy the application strace to the jail :

jt cp /usr/bin /usr/bin/strace    # this is done inside the jail directory itself

Here’s what the arguments mean :

• /usr/bin

  The first path is actually the destination path *inside* the jail that you want
  to copy your binary to. We could have put /bin if we wanted or any path you
  want (as long as you take care of setting the PATH correctly in the jail).

• /usr/bin/strace

  This is the path on your base system for the strace application, which, in our
  case is in our /usr/bin directory.

cp will check all shared object dependencies that strace requires to run and copy them along with the binary itself. This way, you will be able to run the application without doing any more work than that.

Important

Certain applications also requires specific devices (in /dev) and/or directories to be present, the command cp can not provide those. You will need to figure these either from the manual of these programs or by using the strace program (we purposefully shown how to copy it to a jail for this reason).

What a created jail contains

Although the content changes from time to time with development, at this moment, a created jail contains these files and directories :

• root/

  This directory contains the filesystem of the underlying jail.

• rootCustomConfig.sh

  The primary configuration file of the jail. This is where you can configure your jails.
  You can either edit this file manually or use the 'jt config' command.

• rootDefaultConfig.sh

  The default configuration file for the jail. It is not to be edited.
  You values presented in this section have to be modified in rootCustomConfig.sh, in the section 'Configuration'.

• run/

  Contains logs, pids and anything else in relation to the jail.
  It is safe to add more files to this directory.

• jailLib.sh

  This is the library for the various functions available to jails. It is not meant to be called directly.

• startRoot.sh

  This contains the jail startup code and it is not meant to be called directly anymore. Use the command 'jt'
  to interact with the jail.

• update.sh

  This contains the commands that was used to copy files over to the jail with the 'jt cp' command.
  It was meant to make it easy to redo the same commands in the future to install newer versions of the
  applications. It is somewhat deprecated.

How to Customize the jail

There are 5 vectors of customization for jails. Each in their own section in rootCustomConfig.sh.

They are :

1. The configuration variables/flags

   These are used to toggle features provided in the jail and set various values
   for configurating for example : the network IP of the jail and if the jail should get internet access.

2. The jail commands

   It is possible to customize what program to start with the 3 start points of jails : start, daemon and shell.
   (Do note that "shell" does not start a jail but rejoins an already started jail)

3. The mount points

   These are used specifically to mount external directories inside the jail itself,
   making the files/directories accessible to the jailed applications. There are 4 kinds
   of mount points each with their section.

4. Bridge

   You can join a bridge using the parameters of this section. Starting a bridge is done in the first section.

5. Firewall

   You can set what firewall rules you want applied to the jail, internally or externally (external is on the host system)