SFTPPlus Documentation

Start Page 4. Configuration Instructions 4.17. Locations

4.17. Locations

4.17.1. Introduction

A location configuration provides the required information to allow the SFTPPlus to connect to local or remote locations in order to perform file transfers between locations.

Please consult the type configuration option to see the list of supported location types.

Location are auto-started when a transfer or another component needs them and the location is not started and connected.

They are also fault-tolerant allowing to retry failed connections.

All components/transfer trying to use a location which failed, will also have their operation failed and will not trigger a new connection attempt of the location.

4.17.2. Adding a new location via Local Manager

A new location can be added or changed via Local Manager below. Options will differ depending on which location type is used.

See below for an example of an initial configuration with the FTPES location.

../_images/gallery-add-ftps-location.png

4.17.3. Adding a new location via text configuration

Adding a new location configuration is done by creating a new section inside the configuration file. The name of the section should be prefixed with locations/ and followed by the location’s UUID.

The location’s UUID can be any unique string used to identify the location. Once defined, the UUID should not be changed.

For more information, please see the dedicated UUID documentation.

For example, to add a new location configuration of type filesystem called Local file system:

[locations/b904e6h6-c295-4ccf-8abd-edcae4d3324f]
name = Local file system
description = File system accesses as service account.
type = filesystem

4.17.4. Location options

Each location configuration section has the following configurations:

4.17.4.1. name

Default value:

‘’

Optional:

No

From version:

2.8.0

Values:
  • Any text.
Description:

Human-readable short text used to identify this location.

4.17.4.2. description

Default value:

‘’

Optional:

Yes

From version:

2.8.0

Values:
  • Any text.
Description:

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

4.17.4.3. 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.
  • azure-file - Azure File Service.
Description:

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

4.17.4.4. idle_connection_timeout

Default value:

300

Optional:

Yes

From version:

3.0.0

Values:
  • Number of seconds after which idle connections are disconnected.
  • 0 - To disable timeouts.
Description:

Disconnect the connection to the remote peer if the location has not received any requests for the configured number of seconds.

Keep-alive command requests are ignored, and the connection will be automatically disconnected if keep-alive is the only command requested in the configured interval.

Disconnected locations will automatically reconnect when a new request is made.

If the remote peer closed the connection before the local configured timeout, the connection is left closed, and it will be automatically recreated when a new command is requested.

Set to 0 to always keep the connection active, by forcing reconnection when the remote peer closes the connection.

4.17.4.5. 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,

4.17.4.6. connection_retry_count

Default value:

2

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.

4.17.4.7. connection_retry_interval

Default value:

60

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.

4.17.5. Local File System Location

A local file system location is accessed using the operating system’s file system.

For now, no extra configuration options are available for this location type.

Note

For the moment, local file system locations can’t be defined from the Local Manager GUI. There is a single default local filesystem which is available inside the GUI and which can not be removed.

4.17.6. SFTP Location

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

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_fingerprint option.

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

4.17.6.1. ssh_server_fingerprint

Default value:

‘’

Optional:

No

Values:
  • Hexadecimal string delimited by colons.
From version:

2.8.0

Description:

Hexadecimal string representation of the MD5 hash of the SSH (RSA/DSA) key used by the remote server.

When the server’s key fingerprint cannot be verified, all connections are aborted.

4.17.6.2. address

Default value:

‘’

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.

4.17.6.3. port

Default value:

‘’

Optional:

No

Values:
  • Number, greater than 0.
From version:

2.8.0

Description:

Port number of the remote SSH server.

4.17.6.4. username

Default value:

‘’

Optional:

No

From version:

2.8.0

Values:
  • Text.
Description:

Username used to authenticate to the remote SSH server.

4.17.6.5. password

Default value:

‘’

Optional:

Yes

From version:

2.8.0

Values:
  • Plain text password.
  • Disabled or 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.

4.17.6.6. ssh_private_key

Default value:

‘’

Optional:

Yes

From version:

3.0.0

Values:
  • Absolute path on the local filesystem.
  • Content of the SSH private key (Since 3.40.0).
  • Disabled or 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.

4.17.6.7. proxy

Default value:

‘’

Optional:

Yes

Values:
  • URI like expression.
  • socks5://12.342.421.2:8899
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.

4.17.6.8. ssh_cipher_list

Default value:

secure

Optional:

Yes

Values:
  • List of accepted key exchanges, HMACs and ciphers 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.

This will configure the symmetrical encryption, asymmetrical encryption, hash-based message authentication code, and key exchange algorithms.

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.

4.17.7. FTP Location

An ftp location provides access to an FTP server over the unencrypted mode.

Only username and password credentials are supported.

4.17.7.1. address

Default value:

‘’

Optional:

No

Values:
  • Host name or IP address of the FTP server.
From version:

3.0.0

Description:

Address of the FTP server. IP or host name.

4.17.7.2. port

Default value:

21

Optional:

Yes

