7.8. Embedded database¶

7.8.1. Introduction¶

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.

When using the database event handler, SFTPPlus will store / update the newly generated events in an embedded SQLite3 database file.

The default configuration, will store the logs for the last 7 days. You can configure the number of days to meet your log retention policy.

7.8.2. SQLite low-level details¶

The default database is stored in a file named log/server.db3. You can configure this name or configure SFTPPlus to store different log types in separate database files.

Inside the SQLite file, the name of the database used to store the logs is chevah_log_entries. In SQLite, to check all the fields from the table, you can use:

| sqlite> SELECT * FROM sqlite_master WHERE type='table' and
  name='chevah_log_entries';

To prevent excessive filesystem fragmentation, the size of the SQLite file will never decrease. When rows are removed they are marked as removed and will be overwritten with new rows. If you need to claim the free space, you can use the VACUUM command.

To reclaim the disk space, use the VACUUM command:

sqlite> VACUUM ;

You can use the SFTPPlus SQLite file with your own tools and script to implement custom reporting or task.

7.8.3. 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.8.4. cluster_activation¶

Default value:

'all'

Optional:

No

From version:

5.13.0

Values:

• all

• controller

• node

• Node UUID

Description:

When clustering is enabled, it determines on which SFTPPlus instance this component is enabled.

When configured with all, it will be active on any SFTPPlus instance, including the controller and all nodes.

When configured with controller, it will only be active on the SFTPPlus controller instance.

When configured with node, it will be active on all SFTPPlus node instances.

You can configure it with the UUID of a node, to make it active only on that particular node instance.

Note

The enabled configuration is not ignored. When configured with enabled = No this will not be active, regardless of the cluster_activation configuration.

7.8.5. 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.8.6. 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.8.7. 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.8.8. 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.8.9. 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.8.10. 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.8.11. servers¶

Default value:

empty

Optional:

Yes

From version:

5.13.0

Values:

• UUID of an SFTPPlus servers

• Comma-separated list of UUIDs

• all

Description:

This is designed to be used with SFTPPlus cluster deployments.

When configured it will handle events from particular SFTPPlus servers.

When left empty, it will only handle events emitted by the local SFTPPlus server.

When set to all, it will handle events from all SFTPPlus servers.

It can be configured with one or multiple SFTPPlus server UUIDs.

7.8.12. 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.8.13. data_filter¶

Default value:

''

Optional:

Yes

Values:

• Comma-separated list of data member names and filter expressions.

• Multiple expressions, one per line (Since 4.29.0)

• Leave empty to handle all events.

From version:

3.22.0

Description:

Comma separated definition with the 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 value to be matched/filtered 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 based on multiple data members using multiple rules. Each rule is defined on a separate line.

In the following example, events are triggered only if they are uploaded into the directory named reports-A with a size of 0 bytes (empty file):

[event-handlers/b904ed23-a234-4ccf-8abd-edcae4d3324f]
data_filter =
    path, */reports-A/*
    size, 0

Leave this configuration empty to not filter based on the event's attached data, and handle events regardless of their data attributes.

7.8.14. 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.8.15. 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.

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