SFTPPlus Documentation

Start Page 4. Configuration Instructions 4.19. Event Handlers

4.19. Event Handlers

4.19.1. Introduction

Event handlers are triggered by server events, and each event handler performs a specific action.

Please see the type configuration option for the list of all supported types of event handlers. For more information on using event handlers, please see the usage instructions page.

The most common event handlers are the ones sending events to a specific destination. Each destination is configured using an event handler. Each event handler has its own configuration and is used for sending the event in a certain format or according to certain rules.

For example, you can configure one event handler to store the logs in automatically rotated files and another one to send the logs to Windows Events or a remote Syslog server.

The server can be configured with an arbitrary number of handlers and you can configure multiple handlers of the same type.

Note

Check the documentation for the type configuration option to get a list of all the supported event handlers.

4.19.2. Adding a new event handler via Local Manager

A new event handler can be added or changed via Local Manager below. Options will differ depending on which event handler is used.

../_images/gallery-add-event-handler.png

4.19.3. Adding a new event handler via text configuration

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

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

For more information about UUIDs, please see the dedicated UUID documentation.

For example, to add a new event handler of type http called Critical Errors to be triggered when events with id 1345 or id 2456 and by user mary or john occur, you could use this configuration example:

[event-handlers/b904ed23-a234-4ccf-8abd-edcae4d3324f]
name = Critical Errors
description = Send critical errors as HTTP notifications using JSON.
type = http
http_content_type = json

target = 1345, 2456
usernames = mary, john

4.19.4. Event handler options

Each event handler configuration has the following options:

4.19.4.1. name

Default value:

‘’

Optional:

No

From version:

2.10.0

Values:
  • Any text.
Description:

Human-readable short text used to identify this event handler.

4.19.4.2. description

Default value:

‘’

Optional:

Yes

From version:

2.10.0

Values:
  • Any text.
Description:

Human-readable text that describes the purpose of this event handler.

4.19.4.3. type

Default value:

‘’

Optional:

No

From version:

2.10.0

Values:
  • file-dispatcher - Dispatch a file into one or multiple paths.
  • http-post - HTTP POST request (unsecured).
  • amend-content - Generates copies of files.
  • local-file - Append events to a file located on the local file system.
  • account-activity - Report the activity of accounts.
  • email-sender - Send emails as an SMTP client.
  • eventlog - Send events to Windows EventLog Service.
  • digital-signature-validation - Validate the digital signature of the files. Only supported on Windows.
  • standard-stream - Send events to standard output.
  • syslog - Local Unix socket or remote IP:PORT address for Syslog.
  • extract-archive - Extract/Uncompressed a file.
  • external-executable - Execute an external script or program.
  • extension - For custom event handlers implemented using our API.
Description:

This option specifies the type of the event handler. Each type has a set of specific configuration options. Please see below for more details.

4.19.4.4. target

Default value:

‘’

Optional:

Yes

Values:
  • Comma separated list of event ids.
  • Comma separated list of event ids starting with an exclamation mark.
  • Leave empty to handle all events.
From version:

2.10.0

Description:

Define a comma separated list of event ids to have the event handler triggered only for those events.

When you want to have it triggered for all the events, excepting a few events you should prefix each event id with the exclamation mark (!).

Leave it empty to handle all events.

Note

Combining the two methods is not supported as the same result can be achieved by allowing only the desired events, all the others will be ignored.

4.19.4.5. groups

Default value:

‘’

Optional:

Yes

Values:
  • Comma separated list of event groups.
  • Comma separated list of event groups starting with an exclamation mark.
  • Empty.
From version:

3.39.0

Description:

Defines the list of event groups for which this handler is active.

When you want to handle all the events, except for the ones from a set of groups, prefix the group names with the exclamation mark (!).

An event can be a member of one or multiple groups. The event is handled if any of its groups is found in the list of configured allowed groups. The event is not handled if any of its groups is found in the list of configured ignored groups (starting with !).

Leave it empty to handle events from all groups.

4.19.4.6. usernames

Default value:

‘’

Optional:

Yes

Values:
  • Comma separated list of usernames.
  • Comma separated list of usernames starting with an exclamation mark.
  • Leave empty to handle all events.
From version:

3.9.0

Description:

Comma separated list of usernames whose events are handled by this event handler. A username can include OS accounts, application accounts, and any accounts accepted by any authentication method including external HTTP accounts.

When you want to have it triggered for all the events, excepting a few events you should prefix each username with the exclamation mark (!).

Leave it empty to handle events from any users or events which are not associated with any user.

4.19.4.7. components

Default value:

‘’

Optional:

Yes

Values:
  • Comma separated list of UUIDs.
  • Comma separated list of UUIDs starting with an exclamation mark.
  • Leave empty to handle all events.
From version:

3.18.0

Description:

Comma separated list of component UUIDs for which events are handled by this event handler.

When you want to have it triggered for all the events, excepting a few events you should prefix each UUID with the exclamation mark (!).

Leave it empty to handle events emitted by any component.

4.19.4.8. source_addresses

Default value:

Empty

Optional:

Yes

Values:
  • Comma separated list of IP addresses.
  • List of IP addresses starting with an exclamation mark.
  • Empty.
From version:

3.40.0

Description:

Comma separated list of source IP addresses of the remote peers, which are handled by this event handler.

When you want to have it triggered for all the addresses, excepting a few addresses you should prefix each address with the exclamation mark (!).

Leave it empty to handle events emitted by any source address.

4.19.4.9. data_filter

Default value:

‘’

Optional:

Yes

Values:
  • Comma separated list of data member name and filter expression.
  • Leave empty to handle all events.
From version:

3.22.0

Description:

Comma separated definition with name of attribute data member and the targeted matching expression.

Data member names are configured with insensitive cases.

For more details about the available expressions see the matching expression documentation.

The following example will extract the to be matched/filtered value from the path data member of the event. The extracted value is then matched against the */folderA/* globbing expression:

[event-handlers/b904ed23-a234-4ccf-8abd-edcae4d3324f]
data_filter = path, */folderA/*

See the usage instructions for more operational details.

You can filter only based on a single data member with a single matching expression.

Leave it empty to not filter based on the event’s attached data.

4.19.4.10. fail_after_errors

Default value:

10

Optional:

Yes

From version:

3.0.0

Values:
  • An integer number greater than 0.
  • 0 Disabled.
Description:

Number of consecutive errors after which the event handler will automatically stop with a failed state.

Setting this to 0 will disable the feature. The event handler will no longer stop regardless of the number of errors encountered.

4.19.5. Local File

To configure an event handler which sends events to a local file system, use the type local-file.

Event entries are appended to the file, and the file can be configured to be rotated by external tools or automatically rotated by the server, based on size or time rules. The log format can be specified using the entry_content configuration option.

Warning

Please enable rotation, otherwise the log file can grow to an extremely large file.

4.19.5.1. path

Default value:

log/server.log

Optional:

No

Values:
  • Local path.
  • Local path with variables.
From version:

2.1.0

Description:

This option specifies the path to a file where the events are to be stored.

You can use a set of variables as part of the path, which will be replaced with actual values once the event handler is started.

For example, to include the hostname in the log file name, you can define it as:

[event-handlers/b904ed23-a234-4ccf-8abd-edcae4d3324f]
path = /var/logs/sftpplus-{host.name}.log

The following variables are supported (case insensitive):

  • {host.name} - The name of the host.
  • {host.fqdn} - The fully qualified domain name of the host.

4.19.5.2. rotate_external

Default value:

No

Optional:

Yes

Values:
  • Yes
  • No
From version:

2.1.0

Description:

This is used when external applications for rotating the files are employed. When this option is set, the server will monitor the file and will reopen the file handler if the file was moved by an external log rotating system.

Note

Rotating log files using external applications is not available on Windows, as the server will always keep a file handler to the log file, which prevents any external application from moving the log file.

4.19.5.3. rotate_at_size

Default value:

0

Optional:

Yes

Values:
  • Number of bytes at which the file will be rotated.
  • Disabled or 0 to disable rotation based on file size.
From version:

2.1.0

Description:

The server can be configured to handle file rotation by itself, based on file size. To enable file rotation based on file size, set this to the size for which the file will be rotated. The size is defined in bytes. For example, to enable file rotation at 10 MB, you will need to set the value of 10,485,760.

Warning

Size based rotation is ignored when either rotate_each or rotate_on is configured.

In order to enable size based rotation it is required to disable these configuration options by setting value Disabled or 0.

4.19.5.4. rotate_each

Default value:

0

Optional:

Yes

Values:
  • 1 day.
  • 4 days.
  • 360 seconds.
  • 60 minutes.
  • 12 hours.
  • 2 midnights.
  • 4 Mondays.
  • Disabled or 0 to disable time-based rotation.
From version:

2.1.0

Description:

To activate file rotation based on time intervals, set this to the time interval at which the file will be rotated.

The rotation is only done when the handler is running.

Warning

The interval is reset each time the product is started. If you have it set for 2 midnights but the product is restarted daily, the file is never rotated.

It is recommended to use the rotate_on configuration option.

The time interval is expressed as an integer number that represent the time amount and a word that represent the time interval type.

The following time interval types are supported:

  • seconds - defines the time interval in seconds.
  • minutes - defines the time interval in minutes.
  • hours - defines the time interval in hours.
  • days - defines the time interval in days.
  • midnights - defines the 00:00 hour of a day.
  • Mondays, Tuesdays, Wednesdays, Thursdays, Fridays, Saturdays, Sundays - defines a day of the week.

For example, 3 midnights means rotate the file every 3rd midnight, and 1 midnight means rotate the file every midnight.

Note

You can use both singular or plural forms of interval types. seconds has the same effect as second and similar behaviour is available for hours, days, etc.

Interval types are not case-sensitive, second having the same behaviour as SECOND.

When file is rotated, the log file (specified in the configuration option path) is renamed, and its new file name is formatted using format which depends on the current time interval type:

  • seconds - log-path.YYYY-MM-DD_HH-MM-SS.
  • minutes - log-path.YYYY-MM-DD_HH-MM.
  • hours - log-path.YYYY-MM-DD_HH.
  • days, midnights, Mondays, Tuesdays, Wednesdays, Thursdays, Fridays, Saturdays, Sundays - log-path.YYYY-MM-DD.

log-path is replaced with the value of configuration option path, YYYY is replaced with the current year, MM is replaced with the current month, DD with the current day of the month, HH with the current hour, MM with minutes and SS with seconds.

For example, if path equals to log/server.log, rotate_each equals to 20 minutes and now is 10th August 2016 (02:17:34), then the rotated file is log/server.log.2016-08-10_02-17.

4.19.5.5. rotate_on

Default value:

Disabled

Optional:

Yes

Values:
  • DAY_NUMBER day-of-month
  • HOUR:MINUTES time-of-day
  • Disabled
From version:

3.13.0

Description:

To configure file rotation based on calendar day or daily at certain time, set this to the calendar day or time at which the file will be rotated.

The rotation is only done when the handler is running. If the handler is stopped at the time of a configured rotation, it will not rotate the file and will only rotate at the next time when it is running.

The calendar day is expressed as an integer number (from 1 to 31) that represents the day of a month and the word ‘day-of-month’.

The time is expressed as two integers separated by double colon, the first representing the hour (from 0 to 23) and the second representing minutes (from 0 to 59).

The file is rotated each month at the start of the specified day or each day at the specified time. When configured with day-of-month the rotation happens at 00:00 / 12AM hour in the rotation day.

If the month doesn’t have the specified calendar day (like February doesn’t have 30th day), the file will be rotated on the last day of the month.

For example, 2 day-of-month means rotate the file on the second day of every month. 14:32 time-of-day means rotate the file every day at 14 / 2PM, 32 minutes and 0 seconds, local time.

31 day-of-month means rotate the file on the last day of every month (i.e. in April, the file would be rotated on 30th April). 30 day-of-month means rotate the file on 30th day of each month (but in February it would be rotated on the last day).

When file is rotated, the base file is renamed, and its new file name is formatted using the following format base-file-name.YYYY-MM-DD for monthly based rotation or base-file-name.YYYY-MM-DDThhmmss.sssss for daily based. base-file-name is replaced with base log file name (e.g. server.log), YYYY is replaced with the current year, MM is replaced with the current month, DD with the current day of the month, hh with the current hour, mm with current minute and ss.ssssss with current second and microsecond.

For example, if the base file name is server.log and today is 10th August 2016, the rotated file is named server.log.2016-08-10. For daily rotation at 14:30, the file is named server.log.2016-08-10T143000.000.

If the rotated log file with such name already exists, then it is replaced by the newest file.

Warning

To enable rotation based on calendar day or time of day it is required to disable configuration options rotate_external and rotate_each.

4.19.5.6. rotate_count

Default value:

0

Optional:

Yes

Values:
  • number
  • 0 to keep all rotated files.
  • -1 to enable rotation in place.
From version:

2.1.0

Description:

This option defines whether to keep all rotated log files, to rotate the log file in place or to keep the only certain amount of rotated log files.

By default, all rotated log files are kept.

If log rotation in place is enabled, then on rotation, the log file content is removed and no rotated file is created.

If it is configured (using an positive integer number) to keep specific number of rotated files, the oldest rotated log files are deleted.

When rotate_at_size is enabled, rotated file names will contain the rotation number appended to the base file name. For example, with this configuration:

[event-handlers/b904ed23-a234-4ccf-8abd-edcae4d3324f]
rotate_count = 5
path = log/app.log

You would get log/app.log, log/app.log.1, log/app.log.2, up to log/app.log.5. The file being written to is always log/app.log.

When rotate_each is enabled, rotated file names will contain YEAR-MONTH-DAY-HOUR-MINUTE-SECOND appended to the base name.

For a file rotated at 2012-04-25 15:34:50 with a base file name log/app.log, the rotated file name will be log/app.log.2012-04-25-15-34-50.

4.19.5.7. entry_content

Default value:

{id} {timestamp.cwa_14051} {component.uuid} {account.name} {account.peer.address}:{account.peer.port} {message}

Optional:

Yes

Values:
  • Format string.
From version:

3.13.0

Description:

The log format can be configured using a format string. By default, every line starts with the event id but this can be changed. For example, to show the date first, only the peer address and a Unix newline:

[event-handlers/b904ed23-v254-4ccf-8abd-edcae4d3324f]
entry_content = {timestamp.cwa_14051} {id} {account.peer.address}
{message} {LF}

If the format string does not end with a newline character ({LF} or {CR}{LF}) it will be added accordingly to the current platform (i.e. LF on Unix and CR+LF on Windows).

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

  • id
  • message
  • account.name
  • account.peer.address
  • account.peer.port
  • account.peer.protocol
  • account.uuid
  • component.name
  • component.uuid
  • data
  • data_json
  • timestamp.cwa_14051
  • timestamp.timestamp

Note

This configuration is ignored if the structured_fields option is set.

4.19.5.8. structured_fields

Default value:

‘’

Optional:

Yes

Values:
  • Comma separated event fields.
From version:

3.21.0

Description:

When this configuration option is defined, the log handler will store log entries in a CSV file with the header being the field names.

The value should be a comma separated list of fields such as:

[event-handlers/b904ed23-v254-4ccf-8abd-edcae4d3324f]
structured_fields = timestamp.cwa_14051, id, account.peer.address,
message

Leaving this option empty disables CSV logging.

The entry_content configuration is ignored when the option is not empty.

Note

When changing this configuration, the header will only be written when it is opening a new file.

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

  • id
  • message
  • account.name
  • account.peer.address
  • account.peer.port
  • account.peer.protocol
  • account.uuid
  • component.name
  • component.uuid
  • data
  • data_json
  • timestamp.cwa_14051
  • timestamp.timestamp

4.19.6. Standard Stream

The standard-stream event handler can be used for formatting the events for the standard output.

4.19.6.1. entry_content

Default value:

{id} {timestamp.cwa_14051} {component.uuid} {account.name} {account.peer.address}:{account.peer.port} {message}

Optional:

Yes

Values:
  • Format string.
From version:

3.31.0

Description:

This option defines the format used to represent the event.

For more information about how to configure the format, check the entry_content option from the Local File event handler.

4.19.7. Windows EventLog Event Handler

SFTPPlus can be configured with multiple Windows EventLog event handlers.

The name configuration option is used as Source Name for the logs.

The name identifier should not include *, ?, - and \ characters. Space characters are allowed.

All events are sent to the Application category using the Informational level.

The Windows Event ID is the same as the general server event ID. For more information on server events, please see Server Events.

Note

Our roadmap includes adding configurable log level options. Please contact us to find out more about our roadmap progress.

Warning

When using the - character in the source name identifier, Windows Event Log Viewer will display an incomplete name as the source. This is a bug in Windows Event Log Viewer, and does not affect the information stored in the log. The detailed view displays accurate data.

4.19.8. HTTP POST Event Handlers

The HTTP POST Event Handler is where you can integrate SFTPPlus with your web resource. To read more, please go to :doc: the Developer Documentation </developer/http-api-event-handler>.

In this section you will find the configuration option available to the http-post event handler.

4.19.8.1. url

Default value:

‘’

Optional:

No

Values:
  • URL
From version:

2.10.0

Description:

Full URL for a resource used to receive the event details. For example: http://www.acme.io/http-post-hook-url

4.19.8.2. username

Default value:

‘’

Optional:

yes

From version:

3.30.0

Values:
  • Text.
Description:

Username used to authenticate to the remote HTTP server.

Leave this value empty in order to leave out HTTP Basic authentication.

Warning

For now, only HTTP Basic authentication is supported. This will send the username and password in clear text.

4.19.8.3. password

Default value:

‘’

Optional:

Yes

From version:

3.30.0

Values:
  • Plain text password.
  • Empty.
Description:

Password associated with the configured username.

4.19.8.4. http_content_type

Default value:

json

Optional:

Yes

Values:
  • json
  • legacy-webadmin
From version:

3.0.0

Description:

Format used to send the event over HTTP.

Use json to send the event as JSON formated. Use legacy-webadmin to send the events to the SFTPPlus WebAdmin server.

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

4.19.8.6. 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.19.8.7. 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.19.8.8. 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.19.8.9. 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.19.8.10. 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.19.8.11. 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.19.8.12. 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.19.8.13. ssl_allowed_methods

Default value:

tlsv1 tlsv1.1 tlsv1.2 tlsv1.3

Optional:

Yes

Values:
  • tlsv1.0
  • tlsv1.1
  • tlsv1.2
  • tlsv1.3
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.
  • 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.

4.19.8.14. extra_data

Default value:

Empty

Optional:

Yes

Values:
  • JSON string with variables.
From version:

3.38.0

Description:

You can configure extra JSON values to be included in the HTTP POST payload. The JSON can be nested and contain multiple objects/dictionaries.

The root JSON object can’t be an array.

JSON key and values can contain variables which will be replaced based on the event’s data.

For example to send the event as an Slack Incoming WebHook message:

[event-handlers/b904ed23-v254-4ccf-8abd-edcae4d3324f]
url = https://hooks.slack.com/services/n2unjSpQQ4L6JIOrHoO9CKXl
extra_data = {
    "text": "{id} {message}"
    "username": "{account.name}"
    }

Below you can find all the available variables.

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

  • id
  • message
  • account.name
  • account.peer.address
  • account.peer.port
  • account.peer.protocol
  • account.uuid
  • component.name
  • component.uuid
  • data
  • data_json
  • timestamp.cwa_14051
  • timestamp.timestamp

Only available for http_content_type = json.

4.19.9. Account Activity Event Handler

This event handler collects last user login information that can be later retrieved and displayed as a report inside the Local Manager.

The logins span across all services configured on the server (FTP, SFTP, Local Manager, etc.).

In order to collect this data, this event handler requires a database with read/write permissions.

The default configuration comes with a pre-defined account activity event handler.

You can disable or remove the pre-defined configuration, and later enable or re-create it.

4.19.9.1. database

Default value:

‘’

Optional:

No

Values:
  • UUID of a database configuration.
From version:

3.0.0

To version:

None

Description:

UUID of the database to store the reports.

4.19.10. Syslog Event Handler

To configure an event handler which sends events to a Syslog server, use the type syslog.

It can send logs to a local Unix socket, for example /dev/log, or to a remote IP:PORT address.

All messages are logged with the daemon facility and info severity. They are formatted conforming to RFC 3164, also known as syslog-bsd. Messages can be plain 7-bit ASCII or UTF-8 encoded.

The process name used when formatting the message is configurable via the [server] option.

When using TCP and the connection to the server is lost, it will try to reconnect and will not handle any event until the connection is established.

4.19.10.1. url

Default value:

Disabled

Optional:

Yes

From version:

3.8.0

Values:
  • file://some-relative/path
  • file:///an/absolute/path
  • tcp://address:port
  • tcp://address
  • udp://address:port
  • udp://address
Description:

This option specifies the location of the Syslog server.

It supports local Unix domain sockets defined as relative or absolute paths, as well as TCP or UDP addresses.

UDP support is implemented based on RFC 5424. When no port is specified for UDP, it will use 514 as the default port.

TCP support is implemented based on RFC 6587 When no port is specified for TCP, it will use 601 as the default port.

4.19.10.2. path

Default value:

Disabled

Optional:

Yes

From version:

3.0.0

Values:
  • A path to a Unix socket.
  • Disabled to not send logs to local files.
Description:

This option specifies the path to Syslog Unix socket.

If you want to send logs to a remote Syslog server, set this option to Disabled and configure the address and port.

Note

This option is ignored if the URL option is set.

Note

This option is deprecated in favor of the URL and will be removed in the next major release.

4.19.10.3. address

Default value:

127.0.0.1

Optional:

Yes

From version:

3.0.0

Values:
  • An IP address or hostname.
Description:

This option specifies the IP address of the remote Syslog server.

Note

This option is ignored if path option is not set to Disabled or when the URL is set.

Note

This option is deprecated in favor of the URL and will be removed in the next major release.

4.19.10.4. port

Default value:

541

Optional:

Yes

From version:

3.0.0

Values:
  • A port number.
Description:

This option specifies the IP port of the remote Syslog server.

Note

This option is ignored if path option is not set to Disabled or when the URL is set.

Note

This option is deprecated in favor of the URL and will be removed in the next major release.

4.19.11. Database

To configure an event handler which persists events into a database, use the type database.

4.19.11.1. database

Default value:

‘’

Optional:

No

Values:
  • UUID of a database configuration.
From version:

3.0.0

Description:

UUID of the database to which the logs are sent.

Note

We strongly discourage using SQLite databases for storing production logs as they can grow quite big and use up a lot of disk space. They are supported for test and trial purposes only.

We recommend using a MySQL database server instead.

4.19.11.2. auto_delete

Default value:

0

Optional:

Yes

Values:
  • Number of days
From version:

3.42.0

Description:

Define the number of days after which older events are automatically removed from the database.

Set it to 0 to keep all events, regardless of their age.

Note

The removal of older entries is done when the handler starts and every 4 hours.

4.19.12. Email Sender

To configure an event handler which sends emails to an SMTP server, use the type email-sender.

The emails will be sent over SMTP or ESMTP and SFTPPlus will act as an SMTP client.

The emails will be sent using a resource of type Email Client.

4.19.12.1. email_client_resource

Default value:

‘’

Optional:

No

Values:
  • UUID for an email client resource.
From version:

3.4.0

Description:

UUID of the email client resource used to send emails.

4.19.12.2. email_to_recipients

Default value:

‘’

Optional:

No

Values:
  • Comma separated list of email addresses.
From version:

3.4.0

Description:

Comma separated list of addresses where to send emails.

4.19.12.3. email_cc

Default value:

‘’

Optional:

Yes

Values:
  • Comma separated list of email addresses.
From version:

3.44.0

Description:

Comma separated list of secondary recipients whose names are visible to one another and to the primary recipients.

Leave it empty to not use CC.

4.19.12.4. email_bcc

Default value:

‘’

Optional:

Yes

Values:
  • Comma separated list of email addresses.
From version:

3.44.0

To version:

None

Description:

Comma separated list of tertiary recipients whose names are invisible to each other and to the primary and secondary recipients.

Leave it empty to not use BCC.

4.19.12.5. email_associated_files

Default value:

Disabled

Optional:

Yes

Values:
  • Disabled.
  • attachment.
From version:

3.18.0

Description:

When set to attachment, an email (as multi-part MIME) is sent with the associated file as an attachment. The file path is taken from the real_path property of an event data.

The maximum allowed file size equals to 5MB. If the file can’t be attached or is larger than 5MB, then the email is not sent and an audit event is created for this failure.

When set to Disabled, an email is sent without an attachment.

4.19.12.6. email_subject

Default value:

[{id}] [{component.name}] New event from SFTPPlus

Optional:

No

Values:
  • Plain text.
From version:

3.4.0

Description:

Template used for the subject field of the sent email.

The email_subject can be configured using a format string like New Event {id} from {account.name}.

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

  • id
  • message
  • account.name
  • account.peer.address
  • account.peer.port
  • account.peer.protocol
  • account.uuid
  • component.name
  • component.uuid
  • data
  • data_json
  • timestamp.cwa_14051
  • timestamp.timestamp

4.19.12.7. email_body

Default value:

[{timestamp.cwa_14051}] {message}{LF}{LF}{data_json}

Optional:

Yes

Values:
  • Plain text.
From version:

3.18.0

Description:

Template used for the body of the sent email.

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

  • id
  • message
  • account.name
  • account.peer.address
  • account.peer.port
  • account.peer.protocol
  • account.uuid
  • component.name
  • component.uuid
  • data
  • data_json
  • timestamp.cwa_14051
  • timestamp.timestamp

Using these variables the email_body can be configured, for example, like the following:

[event-handlers/b9787c72-2c8b-4725-a049-ee628aa0abc1]
email_body = {id} {message}{LF}{LF}{data_json}

4.19.13. Digital Signature Validation

The digital-signature-validation event handler can be configured to check if files have a valid signature.

For now, it only handles signatures designed for comma separated values text files. The signature is distributed as trailing content separated by comma.

The signed file is in the format:

SIGNED_CONTENT,SIGNATURE

It uses the SHA-256 hash function.

The signature validation process is based on the RSA Digital Signature Algorithm PKCS#1 v2.1 also known as RSASSA-PSS and documented in RFC 3447.

New lines in the SIGNED_CONTENT are normalized to Unix new lines LF / \n / 0xA.

If you have a different signature distribution method, please get in touch with us.

When the configured certificate has expired or was revoked the handler will continue to operate and will consider all files as having an invalid signature.

Dedicated events are emitted for valid and invalid signatures.

Note

The Digital Signature Validation event handler will only check files with lines smaller than 16,000 characters. If the file contains longer lines, it will not be validated. This is done to prevent handling accidental binary files.

4.19.13.1. signer_certificate_path

Default value:

‘’

Optional:

No

Values:
  • Path on local file system.
From version:

3.5.0

Description:

Path on the local file system to a PEM encoded X.509 certificate containing the public key of the signer.

4.19.13.2. ssl_certificate_authority

Default value:

Disabled

Optional:

Yes

Values:
  • Path to the PKI certificate file of PKI certificate authorities.
  • Disabled
From version:

3.13.0

Description:

Only certificates signed by one of these CAs are accepted.

The certificate authority file should be stored in PEM format.

When certificate authority check is disabled, the digital signature validation process will use any certificate configured at signer_certificate_path.

4.19.13.3. ssl_certificate_revocation_list

Default value:

Disabled

Optional:

Yes

Values:
  • Relative path on local filesystem.
  • Absolute path on local filesystem.
  • http://example.com/some.crl
  • file:///unix/absolute/test-ca.crl
  • file://unix/relative/test-ca.crl
  • file://c:windowsabsolutetest-ca.crl
  • file://windowsrelativetest-ca.crl
  • Comma separated list of CRL locations.
  • crl-distribution-points
  • Disabled
From version:

3.13.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 in both absolute and relative paths.

Retrieving the CRL over HTTP is also supported. The HTTP request is done using non-persistent HTTP/1.1 connections.

CRL distribution points (CDP) are supported by using the crl-distribution-points configuration value.

When CRL distribution points are configured, the server-side certificate defined at ssl_certificate needs to have the CDP extension. The CDP advertised in the server-side 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.

Note

HTTP redirection is not yet supported.

Set it to Disabled to disable certificate revocation checks.

The certificate revocation list can only be used when the service 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.

Note

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.19.13.4. ssl_certificate_revocation_list_refresh

Default value:

0

Optional:

Yes

Values:
  • Number of seconds.
  • 0 to read at startup and after expiration.
From version:

3.13.0

Description:

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.

It can be configured with the number of seconds after which the local CRL file should be read again.

For example, a value of 86400 means the server will re-read the CRL 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.19.14. File Dispatcher

The file-dispatcher event handler can be configured to handle files to one or multiple directory paths based on a matching expression.

This section describes the available configuration options. For more details about the scenarios in which you can use this event handler, check the file dispatcher usage guide.

4.19.14.1. dispatch_rules

Default value:

‘’

Optional:

No

Values:
  • dispatch-action, file-match-expression, destination-path-1
  • dispatch-action, file-match-expression, path-1, path-2
  • dispatch-action, file-match-expression
  • List of rules, separated by newlines.
From version:

3.5.0

Description:

This is a comma separated configuration value.

First value is the file dispatching action. The supported actions are:

  • move
  • move-with-timestamp
  • rename
  • rename-prepend-unixtime
  • delete
  • copy

Second value is the the full path matching expression. Globbing expression or regular expression can be used. For more details see the matching expression documentation.

The remaining values are paths to which the file is dispatched. The file is dispatched into the configured destinations observing the configured order. Certain actions do not need a destination path.

When regular expressions are used for the path matching configuration, the destination path can be dynamically generated based on regex matching groups. For more details see the file dispatcher usage guide.

You can specify multiple rules, one per line. Leading and trailing spaces are ignored.

4.19.14.2. fallback_rule

Default value:

‘’

Optional:

Yes

Values:
  • dispatch-action, destination-path-1
  • dispatch-action, path-1, path-2
  • dispatch-action
From version:

3.5.0

Description:

This is a comma separated configuration value.

This is a single rule which defines how to dispatch files which were not matched by any of the default rules.

Leave it empty to do nothing for files which don’t match any expression.

First value is the file dispatching action. It supports all actions from dispatch_rules.

The remaining values are paths to which the file is dispatched. The files are dispatched using the same process as for dispatch_rules.

4.19.14.3. dispatch_attribute

Default value:

real_path

Optional:

Yes

Values:
  • Event data member name.
From version:

3.20.0

Description:

This is the name of the event’s data attribute used to get the path or the list of paths which will be dispatched by this event.

This is a case insensitive value.

4.19.14.4. create_destination_folder

Default value:

Disabled

Optional:

Yes

Values:
  • parent
  • Disabled
From version:

3.31.0

Description:

This configuration can be used to instruct SFTPPlus to create the destination folder, in case they do not exist.

This is a case insensitive value.

Set it to parent to create the parent directory of the destination file.

Set it to Disable to not have the destination automatically created and fail when destination does not exist.

4.19.15. Amend File Content

The amend-content event handler can be configured to create a copy of a local file attached to an event, and modify the content of the copied file.

The original file is kept without any change.

For now, this option only supports removing the last line print plain text files.

4.19.15.1. destination_path

Default value:

‘’

Optional:

No

Values:
  • Local filesystem path.
From version:

3.22.0

Description:

Local filesystem path that will store a copy of the file.

4.19.15.2. source_attribute

Default value:

real_path

Optional:

Yes

Values:
  • Event data member name.
From version:

3.22.0

Description:

This is the name of the event’s structured data member used to get the path which will be handled by this event.

This is a case insensitive value.

4.19.16. Extract Archive / Uncompress

The extract-archive event handler can be configured to extract archive / compressed files to a specific destination.

The event handler will automatically detect the format of the source file based on its extension.

The following formats are supported:

  • gzip - extract file-name.ext.gz to file-name.ext.

4.19.16.1. source_attribute

Default value:

real_path

Optional:

Yes

Values:
  • Event data member name.
From version:

3.43.0

Description:

This is the name of the event’s structured data member used to get the path which will be handled by this event.

This is a case insensitive value.

4.19.16.2. destination_path

Default value:

empty

Optional:

Yes

Values:
  • Absolute path on local filesystem.
From version:

3.43.0

Description:

The path where the archive is extracted or files are decompressed.

Leave it empty to extract the files in the same path as the source archive/compressed file.

If the destination path already contains the file which is going to be extracted, the operation fails and the existing file is not overwritten.

4.19.16.3. delete_source_on_success

Default value:

Yes

Optional:

yes

Values:
  • Yes
  • No
From version:

3.43.0

Description:

Whether to delete the source archive after a successful extraction.

If extracting / uncompressing the archive fails, the source is not removed, even when this is set to Yes.

4.19.17. Execute external script or program

The external-executable event handler can be configured to call an external script or program based on an event.

The following environment variables are available to the executed script or program:

EVENT:ID of the event which for which it was called.
HANDLER_UUID:UUID of this event handler.
COMPONENT_UUID:UUID of the SFTPPlus component which has created the event.
TIMESTAMP:Unix timestamp when this event was generated.
PEER:Associated IP and PORT
USER:Associated user / account.
DATA_*:Data members of this event. For example DATA_REAL_PATH or DATA_DETAILS.

4.19.17.1. executable_path

Default value:

‘’

Optional:

No

Values:
  • Local filesystem path.
From version:

3.47.0

Description:

Local filesystem path to the executable.

4.19.17.2. executable_arguments

Default value:

{data.real_path}

Optional:

Yes

Values:
  • Plain text.
  • Variable expression.
From version:

3.47.0

Description:

This configuration defines the arguments used to call the executable.

Make sure the arguments which might contain spaces are enclosed in quotes.

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

  • id
  • message
  • account.name
  • account.peer.address
  • account.peer.port
  • account.peer.protocol
  • account.uuid
  • component.name
  • component.uuid
  • data
  • data_json
  • timestamp.cwa_14051
  • timestamp.timestamp

4.19.17.3. executable_timeout

Default value:

30

Optional:

Yes

Values:
  • Number
From version:

3.47.0

Description:

Number of seconds to allow for the external process to execute before forcefully closing it.

A configured value must be equal to or greater than 1.

4.19.17.4. concurrent_processes

Default value:

2

Optional:

Yes

Values:
  • Number
From version:

3.47.0

Description:

Maximum number of concurrent processes to execute at the same time.

When the event handler is required to handle more events, the remaining events are placed in the queue and executed as soon as possible, making sure that only the configured number or processes are active at the same time.

A configured value must be equal to or greater than 1.

We recommend to set this based on the number of available CPUs.

4.19.18. Extension API

The extension event handler can be configured to allow the creation of custom event handlers implemented using the SFTPPlus API.

The extensions code will be placed inside the extension folder located in the SFTPPlus base installation folder.

This event handler is targeted towards application developers.

4.19.18.1. entry_point

Default value:

empty

Optional:

No

Values:
  • python:dotted.path.EntryClassHandler
From version:

3.28.0

Description:

The API entry point is defined in the format LANGUAGE:DOTTED.ENTRY.POINT,

LANGUAGE is the name of the language in which the extension is written.

DOTTED.ENTRY.POINT as an expression defining the package, module, and class name which will receive the event.

Note

At this moment, the event handler API supports the development of custom handlers based on the Python programming language.

As an example, for the file extension/demo_handler.py defining the DemoEventHandler class, the configuration will be:

entry_point = python:demo_handler.DemoEventHandler

See Python API Event Handler developer documentation for more details about how to use the event handler.