Show Contents / Index / Search

Client Configuration Keywords

You can configure the following settings in the client configuration file. (The global file is /etc/ssh2/ssh2_config; the user-specific file is $HOME/.ssh2/ssh2_config.) You can also configure these settings using the -o option on the ssh command line.

AllowedAuthentications

Specifies which authentication methods the client attempts, and the order in which they are tried. The supported methods are:`gssapi-keyex', `gssapi-with-mic', `publickey', `keyboard-interactive', and `password'. Use a comma-separated list to specify supported methods. The client attempts authentication methods in order from first to last. The authentication technique used for the connection is the one 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 may be needed to establish a connection. To support automated scripts, the least interactive methods should be placed first in the list. The default is `gssapi-with-mic, publickey, keyboard-interactive, password'.

AuthenticationSuccessMsg

Specifies whether to display the following message when authentication has been completed successfully: "Authentication successful." The allowed values are `yes' and `no'. The default is `yes'.

BatchMode

Specifies whether to disable all queries for user input, including password and passphrase prompts, which is useful for scripts and batch jobs. If StrictHostKeyChecking is set to `ask' and BatchMode is set to `yes', the client assumes a "no" response to all queries about unknown host keys. The allowed values are `yes' and `no'. The default is `no'.

CheckHostIP

Specifies whether host IP address checking is performed using the host name and IP address encoded in the public key file name. When a user accepts a new host key, the key is added to the known hosts store using the format key_port_host,IP.pub. When CheckHostIP is enabled, host authentication fails if the actual IP of the specified host doesn't match the encoded IP address for that host. Enabling this setting helps detect DNS spoofing if the host key changes. The allowed values are `yes' and `no'. The default is `yes'.

Note: Host keys added to the host key store using versions earlier than v. 7.0 do not include the host IP address. Disable CheckHostIP if you use keys with the older format.

Ciphers

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-cbc', `blowfish-cbc', `arcfour', `arcfour128', `arcfour256', `aes192-cbc', `aes256-cbc', `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' (which combines `aes128-cbc', `aes192-cbc', and `aes256-cbc'), `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 specify encryption algorithms on the ssh command line using the -c option. The default is `AnyStdCipher'.

ClearAllForwardings

Clears any local, remote, or dynamically forwarded ports that have already been processed from either a configuration file or the command line. The allowed values are `yes' and `no'. The default is `no'. Note: scp and sftp clear all forwarded ports automatically regardless of the value of this setting.

Compression

Specifies whether compression is enabled. 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. The allowed values are `yes' and `no'. The default is `no'. Compression can be disabled on the ssh command line using the -C option, but can only be enabled in the configuration file.

ConnectionReuse

Specifies whether new ssh , scp , and sftp sessions can reuse an established connection. This feature allows you to start new sessions without having to reauthenticate. The allowed values are `yes' and `no'. The default is `no'. When set to `yes', a new session reuses an existing tunnel if the target host, port, and user are all identical to those used for the established connection. When set to `no', the client establishes a new connection for each session, which means that each new connection repeats the authentication process and also applies any modified connection-specific settings (such as forwards and ciphers).

Note: Connection reuse may fail if the server administrator has configured restricted directory access using ChrootSftpGroups or ChrootSftpUsers.

ConnectionTimeout

Specifies the maximum time (in seconds) that the client waits when trying to connect to the server. The default is set to 0 (zero), which means that the client sets no limit and the actual limit is determined by the operating system.

DontReadStdin

Redirects stdin from /dev/null, which prevents reading from stdin. You can also configure this on the ssh command line using the -n option. The allowed values are `yes' and `no'. The default is `no'.

EscapeChar

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 in the ssh man page. You can also set the escape character on the ssh command line using the -e option.

ExitOnForwardFailure

Specifies whether ssh terminates the connection if all requested dynamic, local, and remote port forwardings cannot be configured. The allowed values are `yes' and `no'. The default is `no'.

