Documentation

5.4. HTTP / HTTPS

The http / https service allows the same level of file access as the other available file transfer services, such as FTPS or SFTP.

5.4.1. Introduction

When configured for a some.example.com address and the 18080 port, the service will be available at the URL http://some.example.com:18080, and it will redirect users to the start URL http://some.example.com:18080/home/.

As this page focuses on configuration options, please refer to the dedicated HTTP/HTTPS operations page.

Below you can find the list of available configuration options.

5.4.2. 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.4.3. 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.4.4. 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.4.5. 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.4.6. 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.4.7. 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.4.8. 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.4.9. 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.4.10. 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.4.11. 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.4.12. languages

Default value:

en

Optional:

Yes

Values:

  • Language ISO code

From version:

4.14.0

Description:

This configures the language for the web file transfer client user interface.

The available languages are: * en - English * es - Castellano / Spanish

When left empty, it defaults to English.

5.4.13. ui_version

Default value:

ui-gen-2 (Since 5.0.0)

Optional:

Yes

Values:

  • ui-gen-1

  • ui-gen-2

From version:

4.16.0

Description:

This defined the UI variant to be used for the web client.

The latest version is ui-gen-2.

To use the legacy UI found in SFTPPlus version 4.15.0 or older, set this to ui-gen-1.

5.4.14. login_footnotes

Default value:

Empty

Optional:

Yes

Values:

  • Text

From version:

5.1.0

Description:

This configuration can be used to define a custom footnote with addition info on the login page.

Note

This functionality is not available when using Internet Explorer 11.

Note

This configuration is only available for ui_version = ui-gen-2 or newer.

It is implemented as a link that reveals the additional information when accessed.

The configuration is defined as the following elements, on separate lines:

LINK_TEXT_FIRST_LINE
TITLE_TEXT_SECOND_LINE
The content of the message box
is in these remaining lines.

The content can be defined on multiple lines with distinct paragraphs.

The text of the footnote link is defined by the first line. The second line is the title of the message box to be opened. The remaining lines are the content of the message box.

Leave this configuration empty to not have a footnotes link on the login page.

5.4.15. theme_path

Default value:

Empty

Optional:

Yes

Values:

  • Absolute path on the local filesystem.

From version:

3.42.0

Description:

Absolute path to a local directory containing the files required to customize the HTTP transfer service.

The folder needs to contain at least the 'main.css' and main.js files.

Leave it empty when you don't want to customize the appearance of the HTTP file transfer service.

You can find more information on the usage of a theme path on the HTTP/HTTPS operations page.

Attention

The custom appearance functionality is released as a feature preview. We encourage you to try this functionality and send feedback. The HTML and CSS markup might be changed in future releases.

5.4.16. public_error

Default value:

No

Optional:

Yes

From version:

4.27.0

Values:

  • Yes

  • No

Description:

When set to Yes it will advertise to the end users the reason why the authentication failed.

When set to No, end users will receive a generic authentication failure message.

Warning

Exposing the error details can weaken the security of your server. For example, when receiving a detailed error "Invalid password", an attacker will know that the username is valid and in this way discover the name of valid usernames.

5.4.17. public_account_uuid

Default value:

Empty

Optional:

Yes

Values:

  • UUID to application account.

  • Empty.

From version:

3.40.0

Description:

This configuration option can be used to make a set of files available over HTTP/HTTPS without requiring an username or password.

The files for this account will be available under the /public/ URL or another suffix of your choosing, as configured for public_name.

Leave it empty to not allow public access. Trying to access the '/public/' URL will result in 404 Page Not Found error.

Credentials will still be required when accessing the '/home/' URL, which is dedicated to the private/protected access.

Using a dedicated application account to configure public access allows you to set fine grained access to the public files. The public files are not limited to read-only access.

Only application accounts defined in the main configuration are supported. OS accounts or external application accounts are not supported.

5.4.18. public_name

Default value:

public

Optional:

Yes

