While operating, SFTPPlus will emit a set of events. Each event has a unique ID and defines a specific operation carried out by the server.
A common action for an event is to send it to one of the supported logging system. In addition, arbitrary actions can be attached to an event by configuring event handlers.
Event handlers are asynchronous / independent components and server operations will continue regardless of the side effects produced by the event handler.
All data used by the event handlers is Unicode, encoded as UTF-8.
The integrated logging system, keeps an audit trail for each action/event produced while performing management tasks or file transfer operations. The server can also send events to a SysLog server or to the Windows EventLog, but after an entry is sent, the server cannot retrieve or manage those logs.
All failure events are part of the failure group.
Internal server errors and errors which should not occur during normal operation are part of the failure and failure-critical groups. All critical failures have a details data field which contains information about the cause of the error.
Configuration errors and other errors which cause one of the components to stop, or prevent it from starting, are part of the failure and failure-high group.
This section describes how the audit trail works in order to help you use it and integrate it as per your requirements. For configuring the audit system, please see event handlers configuration.
Each audit entry contains the following information:
While the plain text log format does not list the structured log data, this is available in the format used for storing audit entries in a database.
Here is an example of text file log format:
20076 2014-06-07 19:44:05 ftp-only-1 Process 0.0.0.0:0 Service “ftp” started on “0.0.0.0:10023” using “ftp” protocol.10033 2014-06-07 19:44:10 ftp-only-1 Unknown 127.0.0.1:51290 New FTP/FTPS client connection made.20009 2014-06-07 19:44:10 ftp-only-1 test_user 127.0.0.1:51290 User authenticated as application account using password credentials.10059 2014-06-07 19:44:10 ftp-only-1 test_user 127.0.0.1:51290 User successfully logged on “/srv/iop_files/test_user” as “/”.10061 2014-06-07 19:44:17 ftp-only-1 test_user 127.0.0.1:51292 Passive transfer requested.10022 2014-06-07 19:44:17 ftp-only-1 test_user 127.0.0.1:51292 Listening on port 9000 for the next passive request.10077 2014-06-07 19:44:17 ftp-only-1 test_user 127.0.0.1:51292 Processing STOR command for file “/remote_put”.
For Syslog the log format conforms to RFC 3164. Here is an example:
<30>Apr 19 18:08:11 host test-server-name: 20156 admin 127.0.0.1:33674 Successfully started event handler “SQLite Event Handler” of type database.<30>Apr 19 18:09:53 host test-server-name: 20156 admin 127.0.0.1:33674 Successfully started event handler “sample-digital-signature” of type digital-signature-validation.<30>Apr 19 18:19:28 host test-server-name: 50002 admin 127.0.0.1:33674 Configuration read from local manager.<30>Apr 19 21:38:34 host test-server-name: 20156 Process 0.0.0.0:0 Successfully started database connector “SQLite” of type sqlite.
Here is an example of structured data attached to an event with ID 10077:
account:
name: test_user
peer:
protocol: TCP
port: 51490
address 127.0.0.1
path: /remote_put
Plain text log files can automatically rotate based on size or date, older files being automatically removed, based on configurable rules. This helps limit the size of a single file and control the total disk space used by the plain text logging system.
Audit entries stored in a database can be viewed and filtered using the Local Manager service.
Note
Currently, there is no option to remove/clean log entries stored in a database from within SFTPPlus.
You can, however, use external tools to remove logs stored in a database.
When an HTTP or HTTPS handler is used, SFTPPlus will initiate a POST client request to the configured URL with a body containing one or more events, together with the identity of the server making the request.
The request body is formatted as JSON.
Each event from the events array contains the following attributes:
| name: | id |
|---|---|
| type: | string |
| optional: | No |
| description: | ID of this account. See Events page for the list of all available events. |
| name: | created |
|---|---|
| type: | string |
| optional: | No |
| description: | Date and time at which this event was created, as Unix timestamp with milliseconds. |
| name: | service_uuid |
|---|---|
| type: | string |
| optional: | No |
| description: | UUID of the service emitting this event. |
| name: | account_uuid |
|---|---|
| type: | string |
| optional: | No |
| description: | UUID of the account for which this event was emitted. Might be null when the event has no associated account. |
| name: | data |
|---|---|
| type: | JSON Object |
| optional: | No |
| description: | Event specific data. See Events page for more details regarding the data available for each event. |
The server contains the following attributes:
| name: | uuid |
|---|---|
| type: | string |
| optional: | No |
| description: | UUID of the server emitting this event. |
The account contains the following attributes:
| name: | uuid |
|---|---|
| type: | string |
| optional: | No |
| description: | UUID of the account emitting this event. In case no account is associated with the event, this will be the special process account. In case the associated account is not yet authenticated this will be the special peer account. |
| name: | name |
|---|---|
| type: | string |
| optional: | No |
| description: | Name of the account emitting this event. |
| name: | peer |
|---|---|
| type: | JSON Object |
| optional: | No |
| description: | Address of the peer attached to this account. This might be a local or remote address, depending on whether the account is used for client side or server side interaction. |
The peer contains the following attributes:
| name: | address |
|---|---|
| type: | string |
| optional: | No |
| description: | IP address of this connection. |
| name: | port |
|---|---|
| type: | integer |
| optional: | No |
| description: | Port number of this connection. |
| name: | protocol |
|---|---|
| type: | string |
| optional: | No |
| description: | Internet suite protocol used for this connection: TCP, UDP. |
The creator contains the following attributes:
| name: | uuid |
|---|---|
| type: | string |
| optional: | No |
| description: | UUID of the server part emitting this event. |
| name: | type |
|---|---|
| type: | string |
| optional: | No |
| description: | Type of the server part emitting this event. |
Below is an example for an request containing two events:
POST /remote/url
Content-Type: application/json
{
"events": [
{
"id": "10025",
"created": "12344535.2341",
"data": {
"path": "/path/of/file/as/seen/by/client",
"details": "Some details about failure."
},
"account": {
"uuid": "0c12a7f9-484a-45de-b622-8a5d96061328",
"name": "mike",
"peer": {
"address": "12.442.23.34",
"port": 2345,
"protocol": "TCP"
}
},
"creator": {
"uuid": "dff314a6-c594-48dc-8e34-5270fd6cb635",
"type": "ssh"
}
},
{
"id": "20040",
"created": "12345245.1245",
"data": {
"subject": "event specific data."
},
"account": {
"uuid": "0c12a7f9-484a-45de-b622-8a5d96061328",
"name": "mike",
"peer": {
"address": "12.442.23.34",
"port": 2355,
"protocol": "TCP"
}
},
"creator": {
"uuid": "dff314a6-c594-48dc-8e34-5270fd6cb635",
"type": "ssh"
}
}
],
"server": {
"uuid": "cc5c804d-0a3c-4c4c-b651-eba6fc3b5902"
}
}
Once the server has successfully received and processed the events, it should respond with HTTP code 200:
Status: 200 OK
When the remote HTTP server is busy and we have to stop sending events, the response should display HTTP code 503 together with a Retry-After header with a value expressed in seconds. The current events are discarded.:
Status: 503 Service Unavailable
Retry-After: 3600
When we cannot get a response from the remote HTTP server (e.g. network failures, remote resource not found, etc.), or the response code is not one of the accepted codes, SFTPPlus will consider that the request has failed.
Failed requests are not retried and the server will stop sending events after the configured number of consecutive failures.
All fields that are displayed in the Past Activity page have an associated, single column, index. The sole exception is the Summary/message field, in order to limit database/table size.