Chroot in OpenSSH

You may have seen the recent commit message from djm@ about the new feature in OpenSSH: ChrootDirectory

Damien Miller (djm@), who worked on this new feature with Markus Friedl (markus@), offers more details about ChrootDirectory:

This commit adds a chroot(2) facility to sshd, controlled by a new sshd_config(5) option "ChrootDirectory". This can be used to "jail" users into a limited view of the filesystem, such as their home directory, rather than letting them see the full filesystem.

More from Damien follows.

Unfortunately, setting up a chroot(2) environment is complicated, fragile and annoying to maintain. The most frequent reason our users have given when asking for chroot support in sshd is so they can set up file servers that limit semi-trusted users to be able to access certain files only. Because of this, we have made this particular case very easy to configure.

In a previous commit, markus@ implemented an "in-process" sftp server in sshd, basically linking sftp-server(8) into sshd(8). When the in-process sftp server is used, sshd does not need any special chroot configuration (no /dev nodes, no libraries, no statically-linked sftp-server) so the chroot setup and maintenance burden is eliminated. The chroot support does work for login and command-execution sessions too, but administrators will need to configure the chroot environment manually.

To set up a restricted sftp server one should use the "ForceCommand" and "ChrootDirectory" directives in sshd_config. Presumably most people will not want to restrict every user, so they should also use the "Match" directive to select a user or group to apply the restrictions to. For example:

Match user djm
    ForceCommand internal-sftp
    ChrootDirectory /chroot

This will cause the user 'djm' to be chrooted to the "/chroot" directory at login, and the use of the in-process sftp server will be forced for all connections. I.e. the user will not be able to login interactively, or run arbitrary commands - the login will only be useful for sftp transfers. Note that the user's home directory may exist under the "/chroot" directory above (e.g. "/chroot/home/djm") and sshd will try to chdir to it before starting to serve files, but it doesn't matter if it does not exist.

Setting up a safe chroot jail is somewhat tricky, and it is quite easy to make to compromise one's security. To reduce this risk, sshd ensures the ChrootDirectory and each of its components is root-owned and not writable by other users, but it is still possible for administrators to break their own setups by doing dumb things (e.g. leaving /dev nodes for the physical drives in a chroot, executing scripts inside the chroot from cron(8) or elsewhere, etc.).

A limitation of the chroot support is that the in-process sftp server does not support scp(1) transfers. scp is a really busted protocol and it would be a fair bit more work to build it in in the way we have built in sftp. It is still possible to support chrooted scp, but administrators will need to populate the chroot environment manually. Please use sftp instead.

To make the internal-sftp chroot work for me, I made the following changes to /etc/ssh/sshd_config:

#Subsystem      sftp    /usr/libexec/sftp-server
Subsystem       sftp    internal-sftp

The full commit message:

CVSROOT:        /cvs
Module name:    src
Changes by:     djm@     2008/02/08 16:24:08

Modified files:
        usr.bin/ssh    : sshd_config.5 sshd_config sftp.h sftp-server.c
                         sftp-server-main.c session.c servconf.h
                         servconf.c

Log message:
add sshd_config ChrootDirectory option to chroot(2) users to a directory and
tweak internal sftp server to work with it (no special files in chroot
required). ok markus@

Thanks to Damien Miller for taking the time to explain the ChrootDirectory feature.