Values:

  • Name of the URL fragment.

  • ROOT

From version:

4.3.0

Description:

This defines the URL name under which the public files are available.

For example, when public_name = public-access, public files are available under an URL ending with /public-access, such as https://www.domain.com/public-access.

Set it to ROOT to have nothing special appended to the URL corresponding to the root of the HTTP/HTTPS file transfer service.

When this is empty, the default value of public is used.

This configuration is ignored when public_account_uuid is not defined.

5.4.19. as2_receive_name

Default value:

as2receive

Optional:

Yes

Values:

  • Name of the URL fragment for AS2 receive requests.

  • /path-name

  • /parent/path-name (Since version 4.26.0)

From version:

4.5.0

Description:

This defines the URL path used to receive AS2 requests.

For example, when as2_receive_name = as2receive, AS2 files will be accepted on the URL https://www.domain.com/as2receive.

It can also be configured using a sub-path. For example, when as2_receive_name = /as2/receive.in, AS2 files will be accepted on the URL https://www.domain.com/as2/receive.in.

5.4.20. as2_receive_path

Default value:

Empty

Optional:

Yes

Values:

  • Path to a directory in the user's home folder.

  • Empty

From version:

4.5.0

Description:

This defines the path used to store the files received via AS2 for each user.

This is a path relative to the home path of each user.

For example, when as2_receive_path = /as2/receive, and an account has home_folder_path = C:/Users/JohnD, files received through AS2 are stored in C:/Users/JohnD/as2/receive.

Leave it empty to store the files in the account's root home directory.

5.4.21. as2_pending_path

Default value:

_as2_pending

Optional:

Yes

Values:

  • Path to a directory in the user's home folder.

  • Empty

From version:

4.28.0

Description:

This defines the path inside each user's home folder, used to temporarily store the files received via AS2 before they are validated.

This is a path relative to the home path of each user.

For example, when as2_pending_path = /as2/pending, and an account has home_folder_path = C:/Users/JohnD, pending files are stored in C:/Users/JohnD/as2/pending.

Note

The path configured at as2_pending_path should be on the same filesystem as the path configured at as2_receive_path. This is because the files are moved from the temporary pending folder to the final folder using an internal filesystem rename operation, and moving across filesystems does not atomically create the destination with the full content.

5.4.22. as2_default_filename

Default value:

Empty

Optional:

Yes

Values:

  • Fixed name for a file

  • Template for filename.

From version:

4.14.0

Description:

This defines the file name used to store the received AS2 data when there are no AS2 request headers for the file name.

When this configuration is empty, and the AS2 request doesn't include a filename, the data is stored using a file named as2-received-file.TIMESTAMP.

This can also be configured as a file name template. For example, with the following configuration the actual file name created to store the received data will look like john_d-20210902T174910.xml, where john_d is the name of the account uploading the file:

as2_default_filename = {account.name}-{timestamp.iso_8601_compact}.xml

The following variables (case-insensitive) are provided as context data containing information about the event being triggered:

  • uuid

  • account.name

  • account.peer.address

  • account.peer.port

  • account.peer.protocol

  • account.uuid

  • timestamp.cwa_14051

  • timestamp.iso_8601

  • timestamp.iso_8601_fractional

  • timestamp.iso_8601_local

  • timestamp.iso_8601_basic

  • timestamp.iso_8601_compact

  • timestamp.timestamp

5.4.23. as2_receive_certificate

Default value:

Empty

Optional:

Yes

Values:

  • Certificate key in PEM format.

  • Empty

From version:

4.5.0

Description:

This defines the certificate associated with the private key used to sign the message disposition notification (MDN) response.

This configuration option can also contain the private key associated with this certificate.

Leave it empty to use the general server certificate.

5.4.24. as2_receive_key

Default value:

Empty

Optional:

Yes

Values:

  • RSA private key in PEM format.

  • Empty

From version:

4.5.0

Description:

