Configuration File Keyword Reference - Secure Shell Settings

Use this reference if you manually edit your Secure Shell configuration file. The configuration file is organized into sections, each identified by a Host keyword. Each section specifies Secure Shell settings to be used for all connections made using the specified host or SSH configuration scheme.

The configuration file consists of keywords followed by values. Configuration options may be separated by white space or by optional white space and exactly one equal sign (=). Keywords are case-insensitive and arguments are case-sensitive.

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

AddAuthKeyToAgent

This setting affects how the client handles public key authentication when ForwardAgent is set to 'yes.' When public key authentication to the server is successful, and both ForwardAgent and AddAuthKeyToAgent are set to yes, the key or certificate that was used for authentication is automatically added to the Key Agent. This key is not saved in the Key Agent, but remains available as long as the Key Agent is running. When AddAuthKeyToAgent is set to no (the default), keys and certificates are not automatically added to the Key Agent; it uses only those keys that have already been manually imported.

AgentEnumCertsAs

This setting allows the client to choose what it will use. When both is selected, the enumeration offers up both the certificate and the key as separate options. When certs are selected, the signing is requested using only the certificate. When keys is selected, a signing is requested using a key that was contained in a certificate, the agent now utilizes only the key. The order in which it is offered is set based on the initial connection. For example, if I connect using only a key, agent forwarding will enumerate the key, and then the certificate.

These values have been optimized to server types based on their currently supported algorithms and key types. Available optimization values= sunssh, openvms, openssh, pkix and rsit

AuthUseAllKeys

This setting affects how the client handles public key authentication. When set to no (the default), the client attempts to authenticate using only the key (or keys) you have specified using the IdentityFile keyword. When set to yes the client attempts to authenticate using all available public keys.

BatchMode

Specifies whether or not to disable all queries for user input, including password and passphrase prompts, which is useful for scripts and batch jobs. The allowed values are yes and no. The default is no.

BindAddress

Specifies the interface to transmit from on computers with multiple interfaces or aliased addresses.

CheckHostIP

If this flag is set to yes, the Secure Shell Client checks the host IP address in the known_hosts file in addition to checking the host public key. The connection is allowed only if the host IP in the known hosts lists matches the IP address you are using for the connection. The default is no. Note: This setting has no effect if StrictHostKeyChecking = no.

CheckHostPort

If this flag is set to yes, the Secure Shell Client checks the host port in the known_hosts file in addition to checking the host public key. The connection is allowed only if the host port in the known hosts lists matches the port you are using for the connection. The default is no. Note: This setting has no effect if StrictHostKeyChecking = no.

Ciphers

Specifies the ciphers allowed for protocol version 2 in order of preference. Multiple ciphers must be comma-separated. The default is 'aes256-gcm@openssh.com,aes128-gcm@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr,aes256-cbc,aes192-cbc,aes128-cbc,3des-cbc'.

ClearAllForwardings

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

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.

ConnectionAttempts

Specifies the number of tries (one per second) to make before exiting. The argument must be an integer. This may be useful in scripts if the connection sometimes fails. The default is 1.

ConnectionReuse

Specifies whether multiple sessions to the same host reuse the original Secure Shell connection, and, therefore don't require re-authentication. The argument must be yes or no. When set to yes new connections reuse the existing tunnel when the host name, user name, and SSH configuration scheme (if used) all match. 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). The default is yes for connections made using the the client window to make your connections. It is no if you are using the command line utilities to make your connections. For details, see Connection Reuse in Secure Shell Sessions.

ConnectTimeout

Specifies the maximum time (in seconds) that the client waits when trying to complete the connection to the server. The timer starts when the connection is established (before logon) and runs during the negotiation of settings, host key exchange, and authentication. For all practical purposes, the timed period is basically the authentication activities. The default is 120.

DisableCRL

Specifies whether CRL (Certificate Revocation List) checking occurs when validating host certificates. Setting this to yes disables Certificate Revocation List checking. The default value of this setting is based on your current system setting for CRL checking. To view and edit the system settings, launch the Internet Options dialog box from the start menu, and navigate to the Advanced tab. Under the Security section, disable the Check for server certificate revocation setting.

DynamicForward

Specifies that a TCP/IP port on the local machine be forwarded over the secure channel, and the application protocol is then used to determine where to connect to from the remote machine. The argument must be a port number. Currently the SOCKS4 protocol is supported, and the client Secure Shell will act as a SOCKS4 server. Multiple forwardings may be specified, and additional forwardings can be given on the command line. Only a user with administrative privileges can forward privileged ports.

