(full manual page, below)
USAGE:ssh [-l login_name] hostname [command]
Ssh (Secure Shell) is a program for logging into a remote machine and executing commands in a remote machine. It is intended to replace rlogin and rsh, and provide secure, encrypted communications between hosts. X11 connections and arbitrary TCP/IP ports can also be forwarded over the secure channel.
Ssh connects and logs into the specified hostname. The user must prove his identity to the remote machine using a password (or some other authentication method -- read the full man pages for ssh).
parter> ssh ucsu
Log on securely to ucsu (where your username is the same as on parter)
parter> ssh -l smithj euclid.ucla.edu
Log on securely to euclid.ucla.edu as user smithj (different than your parter username)
parter> ssh simpson /home/student/joesmith/a.out
Run your program ``a.out'' on simpson without actually logging in (see man pages for rsh)
full manual page for ssh
SSH Last change: March 22, 2000 NAME ssh - secure shell client (remote login program) SYNOPSIS ssh [-l login_name] hostname [command] ssh [-l login_name] [-n] [+a] [-a] [+x] [-x] [-i file] [-F file] [-t] [-v] [-d debug_level] [-V] [-q] [-f[o]] [-e char] [-c cipher] [-p port] [-S] [-L port:host:hostport] [-R port:host:hostport] [+C] [-C] [-o `option'] [-h] [login_name@]hostname[#port] [command] DESCRIPTION Ssh (Secure Shell) is a program for logging into a remote machine and executing commands in a remote machine. It is intended to replace rlogin and rsh, and provide secure, encrypted communications between two untrusted hosts over an insecure network. X11 connections and arbitrary TCP/IP ports can also be forwarded over the secure channel. Ssh connects and logs into the specified hostname. The user must prove his identity to the remote machine using some authentication method. Public key authentication is based on the use of digital signatures. Each user creates a public / private key pair for authentication purposes. The server knows the user's public key, and only the user has the private key. The filenames of private keys that are used in authentication are set 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 end. The user is authenticated by signing the challenge using the private key. See the FILES section below for more information on identification and authorization files. Private / public key pairs can be created with ssh- keygen2(1). See ssh-agent2(1) for information on how to use public key authentication in conjunction with an authentica- tion agent. If other authentication methods fail, ssh prompts for a password. Since all communications are encrypted, the pass- word will not be available for eavesdroppers. 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 no pseudo tty has been allocated, the session is tran- sparent and can be used to reliably transfer binary data. The session terminates when the command or shell in on 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. 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 pro- grams 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 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, and happens 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 machine. For this purpose, it will generate a random authorization cookie, store it in the Xauthority data on the server, and verify that any forwarded connections carry this cookie and replace it with the real cookie when the connec- tion 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 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. TCP/IP forwarding can be used for secure connections to electronic purses or for going through firewalls. Ssh automatically maintains and checks a database contain- ing public keys of hosts. When logging on to a host for the first time, the host's public key is stored to a file .ssh2/hostkey_PORTNUMBER_HOSTNAME.pub in the user's home directory. If a host's identification changes, ssh issues a warning and disables password authentication to prevent a Trojan horse from getting the user's password. Another pur- pose of this mechanism is to prevent man-in-the-middle attacks which could otherwise be used to circumvent the encryption. Ssh has built-in support for SOCKS version 4 for traversing firewalls. See ENVIRONMENT. OPTIONS -l login_name Specifies the user for login to the remote machine. -n Redirect input from /dev/null, ie. don't read stdin. This option can also be specified in the configuration file. +a Enable authentication agent forwarding. (default) -a Disable authentication agent forwarding. +x Enable X11 connection forwarding. (default) -x Disable X11 connection forwarding. -i file Specifies the identity file for public key authentica- tion. This option can also be specified in the confi- guration file. -F file Specifies an alternative configuration file to use. NOTE: $HOME/.ssh2/ssh2_config is still read, options specified here will be in addition to those. -t For tty allocation, ie. allocate a tty even if a com- mand is given. This option can also be specified in the configuration file. -v Enable verbose mode. Display verbose debugging mes- sages. Equal to `-d 2'. This option can also be speci- fied in the configuration file. -d debug_level Print extensive debug information to stderr. debug_level is either a number, from 0 to 99, where 99 specifies that all debug information should be displayed, or a comma-separated list of assignments "ModulePattern=debug_level". -V Display version string. -q Make ssh quiet, so that it doesn't display any warning messages. This option can also be specified in the con- figuration file. -f [o] Fork into background after authentication. This option can also be specified in the configuration file. Implies '-S'. With this option, ssh stays in the back- ground, waiting for connections indefinitely (it has to be killed for it to stop listening). With optional `o' argument, goes to ``one-shot'' mode, which means that once all channels are closed, ssh exits. -e char Set escape character. Use ``none'' to disable. This option can also be specified in the configuration file. (default; ~) -c cipher Select the encryption algorithm. Multiple -c options are allowed and a single -c flag can have only one cipher. This option can also be specified in the confi- guration file. -p port Port to connect to on the remote host. This option can also be specified in the configuration file. -S Don't request a session channel. This can be used with port-forwarding requests if a session channel (and tty) isn't needed, or the server doesn't give one. -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 be listened port on the local side, and whenever a con- nection is made to this port, the connection is for- warded over the secure channel and a connection is made to host:hostport from the remote machine. Port for- wardings can also be specified in the configuration file. Only root can forward privileged ports. -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 port on the remote side, and whenever a con- nection is made to this port, the connection is for- warded over the secure channel, and a connection is made to host:hostport from the local machine. Privileged ports can be forwarded only when logging in as root on the remote machine. +C Enable compression. -C Disable compression. (default) -o 'option' Can be used to give options in the format used in the configuration files. 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. Comment lines are not currently accepted via this option. -h Display short help on command-line options. Ssh obtains configuration data from the following sources (in this order): system's global configuration file (typi- cally /etc/ssh2/ssh2_config), user's configuration file ($HOME/.ssh2/ssh2_config) and the command line options. For each parameter, the last obtained value will be effective. The configuration file has the following format: `expression:' denotes the start of a per-host confi- guration block, where `expression' is an arbitrary string which distinguishes this block from others. The `expression' can contain wildcards. It will be compared to the hostname obtained from the command-line, and if it matches, the block will be evaluated. Evaluation stops at the next `expression:' statement. If more than one match is found, all will be evaluated and the last obtained values for parameters will be effective. Note that `expression' doesn't have to be a real hostname, as long as the `expression' block contains a "Host" configuration parameter, where the real hostname to connect is defined. Empty lines and lines starting with '#' are ignored as comments. Otherwise a line is of the format "keyword arguments". Note that it is possible to enclose arguments in quotes, and use the standard C convention. The possi- ble keywords and their meanings are as follows (note that the configuration files are case-sensitive, but keywords are case-insensitive): AuthorizationFile Specifies the name of the user's authorization file. BatchMode If set to "yes", ssh disables password/passhphrase querying. This is useful in scripts and other batch jobs where you don't have a user to supply the pass- word. If the "StrictHostKeyChecking" parameter is set to "ask", ssh assumes a "no" answer to queries (this is because ssh doesn't even try to get user input when invoked with "BatchMode yes"). The argument must be "yes" or "no". Ciphers Specifies the ciphers to use for encrypting the ses- sion. Currently, des, 3des, blowfish, idea, arcfour and twofish are supported, of which des, 3des, arcfour, blowfish and twofish are in all distributions. Multiple ciphers can be specified as a comma-separated list. Special values to this option are any, anystd, that allows only standard (see below) ciphers, and anycipher that allows either any available cipher or excludes nonencrypting cipher mode none but allows all others. anystdcipher is the same as above, but includes only those ciphers mentioned in the IETF-SecSH-draft (excluding 'none'). Compression Specifies whether to use compression. The argument must be "yes" or "no". DontReadStdin Redirect input from /dev/null, ie. don't read stdin. The argument must be "yes" or "no". EscapeChar Sets the escape character (default: ~). The escape character can also be set on the command line. The argument should be a single character, '^' followed by a letter, or "none" to disable the escape character entirely (making the connection transparent for binary data). ForcePTTYAllocation For tty allocation. Ie. allocate a tty even if a com- mand is given. The argument must be "yes" or "no". (not yet implemented) ForwardAgent Specifies whether the connection to the authentication agent (if any) will be forwarded to the remote machine. The argument must be "yes" or "no". ForwardX11 Specifies whether X11 connections will be automatically redirected over the secure channel and DISPLAY set. The argument must be "yes" or "no". GatewayPorts Specifies that also remote hosts may connect to locally forwarded ports. The argument must be "yes" or "no". The default is "no". (not yet implemented) GoBackground Requests ssh to go to background after authentication is done and forwardings have been established. This is useful if ssh is going to ask for passwords or passphrases, but the user wants it in the background. The argument must be "yes", "no" or "oneshot". With "oneshot", ssh behaves the same way as with `-f o' commandline arguments. The default is "no". Host Specifies the real host name to log into. With `expres- sion' above, this can be used to specify nicknames or abbreviations for hosts. The default is the name given on the command line. Numeric IP addresses are also per- mitted (both on the command line and in HostName specifications). IdentityFile Specifies the name of the user's identification file. KeepAlive Specifies whether the system should send keepalive mes- sages to the other side. If they are sent, death of the connection or crash of one of the machines will be properly noticed. However, this means that connections will die if the route is down temporarily, and some people find this annoying. The default is "yes" (to send keepalives), and the client will notice if the network goes down or the remote host dies. This is important when using scripts, and many users want it too. To disable keepalives, the value should be set to "no" in both the server and the client configuration files. LocalForward Specifies that a TCP/IP port on the local machine is forwarded over the secure channel to given host:port from the remote machine. The argument should be enclosed in double-quotes (""). The argument format is port:remotehost:remoteport . NoDelay If "yes", enable socket option TCP_NODELAY. The argu- ment must be "yes" or "no". Default is "no". PasswordPrompt Sets the password prompt that the user sees when con- necting to a host. Variables '%U' and '%H' can be used to give the user's login name and host, respectively. Port Specifies the port number to connect on the remote host. The default port number is 22. QuietMode Quiet mode. Causes all warnings and diagnostic messages to be suppressed. Only fatal errors are displayed. The argument must be "yes" or "no". RandomSeedFile Specifies the name of the user's randomseed file. RemoteForward Specifies that a TCP/IP port on the remote machine is forwarded over the secure channel to given host:port from the local machine. The argument should be enclosed in double-quotes (""). The argument format is port:remotehost:remoteport . Ssh1AgentCompatibility Specifies whether to forward also SSH1 agent connec- tion. Legal values for this option are "none", "tradi- tional" and "ssh2". With value "none" (default), the SSH1 agent connection is not forwarded at all. With value "traditional", the SSH1 agent connection is for- warded transparently like in SSH1. Value "traditional" can always be used, but it constitutes a security risk, because the agent does not get the information about the forwarding path. Value "ssh2" makes SSH1 agent forwarding similar to SSH2 agent forwarding. With this mode the agent gets the information about the agent forwarding path. Note that value "ssh2" can only be used if you use ssh-agent2 in SSH1 compatibility mode. "yes" or "no". Ssh1Compatibility Specifies whether to use SSH1 compatibility code. With this option, ssh1 is executed when the server supports only SSH 1.x protocols. The argument must be "yes" or "no". Ssh1Path Specifies the path to ssh1 client, which is executed if the server supports only SSH 1.x protocols. The argu- ments for ssh2 are passed to the ssh1 client. StrictHostKeyChecking If this flag is set to "yes", ssh2 will never automati- cally add host keys to the $HOME/.ssh2/hostkeys direc- tory, and will refuse to connect hosts whose host key has changed. This provides maximum protection against Trojan horse attacks. However, it can be somewhat annoying if you don't have the necessary keys in /etc/ssh2/hostkeys and you frequently connect new hosts. Basically this option forces the user to manu- ally add any new hosts. Normally this option is set to "ask", and new hosts will automatically be added to the known host files after you have confirmed you really want to do that. If this value is set to "no" then new host will automatically be added to the known host files. The host keys of known hosts will be verified automatically in either case. If this value is set to "ask", the user also has the option to change the key on the disk on the fly. The argument must be "yes", "no" or "ask". User Specifies the user to log in as. This can be useful if you have a different user name in different machines. This saves the trouble of having to remember to give the user name on the command line. VerboseMode Verbose mode. Causes ssh2 to print debugging messages about its progress. This is helpful when debugging con- nection, authentication, and configuration problems. Ssh2 will normally set the following environment variables: DISPLAY The DISPLAY variable indicates the location of the X11 server. It is automatically set by ssh2 to point to a value of the form "hostname:n" where hostname indicates the host where the shell runs, and n is an integer >= 1. Ssh2 uses this special value to forward X11 connec- tions over the secure channel. The user should nor- mally 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. LOGNAME Synonym for USER; set for compatibility with systems using this variable. MAIL Set to point the user's mailbox. PATH Set to the default PATH, as specified when compiling ssh2 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 by setting environment variable SSH_SOCKS_SERVER to socks://mylogin@socks.ssh.fi:1080/203.123.0.0/16,198.74.23.0/24 uses host socks.ssh.fi port 1080 as your SOCKS server if 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 SSH_SOCKS_SERVER variable can be specified at compile time by specifying --with-socks- server=VALUE on the configure command line when compil- ing ssh2. 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 SSH_SOCKS_SERVER variable is set, it should almost always contain local loopback network (127.0.0.0/8) as network that is connected directly. SSH2_AUTH_SOCK if exists, is used to indicate the path of a unix- domain socket used to communicate with the authentica- tion agent (or its local representative). SSH2_CLIENT Identifies the client end of the connection. The vari- able contains three space-separated values: client ip- address, client port number, and server port number. SSH2_ORIGINAL_COMMAND This will be the original command given to ssh2 if a forced command is run. It can be used to fetch argu- ments etc. from the other end. This need not be a real command, it can be a name of a file, device, parameters or anything else. SSH2_TTY This is 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 The timezone variable is set to indicate the present timezone if it was set when the daemon was started (the daemon passes the value to new connections). USER Set to the name of the user logging in. Additionally, ssh2 reads /etc/environment and $HOME/.ssh2/environment, and adds lines of the format VARNAME=value to the environment. Some systems may have still additional mechanisms for setting up the environment, such as /etc/default/login on Solaris. FILES $HOME/.ssh2/random_seed Used for seeding the random number generator. This file contains sensitive data and its permissions should be 'read/write' for the user and 'not accessible' for others. This file is created the first time the program is run and updated automatically. The user should never need to read or modify this file. $HOME/.ssh2/ssh2_config This is the per-user configuration file. The format of this file is described above. This file is used by the ssh2 client. This file does not usually contain any sensitive information, but the recommended permissions are 'read/write' for the user, and 'not accessible' for others. $HOME/.ssh2/identification contains information on how the user wishes to authen- ticate himself when contacting a specific host. The identification file has the same general syntax as the configuration files. The following keywords can be used: IdKey This is followed by the filename of a private key in the $HOME/.ssh2 directory used for identification when contacting a host. If there are more than one IdKeys , they are tried in the order that they appear in the identification file. PgpSecretKeyFile This is followed by the filename of the user's OpenPGP private keyring in $HOME/.ssh2 directory. OpenPGP keys listed after this line are expected to be found from this file. Keys identified with "IdPgpKey*"-keywords are used like ones identified with "IdKey"-keyword. IdPgpKeyName This is followed by the OpenPGP key name of the key in PgpSecretKeyFile file. IdPgpKeyFingerprint This is followed by the OpenPGP key fingerprint of the key in PgpSecretKeyFile file. IdPgpKeyFingerprint This is followed by the OpenPGP key id of the key in 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 configuration files. The following keywords can be used: Key This is followed by the filename of a public key in the $HOME/.ssh2 directory that is used for identification when contacting the host. If there are more than one key, they are all acceptable for login. PgpPublicKeyFile This is followed by the filename of the user's OpenPGP public keyring in $HOME/.ssh2 directory. 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 This is followed by the OpenPGP key name. PgpKeyFingerprint This is followed by the OpenPGP key fingerprint. PgpKeyId This is followed by the OpenPGP key id. Command This keyword, if used, must follow the "Key" or "PgpKey*" -keyword above. This is used to specify a "forced command", that will be executed on the server side instead of anything else when the user is authen- ticated. The command supplied by the user (if any) is put in the environment variable "SSH2_ORIGINAL_COMMAND". The command is run on a pty if the connection requests a pty; otherwise it is run without a tty. A quote may be included in the command by quoting it with a backslash. 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 forward- ings unless they are explicitly prohibited. $HOME/.ssh2/hostkeys/key_xxxx_yyyy.pub These file are the public keys of the hosts you connect to. These update automatically, unless you have set StrictHostKeyChecking to "yes". If a host's key changes, you should put here the new key. (Do not do that, unless you can be sure that the key is valid, ie. that there has been no man-in-the-middle attack!) The "xxxx" is the port on the server, where sshd2 runs, and the "yyyy" is the host (specified on command-line). /etc/ssh2/hostkeys/key_xxxx_yyyy.pub If a host key is not found from the users "$HOME/.ssh2/hostkeys" directory, this is looked next. These files have to be updated manually; no files are put here automatically. $HOME/.rhosts This file contains host-username pairs, separated by a space, one per line. The given user on the correspond- ing host is permitted to log in without password. The same file is used by rlogind and rshd. sshd2 differs from rlogind and rshd in that it requires public host key authentication in addition to validating the host name retrieved from domain name servers. The file must be writable only by the user; it is recommended that the file is not accessible by 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 For ssh2, this file is exactly the same as for .rhosts. However, this file is not used by rlogin and rshd, so using this permits access using ssh2 only. /etc/hosts.equiv This file is used during .rhosts authentication. In its simplest form, this file contains host names, one per line. Users on those hosts are permitted to log in without a password, provided that they have the same user name on both machines. The host name may also be followed by a user name; such users are permitted to log in as any user on this machine (except root). Additionally, the syntax +@group can be used to specify netgroups. Negated entries start with '-'. If the client host/user is successfully matched in this file, login is automatically permitted, provided the client and server user names are the same. Addition- ally, successful RSA host authentication is normally required. This file must be writable only by root; it is recommended that it be world-readable. Warning: It is almost never a good idea to use user names in hosts.equiv. Note that this really means that the named user(s) can log in as anybody, including bin, daemon, adm, and other accounts that own critical binaries and directories. Using a user name practi- cally grants the user root access. The only valid use for user names should be in negative entries. Note that this warning also applies to rsh/rlogin. /etc/shosts.equiv This is processed exactly as /etc/hosts.equiv. However, this file may be useful in environments that want to run both rsh/rlogin and ssh2. $HOME/.ssh2/knownhosts/xxxxyyyy.pub These are the public hostkeys of hosts that a user wants to log from using "hostbased"-authentication (equivalent with ssh1's RhostsRSAAuthentication). Also, a user has to set up her/his $HOME/.shosts (which only ssh uses) or $HOME/.rhosts file (insecure, as it is used by the r*-commands also). If username is the same in both hosts, it is adequate to put the public hostkey to /etc/ssh2/knownhosts and add the host's name to /etc/shosts.equiv (or /etc/hosts.equiv). xxxx denotes the hostname (FQDN) and yyyy the publickey algorithm of the key. For example, zappa.foo.fi's hostkey algorithm is ssh- dss. The hostkey would be named "zappa.foo.fi.ssh- dss.pub" in the knownhosts-directory. Possible names for publickey-algorithms are "ssh-dss" and "ssh-rsa" (without the quotes). /etc/ssh2/knownhosts/xxxxyyyy.pub As above, but system-wide. These can be overridden by the user by putting a file with the same name to her/his $HOME/.ssh2/knownhosts directory. AUTHORS SSH Communications Security Ltd. For more information, see http://www.ssh.fi. SEE ALSO sshd2(8), ssh-keygen2(1), ssh-agent2(1), ssh-add2(1), scp2(1), sftp(1) rlogin(1), rsh(1), telnet(1)