Values:
  • Number, greater than 0.
From version:

3.0.0

Description:

Port number to connect to the FTP server.

4.17.7.3. username

Default value:

‘’

Optional:

No

From version:

3.0.0

Values:
  • Text.
Description:

Username used to authenticate to the FTP server.

4.17.7.4. password

Default value:

‘’

Optional:

Yes

From version:

3.0.0

Values:
  • Plain text password.
  • Disabled or empty.
Description:

This option specifies the password used to connect to the FTP server.

It is defined in plain text format and sent over the network in plain text without any transport protection.

4.17.8. Explicit FTPS Location

An explicit ftps location provides access to an Explicit FTPS server.

Note

The explicit FTPS location is an experimental feature.

4.17.8.1. address

Default value:

‘’

Optional:

No

Values:
  • Host name or IP address of the FTP server.
From version:

3.13.0

Description:

Address of the server. IP or host name.

In order to check the identity of the remote server the address should be provided as FQDN. IP addresses are not supported by the server identity validation process.

4.17.8.2. port

Default value:

21

Optional:

Yes

Values:
  • Number, greater than 0.
From version:

3.13.0

Description:

Port number to connect to the server.

4.17.8.3. username

Default value:

‘’

Optional:

No

From version:

3.13.0

Values:
  • Text.
Description:

Username used to authenticate to the server.

4.17.8.4. password

Default value:

‘’

Optional:

Yes

From version:

3.13.0

Values:
  • Plain text password.
  • Disabled or empty.
Description:

This option specifies the password used to connect to the server.

It is defined in plain text format and sent over the network protected by the TLS protocol.

4.17.8.5. ssl_domains

Default value:

Empty

Optional:

Yes

Values:
  • Fully qualified domain name (FQDN)
  • Empty
From version:

3.42.0 This configuration option defines the domain for which SFTPPlus will request certificates from the Let’s Encrypt server.

The same domain can be shared by multiple services.

The domain name is handled as a case-insensitive lower case value.

For this option to be used, you need to define a lets-encrypt resource.

4.17.8.6. ssl_certificate

Default value:

no-certificate-defined

Optional:

Yes

Values:
  • Absolute path on local filesystem.
  • Certificate as PEM text format (Since 3.40.0).
  • Disabled
From version:

1.6.0

To version:

None

Description:

This can be defined as an absolute path on the local filesystem to the SSL certificate file used by the component. File content should be encoded in the Privacy-Enhanced Mail (PEM) format.

Note

The path should not be longer than 256 characters.

You can also define the content of the certificate as text in PEM format. In this case the configuration will look as in the following example. It’s important to start each line with at least one space character and keep the number of leading spaces constant:

ssl_certificate = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When the value contains both the certificate and the key, the configuration will look as in the following example:

ssl_certificate = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

This certificate is sent to the remote peer during the SSL/TLS handshake process.

The certificate file can contain both the certificate and the private key, in which case you don’t need to set the path to the private key. Only supported for PEM encoding.

The certificate file can contain the certificate chain. The targeted certificate should be first in the file, followed by the chained certificates. It will advertise the certificate chain in the same order as listed in the file. Only supported for PEM encoding. (Since 3.22.0)

For server-side components using TLS/SSL secure communication, this configuration options is required.

For client-side component using TLS/SSL, you can disable sending the certificate as part of the handshake, by setting this configuration option to Disabled.

4.17.8.7. ssl_key

Default value:

Empty

Optional:

Yes

Values:
  • Absolute path on local filesystem.
  • Key as PEM text format (Since 3.40.0).
  • Empty
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to the X.509 private key file used by this component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) format.

Note

The path should not be longer than 256 characters.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_key = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----

If the value defined in ssl_certificate option already contains the private key, this option can be omitted by leaving it empty.

4.17.8.8. ssl_key_password

Default value:

Disabled

Optional:

Yes

Values:
  • Password as plain text.
  • Disabled
From version:

1.7.19

Description:

This is used to define the password of the private key, when the private X.509 key is stored as an encrypted file.

Set it to Disabled to not use a password for the private key file.

4.17.8.9. ssl_certificate_authority

Default value:

Disabled

Optional:

Yes

Values:
  • Absolute path on local filesystem.
  • Content of the CA chain (Since 3.40.0).
  • ${LETS_ENCRYPT_X3_CA}
  • ${MICROSOFT_IT_CA}
  • Disabled
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to a file containing the certificates to the Certificates Authority used to validate the remote peer.

You can also define the content of the CA as text in PEM format.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_certificate_authority = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When a certificate authority is define, this will result in initiating the two-way SSL/TLS authentication/handshake validation. For a successful connection, make sure the client sends a valid certificate. If the connection fails, the event with ID 40009 is emitted.

The certificate authority file should be stored as a file in PEM format. For multiple CA, place all certificates in the same file.

