unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



ssh2(1)								      ssh2(1)



NAME

  ssh2,	ssh - Secure Shell client remote login and command execution applica-
  tion

SYNOPSIS

  ssh2 [-l login_name] hostname	[command]

  ssh2 [-l login_name] [-n] [+a] [-a] [+x] [+X]	[-x] [-i file] [-F file] [-t]
  [-v] [-d debug_level]	[-V] [-q] [-f [o]] [-e char] [-c cipher] [-m MAC] [-p
  port]	[-S] [-L [protocol/]port:host:hostport]	[-L socks/port]	[-R
  [protocol/]port:host:hostport] [-g] [+g] [+C]	[-C] [-E provider] [-I init-
  string] [-4] [-6] [-1	[ti]] [-o option] [-h] [login_name@] hostname [port#]
  [command]

OPTIONS

  -l login_name
      Specifies	the user for login to the remote system.

  -n  Redirects	input from /dev/null (i.e., do not read	stdin).	This option
      also can be specified in the configuration file.

  +a  Enables authentication agent forwarding (default).

  -a  Disables authentication agent forwarding.

  +x  Enables X11 connection forwarding	(default).  If the X11 SECURITY
      extension	is compiled, you treat the client applications as untrusted.
      See the TrustX11Applications section in ssh2_config(4) for additional
      details.

  +X  Similar to +x, but the client applications are treated as	trusted.

  -x  Disables X11 connection forwarding.

  -i file
      Specifies	the identity file for public key authentication. This option
      also can be specified in the configuration file.

  -F file
      Specifies	an alternative client configuration file. The default client
      configuration file is the	/etc/ssh2/ssh2_config file.  Each user can
      also have	their own ssh2_config file in their $HOME/.ssh2	directory,
      where $HOME is the name of the user's account. The
      /etc/ssh2/ssh2_config file is read first,	then the user's	copy. The
      last obtained value for a	keyword	is used.

  -t  For tty allocation. For example, allocate	a tty even if a	command	is
      given. This option also can be specified in the /etc/ssh2/ssh2_config
      configuration file.

  -v  Enables verbose mode. Displays verbose debugging messages. Equal to the
      -d 2 option. This	option also can	be specified in	the
      /etc/ssh2/ssh2_config configuration file.

  -d debug_level
      Prints extensive debug information to stderr. The	debug_level argument
      is a number from 0 to 99,	where 99 specifies that	all debug information
      should be	displayed, or it is a comma-separated list of assignments.
      This should be the first argument	on the command line.

  -V  Displays the version string.

  -q  Disables warning messages.  This option  also can	be specified in	the
      /etc/ssh2/ssh2_config configuration file.

  -f [o]
      Forks into the background	after authentication waiting indefinitely for
      connections.  It must be killed for it to	stop listening.	This option
      implies -S and -n. The o argument	specifies one-shot mode, which means
      that once	all channels are closed, the ssh2 command exits. This option
      also can be specified in the /etc/ssh2/ssh2_config configuration file.

  -e char
      Sets the escape character. The default escape character is the tilde
      (~). Use none to disable the escape character. This option also can be
      specified	in the /etc/ssh2/ssh2_config configuration file.

  -c cipher
      Specifies	the encryption algorithm to use. See the Ciphers keyword in
      the /etc/ssh2/sshd2_config file and in the /etc/ssh2/ssh2_config file
      for more information.  Multiple -c options are allowed; a	single -c
      option can specify only one cipher.  Allowed values are aes, blowfish,
      twofish, cast, arcfour, 3des, and	des.

  -m MAC
      Specifies	the Message Authentication Code	(MAC) algorithm. See the MACs
      keyword in the /etc/ssh2/sshd2_config file and in	the
      /etc/ssh2/ssh2_config file for more information. Multiple	-m options
      are allowed; a single -m option can have only one	MAC.

  -p port #
      Specifies	the port to connect to on the remote system. This option also
      can be specified in the /etc/ssh2/ssh2_config file.

  -S  Disables requests	for a session channel. This can	be used	with port-
      forwarding requests, if a	session	channel	(and tty) is not needed, or
      the server does not give one.

  -L [protocol/]port:host:hostport
      Fowards the given	port on	the local (client) system to the specified
      host and port on the remote system.  This	allocates a socket to listen
      to port on the local system. Whenever a connection is made to this
      port, the	connection is forwarded	over the secure	channel, and a con-
      nection is made to the host:hostport argument from the remote system.
      Only root	can forward privileged ports. The argument protocol enables
      the protocol-specific forwarding.	The protocols implemented are tcp
      (default,	no special processing) and ftp.	 Temporary forwardings are
      created for ftp data channels, effectively securing the whole ftp	ses-
      sion. This option	can also be specified in the /etc/ssh2/ssh2_config
      file.

      With socks, the Secure Shell client will act as a	SOCKS server for
      other applications, creating forwards as requested by the	SOCKS tran-
      saction. Secure Shell supports both SOCKS4 and SOCKS5, so	you can	con-
      figure it	to use your socks forward by setting an	approriate value for
      the SocksServer configuration option. See	ssh2_config(4).	If the local
      host is given, forwarding	listens	only to	the interface that is bound
      to the address of	the given host.	If it is omitted, all interfaces are
      listening.

  -L socks/port
      Same as above.

  -R [protocol/]port:host:hostport
      Forwards the given port on the remote (server) system to the specified
      host and port on the local system.  This allocates a socket to listen
      to port on the remote system. Whenever a connection is made to this
      port, the	connection is forwarded	over the secure	channel, and a con-
      nection is made to the host:hostport argument from the local system.
      Only root	can forward privileged ports on	the remote system. The argu-
      ment protocol enables the	protocol-specific forwarding. The protocols
      implemented are tcp (default, no special processing) and ftp. Temporary
      forwardings are created for ftp data channels, effectively securing the
      whole ftp	session.  This option also can be specified in the
      /etc/ssh2/ssh2_config file.

  -g  Allows gateway ports (i.e., remote hosts can connect to locally for-
      warded ports).

  +g  Denies gateway ports.

  +C  Enables compression.

  -C  Disables compression. (default)

  -E provider
      Uses an external key provider for	user authentication. This feature is
      only available when external key support is included in the software.
      See ssh-externalkeys(4) for more information.

  -I initstring
      Uses an initialization string to access an external key provider for
      user authentication. This	feature	is onlyavailable when external key
      support is included in the software. See ssh-externalkeys(4) for more
      information.

  -4  Uses IPv4	to connect.

  -6  Uses IPv6	to connect.

  -1 [ti]
      Falls back to the	SSH1 protocol. An additional argument is mandatory.
      The i argument signifies internal	emulation, and the t argument indi-
      cates traditional	mechanism.

  -o option
      Specifies	an option in the format	used in	the /etc/ssh2/ssh2_config
      file.  This is useful for	specifying an option for which there is	no
      command-line option.  Comment lines are not accepted with	this option.
      Where aplication,	use the	egrep regex format.

  -h  Displays help on ssh2 command options.

DESCRIPTION

  The ssh2 command creates a secure connection between a Secure	Shell client
  and server for remote	log in and command execution.  The ssh2	command	is
  intended as a	secure replacement for the rlogin and rsh commands. A secure
  connection provides client and server	authentication,	user authentication,
  data encryption, data	integrity, and nonrepudiation. X11 connections and
  arbitrary TCP/IP ports also can be forwarded over these secure channels.

  A Secure Shell client	and server use public host keys	to authenticate	each
  other. When a	client connects	to a server for	the first time,	the user is
  prompted to accept a copy of the server's public host	key. If	the user
  accepts the key, a copy of the server's public host key is copied to the
  user's hostkeys directory on the client. The client uses this	public host
  key to authenticate the server on subsequent connects. A Secure Shell
  server authenticates a user by using password	authentication,	host-based
  authentication, or public key	authentication.

  Private and public key pairs can be created with ssh-keygen2.	 See ssh-
  agent2 for information on how	to use public-key authentication in conjunc-
  tion with an authentication agent.  If other authentication methods fail,
  the ssh2 command will	prompt for a password.	The filenames of private keys
  that are used	in authentication are stored in	$HOME/.ssh2/identification.
  When the user	tries to authenticate himself, the server checks
  $HOME/.ssh2/authorization for	filenames of matching public keys and sends a
  challenge to the user.  The user is authenticated  by	signing	the challenge
  using	the private key.

  After	the user's identity has	been proven, the Secure	Shell server executes
  the given command or logs the	user into the system and gives the user	a
  normal shell on the remote system.  All communication	with the remote	com-
  mand or shell	will be	encrypted automatically	and checked for	integrity. If
  no pseudo-tty	was allocated, the session is transparent and can be used to
  reliably transfer binary data. The session terminates	when the command or
  shell	on the remote system 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 ssh2.

  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 configured	on the com-
  mand line or in configuration	files.	The DISPLAY value set by the ssh2
  command will point to	the server machine, but	with a display number greater
  than zero.  This is normal, and happens because ssh2 creates a proxy X
  server on the	server machine for forwarding the connections over the
  encrypted channel.

  The ssh2 command will	also automatically set up the Xauthority data on the
  server machine.  It will generate a random authentication cookie, store it
  in the Xauthority data on the	server,	and verify that	any forwarded connec-
  tions	carry this cookie and replace it with the real cookie when the con-
  nection is opened.  The real authentication cookie is	never sent to the
  server.

  If the user is using an authentication agent,	the connection to the agent
  is automatically forwarded to	the remote side	unless disabled	on the com-
  mand 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.  TCP/IP forwarding can be used for secure
  connections to electronic purses or for going	through	firewalls.

  Ssh2 automatically maintains and checks a database containing	the public
  host keys.  When logging in on a host	for the	first time, the	host's public
  key is stored	in the .ssh2/hostkey_PORTNUMBER_HOSTNAME.pub file in the
  user's home directory.  If a host's identification changes, ssh2 issues a
  warning and disables the password authentication in order to prevent man-
  in-the- middle attacks which could otherwise be used to circumvent the
  encryption or	steal passwords.

  Secure Shell has built-in support for	SOCKS versions 4 and 5 for traversing
  firewalls.  (See the Environment Variables section.) However,	the SOCKS5
  support does not include support for the SOCKS authentication	methods.

  See Security Administration for more information about Secure	Shell clients
  and servers and Secure Shell authentication.




NOTES

  The ssh2 command obtains configuration data from the following sources (in
  this order):

   1.  /etc/ssh2/ssh2_config (system's global configuration file )

   2.  $HOME/.ssh2/ssh2_config (user's configuration file)

   3.  command-line options

  For each parameter, the last obtained	value will be effective.

  Escape Sequences


  The ssh2 command supports the	escape sequences that.	For any	escape
  sequences to take effect, you	must enter a newline character (press the
  Enter	key), then enter the characters. For example, a	newline, a tilde (~),
  and the appropriate character	for a task. Following are the escape
  sequences:

  ~.  Terminates the connection.

  ~Ctrl/Z
      Suspends the session. Simultaneously press the Ctrl key and the Z	key.

  ~~  Sends the	escape character.

  ~#  Lists forwarded connections.

  ~-  Disables the escape character.

  ~?  Displays escape sequences.

  ~r  Initiates	rekeying manually.

  ~s  Displays statistics about	the connection,	including server and client
      version, compression, packets in,	packets	out, compression, key
      exchange algorithms, public key algorithms, and symmetric	ciphers.

  ~V  Displays the client version number to stderr (useful for troubleshoot-
      ing).

EXIT STATUS

  On normal execution, the ssh2	command	exits with the status of the command
  run. On successful runs this is normally zero.  If ssh2 encounters an
  error, you usually see the reason in an error	message. Some common exit
  values for ssh2 include the following:

  128 +	signal number
	  Returned if ssh2 encounters a	fatal signal. For example, 143 would
	  be returned for SIGTERM (signal number 15).

  64 + disconnect code
	  Returned on disconnect, clean	or otherwise.

	  Following are	some disconnect	codes:

	  1	  host not allowed to connect

	  2	  protocol error

	  3	  key exchange failed

	  4	  key exchange failed

	  5	  mac error

	  6	  compression error

	  7	  service not available

	  8	  protocol version not supported

	  9	  host key not verifiable

	  10	  connection lost

	  11	  by application

	  12	  too many connections

	  13	  auth cancelled by user

	  14	  no more auth methods available

	  15	  illegal user name

		  For example, 74 would	mean "Connection lost."

  255	  Returned on a	call for ssh_fatal().

  254	  Usually means	that ssh2 failed to exec(3) something (generic
	  catch-all in the libraries for failures to fork(2) or	exec(3)).

  1	  Generic error.

  2	  Connecting to	remote host failed.

ENVIRONMENT VARIABLES

  The ssh2 command will	set the	following environment variables. Addition-
  ally,	the ssh2 command reads the /etc/environment file and the
  $HOME/.ssh2/environment file and adds	lines of the format VARNAME=value to
  the environment.

  DISPLAY
      Indicates	the location of	the X11	server.	 It is automatically set to
      point to a value of the form hostname:n, where hostname is the host
      where the	shell runs, and	n is an	integer	>= 1. The ssh2 command uses
      this special value to forward X11	connections over the secure channel.
      The user should normally not set the DISPLAY environment variable, as
      that will	render the X11 connection insecure (and	will require the user
      to manually copy any required authorization cookies).

  HOME
      Points to	the user's home	directory.

  LOGNAME
      Synonym for USER;	sets for compatibility with systems using this vari-
      able.

  MAIL
      Points to	the user's mailbox.

  PATH
      Sets the default PATH, as	specified when compiling the ssh2 command or,
      on some systems, /etc/environment	or /etc/default/login.

  SSH_SOCKS_SERVER
      If SOCKS is used,	it is configured with this variable. The format	of
      the variable is:


	   socks://username@socks_server:port/network/netmask,network/netmask...

      For example, setting the environment variable SSH_SOCKS_SERVER to
      socks://mylogin@socks.ssh.com:1080/203.123.0.0/16,198.74.23.0/24 uses
      host socks.ssh.com port 1080 as the SOCKS	server if a connection is
      attempted	outside	of networks 203.123.0.0	(16 bit	domain)	and
      198.74.23.0 (8 bit domain) which are connected directly.

      A	default	value for the SSH_SOCKS_SERVER variable	can be specified at
      compile time by specifying --with-socks-server=VALUE on the configure
      command line when	compiling the ssh2 command. The	default	value can be
      cancelled	by setting SSH_SOCKS_SERVER to an empty	string and overridden
      by setting SSH_SOCKS_SERVER to a new value.  If the SSH_SOCKS_SERVER
      variable is set, it should contain a local loopback network
      (127.0.0.0/8) as the network that	is connected directly.

  SSH2_AUTH_SOCK
      Indicates	the path of a unix-domain socket used to communicate with the
      authentication agent (or its local representative).

  SSH2_CLIENT
      Identifies the client of the connection.	The variable contains the
      following	space-separated	values:	client ip-address, client port
      number, host ip-address, and server port number.

  SSH2_ORIGINAL_COMMAND
      The original command given to the	ssh2 command if	a forced command is
      run. For example,	it can be used to fetch	arguments from the other sys-
      tem. This	does not have to be a real command; it can be the name of a
      file, device, parameters or anything else.

  SSH2_TTY
      Set to the name of the tty (path to the device) associated with the
      current shell or command.	 If the	current	session	has no tty, this
      variable is not set.

  TZ  Sets to the present time zone if it was set when the daemon was
      started. The daemon passes the value to new connections.

  USER
      Sets to the name of the user logging in.

FILES

  /etc/ssh2/ssh2_config
      Specifies	Secure Shell client configuration information.

  /etc/ssh2/sshd2_config
      Specifies	Secure Shell server configuration information.

  $HOME/.ssh2/random_seed
      Seeds the	random number generator.  This file is created the first time
      the program is run and it	is updated automatically.  The user should
      never need to modify this	file. This file	contains sensitive data	and
      its permissions should be	set to "read/write" for	the user and "not
      accessible" for others.

  $HOME/.ssh2/ssh2_config
      Contains per-user	configuration information.  The	format of this file
      is described above.  This	file is	used by	the Secure Shell client.
      This file	does not usually contain any sensitive information, but	the
      recommended permissions are "read/write" for the user, and "not acces-
      sible" for others.

  $HOME/.ssh2/identification
      Contains information on how the user will	be authenticated when con-
      tacting a	specific host.	The identification file	has the	same general
      syntax as	the configuration files. The following keywords	can be used:

      IdKey   Precedes the file	name of	a private key in the $HOME/.ssh2
	      directory	used for identification	when contacting	a host.	If
	      there is more than one IdKey, they are tried in the order	that
	      they appear in the identification	file.

      PgpSecretKeyFile
	      Precedes the file	name of	the user's OpenPGP private keyring in
	      the $HOME/.ssh2 directory.  The OpenPGP keys listed after	this
	      line are expected	to be found from this file. The	keys identi-
	      fied with	IdPgpKey*-keywords are used like ones identified with
	      IdKey-keyword.

      IdPgpKeyName
	      Preceds the OpenPGP key name of the key in the PgpSecretKeyFile
	      file.

      IdPgpKeyFingerprint
	      Precedes the OpenPGP key fingerprint of the key in the
	      PgpSecretKeyFile file.

      IdPgpKeyId
	      Precedes the OpenPGP key ID of the key in	the PgpSecretKeyFile
	      file.

  $HOME/.ssh2/authorization
      Contains information on how the server will verify the identity of an
      user.  The authorization file has	the same general syntax	as the confi-
      guration files.  The following keywords can be used:

      Key     Precedes the file	name of	a public key in	the $HOME/.ssh2
	      directory	used for identification	when contacting	the host.
	      More than	one key	is acceptable for login.

      PgpPublicKeyFile
	      Precedes the file	name of	the user's OpenPGP public keyring in
	      the $HOME/.ssh2directory.	 OpenPGP keys listed after this	line
	      are expected to be found from this file.	Keys identified	with
	      PgpKey*-keywords are used	like ones identified with Key-
	      keyword.

      PgpKeyName
	      Precedes the OpenPGP key name.

      PgpKeyFingerprint
	      Precedes the OpenPGP key fingerprint.

      PgpKeyId
	      Precedes the OpenPGP key ID.

      Options This keyword, if used, must follow the Key or PgpKey* keyword.
	      The various options are specified	as a comma-separated list.
	      (See the Public Key Options section for more details.)

      Command This keyword is deprecated.  Use Options instead.

  $HOME/.ssh2/hostkeys/key_xxxx_yyyy.pub
      These files are the public keys of the hosts to which you	connect. They
      are updated automatically, unless	you set	the StrictHostKeyChecking
      parameter	to yes in the ssh2_config file.	If a host's key	changes, you
      should put the key here only if you are sure that	the new	key is valid
      (i.e.,  there was	no man-in-the-middle attack). The xxxx is the port on
      the server, where	the sshd2 deamon runs, and the yyyy is the host
      (specified on the	command	line).

  /etc/ssh2/hostkeys/key_xxxx_yyyy.pub
      If a host	key is not found from the user's $HOME/.ssh2/hostkeys direc-
      tory, this is the	next location to be checked. These files must be
      updated manually;	no files are put here automatically.

  $HOME/.rhosts
      Contains a list of remote	users who are not required to supply a pass-
      word when	they use Secure	Shell host-based authentication	with the ssh2
      command.	The same file is used by rlogind and rshd.

      The sshd2	differs	from rlogind and rshd in that it requires public
      host-key authentication from the Secure Shell server running on this
      host in addition to validating the host name retrieved from domain name
      servers.	The file must be writable only by the user; it should not be
      accessible to others. It is also possible	to use netgroups in the	file.
      Either host or user name may be of the form +@groupname to specify all
      hosts or all users in the	group.

  $HOME/.shosts
      The same as $HOME/.rhosts. However, this file is not used	by rlogin and
      rsh, so using it permits access using ssh2 only.

  /etc/hosts.equiv
      Contains the names of remote hosts and users that	are equivalent to the
      local host or user. An equivalent	host or	user is	allowed	to use the
      ssh2 command with	Secure Shell host-based	authentication without sup-
      plying a password.  Additionally,	the syntax +@group can be used to
      specify netgroups.  Negated entries start	with a minus (-) sign.	This
      file must	be writable only by root; it should also be world-readable.

      Warning: You should not inlcude user names in hosts.equiv.  The named
      users could log in as anybody, including bin, daemon, adm, and other
      accounts that own	critical binaries and directories.  The	only valid
      use for user names should	 be in negative	entries.  This warning also
      applies to rsh and rlogin.

  /etc/shosts.equiv
      The same as /etc/hosts.equiv.  However, this file	is  not	used by	rlo-
      gin and rshd, so using it	permits	access using ssh2 only.

  $HOME/.ssh2/knownhosts/xxxxyyyy.pub
      Contains the public host keys of hosts that users	need to	log in to
      when using host based authentication.

      The xxxx is the fully qualified domain name (FQDN) and yyyy is the pub-
      lic key algorithm. Public	key algorithms are ssh-dss and ssh-rsa.	 For
      example, if the FQDN for a host is server1.foo.fi	and it has a key
      algorithm	of ssh-dss, the	host key would be server1.foo.fi.ssh-dss.pub
      in the knownhosts	directory.

      A	user must add the host name to a $HOME/.shosts file or an
      $HOME/.rhosts file.

  /etc/ssh2/knownhosts/xxxxyyyy.pub
      Same as the $HOME/.ssh2/knownhosts/xxxxyyyy.pub file, but	system-wide.
      This file	is overridden if the user puts a file with the same name in
      the $HOME/.ssh2/knownhosts directory.




  PUBLIC KEY OPTIONS


  The following	options	are specified as a comma-separated list:

  allow-from and deny-from
	  In addition to public-key authentication, the	canonical name of the
	  remote host must match the given patterns.  These parameters follow
	  the logic of {Allow,Deny}Hosts, described in detail in
	  sshd2_config(4).  You	specify	one pattern per	keyword. Multiple
	  keywords can be  used.

  command="command"
	  Specifies a forced command that will be executed on the server side
	  instead of anything else when	the user is authenticated.  The	com-
	  mand supplied	by the user is put in the environment variable
	  SSH2_ORIGINAL_COMMAND.  The command is run on	a pty if the connec-
	  tion requests	a pty; otherwise it is run without a tty. Quotes may
	  be used in the command if escaped with backslashes. This option
	  might	be useful for restricting certain public keys to  perform
	  just a specific operation.  An example might be a key	that permits
	  remote backups but nothing else.  Notice that	the client may
	  specify TCP/IP and/or	X11 forwarding,	unless they are	explicitly
	  prohibited (see no-port-forwarding).

  environment="NAME=value"
	  Specifies that the string is to be added to the environment when
	  logging in using this	key.  Environment variables set	this way
	  override other default environment values.  Multiple options of
	  this type are	permitted.

  idle-timeout=time
	  Sets idle timeout limit to time in seconds (s	or nothing after
	  number), in minutes (m), in hours (h), in days (d), or in weeks
	  (w).	If the connection has been idle	(all channels) this long, the
	  connection is	closed.

  no-port-forwarding
	  Forbids TCP/IP forwarding when this key is used for authentication.
	  Any port forward requests by the client will return an error.	 This
	  is useful in combination with	the command option.

  no-x11-forwarding
	  Forbids X11 forwarding when this key is used for authentication.
	  Any X11 forward requests by the client will return an	error.

  no-agent-forwarding
	  Forbids authentication agent forwarding when this key	is used	for
	  authentication.

  no-pty  Prevents tty allocation (a request to	allocate a pty will fail).









LEGAL NOTICES

  SSH is a registered trademark	of SSH Communication Security Ltd.



SEE ALSO

  Commands: rlogin(1), rsh(1), scp2(1),	sftp(1), ssh-add2(1), ssh-agent2(1),
  ssh-keygen2(1), telnet(1), sshd2(8)

  Files: hosts.equiv(4), rhosts(4), shosts(4), ssh2_config(4),
  sshd2_config(4)

  Guides: Security Administration