This defines the private key used to decrypt the files received via AS2 and to sign the message disposition notification (MDN) responses.

Leave it empty to use the general server private key.

5.4.25. as2_no_mdn_success_text

Default value:

Empty

Optional:

Yes

Values:

  • Any text

From version:

4.17.0

Description:

This defines the response sent by SFTPPlus AS2 server when a message was successfully received but the client has not requested a MDN response.

Leave it empty to not return any explicit message. SFTPPlus will use the standard HTTP 201 Created status to let the client know that the file was successfully created on the server.

5.4.26. triggers

Default value:

Empty

Optional:

Yes

Values:

  • Comma-separated values.

  • Action name, Button Colour, Optional Group UUID

From version:

3.54.0

Description:

This configuration allows defining one or more custom buttons for the client web interface.

You can define multiple trigger buttons, one definition per line.

The first value is the name of the trigger and the text shown on the button. The second value is the type of the button and is defined as a button colour.

The third value is optional and defines the group of users for which the trigger is available. When not defined, the trigger is available to all groups.

Leave it empty to not show any additional buttons in the client web interface.

You can find more information on the usage of trigger buttons on the HTTP/HTTPS operations page.

5.4.27. metadata_fields

Default value:

Empty

Optional:

Yes

Values:

  • Empty

  • Name of HTTP header.

  • key name matching expression, list of options

From version:

4.15.0

Description:

This is used to configure the expected metadata header used making an HTTP API requests.

This is configured as a multi-line option.

The first line contains the name of the header used to extract the associated metadata and an optional list of header options.

The following lines contain comma separated definitions for the expected key/value metadata.

The first value on each line is the name of the metadata key or a matching expression for the metadata key.

The other values from the line are one of the following options:

  • optional - request is processed even if metadata is missing

  • required - request fails if metadata is not provided in the request

Leave it empty to not process any metadata for file operations.

When the metadata header name is configured without any key/value specification the request will accept any provided metadata and will handle them as optional.

The requested HTTP header value should be a key=value comma separated values (CSV) list. For example the following HTTP header:

X-Metadata: tag=report, tag=monthly, project-owner=John Doe

is parsed as the following JSON structure:

{
"tag": ["report", "monthly"],
"project-owner": ["John Doe"]
}

The simplest configuration in which any value from the x-sftpplus header is accessible is:

metadata_fields = x-sftpplus

A more complex configuration example in which:

  • the x-metadata header is required and expected to have the tag key/value fields, and

  • keys starting with project- are accepted but optional.

The request will succeed if the x-metadata header is not provided, as by default the processing of the header is optional:

metadata_fields =
  x-metadata
  tag, required
  project-*, optional

If you require a set of predefined keys but also accept any arbitrary keys, you can configure it as below. This will fail if the x-metadata HTTP header is not provided. This will fail if the tag metadata is not provided in the header's value and will accept any other extra metadata:

metadata_fields =
  x-metadata, required,
  tag, required
  *, optional

You can find more information on API requests with a metadata header on the HTTP REST API page.

5.4.28. announce_session_authentication

Default value:

yes

Optional:

Yes

Values:

  • yes

  • no

From version:

3.40.0

Description:

When set to no the session authentication is still available, but it will not be advertised as part of the www-authenticate header.

Note

SSL-specific options are only available for the https service type.

Warning

When the ssl_certificate_authority configuration option is enabled, web browsers should include an SSL certificate signed by the same certificate authority.

5.4.29. headers

Default value:

Empty

Optional:

Yes

Values:

  • Single header with a name and at least one value.

  • Multiple headers, each header on a separate line.

From version:

3.34.0

Description:

This configuration option can be used to extend the list of headers returned by SFTPPlus for each HTTP response.

Each line should start with the header name, followed by :. Each line should end with the header's values.

For example:

[services/9ac4-1054-f0e4]
name = HTTPS File Transfer Service
type = https
headers = Strict-Transport-Security: max-age=1607040; includeSubDomains

