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