A series of bundle CA are distributed with SFTPPlus. They can be configured together and mixed with other CA certificates. The bundle CAs are available under the following names:

  • ${LETS_ENCRYPT_X3_CA} - For Let’s Encrypt X3 certificate authority.
  • ${MICROSOFT_IT_CA} - For all Microsoft IT CA certificates, used by SharePoint Online and other services provided by Microsoft.

To configure a component to accept peer certificates signed by Microsoft IT CA, which is the CA used by SharePoint Online, you can set the configuration as:

ssl_certificate_authority = ${MICROSOFT_IT_CRL}

Set as Disabled to disable checking the issuer for peer’s certificates. When certificate authority check is disabled, connection peers are not required to send a certificate and will result in a one-way SSL/TLS authentication. If the peer sends a certificate, it is ignored.

This defines the path on local filesystem to a file contain the certificate in PEM format for the single certificate authority or multiple authorities authorities with which this component will communicate.

Only peer connections using certificates signed by one of these certificate authorities will be permitted to communicate to this component.

When this component should communicate with peers holding certificates issued by multiple certificate authorities, put each CA certificate in PEM format inside a single file.

Leave it empty or set it as Disabled to disable checking the issuer of the peer’s certificates.

When certificate authority check is disabled, connection peers are not required to send a certificate. If the peer sends a certificate, it is ignored.

4.17.8.10. ssl_certificate_revocation_list

Default value:

Disabled

Optional:

Yes

Values:
  • Comma separated list of CRL paths or HTTP URLs.
  • crl-distribution-points
  • ${MICROSOFT_IT_CRL}
  • Disabled
From version:

1.6.0

Description:

It defines the locations from where one or more CRLs will be loaded.

Multiple CRLs are defined as a comma separated list.

It supports local files with absolute paths, in either of the following formats:

* ``file:///unix/absolute/test-ca.crl``
* ``file://c:\\windows\\absolute\\test-ca.crl``

Retrieving the CRL over HTTP is also supported. The HTTP request is done using non-persistent HTTP/1.1 connections. The URL will look as follows:

* ``http://example.com/some.crl``

CRL distribution points (CDP) are supported by using the crl-distribution-points configuration value.

When CRL distribution points are configured, the local certificate defined at ssl_certificate needs to have the CDP extension. The CDP advertised in the local certificate is loaded at startup in order to validate the configuration.

The distribution points configuration is mutually exclusive with local file or HTTP url configurations. When the certificate revocation list is configured to use CDP, all other configured CRL location are ignored.

Warning

HTTP redirection is not yet supported for CRL URLs. You have to configure the exact URL for the CRL.

Set it to Disabled, to disable certificate revocation checks.

The certificate revocation list can only be used when the component is configured with CA certificates stored in a single file in PEM format.

When multiple or chained CA certificates are configured the CRL is only checked for the peer’s certificate and not for the CA certificate or for an intermediate CA.

Warning

CDP publishing Delta CRL are not supported.

Note

If the certificate defines multiple HTTP based distribution points in the CDP extension, only the first HTTP URI is used. All non HTTP or the other HTTP URIs are ignored.

The CRL file should be stored in PEM or DER format.

Note

This option is ignored if ssl_certificate_authority is not enabled.

4.17.8.11. ssl_certificate_revocation_list_refresh

Default value:

0

Optional:

Yes

Values:
  • Number of seconds
  • 0
From version:

2.8.0

Description:

This defined the number of seconds after which a configured CRL is reloaded by this component.

When set to 0, the CRL file is initially loaded at startup and then loaded again after the Next Update field advertised in the CRL.

If the Next Publish extension is present in the CRL and this option is set to 0, the CRL will be loaded again at the date and time specified in the Next Publish extension.

If the CRL does not advertise the Next Update field you will have to configure a number of seconds after which the CRL should be reloaded, otherwise you will get a configuration error.

For example, a value of 86400 means that the CRL will be re-read after one day.

For more details about the CRL reloading see the documentation for CRL reloading rules

Note

This option is ignored if ssl_certificate_authority is not enabled.

4.17.8.12. ssl_cipher_list

Default value:

secure

Optional:

Yes

Values:
  • List of SSL/TLS ciphers in OpenSSL format.
  • secure
From version:

1.7.4

Description:

This defined the list of ciphers accepted by this component while communicating over the network.

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

Connections are closed if the remote peer has no common cipher in its list of configured ciphers.

More information about the accepted values can be found at the cryptography guide

The format for this value is the same as the one used for defining the OpenSSL cipher list. More information can be found on the OpenSSL site.

4.17.8.13. ssl_allowed_methods

Default value:

tlsv1 tlsv1.1 tlsv1.2

Optional:

Yes

Values:
  • tlsv1.0
  • tlsv1.1
  • tlsv1.2
From version:

1.7.4

Description:

This defines the space separated list of SSL and TLS methods that are accepted by this component during the secure communication handshake.

Currently, the following methods are officially supported:

  • tlsv1 or tlsv1.0, which is TLS 1.0.
  • tlsv1.1, which is TLS 1.1.
  • tlsv1.2, which is TLS 1.2.

