rssh [ options... ] [ ... ]
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
desireable to provide restricted access should be edited, such that
their shell is rssh. For example:
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 substitu-
tion), 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.
Read this section with exceptional care, or you may put your system at
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 mecha-
nisms 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
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 arbi-
trary 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
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 envi-
ronment, 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
# 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 com-
mand 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-zeal-
ous 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, how-
ever, 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; com-
mands 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
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
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).
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 con-
tact 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 environ-
ments. I take security problems seriously, and will work to resolve
them as quickly as possible.
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 distribu-
tion keeps its documentation files (usually /usr/share/doc/rssh-ver-
sion/ 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
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017
All Rights Reserved.