jailtime Build Status

jailtime is a command-line utility to create and manage chroot/jail environments. Why is this useful? jailtime helps to

  • create restricted SSH logins that only allow scp or git, etc.
  • build a Docker image without all the clutter of a fat base image based on a full Linux distribution.
  • restrict daemons into a filesystem sub-tree to enhance security.

Table of Contents


  • Go version 1.3 or later
  • Git version 1.7 or later
  • Optional: GNU Make
  • Currently only runs on 32-bit or 64-bit x86 Linux

How to Build

General way to build from source via go get:

go get
Build the old-fashioned Way

To build from a specific revision/branch/tag, not using go get:

mkdir -p jailtime && cd jailtime
git clone .
# Optional: checkout a specific rev./branch/tag using i.e. git checkout
eval $(make env)

You may want to create a symlink to the binary somewhere in your path.

How to Use

jailtime creates/updates a target chroot directory from an existing jail specification (see next section). The general invocation syntax is:

jailtime <one or more jailspec files> <target dir>

Multiple jailspec files will be merged and their statements applied in order.

To get started with a rather basic chroot that allows to run Bash interactively, see the files in the examples/ directory. For the basic shell example:

jailtime examples/basic_shell.jailspec chroot_dir

This will copy (among other files) your local /bin/bash to chroot_dir/bin/bash and copy its library dependencies as well. On a Debian Jessie system, the resulting tree looks like this:

+- bin/
|  +- bash  cat  chgrp  chmod  chown  cp  cpio  date  dd  df  dir  ...
+- lib/x86_64-linux-gnu/
|  +-
+- lib64/
|  +-
+- usr/bin/
   +- arch  awk  base64  basename  cksum  csplit  cut  dircolors  ...
Writing Jail Specifications

Jail specification files such as examples/basic_shell.jailspec follow a text format with a few special directives. To start with a simple example:

# This is a single line comment. Blank lines and additional whitespace will be
# ignored.

# This copies the host file /bin/bash into the chroot. It also copies all
# library dependencies.

When copying files, you can also specify the target:

# Copies /bin/bash to <chroot>/bin/sh.
/bin/bash /bin/sh

Instead of creating a copy, you can also create a (sym-)link:

# Copy bash to <chroot>/bin/bash and create a symlink from <chroot>/bin/sh to
# <chroot>/bin/bash
/bin/sh -> /bin/bash

# Hardlinks are created with a fat arrow `=>':
/bin/bash_again => /bin/bash

Some programs will likely need a few special device files in order to function. They are created similar to normal files:

# Creates the two devices /dev/null and /dev/zero.
/dev/null c 1 3
/dev/zero c 1 5

Note: Device creation will most likely require jailtime to be run as root.

To change file permissions inside the chroot, use a 'run' directive:

# Careful not to omit the leading `.'
run chmod 666 ./dev/null

The run directive will execute the text following the run keyword in a shell with the chroot directory set as its current directory. Note: In the future, you will be able to directly specify file permissions in the jail specification.

Empty directories are created when the path name ends with a slash ('/'). There is also a shorthand to create multiple directories, similar to Bash syntax:

# Creates /srv and /srv/nfs
# Expands to /srv/nfs/alice/.ssh/ and /srv/nfs/bob/.ssh/ and creates these
# directories.

Jail specifications can also include other jail specifications:

include python27.jailspec

The include will be relative to the current specification file and file inclusion may be nested up to 8 levels deep. Run statements are executed in order and later specifications override earlier ones.

Entering a chroot

On most systems, entering a chroot environment requires root or at least administrative privileges. If sudo is installed, you can create and enter a chroot with a basic shell like this:

jailtime examples/basic_shell.jailspec chroot_dir
sudo chroot chroot_dir

If you are on a system with systemd (most Linux systems nowadays), you can also easily create a lightweight container:

sudo systemd-nspawn -D chroot_dir/ /bin/bash

This uses the same underlying technique as Docker, Linux Containers (LXC), and allows for greater isolation.

FreeBSD derived systems also have the jail utility, which serves a similar purpose.


  • Cannot specify the file permissions in jail specifications
  • Error messages could be more specific
  • Does not run on OS X or any of the BSDs

Similar Tools

These tools serve a similar purpose or are somewhat related:

  • Jailkit, this also supports checking chroots for security problems and launching daemons inside a chroot. In its current form, jailtime corresponds mostly to jk_cp, the utility to copy files and their dependencies to a chroot directory.
  • copy_exec from initramfs-tools, this also copies files and with their library dependencies.
  • schroot, used to execute commands or interactive shells in different chroot environments. It also supports BTRFS and LVM snapshots as well as on-the-fly chroots unpacked from tar files.
  • debootstrap, this can install Debian-based distributions into a filesystem directory which then can be used as a chroot.

jailtime version 0.3 Copyright (c)2015-2017 Christian Blichmann

jailtime is licensed under a two-clause BSD license, see the LICENSE file for details.

Expand ▾ Collapse ▴


The Go Gopher

There is no documentation for this package.

Source Files


Path Synopsis