Documentation

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 - HTTP POST request (unsecured).
  • local-file - Append events to a file located on the local file system.
  • email-sender - Send emails as an SMTP client.
  • windows-eventlog - Send events to Windows EventLog Service.
  • standard-stream - Send events to standard output.
  • syslog - Local Unix socket or remote IP:PORT address for Syslog.
  • create-archive - Create/Compresses one or more files.
  • extract-archive - Extract/Uncompressed a file.
  • external-executable - Execute an external script or program.
  • openpgp - Encrypt/Decrypt files using OpenPGP.
  • rabbitmq - Publish event to RabbitMQ AMQP 0-9-1 server.
  • 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 rotate_on is configured.

In order to enable size-based rotation it is required to disable the rotate_on configuration option by setting value to Disabled.

4.19.5.4. 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 a 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 rotation. 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 the`rotate_external` configuration option.

4.19.5.5. 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_on 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:00 with a base file name log/app.log, the rotated file name will be log/app.log.2012-04-25-15-34-00.

4.19.5.6. entry_content

Default value:

{timestamp.iso_8601_local} {id} {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-like systems 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_MEMBER_NAME
  • data_json
  • timestamp.cwa_14051
  • timestamp.iso_8601
  • timestamp.iso_8601_fractional
  • timestamp.iso_8601_local
  • timestamp.iso_8601_basic
  • timestamp.iso_8601_compact
  • timestamp.timestamp
  • server.name
  • server.uuid

Note

This configuration is ignored if the structured_fields option is set.

4.19.5.7. 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_MEMBER_NAME
  • data_json
  • timestamp.cwa_14051
  • timestamp.iso_8601
  • timestamp.iso_8601_fractional
  • timestamp.iso_8601_local
  • timestamp.iso_8601_basic
  • timestamp.iso_8601_compact
  • timestamp.timestamp
  • server.name
  • server.uuid

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:

{timestamp.iso_8601_local} {id} {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 event handler.

4.19.8.1. url

Default value:

‘’

Optional:

No

Values:
  • URL
  • Comma separated list of URLs (Since 3.51.0)
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

You can define a fall-back/redundant URL using a comma separates list of URLs. The first URL from the list will be used. When failing to get a response for the first URL, the remaining URLs are tried. Since 3.51.0.

4.19.8.2. retry_count

Default value:

2

Optional:

Yes

From version:

3.48.0

Values:
  • 0
  • Positive integer
Description:

This is the number of times a failed request is retried.

When set to 0, requests are never retried.

The HTTP POST request is retried on connection errors or when the server returns a 5XX HTTP code.

4.19.8.3. retry_increase

Default value:

10

Optional:

Yes

From version:

3.48.0

Values:
  • 0
  • Positive real number
Description:

Number of seconds to add to each wait period before retrying.

This is also the value of the first retry wait period.

When set to 0, there will be no waiting time, a retry is performed right away.

4.19.8.4. 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.5. 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.6. http_content_type

Default value:

json

Optional:

Yes

Values:
  • custom
  • json
  • legacy-webadmin
  • soap
  • xml
From version:

3.0.0

Description:

Format used to send the event over HTTP.

Use custom to send the event as a custom Jinja2 template formated value.

Use json to send the event as JSON formated.

Use soap to send the event as human readable XML SOAP envelope.

Use xml to send the event as machine readable application/xml.

Use legacy-webadmin to send the events to the SFTPPlus WebAdmin server.

4.19.8.7. 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.8. ssl_certificate

Default value:

no-certificate-defined

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).
  • Disabled
From version:

1.6.0

To version:

None

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 setting this configuration option to Disabled.

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

4.19.8.10. 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.11. ssl_certificate_authority

Default value:

Disabled

Optional:

Yes

Values:
  • Absolute path on the local file.
  • Content of the CA chain (Since 3.40.0).
  • ${LETS_ENCRYPT_X3_CA}
  • ${MICROSOFT_IT_CA}
  • ${GO_DADDY_G2_G1}
  • 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 of the Certificate Authorities used to validate the remote peer.

This is used only for certificate-based peer validation. To add the CA certificate for an SSL certificate for this component, simply add it to ssl_certificate, possibly together with other certificates needed to complete the full chain of certificates.

The remote peer identity can only be validated when the remote address is configured using a fully qualified domain name. IP based validation will always fail, this is not a method accepted by the public certificate authorities.

You can 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 defined, this will result in initiating the two-way SSL/TLS authentication/handshake validation. For a successful connection, make sure the remote peer 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.

  • ${GO_DADDY_G2_G1} - For all GoDaddy Certificate Bundles,

    G2 With Cross to G1.

To configure a component to accept the remote 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 remote peer sends a certificate, it is ignored.

This defines the path on the local filesystem to a file containing 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.12. 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.13. 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.14. 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.15. 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.16. expected_response

Default value:

Empty

Optional:

Yes

Values:
  • Empty
  • Matching expression (globbing or regular expression)
From version:

4.2.0

Description:

If the result result of a web-hook is not returned by the server with the HTTP status header, but by the content of the response, you can use this configuration to define an expected expression for a valid response.

You can read more about how to use this configuration :doc: in the HTTP API Developer</developer/http-api-event-handler> documentation page.

Leave this configuration empty to accept any response.

4.19.8.17. headers

Default value:

Empty

Optional:

Yes

Values:
  • Header-Name: Header-Value
  • Multiple headers on separate lines
From version:

4.2.0

Description:

This defines a set of extra headers which are sent with each HTTP request.

4.19.8.18. extra_data

Default value:

Empty

Optional:

Yes

Values:
  • JSON string with variables.
  • EMPTY
From version:

3.38.0

Description:

When left empty the HTTP request is sent using the standard SFTPPlus format associated with each content type.

When this is defined, it will be configured as a template used to send the body of the HTTP request.

When defined for json content, it defines the 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
http_content_type = json
extra_data = {
    "text": "{id} {message}"
    "username": "{account.name}"
    }

To send the event as custom text message:

[event-handlers/b904ed23-v254-4ccf-8abd-edcae4d3324f]
url = https://hooks.slack.com/services/n2unjSpQQ4L6JIOrHoO9CKXl
http_content_type = custom
headers = Content-Type: text/plain
extra_data = New event with ID {id} from {account.name}. {message}

For more details and examples see the HTTP API documentation.

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_MEMBER_NAME
  • data_json
  • timestamp.cwa_14051
  • timestamp.iso_8601
  • timestamp.iso_8601_fractional
  • timestamp.iso_8601_local
  • timestamp.iso_8601_basic
  • timestamp.iso_8601_compact
  • timestamp.timestamp
  • server.name
  • server.uuid

Not available for http_content_type = legacy-webadmin.

You can define a fall-back/redundant URL using a comma separates list of URLs. The first URL from the list will be used. When failing to get a response for the first URL, the remaining URLs are tried.

4.19.9. 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.9.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. The file://PATH configuration is only supported on Linux and macOS.

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. Embedded Database

To configure an event handler which persists events using the embedded SQLite database, use the type database.

Multiple embedded databases can be configured for storing different type of events.

4.19.10.1. path

Default value:

‘’

Optional:

No

Values:
  • Path on the local filesystem.
From version:

4.0.0

Description:

UUID of the database to which the logs are sent.

4.19.10.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.11. 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.11.1. email_to_recipients

Default value:

‘’

Optional:

Yes

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

3.4.0

Description:

Comma separated list of addresses where to send emails.

If this list is not defined, emails will be sent using the general email resource recipients configuration.

4.19.11.2. 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.11.3. 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.11.4. 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.11.5. 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_MEMBER_NAME
  • data_json
  • timestamp.cwa_14051
  • timestamp.iso_8601
  • timestamp.iso_8601_fractional
  • timestamp.iso_8601_local
  • timestamp.iso_8601_basic
  • timestamp.iso_8601_compact
  • timestamp.timestamp
  • server.name
  • server.uuid

4.19.11.6. 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_MEMBER_NAME
  • data_json
  • timestamp.cwa_14051
  • timestamp.iso_8601
  • timestamp.iso_8601_fractional
  • timestamp.iso_8601_local
  • timestamp.iso_8601_basic
  • timestamp.iso_8601_compact
  • timestamp.timestamp
  • server.name
  • server.uuid

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.12. 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.12.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 and event specific 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_MEMBER_NAME
  • data_json
  • timestamp.cwa_14051
  • timestamp.iso_8601
  • timestamp.iso_8601_fractional
  • timestamp.iso_8601_local
  • timestamp.iso_8601_basic
  • timestamp.iso_8601_compact
  • timestamp.timestamp
  • server.name
  • server.uuid

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.12.2. retry_count

Default value:

0

Optional:

Yes

From version:

4.5.0

Values:
  • 0
  • Positive integer
Description:

This is the number of times a failed file dispatching actions is retried.

When set to 0, failed actions are never retried.

4.19.12.3. retry_wait

Default value:

60

Optional:

Yes

From version:

4.5.0

Values:
  • 0
  • Positive integer
Description:

Number of seconds to wait before retrying a failed action.

When set to 0, there will be no waiting time. As soon as a file action fails, it will be retried.

4.19.12.4. 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 rules defined at dispatch_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.12.5. matching_expressions

Default value:

‘’

Optional:

No

Values:
  • attribute name, regular expression
  • List of rules, separated by newlines.
From version:

4.0.0

Description:

This is a comma-separated configuration value.

First value is the name of the attribute from which to collect data for the rename operations.

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

You can specify multiple rules, one per line, to source the rename operation from multiple values. Leading and trailing spaces are ignored.

4.19.12.6. 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.12.7. dispatch_delay

Default value:

0

Optional:

Yes

Values:
  • Number of seconds.
From version:

4.2.0

Description:

Number of seconds to delay the execution of the dispatch action.

If the targeted file no longer exists after the delay, the dispatch execution is canceled and an event is emitted.

Set it to 0 to execute the dispatching right away.

4.19.12.8. destination_temporary_suffix

Default value:

Empty

Optional:

Yes

From version:

4.8.0

Values:
  • Empty.
  • Short text.
Description:

Allows copying or moving a file to the destination using a temporary name, renaming to its initial name once all the file’s content was processed.

Leave it empty to always copy a file to its destination using the original name.

Note

The temporary name is only used for copy or move operations. It it not used for rename or delete operations.

4.19.12.9. overwrite_rule

Default value:

fail

Optional:

Yes

From version:

4.8.0

Values:
  • fail - abort dispatching if destination file already exists.
  • overwrite - always overwrite existing files with the content of the new source files.
  • disable - don’t check for existing file and always try to handle the file.
  • skip - don’t dispatch the source file when destination exists.
Description:

Rule used to decide how to handle the overwriting of an existing file at the destination.

When set to overwrite it will emit an event when the destination file is overwritten.

When set to skip it will not handle the file and the source file is not removed. An event is emitted to inform that the file was skipped.

When set to fail the event handling will fail. The existing file is not overwritten and the source files are not removed.

4.19.12.10. 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.13. Create Archive / Compress

The create-archive event handler can be configured to create an archive based on one or more files associated with the event.

When creating archives of format GZIP (.gz extension) if the associated event has multiple files, it will compress each file as separate archives.

When creating archives of format ZIP (.zip extension) if the associated event has multiple files, it will compress all files as a single archive.

The create archive event handler only handles direct file paths. Recursive directory paths are not yet supported.

4.19.13.1. archive_format

Default value:

zip

Optional:

Yes

Values:
  • zip
  • gzip
From version:

4.7.0

Description:

The format used to create the archive.

The following formats are supported:

  • zip - Standard ZIP file.
  • gzip - GZ archive file - GNU ZIP.

4.19.13.2. archive_name

Default value:

{fullname}{archive_extension}

Optional:

Yes

Values:
  • Single format for both single file and multi file archives
  • SINGLE_FILE_FORMAT, MULTI_FILE_FORMAT
From version:

4.7.0

Description:

This configuration defines the name of the archive to be created.

By default, it is the name of the file to be archived with the archive format extension appended to it. For example for archiving the report.TXT file as GZIP, the resulting archive name is report.TXT.gz.

You can define different configuration options for when the archive contains a single file or multiple files. This is defined using a comma-separated value. The first value is used to define the archive file name for single file archives. The second value is used to define the archive file name for multi file archives.

For example with the following configuration archive_name = ARC_{fullname}-approve{archive_extension} a single file ZIP archive for the file report.TXT is created as ARC_report.TXT-approve.zip.

When multiple files are archived and the configuration contains a single value, the archive name is based on a random member of the files to be archived.

For example with the following configuration archive_name = ARC_{fullname}.zip, {year.decimal}-archive.ZIP a single file ZIP archive for the file report.TXT is created as ARC_report.TXT.zip while a multi file archive is created as 2020-archive.ZIP

When defining the file name format the following placeholders are supported:

  • {fullname} - Name of the single file, including the extension.
  • {archive_extension} - Extension based on the archive format, including the leading dot character.
  • {year.decimal} - Year with century as a decimal number. Example: 2009
  • {year.no_century} - Year without century as a zero-padded decimal number. Example: 09
  • {month.decimal} - Month as a decimal number. Example: 9
  • {month.padded} - Month as a zero-padded decimal number. Example: 09
  • {month.name} - Month as locale’s full name. Example: September
  • {month.abbreviated} - Month as locale’s abbreviated name. Example: Sep
  • {day.padded} - Day of the month as a zero-padded decimal number. Example: 07
  • {day.decimal} - Day of the month as a decimal number. Example: 7
  • {day.of_year_padded} - Day of the year as a zero-padded decimal number. Example: 250
  • {day.name} - Weekday as locale’s full name. Example: Friday
  • {day.abbreviated} - Weekday as locale’s abbreviated name. Example: Fri
  • {hour.padded_24} - Hour (24-hour clock) as a zero-padded decimal number. Example: 16
  • {hour.decimal_24} - Hour (24-hour clock) as a decimal number. Example: 16
  • {hour.padded_12} - Hour (12-hour clock) as a zero-padded decimal number. Example: 04
  • {hour.decimal_12} - Hour (12-hour clock) as a decimal number. Example: 4
  • {hour.am_pm} - Equivalent of either AM or PM.
  • {minute.padded} - Minute as a zero-padded decimal number. Example: 05
  • {minute.decimal} - Minute as a decimal number. Example: 5
  • {second.padded} - Second as a zero-padded decimal number. Example: 04
  • {second.decimal} - Second as a decimal number. Example: 4

4.19.13.3. source_attribute

Default value:

real_path

Optional:

Yes

Values:
  • Event data member name.
From version:

4.7.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.13.4. destination_path

Default value:

empty

Optional:

Yes

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

4.7.0

Description:

The path where the archive is created.

Leave it empty to extract the files in the same path as the source 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.13.5. overwrite_rule

Default value:

fail

Optional:

Yes

From version:

4.7.0

Values:
  • fail - abort transfer if destination file already exists.
  • overwrite - always overwrite existing files with the content of the new source files.
  • disable - don’t check for existing file and always try to transfer the file.
  • skip - don’t transfer the source file when destination exists.
Description:

Rule used to decide how to handle the overwriting of an existing archive at the destination.

When set to overwrite it will emit an event when the destination file is overwritten.

When set to skip it will not handle the file and the source file is not removed. An event is emitted to inform that the file was skipped.

When set to fail the event handling will fail. The existing archive is not overwritten and the source files are not removed.

4.19.13.6. delete_source_on_success

Default value:

Yes

Optional:

yes

Values:
  • Yes
  • No
From version:

4.7.0

Description:

Whether to delete the source files after a successful archive creation.

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

4.19.14. 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 GZ file, e.g. file-name.ext.gz to file-name.ext.
  • tar - extract content of TAR archive to destination path.
  • tar.gz - extract content of TAR.GZ archive to destination path.
  • tar.bz2 - extract content of TAR.BZ2 archive to destination path.
  • zip - Extract as standard ZIP.

The event handler will fail if the file to be extracted from the archive already exists.

The handler will fail if the archive has members which are to be extracted outside of the destination_path or with characters not accepted by the local filesystem.

For TAR/TAR.GZ/TAR.BZ2 archives, only regular files and directories are supported. Symbolic links, device and character files are not supported.

The handler can be associated with events containing a list of files. It will try to handle each file associated with the event and will stop at the first failure.

4.19.14.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.14.2. destination_path

Default value:

empty

Optional:

Yes

Values:
  • Absolute path on the 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.

4.19.14.3. overwrite_rule

Default value:

fail

Optional:

Yes

From version:

4.7.0

Values:
  • fail - abort transfer if destination file already exists.
  • overwrite - always overwrite existing files with the content of the new source files.
  • disable - don’t check for existing file and always try to transfer the file.
  • skip - don’t transfer the source file when destination exists.
Description:

Rule used to decide how to handle the overwriting of an existing file at the destination.

When set to overwrite it will emit an event when the destination file is overwritten.

When set to skip it will not handle the file and the source file is not removed. An event is emitted to inform that the file was skipped.

When set to fail and the archive contains at least one member file that already exist on destination, the extract process fail with a partial archive extraction.

4.19.14.4. 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.14.5. password

Default value:

Empty

Optional:

Yes

Values:
  • Event data member name.
From version:

4.0.0

Description:

This is the password used to decrypt archives.

Leave if empty if the archives are not encrypted.

For ZIP files, only the ZipCrypto / Zip Legacy encryption is supported.

4.19.15. Encrypt / Decrypt using OpenPGP

The openpgp event handler can be configured to encrypt or decrypt files using the OpenPGP standard.

All files with the .pgp or .gpg extensions are decrypted, all the other files are encrypted.

Encrypted files will have the .pgp extension appended to their filename.

The handler can be associated with events containing a list of files. It will try to handle each file associated with the event and will stop at the first failure.

4.19.15.1. encryption_public_keys

Default value:

‘’

Optional:

Yes

Values:
  • ASCII armored public PGP keys
From version:

4.0.0

Description:

Lists of public PGP keys used for the encryption operation.

It can contain one or multiple public PGP keys in printable ASCII format.

Leave it empty if you don’t want to use asymmetric encryption.

4.19.15.2. decryption_private_keys

Default value:

‘’

Optional:

Yes

Values:
  • ASCII armored private PGP keys
From version:

4.0.0

Description:

Lists of private PGP keys used for the decryption operation.

It can contain one or multiple private PGP keys in printable ASCII format.

Leave it empty if you don’t want to use asymmetric encryption.

4.19.15.3. passphrase

Default value:

Empty

Optional:

No

Values:
  • Text
From version:

4.0.0

Description:

Passphrase/password for encrypting/decrypting files using symmetric OpenPGP cryptography.

Leave it empty if you don’t want to use symmetric encryption.

4.19.15.4. encryption_extension

Default value:

.pgp

Optional:

Yes

Values:
  • Text to be appended after the file name.
From version:

4.0.0

Description:

File extension used for the files encrypted by the handler.

Encrypted files will have the configured text appended to the original name.

This value is case-sensitive.

4.19.15.5. encryption_cipher

Default value:

AES128

Optional:

Yes

Values:
  • AES128
  • AES192
  • AES256
  • CAST5
  • 3DES
From version:

4.0.0

Description:

Cipher used for symmetric encryption.

This value is not used when passphrase is not defined, as that is required for symmetric encryption.

This value is case-insensitive.

4.19.15.6. source_attribute

Default value:

real_path

Optional:

Yes

Values:
  • Event data member name.
From version:

4.0.0

Description:

Name of the event’s structured data member used to get the path to be handled.

This is a case-insensitive value.

4.19.15.7. destination_path

Default value:

empty

Optional:

Yes

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

4.0.0

Description:

The path where the resulting files are encrypted/decrypted.

Leave it empty to perform file operations in the path of the source files.

4.19.15.8. overwrite_rule

Default value:

fail

Optional:

Yes

From version:

4.7.0

Values:
  • fail - abort transfer if destination file already exists.
  • overwrite - always overwrite existing files with the content of the new source files.
  • disable - don’t check for existing file and always try to transfer the file.
  • skip - don’t transfer the source file when destination exists.
Description:

Rule used to decide how to handle the overwriting of an existing file at the destination.

When set to overwrite it will emit an event when the destination file is overwritten.

When set to skip it will not handle the file and the source file is not removed. An event is emitted to inform that the file was skipped.

4.19.15.9. delete_source_on_success

Default value:

Yes

Optional:

yes

Values:
  • Yes
  • No
From version:

4.0.0

Description:

Whether to delete the source file after a successful operation.

If encrypting/decrypting the source file fails, the source is not removed, even when this is set to Yes.

4.19.16. 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.16.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.16.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_MEMBER_NAME
  • data_json
  • timestamp.cwa_14051
  • timestamp.iso_8601
  • timestamp.iso_8601_fractional
  • timestamp.iso_8601_local
  • timestamp.iso_8601_basic
  • timestamp.iso_8601_compact
  • timestamp.timestamp
  • server.name
  • server.uuid

4.19.16.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.16.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.17. RabbitMQ AMQP 0-9-1 Publisher

The rabbitmq event handler is used to trigger an AMQP publish operation based on an audit event.

4.19.17.1. url

Default value:

‘’

Optional:

No

Values:
  • URL
  • Comma separated list of URLs
From version:

4.10.0

Description:

URL, without username and password for the RabbitMQ server.

The username and password are configured as separate values for audit and security considerations.

Use amqp://host:port/virtual_host for non-TLS connections. Use amqps://host:port/virtual_host for TLS connections.

When port is not specified it will use port 5672 for non-TLS and port 5671 for TLS connections.

When virtual_host is not specified, it will use the default virtual host.

4.19.17.2. username

Default value:

‘’

Optional:

No

From version:

4.10.0

Values:
  • Text.
Description:

Username used to authenticate to the remote RabbitMQ server.

4.19.17.3. password

Default value:

‘’

Optional:

No

From version:

4.10.0

Values:
  • Plain text password.
Description:

Password associated with the configured username.

4.19.17.4. exchange

Default value:

Empty

Optional:

Yes

Values:
  • Text value
From version:

4.10.0

Description:

The name of the exchange where messages are published.

Leave it empty to use the default exchange.

4.19.17.5. routing_key

Default value:

Empty

Optional:

Yes

Values:
  • Text value
From version:

4.10.0

Description:

The value of the routing key used when publishing the message.

In the most simple case, this is the name of a RabbitMQ queue.

4.19.17.6. payload_template

Default value:
Optional:

No

Values:
  • Static text value
  • Format string
From version:

4.10.0

Description:

The payload of the published message itself.

It can be a static text value used for all the events.

You can also generate dynamic payloads based on event data.

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_MEMBER_NAME
  • data_json
  • timestamp.cwa_14051
  • timestamp.iso_8601
  • timestamp.iso_8601_fractional
  • timestamp.iso_8601_local
  • timestamp.iso_8601_basic
  • timestamp.iso_8601_compact
  • timestamp.timestamp
  • server.name
  • server.uuid

4.19.17.7. retry_count

Default value:

2

Optional:

Yes

From version:

4.10.0

Values:
  • 0
  • Positive integer
Description:

This is the number of times a failed connection or request or is retried.

When set to 0, requests are never retried.

4.19.17.8. retry_increase

Default value:

10

Optional:

Yes

From version:

4.10.0

Values:
  • 0
  • Positive real number
Description:

Number of seconds to add to each wait period before retrying.

This is also the value of the first retry wait period.

When set to 0, there will be no waiting time, a retry is performed right away.

4.19.17.9. 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.17.10. ssl_certificate

Default value:

no-certificate-defined

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).
  • Disabled
