MAN page from Trustix openssh-clients-3.6.1p2-5tr.i586.rpm


Section: User Commands (1)
BSD mandoc


ssh - OpenSSH SSH client (remote login program) 


ssh[-l login_name]hostname | userAATThostname[command]

ssh-words[-afgknqstvxACNTX1246][-b bind_address][-c cipher_spec][-e escape_char][-i identity_file][-l login_name][-m mac_spec][-o option][-p port][-F configfile][-L port host hostport]-words[-R port host hostport][-D port]hostname | userAATThostname[command] 


ssh(SSH client) is a program for logging into a remote machine and forexecuting commands on a remote machine.It is intended to replacerlogin and rsh, and provide secure encrypted communications betweentwo untrusted hosts over an insecure network.X11 connections andarbitrary TCP/IP ports can also be forwarded over the secure channel.

sshconnects and logs into the specifiedhostname The user must provehis/her identity to the remote machine using one of several methodsdepending on the protocol version used:


SSH protocol version 1

First, if the machine the user logs in from is listed in/etc/hosts.equivor/etc/ssh/shosts.equivon the remote machine, and the user names arethe same on both sides, the user is immediately permitted to log in.Second, if.rhostsor.shostsexists in the user's home directory on theremote machine and contains a line containing the name of the clientmachine and the name of the user on that machine, the user ispermitted to log in.This form of authentication alone is normally notallowed by the server because it is not secure.

The second authentication method is therhostsorhosts.equivmethod 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/ssh/shosts.equiv and if additionally the server can verify the client'shost key (see/etc/ssh/ssh_known_hostsand$HOME/.ssh/known_hostsin theSx FILESsection), only then login is permitted.This authentication method closes security holes due to IPspoofing, 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 bedisabled if security is desired.]

As a third authentication method,sshsupports RSA based authentication.The scheme is based on public-key cryptography: there are cryptosystemswhere encryption and decryption are done using separate keys, and itis not possible to derive the decryption key from the encryption key.RSA is one such system.The idea is that each user creates a public/privatekey pair for authentication purposes.The server knows the public key, and only the user knows the private key.The file$HOME/.ssh/authorized_keyslists the public keys that are permitted for loggingin.When the user logs in, thesshprogram tells the server which key pair it would like to use forauthentication.The server checks if this key is permitted, and ifso, sends the user (actually thesshprogram running on behalf of the user) a challenge, a random number,encrypted by the user's public key.The challenge can only bedecrypted using the proper private key.The user's client then decrypts thechallenge using the private key, proving that he/she knows the privatekey but without disclosing it to the server.

sshimplements the RSA authentication protocol automatically.The user creates his/her RSA key pair by runningssh-keygen1.This stores the private key in$HOME/.ssh/identityand the public key in$HOME/.ssh/identity.pubin the user's home directory.The user should then copy theidentity.pubto$HOME/.ssh/authorized_keysin his/her home directory on the remote machine (theauthorized_keysfile corresponds to the conventional$HOME/.rhostsfile, and has one keyper line, though the lines can be very long).After this, the user can log in without giving the password.RSA authentication is muchmore secure than rhosts authentication.

The most convenient way to use RSA authentication may be with anauthentication agent.Seessh-agent1for more information.

If other authentication methods fail,sshprompts the user for a password.The password is sent to the remotehost 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 protocol version 2similar authentication methods are available.Using the default values forPreferredAuthentications the client will try to authenticate first using the hostbased method;if this method fails public key authentication is attempted,and finally if this method fails keyboard-interactive andpassword authentication are tried.

The public key method is similar to RSA authentication describedin the previous section and allows the RSA or DSA algorithm to be used:The client uses his private key,$HOME/.ssh/id_dsaor$HOME/.ssh/id_rsa 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_keysand grants access if both the key is found and the signature is correct.The session identifier is derived from a shared Diffie-Hellman valueand is only known to the client and the server.

If public key authentication fails or is not available a passwordcan be sent encrypted to the remote host for proving the user's identity.

Additionally,sshsupports hostbased or challenge response authentication.

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


Login session and remote execution

When the user's identity has been accepted by the server, the servereither executes the given command, or logs into the machine and givesthe user a normal shell on the remote machine.All communication withthe remote command or shell will be automatically encrypted.

If a pseudo-terminal has been allocated (normal login session), theuser may use the escape characters noted below.

If no pseudo tty has been allocated, thesession is transparent and can be used to reliably transfer binarydata.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 on the remotemachine exits and all X11 and TCP/IP connections have been closed.The exit status of the remote program is returned as the exit statusofssh


Escape Characters

When a pseudo terminal has been requested, ssh supports a number of functionsthrough the use of an escape character.

A single tilde character can be sent as~~or by following the tilde by a character other than those described below.The escape character must always follow a newline to be interpreted asspecial.The escape character can be changed in configuration files using theEscapeCharconfiguration directive or on the command line by the-eoption.

The supported escapes (assuming the default`~')are:

Background ssh
List forwarded connections
Background ssh at logout when waiting for forwarded connection / X11 sessionsto terminate
Display a list of escape characters
Open command line (only useful for adding port forwardings using the-Land-Roptions)
Request rekeying of the connection (only useful for SSH protocol version 2and if the peer supports it)


X11 and TCP forwarding

If theForwardX11variable is set to``yes''(or, see the description of the-Xand-xoptions described later)and the user is using X11 (theDISPLAYenvironment variable is set), the connection to the X11 display isautomatically forwarded to the remote side in such a way that any X11programs started from the shell (or command) will go through theencrypted channel, and the connection to the real X server will be madefrom the local machine.The user should not manually setDISPLAY Forwarding of X11 connections can beconfigured on the command line or in configuration files.

TheDISPLAYvalue set bysshwill point to the server machine, but with a display number greaterthan zero.This is normal, and happens becausesshcreates a``proxy''X server on the server machine for forwarding theconnections over the encrypted channel.

sshwill also automatically set up Xauthority data on the server machine.For this purpose, it will generate a random authorization cookie,store it in Xauthority on the server, and verify that any forwardedconnections carry this cookie and replace it by the real cookie whenthe connection is opened.The real authentication cookie is neversent to the server machine (and no cookies are sent in the plain).

If theForwardAgentvariable is set to``yes''(or, see the description of the-Aand-aoptions described later) andthe user is using an authentication agent, the connection to the agentis automatically forwarded to the remote side.

Forwarding of arbitrary TCP/IP connections over the secure channel canbe specified either on the command line or in a configuration file.One possible application of TCP/IP forwarding is a secure connection to anelectronic purse; another is going through firewalls.


Server authentication

sshautomatically maintains and checks a database containingidentifications for all hosts it has ever been used with.Host keys are stored in$HOME/.ssh/known_hostsin the user's home directory.Additionally, the file/etc/ssh/ssh_known_hostsis automatically checked for known hosts.Any new hosts are automatically added to the user's file.If a host's identificationever changes,sshwarns about this and disables password authentication to prevent atrojan horse from getting the user's password.Another purpose ofthis mechanism is to prevent man-in-the-middle attacks which couldotherwise be used to circumvent the encryption.TheStrictHostKeyCheckingoption can be used to prevent logins to machines whosehost key is not known or has changed.

The options are as follows:

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

Agent forwarding should be enabled with caution.Users with the ability to bypass file permissions on the remote host(for the agent's Unix-domain socket)can access the local agent through the forwarded connection.An attacker cannot obtain key material from the agent,however they can perform operations on the keys that enable them toauthenticate using the identities loaded into the agent.

-b bind_address
Specify the interface to transmit from on machines with multipleinterfaces or aliased addresses.
-c blowfish|3des|des
Selects the cipher to use for encrypting the session.3desis used by default.It is believed to be secure.3des(triple-des) is an encrypt-decrypt-encrypt triple with three different keys.blowfishis a fast block cipher, it appears very secure and is much faster than3des desis only supported in thesshclient for interoperability with legacy protocol 1 implementationsthat do not support the3descipher.Its use is strongly discouraged due to cryptographic weaknesses.
-c cipher_spec
Additionally, for protocol version 2 a comma-separated list of ciphers canbe specified in order of preference.SeeCiphersfor more information.
-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, followedby control-Z suspends the connection, and followed by itself sends theescape character once.Setting the character to``none''disables any escapes and makes the session fully transparent.
Requestssshto go to background just before command execution.This is useful ifsshis going to ask for passwords or passphrases, but the userwants it in the background.This implies-n The recommended way to start X11 programs at a remote site is withsomething likessh -f host xterm
Allows remote hosts to connect to local forwarded ports.
-i identity_file
Selects a file from which the identity (private key) forRSA or DSA authentication is read.The default is$HOME/.ssh/identityfor protocol version 1, and$HOME/.ssh/id_rsaand$HOME/.ssh/id_dsafor protocol version 2.Identity files may also be specified ona per-host basis in the configuration file.It is possible to have multiple-ioptions (and multiple identities specified inconfiguration files).
-I smartcard_device
Specifies which smartcard device to use. The argument isthe devicesshshould use to communicate with a smartcard used for storing the user'sprivate RSA key.
Disables forwarding of Kerberos tickets and AFS tokens.This may also be specified on a per-host basis in the configuration file.
-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.
-m mac_spec
Additionally, for protocol version 2 a comma-separated list of MAC(message authentication code) algorithms canbe specified in order of preference.See theMACs keyword for more information.
Redirects stdin from/dev/null(actually, prevents reading from stdin).This must be used whensshis run in the background.A common trick is to use this to run X11 programs on a remote machine.For example,ssh -n emacs will start an emacs on, and the X11connection will be automatically forwarded over an encrypted channel.Thesshprogram will be put in the background.(This does not work ifsshneeds to ask for a password or passphrase; see also the-foption.)
Do not execute a remote command.This is useful for just forwarding ports(protocol version 2 only).
-o option
Can be used to give options in the format used in the configuration file.This is useful for specifying options for which there is no separatecommand-line flag.
-p port
Port to connect to on the remote host.This can be specified on aper-host basis in the configuration file.
Quiet mode.Causes all warning and diagnostic messages to be suppressed.
May be used to request invocation of a subsystem on the remote system. Subsystems are a feature of the SSH2 protocol which facilitate the useof SSH as a secure transport for other applications (eg. sftp). Thesubsystem is specified as the remote command.
Force pseudo-tty allocation.This can be used to execute arbitraryscreen-based programs on a remote machine, which can be very useful,e.g., when implementing menu services.Multiple-toptions force tty allocation, even ifsshhas no local tty.
Disable pseudo-tty allocation.
Verbose mode.Causessshto print debugging messages about its progress.This is helpful indebugging connection, authentication, and configuration problems.Multiple-voptions increases the verbosity.Maximum is 3.
Disables X11 forwarding.
Enables X11 forwarding.This can also be specified on a per-host basis in a configuration file.

X11 forwarding should be enabled with caution.Users with the ability to bypass file permissions on the remote host(for the user's X authorization database)can access the local X11 display through the forwarded connection.An attacker may then be able to perform activities such as keystroke monitoring.

Requests compression of all data (including stdin, stdout, stderr, anddata for forwarded X11 and TCP/IP connections).The compression algorithm is the same used bygzip(1),and the``level''can be controlled by theCompressionLeveloption for protocol version 1.Compression is desirable on modem lines and otherslow connections, but will only slow down things on fast networks.The default value can be set on a host-by-host basis in theconfiguration files; see theCompressionoption.
-F configfile
Specifies an alternative per-user configuration file.If a configuration file is given on the command line,the system-wide configuration file(/etc/ssh/ssh_config)will be ignored.The default for the per-user configuration file is$HOME/.ssh/config
-L port:host:hostport
Specifies that the given port on the local (client) host is to beforwarded to the given host and port on the remote side.This works by allocating a socket to listen toporton the local side, and whenever a connection is made to this port, theconnection is forwarded over the secure channel, and a connection ismade tohostporthostportfrom the remote machine.Port forwardings can also be specified in the configuration file.Only root can forward privileged ports.IPv6 addresses can be specified with an alternative syntax:port/host/hostport
-R port:host:hostport
Specifies that the given port on the remote (server) host is to beforwarded to the given host and port on the local side.This works by allocating a socket to listen toporton the remote side, and whenever a connection is made to this port, theconnection is forwarded over the secure channel, and a connection ismade tohostporthostportfrom the local machine.Port forwardings can also be specified in the configuration file.Privileged ports can be forwarded only whenlogging in as root on the remote machine.IPv6 addresses can be specified with an alternative syntax:port/host/hostport
-D port
Specifies a local``dynamic''application-level port forwarding.This works by allocating a socket to listen toporton the local side, and whenever a connection is made to this port, theconnection is forwarded over the secure channel, and the applicationprotocol is then used to determine where to connect to from theremote machine.Currently the SOCKS4 protocol is supported, andsshwill act as a SOCKS4 server.Only root can forward privileged ports.Dynamic port forwardings can also be specified in the configuration file.
Forcessshto try protocol version 1 only.
Forcessshto try protocol version 2 only.
Forcessshto use IPv4 addresses only.
Forcessshto use IPv6 addresses only.



sshmay additionally obtain configuration data froma per-user configuration file and a system-wide configuration file.The file format and configuration options are described inssh_config5. 


sshwill normally set the following environment variables:

TheDISPLAYvariable indicates the location of the X11 server.It is automatically set bysshto point to a value of the form``hostname:n''where hostname indicatesthe host where the shell runs, and n is an integer >= 1.sshuses this special value to forward X11 connections over the securechannel.The user should normally not setDISPLAYexplicitly, as thatwill render the X11 connection insecure (and will require the user tomanually copy any required authorization cookies).
Set to the path of the user's home directory.
Synonym forUSER set for compatibility with systems that use this variable.
Set to the path of the user's mailbox.
Set to the defaultPATH as specified when compilingssh
Ifsshneeds a passphrase, it will read the passphrase from the currentterminal if it was run from a terminal.Ifsshdoes not have a terminal associated with it butDISPLAYandSSH_ASKPASSare set, it will execute the program specified bySSH_ASKPASSand open an X11 window to read the passphrase.This is particularly useful when callingsshfrom a.Xsessionor related script.(Note that on some machines itmay be necessary to redirect the input from/dev/nullto make this work.)
Identifies the path of a unix-domain socket used to communicate with theagent.
Identifies the client and server ends of the connection.The variable containsfour space-separated values: client ip-address, client port number,server ip-address and server port number.
The variable contains the original command line if a forced commandis executed.It can be used to extract the original arguments.
This is set to the name of the tty (path to the device) associatedwith the current shell or command.If the current session has no tty,this variable is not set.
The timezone variable is set to indicate the present timezone if itwas set when the daemon was started (i.e., the daemon passes the valueon to new connections).
Set to the name of the user logging in.

Additionally,sshreads$HOME/.ssh/environment and adds lines of the format``VARNAME=value''to the environment if the file exists and if users are allowed tochange their environment.See thePermitUserEnvironmentoption insshd_config5. 


Records host keys for all hosts the user has logged into that are notin/etc/ssh/ssh_known_hosts Seesshd(8).
$HOME/.ssh/identity, $HOME/.ssh/id_dsa, $HOME/.ssh/id_rsa
Contains the authentication identity of the user.They are for protocol 1 RSA, protocol 2 DSA, and protocol 2 RSA, respectively.These filescontain sensitive data and should be readable by the user but notaccessible by others (read/write/execute).Note thatsshignores a private key file if it is accessible by others.It is possible to specify a passphrase whengenerating the key; the passphrase will be used to encrypt thesensitive part of this file using 3DES.
$HOME/.ssh/, $HOME/.ssh/, $HOME/.ssh/
Contains the public key for authentication (public part of theidentity file in human-readable form).The contents of the$HOME/.ssh/identity.pubfile should be added to$HOME/.ssh/authorized_keyson all machineswhere the user wishes to log in using protocol version 1 RSA authentication.The contents of the$HOME/.ssh/id_dsa.puband$HOME/.ssh/id_rsa.pubfile should be added to$HOME/.ssh/authorized_keyson all machineswhere the user wishes to log in using protocol version 2 DSA/RSA authentication.These files are notsensitive and can (but need not) be readable by anyone.These files arenever used automatically and are not necessary; they are only provided forthe convenience of the user.
This is the per-user configuration file.The file format and configuration options are described inssh_config5.
Lists the public keys (RSA/DSA) that can be used for logging in as this user.The format of this file is described in thesshd(8)manual page.In the simplest form the format is the same as the .pubidentity files.This file is not highly sensitive, but the recommendedpermissions are read/write for the user, and not accessible by others.
Systemwide list of known host keys.This file should be prepared by thesystem administrator to contain the public host keys of all machines in theorganization.This file should be world-readable.This file containspublic keys, one per line, in the following format (fields separatedby spaces): system name, public key and optional comment field.When different names are usedfor the same machine, all such names should be listed, separated bycommas.The format is described on thesshd(8)manual page.

The canonical system name (as returned by name servers) is used bysshd(8)to verify the client host when logging in; other names are needed becausesshdoes not convert the user-supplied name to a canonical name beforechecking the key, because someone with access to the name serverswould then be able to fool host authentication.

Systemwide configuration file.The file format and configuration options are described inssh_config5.
/etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key
These three files contain the private parts of the host keysand are used forRhostsRSAAuthenticationandHostbasedAuthentication If the protocol version 1RhostsRSAAuthenticationmethod is used,sshmust be setuid root, since the host key is readable only by root.For protocol version 2,sshusesssh-keysign8to access the host keys forHostbasedAuthentication This eliminates the requirement thatsshbe setuid root when that authentication method is used.By defaultsshis not setuid root.
This file is used in.rhostsauthentication to list thehost/user pairs that are permitted to log in.(Note that this file isalso used by rlogin and rsh, which makes using this file insecure.)Each line of the file contains a host name (in the canonical formreturned by name servers), and then a user name on that host,separated by a space.On some machines this file may need to beworld-readable if the user's home directory is on a NFS partition,becausesshd(8)reads it as root.Additionally, this file must be owned by the user,and must not have write permissions for anyone else.The recommendedpermission for most machines is read/write for the user, and notaccessible by others.

Note that by defaultsshd(8)will be installed so that it requires successful RSA hostauthentication before permitting .rhosts authentication.If the server machine does not have the client's host key in/etc/ssh/ssh_known_hosts it can be stored in$HOME/.ssh/known_hosts The easiest way to do this is toconnect back to the client from the server machine using ssh; thiswill automatically add the host key to$HOME/.ssh/known_hosts

This file is used exactly the same way as.rhosts The purpose forhaving this file is to be able to use rhosts authentication withsshwithout permitting login withrloginorrsh(1).
This file is used during.rhosts authentication.It containscanonical hosts names, one per line (the full format is described onthesshd(8)manual page).If the client host is found in this file, login isautomatically permitted provided client and server user names are thesame.Additionally, successful RSA host authentication is normallyrequired.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 usingsshbut not using rsh/rlogin.
Commands in this file are executed bysshwhen the user logs in just before the user's shell (or command) is started.See thesshd(8)manual page for more information.
Commands in this file are executed bysshwhen the user logs in just before the user's shell (or command) isstarted.See thesshd(8)manual page for more information.
Contains additional definitions for environment variables, see sectionSx ENVIRONMENTabove.



sshexits with the exit status of the remote command or with 255if an error occurred. 


OpenSSH is a derivative of the original and freessh 1.2.12 release by Tatu Ylonen.Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,Theo de Raadt and Dug Songremoved many bugs, re-added newer features andcreated OpenSSH.Markus Friedl contributed the support for SSHprotocol versions 1.5 and 2.0. 


T. YlonenT. KivinenM. SaarinenT. RinneS. Lehtinen"SSH Protocol Architecture"draft-ietf-secsh-architecture-12.txtJanuary 2002work in progress material



SSH protocol version 1
SSH protocol version 2
Login session and remote execution
Escape Characters
X11 and TCP forwarding
Server authentication

This document was created byman2html,using the manual pages.