RSSH(1) 							  Derek D. Martin							   RSSH(1)

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
       desireable 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 parti-
       tion 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  pos-
       sibly  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 environ-
       ment,  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  exe-
       cutable,  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  com-
       mon.

       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 direc-
       tory 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-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 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).

man pages							    1 Aug 2010								   RSSH(1)