Note

SSLv3 is still supported, but highly discouraged, due to the SSLv3 POODLE vulnerability. In the case that you need to interact with an old SSL implementation that only supports SSLv3, it is highly recommended to force the usage of the non-CBC cipher RC4-SHA by configuring as:

[services/681f5f5d-0502-4ebb-90d5-5d5c549fac6b]
ssl_cipher_list = RC4-SHA

Support for SSLv3 will be removed in future versions.

SSLv2 is no longer supported since it is not secure.

In version 2.8.0, the following new methods were added: tlsv1.0 (alias for tlsv1), tlsv1.1 and tlsv1.2

4.17.8.14. ftps_ccc

Default value:

Disabled

Optional:

Yes

From version:

3.13.0

Values:
  • Passive
  • Disabled
  • Empty
Description:

This option specifies whether the security of the FTPS command connection should be downgraded to plain text after authentication.

Leave it empty to keep the command connection secure.

When this option is enabled, the SSL/TLS layer is shutdown after authenticating. The rest of the control channel communication will be done over an unencrypted connection.

For more details about using this configuration option please check the dedicated documentation for the FTPS CCC modes.

4.17.9. Implicit FTPS Location

An implicit ftps location provides access to an Implicit FTPS server.

Note

The implicit FTPS location is an experimental feature.

4.17.9.1. address

Default value:

‘’

Optional:

No

Values:
  • Host name or IP address of the FTP server.
From version:

3.13.0

Description:

Address of the server. IP or host name.

In order to check the identity of the remote server the address should be provided as FQDN. IP addresses are not supported by the server identity validation process.

4.17.9.2. port

Default value:

990

Optional:

Yes

Values:
  • Number, greater than 0.
From version:

3.13.0

Description:

Port number to connect to the server.

4.17.9.3. username

Default value:

‘’

Optional:

No

From version:

3.13.0

Values:
  • Text.
Description:

Username used to authenticate to the server.

4.17.9.4. password

Default value:

‘’

Optional:

Yes

From version:

3.13.0

Values:
  • Plain text password.
  • Disabled or empty.
Description:

This option specifies the password used to connect to the server.

It is defined in plain text format and sent over the network protected by the TLS protocol.

4.17.9.5. ssl_domains

Default value:

Empty

Optional:

Yes

Values:
  • Fully qualified domain name (FQDN)
  • Empty
From version:

3.42.0 This configuration option defines the domain for which SFTPPlus will request certificates from the Let’s Encrypt server.

The same domain can be shared by multiple services.

The domain name is handled as a case-insensitive lower case value.

For this option to be used, you need to define a lets-encrypt resource.

4.17.9.6. ssl_certificate

Default value:

no-certificate-defined

Optional:

Yes

Values:
  • Absolute path on local filesystem.
  • Certificate as PEM text format (Since 3.40.0).
  • Disabled
From version:

1.6.0

To version:

None

Description:

This can be defined as an absolute path on the local filesystem to the SSL certificate file used by the component. File content should be encoded in the Privacy-Enhanced Mail (PEM) format.

Note

The path should not be longer than 256 characters.

You can also define the content of the certificate as text in PEM format. In this case the configuration will look as in the following example. It’s important to start each line with at least one space character and keep the number of leading spaces constant:

ssl_certificate = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When the value contains both the certificate and the key, the configuration will look as in the following example:

ssl_certificate = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

This certificate is sent to the remote peer during the SSL/TLS handshake process.

The certificate file can contain both the certificate and the private key, in which case you don’t need to set the path to the private key. Only supported for PEM encoding.

The certificate file can contain the certificate chain. The targeted certificate should be first in the file, followed by the chained certificates. It will advertise the certificate chain in the same order as listed in the file. Only supported for PEM encoding. (Since 3.22.0)

For server-side components using TLS/SSL secure communication, this configuration options is required.

For client-side component using TLS/SSL, you can disable sending the certificate as part of the handshake, by setting this configuration option to Disabled.

4.17.9.7. ssl_key

Default value:

Empty

Optional:

Yes

Values:
  • Absolute path on local filesystem.
  • Key as PEM text format (Since 3.40.0).
  • Empty
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to the X.509 private key file used by this component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) format.

Note

The path should not be longer than 256 characters.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_key = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----

If the value defined in ssl_certificate option already contains the private key, this option can be omitted by leaving it empty.

4.17.9.8. ssl_key_password

Default value:

Disabled

Optional:

Yes

Values:
  • Password as plain text.
  • Disabled
From version:

1.7.19

Description:

This is used to define the password of the private key, when the private X.509 key is stored as an encrypted file.

Set it to Disabled to not use a password for the private key file.

4.17.9.9. ssl_certificate_authority

Default value:

Disabled

Optional:

Yes

