Provided by: rssh_2.3.4-7ubuntu0.1_amd64 
NAME
rssh - restricted secure shell allowing only scp and/or sftp
SYNOPSIS
rssh [ options... ] [ ... ]
rssh -v
DESCRIPTION
rssh is a restricted shell for providing limited access to a host via ssh(1), allowing a
user whose shell is configured to rssh to use one or more of the command(s) scp(1),
sftp(1) cvs(1), rdist(1), and rsync(1), and only those commands. It is intended primarily
to work with OpenSSH (see http://www.openssh.com), but may work with other
implementations.
The system administrator should install the shell on the restricted system. Then the
password file entry of any user for whom it is desirable to provide restricted access
should be edited, such that their shell is rssh. For example:
luser:x:666:666::/home/luser:/usr/bin/rssh
If invoked with the -v option, rssh will report its version, and exit. All other
arguments to rssh are those specified by the remote ssh(1) client, and aren't of much
concern to the average user. The arguments provided must be what a shell on the remote
end would receive in order to pass control to scp(1), sftp(1), etc. If rssh receives
arguments which do not conform, it will emit an error message and exit. If the program
the user is trying to run is not allowed, or contains syntax which will try to execute a
shell command (such as a command substitution), it will also emit an error and exit.
rssh has a configuration file, rssh.conf(5), which allows some of the behavior of rssh to
be customized. See that man page for details.
SECURITY NOTES
Read this section with exceptional care, or you may put your system at risk!
Using rssh With CVS
If you are using rssh to allow CVS access, it should be noted that it is not possible to
prevent a user who is very familiar with CVS from bypassing rssh and getting a shell,
unless the user does not have write access in the repository. Obviously, the user must
have write access to the repository in order to update it, which allows them to upload
arbitrary programs into the repository. CVS provides several mechanisms for executing
such arbitrary programs... The only reasonably safe way to use rssh with CVS is to use
the chroot jail facilities to place the CVS repository within a chroot jail. Please see
below and all relevant documentation for details of how to set up chroot jails. Note that
users will still be able to get shell access within the jail; the only protection which is
provided is that they can not escape the jail. I have been pursuaded to retain support
for CVS because this protection is better than no protection. You have been warned. Use
CVS at your own risk.
Potential root Compromise With Old Versions
Before rssh 2.3.0, if a regular user had shell access to a machine where rssh was
installed, a root compromise was possible due to rssh_chroot_helper allowing a user to
arbitrarily chroot(2) to anywhere on the filesystem. It is possible to mitigate this
attack against affected versions of rssh using strict access controls to files, by making
sure that the user can not write to any file on the same partition as system executables,
and that any partition where they can write files does not allow execution of SUID
programs. As of rssh 2.3.0, this attack has been prevented by preventing arbitrary
chroot(), if your jail is set up securely. In particular, make sure that regular users
can not write to directories inside the jail which contain the copied binaries. That
should be obvious, but it needs to be said. Though it should not be strictly necessary,
to further protect your system from possible compromise, it is also advisable to follow
the section below, entitled "Safeguards Against Bypassing rssh".
Safeguards Against Bypassing rssh
rssh is designed to interact with several other programs. Even if rssh is completely bug-
free, changes in those other programs could possibly result in methods to circumvent the
protection that rssh is intended to provide. It is important for you, the system
administrator, to stay current on the services you make available with rssh, to be sure
that these commands do not provide mechanisms to allow the user to run arbitrary commands.
Also, while the goal of every release is to be bug free, no one is perfect... There may
be undiscovered bugs in rssh which might allow a user to circumvent it.
You can protect your system from those who would take advantage of such weaknesses. This
is not required for rssh to work properly, but it is a really good idea. There are six
basic steps:
1. protect all non-administrator accounts with rssh (i.e. no regular user
should have shell access to the server)
2. place your users in a chroot jail
3. limit the binaries which live in the jail to the absolute minimum required
4. mount their home filesystem with the noexec/nosuid option (i.e. use separate
partitions in the jail for user home directories and all other files, if
possible/reasonable)
5. create a group for rssh users, and limit executable access to the binaries
to users in that group.
6. use standard file permissions carefully and appropriately
If possible, make sure that no regular user has any kind of shell access to the system
other than through rssh. Otherwise, users with shell access could potentially exploit
undiscovered bugs in rssh_chroot_helper to gain root access to the server.
rssh gives the system administrator the ability to place the users in a chroot jail. See
details in the man page for rssh.conf and in the file CHROOT which is distributed with the
source code. If you want to ensure users can not run arbitrary programs, use a chroot
jail, and be sure not to put any programs other than what are absolutely necessary to
provide the service you are trying to provide. This prevents them from running standard
system commands.
Then, make sure the user's files inside the jail are on a separate filesystem from your
system's executables. If possible in your environment, make sure you mount this
filesystem using the noexec and nosuid options, if your operating system provides them.
This prevents the users from being able to execute programs which they have uploaded to
the target machine (e.g. using scp) which might otherwise be executable, and prevents SUID
programs from respecting the SUID bits. Note that these options necessitate the users'
files are on separate partitions from the binaries and libraries that live in the jail.
Therefore you will need at least 2 partitions for your jail to do this properly (one for
the system binaries in the jail, the other for the user directories).
Additionally, create a group, for example "rsshuser", for rssh users. Put all your users
who will be restricted by rssh in that group. Set the ownership and permissions on rssh
and rssh_chroot_helper so that only those users can execute them. The following commands
should illustrate:
# groupadd rsshuser
# chown root:rsshuser rssh rssh_chroot_helper
# chmod 550 rssh
# chmod 4550 rssh_chroot_helper
Lastly, use standard Unix/POSIX file permissions to ensure they can not access files they
should not be able to within the chroot jail.
Command Line Parser
As of rssh version 2.2.3, the program must parse out the complete command line to avoid
command line options which cause the execution of arbitrary programs (and hence bypass the
security of rssh). In order to keep the program source code sane, the parser is a little
over-zealous about matching command line options. In practice, this probably will not be
an issue, but in theory it is possible.
If you run into a problem where rssh refuses to run, claiming to be rejecting insecure
command line options which were not specified, try changing your command line such that
all short options are specified as single-letter option flags (e.g. -e -p instead of -ep)
and make sure you separate arguments from their respective options by a space (e.g. -p 123
instead of -p123). In virtually all cases, this should solve the problem. Admittedly, an
exhaustive search was not performed, but no problematical cases were found which were
likely to be common.
The alternative would have been to include a complete command-line parser for rcp, rdist,
and rsync; this was way out of the scope of this project. In practice, the existing
parser should suffice. If, however, you find cases where it does not, please post details
to the rssh mailing list. Details about how to post to the mailing list can be found at
the rssh homepage.
OpenSSH Versions and Bypassing rssh
Prior to OpenSSH 3.5, sshd(8) will generally attempt to parse files in the user's home
directory, and may also try to run a start-up script from the user's $HOME/.ssh directory.
rssh does not make use of the user's environment in any way. The relevant command is
executed by calling execv(3) with the full path to the command, as specified at compile
time. It does not depend upon the user's PATH variable, or on any other environment
variable.
There are, however, several problems that can arise. This is due entirely to the way the
OpenSSH Project's sshd works, and is in no way the fault of rssh. For example, one
problem which might exist is that, according to the sshd(8) man page from at least some
releases of OpenSSH, the commands listed in the $HOME/.ssh/rc file are executed with
/bin/sh instead of the user's defined shell. This appears not to be the case on the
systems the author had available to test on; commands were executed using the user's
configured shell (rssh), which did not allow the execution. However if it is true on your
system, then a malicious user may be able to circumvent rssh by uploading a file to
$HOME/.ssh/rc which will be executed by /bin/sh on that system. If any releases (of
OpenSSH) are, in fact, vulnerable to this problem, then it is very likely that they are
only old, outdated versions. So long as you are running a recent version of OpenSSH, this
should not be a problem as far as I can tell.
If your sshd is vulnerable to this attack, there is a workaround for this problem, though
it is pretty restrictive. The user's home directory absolutely must not be writable by
the user. If it is, the user can use sftp to remove the directory or rename it, and then
create a new one, and fill it up with whatever environment files they like. For providing
file uploads, this means a user-writable directory must be created for them, and they must
be made aware of their inability to write into their home directory other than in this
location.
A second problem is that after authenticating the user, sshd also reads
$HOME/.ssh/environment to allow the user to set variables in their environment. This
allows the user to completely circumvent rssh by clever manipulation of such environment
variables as LD_LIBRARY_PATH or LD_PRELOAD to link the rssh binary against arbitrary
shared libraries. In order to prevent this from being a problem, as of version 0.9.3, by
default rssh is now compiled statically. The restrictive work-around mentioned above will
also defeat this sort of attack.
As of OpenSSH 3.5, sshd now supports the option PermitUserEnvironment which is set to "no"
by default. This option allows restricted shells like rssh to function properly without
requiring them to be linked statically. As of rssh version 1.0.1, the configure script
should detect that OpenSSH 3.5 is present, and disable the default of static compilation.
BUGS
None. =8^)
A Note About Getting Help
If you are having trouble getting rssh working, or you think you've found a bug, please
use the mailing list, and do not e-mail me directly. You must sign up for the list in
order to post. Information about how to sign up is available on the rssh homepage. If
you mail me directly with questions, I will almost certainly ignore you, or at the very
least ask you to repost your question on the mailing list. Please also feel free to
provide feedback about rssh on the mailing list, whether positive or negative (especially
negative).
Security Problems
The only exception to the above is if you believe you have found a security problem with
rssh. If that is the case, then please do contact me privately. If you are unable to
find my direct contact info, post a message on the mailing list requesting that I contact
you about a potential security problem. Security problems should be dealt with privately,
so that the threat can be properly assessed, and so as not to needlessly endanger the
installations of rssh in production environments. I take security problems seriously, and
will work to resolve them as quickly as possible.
N.B.:
Before you e-mail me (or the mailing list) with questions, be sure to THOROUGHLY read all
of the following files: README, INSTALL, CHROOT, SECURITY. All of these files are
distributed with the rssh source code, as well as all binary packages of rssh. If you
downloaded a binary package, these files should be located wherever your distribution
keeps its documentation files (usually /usr/share/doc/rssh-version/ or something similar).
Also THOROUGHLY read the man pages for rssh(1), and rssh.conf(5). Finally, if you are
still having problems, read the FAQ at http://www.pizzashack.org/rssh/faq.shtml. If it is
clear to me that you have not read these documents, I will ignore you. In most cases,
these documents will already have everything you need to get rssh working, and I won't be
able to explain it any better on a mailing list than I did in those documents...
SEE ALSO
rssh.conf(5), sshd(8), ssh(1), scp(1), sftp(1).