sftp chroot jail in Ubuntu

(Update 16 Mar 2011: Since writing this post, I’ve learned of an easier way to create this chroot jail. Newer versions of OpenSSH enable the “ChrootDirectory” configuration directive. I recommend that you take a look at George Ornbo’s tutorial on chrooting sftp users in Intrepid for the details.)

(Updated 08 Feb 2011 to reflect xplicit’s experience on Ubuntu 10.04.)

I wanted to give a buddy access to a website hosted on my box. So I tried scponly, since I only wanted to provide SFTP access to that particular directory, using a chroot jail. The steps are as follows.

  1. Install the scponly package using Ubuntu’s APT package management system.
  2. Use the script provided to set up your first jail and your user’s home directory. For the location of the user’s jail, give the path of the directory you want to share.
  3. Provide a password for the new user.
  4. Ensure that the new user has permissions to read and write all the necessary directories in your Web site.

$ sudo apt-get install scponly
$ gzip -dc /usr/share/doc/scponly/setup_chroot/setup_chroot.sh.gz > /tmp/setup_chroot.sh
$ cp /usr/share/doc/scponly/setup_chroot/config.h /tmp

The previous step copies the “config.h” file to help things go more smoothly, as Luke found.

$ chmod +x /tmp/setup_chroot.sh
$ cd /tmp
$ sudo ./setup_chroot.sh

Next we need to set the home directory for this scponly user.
please note that the user's home directory MUST NOT be writeable
by the scponly user. this is important so that the scponly user
cannot subvert the .ssh configuration parameters.
For this reason, a writeable subdirectory will be created that
the scponly user can write into.

Note that I removed the /incoming subdirectory created by this script. There was no need for a separate directory for my buddy to upload files. He could have permissions over the whole site tree.

-en Username to install [scponly]
-en home directory you wish to set for this user [/home/bob]
-en name of the writeable subdirectory [incoming]

creating /var/www/sites/bobsite/htdocs/incoming directory for uploading files

Your platform (Linux) does not have a platform specific setup script.
This install script will attempt a best guess.
If you perform customizations, please consider sending me your changes.
Look to the templates in build_extras/arch.
- joe at sublimation dot org

please set the password for bob:
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully
if you experience a warning with winscp regarding groups, please install
the provided hacked out fake groups program into your chroot, like so:
cp groups /var/www/sites/bobsite/htdocs/bin/groups

This script added certain directories to the site root (/var/www/sites/bobsite/htdocs). Every other directory needed to be writable by Bob. So let’s add Bob to a special group, and allow that group write access on all the website’s files.

$ sudo adduser bob www-data

We can ignore /bin, /etc, /lib and other directories added to the chroot jail (the website filesystem):

$ sudo find . \! -user root -exec chgrp www-data \{\} \;
$ sudo find . \! -user root -exec chmod g+w \{\} \;

Good to go!

9 Comments on “sftp chroot jail in Ubuntu”

  1. Luke Pearce says:

    Thanks for this – really useful.

    As a little note I found a couple of minors with the setup_chroot.sh:

    1) setup_chroot.sh needed to be executable: chmod +x setup_chroot.sh

    2) And it complained about not being a chroot setup unless you copied over the config.h found in the same directory: cp /usr/share/doc/scponly/setup_chroot/config.h /tmp


    • fourstar says:

      Thanks Luke — I updated the post to reflect your experience, since it might be helpful for someone!


      • Luke Pearce says:

        Just to add in Ubuntu 10.04 I still had connection issues until I copied the libnss_files into the individual scponly users lib directory:

        [from the /home/scponly user directory]
        cp /lib/libnss_files* ./lib

        There’s also some good info here:


        Like setting it up so sftp starts in the incoming directory so the user doesn’t have the chroot directories cluttering up their space.

  2. xplicit says:

    Little fix:

    In Ubuntu 10.04
    instead of
    sudo /tmp/setup_chroot.sh

    you should use
    cd /tmp
    sudo ./setup_chroot.sh

    or you will get an error
    “your scponly build is not configured for chrooted operation.
    please reconfigure as follows, then rebuild and reinstall”

    That was about Luke wrote above.

  3. Jim says:

    I did exactly as instructed here and even read all of the issues replies and everything seemed to have gone well.

    After I created the account I noticed that the permissions for the folder I want the user to have access to was set to ‘root’ so I changed it to the [new user] account and [new group]. After this was done, I am getting error when I ftp in with: Connection closed by server with exitcode 1

    I was told by someone that when I deleted the old Null account with the [user] to start over it revereted back to ‘root’ and so it never created the [new user] or something to that efect. Am I missing a step?

    • Jim says:

      here is my exact steps:

      gzip -dc /usr/share/doc/scponly/setup_chroot/setup_chroot.sh.gz > /tmp/setup_chroot.sh
      cp /usr/share/doc/scponly/setup_chroot/config.h /tmp
      chmod +x /tmp/setup_chroot.sh
      cd /tmp
      sudo ./setup_chroot.sh

      sudo adduser webdev www-data
      sudo find . \! -user root -exec chgrp www-data \{\} \;
      sudo find . \! -user root -exec chmod g+w \{\} \;
      cd /var/www/myaudiolisting/lib
      sudo cp /lib/libnss_files* /var/www/myaudiolisting/lib

      Then after this, I opened up another terminal window and did sudo nautilus and went to the /var/www/home/ folder and checked on the permissions and I changed it to webdev for user and webdev for group as it was set to root/root.

    • Jim says:

      Sorry, I meant to type: went to the /var/www/myaudiolisting/ folder to reset permissions back to webdev

    • fourstar says:

      Hi Jim — did you already discover the ChrootDirectory configuration directive in newer versions of OpenSSH? If you have even a relatively recent version of Ubuntu, you’ll be golden.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s