README

   1 Introduction
   2 ------------
   3
   4 Welcome to [schsh][SCHSH], a schroot-based shell.
   5
   6 Its purpose is simple: I want to provide users with scp, sftp and rsync access
   7 to my server, such that they can only operate in a certain subdirectory.
   8 There are plenty of solutions for this problem out there, and all have one
   9 drawback in common:
  10 You need to manually set up a bunch of chroots, and copy the files needed for
  11 scp, sftp and rsync into them.
  12
  13 I didn't like that, so here is my alternative solution: Use schroot for the
  14 chroots. This gets OpenSSH out of the loop when it comes to chroots, instead
  15 the relevant users get a special shell (schsh, the schroot shell). That shell
  16 essentially calls schroot and runs the desired command inside the chroot. It
  17 also provides some very basic command restriction (so that you can allow scp,
  18 sftp and rsync and nothing else).
  19
  20 Unfortunately, this still needs a (s)chroot to be set up for each user, but at
  21 least no files have to be copied: Instead, schroot is configured to bind-mount
  22 the relevant system folders into the user-chroot. Hence no files are
  23 duplicated, and system updates to the relevant tools are applied inside the
  24 chroots automatically. For additional hardening, these bind-mounts are
  25 configured to be read-only and no-setuid, while the only user-writeable folder
  26 is no-exec.
  27
  28 [SCHSH]: http://www.ralfj.de/projects/schsh/
  29
  30 Setup
  31 -----
  32
  33 Before you start, make sure you have the dependencies installed:
  34 schsh needs [Python 3][PYTHON] (I tested it with version 3.2) and
  35 [schroot][SCHROOT] (version 1.6 or newer).
  36
  37 Installation is simple: Just run ```make install```. That will copy some files
  38 to ```/usr/local/bin```, and some configuration to ```/etc/schroot/```.
  39 Before you create any users, make sure the directory ```/var/lib/schsh``` and a
  40 group called ```schsh``` exist.
  41
  42 You should also set up SSH to disallow port forwarding for users controlled by
  43 schsh. See ```sshd_config``` in the source folder for an appropriate snippet
  44 of OpenSSH configuration.
  45
  46 Before you can set up schsh for a user, you need to create it first:
  47
  48     adduser sandboxed --disabled-password
  49
  50 Any existing user can be "sandboxed" by running
  51
  52     makeschsh sandboxed
  53
  54 This does the following:
  55
  56 * Change the user's shell to ```/usr/local/bin/schsh```
  57 * Create a chroot base in ```/var/lib/schsh/sandboxed``` with some empty
  58   subfolders as well as ```/etc/passwd``` and ```/etc/group``` containing
  59   only root, this user and the ```schsh``` group
  60 * Add the user to the ```schsh``` group
  61 * Set up a schroot called ```schsh-sandboxed``` for the given folder, and an
  62   fstab file in ```/etc/schroot/schsh``` used by this schroot
  63
  64 Now if the user logs in via SSH, ```/usr/local/bin/schsh``` will be executed,
  65 and it will lock the user into the schroot ```schsh-sandboxed```. It will
  66 only see some system folders and a folder called ```/data``` mapped to
  67 ```/home/sandboxed/data```. If you want to give the user access to more
  68 folders, or another folder, simply edit ```/etc/schroot/schsh/sandboxed.fstab```.
  69 The only part of schsh writing any files is ```makeschsh```, so you can change
  70 the users' schroot configurations at your will.
  71
  72 [PYTHON]: http://www.python.org
  73 [SCHROOT]: http://packages.qa.debian.org/s/schroot.html
  74
  75 Configuration
  76 -------------
  77
  78 There is not much to configure at the moment. However, there are some
  79 global variables at the top of both ```schsh``` and ```makeschsh``` to
  80 change the base paths, and to tell which commands are allowed.
  81
  82 Source, License
  83 ---------------
  84
  85 You can find the sources in the [git repository][GIT]. They are provided under
  86 the [GPLv3][GPL3]. In addition, all files except for ```schsh-rrsync``` are
  87 provided under the [GPLv2][GPL2] or (at your option) any later vrsion of the
  88 GPL.
  89
  90 [GIT]: http://www.ralfj.de/git/schsh.git
  91 [GPL3]: https://www.gnu.org/licenses/gpl.html
  92 [GPL2]: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
  93
  94 Contact
  95 -------
  96
  97 If you found a bug, or want to leave a comment, please send me a mail:
  98 ```post AT ralfj DOT de```.