Documentation

5.2. FTP / Explicit FTPS / Implicit FTPS

This page describes the configuration options available for the FTP / FTPS service.

SFTPPlus provides two ways for securing FTP transfers - explicit FTPS and implicit FTPS.

5.2.1. Explicit FTPS

Explicit FTPS is the most widely used method. The connections for Explicit FTPS are started just like normal FTP connections. After the initial connection, the FTP client can ask the server to switch to the secured Explicit FTPS mode.

The Explicit FTPS service can share the same TCP port with the non-secured FTP service. This is why the FTP and Explicit FTPS protocols are configured in SFTPPlus as a single service using the ftp protocol.

A single service using the FTP protocol can be configured to allow only unsecured FTP connections, to allow only secured Explicit FTPS connections, or to allow both secured and unsecured connections.

5.2.2. Implicit FTPS

Implicit FTPS is a method in which the client is required to initiate a connection using an SSL/TLS handshake. All connections not initiated using an SSL/TLS handshake are dropped. This does not allow sharing the same TCP port with a non-secured FTP service, thus the Implicit FTPS service requires a dedicated port.

For more details, please check the dedicated FTPS article from Wikipedia.

5.2.3. enabled

Default value:

Yes

Optional:

Yes

Values:

  • Yes - to automatically start the service when the server is started.

  • No - to leave the service stopped when the server is started.

From version:

1.6.0

Description:

When a service is not automatically started, it can still be manually started afterwards from the Web Manager.

5.2.4. name

Default value:

undefined-service-name

Optional:

No

Values:

  • Any text.

From version:

2.0.0

Description:

Human-readable short string used to identify this service.

5.2.5. type

Default value:

''

Optional:

No

Values:

  • ftp - for FTP and Explicit FTPS services.

  • ftpsi - for Implicit FTPS services.

  • ssh - for SSH services providing the SFTP and SCP protocols.

  • http - for HTTP services.

  • http-redirect - for HTTP Redirection services.

  • https - for HTTPS services.

  • monitor - for local file system monitor services.

  • manager - for Web Manager services.

From version:

2.10.0

Description:

The main option which defines what protocol will be used for this service.

FTP and Explicit FTPS are using the same ftp protocol type, since both protocols can be served by the same service.

Note

The sftp option is also available for backward compatibility, and has the same effect as the ssh option.

5.2.6. address

Default value:

'127.0.0.1'

Optional:

No

Values:

  • Host name resolving to an IPv4 address

  • Fully qualified domain name resolving to an IPv4 address

  • IPv4 address

  • IPv6 address

  • 0.0.0.0

From version:

1.7.0

Description:

Host name or IP used to listen for incoming connections.

To accept connections on all available IPv4 interfaces, use the 0.0.0.0 address.

To accept connections on all available IPv6 interfaces, use the :: address.

Note

On some operating systems (for example Linux) setting the address. to :: will listen to all available IPv6 and IPv4 addresses.

Note

This option is ignored for services of type monitor.

5.2.7. port

Default value:

''

Optional:

No

Values:

  • Port number used for incoming connections.

From version:

1.7.0

Description:

To avoid conflicts between different services on the same local machine, this must be a unique port number. On Unix-like systems, a root account is usually required for using ports below 1024.

Note

This option is ignored for services of type monitor.

5.2.8. description

Default value:

''

Optional:

Yes

Values:

  • Any text describing the role of this service.

From version:

1.8.0

Description:

This can be used for attaching notes to a service.

5.2.9. authentications

Default value:

''

Optional:

Yes

Values:

  • Comma separated list of authentication UUIDs.

From version:

3.2.0

To version:

Description:

Comma-separated list of UUIDs for the authentication methods enabled for this service.

The list should be ordered by priority. The service will try to use the first authentication from the list, and continue with the following method if the user is not accepted.

If this configuration option is empty or is left out the global authentication methods are used.

Note

This configuration option is ignored for the monitor service as this service does not authenticate clients.

5.2.10. debug

Default value:

'No'

Optional:

Yes

Values:

  • Yes

  • No

From version:

3.48.0

Description:

When enabled, the service will emit events with id 20000 containing low-level debug messages for the file transfer protocol.

Configuration changes are applied only to new connections. Existing connections respect the debug configuration in use when they were initiated.

Warning

When this is enabled, emitted events may include used passwords in plain text.

5.2.11. idle_connection_timeout

Default value:

300

Optional:

Yes

Values:

  • Positive number

From version:

1.7.19

Description:

This is defined as the number of seconds after which idle connections are disconnected.

The service will close the connection if a client connection is idle for a configurable amount of time. Any authenticated connections are automatically logged out.

When set to 0 or a negative number, it will use the default value.

5.2.12. maximum_concurrent_connections

Default value:

10000

Optional:

Yes

Values:

  • Number of maximum concurrent connections accepted by the service.

  • 0 - To disable the limit.

From version:

1.7.19

Description:

Maximum number of allowed concurrent connections for this service.

This limit is imposed by each service, and it is not a global limit for all services active on the server.

