Documentation

7.12. Execute external script or program

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

7.12.1. Introduction

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.

SFTPPlus will only call a maximum of 3 external commands in parallel. External commands that need to be triggered for the generated events are queued and executed one after another. This is done to prevent extreme usage of the OS resources.

Since you can receive 1000 files in a short period of time, launching 1000 operating system sub-processes at the same time can result in blocking the whole operating system by using too much memory or too many processes. For example, with an external executable using 100MB of memory, calling 10 concurrent such jobs would result in a 1GB extra memory usage.

The external-executable event handler is designed to be used as a notification mechanism or for calling external commands that are fast and have low-memory usage. The event handler is not designed to operate as a sub-process manager, nor for handling of long-running or extensive memory usage processes.

If your external executable uses more than 100MB of memory or takes longer than 10 seconds to operate, consider redesigning your system. For example reduce run duration or reduce the run frequency by filtering events with the target and data_filter options).

7.12.2. name

Default value

''

Optional

No

From version

2.10.0

Values
  • Any text.

Description

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

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

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

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

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

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

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

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

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

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

7.12.12. executable_path

Default value

''

Optional

No

Values
  • Local filesystem path.

From version

3.47.0

Description

Local filesystem path to the executable.

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

  • uuid

  • message

  • account.name

  • account.peer.address

  • account.peer.port

  • account.peer.protocol

  • account.peer.family

  • account.uuid

  • component.name

  • component.type

  • component.uuid

  • 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

  • data.DATA_MEMBER_NAME

  • data_json

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

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