Community Blog How to Configure Chroot Environments for SFTP Access on Ubuntu 16.04

How to Configure Chroot Environments for SFTP Access on Ubuntu 16.04

This article show you how to create an SFTP chroot environment on an ECS instance that locks users to their home directory while restricting shell access for security purposes.

By Francis Ndungu, Alibaba Cloud Tech Share Author. Tech Share is Alibaba Cloud's incentive program to encourage the sharing of technical knowledge and best practices within the cloud community.

In Linux chroot stands for change root. It is a process of creating a jailed environment for a calling process (e.g. SFTP) to isolate it from the rest of the system.

SFTP (Secure Shell File Transfer Protocol) is a means of transferring files securely from a client to a server over a network.

Sometimes, you may want to grant SFTP access to allow users to upload files on your Linux server. However, this would open up a security door and your entire file system can be at risk.

To overcome this challenge, this is where chroot comes in. It simply changes the root directory of the user during an SFTP process.

Chrooted users can't break the jail but they would still be able to run normal SFTP commands to manage their directories and files.

This is a step-by-step guide for creating an SFTP chroot environment on an Alibaba Cloud Elastic Compute Service (ECS) Ubuntu 16.04 instance that locks users to their home directory while restricting shell access for security purposes.


  1. A valid Alibaba Cloud Account. (Sign up now and get up to $1200 to test over 40 Alibaba Cloud products)
  2. An Alibaba Cloud ECS instance running Ubuntu 16.04 Operating system.
  3. A non-root user that can perform sudo tasks.

Step 1: Creating an SFTP Group

To better manage our chrooted users, we will create a group for them using the Linux groupadd command. Since this is a system wide setting, we will run the command using sudo:

$ sudo groupadd sftpusers

Please note, you can replace sftpusers with your preferred name of the group.

Step 2: Setting Up OpenSSH

As mentioned above, SFTP runs over the SSH protocol and therefore, it implements all the security and authentication features of SSH. With data encryption capabilities, SSH can largely prevent password sniffing and man-in-the-middle-attacks.

When started, OpenSSH reads a configuration file located at /etc/ssh/sshd_config. We need to make changes to this file using a nano editor:

$ sudo nano /etc/ssh/sshd_config

Find the line:

#Subsystem sftp /usr/lib/openssh/sftp-server 

And change it to:

Subsystem sftp internal-sftp

Then, towards the end of the file, add the below settings:

Match Group sftpusers
    ChrootDirectory %h
    X11Forwarding no
    AllowTcpForwarding no
    ForceCommand internal-sftp

Remember to replace sftpusers with the name of group you created above. When done, press CTRL+X, Y and Enter to save the file.

Now, let's go over each configuration settings that we have added above:

Subsystem sftp internal-sftp: This directive configures an external process. In our case, the file transfer daemon. The subsystem entry should be accompanied by the command to execute.

In this case, we have specified sftp internal-sftp. This is an in-process SFTP server that simplifies configurations when using chroot directory and forces different roots to our group.

Match Group sftpusers: This directive instructs the system to apply the commands below it to users that belong to the group sftpusers. You may also use a Match User directive to chroot a specific user to a certain directory but this will require multiple chroot configuration blocks for each user.

ChrootDirectory %h: This restricts users to their home directory.

X11Forwarding no: This disables X11 forwarding for the current group and limits group users from executing graphical interface programs through SSH.

AllowTcpForwarding no: This one disables TCP forwarding and limits exposing other internal applications to the group.

ForceCommand internal-sftp: Upon login, this command causes the system to run the internal-sftp process.

After making any changes to OpenSSH configuration file, you must restart the SSHD daemon:

$ sudo service ssh restart

Step 3: Configuring User Accounts

Next, we are going to configure the user accounts and modifying the permissions for their root directory. For the sake of simplicity, we will use a hypothetical username jacob. You can add as many user accounts to the chroot environment depending on your needs.

First, let us add our user to the system using the adduser linux command:

$ sudo adduser jacob

When prompted, enter the user password and other details to create the user on the system as shown below:

Adding user `jacob' ...
Adding new group `jacob' (1006) ...
Adding new user `jacob' (1004) with group `jacob' ...
Creating home directory `/home/jacob' ...
Copying files from `/etc/skel' ...
Enter new UNIX password:Enter Password
Retype new UNIX password:Enter Password
passwd: password updated successfully
Changing the user information for jacob
Enter the new value, or press ENTER for the default
        Full Name []:
        Room Number []:
        Work Phone []:
        Home Phone []:
        Other []:
Is the information correct? [Y/n] y

By default, the adduser command will create a home directory for the user. In our case /home/jacob. Next, we need to add our user to the chrooted group that we created above. We can do this using the command below:

$ sudo usermod -G sftpusers jacob

Next, change the ownership of the user's home directory. It must be owned by root for chroot to work:

$ sudo chown root:root /home/jacob

Next, give root full access to the user's home directory:.

$ sudo chmod 755 /home/jacob

Since the directory /home/jacob is now owned by the root, user jacob won't be in a position to create files or folders in the directory . We must now add some directories under this directory and assign full ownership to our user:

$ sudo mkdir /home/jacob/public_html
$ sudo chown jacob:jacob /home/jacob/public_html

In our case above, the user can use the public_html directory to upload website files through SFTP. We can also create a private document directory for our user with restricted permissions to the outside users using the command below:

$ sudo mkdir /home/jacob/private_docs
$ sudo chown jacob:jacob /home/jacob/private_docs
$ sudo chmod 700 /home/jacob/private_docs

Our user will still be able to upload files to the private_docs directory, but no one else will have permissions to read, execute or write on that folder.

Step 4: Testing the Configuration

Once the chroot settings are in place, you can try to connect to your Ubuntu 16.04 Alibaba Cloud server through sftp using the credentials of the user that we have created.

If you are running Linux on your local computer, run the command below and remember to replace jacob with the correct username and with the public IP address associated with Alibaba ECS instance.

$ sftp jacob@ 

Login session output:

The authenticity of host' can't be established.
ECDSA key fingerprint is SHA256:2wDenY0R9/odsoiYTaSJCmTHNplmy4oWX7z2nIqUNOQ.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added ' ' (ECDSA) to the list of known hosts.
jacob@'s password:Enter password here
Connected to
sftp> pwd
Remote working directory: /

This shows that SFTP is working as expected. When connected, run the pwd command as shown above and see if everything is working as expected.

On Windows, you can use Filezilla to connect to the server through the SFTP channel.

Step 5: Confirming Shell Access Restriction

For security purposes, you may wish to confirm if shell access is restricted as required for the chrooted user. To do this, try connecting to your Alibaba ECS instance via an SSH client with the credentials of the limited user. If you followed the guide, you won't be able to gain access to the server.

Congratulations, you have now created a chroot environment with SFTP access on your server for your users.


In this guide, we have taken you through the steps of creating a group for chroot users on your Linux system. We also went ahead and configured OpenSSH to redirect users to the SFTP program so that they can upload files to their directory.

With the settings in place, chrooted users will be restricted to their home directories but they can't run shell commands. We believe this guide will help you to add more flexibility to your users while still taking care of the system-wide settings of your file system hosted on Alibaba Cloud.

If you are new to Alibaba Cloud, you can sign up and get up to $1200 to test over 40 Alibaba cloud products.

0 1 1
Share on


31 posts | 8 followers

You may also like