EscapeChar

Sets the escape character (default: ~). The escape character can also be set on the command line. The argument must be a single character, ^ followed by a letter, or none to disable the escape character entirely (making the connection transparent for binary data).

FipsMode

When set to yes, connections must be made using security protocols and algorithms that meet United States government's Federal Information Processing Standard (FIPS) 140-2. Options that don't meet these standards are not available from the Encryption section.

ForwardAgent

Setting this to yes enables forwarding of the Key Agent connection. Agent forwarding should be enabled with caution. Users with the ability to bypass file permissions on the remote host (for the agent's Unix-domain socket) can access the local agent through the forwarded connection. Attackers cannot obtain key material from the agent, however they can perform operations on the keys that enable them to authenticate using the identities loaded into the agent. This may need to be enabled on the server also. The default is no.

ForwardX11

Specifies whether X11 connections are automatically redirected over the secure channel and DISPLAY set. The argument must be yes or no. The default is no. (Note: If you configure Secure Shell using Reflection X, see ForwardX11ReflectionX.)

ForwardX11ReflectionX

This setting is used only if you are configuring Secure Shell connections for Reflection X (starting with 14.1). It specifies whether X11 connections are automatically redirected over the secure channel and DISPLAY set. The argument must be yes or no. The default is yes.

GatewayPorts

Specifies whether remote hosts are allowed to connect to local forwarded ports. By default, the client Secure Shell binds local port forwardings to the loopback address. This prevents other remote hosts from connecting to forwarded ports. GatewayPorts can be used to specify that the client Secure Shell should bind local port forwardings to the wildcard address, thus allowing remote hosts to connect to forwarded ports. Be careful about enabling this setting. Using it can reduce the security of your network and connection because it can allow remote hosts to use the forwarded port on your system without authenticating. The argument must be yes or no. The default is no.

GlobalKnownHostsFile

Specifies a file to use for the global host key database instead of the default file named ssh_known_hosts located in the Windows common application data folder.

GssapiAuthentication

Specifies whether GSSAPI authentication is used to authenticate to a KDC. This setting is applicable only if the protocol being used is protocol version 2.

GssapiDelegateCredentials

Specifies whether GSSAPI is used to forward your ticket granting ticket (krbtgt) to the host. This setting is applicable only if the protocol being used is protocol version 2.

GssapiUseSSPI

Specifies whether Microsoft's Security Support Provider Interface (SSPI) is used for GSSAPI authentication. This setting is applicable only if GSSAPI authentication is enabled (using GssapiAuthentication for protocol version 2). The argument to this keyword must be yes or no. When set to no the Secure Shell Client uses GSSAPI authentication. When set to yes the Secure Shell Client uses your Windows domain login credentials (SSPI) to authenticate to the Secure Shell server. SSPI is supported for protocol version 2 connections only, and the server must support the GSSAPI-with-mic authentication method. The default is yes.

GssServicePrincipal

Specifies a non-default service principal name to use when the client sends a request for a service ticket to the Key Distribution Center (KDC). If you have selected SSPI for your GSSAPI provider, you can use this setting to specify a service principal in a realm that is different from the Windows domain. Use a fully qualified host name followed by @ then the realm name, for example myhost.myrealm.com@MYREALM.COM. (By default the hostname value is the name of the Secure Shell server to which you are connecting and the realm depends upon the value of GssapiUseSSPI. When GssapiUseSSPI is no the realm name is specified in your default principal profile. When GssapiUseSSPI is yes, the realm is your Windows domain name.)

Host

Identifies the declarations that follow (up to the next Host key word) as belonging to the specified SSH configuration scheme. The characters '' and '?' can be used as wildcards. A single '' as a pattern can be used to provide global defaults for all hosts. A the client connection will use the first occurrence of any matching Host string (including wildcard characters). Any subsequent matches will be ignored.

HostKeyAlgorithms

Specifies, in order of preference, the host key algorithms that the client uses. The default for this option is: x509v3-ecdsa-sha2-nistp256,x509v3-ecdsa-sha2-nistp384,x509v3-rsa2048-sha256,x509v3-sign-rsa,x509v3-ssh-rsa,x509v3-sign-dss, ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,rsa-sha2-256, 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. SSH protocol allows only one attempt to authenticate the host. (This is different from user authentication in which multiple authentication methods and attempts are supported.) If the host presents a certificate, and the client is not configured for host authentication using certificates, the connection fails when x509 algorithms are preferred. In this situation you can configure the client to prefer SSH keys over certificates by changing the order of preference to ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,rsa-sha2-256,ssh-rsa-sha2-256@attachmate.com,ssh-rsa,ssh-dss,x509v3-ecdsa-sha2-nistp256,x509v3-ecdsa-sha2-nistp384,x509v3-rsa2048-sha256,x509v3-sign-rsa,x509v3-ssh-rsa,x509v3-sign-dss.

Available Values: ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,rsa-sha2-512,rsa-sha2-256,ssh-rsa-sha2-256@attachmate.com,ssh-rsa,ssh-dss,x509v3-ecdsa-sha2-nistp256,x509v3-ecdsa-sha2-nistp384,x509v3-ecdsa-sha2-nistp521,x509v3-rsa2048-sha256,x509v3-sign-rsa,x509v3-ssh-rsa,x509v3-sign-dss

HostKeyAlias

Specifies an alias to be used instead of the real host name for looking up or saving the host key in the host key database files. This option is useful for tunneling ssh connections or for multiple servers running on a single host.

IdentityFile

Specifies a private key to use for key authentication. Files are located in the user .ssh folder. ( \Users*username\Documents\Micro Focus*product-name.ssh\ ). IdentityFile items are added when you select keys or certificates from the list in the User Keys tab of the Secure Shell settings dialog box. It is possible to have multiple identity files specified in configuration files; all these identities will be tried in sequence.

KbdInteractiveAuthentication

Specifies whether to use keyboard interactive authentication. The allowed values are yes and no. The default is yes. This authentication method is recommended if you are using SecurID, PAM authentication, or any other external authentication method that requires prompts from the server and responses from the user. It may also work better than the PasswordAuthentication method for password authentication on hosts where password expiration or first login password changing is enabled. It may also be required for password authentication when expired passwords need to be reset in order to successfully authenticate. This applies to SSH protocol 2 only.

KeepAlive

Specifies whether the system should send TCP keepalive messages to the other side. If they are sent, death of the connection or crash of one of the machines will be detected. The default is yes (to send keepalives), so that the client will detect that the network goes down or the remote host dies. This is important in scripts and helpful to users. However, this means that connections will die if the route is down temporarily, which some users find annoying. To disable keepalives, set the value to no. This keyword enables the Windows TCP keep alive setting, which sends keep alive messages every two hours by default. TCP/IP keep alive is configurable using two optional pentameters that typically do not exist in the Windows registry: KeepAliveTime and KeepAliveInterval. These are configured in the HKEY_LOCAL_MACHINE registry subtree, in the following location:

SYSTEM\CurrentControlSet\Services\Tcpip\Parameters

For information about setting these parameters, refer to Microsoft Knowledge Base Article 120642.

KexAlgorithms

Specifies which key exchange algorithms the client supports, and the order of preference. The supported values are ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group18-sha512, diffie-hellman-group16-sha512, diffie-hellman-group14-sha256, diffie-hellman-group-exchange-sha256, diffie-hellman-group-exchange-sha1, diffie-hellman-group14-sha1, diffie-hellman-group1-sha1.

LocalForward

Specifies that a TCP/IP port on the local machine be forwarded over the secure channel to the specified host and port on the remote machine. Multiple forwardings can be specified. Only users with administrator privileges can forward privileged ports. You can also configure optional arguments for forwarding FTP, configuring remote desktop, and automatically launching an executable file (*.exe) after the connection is made. The syntax for this keyword is:

LocalForward` localport host: hostport [FTP=0|1] [RDP=0|1] ["ExecutableFile" [args]]

The options are:

Logfile

Specifies a log file to use for debugging. All session input and output is written to this file. Use this keyword with the -o command-line utility option as shown here:

-o Logfile=\ path\ logfile_name

LogLevel

Specifies the verbosity level that is used when logging messages from the Secure Shell Client. The possible values are: QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2 and DEBUG3. The default is INFO. DEBUG and DEBUG1 are equivalent. DEBUG2 and DEBUG3 each specify higher levels of verbose output.

Macs

Specifies the MAC (message authentication code) algorithms in order of preference. The MAC algorithm is used in protocol version 2 for data integrity protection. Multiple algorithms must be comma-separated. The default is: "hmac-sha2-512, hmac-sha512, hmac-sha2-256, hmac-sha256, hmac-sha1."

MatchHostName

Specifies whether host name matching is required when validating host certificates. When this setting is yes (the default), the host name you configure for your connection must exactly match a host name entered in either the CommonName or the SubjectAltName fields of the certificate.

Multihop

Configures multi-hop connections, which can be used to establish secure connections through a series of SSH servers. This is useful if your network configuration doesn't allow direct access to a remote server, but does allow access via intermediate servers.

The syntax for this keyword is:

Multihop localport host: hostport ["SSH config scheme"]

Add a new Multihop line for each server in the series. Each connection on the list is sent through the tunnel established by the connection above it.

In the example below, SSH connections configured to ServerC will connect first to ServerA, then to ServerB, and finally to the ServerC.

Host ServerC
Multihop 2022 ServerA:22
Multihop 3022 ServerB:22

You can optionally specify an SSH configuration scheme to configure Secure Shell settings for any host in the chain. For example:

Multihop 4022 joe@ServerA:22 "Multihop SchemeA"

Nodelay

This setting addresses a change made by Microsoft that enables the Nagle algorithm on Windows tcp sockets by default, and can adversely affect performance in Secure Shell connections. Setting Nodelay to yes (the default) disables this algorithm and improves performance on most systems.

NoShell

When NoShell is set to Yes, the client creates a tunnel without opening a terminal session. This option can be used in combination with ConnectionReuse to create a tunnel that can be reused by other ssh connections.

NumberOfPasswordPrompts

Specifies the number of password prompts before giving up. The argument to this keyword must be an integer. The default is 3.

PasswordAuthentication

Specifies whether to use password authentication. The allowed values are yes and no. The default is yes.

Port

Specifies the port number to connect on the remote host. The default is 22.

PreferredAuthentications

Specifies the order in which the client should try protocol 2 authentication methods. This corresponds to the order (top to bottom) in which the methods are displayed in the User Authentication list on the General tab of the Secure Shell Settings dialog box. This setting enables the client to prefer one method (such as keyboard-interactive) over another method (such as password). By default, the client attempts authentication in the following order: 'publickey,keyboard-interactive,password'. If GSSAPI authentication is enabled, the default changes to: 'gssapi-with-mic,external-keyex,gssapi,publickey,keyboard-interactive,password'.

PreserveTimestamps

Specifies whether file attributes and timestamps are modified when files are transferred to and from the server. When this keyword is no (the default), timestamps and attributes are modified. When it is yes, the files retain their original timestamps and attributes.

Protocol

The Secure Shell Client supports protocol 2, which is identified as the value 2.

Proxy

Specifies a proxy type to use for Secure Shell connections. Supported values are "SOCKS" and "HTTP".

PubkeyAlgorithms

Specifies in order of preference the key algorithms the client will propose to the server. If the server is only configured for one algorithm you can set this keyword to only propose that option.

Available values: ecdsa-sha2-nistp256,ecdsa-sha2-nistp384,ecdsa-sha2-nistp521,rsa-sha2-512,rsa-sha2-256,ssh-rsa-sha2-256@attachmate.com,ssh-rsa,ssh-dss,x509v3-ecdsa-sha2-nistp256,x509v3-ecdsa-sha2-nistp384,x509v3-ecdsa-sha2-nistp521x509v3-rsa2048-sha256,x509v3-sign-rsa,x509v3-ssh-rsa,x509v3-sign-dss

PubkeyAuthentication

Specifies whether to try public key authentication. This option applies to protocol version 2. The allowed values are yes and no. The default is yes.

RemoteCommand

Specifies one or more commands to run on the remote server. Use a semicolon (;) to separate multiple commands when connecting to a UNIX server. Use an ampersand (&) to separate commands when connecting to a Windows server. After a connection is established the server executes (or attempts to execute) the specified command(s), and then the session terminates. The server must be configured to allow commands received from the client to run.

The commands must be specified using the correct syntax for your server. For example, the following are equivalent:

On UNIX: ls ; ls -l

On Windows: dir/w & dir

RemoteForward

Specifies that a TCP/IP port on the remote machine be forwarded over the secure channel to the specified host and port from the local machine. The first argument must be a port number, and the second must be host : port. IPv6 addresses can be specified with an alternative syntax: host / port. Multiple forwardings may be specified. Only the users with administrator privileges can forward privileged ports.

SendEnv

Specifies an environment variable to set on the server before executing a shell or a command. The value should be of form: VAR val. The server must support the specified variable, and must be configured to accept these environment variables.

ServerAlive

Specifies whether to send server alive messages to the SSH server at the interval specified by ServerAliveInterval. The Secure Shell ServerAlive setting sends an SSH protocol message to the server at the specified interval to ensure that the server is still functioning. If this is setting is not enabled, the SSH connection will not terminate if the server dies or the network connection is lost. This setting can also be used to keep connections that only forward TCP sessions from being timed out by the server, as the server may timeout these connections because it detects no SSH traffic. The allowed values are yes and no. The default is no.

ServerAliveInterval

Specifies the interval (in seconds) to use when ServerAlive = yes. Use an integer value of one or greater. The default is 30.

ServerKeyFormat

Specifies the key format to use when uploading keys to a Host using the Upload feature on the User Keys tab. The utility automatically determines which the key format to use. Modify this setting if that format is incorrect for your server. The allowed values are 'OpenSSH' and 'SECSH'.

ServerStyle

Specifies the host public key configuration settings to use when uploading keys to a Host using the Upload feature on the User Keys tab. The utility automatically determines which host style to use. Modify this setting if that format is incorrect for your server. The allowed values are 'UNIX' and 'VMS'.

SftpBufferLen

Specifies the number of bytes requested in each packet during SFTP transfers. The default is 32768. Adjusting this value can improve transfer speed. The optimum value depends on your network and server setup. Changing this value may also affect how quickly you can cancel a transfer.

SftpMaxRequests

Specifies the maximum number of outstanding data requests that the client will allow during SFTP transfers. The default is 10. Adjusting this value can improve transfer speed. The optimum value depends on your network and server setup. Changing this value may also affect how quickly you can cancel a transfer.

SftpVersion

Specifies which version the client uses for SFTP connections. Valid values are 3 and 4. When this setting is 4 (the default), the connection uses SFTP version 4 if the server supports it, and drops to version 3 if the server doesn't support version 4. If this setting is 3, the client always uses SFTP version 3.

StrictHostKeyChecking

The argument must be yes, no or 'ask'. The default is 'ask'. If this option is set to yes, the Secure Shell Client never automatically adds host keys to the known_hosts file (located in the user .ssh folder), and refuses to connect to hosts whose host key has changed. This option forces the user to manually add all new hosts. If this flag is set to no, the client connects to the host without displaying a confirmation dialog box, and does not add the host key to the list of trusted keys. If this flag is set to ask, new host keys are added to the user known host files only after the user has confirmed that is what they want. The host keys of known hosts are verified automatically in all cases.

TryEmptyPassword

If this flag is set to yes , the client starts the password authentication by trying to enter an empty password. Note that this will count as a login attempt on most systems.

User

Specifies the user to log in as. This can be useful when a different user name is used on different machines.

UseOCSP

Specifies whether the client uses OCSP (Online Certificate Status Protocol) to validate host certificates. The allowed values are yes and no. The default is no.

UserKeyCertLast

Specifies how the client handles the signature for certificates during public key authentication. When this setting is 'yes' (the default), the client sends the certificate using a standard ssh key signature first. If that fails, the client tries again using a certificate signature. In some cases this second attempt may not occur and authentication fails. When this setting is 'no', the client tries the certificate signature first followed by the ssh key signature.

UserKnownHostsFile

Specifies a file to use for the user host key database instead of the known_hosts file (located in the user .ssh folder). Use quotation marks if the file or path includes spaces.

x509dsasigtype

Specifies the hash algorithm the client uses in the process of proving possession of DSA private keys. Possible values are sha1raw (the default) and sha1asn1.

x509rsasigtype

Specifies the hash algorithm the client uses in the process of proving possession of RSA private keys. Possible values are md5, sha1, and sha256 and all (the default).

X11Display

Determines the port on the PC's local loopback interface to which X11 protocol communications are forwarded when X11 forwarding in enabled.

The default value is 0. This configures forwarding to port 6000, which is the default listening port defined by X11 protocol convention. The display value you specify is added to 6000 to determine the actual listening port. For example, setting X11Display to 20 indicates to the Secure Shell client that the PC-X server is listening on port 6020.

More Information

• Configuration File Keyword Reference - Terminal Emulation Settings