SFTPPlus Documentation

Start Page 4. Configuration Instructions 4.3. Local Configuration Manager

4.3. Local Configuration Manager

4.3.1. Introduction

The Local Configuration Manager can be configured in a similar way to any other service provided by SFTPPlus.

This page describes configuring the Local Manager service. For information about using the service, please see (the page on Local Manager operation).

The Local Manager service must be accessed over HTTPS and is enabled by default on port 10020 of the local interface, thus being available only for local connections, typically at https://127.0.0.1:10020.

Note

Since the HTTPS connection used by the Local Manager is secured using a self-signed SSL certificate; all web browsers will prompt to validate the server identity.

You can configure the Local Manager to secure the HTTPS connection using a different SSL certificate, issued by a trusted certificate authority.

By default the Local Manager provides a dedicated administrator account which is not tied to the operating system. More administrator accounts can be created using the Local Manager or by manually editing the configuration file, please see (the page on configuring administrators).

Note

The default account name is admin and the default password is pass. Details are in this dedicated section on changing admin credentials.

Warning

This default admin account is provided for testing and debugging purpose. For production usage, it is highly recommended to change the account name and password or to disable the account.

Besides allowing administrative access to the default application administrator account, the default configuration also allows administrative access for all users from the operating system’s groups Administrators or adm, as these are the default administrative groups for Windows or Unix/Linux operating systems.

The standard configuration file is pre-configured with a Local Manager service having the DEFAULT-MANAGER UUID. To prevent accidental removal, this service cannot be removed from the Local Manager GUI. You can still remove it by manually editing the configuration file.

4.3.2. Local Manager GUI vs text .ini configurations

Everything that can be configured in the Local Manager GUI can also be configured through the text file (server.ini).

A few of the features only available in the SFTPPlus Local Manager are non-configuration related features, such as the visual status page or the SSH / SSL management page.

4.3.3. Disable or stop the main Local Manager service

SFTPPlus allows creating multiple instances of the Local Manager service, as for any file transfer service.

To prevent accidentally deleting or disabling the main Local Manager service with the DEFAULT-MANAGER UUID, these operations are restricted from the Local Manager itself.

To disable the main Local Manager service, restart the server after amending the configuration file to contain the following options:

[services/DEFAULT-MANAGER]
enabled = No

To re-enable the service, restart the server after amending the configuration file as below:

[services/DEFAULT-MANAGER]
enabled = Yes

After authentication in the Local Manager, an administrator can configure the Local Manager from within the web interface.

The rest of this page describes configuration options specific to the Local Manager, as defined in the configuration file.

Local Manager is configured just like any other service provided by the server, and configuration options are stored inside the configuration/server.ini configuration file.

For general information about configuring a service, please see the services configuration page.

4.3.3.1. 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.3.3.2. 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.3.3.3. 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.3.3.4. 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.3.3.5. 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.3.3.6. 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.3.3.7. 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.3.3.8. 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.3.3.9. 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.3.3.10. idle_connection_timeout

Default value:

300

Optional:

Yes

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

1.7.19

To version:

None

Description:

The service will close the connection if a client connection is idle for a configurable amount of time.

4.3.3.11. maximum_concurrent_connections

Default value:

10000

Optional:

Yes

Values:
  • Number of maximum concurrent connections accepted by the service.
  • 0 - To disable the limit.
  • Disabled - To disable the limit.
From version:

1.7.19

To version:

None

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.