Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
RSSH(1)				Derek D. Martin			       RSSH(1)

       rssh - restricted secure	shell allowing only scp	and/or sftp

       rssh [ options... ] [ ... ]
       rssh -v

       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, 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  de-
       sireable	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
       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 af-
       fected versions of rssh using strict access controls to files, by  mak-
       ing  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 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
		     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  ac-
		     cess 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 ac-
       cess to the system other	than  through  rssh.   Otherwise,  users  with
       shell  access  could  potentially exploit undiscovered bugs in rssh_ch-
       root_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  en-
       sure  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  seperate
       filesystem  from	 your system's executables.  If	possible in your envi-
       ronment,	make sure you mount this filesystem using the noexec  and  no-
       suid  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  il-

	      #	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 re-
       jecting 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 en-
       tirely 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
       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 prob-
       lem 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 en-
       vironment.  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  de-
       tect  that  OpenSSH  3.5	 is present, and disable the default of	static

       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 di-
       rectly.	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 se-
       curity 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  po-
       tential	security problem.  Security problems should be dealt with pri-
       vately, 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  bi-
       nary  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  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...

       rssh.conf(5), sshd(8), ssh(1), scp(1), sftp(1).

man pages			  1 Aug	2010			       RSSH(1)


Want to link to this manual page? Use this URL:

home | help