Skip to main content

How to set up Linux chroot jails

Interested in using containers to isolate processes? Then explore the world of chroot jails: the original containers.
"P6240300" by Janne Räkköläinen is licensed under CC BY-SA 2.0

The term chroot jail was first used in 1992, in an article by a prominent security researcher, Bill Cheswick, (which is interesting if you’re into that sort of thing, you can find the article here). Chroot jails started appearing in 2003, with applications like IRC and FTP. In 2005, Sun introduced its "Containers" technology called Zones, which in turn was a precursor to the concept of namespaces, which is a core technology used with containers.

Chroot basics

Chroot allows an administrator to control access to a service or filesystem while controlling exposure to the underlying server environment. The two common examples you might encounter are during the boot sequence and the "emergency shell" on Red Hat/CentOS/Fedora systems, and in Secure FTP (SFTP).

The command looks like this:

chroot <newroot> [[command][arguments]]

Similar to the sudo command, the chroot command changes the environment of the following command. In other words, it will change you to the newroot directory, and also makes that directory the "working" directory. The command then executes in that location, which is useful for things like rescuing a system that won’t boot.

Unlike sudo, you will be "in" the directory. This practice, again, is useful if you are booting from external media but need to access a "local" filesystem or command to do work.

The other common use of chroot is to restrict a service or user by using a wrapper to hide the rest of the filesystem, therefore restricting a remote user’s view of other users’ data. A popular implementation using this approach SFTP.


Before you start working through this example, you should make sure you have backups. In this case, back up the /etc/ssh/sshd_config file because you’ll be making changes to that one specifically:

[root@showme1 ~]# cp /etc/ssh/sshd_config /etc/ssh/sshd_config.bak

For now, you will only restrict SFTP users to their home directories on the server. This requirement means that you’ll need to add users and put them in a group:

[root@showme1 ~]# useradd -g sftpusers -s /sbin/nologin -p nick nick

Note that doing this will assign nick an account with no login shell. This technique is both practical and a good security practice: If he’s just using SFTP, he shouldn’t have login privileges. I’ll discuss providing a shell to remote users in the next article.

Now, you need to tell the ssh service what to do when SFTP users log in. Open the /etc/ssh/sshd_config file and add the following at the end:

Subsystem sftp internal-sftp

Match Group sftpusers
ForceCommand internal-sftp
ChrootDirectory /home
X11Forwarding no
AllowTcpForwarding no

It’s important that you add these settings as a separate set of entries, and that you use the Match syntax to indicate that this section only applies to users in this group. If you made the changes to the existing entries, they would apply to all SSH users, which could break remote access.

The configuration lines break down as follows:

  • The ForceCommand makes ssh choose its built-in facility to provide SFTP service (which you can control independently).
  • ChrootDirectory tells sshd where to restrict the user to.
  • Subsystem sftp internal-sftp tells sshd to load the internal sftp service and make it available.

You might need to make sure that this Subsystem is not defined already by commenting out this line earlier in the config file:

# override default of no subsystems
# Subsystem sftp /usr/libexec/openssh/sftp-server

Once you’ve made the changes and checked the spelling, go ahead and save the changes. Then, restart sshd:

[root@showme1 ~]# systemctl restart sshd

Test the new user:

[skipworthy@milo ~]$ sftp nick@showme
nick@showme's password:
Connected to nick@showme.
sftp> ls
accounting   ansible   fred   jason   kenny   lisa    
sftp> pwd
Remote working directory: /
sftp> exit

Oops, hang on just one minute: It looks like you can see all of the other users’ directories as well. However, you can’t navigate to those directories:

sftp> cd fred
sftp> ls
remote readdir("/fred"): Permission denied

You can direct the chrooted user to their own home directory by changing the ChrootDirectory line in the sshd_config file like this:

ChrootDirectory /

This quick change makes it look to Nick as though he’s in his own home directory, and he won’t be able to see any other user’s files:

sftp> pwd
Remote working directory: /home/nick
sftp> exit
[skipworthy@milo ~]$ touch test.txt
[skipworthy@milo ~]$ sftp nick@showme
nick@showme's password:
Connected to nick@showme.
sftp> put test.txt
Uploading test.txt to /home/nick/test.txt
test.txt 100% 0 0.0KB/s 00:00
sftp> ls

Where did it go? Check this out:

[root@showme1 ~]# ls /home/nick

Note that a chroot jail is not considered to be an adequate security restriction by itself. While it prevents a user from changing out of a restricted directory, there are ways around this (the general idea is referred to in the chroot(2) man page, which you should take a look at if you are considering using this trick in a production- or business-critical context.)

Wrapping up (for now)

So, you can see that chroot can be a pretty useful tool. In part 2, I’ll look more at assigning specific directories to users, and providing a shell environment to a remote user without exposing the rest of the server.

New to containers? Download the Containers Primer and learn the basics of Linux containers.

Topics:   Linux   Containers  
Author’s photo

Glen Newell

Glen Newell has been solving problems with technology for 20 years. As a Systems Engineer and administrator, he’s built and managed servers for Web Services, Healthcare, Finance, Education, and a wide variety of enterprise applications. More about me

Try Red Hat Enterprise Linux

Download it at no charge from the Red Hat Developer program.