300

3.0.0

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.

0

3.0.0

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,

12

3.9.0

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

Set to 0 to not retry.

300

3.9.0

Number of seconds to wait between connection attempts.

Set to 0 to retry right away without any delay.

Empty

• text

Full URL address of the HTTP server resource or page from where the file content is pulled.

Or if you need a custom port number use:

url = https://files.example.com/path/to/resource

When this is defined as an http:// URL, the TLS/SSL configuration options are ignored.

Empty

4.23.0

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

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

GET

• GET

• POST

• PUT

The HTTP method to use when making the request on the remote server.

You can configure it to values like POST or PUT. The value is case-insensitive.

When left empty, it will default to GET.

Empty

• Any text

• seed-file

Content used for the body of the HTTP request sent to the remote server.

Leave empty to send a request with an empty body.

When configured to seed-file it will make the request with having the body the content of a local file detected in the source_path configuration of each transfer.

This configuration is ignored when request_method is configured with the GET option.

Empty

• HEADER_NAME: HEADER VALUE

• Multiple headers, one header per line.

The list of headers used for the HTTP request to send to the remote server.

Leave empty to send a request without extra headers.

Each header is defined using NAME: VALUE format. Multiple headers can be defined, one header per line.

In the example below, 2 extra headers are sent:

request_headers =
    X-Stream-Type: reports
    Content-Type: application/octet-stream

The requests will always contain the following standard headers, required for basic HTTP operations:

• Host

• User-Agent`

• Content-Length

• Authorization (if authentication is enabled)

2*

• text

• matching expression

The expected HTTP response code for a successful request.

This is used to detect a failed request and to trigger the retry mechanism.

It can be configured to a fixed value like 200 or 201. It can also be configured to a matching expressing like 2* or 200 | 201, for which in the first case it will match any code starting with 2 or for the second case, it will accept 200 or 201.

When the remote server returns a different response code, it is considered a failure and the transfer is retried, based on the transfer configuration.

When left empty, it will consider any response a success.

http-pull.file

• fixed text

The name of the local file used to store the body of the response, when this is used as the source location.

This option is ignored when the location is used as the destination location.

It can be a fixed name or a template used to generate dynamic file names.

For example, when configured below, it will store the content of the url as a local file named stock-results.xml:

response_file_name = stock-results.xml

set-on-first-connection

• PEM content of a CA chain (Since 3.40.0)

• PEM content of a pinned public key (Since 5.1.0)

• Absolute path to a local file

• set-on-first-connection (Since 5.0.0)

• pin-public-key (Since 5.1.0)

• ${MOZILLA_CA_ROOTS} (Since 5.0.0)

• ${LETS_ENCRYPT_X3_CA}

• ${MICROSOFT_IT_CA}

• ${GO_DADDY_G2_G1}

• disable-identity-security (Since 5.0.0)

This is used to validate the identity of the remote server.

Remote server identity can only be validated when the remote address or URL is configured using a fully-qualified domain name. IP-based validation would always fail as this is not a method accepted by Certificate Authorities (CAs).

Configured certificates need to be in PEM format.

Multiple Certificate Authorities can be configured, one after the other. They can be multiple root CAs or intermediate CAs.

When set-on-first-connection is used, the Certificate Authority of the remote server is configured automatically. The set-on-first-connection configuration value is automatically replaced by the actual CA chain of the remove server on the very first connection. For all subsequent connections, the server identity is validated against the automatically configured CA chain.

When pin-public-key is set, SFTPPlus accepts server certificates that have the same public key as the one discovered during the first connection to this server. This is used to implement certificate and public key pinning. SFTPPlus only pins the public key. This can be used for self-signed server certificates.

You can configure the client to validate the server's identity 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 server certificate is accepted even if it's expired or issued for a different hostname.

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

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

• ${MOZILLA_CA_ROOTS} - All the root certification authorities accepted by the Mozilla's CA Certificate Program

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

• ${GO_DADDY_G2_G1} - For all GoDaddy Certificate Bundles, G2 With Cross to G1.

Only servers using certificates signed by one of the configured Certificate Authorities are allowed to communicate with this client.

Leave it empty to disable checking the identity of the remote server.

Empty

• Fully qualified domain name (FQDN)

• Comma separated list of fully qualified domain names

• Empty

Empty

• 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

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.

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.

Empty

• Absolute path on the local filesystem.

• Key as PEM text format (Since 3.40.0).

• Empty

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.

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.

Empty

• Password as plain text.

• Empty

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.

Empty

• Comma separated list of CRL paths or HTTP URLs.

• crl-distribution-points

• ${MICROSOFT_IT_CRL}

• Empty

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.

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.

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

0

• Number of seconds

• 0

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

secure

• List of SSL/TLS ciphers in OpenSSL format.

• secure

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.

secure

• secure

• all

• tlsv1.0

• tlsv1.1

• tlsv1.2

• tlsv1.3

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.

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