Chrooted SSH/SFTP Tutorial (Debian Lenny)

Version 1.0
Author: Falko Timme <ft [at] falkotimme [dot] com>
Last edited 03/03/2009

Since version 4.8, OpenSSH supports chrooting (see http://openssh.org/txt/release-4.8), so no patches are needed anymore. This tutorial describes how to give users chrooted SSH access. With this setup, you can give your users shell access without having to fear that they can see your whole system. Your users will be jailed in a specific directory which they will not be able to break out of. I will also show how to use chrooted SFTP.

I do not issue any guarantee that this will work for you!

1 Preliminary Note

The OpenSSH version coming with Debian Lenny is 5.1p1, so it supports chrooting.

I will use the user falko here with the home directory /home/falko. The user falko belongs to the group users. I want to chroot the user to the /home directory.

2 Installing OpenSSH

If OpenSSH is not already installed, install it as follows:

apt-get install ssh openssh-server

3 Enabling Chrooted SFTP

Enabling SFTP is very easy. Open /etc/ssh/sshd_config...

vi /etc/ssh/sshd_config

... and make sure you have the following line in it:

[...]
Subsystem sftp /usr/lib/openssh/sftp-server
[...]

Then add the following stanza at the end of the file (add such a stanza for each user that you want to chroot):

[...]
Match User falko
    ChrootDirectory /home
    AllowTCPForwarding no
    X11Forwarding no
    ForceCommand /usr/lib/openssh/sftp-server

Instead of adding a stanza for each user, you can also chroot groups, e.g. as follows:

[...]
Match Group users
    ChrootDirectory /home
    AllowTCPForwarding no
    X11Forwarding no
    ForceCommand /usr/lib/openssh/sftp-server

This would chroot all members of the users group to the /home directory.

Restart OpenSSH:

/etc/init.d/ssh restart

If you chroot multiple users to the same directory, but don't want the users to browse the home directories of the other users, you can change the permissions of each home directory as follows:

chmod 700 /home/falko

Afterwards, you can log in with an SFTP client, such as FileZilla or WinSCP.

4 Enabling Chrooted SSH

Enabling chrooted SSH is a bit more complicated because we must set up a chroot environment with all programs/tools (e.g. /bin/bash, /bin/cp, etc.) that the users should be able to use. This means we must also copy all libraries that these programs need to the chroot jail. You can do this manually with the cp command, and you can find out what libraries a tool needs by using the ldd command, e.g.

ldd /bin/bash

We also have to create some devices such as /dev/null, /dev/zero, /dev/tty, and /dev/urandom inside the chroot jail with the mknod command.

However, this can be a tedious task. Fortunately, there's a script that can do this for us.

First, we need to install some prerequisites:

apt-get install sudo debianutils coreutils

Then we download make_chroot_jail.sh to /usr/local/sbin and make it executable for the root user:

cd /usr/local/sbin
wget http://www.fuschlberger.net/programs/ssh-scp-sftp-chroot-jail/make_chroot_jail.sh
chmod 700 /usr/local/sbin/make_chroot_jail.sh

Before we use the script, you might want to add some programs (e.g. such as /usr/bin/vi) to the APPS line of your distribution in that script so that these tools get added to the chroot jail automatically:

vi /usr/local/sbin/make_chroot_jail.sh

[...]
elif [ "$DISTRO" = DEBIAN ]; then
  APPS="/bin/bash /bin/cp /usr/bin/dircolors /bin/ls /bin/mkdir /bin/mv /bin/rm /bin/rmdir /bin/sh /bin/su /usr/bin/groups /usr/bin/id /usr/bin/rsync /usr/bin/ssh /usr/bin/scp /sbin/unix_chkpwd /usr/bin/vi"
else
[...]

Next we add a symlink /home/home that points back to /home:

cd /home
ln -s . home

Now we can already use the script. Usage is as follows:

make_chroot_jail.sh username [/path/to/chroot-shell [/path/to/chroot]]

chroot-shell is a special shell created by the script to chroot users. Since OpenSSH now supports chrooting by default, we don't need the script to create a special shell; instead, we can use /bin/bash or /bin/sh.

It doesn't matter if the user is already existing or not. If he's existing, he will be updated; if not, he will be created.

make_chroot_jail.sh falko /bin/bash /home

This will create/update the user falko with the chroot jail /home.

To update all files/libraries in the chroot jail, run

make_chroot_jail.sh update /bin/bash /home

Now we need to configure OpenSSH which is similar to the SFTP configuration. Open /etc/ssh/sshd_config...

vi /etc/ssh/sshd_config

... and add the following stanza at the end of the file (add such a stanza for each user that you want to chroot):

[...]
Match User falko
    ChrootDirectory /home
    AllowTCPForwarding no
    X11Forwarding no

Instead of adding a stanza for each user, you can also chroot groups, e.g. as follows:

[...]
Match Group users
    ChrootDirectory /home
    AllowTCPForwarding no
    X11Forwarding no

This would chroot all members of the users group to the /home directory.

The difference to the SFTP configuration is that this time, we must not use the line ForceCommand /usr/lib/openssh/sftp-server in the Match stanzas! This makes that users can still use chrooted SFTP (provided you also have the line Subsystem sftp /usr/lib/openssh/sftp-server in /etc/ssh/sshd_config), but also chrooted SSH.

Restart OpenSSH:

/etc/init.d/ssh restart

If you chroot multiple users to the same directory, but don't want the users to browse the home directories of the other users, you can change the permissions of each home directory as follows:

chmod 700 /home/falko

Afterwards, you can log in with with an SSH client such as PuTTY.

5 Links

• OpenSSH: http://www.openssh.org
• make_chroot_jail.sh: http://www.fuschlberger.net/programs/ssh-scp-sftp-chroot-jail
• Debian: http://www.debian.org