ForcePTTYAllocation

Forces a tty allocation even if a command is specified. The allowed values are `yes' and `no'. The default is `no'. You can also configure this on the ssh command line using the -t option.

ForwardAgent

Specifies whether a connection to the authentication agent (if established) is forwarded to the remote machine. The allowed values are `yes' and `no'. The default is `yes'.

ForwardX11

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. The allowed values are `yes' and `no'. The default is `yes'. You can also configure this on the ssh command line using the -X option.

GatewayPorts

The gateway ports setting controls whether locally forwarded ports are available to remote applications. By default this setting is not enabled, and the client uses the loopback address ("localhost" or 127.0.0.1) when it opens a socket for local port forwarding. This prevents applications running on other computers from connecting to the forwarded port. When you enable gateway ports, a remote application client can open a socket using the Secure Shell client's Ethernet address (such as an IP address, a URL, or a DNS name). For example, a Secure Shell client running on acme.com might be configured to forward port 8088. When gateway ports are not enabled, the forwarded socket is localhost:8088. When gateway ports are enabled, the forwarded socket is acme.com:8088. The allowed values are `yes' and `no'. The default is `no'. You can also configure this on the ssh command line using the -g option.

GSSAPIDelegateCredentials

Specifies whether to forward (delegate) GSSAPI credentials to the server. The allowed values are `yes' and `no'. The default is `no'.

Host

Specifies the actual host name or IP address to use for a connection. The default is an empty string. This keyword can be used in combination with a host stanza expression to create an alternate name for connecting to a host. When this keyword appears outside any stanza, it can be used to specify a default host for the connection.

IdentificationFile

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. For details, see the FILES section below. You can also configure this on the ssh command line using the -i option.

IdentityFile

This keyword is deprecated. It is the equivalent of IdentificationFile.

KeepAlive

Specifies whether the client sends TCP keep-alive messages to the server. This keyword is deprecated. Use ServerAliveInterval instead. The allowed values are `yes' and `no'. The default is `yes'.

LibGssKrb5

Use this setting if you use GSSAPI (Kerberos 5) authentication. It specifies the fully-qualified path to the Kerberos library called libgssapi_krb5.so

LocalForward

Use this keyword to forward connections from an arbitrary port on the client through the secure tunnel. The syntax for configuring this setting is:

listening_port:host:hostport

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.

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.

The following example uses local forwarding to secure e-mail 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. 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.

LocalForward=14300:localhost:143

You can also configure local forwarding on the ssh command line using the-L option.

MACs

Specifies which MACs (message authentication algorithms) 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 on the ssh command line using the -m option. The default is `AnyStdMac'.

NumberOfPasswordPrompts

Specifies the number of password prompts to respond to before giving up. Note: The server can also set a maximum number of allowed password attempts. If you set NumberOfPasswordPrompts to a larger value than is configured by the server, the connection will fail when the server limit is reached. The default is 3.

Port

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 this on the ssh command line using the -p option.

QuietMode

Enables quiet mode, which causes all warning and diagnostic messages, including banners, to be suppressed. The allowed values are `yes' and `no'. The default is `no'. You can also configure this on the ssh command line using the -q option.

RekeyIntervalSeconds

Specifies the number of seconds the client waits before initiating a negotiation for a new session key. The value must be an integer. The default is 3600. This key can be used in combination with RekeyLimit, in which case the client initiates a new key exchange whenever the first limit is reached.

RekeyLimit

Specifies the maximum amount of data that can be transmitted before the client initiates a negotiation for a new session key. The argument is the number of bytes, with an optional suffix of `K', `M', or `G' to indicate kilobytes, megabytes, or gigabytes, respectively. Set this value to 0 (zero) to use the default value. The default is between `1G' and `4G', depending on the cipher. This key can be used in combination with RekeyIntervalSeconds, in which case the client initiates a new key exchange whenever the first limit is reached.

RemoteForward

