SSHjail for OpenSSH

[What is it] [Why do it] [Installation] [Download][Credits]

What is it?

SSHjail is just an unofficial patch for the OpenSSH daemon which provide the ability to confine users to a prepopulated jail in a chosen part of the filesystem area when they login via ssh,sftp or scp instead of being able to access whole system. All this is achieved using the chroot() system call.

Why do it?

I know there is another very well known patch (http://chrootssh.sourceforge.net) that already does this but it has some limitations because you must change the user homedir in the passwd file and this mess up with almost all other daemons running on the machine, For example, httpd is no longer able to serve "http://hostname/~user", IMAPd can't access the "~/Mail", etc..
It also suffer from another pitfall, the inability to use PAM. Maybe they start to support this after seeing my patch, it's trivial.

Instead of use a chrootssh's patch you could also use the pam_chroot (http://sourceforge.net/projects/pam-chroot/) for this propose but you fall in the same limitations because the user homedir in the passwd isn't the real PATH. Also, PAM isn't even an option for other unices, especially older ones.

My goal was to write a patch that would effectively chroot users without any changes to any existent configuration files, so that all other applications could keep on working with their defaults configurations. Also, I'd like as much as possible to keep using the current OpenSSH configuration, and that means PAM, UsePrivilegeSeparation, etc.

Installation

For better understanding, let's imagine we want to have five users: three with ssh/scp/sftp chroot access -- user1 and user2, which are the only users in "webusers" group, and user3 in any other random group; one other with only sftp chroot access, user4; and lastly a user with ssh/scp/sftp access to the whole system, user5. You'd do as follows:
  1. Download the sshjail's patch;
  2. Download and uncompress the OpenSSH package;
  3. Outside the openssh-x.xpx directory apply the patch (patch -p0 < openssh-x.xpx-sshjail.patch);
  4. cd openssh-x.xpx; ./configure --with-all-your-favorite-options; make; make install;
  5. Now create the "/etc/sshjail.conf" file
    For our example the file looks like this:
    ----------------------------------------
    #sshjail configuration file
    #
    #Path for the chroot environment and users/groups for it
    chroot=/home/env1
    users=@webusers,user3

    #Path for the chroot environment and users/groups for it
    chroot=/home/env2
    users=user4
    ---------------------------------------
    As you can see, the hash symbol (#) denotes a comment, empty lines are ignored, 'chroot=' is the path to the location where you built the chroot environent, 'users=' is a list of users or groups you want to separate. To differentiate users from groups, you put a "@" before it, e.g. "example" is a user, "@example" is a group. All parameters are separated by a comma, "," e.g. "user1,user2,@group1".

    We could confine all four users to the same chroot jail, but for explanatory purposes, so that all possible configurations are explained, they were effectively separated into two different jails. This way we make sure that users with only ssh access can't see users with just sftp, and vice-versa. As user5 isn't restricted, he isn't mentioned in the configuration, of course.
  6. Create the two chroot environment on /home/env1 and /home/env2. The building process is out of the scope of this document, there is already to many pages on the internet explaining that, try this one, or go to Google
  7. Now lets see how /etc/passwd looks like:
    ------------------------------------------
    user1:x:802:300::/home/env1/home/user1:/bin/bash
    user2:x:803:300::/home/env1/home/user2:/bin/bash
    user3:x:804:301::/home/env1/home/user3:/bin/bash
    user4:x:805:302::/home/env2/home/user4:/usr/libexec/sftp-pserver
    user5:x:806:303::/home/user5:/bin/bash
    -------------------------------------------
  8. If you are using OpenSSH version 5.Xp1 be sure your sshd_config file has the line "Subsystem sftp internal-sftp"
  9. The last part. Run the daemon and check if everything behaves properly. If not, please read the installation instructions again.

Download

You can download the SSHjail patch from http://antitese.org/sshjail/downloads/

Credits

SSHjail patch was written by Gonçalo Silva (gngs@antitese.org) and even though with different approach was initially inspired on the Ricardo Cerqueira's idea.

©2005 -2009
Valid CSS! Valid XHTML 1.1