13.3 Client Configuration Keywords

Specifies which address formats are supported by the client. The allowed values are 'any' (allow the system to decide which address family to use), 'inet' (accept only IPv4), and 'inet6' (prefer IPv6 but accept IPv4). The default is 'inet'. You can also configure address family preference using the -4 and -6 command line options.

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

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

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

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.

When this setting is 'yes' (the default), interrupted file transfer resumes at the point of interruption. When this setting is 'no' transfers always start over. Note: Checkpoint resume can also be disabled on the server using the SmartFileTransfer keyword.

Specifies one or more (comma-separated) encryption algorithms supported by the client.

The cipher used for a given session is the cipher highest in the client's order of preference 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'.

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.

Specifies the level of compression. You can specify compression values 0-9. Increasing the value increases the amount of compression. Using higher values results in the use of less network bandwidth, but at the cost of more CPU cycles. Level 6 is equivalent to 'yes'. Level 0 is equivalent to 'no'. The default is 'no' (0).

Note: Compression can be disabled on the ssh command line using the -C option, but can only be enabled using this keyword.

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.

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.

Specifies a default domain name. You can add this setting to your configuration file if you want to be able to enter a short host name on the command line, but send a fully qualified domain name to make the connection. If you have configured a value for DefaultDomain and you enter a host name that doesn't contain any "." (dot) characters, the DefaultDomain value is concatenated to the host name using a "." character. (Note: You can include an optional dot at the beginning of the DefaultDomain string; the first "." in this string is ignored.) Any alpha-numeric character is accepted as a value. For example, if DefaultDomain is set to either "acme.com" or ".acme.com", the command "ssh joe@myhost" is sent as "ssh joe@myhost.acme.com".

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

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.

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

Specifies which file types use ASCII transfer during sftp sessions when auto mode transfer is enabled. All other files use binary transfer. Specify a comma or space-separated list. Wildcard (zsh-glob) characters are supported. Don't precede file extensions with a period. To specify extensions containing spaces, use quotation marks around the extension or use a backslash as an escape character. The default is 'txt, htm*, pl, php*'. (You can use the setext during an sftp session to specify a different file list for that session. Use getext to display the current list.)

Note: This setting is only relevant when auto transfer is enabled. The transfer method is set to binary by default. To enable auto transfer, use the sftp command "auto". To display the current transfer mode, use "ascii -s".

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

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.

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

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'. When ForwardX11 is set to yes (the default), X11 forwarding is enabled only if the DISPLAY environment variable is set. If the DISPLAY variable is not set, the client will automatically disable X11 forwarding and will not set up the tunnel and authenticate. This helps minimize the risk of attacks using the X11 tunnel.

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.

Caution: This option should be used with extreme caution (and never with Internet-facing network adapters), because the client performs no authentication of remote host connections. If the application to which this connection is forwarded does not perform its own authentication, then all remote hosts connections are allowed unrestricted access to that application.

Use this keyword when you have configured port forwarding and you want the Secure Shell session to run in the background. The allowed values are 'yes', 'no', and 'oneshot'. The default is 'no'. If at least one port forwarding rule is configured, both 'yes' and 'oneshot' send the session to the background after authentication is complete. When you specify 'yes', the Secure Shell session remains in the background and continues to accept forward requests indefinitely until you manually kill the process. (This is equivalent to using -f on the ssh command line.) When you specify 'oneshot', the background session waits for only one forwarded connection to occur and exits as soon as the forwarded connection is closed. (This is equivalent to using -fo on the ssh command line.)

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

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.

This keyword is no longer supported. Use Reflection PKI Services Manager to configure trust anchors.

This keyword is no longer supported. Use Reflection PKI Services Manager to configure revocation checking.

Specifies whether server authentication using a certificate requires host name checking. When HostCertNameCheck is 'yes', authentication succeeds only if the host name or IP address specified for the connection is included in the allowed identity set for the certificate. (Use the PKI Services Manager map file to configure allowed identities.) When HostCertNameCheck is 'no', the client ignores the allowed identity set and accepts any valid certificate. When HostCertNameCheck is 'ask' (the default), the user receives a prompt when the server name is not an allowed identity, and is asked whether or not to continue.

