ssh2_config Man Page

NAME

ssh2_config - Client configuration file used by ssh.

SYNOPSIS

/etc/ssh2/ssh2_config - System-wide configuration file.

$HOME/.ssh2/ssh2_config - User configuration file.

DESCRIPTION

Reflection for Secure IT configuration files control connections made using ssh. These settings also affect scp and sftp, which use ssh to create the connection.

The ssh client processes settings cumulatively in the following order. If a setting is configured in more than one place, the last value processed overrides any previous value of the same setting.

System-wide configuration file: /etc/ssh2/ssh2_config
User-specific configuration file: $HOME/.ssh2/ssh2_config
Optional user configuration file specified using the -F switch on the ssh command line.
Command line options used with ssh, scp, and sftp.

A sample configuration file is installed to /etc/ssh2/ssh2_config. This file includes comment lines that show all available settings and their default values. A duplicate copy of this file is installed to /etc/ssh2/ssh2_config.example.

FILE FORMAT

The configuration file consists of keywords followed by values. You can use optional host stanzas to configure settings specific to individual hosts or groups of hosts. If a setting is configured in more than one place in the file, the value configured further down the list overrides the previous value.

Any line starting with a number sign (#) is a comment. Any empty line is ignored. REGULAR EXPRESSIONS

Regular expressions are evaluated using POSIX-Extended syntax. For details about regular expression rules, see:

http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap09.html

Keyword syntax

Every keyword requires a value. The value can be separated from the keyword by spaces, or optional spaces and exactly one "=". Enclose the value in quotation marks (single or double) if it includes spaces. For example:

key value

key=value

key="value with spaces"

key=value1, value2

Keywords are not case sensitive.

Host Stanzas

Use host stanzas to apply different settings to different hosts. To create a host stanza, use a regular expression that identifies an individual host or a group of hosts. Place this at the beginning of a new line, followed by a colon (:). This line cannot contain white space. When you initiate a connection, the client matches host stanza expressions against the host name you specify for that connection. If the host stanza expression matches your specified host, values within that stanza are applied to the connection. The client continues to search for matching host stanzas and applies any relevant settings until the end of the file is reached. Because the last value of a keyword overrides any previous value for the same keyword, you need to place global settings above host-specific settings. Settings outside of any stanza apply to all connections, but can be superseded by subsequent settings placed within a stanza.

You can configure global settings by creating a stanza labeled with ".*:" Settings in this stanza apply to any host you specify on the command line.

Note: Global settings configured in this stanza do not apply to a connection in which no host is specified. To make a successful connection without specifying a host, you must use a configuration file in which the Host keyword appears outside of a host stanza.

The following example sets the default user name to `joe', and changes the user name to `guy' for connections to samplehost.

.*:

user=joe

samplehost:

user=guy

KEYWORDS

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 `no'.

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-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 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'.

FipsMode

Specifies whether all connections will be made using security protocols and algorithms that meet FIPS 140-2 standards. 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 `yes'.

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.

HostKeyAlias

Specifies an alias to use instead of the real host name when a host key is saved to the client's directory of known host keys. Host keys are stored using this naming format: key_port_host,IP.pub. The value you specify replaces the host portion of the stored host key name. This option is useful for tunneling Secure Shell connections, or when multiple servers are running on a single host.

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'.

KEXs

Specifies which key exchange algorithms the client supports. Supported values are `diffie-hellman-group1-sha1' and `diffie-hellman-group14-sha1'. Multiple algorithms can be specified as a comma-separated list. The default value is `diffie-hellman-group14-sha1,diffie-hellman-group1-sha1'.

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 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 on the ssh command line using the -m option. The default is `AnyStdMac'.

NoHostAuthenticationForLocalHost

This option disables host authentication when the client connects to localhost. It is useful when the home directory is shared across computers. In this situation localhost will refer to a different host on each of the computers, and the client user will get many warnings about changed host keys. Setting this to `yes' disables authentication for localhost so the user won't see these warnings. The allowed values are `yes' and `no'. The default is `no'.

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.

RelaySignals

Specifies which signals the client should relay to the server. RelaySignals accepts a comma-separated list of any of the following signals: ABRT, ALRM, FPE, HUP, ILL, INT, PIPE, QUIT, SEGV, TERM, USR1, USR2. The signals KILL and STOP cannot be caught, blocked, or ignored, so these signals are not supported. No signals are relayed by default.

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, and ServerAliveCountMax 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. The user's .ssh2 directory must be accessible only to the user (mode 700), the identification file must be writable only by the user (for example, mode 644), and the private keys listed in the identification file must be accessible only to the user (mode 400 or 600). When set to `no', the private key restrictions are still enforced, but not those of the .ssh2 directory. 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. The 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.

FILES

$HOME/.ssh2/ssh2_config

User-specific configuration file. The format is the same as the system-wide configuration file.

/etc/ssh2/ssh2_config

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).

$HOME/.ssh2/hostkeys/key_*.pub

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:

key_port_host,IP.pub

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.

/etc/ssh2/hostkeys/key_*.pub

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.

$HOME/.ssh2/identification

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:

IdKey <keyname>

For example:

IdKey id_dsa_2048_a