Values:
  • Absolute path on local filesystem.
  • Content of the CA chain (Since 3.40.0).
  • ${LETS_ENCRYPT_X3_CA}
  • ${MICROSOFT_IT_CA}
  • Disabled
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to a file containing the certificates to the Certificates Authority used to validate the remote peer.

You can also define the content of the CA as text in PEM format.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_certificate_authority = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When a certificate authority is define, this will result in initiating the two-way SSL/TLS authentication/handshake validation. For a successful connection, make sure the client sends a valid certificate. If the connection fails, the event with ID 40009 is emitted.

The certificate authority file should be stored as a file in PEM format. For multiple CA, place all certificates in the same file.

A series of bundle CA are distributed with SFTPPlus. They can be configured together and mixed with other CA certificates. The bundle CAs are available under the following names:

  • ${LETS_ENCRYPT_X3_CA} - For Let’s Encrypt X3 certificate authority.
  • ${MICROSOFT_IT_CA} - For all Microsoft IT CA certificates, used by SharePoint Online and other services provided by Microsoft.

To configure a component to accept peer certificates signed by Microsoft IT CA, which is the CA used by SharePoint Online, you can set the configuration as:

ssl_certificate_authority = ${MICROSOFT_IT_CRL}

Set as Disabled to disable checking the issuer for peer’s certificates. When certificate authority check is disabled, connection peers are not required to send a certificate and will result in a one-way SSL/TLS authentication. If the peer sends a certificate, it is ignored.

This defines the path on local filesystem to a file contain the certificate in PEM format for the single certificate authority or multiple authorities authorities with which this component will communicate.

Only peer connections using certificates signed by one of these certificate authorities will be permitted to communicate to this component.

When this component should communicate with peers holding certificates issued by multiple certificate authorities, put each CA certificate in PEM format inside a single file.

Leave it empty or set it as Disabled to disable checking the issuer of the peer’s certificates.

When certificate authority check is disabled, connection peers are not required to send a certificate. If the peer sends a certificate, it is ignored.

4.17.9.10. ssl_certificate_revocation_list

Default value:

Disabled

Optional:

Yes

Values:
  • Comma separated list of CRL paths or HTTP URLs.
  • crl-distribution-points
  • ${MICROSOFT_IT_CRL}
  • Disabled
From version:

1.6.0

Description:

It defines the locations from where one or more CRLs will be loaded.

Multiple CRLs are defined as a comma separated list.

It supports local files with absolute paths, in either of the following formats:

* ``file:///unix/absolute/test-ca.crl``
* ``file://c:\\windows\\absolute\\test-ca.crl``

Retrieving the CRL over HTTP is also supported. The HTTP request is done using non-persistent HTTP/1.1 connections. The URL will look as follows:

* ``http://example.com/some.crl``

CRL distribution points (CDP) are supported by using the crl-distribution-points configuration value.

When CRL distribution points are configured, the local certificate defined at ssl_certificate needs to have the CDP extension. The CDP advertised in the local certificate is loaded at startup in order to validate the configuration.

The distribution points configuration is mutually exclusive with local file or HTTP url configurations. When the certificate revocation list is configured to use CDP, all other configured CRL location are ignored.

Warning

HTTP redirection is not yet supported for CRL URLs. You have to configure the exact URL for the CRL.

Set it to Disabled, to disable certificate revocation checks.

The certificate revocation list can only be used when the component is configured with CA certificates stored in a single file in PEM format.

When multiple or chained CA certificates are configured the CRL is only checked for the peer’s certificate and not for the CA certificate or for an intermediate CA.

Warning

CDP publishing Delta CRL are not supported.

Note

If the certificate defines multiple HTTP based distribution points in the CDP extension, only the first HTTP URI is used. All non HTTP or the other HTTP URIs are ignored.

The CRL file should be stored in PEM or DER format.

Note

This option is ignored if ssl_certificate_authority is not enabled.

4.17.9.11. ssl_certificate_revocation_list_refresh

Default value:

0

Optional:

Yes

Values:
  • Number of seconds
  • 0
From version:

2.8.0

Description:

This defined the number of seconds after which a configured CRL is reloaded by this component.

When set to 0, the CRL file is initially loaded at startup and then loaded again after the Next Update field advertised in the CRL.

If the Next Publish extension is present in the CRL and this option is set to 0, the CRL will be loaded again at the date and time specified in the Next Publish extension.

If the CRL does not advertise the Next Update field you will have to configure a number of seconds after which the CRL should be reloaded, otherwise you will get a configuration error.

For example, a value of 86400 means that the CRL will be re-read after one day.

For more details about the CRL reloading see the documentation for CRL reloading rules

Note

This option is ignored if ssl_certificate_authority is not enabled.

4.17.9.12. ssl_cipher_list

Default value:

secure

Optional:

Yes

Values:
  • List of SSL/TLS ciphers in OpenSSL format.
  • secure
From version:

1.7.4

Description:

This defined the list of ciphers accepted by this component while communicating over the network.

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