Specifies, in order of preference, the host key algorithms proposed by the client. The default value is ‘x509v3-rsa2048-sha256’,’x509v3-sign-rsa’,’x509v3-ssh-rsa’,’x509v3-sign-dss’,’ecdsa-sha2-nistp256’,’ecdsa-sha2-nistp384’,’ssh-rsa-sha2-256@attachmate.com’,’ssh-rsa,ssh-dss’.

This setting is useful when the server is configured for both certificate and standard host key authentication. The default value presents x509 algorithms before regular SSH key algorithms. Secure Shell protocol allows only one attempt to authenticate the host. If the host presents a certificate, and the client is not configured for host authentication using certificates, the connection fails. (This is different from user authentication in which multiple authentication methods and attempts are supported.) In this situation you can configure the client to prefer SSH keys over certificates by changing the order of preference to `x509v3-ecdsa-sha2-nistp256', ‘x509v3-ecdsa-sha2-nistp384',‘x509v3-ecdsa-sha2-nistp521',‘x509v3-rsa2048-sha256', ‘x509v3-sign-rsa',‘x509v3-ssh-rsa',‘x509v3-sign-dss',‘ecdsa-sha2-nistp256',‘ecdsa-sha2-nistp384',‘ssh-rsa-sha2-256@attachmate.com',‘ssh-rsa,ssh-dss'.

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.

Specifies whether Reflection for Secure IT uses HPN dynamic TCP window features to enhance performance. When HPNDisabled = 'no' (the default), Reflection for Secure IT adjusts the TCP window and TCP receive buffers to optimize performance. When HPNDisabled is 'yes', the receive buffer is set to 64 KB.

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

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

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

Specifies which key exchange algorithms the client supports. Supported values are ‘ecdh-sha2-nistp256',‘ecdh-sha2-nistp384',‘ecdh-sha2-nistp52',’diffie-hellman-group-exchange-sha256', ‘diffie-hellman-group-exchange-sha1',‘diffie-hellman-group14-sha1',‘diffie-hellman-group1-sha1'. Multiple algorithms can be specified as a comma-separated list. The default value is `ecdh-sha2-nistp256',`ecdh-sha2-nistp384',`ecdh-sha2-nistp521',`diffie-hellman-group-exchange-sha256',`diffie-hellman-group-exchange-sha1',‘diffie-hellman-group14-sha1',‘diffie-hellman-group1-sha1'..

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

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

[protocol/][listening_host:] 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). (On client hosts with multiple interfaces, use listening_host to specify which interface.) 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. The optional protocol can be tcp or ftp.

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

In the following example, FTP communications sent from an FTP client (on the same computer as the Secure Shell client) are forwarded to an FTP server running on myhost.com. With this configuration, you would configure the FTP client to connect to localhost:2121.

LocalForward=ftp/2121:myhost.com:21

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

Sets the verbosity level used for ssh messages. Allowed values are 'fatal', 'error', 'quiet', 'info', 'verbose', 'debug1' ('debug' and 1 are equivalent), 'debug2' (2 is equivalent), 'debug3' (3 is equivalent), and 'trace' ('debug99' and 99 are equivalent). The syslog level associated with these values is CRIT for fatal, ERROR for error and quiet, INFO for info and verbose, and DEBUG for debug1, debug2, debug3, and trace. The default is 'info'.

Note: Setting logging to 'trace' can increase your security risk. At this level, information leakage is a concern, as unencrypted protocol information may be written out. Also, the volume of information written may fill up disk space rapidly, potentially causing the host or Reflection for Secure IT to stop responding.

Specifies, in order of preference, which MACs (message authentication codes) are supported by the client. Allowed values are 'hmac-sha256', 'hmac-sha1', 'hmac-sha1-96', 'hmac-md5', 'hmac-md5-96', 'hmac-sha512', and 'hmac-ripemd160'. Use 'AnyMac' to support all of these. Use 'AnyStdMac' to specify 'hmac-sha256, hmac-sha1,hmac-sha1-96,hmac-md5,hmac-md5-96, hmac-sha512'. Specifying hmac-sha256 also enables hmac-sha2-256. Specifying hmac-sha512 also enables hmac-sha2-512. Multiple MACs can also be specified as a comma-separated list. Additional options are 'none', 'any' (equivalent to AnyMac plus 'none'), and 'AnyStd' (equivalent to 'AnyStdMac' plus 'none'). 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'.

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

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.

