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.
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 example, to add a new event handler of type http
called CriticalErrors to be triggered when events with id
1345 or id 2456 and by user mary or john occur,
you could use this configuration example:
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 !).
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.
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:
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.
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.
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 10MB, 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.
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:32time-of-day means rotate the file
every day at 14 / 2PM, 32 minutes and 0 seconds, local time.
31day-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).
30day-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.
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:
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:
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
account.name
account.peer.address
account.peer.port
account.peer.protocol
account.peer.family
account.uuid
component.name
component.type
component.uuid
timestamp.cwa_14051
timestamp.iso_8601
timestamp.iso_8601_fractional
timestamp.iso_8601_local
timestamp.iso_8601_basic
timestamp.iso_8601_compact
timestamp.timestamp
server.name
server.uuid
data.DATA_MEMBER_NAME
data_json
Note
This configuration is ignored if the structured_fields option is set.
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.
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.
Comma separated list of fully qualified domain names
Empty
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.
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:
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.
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:
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.
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:
file:///unix/absolute/test-ca.crl
file://c:\\windows\\absolute\\test-ca.crl
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:
http://example.com/some.crl
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.
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.
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:
Matching expression (globbing or regular expression)
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.
The following variables (case-insensitive) are provided as context data
containing information about the event being triggered:
id
uuid
message
account.name
account.peer.address
account.peer.port
account.peer.protocol
account.peer.family
account.uuid
component.name
component.type
component.uuid
timestamp.cwa_14051
timestamp.iso_8601
timestamp.iso_8601_fractional
timestamp.iso_8601_local
timestamp.iso_8601_basic
timestamp.iso_8601_compact
timestamp.timestamp
server.name
server.uuid
data.DATA_MEMBER_NAME
data_json
Not available for http_content_type = legacy-webadmin.
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.
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.
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.
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.
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.
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:
Single format for both single file and multi file archives
SINGLE_FILE_FORMAT, MULTI_FILE_FORMAT
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
The extract-archive event handler can be configured to extract
archive / compressed files to a specific destination.
The event handler will automatically detect the format of the source
file based on its extension.
The following formats are supported:
gzip - extract GZ file, e.g. file-name.ext.gz to file-name.ext.
tar - extract content of TAR archive to destination path.
tar.gz - extract content of TAR.GZ archive to destination path.
tar.bz2 - extract content of TAR.BZ2 archive to destination path.
zip - Extract as standard ZIP.
The event handler will fail if the file to be extracted from the archive
already exists.
The handler will fail if the archive has members which are to be extracted
outside of the destination_path or with characters not accepted by the
local filesystem.
For TAR/TAR.GZ/TAR.BZ2 archives, only regular files and directories
are supported.
Symbolic links, device and character files are not supported.
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.
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.
When set to fail and the archive contains at least one member file that
already exist on destination, the extract process fail with a partial
archive extraction.
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.
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.
Comma separated list of fully qualified domain names
Empty
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.
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:
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.
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:
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.
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:
file:///unix/absolute/test-ca.crl
file://c:\\windows\\absolute\\test-ca.crl
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:
http://example.com/some.crl
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.
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.
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:
