From: Ralf Jung Date: Thu, 8 Oct 2015 08:26:12 +0000 (+0200) Subject: Convert README to markdown X-Git-Url: https://git.ralfj.de/schsh.git/commitdiff_plain/f904a13d8172b27f6a1ceeb78673d3261c3783f1 Convert README to markdown --- diff --git a/README.md b/README.md new file mode 100644 index 0000000..a05a1fa --- /dev/null +++ b/README.md @@ -0,0 +1,91 @@ +# schsh: Restricted file access via SSH + +## Introduction + +Welcome to [schsh](https://www.ralfj.de/projects/schsh), a schroot-based shell. + +Its purpose is simple: I want to provide users with scp, sftp and rsync access +to my server, such that they can only operate in a certain subdirectory. +There are plenty of solutions for this problem out there, and all have one +drawback in common: +You need to manually set up a bunch of chroots, and copy the files needed for +scp, sftp and rsync into them. + +I didn't like that, so here is my alternative solution: Use schroot for the +chroots. This gets OpenSSH out of the loop when it comes to chroots, instead +the relevant users get a special shell (schsh, the schroot shell). That shell +essentially calls schroot and runs the desired command inside the chroot. It +also provides some very basic command restriction (so that you can allow scp, +sftp and rsync and nothing else). + +Unfortunately, this still needs a (s)chroot to be set up for each user, but at +least no files have to be copied: Instead, schroot is configured to bind-mount +the relevant system folders into the user-chroot. Hence no files are +duplicated, and system updates to the relevant tools are applied inside the +chroots automatically. For additional hardening, these bind-mounts are +configured to be read-only and no-setuid, while the only user-writeable folder +is no-exec. + +## Setup + +Before you start, make sure you have the dependencies installed: +schsh needs [Python 3](http://www.python.org) (I tested it with +version 3.2) and [schroot](https://wiki.debian.org/Schroot) +(version 1.6 or newer). + +Installation is simple: Just run `make install`. That will copy some files +to `/usr/local/bin`, and some configuration to `/etc/schroot/`. +Before you create any users, make sure the directory `/var/lib/schsh` and a +group called `schsh` exist. + +You should also set up SSH to disallow port forwarding for users controlled by +schsh. See `sshd_config` in the source folder for an appropriate snippet +of OpenSSH configuration. + +Before you can set up schsh for a user, you need to create it first: + + adduser sandboxed --disabled-password + +Any existing user can be "sandboxed" by running: + + makeschsh sandboxed + +This does the following: + +* Change the user's shell to `/usr/local/bin/schsh` +* Create a chroot base in `/var/lib/schsh/sandboxed` with some empty + subfolders as well as `/etc/passwd` and `/etc/group` containing + only root, this user and the `schsh` group +* Add the user to the `schsh` group +* Set up a schroot called `schsh-sandboxed` for the given folder, and an + fstab file in `/etc/schroot/schsh` used by this schroot + +Now if the user logs in via SSH, `/usr/local/bin/schsh` will be executed, +and it will lock the user into the schroot `schsh-sandboxed`. It will +only see some system folders and a folder called `/data` mapped to +`/home/sandboxed/data`. If you want to give the user access to more +folders, or another folder, simply edit `/etc/schroot/schsh/sandboxed.fstab`. +The only part of schsh writing any files is `makeschsh`, so you can change +the users' schroot configurations at your will. + +## Configuration + +There is not much to configure at the moment. However, there are some +global variables at the top of both `schsh` and `makeschsh` to +change the base paths, and to tell which commands are allowed. + +## Source, License + +You can find the sources in the [git +repository](http://www.ralfj.de/git/schsh.git) (also available [on +GitHub](https://github.com/RalfJung/schsh)). They are provided under the +[GPLv3](https://www.gnu.org/licenses/gpl.html). In addition, all files except +for `schsh-rrsync` are provided under the +[GPLv2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.html) or (at your +option) any later version of the GPL. See the file `LICENSE-GPL3` for more +details. + +## Contact + +If you found a bug, or want to leave a comment, please +[send me a mail](mailto:post-AT-ralfj-DOT-de). diff --git a/README.rst b/README.rst deleted file mode 100644 index e46b664..0000000 --- a/README.rst +++ /dev/null @@ -1,102 +0,0 @@ -schsh: Restricted file access via SSH -===================================== - -Introduction ------------- - -Welcome to schsh_, a schroot-based shell. - -Its purpose is simple: I want to provide users with scp, sftp and rsync access -to my server, such that they can only operate in a certain subdirectory. -There are plenty of solutions for this problem out there, and all have one -drawback in common: -You need to manually set up a bunch of chroots, and copy the files needed for -scp, sftp and rsync into them. - -I didn't like that, so here is my alternative solution: Use schroot for the -chroots. This gets OpenSSH out of the loop when it comes to chroots, instead -the relevant users get a special shell (schsh, the schroot shell). That shell -essentially calls schroot and runs the desired command inside the chroot. It -also provides some very basic command restriction (so that you can allow scp, -sftp and rsync and nothing else). - -Unfortunately, this still needs a (s)chroot to be set up for each user, but at -least no files have to be copied: Instead, schroot is configured to bind-mount -the relevant system folders into the user-chroot. Hence no files are -duplicated, and system updates to the relevant tools are applied inside the -chroots automatically. For additional hardening, these bind-mounts are -configured to be read-only and no-setuid, while the only user-writeable folder -is no-exec. - -.. _schsh: https://www.ralfj.de/projects/schsh - -Setup ------ - -Before you start, make sure you have the dependencies installed: -schsh needs `Python 3`_ (I tested it with version 3.2) and -schroot_ (version 1.6 or newer). - -Installation is simple: Just run ``make install``. That will copy some files -to ``/usr/local/bin``, and some configuration to ``/etc/schroot/``. -Before you create any users, make sure the directory ``/var/lib/schsh`` and a -group called ``schsh`` exist. - -You should also set up SSH to disallow port forwarding for users controlled by -schsh. See ``sshd_config`` in the source folder for an appropriate snippet -of OpenSSH configuration. - -Before you can set up schsh for a user, you need to create it first:: - - adduser sandboxed --disabled-password - -Any existing user can be "sandboxed" by running:: - - makeschsh sandboxed - -This does the following: - -* Change the user's shell to ``/usr/local/bin/schsh`` -* Create a chroot base in ``/var/lib/schsh/sandboxed`` with some empty - subfolders as well as ``/etc/passwd`` and ``/etc/group`` containing - only root, this user and the ``schsh`` group -* Add the user to the ``schsh`` group -* Set up a schroot called ``schsh-sandboxed`` for the given folder, and an - fstab file in ``/etc/schroot/schsh`` used by this schroot - -Now if the user logs in via SSH, ``/usr/local/bin/schsh`` will be executed, -and it will lock the user into the schroot ``schsh-sandboxed``. It will -only see some system folders and a folder called ``/data`` mapped to -``/home/sandboxed/data``. If you want to give the user access to more -folders, or another folder, simply edit ``/etc/schroot/schsh/sandboxed.fstab``. -The only part of schsh writing any files is ``makeschsh``, so you can change -the users' schroot configurations at your will. - -.. _Python 3: http://www.python.org -.. _schroot: https://wiki.debian.org/Schroot - -Configuration -------------- - -There is not much to configure at the moment. However, there are some -global variables at the top of both ``schsh`` and ``makeschsh`` to -change the base paths, and to tell which commands are allowed. - -Source, License ---------------- - -You can find the sources in the `git repository`_ (also available `on GitHub`_). -They are provided under the GPLv3_. In addition, all files except for -``schsh-rrsync`` are provided under the GPLv2_ or (at your option) any later -version of the GPL. See the file ``LICENSE-GPL3`` for more details. - -.. _git repository: http://www.ralfj.de/git/schsh.git -.. _on GitHub: https://github.com/RalfJung/schsh -.. _GPLv2: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html -.. _GPLv3: https://www.gnu.org/licenses/gpl.html - -Contact -------- - -If you found a bug, or want to leave a comment, please -`send me a mail `_.