Specifies the prompt to display for password authentication. Two variable options are supported: %r is replaced by the user name and %h is replaced by the host name. The default is "%r@%h's password:" (This setting has no effect on keyboard-interactive authentication.)

Specifies the port used to connect to PKI Services Manager. Use the format host:port. The default is localhost:18081. If you specify a host and omit the port, the default PKI Services Manager port (18081) is used.

Specifies the name and location of the public key used by to confirm the identity of Reflection PKI Services Manager. The default is /install-directory/config/pki_key.pub.

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.

Specifies the command to use to connect to the server. The command string extends to the end of the line, and is executed with the user's shell. Two variable options are supported in the command: '%h' is replaced by the host name and '%p' by the port. The command can be anything that reads from stdin and writes to stdout. The command should eventually connect to a Reflection for Secure IT server. You can use ProxyCommand in conjunction with a command such as nc (or netcat) that provides proxy support. For example, the following command uses nc to connect via an HTTP proxy at 198.168.2.1:

ProxyCommand /usr/bin/nc -X connect -x 198.168.2.1:8080 %h %p

The default is 'none', which disables this option. (This is equivalent to specifying an empty string).

Note: CheckHostIP, is not available for connections made with a proxy command.

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.

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.

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.

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.

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

[protocol/][listening_host:] 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). (On server hosts with multiple interfaces, use listening_host to specify which interface.) 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). The optional protocol can be tcp or ftp.

In the following example, FTP communications sent from an FTP client (on the same computer as the Secure Shell server) are forwarded to an FTP server (on the same computer as the Secure Shell client). With this configuration, you would configure the FTP client to connect to port 3333.

RemoteForward=ftp/3333:localhost:21

You can also configure remote port forwarding on the ssh command line using the -R option.

Specifies whether the client sends NOOP messages through the Secure Shell channel to the 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'.

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.

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.

Specifies an environment variable to set on the server before executing a shell or a command. The value should be in the form: VAR=val, where val can be empty. The argument must be uppercase.

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

Specifies the maximum SFTP protocol version supported by the client. Valid values are 3 and 4 (the default). If the server only supports an older version than what is specified in this setting, the version specified by the server is used.

Specifies whether Reflection for Secure IT checks for identical files before doing a file transfer. When this setting is 'yes' (the default), existing files are checked for equality and no data transfer takes place if the files are identical. When this setting is 'no', no check for equality is made and existing files are always overwritten. Note: Smart file copy can also be disabled on the server using the SmartFileTransfer keyword.

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 (~/.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 (~/.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 (~/.ssh2/hostkeys) and used to verify the host's identity in subsequent connections. The user never knows when an unknown host key is presented.

Specifies file and directory permissions required for public key authentication. The allowed values are 'yes' and 'no'. The default is 'yes'. When set to 'yes', the user directory (~/.ssh2/) and all parent directories must be writable and executable only by the user (mode 755 is accepted). Recommended permissions for the user directory = 700. The user identification file (~/.ssh2/identification by default) must be configured for user-only read/write access (600 is recommended, 644 is accepted). When set to 'no' these file permissions are not enforced and sensitive files and information could be compromised.

Note: Additional file permission restrictions are enforced for all private keys. Keys must be configured for user-only read access regardless of the current StrictModes setting. If access to the private key is not sufficiently restricted, public key authentication will always fail. Recommended permissions for private keys = 600.

Specifies the facility code used to log messages for ssh, sftp, and scp connections. The default is 'USER'. When this value is 'none', Reflection for Secure IT disables logging to syslog. Other valid values are platform-dependent. See syslog(3) and syslog.conf(5).

This keyword is no longer supported. Use Reflection PKI Services Manager to configure trust anchors.

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.

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.

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

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