Connections are closed if the remote peer has no common cipher in its list of configured ciphers.

More information about the accepted values can be found at the cryptography guide

The format for this value is the same as the one used for defining the OpenSSL cipher list. More information can be found on the OpenSSL site.

4.17.9.13. ssl_allowed_methods

Default value:

tlsv1 tlsv1.1 tlsv1.2

Optional:

Yes

Values:
  • tlsv1.0
  • tlsv1.1
  • tlsv1.2
From version:

1.7.4

Description:

This defines the space separated list of SSL and TLS methods that are accepted by this component during the secure communication handshake.

Currently, the following methods are officially supported:

  • tlsv1 or tlsv1.0, which is TLS 1.0.
  • tlsv1.1, which is TLS 1.1.
  • tlsv1.2, which is TLS 1.2.

Note

SSLv3 is still supported, but highly discouraged, due to the SSLv3 POODLE vulnerability. In the case that you need to interact with an old SSL implementation that only supports SSLv3, it is highly recommended to force the usage of the non-CBC cipher RC4-SHA by configuring as:

[services/681f5f5d-0502-4ebb-90d5-5d5c549fac6b]
ssl_cipher_list = RC4-SHA

Support for SSLv3 will be removed in future versions.

SSLv2 is no longer supported since it is not secure.

In version 2.8.0, the following new methods were added: tlsv1.0 (alias for tlsv1), tlsv1.1 and tlsv1.2

4.17.10. WebDAV over HTTPS Location

A webdavs location provides access to a WebDAV server over a protected HTTPS connection.

SharePoint Online is the only WebDAV server currently supported. Only username and password credentials are supported to authenticate against the WebDAV server provided by SharePoint Online as part of the Office 365 claims-based authentication.

It is assumed that the WebDAV server handles the path in a case-insensitive manner. Please get in touch if your WebDAV server is case-sensitive.

Unlike a web browser, to protect the HTTPS connection you will have to explicitly configure the list of trusted CA and the location of the CRLs.

4.17.10.1. address

Default value:

‘’

Optional:

No

Values:
  • Host name or IP address.
From version:

3.20.0

Description:

Address of the WebDAV server. IP or host name.

4.17.10.2. port

Default value:

443

Optional:

Yes

Values:
  • Number, greater than 0.
From version:

3.20.0

Description:

Port number to connect to the WebDAV server.

4.17.10.3. username

Default value:

‘’

Optional:

No

From version:

3.20.0

Values:
  • Text.
Description:

Username used to authenticate to the WebDAV server.

4.17.10.4. password

Default value:

‘’

Optional:

Yes

From version:

3.0.0

Values:
  • Plain text password.
  • Disabled or empty.
Description:

This option specifies the password used to connect to the WebDAV server.

It is defined in plain text format and sent over the network protected by the HTTPS connection.

4.17.10.5. proxy

Default value:

‘’

Optional:

Yes

Values:
  • URI like expression.
  • connect://12.342.421.2:3128
From version:

3.20.0

Description:

This configuration adds the proxy used to connect to the final URL.

For now, only the HTTP/1.1 CONNECT tunneling proxy method is supported.

4.17.10.6. ssl_domains

Default value:

Empty

Optional:

Yes

Values:
  • Fully qualified domain name (FQDN)
  • Empty
From version:

3.42.0 This configuration option defines the domain for which SFTPPlus will request certificates from the Let’s Encrypt server.

The same domain can be shared by multiple services.

The domain name is handled as a case-insensitive lower case value.

For this option to be used, you need to define a lets-encrypt resource.

4.17.10.7. ssl_certificate

Default value:

no-certificate-defined

Optional:

Yes

Values:
  • Absolute path on local filesystem.
  • Certificate as PEM text format (Since 3.40.0).
  • Disabled
From version:

1.6.0

To version:

None

Description:

This can be defined as an absolute path on the local filesystem to the SSL certificate file used by the component. File content should be encoded in the Privacy-Enhanced Mail (PEM) format.

Note

The path should not be longer than 256 characters.

You can also define the content of the certificate as text in PEM format. In this case the configuration will look as in the following example. It’s important to start each line with at least one space character and keep the number of leading spaces constant:

ssl_certificate = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When the value contains both the certificate and the key, the configuration will look as in the following example:

ssl_certificate = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

This certificate is sent to the remote peer during the SSL/TLS handshake process.

The certificate file can contain both the certificate and the private key, in which case you don’t need to set the path to the private key. Only supported for PEM encoding.

The certificate file can contain the certificate chain. The targeted certificate should be first in the file, followed by the chained certificates. It will advertise the certificate chain in the same order as listed in the file. Only supported for PEM encoding. (Since 3.22.0)

For server-side components using TLS/SSL secure communication, this configuration options is required.

For client-side component using TLS/SSL, you can disable sending the certificate as part of the handshake, by setting this configuration option to Disabled.

4.17.10.8. ssl_key

Default value:

Empty

Optional:

Yes

Values:
  • Absolute path on local filesystem.
  • Key as PEM text format (Since 3.40.0).
  • Empty
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to the X.509 private key file used by this component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) format.

Note

The path should not be longer than 256 characters.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_key = -----BEGIN RSA PRIVATE KEY-----
    MIICXgIBAAKBgQDOoZUYd8KMYbre5zZIwR+V6dO2+cCYVS46BHbRbqt7gczkoIWh
    ...
    MORE KEY DATA
    ...
    Wh+QF3UArO8r8RYv3HRcnBjrGh+yEK93wIifVNGgy63FIQ==
    -----END RSA PRIVATE KEY-----

If the value defined in ssl_certificate option already contains the private key, this option can be omitted by leaving it empty.

4.17.10.9. ssl_key_password

Default value:

Disabled

Optional:

Yes

Values:
  • Password as plain text.
  • Disabled
From version:

1.7.19

Description:

This is used to define the password of the private key, when the private X.509 key is stored as an encrypted file.

Set it to Disabled to not use a password for the private key file.

4.17.10.10. ssl_certificate_authority

Default value:

Disabled

Optional:

Yes

Values:
  • Absolute path on local filesystem.
  • Content of the CA chain (Since 3.40.0).
  • ${LETS_ENCRYPT_X3_CA}
  • ${MICROSOFT_IT_CA}
  • Disabled
From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to a file containing the certificates to the Certificates Authority used to validate the remote peer.

You can also define the content of the CA as text in PEM format.

When the value is defined as PEM text, the configuration will look as in the following example:

ssl_certificate_authority = -----BEGIN CERTIFICATE-----
    MIICaDCCAdGgAwIBAgIBDjANBgkqhkiG9w0BAQUFADBGMQswCQYDVQQGEwJHQjEP
    ...
    MORE CERTIFICATE DATA
    ...
    JZQaMjV9XxNTFOlNUTWswff3uE677wSVDPSuNkxo2FLRcGfPUxAQGsgL5Ts=
    -----END CERTIFICATE-----

When a certificate authority is define, this will result in initiating the two-way SSL/TLS authentication/handshake validation. For a successful connection, make sure the client sends a valid certificate. If the connection fails, the event with ID 40009 is emitted.

The certificate authority file should be stored as a file in PEM format. For multiple CA, place all certificates in the same file.

A series of bundle CA are distributed with SFTPPlus. They can be configured together and mixed with other CA certificates. The bundle CAs are available under the following names:

  • ${LETS_ENCRYPT_X3_CA} - For Let’s Encrypt X3 certificate authority.
  • ${MICROSOFT_IT_CA} - For all Microsoft IT CA certificates, used by SharePoint Online and other services provided by Microsoft.

To configure a component to accept peer certificates signed by Microsoft IT CA, which is the CA used by SharePoint Online, you can set the configuration as:

ssl_certificate_authority = ${MICROSOFT_IT_CRL}

Set as Disabled to disable checking the issuer for peer’s certificates. When certificate authority check is disabled, connection peers are not required to send a certificate and will result in a one-way SSL/TLS authentication. If the peer sends a certificate, it is ignored.

This defines the path on local filesystem to a file contain the certificate in PEM format for the single certificate authority or multiple authorities authorities with which this component will communicate.

Only peer connections using certificates signed by one of these certificate authorities will be permitted to communicate to this component.

When this component should communicate with peers holding certificates issued by multiple certificate authorities, put each CA certificate in PEM format inside a single file.

Leave it empty or set it as Disabled to disable checking the issuer of the peer’s certificates.

When certificate authority check is disabled, connection peers are not required to send a certificate. If the peer sends a certificate, it is ignored.

4.17.10.11. ssl_certificate_revocation_list

Default value:

Disabled

Optional:

Yes

Values:
  • Comma separated list of CRL paths or HTTP URLs.
  • crl-distribution-points
  • ${MICROSOFT_IT_CRL}
  • Disabled
From version:

1.6.0

Description:

It defines the locations from where one or more CRLs will be loaded.

Multiple CRLs are defined as a comma separated list.

It supports local files with absolute paths, in either of the following formats:

* ``file:///unix/absolute/test-ca.crl``
* ``file://c:\\windows\\absolute\\test-ca.crl``

Retrieving the CRL over HTTP is also supported. The HTTP request is done using non-persistent HTTP/1.1 connections. The URL will look as follows:

* ``http://example.com/some.crl``

CRL distribution points (CDP) are supported by using the crl-distribution-points configuration value.

When CRL distribution points are configured, the local certificate defined at ssl_certificate needs to have the CDP extension. The CDP advertised in the local certificate is loaded at startup in order to validate the configuration.

The distribution points configuration is mutually exclusive with local file or HTTP url configurations. When the certificate revocation list is configured to use CDP, all other configured CRL location are ignored.

Warning

HTTP redirection is not yet supported for CRL URLs. You have to configure the exact URL for the CRL.