Use this keyword to forward connections from an arbitrary port on the server through the secure tunnel. The syntax for configuring this setting is:

listening_port:host:hostport

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 port forwarding on the ssh command line using the -R option.

SendNOOPPackets

Specifies whether the client sends NOOP messages through the Secure Shell channel to server. Setting this to `yes' is equivalent to setting ServerAliveCountMax to 3 and ServerAliveInterval to 600. The allowed values are `yes' and `no'. The default is `no'.

ServerAliveCountMax

Use this setting to close sessions to servers that have become unresponsive. It is relevant only when ServerAliveInterval is set to a non-zero value. ServerAliveCountMax sets the maximum number of server alive messages the client will send without receiving a return message from the server. When this threshold is reached, the client terminates the session. The default is 3. For example, if ServerAliveInterval is set to 600, andServerAliveCountMax is 3, the client sends a message to the server every 10 minutes until it has sent 3 messages to the server without response. This means that the client will close an unresponsive connection after about 30 minutes.

ServerAliveInterval

Sets a time interval, in seconds, for sending NOOP messages to the server through the Secure Shell channel. The client sends a message to the server when no data has been received from the server during the specified interval. Setting this to a non-zero value can be used to inform the Secure Shell server and the TCP stack that the client is still alive, inform all networking hardware (such as routers and NATs) that the Secure Shell connection is still active, and detect network problems and application problems. Use this setting in conjunction with ServerAliveCountMax to terminate a connection to a server that has become unresponsive. The default is 0; which configures the client to send no messages.

SetRemoteEnv

Specifies an environment variable to set on the server before executing a shell or a command. The value should be of form: VAR=val, where val can be empty. The argument is case-sensitive.

Note: Values set with this keyword are cumulative; you can set multiple variables by configuring this keyword multiple times in one or more configuration files.

StrictHostKeyChecking

This keyword determines how the client behaves when a host presents an unknown key for authentication. The possible values are:

`yes' - Connections succeed only when host keys have been manually copied to the user's host key directory ($HOME/.ssh2/hostkeys), or the system-wide host key directory/etc/ssh2/hostkeys The client does not add host keys to the user's computer. This is the most secure option.

`ask' - This is the default. The client displays a prompt asking if the user wants to accept a key from an unknown host. This prompt shows the host key fingerprint, which can be used to verify the host's identity. If the user answers `yes', the client adds the host key to the known host keys in the user's directory ($HOME/.ssh2/hostkeys) and uses this key to verify the host's identity in subsequent connections.

`no' - Unknown host keys are added automatically to the user's host key directory ($HOME/.ssh2/hostkeys) and used to verify the host's identity in subsequent connections. The user never knows when an unknown host key is presented.

StrictModes

Specifies how the client checks file modes and ownership during public key authentication. When set to `yes', the .ssh2 folder must not be group or world readable (permissions=700), and the private keys listed in the identification file must not be group or world readable (permissions=600). When set to `no', the private key restrictions are still enforced, but not those of the .ssh2 folder. If these conditions aren't met, public key authentication fails. The allowed values are `yes' and `no'. The default is `yes'.

TrustX11Applications

Specifies whether the X server treats forwarded X11 client applications as trusted. The allowed values are `yes' and `no'. The default is `no'. Set this to `yes' to give remote X11 clients full access to the X11 display. When this is set to `no', X11 applications are treated as untrusted. This avoids the risk created when a connection to a compromised host allows applications on that host to "sniff" input operations using the forwarded X11 connection.

User

Specifies the user name for the remote server. You can configure different user names for different hosts by defining this setting in host-specific stanzas. The default is the current value of the environment variable $USER.

VerboseMode

Sets the debug level to verbose mode, which is equivalent to setting the debug level to 2. You can also configure this on the ssh command line using the -v option. eThe allowed values are `yes' and `no'. The default is `no'.

XauthPath

Specifies the location of the xauth(1) program. The default (for example /usr/X11R6/bin/xauth) is system-dependent.