From version:

1.6.0

To version:

None

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 setting this configuration option to Disabled.

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

4.19.17.12. 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.17.13. ssl_certificate_authority

Default value:

Disabled

Optional:

Yes

Values:
  • Absolute path on the local file.
  • Content of the CA chain (Since 3.40.0).
  • ${LETS_ENCRYPT_X3_CA}
  • ${MICROSOFT_IT_CA}
  • ${GO_DADDY_G2_G1}
  • 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 of the Certificate Authorities used to validate the remote peer.

This is used only for certificate-based peer validation. To add the CA certificate for an SSL certificate for this component, simply add it to ssl_certificate, possibly together with other certificates needed to complete the full chain of certificates.

The remote peer identity can only be validated when the remote address is configured using a fully qualified domain name. IP based validation will always fail, this is not a method accepted by the public certificate authorities.

You can 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 defined, this will result in initiating the two-way SSL/TLS authentication/handshake validation. For a successful connection, make sure the remote peer 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.

  • ${GO_DADDY_G2_G1} - For all GoDaddy Certificate Bundles,

    G2 With Cross to G1.

To configure a component to accept the remote 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 remote peer sends a certificate, it is ignored.

This defines the path on the local filesystem to a file containing 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.17.14. 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.17.15. 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.17.16. 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.17.17. 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.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.

4.19.18.2. configuration

Default value:

empty

Optional:

Yes

Values:
  • Free text
From version:

4.0.0

Description:

A text value which is passed to the event handler together with each event.

You can set it as JSON for structured data or BASE64 for binary data and decode it in the event handler.