sshSection: SSH (1)
Updated: November 8, 1995
SSH man page index
Return to SSH FAQ
NAMEssh - secure shell client (remote login program)
ssh[-a][-cidea|blowfish|des|3des|arcfour|none][-e escape_char][-i identity_file][-l login_name][-n][-k][-V][-o option][-p port][-q][-P][-t][-v][-x][-C][-g][-L port:host:hostport][-R port:host:hostport]hostname[command]
Ssh (Secure Shell) a program for logging into a remote machine and forexecuting commands in 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.
Ssh connects and logs into the specified hostname.The user must provehis/her identity to the remote machine using one of several methods.
First, if the machine the user logs in from is listed in/etc/hosts.equivor/etc/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 (and primary) authentication method is the rhosts or hosts.equiv method combined with RSA-based host authentication. Itmeans that if the login would be permitted by.rhosts,.shosts,/etc/hosts.equiv,or/etc/shosts.equiv,and additionally it can verify the client'shost key (see $HOME/.ssh/known_hosts and /etc/ssh_known_hosts in the FILESsection), only then login ispermitted. This authentication method closes security holes due to IPspoofing, DNS spoofing and routing spoofing. [Note to the administrator:/etc/hosts.equiv, .rhosts,and the rlogin/rsh protocol in general, are inherently insecure and should bedisabled if security is desired.]
As a third authentication method, ssh supports 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/private key pair for authentication purposes. Theserver 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, the ssh program 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 usercreates his/her RSA key pair by running ssh-keygen(1).This stores the private key in .ssh/identityand the public key in.ssh/identity.pubin the user's home directory. The user should thencopy the identity.pubto .ssh/authorized_keysin his/her home directory on the remote machine (the authorized_keysfile corresponds to the conventional .rhostsfile, and has one keyper line, though the lines can be very long). After this, the usercan 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. See ssh-agent(1)for more information.
As a fourth authentication method,sshsupports authentication through TIS authentication server. The idea isthatsshasks TIS authsrv(8)to authenticate the user. Sometime, usernames in the TIS databasecannot be the same as the local users. This can be the case if the userauthenticates itself with a smartcard or a Digipass. In that case, theusername in the database is usually known as the serial number of theauthentification device. The file/etc/sshd_tis.mapcontains the mapping between local users and their corresponding namein the TIS database. If the file does notexist or the user is not found, the corresponding name in the TISdatabase is supposed to be the same.
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.
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 can disconnect with "~.", and suspendsshwith "~^Z". All forwarded connections can be listed with "~#", and ifthe session blocks waiting for forwarded X11 or TCP/IPconnections to terminate, it can be backgrounded with "~&" (thisshould not be used while the user shell is active, as it can cause theshell to hang). All available escapes can be listed with "~?".
A single tilde character can be sent as "~~" (or byfollowing the tilde by a character other than those described above).The escape character must always follow a newline to be interpreted asspecial. The escape character can be changed in configuration filesor on the command line.
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'' willalso make the session transparent even if a tty is used.
The session terminates when the command or shell in on the remotemachine exists and all X11 and TCP/IP connections have been closed.The exit status of the remote program is returned as the exit statusofssh.
If 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.
The DISPLAY value 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 the user is using an authentication agent, the connection to the agentis automatically forwarded to the remote side unless disabled oncommand line or in a configuration file.
Forwarding of arbitrary TCP/IP connections over the secure channel canbe specified either on command line or in a configuration file. Onepossible application of TCP/IP forwarding is a secure connection to anelectronic purse; another is going trough firewalls.
Sshautomatically maintains and checks a database containing RSA-basedidentifications for all hosts it has ever been used with. Thedatabase is stored in .ssh/known_hostsin the user's home directory. Additionally, the file /etc/ssh_known_hostsis automatically checked for known hosts. Any new hosts areautomatically 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 (see below) can be used to prevent logins to machines whosehost key is not known or has changed.
- Disables forwarding of the authentication agent connection. This mayalso be specified on a per-host basis in the configuration file.
- -c idea|des|3des|blowfish|arcfour|none
- Selects the cipher to use for encrypting the session. ideais used by default. It is believed to be secure. desis the data encryption standard, but is breakable by governments, large corporations, and major criminal organizations.3des(triple-des) is encrypt-decrypt-encrypt triple with three differentkeys. It is presumably more secure thanDES. It is used as default if both sites do not support IDEA.blowfishis an encryption algorithm invented by Bruce Schneier. It uses 128bit keys.arcfouris an algorithm published in the Usenet News in 1995.This algorithm is believed to be equivalent with the RC4 cipher fromRSA Data Security (RC4 is a trademark of RSA Data Security). This isthe fastest algorithm currently supported.nonedisables encryption entirely; it is only intended for debugging, andit renders the connection insecure.
- -e ch|^ch|none
- Sets the escape character for sessions with a pty (default: ~). Theescape character is only recognized at the beginning of a line. Theescape 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 anyescapes and makes the session fully transparent.
- Requests ssh to go to background after authentication is done andforwardings have been established. This is useful if ssh is going toask for passwords or passphrases, but the user wants it in thebackground. This may also be useful in scripts. This implies-n.The recommended way to start X11 programs at a remote site is withsomething like "ssh -f host xterm".
- -i identity_file
- Selects the file from which the identity (private key) for RSAauthentication is read. Default is .ssh/identityin the user's home directory. Identity files may also be specified ona per-host basis in the configuration file. It is possible to havemultiple -i options (and multiple identities specified inconfiguration files).
- Disables forwarding of the kerberos tickets. This mayalso 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 may alsobe specified on a per-host basis in the configuration file.
- 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 X11programs in a remote machine. For example, "ssh -n shadows.cs.hut.fiemacs &" will start an emacs on shadows.cs.hut.fi, 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 -f option.)
- -o 'option'
- Can be used to give options in the format used in the config file.This is useful for specifying options for which there is no separatecommand-line flag. The option has the same format as a line in theconfiguration file.
- -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 besuppressed. Only fatal errors are displayed.
- Use non privileged port. With this you cannot use rhosts or rsarhostsauthentications, but it can be used to bypass some firewalls that dontallow privileged source ports to pass.
- Force pseudo-tty allocation. This can be used to execute arbitaryscreen-based programs on a remote machine, which can be very usefule.g. when implementing menu services.
- Verbose mode. Causessshto print debugging messages about its progress. This is helpful indebugging connection, authentication, and configuration problems.
- Print only version number and exit.
- Allows remote hosts to connect local port forwarding ports. The
default is that only localhost may connect to locally binded ports.
- Disables X11 forwarding. This can also be specified on a per-hostbasis in a configuration file.
- Requests compression of all data (including stdin, stdout, stderr, anddata for forwarded X11 and TCP/IP connections). The compressionalgorithm is the same used by gzip, and the "level" can be controlledby theCompressionLeveloption (see below). 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 theCompressoption below.
- -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 worksby 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 tohost:hostportfrom the remote machine. Port forwardings can also be specified in theconfiguration file. Only root can forward privileged ports.
- -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 worksby 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 tohost:hostportfrom the local machine. Port forwardings can also be specified in theconfiguration file. Privileged ports can be forwarded only whenlogging in as root on the remote machine.
Sshobtains configuration data from the following sources (in this order):command line options, user's configuration file($HOME/.ssh/config), and system-wide configuration file(/etc/ssh_config). For each parameter, the first obtained valuewill be used. The configuration files contain sections bracketed by"Host" specifications, and that section is only applied for hosts thatmatch one of the patterns given in the specification. The matchedhost name is the one given on the command line.
Since the first obtained value for each parameter is used, morehost-specific declarations should be given near the beginning of thefile, and general defaults at the end.
The configuration file has the following format:
- Empty lines and lines starting with '#' are comments.
- Otherwise a line is of the format "keyword arguments" or "keyword =arguments". The possible keywords and their meanings are as follows(note that the configuration files are case-sensitive, but keywordsare case-insensitive):
HostRestricts the following declarations (up to the nextHostkeyword) to be only for those hosts that match one of the patternsgiven after the keyword. '*' and '?' can be as wildcards in thepatterns. A single '*' as a pattern can be used to provide globaldefaults for all hosts. The host is thehostnameargument given on the command line (i.e., the name is not converted toa canonicalized host name before matching).
- If set to "yes", passphrase/password querying will be disabled. Thisoption is useful in scripts and other batch jobs where you have nouser to supply the password. The argument must be"yes" or "no".
- Specifies the cipher to use for encrypting the session. Currently,idea,des,3des,blowfish,arcfour,andnoneare supported. The default is "idea" (or "3des" if "idea" is notsupported by both hosts). Using "none" (no encryption) is intendedonly for debugging, and will render the connection insecure.
- Clears all forwardings after reading all config files and parsingcommand line. This is usefull to disable forwardings in config filewhen you want to make second connection to host having forwardings inconfig file. Scp sets this on by default so it will not fail even ifyou have some forwardings set in config file.
- Specifies whether to use compression. The argument must be"yes" or "no".
- Specifies the compression level to use if compression is enable. Theargument must be an integer from 1 (fast) to 9 (slow, best). Thedefault level is 6, which is good for most applications. The meaningof the values is the same as in GNU GZIP.
- Specifies the number of tries (one per second) to make before fallingback to rsh or exiting. The argument must be an integer. This may beuseful in scripts if the connection sometimes fails.
- Sets the escape character (default: ~). The escape character can alsobe set on the command line. The argument should be a singlecharacter, '^' followed by a letter, or ``none'' to disable the escapecharacter entirely (making the connection transparent for binarydata).
- Specifies that if connecting viasshfails due to a connection refused error (there is nosshdlistening on the remote host), rshshould automatically be used instead (after a suitable warning aboutthe session being unencrypted). The argument must be"yes" or "no".
- Specifies whether the connection to the authentication agent (if any)will be forwarded to the remote machine. The argument must be"yes" or "no".
- Specifies whether X11 connections will be automatically redirectedover the secure channel and DISPLAYset. The argument must be "yes" or "no".
- Specifies that also remote hosts may connect to locally forwardedports. The argument must be"yes" or "no".
- Specifies a file to use instead of /etc/ssh_known_hosts.
- Specifies the real host name to log into. This can be used to specifynicnames or abbreviations for hosts. Default is the name given on thecommand line. Numeric IP addresses are also permitted (both on thecommand line and inHostNamespecifications).
- Specifies the file from which the user's RSA authentication identityis read (default .ssh/identity in the user's home directory).Additionally, any identities represented by the authentication agentwill be used for authentication. The file name may use the tildesyntax to refer to a user's home directory. It is possible to havemultiple identity files specified in configuration files; all theseidentities will be tried in sequence.
- Specifies whether the system should send keepalive messages to theother side. If they are sent, death of the connection or crash of oneof the machines will be properly noticed. However, this means thatconnections will die if the route is down temporarily, and some peoplefind it annoying.
The default is "yes" (to send keepalives), and the client will noticeif the network goes down or the remote host dies. This is importantin scripts, and many users want it too.
To disable keepalives, the value should be set to "no" in both theserver and the client configuration files.
- Specifies whether Kerberos V5 authentication will be used.
- Specifies whether a Kerberos V5 TGT will be forwarded to the server.
- Specifies that a TCP/IP port on the local machine be forwarded overthe secure channel to given host:port from the remote machine. Thefirst argument must be a port number, and the second must behost:port. Multiple forwardings may be specified, and additionalforwardings can be given on the command line. Only the root canforward privileged ports.
- Specifies number of password prompts before giving up. The argument tomust be integer. Note that server also limits number of attempts(currently 5), so setting this larger doesn't have any effect. Defaultvalue is one.
- Specifies whether to use password authentication. The argument tothis keyword must be"yes" or "no".
- Specifies whether to include the remote host name in the password prompt.The argument to this keyword must be"yes" or "no".
- Specifies whether to include the remote login name in the password prompt.The argument to this keyword must be"yes" or "no".
- Specifies the port number to connect on the remote host. Default is22.
- Specifies the command to use to connect to the server. The commandstring extends to the end of the line, and is executed with /bin/sh.In the command string, %h will be substituted by the host name toconnect and %p by the port. The command can be basically anything,and should read from its stdin and write to its stdout. It shouldeventually connect ansshdserver running on some machine, or execute"sshd -i" somewhere. Host key management will be done using theHostName of the host being connected (defaulting to the name typed bythe user).
Note thatsshcan also be configured to support the SOCKS system using the--with-socks4 or --with-socks5 compile-time configuration option.
- Specifies that a TCP/IP port on the remote machine be forwarded overthe secure channel to given host:port from the local machine. Thefirst argument must be a port number, and the second must behost:port. Multiple forwardings may be specified, and additionalforwardings can be given on the command line. Only the root canforward privileged ports.
- Specifies whether to try rhosts based authentication. Note that thisdeclaration only affects the client side and has no effect whatsoeveron security. Disabling rhosts authentication may reduceauthentication time on slow connections when rhosts authentication isnot used. Most servers do not permit RhostsAuthentication because itis not secure (see RhostsRSAAuthentication). The argument to thiskeyword must be"yes" or "no".
- Specifies whether to try rhosts based authentication with RSA hostauthentication. This is the primary authentication method for mostsites. The argument must be"yes" or "no".
- Specifies whether to try RSA authentication. The argument to thiskeyword must be"yes" or "no".RSA authentication will only beattempted if the identity file exists, or an authentication agent isrunning.
- If this flag is set to "yes", sshssh will never automatically add host keys to the$HOME/.ssh/known_hostsfile, and refuses to connect hosts whose host key has changed. Thisprovides maximum protection against trojan horse attacks. However, itcan be somewhat annoying if you don't have good/etc/ssh_known_hostsfiles installed and frequently connect new hosts. Basically thisoption forces the user to manually add any new hosts. Normally thisoption is set to "ask", and new hosts will automatically be added tothe known host files after you have confirmed you really want to dothat. If this is set to "no" then new host will automatically be addedto the known host files. The host keys of known hosts will be verifiedautomatically in either case.
The argument must be"yes", "no" or "ask".
- Specifies whether to try TIS authentication. The argument to thiskeyword must be"yes" or "no".
- Specifies whether to use privileged port when connecting to otherend. The default is yes if rhosts or rsarhosts authentications areenabled.
- Specifies the user to log in as. This can be useful if you have adifferent user name in different machines. This saves the trouble ofhaving to remember to give the user name on the command line.
- Specifies a file to use instead of $HOME/.ssh/known_hosts.
- Specifies that rlogin/rsh should be used for this host. It ispossible that the host does not at all support thesshprotocol. This causessshto immediately exec rsh.All other options (exceptHostName)are ignored if this has been specified. The argument must be"yes" or "no".
- Specifies the path to xauth program.
Ssh will normally set the following environment variables:
- The DISPLAY variable indicates the location of the X11 server. It isautomatically set by sshto point to a value of the form "hostname:n" where hostname indicatesthe host where the shell runs, and n is an integer >= 1. Ssh usesthis special value to forward X11 connections over the securechannel. The user should normally not set DISPLAY explicitly, 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 for USER; set for compatibility with systems that usethis variable.
- Set to point the user's mailbox.
- Set to the default PATH, as specified when compilingsshor, on some systems, /etc/environment or /etc/default/login.
- if exists, is used to indicate the path of a unix-domain socket usedto communicate with the authentication agent (or its localrepresentative).
- Identifies the client end of the connection. The variable containsthree space-separated values: client ip-address, client port number,and server port number.
- This will be the original command line of given by protocol if forcedcommand is run. It can be used to fetch arguments etc from the otherend.
- 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 (e.i., the daemon passes the valueon to new connections).
- Set to the name of the user logging in.
Additionally, sshreads /etc/environment and $HOME/.ssh/environment, and adds lines ofthe format VARNAME=valueto the environment. Some systems may havestill additional mechanisms for setting up the environment, such as/etc/default/loginon Solaris.
- Records host keys for all hosts the user has logged into (that are notin /etc/ssh_known_hosts). Seesshdmanual page.
- Used for seeding the random number generator. This file containssensitive data and should read/write for the user and not accessiblefor others. This file is created the first time the program is runand updated automatically. The user should never need to read ormodify this file.
- Contains the RSA authentication identity of the user. This filecontains sensitive data and should be readable by the user but notaccessible by others. It is possible to specify a passphrase whengenerating the key; the passphrase will be used to encrypt thesensitive part of this file usingIDEA.
- Contains the public key for authentication (public part of theidentity file in human-readable form). The contents of this fileshould be added to $HOME/.ssh/authorized_keys on all machineswhere you wish to log in using RSA authentication. This file is notsensitive and can (but need not) be readable by anyone. This file isnever used automatically and is not necessary; it is only provided forthe convenience of the user.
- This is the per-user configuration file. The format of this file isdescribed above. This file is used by thesshclient. This file does not usually contain any sensitive information,but the recommended permissions are read/write for the user, and notaccessible by others.
- Lists the RSA keys that can be used for logging in as this user. Theformat of this file is described in thesshdmanual page. In the simplest form the format is the same as the .pubidentity files (that is, each line contains the number of bits inmodulus, public exponent, modulus, and comment fields, separated byspaces). 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, number of bits in modulus, public exponent,modulus, 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 manual page.
- The canonical system name (as returned by name servers) is used bysshdto 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. This file provides defaults for thosevalues that are not specified in the user's configuration file, andfor those users who do not have a configuration file. This file mustbe world-readable.
- This file is used in .rhosts authentication 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. This file must be owned by the user,and must not have write permissions for anyone else. The recommendedpermission is read/write for the user, and not accessible by others.
- Note that by defaultsshdwill be installed so that it requires successful RSA hostauthentication before permitting .rhosts authentication. If yourserver 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 toconnect back to the client from the server machine using ssh; thiswill automatically add the host key in $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 with rlogin or rsh.
- This file is used during .rhosts authentication. It containscanonical hosts names, one per line (the full format is described onthesshdmanual 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 thesshdmanual 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 the sshdmanual page for more information.
Sshis normally installed as suid root. It needs root privileges only forrhosts authentication (rhosts authentication requires that theconnection must come from a privileged port, and allocating such aport requires root privileges). It also needs to be able to read/etc/ssh_host_key to performRSAhost authentication. It is possible to usesshwithout root privileges, but rhosts authentication will then bedisabled. Sshdrops any extra privileges immediately after the connection to theremote host has been made.
Considerable work has been put into makingsshsecure. However, if you find a security problem, please report itimmediately to <email@example.com>.
Tatu Ylonen <firstname.lastname@example.org>
Information about new releases, mailing lists, and other relatedissues can be found from the ssh WWW home page at http://www.ssh.com
This document was created by man2html,using the manual pages.
Time: 05:39:01 GMT, September 09, 1999