4.19. 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 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.
A new event handler can be added or changed via Local Manager below.
Options will differ depending on which event handler is used.
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
timeout = 30
target = 1345, 2456
usernames = mary, john
Each event handler configuration has the following options:
- Default value
''
- Optional
No
- From version
2.10.0
- Values
-
- Description
Human-readable short text used to identify this event handler.
- Default value
''
- Optional
Yes
- From version
2.10.0
- Values
-
- Description
Human-readable text that describes the purpose of this event handler.
- 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.
- 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.
- Default value
''
- Optional
Yes
- Values
-
- 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.
- 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.
- 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.
- Default value
Empty
- Optional
Yes
- Values
-
- 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.
- Default value
''
- Optional
Yes
- Values
-
- 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.
- Default value
10
- Optional
Yes
- From version
3.0.0
- Values
-
- 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.
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.
- Default value
log/server.log
- Optional
No
- Values
-
- 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):
- Default value
No
- 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.
- Default value
0
- Optional
Yes
- Values
-
- 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.
- 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.
- Default value
0
- Optional
Yes
- Values
-
- 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.
- Default value
{timestamp.iso_8601_local} {id} {component.uuid}
{account.name} {account.peer.address}:{account.peer.port}
{message}
- Optional
Yes
- Values
-
- 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:
Note
This configuration is ignored if the structured_fields option is set.
- Default value
''
- Optional
Yes
- Values
-
- 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:
The standard-stream event handler can be used for formatting the events
for the standard output.
- Default value
{timestamp.iso_8601_local} {id} {component.uuid}
{account.name} {account.peer.address}:{account.peer.port}
{message}
- Optional
Yes
- Values
-
- 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.
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.
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.
- Default value
''
- Optional
No
- Values
-
- 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.
- Default value
120
- Optional
Yes
- Values
-
- From version
4.16.0
- Description
Duration, in seconds, to wait for a response from the HTTP server.
If a response is not received during this period, the event handling fails.
- Default value
2
- Optional
Yes
- From version
3.48.0
- Values
-
- 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.
- Default value
10
- Optional
Yes
- From version
3.48.0
- Values
-
- 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.
- Default value
''
- Optional
yes
- From version
3.30.0
- Values
-
- 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.
- Default value
''
- Optional
Yes
- From version
3.30.0
- Values
Plain text password.
Empty.
- Description
Password associated with the configured username.
- 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.
- Default value
Empty
- Optional
Yes
- Values
-
- 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.
- Default value
Empty
- 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).
Empty
- 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 leaving this configuration
option empty.
- Default value
Empty
- Optional
Yes
- Values
-
- 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.
- Default value
Empty
- Optional
Yes
- Values
Password as plain text.
Empty
- 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.
Leave it empty to not use a password for the private key file.
- Default value
Empty
- Optional
Yes
- Values
-
- 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}
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 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.
- Default value
Empty
- Optional
Yes
- Values
-
- 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:
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:
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.
Leave it empty 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.
- Default value
0
- Optional
Yes
- Values
-
- 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.
- Default value
secure
- Optional
Yes
- Values
-
- 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.
When left empty, it will default to the secure configuration.
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.
- Default value
secure
- Optional
Yes
- Values
secure
all
tlsv1.0
tlsv1.1
tlsv1.2
tlsv1.3
- From version
1.7.4
- Description
This defines the comma-separated list of SSL and TLS methods that are
accepted by this component during the secure communication handshake.
Set this to secure to allow only the TLS methods that are currently
considered secure. For now, this is TLS 1.2 and TLS 1.3 but this might
be changed in the future.
Any other configured value is ignored.
Set this to all to allow any supported SSL or TLS method.
Any other configured value is ignored.
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.
Prior to version 4.17.0, this was configured as a space separated value.
- Default value
Empty
- Optional
Yes
- Values
-
- 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.
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.
- Default value
Empty
- Optional
Yes
- From version
3.8.0
- Values
-
- 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.
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.
- Default value
''
- Optional
No
- Values
-
- From version
4.0.0
- Description
UUID of the database to which the logs are sent.
- Default value
0
- Optional
Yes
- Values
-
- 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.
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.
- Default value
''
- Optional
Yes
- Values
-
- 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.
- Default value
''
- Optional
Yes
- Values
-
- 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.
- Default value
''
- Optional
Yes
- Values
-
- 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.
- Default value
Empty
- Optional
Yes
- Values
-
- 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 the empty value, an email is sent without an attachment.
- Default value
[{id}] [{component.name}] New event from SFTPPlus
- Optional
No
- Values
-
- 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:
- Default value
[{timestamp.cwa_14051}] {message}{LF}{LF}{data_json}
- Optional
Yes
- Values
-
- 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:
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}
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.
- 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
execute
ignore
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:
For more details see
the file dispatcher usage guide.
You can specify multiple rules, one per line.
Leading and trailing spaces are ignored.
- Default value
0
- Optional
Yes
- From version
4.5.0
- Values
-
- Description
This is the number of times a failed file dispatching actions is retried.
When set to 0, failed actions are never retried.
- Default value
60
- Optional
Yes
- From version
4.5.0
- Values
-
- 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.
- Default value
30
- Optional
Yes
- Values
-
- From version
4.15.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.
- 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.
- 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.
- Default value
real_path
- Optional
Yes
- Values
-
- 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.
- Default value
0
- Optional
Yes
- Values
-
- 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.
- Default value
Empty
- Optional
Yes
- From version
4.8.0
- Values
-
- 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.
- 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.
- Default value
Empty
- Optional
Yes
- Values
-
- 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.
Leave it empty to not have the destination automatically created and
fail when destination does not exist.
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.
- Default value
{fullname}{archive_extension}
- Optional
Yes
- Values
-
- 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
- Default value
real_path
- Optional
Yes
- Values
-
- 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.
- Default value
empty
- Optional
Yes
- Values
-
- 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.
- 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.
- Default value
Yes
- Optional
yes
- Values
-
- 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.
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.
- Default value
''
- Optional
Yes
- Values
-
- 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.
- Default value
''
- Optional
Yes
- Values
-
- 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.
- Default value
Empty
- Optional
No
- Values
-
- 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.
- Default value
.pgp
- Optional
Yes
- Values
-
- 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.
- 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.
- Default value
real_path
- Optional
Yes
- Values
-
- 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.
- Default value
empty
- Optional
Yes
- Values
-
- 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.
- 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.
- Default value
Yes
- Optional
yes
- Values
-
- 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.
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.
- Default value
''
- Optional
No
- Values
-
- From version
3.47.0
- Description
Local filesystem path to the executable.
- 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:
- Default value
30
- Optional
Yes
- Values
-
- 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.
- Default value
2
- Optional
Yes
- Values
-
- 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.
The rabbitmq event handler is used to trigger an AMQP publish operation
based on an audit event.
- Default value
''
- Optional
No
- Values
-
- 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.
- Default value
''
- Optional
No
- From version
4.10.0
- Values
-
- Description
Username used to authenticate to the remote RabbitMQ server.
- Default value
''
- Optional
No
- From version
4.10.0
- Values
-
- Description
Password associated with the configured username.
- Default value
Empty
- Optional
Yes
- Values
-
- From version
4.10.0
- Description
The name of the exchange where messages are published.
Leave it empty to use the default exchange.
- Default value
Empty
- Optional
Yes
- Values
-
- 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.
- 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:
- Default value
2
- Optional
Yes
- From version
4.10.0
- Values
-
- Description
This is the number of times a failed connection or request or is retried.
When set to 0, requests are never retried.
- Default value
10
- Optional
Yes
- From version
4.10.0
- Values
-
- 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.
- Default value
Empty
- Optional
Yes
- Values
-
- 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.
- Default value
Empty
- 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).
Empty
- 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 leaving this configuration
option empty.
- Default value
Empty
- Optional
Yes
- Values
-
- 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.
- Default value
Empty
- Optional
Yes
- Values
Password as plain text.
Empty
- 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.
Leave it empty to not use a password for the private key file.
- Default value
Empty
- Optional
Yes
- Values
-
- 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}
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 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.
- Default value
Empty
- Optional
Yes
- Values
-
- 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:
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:
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.
Leave it empty 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.
- Default value
0
- Optional
Yes
- Values
-
- 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.
- Default value
secure
- Optional
Yes
- Values
-
- 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.
When left empty, it will default to the secure configuration.
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.
- Default value
secure
- Optional
Yes
- Values
secure
all
tlsv1.0
tlsv1.1
tlsv1.2
tlsv1.3
- From version
1.7.4
- Description
This defines the comma-separated list of SSL and TLS methods that are
accepted by this component during the secure communication handshake.
Set this to secure to allow only the TLS methods that are currently
considered secure. For now, this is TLS 1.2 and TLS 1.3 but this might
be changed in the future.
Any other configured value is ignored.
Set this to all to allow any supported SSL or TLS method.
Any other configured value is ignored.
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.
Prior to version 4.17.0, this was configured as a space separated value.
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.
- Default value
empty
- Optional
No
- Values
-
- 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_event_handler.py defining
the DemoEventHandler class, the configuration will be:
entry_point = python:demo_event_handler.DemoEventHandler
See Python API Event Handler
developer documentation for more details about how to use
the event handler.
- Default value
empty
- Optional
Yes
- Values
-
- 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.