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

FreeBSD Manual Pages


home | help
ssh(1)				 User Commands				ssh(1)

       ssh - OpenSSH secure shell client (remote login program)

       ssh [-l login_name] [ hostname  |  user@hostname]  [ command]

       ssh  -afgknqtvxACNPTX246	 [-c  cipher_spec]  [-e	escape_char] [-i iden-
       tity_file] [-l login_name] [-o option] [-p  port]  [-L  port:host:host-
       port] [-R port:host:hostport] [hostname | user@hostname]	 [command]

       ssh  (Secure  Shell) is a program for logging into a remote machine and
       for executing commands on a remote machine. It is intended  to  replace
       rlogin  and rsh,	and to provide secure encrypted	communications between
       two untrusted hosts over	an insecure network. X11 connections and arbi-
       trary TCP/IP ports can also be forwarded	over the secure	channel.

       ssh  connects and logs into the specified hostname. The user must prove
       his or her identity to the remote machine using one of several  methods
       depending on the	protocol version used:

   SSH protocol	version	1
       First,	if   the   machine   the  user	logs  in  from	is  listed  in
       /etc/hosts.equiv	or /etc/shosts.equiv on	the remote  machine,  and  the
       user  names are the same	on both	sides, the user	is immediately permit-
       ted to log in. Second, if .rhosts  or .shosts exists in the user's home
       directory on the	remote machine and contains a line containing the name
       of the client machine and the name of the user  on  that	 machine,  the
       user  is	permitted to log in. This form of authentication alone is nor-
       mally not allowed by the	server because it is not secure.

       The second  (and	 primary)  authentication  method  is  the  rhosts  or
       hosts.equiv  method  combined  with  RSA-based  host authentication. It
       means  that  if	the  login  would  be  permitted   by	$HOME/.rhosts,
       $HOME/.shosts, /etc/hosts.equiv,	or /etc/shosts.equiv, and if addition-
       ally   the   server   can   verify   the	  client's   host   key	  (see
       /etc/ssh_known_hosts  in	the FILES section), only then is login permit-
       ted. This authentication	method closes security holes due to IP	spoof-
       ing, DNS	spoofing, and routing spoofing.

       Note  to	 the  administrator:  /etc/hosts.equiv,	$HOME/.rhosts, and the
       rlogin/rsh protocol in general, are inherently insecure and  should  be
       disabled	if security is desired.

       As  a  third  authentication method, ssh	supports RSA-based authentica-
       tion. The scheme	is based on public-key cryptography. There  are	 cryp-
       tosystems where encryption and decryption are done using	separate keys,
       and it is not possible to derive	the decryption key from	the encryption
       key.  RSA is one	such system. The idea is that each user	creates	a pub-
       lic/private key pair for	authentication purposes. The server knows  the
       public  key,  and  only	the  user  knows  the  private	key.  The file
       $HOME/.ssh/authorized_keys lists	the public keys	that are permitted for
       logging	in.  When  the	user logs in, the ssh program tells the	server
       which key pair it would like to	use  for  authentication.  The	server
       checks  if  this	 key is	permitted, and if so, sends the	user (actually
       the ssh program running on behalf of the	user) a	challenge in the  form
       of  a  random number, encrypted by the user's public key. The challenge
       can only	be decrypted using the proper private key. The	user's	client
       then  decrypts  the challenge using the private key, proving that he or
       she knows the private key but without disclosing	it to the server.

       ssh implements the RSA authentication protocol automatically. The  user
       creates	his or her RSA key pair	by running ssh-keygen(1).  This	stores
       the  private  key  in  $HOME/.ssh/identity  and	the  public   key   in
       $HOME/.ssh/	in  the	user's home directory. The user	should
       then copy the to $HOME/.ssh/authorized_keys	in his or  her
       home  directory	on the remote machine (the authorized_keys file	corre-
       sponds to the conventional $HOME/.rhosts	file,  and  has	 one  key  per
       line,  though the lines can be very long). After	this, the user can log
       in without giving the password. RSA authentication is much more	secure
       than rhosts authentication.

       The  most  convenient  way to use RSA authentication may	be with	an au-
       thentication agent. See ssh-agent(1) for	more information.

       If other	authentication methods fail, ssh prompts the user for a	 pass-
       word.  The  password  is	sent to	the remote host	for checking. However,
       since all communications	are encrypted, the password cannot be seen  by
       someone listening on the	network.

   SSH protocol	version	2
       When  a user connects using the protocol	version	2, different authenti-
       cation methods are available. At	first, the client attempts to  authen-
       ticate  using the public	key method. If this method fails, password au-
       thentication is tried.

       The public key method is	similar	to RSA authentication described	in the
       previous	 section  except that the DSA algorithm	is used	instead	of the
       patented	 RSA  algorithm.  The  client  uses  his   private   DSA   key
       $HOME/.ssh/id_dsa  to  sign the session identifier and sends the	result
       to the server. The server checks	whether	the  matching  public  key  is
       listed  in $HOME/.ssh/authorized_keys and grants	access if both the key
       is found	and the	signature is correct. The session  identifier  is  de-
       rived  from  a  shared  Diffie-Hellman  value  and is known only	to the
       client and the server.

       If public key authentication fails or is	not available, a password  can
       be  sent	 encrypted to the remote host for proving the user's identity.
       This protocol 2 implementation does not yet support Kerberos  or	 S/Key

       Protocol	 2  provides  additional  mechanisms  for confidentiality (the
       traffic is encrypted using 3DES,	Blowfish, CAST128 or Arcfour) and  in-
       tegrity	(hmac-sha1,  hmac-md5).	 Notice	that protocol 1	lacks a	strong
       mechanism for ensuring the integrity of the connection.

   Login session and remote execution
       When the	user's identity	has been accepted by the  server,  the	server
       either  executes	 the given command, or logs into the machine and gives
       the user	a normal shell on the remote machine. All  communication  with
       the remote command or shell will	be automatically encrypted.

       If  a  pseudo-terminal  has  been allocated (normal login session), the
       user can	disconnect with	~., and	suspend	ssh with  ~^Z.	All  forwarded
       connections  can	 be  listed with ~#. If	the session blocks waiting for
       forwarded X11 or	TCP/IP connections to  terminate,  ssh	can  be	 back-
       grounded	with ~&, although this should not be used while	the user shell
       is active, as it	can cause the shell to hang. All available escapes can
       be listed with ~?.

       A  single  tilde	character can be sent as ~~ (or	by following the tilde
       by a character other than those described above). The escape  character
       must  always  follow a newline to be interpreted	as special. The	escape
       character can be	changed	in configuration files or on the command line.

       If no pseudo tty	has been allocated, the	session	is transparent and can
       be  used	to reliably transfer binary data. On most systems, setting the
       escape character	to "none" will also make the session transparent  even
       if a tty	is used.

       The  session terminates when the	command	or shell in the	remote machine
       exits and all X11 and TCP/IP connections	have  been  closed.  The  exit
       status of the remote program is returned	as the exit status of ssh.

   X11 and TCP forwarding
       If the user is using X11	(the DISPLAY environment variable is set), the
       connection to the X11 display is	automatically forwarded	to the	remote
       side  in	 such  a  way that any X11 programs started from the shell (or
       command)	will go	through	the encrypted channel, and the	connection  to
       the  real X server will be made from the	local machine. The user	should
       not manually set	DISPLAY. Forwarding of X11 connections can be  config-
       ured on the command line	or in configuration files.

       The DISPLAY value set by	ssh will point to the server machine, but with
       a display number	greater	than zero. This	is  normal  behavior,  because
       ssh creates a "proxy" X server on the server machine for	forwarding the
       connections over	the encrypted channel.

       ssh will	also automatically set up Xauthority data on  the  server  ma-
       chine.  For  this  purpose,  it	will  generate	a random authorization
       cookie, store it	in Xauthority on the server, and verify	that any  for-
       warded  connections carry this cookie and replace it by the real	cookie
       when the	connection is opened. The real authentication cookie is	 never
       sent to the server machine (and no cookies are sent in the plain).

       If  the	user  is  using	an authentication agent, the connection	to the
       agent is	automatically forwarded	to the remote side unless disabled  on
       the command line	or in a	configuration file.

       Forwarding  of arbitrary	TCP/IP connections over	the secure channel can
       be specified either on the command line or in a configuration file. One
       possible	 application of	TCP/IP forwarding is a secure connection to an
       electronic purse. Another possible application is going	through	 fire-

   Server authentication
       ssh  automatically maintains and	checks a database containing identifi-
       cations for all hosts it	has ever been used with.  RSA  host  keys  are
       stored  in  $HOME/.ssh/known_hosts  in the user's home directory. Addi-
       tionally, the file /etc/ssh_known_hosts is  automatically  checked  for
       known  hosts. Any new hosts are automatically added to the user's file.
       If a host's identification ever changes,	ssh warns about	this and  dis-
       ables  password	authentication	to prevent a trojan horse from getting
       the user's password. Another purpose of this mechanism  is  to  prevent
       man-in-the-middle  attacks  which could otherwise be used to circumvent
       the encryption. The StrictHostKeyChecking option	 (see  below)  can  be
       used  to	 prevent logins	to machines whose host key is not known	or has

       The following options are supported:

       -2    Forces ssh	to try protocol	version	2 only.

       -4    Forces ssh	to use IPv4 addresses only.

       -6    Forces ssh	to use IPv6 addresses only.

       -a    Disables forwarding of the	authentication agent connection.

       -A    Enables forwarding	of the authentication agent  connection.  This
	     can  also	be  specified  on  a per-host basis in a configuration

       -c blowfish | 3des
	     Selects the cipher	to use for encrypting  the  session.  3des  is
	     used  by  default.	It is believed to be secure. 3des (triple-des)
	     is	an encrypt-decrypt-encrypt triple with three  different	 keys.
	     It	 is  presumably	 more  secure than the des cipher, which is no
	     longer fully supported in ssh. blowfish is	a fast	block  cipher,
	     it	appears	very secure and	is much	faster than 3des.

       -c 3des-cbc,blowfish-cbc,aes128-cbc
	     Additionally,  for	 protocol  version 2 a comma-separated list of
	     ciphers can be specified in order of preference. Protocol version
	     2 supports	3DES, Blowfish,	and AES	128 in CBC mode.

       -C    Requests  compression  of	all  data  (including  stdin,  stdout,
	     stderr, and data for forwarded X11	and TCP/IP  connections).  The
	     compression algorithm is the same used by gzip(1).	 (The gzip man
	     page is available in the SUNWsfman	package.) The "level"  can  be
	     controlled	 by  the CompressionLevel option (see below). Compres-
	     sion is desirable on modem	lines and other	slow connections,  but
	     will  only	 slow  down things on fast networks. The default value
	     can be set	on a host-by-host basis	in  the	 configuration	files.
	     See the Compress option below.

       -e ch | ^ch | none
	     Sets the escape character for sessions with a pty (default: `~').
	     The escape	character is only recognized at	 the  beginning	 of  a
	     line.  The	 escape	 character  followed by	a dot (".") closes the
	     connection. If followed by	control-Z, the escape  character  sus-
	     pends the connection. If followed by itself, the escape character
	     sends itself once.	Setting	the character to "none"	 disables  any
	     escapes and makes the session fully transparent.

       -f    Requests  ssh  to go to background	just before command execution.
	     This  is  useful  if  ssh	is  going  to  ask  for	 passwords  or
	     passphrases,  but	the  user wants	it in the background. This im-
	     plies the -n option. The recommended way to start X11 programs at
	     a remote site is with something like ssh -f host xterm.

       -g    Allows remote hosts to connect to local forwarded ports.

       -i identity_file
	     Selects  the  file	 from which the	identity (private key) for RSA
	     authentication is read. Default  is  $HOME/.ssh/identity  in  the
	     user's  home directory. Identity files may	also be	specified on a
	     per-host basis in the configuration file. It is possible to  have
	     multiple -i options (and multiple identities specified in config-
	     uration files).

       -l login_name
	     Specifies the user	to log in as on	the remote machine. This  also
	     may be specified on a per-host basis in the configuration file.

       -L port:host:hostport
	     Specifies that the	given port on the local	(client) host is to be
	     forwarded to the given host and port on  the  remote  side.  This
	     works  by	allocating a socket to listen to the port on the local
	     side. Then, whenever a connection is made to this port, the  con-
	     nection  is forwarded over	the secure channel and a connection is
	     made to host port hostport	from the remote	 machine.   Port  for-
	     wardings  can  also  be specified in the configuration file. Only
	     root can forward privileged ports.	IPv6 addresses can  be	speci-
	     fied with an alternative syntax: port/host/hostport.

       -n    Redirects	stdin  from /dev/null (actually, prevents reading from
	     stdin). This must be used when ssh	is run in  the	background.  A
	     common  trick  is to use this to run X11 programs on a remote ma-
	     chine. For	example,

	     ssh -n emacs &

	     will start	an emacs on, and the X11  connection
	     will  be  automatically  forwarded	over an	encrypted channel. The
	     ssh program will be put in	the background.	This does not work  if
	     ssh  needs	 to ask	for a password or passphrase.  See also	the -f

       -N    Does not execute a	remote command.	This is	 useful	 if  you  just
	     want to forward ports (protocol version 2 only).

       -o option
	     Can  be used to give options in the format	used in	the configura-
	     tion file.	This is	useful for specifying options for which	 there
	     is	 no separate command-line flag.	The option has the same	format
	     as	a line in the configuration file.

       -p port
	     Specifies the port	to connect to on the remote host. This can  be
	     specified on a per-host basis in the configuration	file.

       -P    Uses  a non-privileged port for outgoing connections. This	can be
	     used if your firewall does	not permit connections from privileged
	     ports. Notice that	this option turns off RhostsAuthentication and

       -q    Quiet mode. Causes	all warning and	diagnostic messages to be sup-
	     pressed. Only fatal errors	are displayed.

       -R port:host:hostport
	     Specifies	that  the given	port on	the remote (server) host is to
	     be	forwarded to the given host and	port on	the local  side.  This
	     works  by allocating a socket to listen to	the port on the	remote
	     side. Then, whenever a connection is made to this port, the  con-
	     nection  is forwarded over	the secure channel and a connection is
	     made to host port hostport	from the local machine.	 Port forward-
	     ings  can also be specified in the	configuration file. Privileged
	     ports can be forwarded only when logging in as root on the	remote

       -t    Forces  pseudo-tty	 allocation. This can be used to execute arbi-
	     trary screen-based	programs on a remote  machine,	which  can  be
	     very useful, for example, when implementing menu services.

       -T    Disables pseudo-tty allocation (protocol version 2	only).

       -v    Verbose  mode.  Causes  ssh to print debugging messages about its
	     progress. This is helpful in  debugging  connection,  authentica-
	     tion,  and	 configuration	problems. Multiple -v options increase
	     the verbosity. Maximum is 3.

       -x    Disables X11 forwarding.

       -X    Enables X11 forwarding. This can also be specified	on a  per-host
	     basis in a	configuration file.

       ssh will	normally set the following environment variables:

	     The DISPLAY variable indicates the	location of the	X11 server. It
	     is	automatically set by ssh to point to a value of	the form host-
	     name:n  where  hostname  indicates	the host where the shell runs,
	     and n is an integer greater than or equal to  1.  ssh  uses  this
	     special value to forward X11 connections over the secure channel.
	     The user should normally not set DISPLAY explicitly, as that will
	     render  the X11 connection	insecure (and will require the user to
	     manually copy any required	authorization cookies).

       HOME  Set to the	path of	the user's home	directory.

	     Synonym for USER. Set for compatibility  with  systems  that  use
	     this variable.

       MAIL  Set to point to the user's	mailbox.

       PATH  Set to the	default	PATH, as specified when	compiling ssh.

	     Indicates	the  path  of a	unix-domain socket used	to communicate
	     with the agent.

	     Identifies	the client end of the connection.  The	variable  con-
	     tains  three  space-separated  values:  client ip-address,	client
	     port number, and server port number.

	     This is set to the	name of	the tty	(path to the  device)  associ-
	     ated  with	 the  current shell or command.	If the current session
	     has no tty, this variable is not set.

       TZ    The timezone variable is set to indicate the present timezone  if
	     it	 was  set  when	 the  daemon  was started, that	is, the	daemon
	     passes the	value on to new	connections.

       USER  Set to the	name of	the user logging in.

       Additionally, ssh reads $HOME/.ssh/environment and adds	lines  of  the
       format VARNAME=value to the environment

       The following exit values are returned:

       0     Successful	completion.

       1     An	error occurred.

	     Records host keys for all hosts the user has logged into that are
	     not in /etc/ssh_known_hosts. See sshd(1M).


	     Contains the RSA and the DSA authentication identity of the user.
	     These  files contain sensitive data and should be readable	by the
	     user but not accessible by	 others	 (read/write/execute).	Notice
	     that  ssh	ignores	a private key file if it is accessible by oth-
	     ers. It is	possible to specify a passphrase when  generating  the
	     key. The passphrase will be used to encrypt the sensitive part of
	     this file using 3DES.


	     Contains the public key for authentication, that is,  the	public
	     part of the identity file in human-readable form. The contents of
	     the   $HOME/.ssh/   file   should   be	   added    to
	     $HOME/.ssh/authorized_keys	 on all	machines where you wish	to log
	     in	  using	  RSA	authentication.	  The	 contents    of	   the
	     $HOME/.ssh/  file  should be added to $HOME/.ssh/autho-
	     rized_keys	on all machines	where you wish to log in using DSA au-
	     thentication.  These  files  are  not sensitive and can, but need
	     not, be readable by anyone. These files are never used  automati-
	     cally  and	are not	necessary. They	are provided only for the con-
	     venience of the user.

	     This is the per-user configuration	file. The format of this  file
	     is	 described  above.  This  file is used by the ssh client. This
	     file does not usually contain any sensitive information, but  the
	     recommended  permissions  are read/write for the user and not ac-
	     cessible by others.

	     Lists the DSA keys	that can be used for logging in	as this	 user.
	     This  file	 is  not highly	sensitive, but the recommended permis-
	     sions are read/write for the user and not accessible by others.

	     Systemwide	list of	known host keys. /etc/ssh_known_hosts contains
	     RSA  keys.	This file should be prepared by	the system administra-
	     tor to contain the	public host keys of all	machines in the	 orga-
	     nization  and  should be world-readable. The file contains	public
	     keys, one per line, in the	following format,  with	 fields	 sepa-
	     rated  by	spaces:	system name, number of bits in modulus,	public
	     exponent, modulus,	and optional  comment  field.  When  different
	     names  are	 used  for  the	same machine, all such names should be
	     listed, separated by commas. See sshd(1M).

	     The canonical system name (as returned by name servers)  is  used
	     by	 sshd(1M)  to  verify  the  client host	when logging in. Other
	     names are needed because ssh does not convert  the	 user-supplied
	     name  to  a  canonical  name  before checking the key, to prevent
	     someone with access to the	name servers from being	able  able  to
	     fool host authentication.

	     Systemwide	 configuration	file.  This file provides defaults for
	     those values that are not specified in the	 user's	 configuration
	     file, and for those users who do not have a configuration file.

	     This file must be world-readable.

	     This file is used in .rhosts authentication to list the host/user
	     pairs that	are permitted to log in. (Notice  that	this  file  is
	     also  used	 by  rlogin and	rsh, which makes using this file inse-
	     cure.) Each line of the file contains a host name (in the canoni-
	     cal  form returned	by name	servers), and then a user name on that
	     host, separated by	a space. On some machines, this	file may  need
	     to	 be  world-readable  if	the user's home	directory is on	an NFS
	     partition,	because	sshd(1M) reads it as root. Additionally,  this
	     file  must	 be  owned by the user and must	not have write permis-
	     sions for anyone else. The	recommended permission	for  most  ma-
	     chines is read/write for the user and not accessible by others.

	     Notice  that,  by	default, sshd(1M) will be installed so that it
	     requires successful RSA  host  authentication  before  permitting
	     .rhosts  authentication. If your server machine does not have the
	     client's host key in /etc/ssh_known_hosts,	you can	 store	it  in
	     $HOME/.ssh/known_hosts.  The easiest way to do this is to connect
	     back to the client	from the server	machine	using ssh.  This  will
	     automatically add the host	key to $HOME/.ssh/known_hosts.

	     This  file	 is  used exactly the same way as .rhosts. The purpose
	     for having	this file is to	be able	to use	rhosts	authentication
	     with ssh without permitting login with rlogin(1) or rsh(1).

	     This  file	 is  used  during  .rhosts authentication. It contains
	     canonical hosts names, one	per line. (See sshd(1M)	for  the  full
	     format  description.).  If	the client host	is found in this file,
	     login is automatically permitted, provided	that client and	server
	     user names	are the	same. In addition, successful RSA host authen-
	     tication is normally required. This file should only be  writable
	     by	root.

	     This file is processed exactly as /etc/hosts.equiv. This file may
	     be	useful to permit logins	using ssh but not using	rsh or rlogin.

	     Commands in this file are executed	by ssh when the	user  logs  in
	     just  before the user's shell or command is started. See sshd(1M)
	     for more information.

	     Commands in this file are executed	by ssh when the	user  logs  in
	     just  before the user's shell or command is started. See sshd(1M)
	     for more information.

	     Contains additional definitions for  environment  variables.  See

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWsshu			   |

       rlogin(1),  rsh(1),  scp(1),  ssh-add(1),  ssh-agent(1),	ssh-keygen(1),
       telnet(1), sshd(1M), ssh_config(4), attributes(5)

       To view license terms, attribution, and copyright for OpenSSH, the  de-
       fault path is /var/sadm/pkg/SUNWsshdr/install/copyright.	If the Solaris
       operating environment has been installed	anywhere other	than  the  de-
       fault,  modify the given	path to	access the file	at the installed loca-

       OpenSSH is a derivative of the original and free	ssh 1.2.12 release  by
       Tatu  Ylonen.  Aaron  Campbell,	Bob Beck, Markus Friedl, Niels Provos,
       Theo de Raadt and Dug Song removed many bugs, added newer features  and
       created	Open SSH. Markus Friedl	contributed the	support	for SSH	proto-
       col versions 1.4	and 2.0.

SunOS 5.9			  25 Feb 2002				ssh(1)


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

home | help