ssh - Secure Shell client (remote login program).
ssh [-a] [-c cipher] [-C] [-d debug_level] [-e character]
[-F file] [-g] [-h] [-i file] [-l username]
[-m mac_algorithm] [-n] [-o option] [-p port] [-q]
[-s subsystem] [-t] [-v] [-V] [-X] [-x] [-Y]
[[username@]host[#port]] [remote_command [arguments] ...]
ssh (Secure Shell) is a program for securely logging onto a remote computer and executing commands. It provides a secure alternative to telnet, FTP, rlogin, or rsh. Secure Shell connections require both server and user authentication, and all communications pass between hosts over an encrypted communication channel. You can also use Secure Shell connections to forward X11 sessions or specified TCP/IP ports through the secure tunnel. The syntax is:
ssh [options] [user@]hostname[#port] [remote_command [arguments] ...]
When no user is specified, the client connects using your current login name. When no port is specified, the client uses the default port (which is 22 unless this has been changed in the client configuration file).
When no command is specified, ssh creates a new session on the remote host. When a command is specified, the command is executed on the host and then ssh exits. When no user is specified, the current user name is used.
Note: Quotation marks are required if you specify a remote command that takes arguments.
You can configure ssh connections using the options described below, and by using configuration files. Command line options override configuration file settings. A default, system-wide configuration file is installed automatically to /etc/ssh2/ssh2_config. You can also configure user-specific settings by creating and configuring $HOME/.ssh2/ssh2_config. Settings in the user-specific configuration file override settings in the system-wide file.
Encryption and Data Integrity Checking
Once a session is established, all data that passes between the client and server is encrypted using a symmetric cipher. The client and server agree on a cipher during the key exchange portion of the connection process. The client presents a list of supported ciphers in order of preference. The cipher used for a given session is the first item in this list that is also supported by the server. You can configure which ciphers the client supports using the -c option on the command line, or the Ciphers keyword in the configuration file.
Secure Shell connections use MACs (message authentication codes) to ensure data integrity. The client and server independently compute a hash for each packet of transferred data. If the message has changed in transit, the hash values are different and the packet is rejected. The MAC used for a given session is the MAC highest in the client's order of preference that is also supported by the server. You can configure which MACs the client supports using the -m option on the command line, or the MACs keyword in the configuration file.
Secure Shell connections require both server and client authentication.
Server authentication enables the client to confirm the identity of the server. By default, Secure Shell servers authenticate using public key authentication. If the host public key has not previously been installed on the client, the first time you attempt to connect you see a message indicating that this is an unknown host. This message includes a fingerprint that identifies the host. To be sure that this is actually your host, you should contact the host system administrator who can confirm that this is the correct fingerprint. Until you know that the host is actually your host, you are at risk of a "man-in-the-middle" attack, in which another server poses as your host.
When you accept a new host key, it is added automatically to your known host keys in $HOME/.ssh2/hostkeys. To reduce the risk created by allowing users to accept unknown keys, administrators can manually install host keys on client computers. Keys can be added to users' host key directories or to a system-wide directory (/etc/ssh2/hostkeys). For details see the FILES section below. An additional option for server authentication is Kerberos authentication using gssapi-keyex. To use this option, the server host and client user must both be configured to authenticate to the Kerberos realm.
Several methods of client authentication are available, and both the client and server can be configured to determine which method — or methods — are used. The server can be configured to allow, require, or deny client authentication methods. During Secure Shell connection negotiations, the server presents a list of allowed and required methods from which the client and server negotiate one or more authentication methods.
Authentication attempts follow the order of preference set by the client. The connection uses the first authentication technique highest in the client order of preference that is also allowed by the server. If the server is configured to require more than one method, multiple authentication methods are needed to establish a connection.
You can configure which authentication methods the client attempts, and the order in which they are tried, using the AllowedAuthentications keyword in the configuration file. By default, ssh attempts gssapi-keyex, gssapi-with-mic, public key, keyboard interactive, then password.
If you use Secure Shell public keys to authenticate client users, you need to configure both the client and the server. On the client, generate the key and then add a line for this key to the client identification file ($HOME/.ssh2/identification). This file lists the keys the client presents for authentication. For details see FILES in ssh(1). On the server, copy each client user's public key to that user's Secure Shell directory ($HOME/.ssh2) and add the key to the user's authorization file ($HOME/.ssh2/authorization by default). This file lists the keys the server accepts for user authentication. For details see FILES in sshd(8).
Port forwarding is available and can be used to secure X11 connections and TCP/IP communications. Port forwarding, also known as tunneling, provides a way to redirect communications through the Secure Shell channel of an active session. When port forwarding is configured, all data sent to a specified port is redirected through the secure channel.There are two types of port forwards: local port forwards and remote port forwards. If the TCP client application (whose connection you want to forward) is located on the same computer as the Secure Shell client, configure local forwarding to redirect the traffic from this application to the TCP server application. If the TCP client application is on the same computer as the Secure Shell server, use remote forwarding.
Options are available in both a single-character form (such as -o) and a descriptive equivalent (--option). Single characters are shown here. To view the descriptive equivalents, use the -h command line option.
Disables authentication agent forwarding. Authentication agent forwarding is enabled using the ForwardAgent keyword, which is set to `yes' by default. You can use -a to override the configuration file setting.
Specifies one or more (comma-separated) encryption algorithm supported by the client. The client and server agree on a cipher during the key exchange portion of the connection process. The client presents a list of supported ciphers in order of preference. The cipher used for a given session is the first item in this list that is also supported by the server. Allowed values are `aes128-ctr', `aes128-cbc', aes192-ctr', `aes192-cbc', `aes256-ctr', `aes256-cbc', `blowfish-cbc', `arcfour', `arcfour128', `arcfour256', `cast128-cbc', and `3des-cbc'.
You can also set this value to `none'. When `none' is the agreed on cipher, data is not encrypted. Note that this method provides no confidentiality protection, and is not recommended.
The following values are provided for convenience: `aes' (all supported aes ciphers), `blowfish' (equivalent to `blowfish-cbc'), `cast' (equivalent to `cast128-cbc'), `3des' (equivalent to `3des-cbc'), `Any' or `AnyStd' (all available ciphers plus `none'), and `AnyCipher' or `AnyStdCipher' (all available ciphers).
You can also configure encryption algorithms in the configuration file using the Ciphers keyword; the default is `AnyStdCipher'.
Disables compression. Compression is desirable on modem lines and other slow connections, but will slow down response rates on fast networks. Compression also adds extra randomness to the packet, making it harder for a malicious person to decrypt the packet. Compression can be enabled using the Compression keyword in the configuration file. Using -C overrides the configuration file setting.
Sets the debug level. Increasing the value increases the amount of information displayed. Use 1, 2, 3, or 99. (Values 4-98 are accepted, but are equivalent to 3.)
Sets the escape character for the terminal session. The default character is a tilde (~). Setting the escape character to `none' means that no escape character is available and the tilde acts like any other character. For details, see ESCAPE SEQUENCES below. You can also set the escape character in the configuration file using the EscapeChar keyword.
Specifies an additional configuration file. Settings are read from this file in addition to the default user-specific file ($HOME/.ssh2/ssh2_config and/or the system-wide file (/etc/ssh2/ssh2_config). Settings in this file override settings in both the user-specific file and the system-wide file.
Enables gateway ports. Remote hosts are allowed to connect to local forwarded ports. You can also configure this in the configuration file using the GatewayPorts keyword.
Displays a brief summary of command options.
Specifies an alternate identification file to use for public key authentication. The file location is assumed to be in the current working directory unless you specify a fully-qualified or relative path. The default identity file is $HOME/.ssh2/identification. You can also specify an identity file in the configuration file using the IdentificationFile keyword.
Specifies a name to use for login on the remote computer. You can also specify a user name in the configuration file using the Username keyword. (Note: If you include the optional [user@] as part of your host specification, -l overrides the specified user name.)
Redirects data from the specified local port, through the secure tunnel to the specified destination host and port. When a Secure Shell connection is established, the Secure Shell client opens a socket on the Secure Shell client host using the designated local port (listening_port). Configure your application client (the one whose data you want to forward) to send data to the forwarded socket (rather than directly to the destination host and port). When that client establishes a connection, all data sent to the forwarded port is redirected through the secure tunnel to the Secure Shell server, which decrypts it and then directs it to the destination socket (host,hostport). Unless the gateway ports option is enabled, the forwarded local port is available only to clients running on the same computer as the Secure Shell client. Multiple client applications can use the forwarded port, but the forward is active only while ssh is running.
Note: If the final destination host and port are not on the Secure Shell server host, data is sent in the clear between the Secure Shell host and the application server host.
You can also configure local forwarding in the configuration file using the LocalForward keyword.
Specifies which MACs (message authentication codes) are supported by the client. Allowed values are `hmac-sha1', `hmac-sha1-96', `hmac-md5', `hmac-md5-96'; and `hmac-ripemd160'. Use `AnyMac' to support all of these. Use `AnyStdMac' to support `hmac-sha1', `hmac-sha1-96', `hmac-md5', and `hmac-md5-96'. Additional options are `none', `any' (equivalent to AnyMac plus `none'), and `AnyStd' (equivalent to `AnyStdMac' plus `none'). Multiple MACs can also be specified as a comma-separated list. When `none' is the agreed on MAC, no message authentication code is used. Because this provides no data integrity protection, options that include `none' are not recommended.
You can also configure MACs in the configuration file using the MACs keyword; the default is `AnyStdMac'.
Redirects stdin from /dev/null, which prevents reading from stdin. You can also configure this in the configuration file using the DontReadStdin keyword.
Sets any option that can be configured using a configuration file keyword. For a list of keywords and their meanings, see ssh2_config(5). Syntax alternatives are shown below. Use quotation marks to contain expressions that include spaces.
-o key1="sample value"
-o "key1 value"
To configure multiple options, use multiple -o switches.
-o key1=value -o key2=value
Specifies the port to connect to on the server. The default is 22, which is the standard port for Secure Shell connections. You can also configure the port in the configuration file using the Port keyword.
Enables quiet mode, which causes all warning and diagnostic messages, including banners, to be suppressed. You can also configure this in the configuration file using the QuietMode keyword.
Redirects data from the specified remote port (on the computer running the Secure Shell server), through the secure tunnel to the specified destination host and port. When the Secure Shell connection is established, the Secure Shell server opens a socket on its host (the computer running the Secure Shell server) using the designated remote port (listening_port). Configure your client application (the one whose data you want to forward) to send data to the forwarded socket (rather than directly to the destination host and port). When that client establishes a connection, all data sent to the forwarded port is redirected through the secure tunnel to the Secure Shell client, which decrypts it and then directs it to the destination socket (host,hostport).
Note: If the final destination host and port are not on the same computer as the Secure Shell client, data is sent in the clear between the Secure Shell client and the final destination.
You can also configure remote forwarding in the configuration file using the RemoteForward keyword.
Invokes the specified subsystem on the remote system. Subsystems are a feature of the Secure Shell protocol which facilitates the use of Secure Shell as a secure transport for other applications (such as sftp). Subsystems must be defined by the Secure Shell server.
Forces a tty allocation even if a command is specified. You can also configure this in the configuration file using the ForcePTTYAllocation keyword.
Sets the debug level to verbose mode, which is equivalent to using `-d 2'. You can also configure this in the configuration file using the VerboseMode keyword.
Displays product name and version information and exits. If other options are specified on the command line, they are ignored.
Enables X11 connection forwarding and treats X11 clients as untrusted. Untrusted remote X11 clients are prevented from tampering with data belonging to trusted X11 clients. You can also configure this in the configuration file using the ForwardX11 keyword.
Disables X11 connection forwarding. You can also configure this in the configuration file using the ForwardX11 keyword.
Enables X11 connection forwarding and treats X11 clients as trusted.
Use escape sequences to manage your client terminal session. Escape sequences are recognized only after a newline character. If you have just logged in, press Enter before you enter your first escape sequence. You can configure an alternate escape character using -e on the command line or EscapeChar in the configuration file.
The following escape sequences are available. These are shown with the default escape character, a tilde (~).
~. Terminates the connection.
~^Z Suspends ssh.
~# Lists active forwarded connections. Note: Forwarded connections are listed only when the ports are actually transmitting data.
~- Disables use of the escape character for the duration of the session.
~? Displays a list of available escape sequences.
~~ Sends the escape character to the host. (Type the escape character twice to send one escape character.)
~C Execute command mode, which you can use to request port forwarding. The options are:
-L[bind_address:]port:host:hostport Request local
~V Sends version information to stderr.
~s Sends connection information to stderr.
~r Initiates an immediate key exchange to establish new encryption and integrity keys.
~l Enters line mode. Keystrokes are stored to a buffer and output when you press Enter.
~B Sends a BREAK to the remote system.
User-specific configuration file. The format is the same as the system-wide configuration file.
System-wide configuration file. This file is installed when you install Reflection for Secure IT. The installed file shows default values as commented out lines. Edit this file to change system-wide settings. For information about keywords and supported values, see ssh2_config(5).
This directory contains the public keys of hosts trusted by the current user. By default, keys are added automatically to this location when the user answers `yes' in response to an unknown host prompt. (This behavior can be changed using the StrictHostKeyChecking keyword in the configuration file.) Starting with version 7.0, host keys use the following file name format:
Where port is the port used for the ssh connection, host is the host name, and IP is the host IP address.
Earlier versions used key_port_host.pub, and this format is still supported.
System-wide known hosts. Hosts with keys in this list are trusted for all users of the computer. No keys are installed to this location automatically. To add a system-wide trusted host, create this directory and put a copy of the host public key in it. Use the file name format described above for $HOME/.ssh2/hostkeys/key_*.pub.
An identification file is required if you use public keys for user authentication. (This is the default file name and location. You can redefine the name and/or location of the identification file on the ssh command line using -i or in the configuration file using the IdentificationFile keyword.) The identification file contains a list of one or more private keys held by a client user. Any listed key can be used by the client for user authentication. If more than one key is listed, the client tries the first key in the list, then continues trying the other keys in order. If no path information is provided, the client looks for listed keys in $HOME/.ssh2/. Use the following syntax to add keys to the list:
Note: Server-side configuration is also required for user public key authentication. See sshd(8).
Exit values are provided to assist in troubleshooting. In scripts we recommend that you use only zero or non-zero for error handling. Looking for specific non-zero values is not reliable because of variability caused by operating systems and servers.
Error codes are limited to values 0-255. Errors 65-79 are disconnect conditions, calculated as 64 + error value returned from host, as defined in RFC4253. Errors values 128-254 are system Signals, calculated as 128 + Signal value. Error value 255 is returned when ssh fails after being executed by another process, such as scp.
1 Generic error.
2 Remote host connection failure.
65 Access denied by host for this client address.
66 Protocol error.
67 Key exchange failed.
68 Authentication failed.
69 MAC error.
70 Compression error.
71 Service not available.
72 Protocol version not supported.
73 Host key not verifiable.
74 Connection lost.
75 Disconnected by application.
76 Too many connections.
77 Cancelled by user.
78 No more authentication methods available.
79 Unknown user name.
The following example logs onto the remote host using the current user name.
The following example logs onto the remote host as joe, executes the cd and ls commands, then exits.
ssh email@example.com "cd .ssh2; ls"
The following example creates a log file with verbose debugging information.
ssh -d3 firstname.lastname@example.org 2> debug_log
The following example uses local forwarding to secure email communications between a mail client running on the same computer as the Secure Shell client and a mail server running on the same computer as the Secure Shell server (mailserver.com in this example). The local mail client is configured to send communications to local port 14300. Data received on port 14300 is forwarded through the secure tunnel to the server, where it is redirected to port 143.
ssh -L 14300:localhost:143 email@example.com
Copyright (C) 2008 Attachmate Corporation
ssh2_config(5), ssh-keygen(1), scp(1), sftp(1), ssh-add(1), ssh-agent(1), sshd(8), sshd2_config(5)
Additional Reflection for Secure IT documentation is available online from the Attachmate documentation web page:
And from the technical note library: