Gentoo Wiki




The content of this page is old and probably wrong. Someone who knows how to use Wiki should probably should move the content after a little clean up from Talk:HOWTO_chroot_login here. The usage of instead of the chrootshell is much safer and better.


This HOWTO details creating accounts on a Linux operating system that are chroot'ed to their home directory. That is, when this user logs in, they will not be able to access any other part of the filesystem(s) other than what lies in the account's home directory.

Warning: from a security point of view this chroot setup has several flaws:

For a more secure chroot login you might want to look at Jailkit

There is another easy to use tool in portage, similiar to jailkit, i wrote a howto for it: HOWTO_Jail --the_mgt 12:48, 17 September 2005 (GMT)
I also added an ebuild for the JailKit software here: HOWTO_JailKit --the_mgt 17:53, 18 September 2005 (GMT)



When a login is attempted, this is the course of events:

login -> sudo(root) -> chroot $HOME -> su $USER

Essentially what this means is that when a login is attempted, the user is authenticated in the normal way. After successful authentication, the login process passes the user to what it assumes is a shell, but in fact, it will be passing the user to a series of programs that will turn the user into root, chroot them into their directory, then turn the user back into himself again.


Step-By-Step Process

Make a faux-shell

Reminder: it is possible to break out of this chroot script using the chdir() hack! Use jk_chrootsh if you want to create a chroot shell for security reasons!

I call it /bin/chroot-shell. Here is the shell script I use:

File: /bin/chroot-shell
if [ "$1" = "-c" ]; then
       for param in $*; do
               if [ $i -gt 0 ]; then
                       PARAMS="$PARAMS $param";
               let i++;
       sudo /usr/sbin/chroot /home/$USER /bin/su - $USER -c "$PARAMS"
       sudo /usr/sbin/chroot /home/$USER /bin/su - $USER

If you do not have bash, you can use this sh compatible chroot-shell:

#Thanks to Ben Okopnik for this more simplified and compatible version of chroot-shell
[ "$1" = "-c" ] && a="$*"
sudo /usr/sbin/chroot /home/$USER /bin/su - $USER $a

NOTE: This will not work if you need to run commands with spaces in them on login (e.g. scp)

Dont forget to add /bin/chroot-shell in /etc/shells and chmod 755 /bin/chroot-shell!

Add a user

useradd -d /tmp -s /bin/chroot-shell peon

This makes an entry in the /etc/passwd file like this:


You should also set the password for the new account at this time:

passwd peon

Create a home directory

mkdir /home/peon
mkdir /home/peon/etc
mkdir /home/peon/dev
mkdir /home/peon/bin
mkdir /home/peon/lib
mkdir /home/peon/usr
mkdir /home/peon/usr/bin
mkdir /home/peon/home
chown peon:peon /home/peon/home

Create a chroot passwd and group file


Install bash

cp /bin/bash /home/peon/bin/

Unless you have a statically linked version of bash (which is doubtful), you'll have to copy the required libraries to /home/peon/lib. To find out what libraries are required, use ldd:

ldd /bin/bash

Useful tools to automatically copy a binary and all it's libraries to a chroot jail are jk_cp and jk_init from the Jailkit project.

Install su

cp /bin/su /home/peon/bin/

Unless you have a statically linked version of su (which is doubtful), you'll have to copy the required libraries to /home/peon/lib. To find out what libraries are required, use ldd:

ldd /bin/su

NOTE: on glibc systems, all name service plugins, such as /lib/ should be copied to the jail as well. If you want this automatically done, use jk_init from the Jailkit project.

NOTE: If your su binary uses PAM for an authentication mechanism, you may have to build a new su binary. This is the case for RedHat. Thanks to Pablo Pasqualino for pointing this out.

NOTE: On RedHat 7.x systems, not only do you have to build a new su binary but you must copy /lib/ and /lib/ (as well as /lib/ to the chroot /lib directory even though they don't show up in 'ldd su'. Thanks to Arnstein Ressem and others for figuring this out.

NOTE: Newer versions of the coreutils do exist, check the ftp for the one the fits your needs.

In the event you have to build a new su binary (required under Gentoo), do the following:

cd /usr/src
tar zxvf coreutils-5.2.0.tar.gz
ln -s coreutils-5.2.0 coreutils
cd coreutils
cp src/su /home/peon/bin/

Erick Turnquist contributed the following (untested) command for automating the copying of linked libraries. For example, for /bin/su:

ldd /bin/su | awk '{ print $3; }' | sed 's/\(\/.*\/\(.*\)\)/\1 \2/g' -\
| xargs -l1 --no-run-if-empty cp

Install fileutils (optional)

(cd /bin; cp ln ls rm mv cp du /home/peon/bin/)

The same goes for libs if you don't want to compile fileutils staticly, just use ldd <executable> to find out which shared libs you need to copy to /home/peon/lib.

Install OpenSSH (optional)

cp /usr/bin/ssh /home/peon/usr/bin/
cp /usr/bin/scp /home/peon/usr/bin/
cp /usr/bin/env /home/peon/usr/bin/

The same goes for libs if you don't want to compile OpenSSH staticly, just use ldd <executable> to find out which shared libs you need to copy to /home/peon/lib.

Open SSH also needs a couple of devices to function properly. Make them like this:

mknod -m 0666 /home/peon/dev/tty c 5 0
mknod -m 0644 /home/peon/dev/urandom c 1 9

Grant sudo access to the new account

If you are familiar with vi, I suggest just typing visudo. If not, you can set the environment variable EDITOR prior execute visudo.

Add a line like the following:

peon  ALL= NOPASSWD: /usr/sbin/chroot /home/peon /bin/su - peon*

Then, copy chroot binary to /usr/sbin :

cp /bin/chroot /usr/sbin/

SCP/SFTP without shell access

Those of you wanting to set up SCP/SFTP access without giving those users access to a shell may want to look at the scponly package. scponly has an option --enable-chrooted-binary which allows for chroot configurations. Another useful tool is jk_lsh from the Jailkit project, which is a shell that can be configured to allow only a small set of binaries, for example only sftp and scp, but other possibilities are cvs, rsync or subversion.

Those using scponly on Linux with x86 or ppc hardware may also be interested in my scpjailer project. It sets up all the files necessary for chroot SCP/SFTP using tiny static binaries.



I had trouble using this guide. It didn't work correctly if I followd the above listed instructions. There's another guide which works: Maybe this page should be reviewed.

Retrieved from ""

Last modified: Wed, 06 Aug 2008 09:44:00 +0000 Hits: 25,483