Set it to Disabled, to disable certificate revocation checks.

The certificate revocation list can only be used when the component is configured with CA certificates stored in a single file in PEM format.

When multiple or chained CA certificates are configured the CRL is only checked for the peer’s certificate and not for the CA certificate or for an intermediate CA.

Warning

CDP publishing Delta CRL are not supported.

Note

If the certificate defines multiple HTTP based distribution points in the CDP extension, only the first HTTP URI is used. All non HTTP or the other HTTP URIs are ignored.

The CRL file should be stored in PEM or DER format.

Note

This option is ignored if ssl_certificate_authority is not enabled.

4.17.10.12. ssl_certificate_revocation_list_refresh

Default value:

0

Optional:

Yes

Values:
  • Number of seconds
  • 0
From version:

2.8.0

Description:

This defined the number of seconds after which a configured CRL is reloaded by this component.

When set to 0, the CRL file is initially loaded at startup and then loaded again after the Next Update field advertised in the CRL.

If the Next Publish extension is present in the CRL and this option is set to 0, the CRL will be loaded again at the date and time specified in the Next Publish extension.

If the CRL does not advertise the Next Update field you will have to configure a number of seconds after which the CRL should be reloaded, otherwise you will get a configuration error.

For example, a value of 86400 means that the CRL will be re-read after one day.

For more details about the CRL reloading see the documentation for CRL reloading rules

Note

This option is ignored if ssl_certificate_authority is not enabled.

4.17.10.13. ssl_cipher_list

Default value:

secure

Optional:

Yes

Values:
  • List of SSL/TLS ciphers in OpenSSL format.
  • secure
From version:

1.7.4

Description:

This defined the list of ciphers accepted by this component while communicating over the network.

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

Connections are closed if the remote peer has no common cipher in its list of configured ciphers.

More information about the accepted values can be found at the cryptography guide

The format for this value is the same as the one used for defining the OpenSSL cipher list. More information can be found on the OpenSSL site.

4.17.10.14. ssl_allowed_methods

Default value:

tlsv1 tlsv1.1 tlsv1.2

Optional:

Yes

Values:
  • tlsv1.0
  • tlsv1.1
  • tlsv1.2
From version:

1.7.4

Description:

This defines the space separated list of SSL and TLS methods that are accepted by this component during the secure communication handshake.

Currently, the following methods are officially supported:

  • tlsv1 or tlsv1.0, which is TLS 1.0.
  • tlsv1.1, which is TLS 1.1.
  • tlsv1.2, which is TLS 1.2.

Note

SSLv3 is still supported, but highly discouraged, due to the SSLv3 POODLE vulnerability. In the case that you need to interact with an old SSL implementation that only supports SSLv3, it is highly recommended to force the usage of the non-CBC cipher RC4-SHA by configuring as:

[services/681f5f5d-0502-4ebb-90d5-5d5c549fac6b]
ssl_cipher_list = RC4-SHA

Support for SSLv3 will be removed in future versions.

SSLv2 is no longer supported since it is not secure.

In version 2.8.0, the following new methods were added: tlsv1.0 (alias for tlsv1), tlsv1.1 and tlsv1.2

4.17.11. Azure File Service Location

An azure-file location provides access over HTTPS to the Azure File Service of an Azure Storage account.

The files stored in Azure File Service shares are accessible via the SMB protocol and HTTP API. Azure Files is specifically a network file system. SFTPPlus will use the HTTPS based API to manage the files.

The HTTPS connections will use the default list of secure ciphers and will accept TLS v1.0, TLS v1.1 and TLS v1.2 protocols.

Note

This is not supported on SLES 11 without Security Module, due to the lack of SHA256.

Note

Unsecured HTTP access is not available.

Note

The current implementation is tested using General-purpose v2 (GPv2) accounts.

Only storage account names with access keys are currently supported. Please get in touch if you plan to use Azure Active Directory or shared access signatures.

The path / url to the Azure File storage is case-sensitive.

When using Azure File locations, the source or destination path will be defined as the name of the share (to or from where files are transferred) followed by the targeted directory inside that share. The path will look like /SHARE-NAME/DIR-IN-ROOT/PARENT-DIR.

The requests made by SFTPPlus to the Azure Storage server are done using the sftpplus-azure-file-UUID format. Where UUID is a unique identifier for this location. This can be used inside Azure Storage Analytics to identify the operations done by this location. The request ID will look like:

x-ms-client-request-id: sftpplus-azure-file-60ec1329-cc5d-416e-81b9-7c22

4.17.11.1. username

Default value:

‘’

Optional:

No

From version:

3.36.0

Values:
  • Text.
Description:

Name of the Azure Storage Account.

4.17.11.2. password

Default value:

‘’

Optional:

Yes

From version:

3.36.0

Values:
  • Plain text.
Description:

Any of the two access keys for the Azure storage account.

It should be specified in Base64 format. This is the default format presented by the Azure Portal.