6.4.1. Introduction¶

As the connection is done in non-interactive mode, the identity of the remote SSH server needs to be verified, so that credentials are not sent to an untrusted remote SSH server.

To validate the remote SSH server, the fingerprint of its public key is stored as a hexadecimal string in the ssh_server_identity option.

An SSH server can authenticate users using either a password or an SSH key.

6.4.2. name¶

Default value:

Empty

Optional:

No

From version:

2.8.0

Values:

• Any text.

Description:

Human-readable short text used to identify this location.

6.4.3. description¶

Default value:

Empty

Optional:

Yes

From version:

2.8.0

Values:

• Any text.

Description:

Human-readable text that describes the purpose of this location.

6.4.4. type¶

Default value:

''

Optional:

No

From version:

2.6.0

Values:

• filesystem - Local file system.

• sftp - SFTP protocol v3 over SSH v2.

• ftp - FTP protocol without any encryption.

• ftpse - Explicit FTPS protocol.

• ftpsi - Implicit FTPS protocol.

• webdavs - WebDAV over HTTPS.

• as2 - AS2 over HTTP or HTTPS

• azure-file - Azure File Service.

• smb - SMB / Windows Share

Description:

This option specifies the type of the location. Each type has a set of specific configuration options

6.4.5. idle_connection_timeout¶

Default value:

300

Optional:

Yes

From version:

3.0.0

Values:

• Number of seconds

• 0

Description:

This controls the automatic disconnection from the remote server after the location has not received any file transfer operation requests for the configured number of seconds.

Keep-alive command requests are not counted as file transfer operations. The connection gets automatically disconnected if keep-alive is the only command requested in the configured interval.

Disconnected locations automatically reconnect when a new file transfer operation request is made. For example, when a new file needs to be transferred to the remote server.

If the remote peer closes the connection before the configured timeout, the connection is left closed. It gets automatically reconnected when a new file transfer operation is requested.

Set to 0 to always keep the connection active, by forcing re-connection when the remote server closes the connection.

Note

The idle_connection_timeout is the maximum number of seconds before closing an idle connection to the server. If the remote server decides that the connection is idle and closes the connection, SFTPPlus doesn't try to "challenge" the server, leaving the connection closed. The connection is automatically reopened next time a file needs to be transferred.

6.4.6. idle_connection_keepalive_interval¶

Default value:

0

Optional:

Yes

From version:

3.0.0

Values:

• Number of seconds

Description:

Send a keep-alive command every N seconds to avoid having the connection disconnected by the other peer due to inactivity.

Set to 0 to disable keep-alive commands.

The keep-alive command does not reset the idle connection timeout,

6.4.7. connection_retry_count¶

Default value:

12

Optional:

Yes

From version:

3.9.0

Values:

• Number of retries

Description:

Number of times to retry connection to the location, when the initial connection fails.

Set to 0 to not retry.

6.4.8. connection_retry_interval¶

Default value:

300

Optional:

Yes

From version:

3.9.0

Values:

• Number of seconds

Description:

Number of seconds to wait between connection attempts.

Set to 0 to retry right away without any delay.

6.4.9. ssh_server_identity¶

Default value:

''

Optional:

No

Values:

• MD5 Hexadecimal, delimited by colons

• SHA1 Base64

• SHA256 Base64

• OpenSSH Public Key

• X.509 certificate

• Multiple identities on multiple lines.

• set-on-first-connection

From version:

3.51.0

Description:

This configuration defines the identity of the remote SSH server.

It can be defined as an MD5, SHA1, or SHA256 fingerprint.

You can also define it as an OpenSSH public key or an X.509 SSL/TLS certificate.

To automatically configure with the identity of the server found during the first connection, you can use the set-on-first-connection option. For security reasons, we do not recommend this option. This option is not available for cluster operations when the remote SFTP service has more than one SSH server identity.

When you are connecting to a remote SSH / SFTP service which is deployed as a cluster or as a disaster recovery failover it is possible that each node/server from the cluster to have its own identity. You will need to configure SFTPPlus with the identity of each server by defining multiple identities on separate lines.

This configuration is mandatory and critical for securing the SSH connection. When the server's key fingerprint cannot be verified, all connections are rejected.

6.4.10. address¶

Default value:

Empty

Optional:

No

Values:

• Host name or IP address of the SFTP server.

From version:

2.8.0

Description:

Address of the remote SSH server. IP or DNS name.

6.4.11. port¶

Default value:

Empty

Optional:

No

Values:

• Number, greater than 0.

From version:

2.8.0

Description:

Port number of the remote SSH server.

6.4.12. username¶

Default value:

Empty

Optional:

No

From version:

2.8.0

Values:

• Text.

Description:

Username used to authenticate to the remote SSH server.

6.4.13. password¶

Default value:

Empty

Optional:

Yes

From version:

2.8.0

Values:

• Plain text password.

• Empty.

Description:

This option specifies the password used to connect to the remote SSH server. It is provided in plain text. To disable password authentication, set this to an empty string.

When ssh_private_key is defined and configured to a private key which is stored in encrypted mode, this holds the password used to decrypt the private key.

6.4.14. ssh_private_key¶

Default value:

Empty

Optional:

Yes

From version:

3.0.0

Values:

• Absolute path on the local filesystem.

• Content of the SSH private key (Since 3.40.0).

• Empty.

Description:

SSH private key used to authenticate to the remote SSH server. Leave it empty to disable SSH key authentication.

It can be configured with a path on the local filesystem containing the content of the SSH key.

You can also define the content of the SSH key directly as a text value. In this case the configuration will look like the following example. It's important to start each line with at least one space character and keep the number of leading spaces constant:

[locations/b904e6h6-c295-4ccf-8abd-edcae4d3324f]
name = SFTP Acme Server
type = sftp
ssh_private_key = -----BEGIN RSA PRIVATE KEY-----
    Proc-Type: 4,ENCRYPTED
    DEK-Info: AES-128-CBC,ACD9A45C68DD1924FF2A1A54BE2A7BF4

    RAHH7yMbPk/vrhT5jkSDGIUdH+nG0OQpeSWcQXd4JJ6pqdJh/cw/havtxlHFp1yz
    ...
    MORE SSH KEY CONTENT
    ...
    Pkf+23OGZln2dLz/pkJkiRRzmsWgT2hUv/EK4NYRQq1kEAXLf3J6xZqLlR3ZBLJm
    -----END RSA PRIVATE KEY-----

We recommend to store the key in PEM OpenSSH format, but Putty or Tectia formats are also supported.

When the configured key is encrypted, the value configured in password is used to decrypt the key.

6.4.15. proxy¶

Default value:

Empty

Optional:

Yes

Values:

• URI like expression.

• socks5://12.342.421.2:8899

• Empty

From version:

3.31.0

Description:

This option configures a proxy to be used when making connection to the remote server.

When no port is defined, it will use port 1080.

Leave it empty to disable proxy usage.

For now, only the SOCKS5 without authentication is supported. The DNS resolution will be delegated to the SOCKS server.

6.4.16. ssh_cipher_list¶

Default value:

secure

Optional:

Yes

Values:

• List of SSH algorithm names.

• all

• secure

• fips

From version:

3.11.0

Description:

This is configured as a comma-separated list of full name for each host public key, key exchange, HMAC or cipher.

You can find all the names of the supported algorithms on SSH cryptography page.

For SFTP services the configuration must include at least one algorithm from each of:

• ciphers

• HMACs

• key exchanges

For SFTP service, the list of public keys is extracted from the SSH keys configured at ssh_host_private_keys.

For SFTP locations the configuration must include at least one algorithm from each of:

• public key

• ciphers

• HMACs

• key exchanges

For example, to only allow RSA host keys, AES256 in CTR mode with SHA256 HMAC hash and Diffie-Hellman group 14 key exchange with sha256 algorithms, the configuration is:

ssh_cipher_list = ssh-rsa, aes256-ctr, hmac-sha2-256, diffie-hellman-group14-sha256

The special keyword secure contains all the algorithms that we currently consider secure.

We recommend using the latest version of SFTPPlus, for automatic enforcement of any newly-deprecated ciphers via the secure list.

When we update this list of algorithms to exclude any newly-deprecated ciphers, your SFTPPlus installations automatically enforce our changes when upgraded to a version that contains the updated secure list of algorithms.

The keyword all is available for configuring all the supported algorithms, including weak ciphers. This is provided mainly to help with backward compatibility.

Warning

Configuring all ciphers also enables ciphers no longer considered secure by modern standards.

A pre-defined set of FIPS 140-2 approved ciphers is available by using the special fips keyword in this configuration. When FIPS 140-s ciphers are enabled, any other configured cipher in the list is ignored.

If an unsupported name is used, the component fails to start.

When the all keyword is used, all other values are ignored. When the secure keyword is used, all other values are ignored, including fips and explicit ciphers. When the fips keyword is used, any explicit cipher configuration is ignored.

Only one option from all, secure, or fips should be used at a single time.