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.
Items in this list configure features which affect the Secure Shell connection. Additional keywords are available for configuring terminal emulation for ssh command line sessions. Reference information about these keywords is available in Configuration File Keyword Reference - Terminal Emulation Settings.
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.
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
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.
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.
This keyword does not disable queries for user input when keyboard interactive authentication is configured, but connections that use keyboard interactive will fail when BatchMode is enabled.
Specifies the interface to transmit from on computers with multiple interfaces or aliased addresses.
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.
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.
Specifies the ciphers allowed for protocol version 2 in order of preference. Multiple ciphers must be comma-separated. The default is 'aes128-ctr,aes128-cbc,aes192-ctr,aes192-cbc,aes256-ctr,aes256-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128,arcfour256,arcfour'.
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.
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.
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.
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.
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.
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.
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.
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).
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.
This setting affects the SSH configuration scheme specified by the Host keyword, and has no effect on subsequent Secure Shell sessions unless they are configured to use the same SSH configuration scheme (or host name).
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.
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.)
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.
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.
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.
Enclose the filename in quotation marks if any part of the path or filename includes spaces.
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.
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.
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.
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.)
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.
When you close the Secure Shell Settings dialog box, values with default settings are not saved to the configuration file. If a default value has been manually added to the file, it is removed when you close the dialog box. This imposes design constraints if you use wildcard host stanzas in combination with stanzas that use specific host names.
If you have manually configured a default value in a specific host stanza that is meant to override a value configured in a wildcard stanza, the default setting is removed when you open the Secure Shell settings dialog box to view settings for the host-specific SSH configuration scheme. You can successfully handle this situation by using the global configuration file, which is not updated when users open and close the Secure Shell Settings dialog box.
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,firstname.lastname@example.org,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,email@example.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
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.
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.
Enclose the full path name in quotation marks if it includes spaces.
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.
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:
For information about setting these parameters, refer to Microsoft Knowledge Base Article 120642.
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-group1-sha1', 'diffie-hellman-group-exchange-sha1' and 'diffie-hellman-group14-sha1'. The default is 'ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521,diffie-hellman-group1-sha1,diffie-hellman-group-exchange-sha1,diffie-hellman-group14-sha1'.
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:
|A local port number.
|A remote host and a port on that host. (You can specify
localhost to forward data to a different port on the same remote host to which you have already established a Secure Shell connection.) IPv6 addresses can be specified with an alternative syntax:
1 if you are tunneling FTP file transfer.
1 if you are tunneling a Remote Desktop session.
|Specify an executable file (including complete path information, if required) to have the client launch an application immediately after the Secure Shell connection is established. To forward data through the secure tunnel, this application should be configured to make a connection to localhost (or the loopback IP address,
127.0.0.1) using the specified localport.
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
Enclose the path filename in quotation marks if any part of the path or filename includes spaces.
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.
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-sha256, hmac-sha2-256, hmac-sha1, hmac-md5, hmac-ripemd160, hmac-sha1-96, hmac-md5-96, hmac-sha512, hmac-sha2-512."
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.
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.
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"
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.
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.
This option affects connections made with the command line utility; it is not intended for use with the user interface.
Specifies the number of password prompts before giving up. The argument to this keyword must be an integer. The default is 3.
Specifies whether to use password authentication. The allowed values are yes and no. The default is yes.
Specifies the port number to connect on the remote host. The default is 22.
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'.
- If you include PreferredAuthentications in your config file, the list you specify must include every authentication method you want to try. If PreferredAuthentications is present, but does not specify a particular authentication method, the client will not use that authentication method, even if the keyword for enabling that authentication method is correctly configured.
- Including an authentication method in the PreferredAuthentications list does not enable authentication using that method. To enable an authentication method that is not used by default, the keyword for that authentication method must also be correctly configured (for example, to enable GSSAPI authentication, you must set GssapiAuthentication to yes.)
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.
The Secure Shell Client supports protocol 2, which is identified as the value 2.
Specifies a proxy type to use for Secure Shell connections. Supported values are "SOCKS" and "HTTP".
Proxy use is enabled for each Host section in the configuration file using this setting. The proxy server address is stored in the Windows registry on a per-user basis.
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,firstname.lastname@example.org,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
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.
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:
ls ; ls -l
dir/w & dir
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.
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.
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.
The Secure Shell ServerAlive setting is not related to the TCP keep alive setting (KeepAlive) that can be set in the Windows registry to keep all TCP/IP connections from being timed out by a firewall. To change the TCP/IP keep alive behavior, you need to edit the Windows registry.
Specifies the interval (in seconds) to use when ServerAlive = yes. Use an integer value of one or greater. The default is 30.
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'.
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'.
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.
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.
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.
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.
This setting has no effect when the host has been configured to authenticate using x509 certificates. If a host presents a certificate for host authentication and you do not have the required CA certificate configured as a trust anchor, the connection will fail.
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.
Specifies the user to log in as. This can be useful when a different user name is used on different machines.
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.
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.
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.
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.
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).
Determines the port on the PC's local loopback interface to which X11 protocol communications are forwarded when X11 forwarding in enabled.
If you are using Reflection X (version 12.x, 13.x, or 14.x), you don't need to configure this keyword. The Reflection X server and Secure Shell client automatically synchronize to use the correct port based on your X server display setting ( Settings > Display > X display number); in this case the X11Display keyword is ignored. If you use a different PC X server, use this keyword to specify the correct listening port as defined for your PC X server.
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.