5.2.14. passive_port_range

Default value:

All available ports provided by the operating system.

Optional:

Yes

Values:

  • A range of port numbers.

  • MIN_PORT - MAX_PORT

  • 0 - 0 to use random ports.

From version:

1.7.0

Description:

When FTP/FTPS clients are requesting a passive transfer, the server will open a new connection that will be used for sending or receiving files from the client.

By default, the server will use a random port number for the newly created connection.

For example, to set a range of ports starting from 1500 and ending at port 2000, set the value to 1500 - 2000 like the following example:

[services/27b8e2b1-7971-416d-af14-6a8aae2ac46e] passive_port_range = 1500 - 2000

To use all available ports, do not define this or set it to 0 - 0:

[services/27b8e2b1-7971-416d-af14-6a8aae2ac46e] passive_port_range = 0 - 0

Note

passive_port_range is designed to help with firewalled configurations, but to some extent it is also a mechanism to limit the number of concurrent connections to the server. While this option is specific to the FTP protocol, there is a generic option, maximum_concurrent_connections, available to all protocols.

5.2.15. active_source_port

Default value:

0

Optional:

Yes

Values:

  • A TCP port number.

From version:

3.6.0

Description:

Source port used by the FTP service to initiate the active connections for the PORT or the EPRT requests.

The source address is the same as address used to listen for incoming control connections.

If you have a set address such as:

[services/27b8e2b1-7971-416d-af14-6a8aae2ac46e]
address = 0.0.0.0

And your deployment requires an explicit outbound / outgoing / egress interface, you will need to configure an explicit address otherwise outbound connections will use the source address automatically provided by the operating system, based on routing table.

When set as 0, a random source port is used.

Note

On Unix-like systems, elevated privileges are required to initiate connection from source ports below 1024.

5.2.16. passive_address

Default value:

Empty

Optional:

Yes

Values:

  • 1.2.3.4

  • Empty.

From version:

2.9.0

Description:

IP address advertised by the FTP service in the passive PASV request.

When left empty, the service will automatically detect server address.

When set to a single IP address, it will use that address in all PASV requests, regardless of the client's source IP.

Note

This option is ignored for EPSV requests.

5.2.17. idle_data_connection_timeout

Default value:

30

Optional:

Yes

Values:

  • An integer value greater than 0, representing seconds.

From version:

1.8.2

Description:

Specifies the timeout, in seconds, after which an inactive data channel is disconnected. For this number of seconds, the service will only act upon the data channel, without disconnecting the command channel.

When set to 0 or a negative number, the default timeout is used.

5.2.18. ssl_certificate_authority

Default value:

Empty

Optional:

Yes

Values:

  • PEM content of a CA chain (Since 3.40.0)

  • PEM content of a public key (Since 5.1.0)

  • Absolute path to a local file.

  • ${LETS_ENCRYPT_X3_CA}

  • ${MICROSOFT_IT_CA}

  • ${GO_DADDY_G2_G1}

  • Empty

From version:

1.6.0

Description:

This is used only for certificate-based peer validation and mutual TLS authentication.

Configured certificates need to be in PEM format.

Multiple certificates authorities (CAs) can be configured, one after the other. They can be multiple root CAs or intermediate CAs.

This option can be defined as an absolute path on the local filesystem to a file containing the certificates of the Certificate Authorities used to validate the remote peer.

When a certification authority is configured for this server, the server will enforce two-way SSL/TLS authentication/handshake validation for every incoming connection.

For a successful connection, make sure the remote peer sends a valid certificate. If the connection fails, the event with ID 40054 is emitted.

Only client connections using certificates signed by one of these Certificate Authorities is permitted to communicate to this server.

When this server should communicate with peers holding certificates issued by different certificate authorities, put all the CA certificates in PEM format inside a single file.

You can configure the server to validate the peer certificates based on a fixed list of public keys. In this way, you can implement public key pinning. When public key validation is used, the public key infrastructure (PKI) certificate policies are not enforced. For example, the peer certificate is accepted even if it's expired. This is done by configuring the values in PEM public key format.

Leave it empty 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.

5.2.19. ssl_domains

Default value:

Empty

Optional:

Yes

Values:

  • Fully qualified domain name (FQDN)

  • Comma separated list of fully qualified domain names

  • 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.

You can generate a certificate with multiple domain names (Subject Alternative Name - SAN), by defining a comma-separated list of domain names. The first name from the list is used as the common name of the certificate, while the remaining names are used for the SAN extension.

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

5.2.20. ssl_certificate

Default value:

Empty

Optional:

Yes

Values:

  • Absolute path on the local filesystem.

  • Certificate in PEM text format (Since 3.40.0).

  • Certificate in PKCS12 / PXF binary format (Since 4.0.0).

  • Empty

From version:

1.6.0

Description:

This can be defined as an absolute path on the local filesystem to the file containing the SSL certificate or chain of certificates used by the component.

File content should be encoded in the Privacy-Enhanced Mail (PEM) or PKCS12 / PFX formats.

