4.20. Event Handlers¶

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 dedicated documentation 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.

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

4.20.1. Adding a new event handler ¶

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 section:

[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.20.2. Event handler options ¶

Each event handler configuration has the following options:

4.20.2.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.20.2.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.20.2.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). 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. syslog - Local Unix socket or remote IP:PORT address for Syslog.
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.20.2.4. target ¶

Default value:	empty
Optional:	Yes
Values:	Comma separated list of events ids empty to handle all events
From version:	2.10.0
Description:	Comma separated list of event ids handled by this event handler. Leave it empty to handle all events.

4.20.2.5. usernames ¶

Default value:	empty
Optional:	Yes
Values:	Comma separated list of user names empty to handle all events
From version:	3.9.0
Description:	Comma separated list of usernames whose events are handled by this event handler. An username can include OS accounts, application accounts and any accounts accepted by any authentication method, including external HTTP accounts. Leave it empty to handle events from any users or events which are not associated with any user.

4.20.2.6. 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.20.3. 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

When rotation is not enabled, the log file can grow to an extremely large file.

4.20.3.1. path ¶

Optional:	No
Default value:	log/server.log
Values:	A path to a plain text file for storing the event entries. Disabled to disable the local file event handler.
From version:	2.1.0
Description:	This option specifies where will the plain text events be stored.

4.20.3.2. rotate_external ¶

Optional:	Yes
Default value:	No
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. Attention 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.20.3.3. rotate_at_size ¶

Optional:	Yes
Default value:	0
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.20.3.4. rotate_each ¶

Optional:	Yes
Default value:	0
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 time-based file rotation, set this to the time interval at which the file will be rotated. 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. Tip 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.20.3.5. rotate_on ¶

Optional:	Yes
Default value:	Disabled
Values:	DAY_NUMBER day-of-month Disabled
From version:	3.13.0
Description:	To configure file rotation based on calendar day, set this to the calendar day at which the file will be rotated. 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 file is rotated each month at the start of the specified day. 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. 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. 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 and DD with the current day of the month. 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. 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, it is required to disable configuration options rotate_external and rotate_each.

4.20.3.6. rotate_count ¶

Optional:	Yes
Default value:	0
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 a `rotate_count = 5` and `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.20.3.7. entry_content ¶

Optional:	Yes
Default value:	{id} {timestamp.cwa_14051} {component.uuid} {account.name} {account.peer.address}:{account.peer.port} {message}
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: {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 are provided as context data containing information about the event being logged: id message account.name account.peer.address account.peer.port account.peer.protocol account.uuid component.name component.uuid timestamp.cwa_14051

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

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.

Note

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

4.20.5. HTTP POST Event Handler ¶

An http event handler sends an HTTP POST request to a remote HTTP resource.

To get more details about the request format, please see the dedicated HTTP event handler documentation.

Warning

Event details are transferred using unsecured HTTP connections. Use this method only over private networks.

4.20.5.1. url ¶

Default value:	N/A
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.mocky.io/v2/2ad00713b561 Warning HTTPS URLs are supported, but for now SSL certificates are not validated. SSL certificate validation will be added soon.

4.20.5.2. 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.20.5.3. 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.20.6. 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.20.6.1. database ¶

Optional:	No
Default value:	N/A
Values:	UUID of a database configuration
From version:	3.0.0
To version:	None
Description:	UUID of the database to store the reports.

4.20.7. 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, the INFO severity and 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] name 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.20.7.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.20.7.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 url option is set. Warning This option is deprecated in favor of url and will be removed in the next major release.

4.20.7.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 url is set. Warning This option is deprecated in favor of url and will be removed in the next major release.

4.20.7.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 url is set. Warning This option is deprecated in favor of url and will be removed in the next major release.

4.20.8. Database ¶

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

4.20.8.1. database ¶

Optional:	No
Default value:	N/A
Values:	UUID of a database configuration.
From version:	3.0.0
To version:	None
Description:	UUID of the database to which the logs are sent.

4.20.9. 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.20.9.1. email_client_resource ¶

Optional:	No
Default value:	N/A
Values:	UUID for an email client resource.
From version:	3.4.0
To version:	None
Description:	UUID of the email client resource used to send emails.

4.20.9.2. email_to_recipients ¶

Optional:	No
Default value:	N/A
Values:	Comma separates list of email addresses.
From version:	3.4.0
To version:	None
Description:	Comma separates list of addresses where to send emails.

4.20.9.3. email_subject ¶

Optional:	No
Default value:	N/A
Values:	Plain text.
From version:	3.4.0
To version:	None
Description:	Text used for the subject field of the sent email.

4.20.10. 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.20.10.1. signer_certificate_path ¶

Optional:	No
Default value:	N/A
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.20.10.2. ssl_certificate_authority ¶

Optional:	Yes
Default value:	Disabled
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.20.10.3. ssl_certificate_revocation_list ¶

Optional:	Yes
Default value:	Disabled
Values:	relative path on local filesystem absolute path to 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.20.11. ssl_certificate_revocation_list_refresh ¶

Optional:	Yes
Default value:	0
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.20.12. File Dispatcher ¶

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

A single file can be moved into one or multiple directories, each directory receiving a copy of the original file.

Only events from the group file-operation can be used together with the file-dispatcher event handler since only those events are attached to a path on the local filesystem.

Note

For now, the source file is always removed after dispatched in all the configured folders. If you want to keep a copy of the file in the original path, please get in touch with us.

Attention

Please make sure that you are not attaching this event handler to file events for which the path was not yet closed. In such scenarios the move operation will fail.

4.20.12.1. dispatch_rules ¶

Optional:	No
Default value:	N/A
Values:	dispatch-mode, file-match-expression, destination-path-1 dispatch-mode, file-match-expression, path-1, path-2 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 mode. The supported modes are: move - Copy the source in each destination, deleting the source file in the end. move-with-timestamp - Similar to move but files are copied with a timestamp to prevent overwriting files on destination. 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 matching expression is checked against the full path of the file. For example, when you have files based on the following naming convention INV_NNNN.csv (INV_0023.csv or INV_1202.csv). If you want to match these files in any directory you should use a globbing rule like /INV_.csv. The remaining values are paths to which the file is dispatched. The file is dispatched into the configured destinations observing the configured order. You can specify multiple rules, one per line. Leading and trailing spaces are ignored. The dispatch will stop after the first rule which matches the current filename. Multiple rules are checked in the order of their definition. The file dispatcher will not overwrite existing file and the whole dispatch process will fail if one of the configured destination already contains a file with the same name.

4.20.12.2. fallback_rule ¶

Optional:	Yes
Default value:	‘’
Values:	dispatch-mode, destination-path-1 dispatch-mode, path-1, path-2
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 mode. It supports all the modes 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.

SFTPPlus Documentation

4.20. Event Handlers¶