Open Source

Chroot users with OpenSSH: An easier way to confine users to their home directories

With the release of OpenSSH 4.9p1, you no longer have to rely on third-party hacks or complicated chroot setups to confine users to their home directories or give them access to SFTP services. Vincent Danen tells you how to take advantage of this new addition to OpenSSH.

With previous versions of OpenSSH, the only way to confine users to their home directories was with third-party hacks or elaborate chroot setups. The recently-released 4.9p1 release of OpenSSH, however, provides the ability to chroot users without the use of third-party add-ons; a welcome addition to this powerful tool.

As well, providing SFTP services that restricts users to their home directory is much simpler now.

To begin, ensure you have OpenSSH 4.9p1 or newer installed. Then edit /etc/ssh/sshd_config (/etc/sshd_config on some distributions) and set the following options:

Subsystem     sftp   internal-sftp
Match Group sftp
    ChrootDirectory %h
    ForceCommand internal-sftp
    AllowTcpForwarding no

Ensure the "Match" directive is at the end of the file. This tells OpenSSH that all users in the sftp group are to be chrooted to their home directory (which %h represents in the ChrootDirectory command), forces the use of the internal-sftp helper, and disables TCP port forwarding. The Subsystem command previously enabled is required to enable the use of the SFTP subsystem. This can either be a path to the sftp-server helper, or the internal-sftp, but for the purpose of chrooting, the internal-sftp command works better and doesn't require a shell or libraries installed in the chroot.

For any users that you wish to chroot, add them to the sftp group by using:

# usermod -G sftp joe
# usermod -s /bin/false joe
# chown root:root /home/joe
# chmod 0755 /home/joe

The usermod command above will add user joe to the sftp group and set their shell to /bin/false so they absolutely cannot ever get shell access. The chown and chmod commands will set the required permissions for the directory. With these permissions set, the user will be allowed to upload and download files, but cannot create directories or files in the root directory. In other words, if this is used for Web hosting, ensure that a subdirectory in the root directory, such as /home/joe/public_html/ is available and owned by the user; this way they can write to and create directories in /home/joe/public_html/, but cannot make changes to the root directory (/home/joe), itself.

Chrooting shell accounts is a little more complicated as it requires that certain device files and a shell be available in the user's home directory. The following commands will set up a very basic chroot system on Mandriva Linux:

# mkdir /chroot
# cd /chroot
# mkdir {bin,dev,lib}
# cp -p /bin/bash bin/
# cp -p /lib/{,,,} lib/
# mknod dev/null c 1 3
# mknod dev/zero c 1 5
# chmod 0666 dev/{null,zero}
# mkdir -p /chroot/home/joe

With the above, user joe can ssh in and will be restricted to the chroot. Unfortunately, this doesn't do much, but it gives you an idea of how it can be set up. Depending on what you want to provide, you will need to install additional libraries and binaries. One idea might be to have a chroot setup that is a minimal distribution install. For instance, with Mandriva you can install a second copy of the operating system using urpmi in the /chroot directory. All authentication information is taken from the host, so there is no need to create and maintain user passwords inside the chroot, and this would allow for another degree of separation from the main/host operating system to where users are permitted access, effectively jailing them inside a second OS with limited tools and functionality.

Of the two, chrooted SFTP is the easiest to set up and maintain and is likely sufficient for most remote access use.

Get the PDF version of this tip.


Vincent Danen works on the Red Hat Security Response Team and lives in Canada. He has been writing about and developing on Linux for over 10 years and is a veteran Mac user.

Editor's Picks