Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc


Introduction to Jail

The Jail Chroot Project is an attempt to write a tool that builds a chrooted environment. Much of the following is based closely on the documentation provided at the Program's original homepage.

You can just chroot any user who logs in on your server into their home directory, or you can run some services as FTP or SSHD there. The main goal of Jail is to be as simple as possible, and highly portable.

The most difficult steps when building a chrooted environment is to set up the right libraries and files. Jail comes to the rescue with a tool that automagically configures and builds all the required files, directories and libraries.

Jail is licensed under the GNU General Public License. The Jail program has been written using C, and the setup script has been written using bash scripting and perl.

Jail supports lots of interesting features:


Jail is very easy to use, but when it comes to security, you should not put all your trust in a single program or script but instead you should thoroughly investigate all the aspects that contribute to a secure system. The documentation provided by the Hardened Gentoo Project is a good place to start.

You should inform yourself about chrooted environments. There are ways to break out. Particularly important is not to run programs as a root user in a jail and avoid software which is set with setuid. The following external articles give more information on these points:

How jail interacts with the login process

Before we configure Jail, it is wise to know a little about how Jail works.

As you can see in the following diagram, Jail begins by obtaining the user's information from the non-chrooted /etc/passwd. This file indicates that Jail is activated for a user and it also specifies the target directory of the chroot. Jail is activated by using the file "jail" as the user shell in the non-chrooted environment.

Example: prisoner:x:1005:100:Jail Test User:/var/chroot:/usr/bin/jail

When the user logs in, Jail changes the directory to the one specified in the the non-chrooted passwd file and then calls chroot from this directory, thus creating the chrooted environment. After this call, Jail can only see the files under the chrooted directory. Jail then sets up some environment variables, i.e. the HOME and the SHELL variable that will be used by the real shell.

Jail then gets the user's information from the /etc/passwd file in the chrooted environment, and checks if the user home directory is the same as the user home directory information that was read from the non-chrooted file. If they are the same, then the HOME variable is set to '/'. Otherwise Jail changes to this directory, and changes the HOME variable to this one.

Lastly, Jail sets up enviroment variables again, SHELL is set up with the information read from the chrooted /etc/passwd file. Jail replaces itself with the shell program stored in the SHELL variable, runing the shell.

This is the whole process step-by-step:

Start by emerging it

# emerge -va jail

Adding a normal system user with useradd

We will need the system user in both environments, so first we add him to the unrestricted environment. Our nick name for the test user used in the examples will be prisoner. All the magic resides on the /etc/passwd file. The line in this file has to fit the uid an gid fields password, etc. The line should look something like this:

prisoner:x:1005:100:Jail Test User:/var/chroot:/usr/bin/jail

Note the /var/chroot field. This is the root directory of the chroot environment for this user.
All we need to do with gentoo is this:

# useradd -g users -d /var/chroot/ -s /usr/bin/jail prisoner

Creating the Jail environment Or how to invoke mkjailenv

mkjailenv creates the directories, and generates the basic filesystem layout with the special devices. mkjailenv has been written in perl.

This are the command line arguments:
mkjailenv chrootdir
Argument Description
chrootdir   The directory where the chrooted environment will live.
                     It its the home entry in the non-chrooted /etc/passwd file.

Invocation example:

# mkjailenv /var/chroot

This will create the chrooted enviroment under the directory /var/chroot.

Adding users to the Jail Or how to invoke addjailuser

The tool addjailuser edits the chrooted /etc/passwd automatically and creates the user directories. Addjailuser has been written in perl script.

These are the command line arguments:
addjailuser chrootdir userdir usershell username
Argument Description
chrootdir   The directory where the chrooted environment will live.
                    It its the home entry in the non-chrooted /etc/passwd file
userdir     The directory inside the chrooted enviroment when the user will live, in our example,               
usershell   The user's shell full path (e.g. /bin/bash)
username    The user's name.

In our example, Userinvocation would look like this:

# addjailuser  /var/chroot /home/prisoner /bin/bash prisoner

This will add a user under the directory /var/chroot setups the home directory of the prisoner into /home/prisoner, and selects /bin/bash as default shell for the user prisoner. Also edits the chrooted /etc/passwd, /etc/group and /etc/shadow to configure the jail properly.

Adding software to Jail Or how to invoke addjailsw

The tool addjailsw will copy programs and their dependencies (libraries, auxiliar files, special devices) into the right places in the chrooted environment. addjailsw has been written in perl.

These are the command line arguments:
addjailsw chrootdir [-D] [-P program args]
Argument Description
chrootdir   The directory where the chrooted environment will live.
                     It its the home entry in the non-chrooted / etc/passwd file
-P program args (optional)   installs the specific program "program" into the chrooted environment.
                             The script uses the "args" parameter to launch the program where doing
                             the strace command, to allows the program exit nicely, so the strace can do its work.
                             If this parameter isn?t specified, the standard programs included in the file will be installed.
                             See addjailsw?s code for in-deep details.

Invocation examples:

# addjailsw /var/chroot


# addjailsw /var/chroot -D


# addjailsw /var/chroot -P bash "--version"

The first example will add the standard programs under the /var/choot directory.
The second example will do the same as the first, but will also show which files are going to be copied in /var/chroot.
The third example will install the program bash, and when launched in the strace call, the argument "--version" will be passed to it (so bash will exit immediately). You will definetly need a bash, if you want to login to the chroot jail!!

Note: The software you add must run AND terminate, or else addjailsw won't finish! (You can kill the started application from another console, if you need to.)

Gentoo specific

For some reason, the addjailsw tool does not fetch the, which leads to the error "execve(): File or Directory doesn't exist", so we copy it manually.

# cp /lib/ /var/chroot/lib/

but if architecture is amd64 then

# mkdir -p /var/chroot/lib64; cp /lib64/ /var/chroot/lib64/

That's all, folks! Now you can add whatever you want to the chroot. You can even start another chrooted environment in another directory.

Tip: Add /etc/bash/bashrc, /etc/DIR_COLORS, /etc/profile and the program "whoami" to the chrooted jail, if you want a nicer looking and working shell
mkdir /var/chroot/etc/bash 
cp /etc/bash/bashrc /var/chroot/etc/bash/
cp /etc/profile /var/chroot/etc/
cp /etc/DIR_COLORS /var/chroot/etc/
addjailsw /var/chroot -P whoami

If the chroot environment can access IP address but no domain-name ("Name or service not known") :

# cp -a /lib/libnss_dns* lib/

Screen in your jail

If you want to run a screen in your jail you must mount the /dev and /dev/pts filesystem in your jail.

# mount -o bind /dev /var/chroot/dev


# mount -t devpts none /var/chroot/dev/pts

I did need these too (not sure about security but works):

# mkdir /var/chroot/proc
# mount -t proc proc /var/chroot/proc


Instructions for running the irssi irc client in a chroot jail can be found here.

If you get an error message like

setupterm() failed for TERM=xterm: 0
Can't initialize screen handling, quitting.
You can still use the dummy mode with -d parameter

Then try running irssi under a Screen session.

You can find the IP addresses with

# emerge host


# hostx

outside the jail.

You may also need to do something like

# cp -r /usr/lib64/perl5/* /var/chroot/usr/lib64/perl5/

to get extra irssi scripts working.


-Thanks to Juan M. Casillas for the program!

-the_mgt made this Gentoo-wiki version of the guide.

Retrieved from ""

Last modified: Fri, 05 Sep 2008 10:25:00 +0000 Hits: 19,176