File extension should be .p12 or .pfx for the file to be recognized as a PCKS-12 certificate. The password for the PCKS12 / PFX certificate should be set in the ssl_key_password configuration option.

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 full chain of certificates. 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 option is required. If no value is defined here, the global ssl_certificate value is used.

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

5.2.21. ssl_key

Default value:

Empty

Optional:

Yes

Values:

  • Absolute path on the 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 ssl_certificate is not defined, any value defined for this ssl_key configuration is ignored and the global ssl_key value is used.

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

5.2.22. ssl_key_password

Default value:

Empty

Optional:

Yes

Values:

  • Password as plain text.

  • Empty

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.

Leave it empty to not use a password for the private key file.

5.2.23. ssl_certificate_revocation_list

Default value:

Empty

Optional:

Yes

Values:

  • Comma separated list of CRL paths or HTTP URLs.

  • crl-distribution-points

  • ${MICROSOFT_IT_CRL}

  • Empty

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.

Leave it empty 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.

5.2.24. 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.

5.2.25. 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.

When left empty, it will default to the secure configuration.

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.

5.2.26. ssl_allowed_methods

Default value:

secure

Optional:

Yes

Values:

  • secure

  • all

  • tlsv1.0

  • tlsv1.1

  • tlsv1.2

  • tlsv1.3

From version:

1.7.4

Description:

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

Set this to secure to allow only the TLS methods that are currently considered secure. For now, this is TLS 1.2 and TLS 1.3 but this might be changed in the future. Any other configured value is ignored.

Set this to all to allow any supported SSL or TLS method. Any other configured value is ignored.

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.

  • tlsv1.3, which is TLS 1.3.

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

Support for tlsv1.3 was added in version 3.47.0.

Prior to version 4.17.0, this was configured as a space separated value.

5.2.27. ftps_explicit_enabled

Default value:

Yes

Optional:

Yes

Values:

  • Yes - Enable Explicit FTPS protocol.

  • No - Disable Explicit FTPS protocol.

From version:

1.6.0

Description:

If the FTPS protocol is disabled, no secured connections are accepted.

This will only enable Explicit FTPS secure connections, but will not enforce clients to use secured connections. Dedicated configuration options are provided for this purpose.

Not available for the Implicit FTPS protocol.

In SFTPPlus version 4 and older, the default value was No.

5.2.28. enable_password_authentication

Default value:

Yes

Optional:

Yes

Values:

  • Yes - Enable password-based authentication.

  • No - Disable password-based authentication.

From version:

1.7.4

Description:

Enable authentication based on username and password credentials.

5.2.29. enable_ssl_certificate_authentication

Default value:

Yes

Optional:

Yes

Values:

  • Yes - Enable SSL certificate-based authentication.

  • No - Disable SSL certificate-based authentication.

From version:

1.7.4

Description:

SSL certificate-based authentication allows clients to authenticate using a pair of username and SSL certificate credentials. A password is no longer required.

When the SSL certificate-based authentication is disabled, ensure that password-based authentication is enabled, otherwise clients will have no authentication method available.

5.2.30. ftps_force_secured_command_channel

Default value:

Yes

Optional:

Yes

Values:

  • Yes - Only allow commands over secured connections.

  • No - Allow commands over both secured and unsecured connections.

From version:

1.6.0

Description:

When secure command channel is forced, any attempt to send unencrypted commands will be rejected.

This option will be ignored if Explicit FTPS is not enabled.

Not available for Implicit FTPS protocol, where secured command is always enforced due to protocol specification.

In SFTPPlus version 4 and older, the default value was No.

5.2.31. ftps_require_session_reuse

Default value:

Yes (Since 5.0.0)

Optional:

Yes

Values:

  • Yes

  • No

From version:

4.35.0

Description:

To make sure the data connection is initiated by the same party that was previously authenticated over the command channel, SFTPPlus will check that the data and command channel have the same TLS session.

When set to No, the session validation is skipped. It should be disabled only when support for legacy FTPS clients is required. When disabling this, make sure your firewall is updated to only allow connections from trusted source IP address. If you need to disable this, consider enabling the certificate authority validation for FTPS clients.

Danger

When disabled, the security of the data connection is highly decreased. A malicious 3rd party could intercept any transferred data.

This option is ignored for non-FTPS (implicit or explicit) connections.

5.2.32. ignore_ascii_data_type

Default value:

No

Optional:

Yes

Values:

  • Yes

  • No

From version:

3.8.0

Description:

This option allows configuring the FTP service to pretend that ASCII mode is supported, but to transfer the data in BINARY/IMAGE mode.

5.2.33. ascii_data_type_as_default

Default value:

No

Optional:

Yes

Values:

  • Yes

  • No

From version:

3.10.0

Description:

This option defines whether to use ASCII as the data type for the case in which the client does not explicitly ask for specific data type.

Set it to Yes to use ASCII/text as the default data type.

Set it to No to use IMAGE/binary as the default data type.

5.1. Introduction to server-side file transfers
5.3. SSH (SFTP and SCP)