SFTPPlus Documentation

Start Page 4. Configuration Instructions 4.7. Resources

4.7. Resources

SFTPPlus can interact with various external resources in order to execute related operations, such as sending emails on errors.

The same resource can be shared for different server operations. For example you can use the same email client to send email for both critical errors or to inform about a normal operation.

When a component inside the SFTPPlus requires a resource, and the resource is not already started, that resource is automatically started.

4.7.1. Adding a new resource via Local Manager

A new resource can be added or changed via Local Manager below.

../_images/gallery-add-resource.png

4.7.2. Adding a new resource via text configuration

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

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

For more information about UUIDs see the dedicated UUID documentation.

For example, to add a new resource configuration for an SMTP client called Client for staging SMTP server:

[resource/a904e3a6-a59b-4bbf-8abd-edcae4d3324f]
name = Client for staging SMTP server
description = Send email using the staging SMTP server.
type = email-client
address = 10.0.4.35
port = 25

4.7.3. Generic resource options

While additional options are available (depending on the resource type), each resource configuration section has the following standard configuration options:

4.7.3.1. name

Default value:

‘’

Optional:

No

From version:

3.4.0

Values:
  • Any text.
Description:

Human-readable short string used to identify this resource.

4.7.3.2. description

Default value:

‘’

Optional:

Yes

From version:

3.4.0

Values:
  • Any text.
Description:

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

4.7.3.3. type

Default value:

‘’

Optional:

No

From version:

3.4.0

Values:
  • email-client - Email client configuration.
  • lets-encrypt - Let’s Encrypt ACME client.
  • process-monitor - Monitor computer resources used by SFTPPlus.
Description:

This option specifies the type of the resource.

4.7.4. Email Client

An email-client is configured to allow SFTPPlus to send emails as an SMTP client via a remote SMTP server.

You will need to specify the address or the fully qualified domain name of the SMTP server to use and the value to be used by this client for the From field.

4.7.4.1. address

Default value:

127.0.0.1

Optional:

No

From version:

3.4.0

Values:
  • An IP address or a host name.
Description:

This option specifies the IP address or the host name of the remote server.

4.7.4.2. port

Default value:

25

Optional:

No

From version:

3.4.0

Values:
  • A port number for the server.
Description:

This option specifies the IP port of the remote server.

4.7.4.3. username

Optional:

Yes

Default value:

‘’

Values:
  • Username.
From version:

3.4.0

Description:

Username used to connect to the server.

4.7.4.4. password

Optional:

Yes

Default value:

‘’

Values:
  • Plain text password.
From version:

3.4.0

Description:

Password used to connect to the server.

4.7.4.5. email_from_address

Default value:

no-reply@sftpplus.example.com

Optional:

No

Values:
From version:

3.4.0

Description:

Email address used in the From field of messages sent from this server.

You can specify just an email address or a name and email address.

Note

While you can configure any email address, including one which doesn’t exist, it is recommended to set up a real email address.

In this way, you will receive email delivery errors.

4.7.5. Let’s Encrypt Client / CertBot

The lets-encrypt resource allows SFTPPlus to automatically request SSL / X.509 certificates from Let’s Encrypt’s Certificate Authority.

It acts as an embedded certbot.

Let’s Encrypt is a free, automated, and open certificate authority (CA), run for the public’s benefit. It is a service provided by the Internet Security Research Group (ISRG). It offers everyone a convenient way to get fairly large numbers of SSL/TLS/X.509 certificates, in an automated way, completely for free.

You can find out more about Let’s Encrypt by visiting the dedicated website.

As this page focuses on configuration options, refer to the dedicated Let’s Encrypt operations page.

You can only have a single lets-encrypt resource defined. All the file transfer services will use the same unique lets-encrypt resource.

As part of the lets-encrypt resource configuration you define the general options, while each service which uses Let’s Encrypt certificate will have a dedicated option with the domain for which the certificate is issued .

Below is an example in which three file transfer services define the domain name for Let’s Encrypt:

[resources/9ac4-1054-f0e4]
name = Let's Encrypt Cert Generator
type = lets-encrypt
address = 0.0.0.0
port = 80
acme_url = https://acme-v01.api.letsencrypt.org/directory

[services/1c17-4485-878c]
name = FTPS Explicit
type = ftp
ssl_domains = ftps.files.example.com

[services/17c9-7aa6-2f35]
name = FTPS Implicit
type = ftpsi
ssl_domains = ftps.files.example.com

[services/de43-bc54-342a]
name = HTTPS Service
type = https
ssl_domains = www.files.example.com, files.example.com

4.7.6. enabled

Optional:

Yes

Default value:

Yes

Values:
  • Yes
  • No
From version:

3.42.0

Description:

Set to Yes to have Let’s Encrypt automatically started when SFTPPlus starts.

