Local file#

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

Introduction #

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.

name #

Default value:

Optional:

From version:

2.10.0

Values:

Any text.

Description:

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

cluster_activation #

Default value:

'all'

Optional:

From version:

5.13.0

Values:

all
controller
node
Pool 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.

Configure it with the UUID of a pool to make it active on all nodes in that pool.

Note

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

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.

type #

Default value:

Optional:

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.

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.

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

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

Before version 6.0.0, this option was named groups. Existing configurations are automatically migrated to event_groups. If both options are configured, the event_groups value is used.

user_groups #

Default value:

Optional:

Yes

Values:

Comma separated list of group or role UUIDs.
Empty.

From version:

5.25.0

Description:

Defines the list of avatar group or role UUIDs for which this handler is active.

For end-user events this matches the account's associated groups. For manager events this matches the administrator's associated roles.

When you want to handle all the events except for a set of groups or roles, prefix each UUID with the exclamation mark (!).

The event is handled if any of the avatar UUIDs is found in the list of configured allowed UUIDs. The event is not handled if any of the avatar UUIDs is found in the list of configured ignored UUIDs.

Leave it empty to handle events from any avatar groups or roles.

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.

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.

pool_uuids #

Default value:

empty

Optional:

Yes

From version:

6.1.0

Values:

UUID of a cluster pool
Comma-separated list of UUIDs
all

Description:

This is designed for SFTPPlus cluster deployments. Select pool names in the Web Manager; the configuration stores their UUIDs.

When configured, this handler processes events from the selected pools.

When left empty, it only handles events emitted by the local server.

When set to all, it handles events from all cluster pools and the local server.

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.

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.

fail_after_errors #

Default value:

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.

path #

Default value:

log/server.log

Optional:

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.

rotate_external #

Default value:

Optional:

Yes

Values:

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.

rotate_at_size #

Default value:

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.

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.

rotate_count #

Default value:

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.

output_format #

Default value:

text

Optional:

Yes

Values:

text
logfmt
csv

From version:

6.1.0

Description:

Selects the serialization format for log entries. The text and logfmt formats use entry_content and ignore structured_fields. The csv format uses only structured_fields and ignores entry_content. For compatibility, when output_format is omitted and structured_fields is not empty, CSV logging is used.

See Logfmt output for examples and formatting rules.

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 timestamp, 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
uuid
message
msg
loglevel
peer.ip
peer.port
account.name
account.email
account.peer.address
account.peer.port
account.peer.protocol
account.peer.family
account.peer.country_code
account.peer.asn_number
account.peer.asn_name
account.uuid
component.name
component.type
component.uuid
server.name
server.uuid
server.instance_name
data.DATA_MEMBER_NAME
data_json
tb

timestamp.cwa_14051
timestamp.iso_8601
timestamp.iso_8601_fractional
timestamp.iso_8601_local
timestamp.iso_8601_basic
timestamp.iso_8601_compact
timestamp.timestamp
timestamp.year_decimal
timestamp.year_no_century
timestamp.month_decimal
timestamp.month_padded
timestamp.day_padded
timestamp.day_decimal
timestamp.day_of_year_padded
timestamp.hour_padded_24
timestamp.hour_decimal_24
timestamp.hour_padded_12
timestamp.hour_decimal_12
timestamp.hour_am_pm
timestamp.minute_padded
timestamp.minute_decimal
timestamp.second_padded
timestamp.second_decimal

msg is an alias for message. loglevel is the event severity: trace, info, warn, error, or critical. It is specified in the event definition and follows the group semantics described in Events, event handlers and the audit trail. The peer field contains only ip and port, copied from account.peer.address and account.peer.port. Events generated by the server process use IP address 0.0.0.0 and port 0. loglevel is included in default event JSON serialization. The msg and peer aliases are excluded. Use {msg}, {loglevel}, {peer.ip}, and {peer.port} in event handler templates.

data_json contains an indented JSON serialization of the event data, excluding tracebacks. It is generated on first use and cached for subsequent requests. tb contains the traceback, or an empty string when there is no traceback. Both are separate from data and available in all event handler templates. Account information is available through account, rather than data.avatar. Tracebacks can contain sensitive information and are omitted from default email, log, and webhook output. To include a traceback, explicitly add {tb} to the template.

DATA_MEMBER_NAME can be any of the supported data attributes specific to each event ID. You can discover the available data attributes as part of the Events reference documentation or the Web Manager Activity log.

Peer information includes an estimated country and the autonomous system (AS) that announces the IP address. country_code is a two-letter country code, asn_number is the AS identifier represented as a string with the ASN prefix (for example, ASN15169), and asn_name is the AS organization name. These values are empty strings for private addresses and addresses without matching information. Country and AS information is resolved locally using a database bundled with SFTPPlus and refreshed for each release. IP geolocation is an estimate and does not identify a person's location. For details, see IP geolocation database.

Note

This configuration is ignored when output_format is csv.

Since version 6.1.0, missing {data.KEY} values produce empty text. Message line breaks are replaced with spaces.

structured_fields #

Default value:

Optional:

Yes

Values:

Comma separated event fields.

From version:

3.21.0

Description:

When output_format is csv, the log handler stores entries in a CSV file with the field names as the header.

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

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

The entry_content configuration is ignored when output_format is csv. Since version 6.1.0, missing {data.KEY} values produce empty CSV fields. For older configurations without output_format, a nonempty structured_fields value continues to enable CSV logging.

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
uuid
message
msg
loglevel
peer.ip
peer.port
account.name
account.email
account.peer.address
account.peer.port
account.peer.protocol
account.peer.family
account.peer.country_code
account.peer.asn_number
account.peer.asn_name
account.uuid
component.name
component.type
component.uuid
server.name
server.uuid
server.instance_name
data.DATA_MEMBER_NAME
data_json
tb

timestamp.cwa_14051
timestamp.iso_8601
timestamp.iso_8601_fractional
timestamp.iso_8601_local
timestamp.iso_8601_basic
timestamp.iso_8601_compact
timestamp.timestamp
timestamp.year_decimal
timestamp.year_no_century
timestamp.month_decimal
timestamp.month_padded
timestamp.day_padded
timestamp.day_decimal
timestamp.day_of_year_padded
timestamp.hour_padded_24
timestamp.hour_decimal_24
timestamp.hour_padded_12
timestamp.hour_decimal_12
timestamp.hour_am_pm
timestamp.minute_padded
timestamp.minute_decimal
timestamp.second_padded
timestamp.second_decimal