You can configure multiple headers by defining each header on a separate line.

Using this configuration option, you can overwrite the Server header, in order to obscure the identity and/or version of SFTPPlus.

If your header contains a comma, you will need to enclose the whole option in double quotation marks:

[services/5300-19d0-92ce]
type = http
headers = "Keep-Alive: timeout=5, max=100"

5.4.30. accepted_origins

Default value:

Empty

Optional:

Yes

Values:

  • Comma-separated values of fully qualified domain names.

  • Comma-separated pairs of FQDN:PORT values.

From version:

3.41.0

Description:

When running behind a load balancer or a reverse proxy, you can configure a list of domain names handled by the load balancer for which SFTPPlus should accept forwarded requests.

When not using standard ports (80 for HTTP and 443 for HTTPS), you will also need to add the port number after the domain name.

You might see 400 Possible CSRF errors if this configuration is not set, as the same-origin policy is broken.

Setting this configuration option will also trigger the session cookie to always be set with the secure attribute.

Leave it empty when SFTPPlus is not behind a load balancer.

5.4.31. client_forwarded_header

Default value:

Empty

Optional:

Yes

Values:

  • empty.

  • Forwarded.

  • X-Forwarded-For.

  • Header name.

From version:

4.14.0

Description:

When running behind a load balancer or a reverse proxy, you can configure the HTTP header to be parsed for the client's source IP address.

When left empty, it will use the low-level TCP connection source address as the source peer for the authenticated user. This is the default value, to be used when clients are connecting directly to SFTPPlus server without using any proxy or balancer.

Set it to X-Forwarded-For to extract the source address from the X-Forwarded-For / XFF header used by many proxies as the de-facto standard. It expects the proxy header in the following format: X-Forwarded-For: <client>, <proxy1>, <proxy2> where proxy1 and proxy2 are optional.

The following custom and X-Forwarded-For IP address formats are supported:

  • 1.2.4.5 - IPv4 without port number

  • 1.2.4.5:6789 - IPv4 with port number

  • 2001:db8::8a2e:370:7334 - IPv6 without port number

  • [2001:db8::8a2e:370:7334] - IPv6 without port number

  • [2001:db8::8a2e:370:7334]:1234 - IPv6 with port number

  • ::ffff:192.0.2.128 - IPv4-mapped IPv6 address without a port number

  • [::ffff:192.0.2.128]:1234 - IPv4-mapped IPv6 address with a port number

Set it to Forwarded, to extract the source address from the Forwarded header as defined in RFC 7238 section 4.

You can set it to any other header name. For example, X-ProxyUser-Ip is the header used by some Google services, while other products might use an X-Forwarded-Host header.

When a header value does not include a port number, port 0 is used as a placeholder.

When a header name is configured and the request is missing that header, the request uses the TCP source address.

If the value of the header is malformed, the request uses the TCP source address.

Warning

If you are not running SFTPPlus behind a proxy or load balancer, leave this configuration empty.

If you are running behind a proxy or load balancer, make sure clients can't bypass the proxy and connect directly to SFTPPlus. Otherwise, clients would be able to spoof/impersonate their source IP addresses.

If the proxy allows chained proxy requests (a client connecting to a proxy that connects to another proxy), make sure the closest proxy to SFTPPlus has a trust relation with all the other chained proxies.

5.4.32. 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.4.33. 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.4.34. 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.4.35. 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.4.36. 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.4.37. 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.4.38. 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.4.39. 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.4.40. 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.4.41. 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.4.42. 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.4.43. 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.4.44. 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.4.45. 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.4.46. 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.4.47. 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.4.48. 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.4.49. 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.4.50. 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.

Note

When clients use a web browser, a single session might generate multiple connections (e.g. one for getting the HTML page, one for its images, another one for its CSS files, etc.) This is why maximum_concurrent_connections is not always equal to the maximum number of concurrent users/sessions/clients.

5.3. SSH (SFTP and SCP)
5.5. HTTP redirection