Documentation

6.4. SFTP

An sftp location provides access to an SFTP (version 3) server over SSH (version 2). This does not include access over SCP.

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 accepted key exchanges, HMACs and cipher names.

  • all

  • secure

  • fips

From version

3.11.0

To version

None

Description

The full name for each key exchange, HMAC or cipher should be used as comma-separated values.

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

The configuration must include at least one algorithm from each of:

  • ciphers

  • HMACs

  • key exchanges

For example, to only allow AES256 in CTR mode with SHA1 HMAC hash and Diffie-hellman group 14 key exchange with sha256 algorithms, the configuration will be:

ssh_cipher_list = aes256-ctr, hmac-sha1, diffie-hellman-group14-sha256

The special keyword secure contains all the algorithms that we currently consider secure. Should this list of algorithms be updated to exclude any new ciphers that have been considered weak, SFTPPlus will need to be upgraded to the version that contains the updated secure list of algorithms.

The keyword all is available for configuring all the supported algorithms. This is provided mainly to help with backward compatibility and will also enable weak ciphers.

Warning

Configuring all ciphers will also enabled ciphers which are 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 will fail 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.