Set it to No to have the resource stopped.

You can still manually start and stop the resource from the Local Manager.

4.7.7. address

Optional:

No

Default value:

N/A

Values:
  • IPv4 address
  • IPv6 address
  • Fully Qualified Domain Name (FQDN).
  • 0.0.0.0
From version:

3.42.0

Description:

Address on which SFTPPlus’ Let’s Encrypt service will listen for validating the HTTP-01 challenge.

Use 0.0.0.0 to listen on all the available network interfaces.

4.7.8. port

Optional:

No

Default value:

80

Values:
  • Port number.
From version:

3.42.0

Description:

Port on which SFTPPlus’ Let’s Encrypt service will listen for validating the HTTP-01 challenge.

This must be a unique port number for the local machine, to avoid conflicts between different services.

On Unix and Linux systems, a root account is required for using ports below 1024.

4.7.8.1. acme_url

Default value:

https://acme-v01.api.letsencrypt.org/directory

Optional:

No

Values:
  • URL to the ACME Server endpoint.
From version:

3.42.0

Description:

When getting certificates from a server other than the public Let’s Encrypt server, you can use this configuration option to instruct SFTPPlus to use a different ACME server.

Also, you can use it to point to the staging Let’s Encrypt server at https://acme-staging.api.letsencrypt.org/directory. Highly recommended during initial deployment and testing.

Most users don’t need to change this configuration, and should use the default value.

4.7.9. Process Monitor and Alerts

The process-monitor resource is defined in order to monitor at a fixed interval the OS resources used by SFTPPlus.

At the configured interval, a dedicated event containing the usage counters is generated.

Exceptional events are emitted when the usage for a resource hits a certain value / limit. These events can be linked with the email-sender event handler, in order to raise alerts over email.

An example for monitoring resource usage every 2 minutes (120 seconds), triggering an exceptional event when there are more than 1000 total active connections:

[resources/03c4-1caf-fee0]
name = Let's Encrypt Cert Generator
type = process-monitor
monitor_interval = 120
connections_count_trigger = 1000

Note

The process monitor is not available on HP-UX, Solaris, and AIX.

4.7.9.1. monitor_interval

Default value:

60

Optional:

No

Values:
  • Number of seconds
From version:

3.44.0

Description:

Time interval, in seconds, between system resources measurements.

For production environments we recommend setting a value equal to or greater than 60 seconds. Lower values may impact the overall performance of the system.

4.7.9.2. memory_resident_trigger

Default value:

0

Optional:

Yes

Values:
  • Number of bytes
  • 0
From version:

3.44.0

Description:

Amount of resident / non-swapped physical memory used by SFTPPlus, in bytes, for which to emit an exception event if its process is using more than the configured value.

On Windows, it matches the Mem Usage column of the task manager. On other OSes, it matches the RES column of the top command.

Leave it to 0 to disable triggering an event based on the usage of this resource.

4.7.9.3. memory_virtual_trigger

Default value:

0

Optional:

Yes

Values:
  • Number of bytes
  • 0
From version:

3.44.0

Description:

Total amount of virtual memory used by SFTPPlus, in bytes, for which to emit an exception event if its process is using more than the configured value.

This includes both physical memory and swapped memory.

On Windows, it matches the VM Size column of the task manager. On other OSes, it matches the VIRT column of the top command.

Leave it to 0 to disable triggering an event based on the usage of this resource.

4.7.9.4. connection_count_trigger

Default value:

0

Optional:

Yes

Values:
  • Number
  • 0
From version:

3.44.0

Description:

Total number of connections (server-side and client-side) used by SFTPPlus for which to trigger an exceptional event.

This includes the following connection categories: * Incoming connections made to file transfer services * Outgoing connections made to remote servers through configured transfers * Syslog / HTTP Authentication / HTTP Event Handlers connections * Connections made to the Local Manager service.

Leave it to 0 to disable triggering an event based on the usage of this resource.

4.7.9.5. file_count_trigger

Default value:

0

Optional:

Yes

Values:
  • Number
  • 0
From version:

3.44.0

Description:

Total number of local files used by SFTPPlus for which to trigger an exceptional event.

This includes all files opened by SFTPPlus as part of file transfer operations or for administrative operations.

For example, log files used by event handlers are included in this count.

A single connection can trigger the opening of multiple local files.

Leave it to 0 to disable triggering an event based on the usage of this resource.

4.7.9.6. thread_count_trigger

Default value:

0

Optional:

Yes

Values:
  • Number
  • 0
From version:

3.44.0

Description:

Total number of threads used by SFTPPlus for which to trigger an exceptional event.

Take into consideration that multiple transfers can use the same thread.

Leave it to 0 to disable triggering an event based on the usage of this resource.