For systems working alongside unFTP it might be useful to know of FTP related events happening. For this unFTP supports integration with Google Pub/Sub.

Enabling the Pub/Sub integration

You can enable the unFTP Pub/Sub notifier by specifying the --ntf-pubsub-project and --ntf-pubsub-topic arguments.

NOTE: Currently authentication with workload identity is the only supported authentication mechanism.

Here is an example:

unftp \
  --ntf-pubsub-project="my-project" \
  --ntf-pubsub-topic="unftp-events"

The Message Format

The Pub/Sub message sent by unFTP contains meta data (attributes) as shown below and a body in JSON format.

Message attributes:

Message attributes can be used to filter messages messages such that when you receive messages from a subscription with a filter, you only receive the messages that match the filter. unFTP only specifies an eventType attribute:

Key	Value	Description
eventType	One of: - startup - login - logout - get - put - delete - makeDir - rename - removeDir	Indicates the type of event

Message Body

The message body is a JSON object with these fields:

Field	Type	Explanation
source_instance	string	This is the name of the unFTP instance as set by the `--instance-name` variable. Default is 'unFTP'.
hostname	string	The operating system host name where unFTP is running.
payload	Payload Object	More detail on the specific event type. See below.
username	string	The name used during FTP login or "unknown" if not logged in yet.
trace_id	string	A number that uniquely identifies the FTP connection or session.
sequence_number	number	Identifies the position of the event in the sequence of events for the connection.

The Payload Object (payload field) can be one of:

Startup
Login
Logout
Get
Put
Delete
MakeDir
Rename
RemoveDir

All of them are of type JSON object. Examples of their format are shown below.

Example Events

Startup Event:

{
  "source_instance": "unFTP",
  "hostname": "MYMAC-XYZ",
  "payload": {
    "Startup": {
      "libunftp_version": "0.19.1",
      "unftp_version": "v0.14.7"
    }
  }
}

Login Event:

{
  "source_instance": "unFTP",
  "hostname": "MYMAC-XYZ",
  "payload": {
    "Login": {}
  },
  "username": "hannes",
  "trace_id": "0xe25ceb1d960303f3",
  "sequence_number": 1
}

Logout Event:

{
  "source_instance": "unFTP",
  "hostname": "MYMAC-XYZ",
  "payload": {
    "Logout": {}
  },
  "username": "hannes",
  "trace_id": "0xe25ceb1d960303f3",
  "sequence_number": 2
}

Get Event (FTP RETR):

{
  "source_instance": "unFTP",
  "hostname": "MYMAC-XYZ",
  "payload": {
    "Get": {
      "path": "hello.txt"
    }
  },
  "username": "hannes",
  "trace_id": "0x687ee52555459a9c",
  "sequence_number": 2
}

Make Directory Event (FTP MKD):

{
  "source_instance": "unFTP",
  "hostname": "MYMAC-XYZ",
  "payload": {
    "MakeDir": {
      "path": "/x"
    }
  },
  "username": "hannes",
  "trace_id": "0x687ee52555459a9c",
  "sequence_number": 3
}

Rename Event (FTP RNFR and RNTO):

{
  "source_instance": "unFTP",
  "hostname": "MYMAC-XYZ",
  "payload": {
    "Rename": {
      "from": "/x",
      "to": "/y"
    }
  },
  "username": "hannes",
  "trace_id": "0x687ee52555459a9c",
  "sequence_number": 4
}

Put Event (FTP STOR):

{
  "source_instance": "unFTP",
  "hostname": "MYMAC-XYZ",
  "payload": {
    "Put": {
      "path": "x.yaml"
    }
  },
  "username": "hannes",
  "trace_id": "0x687ee52555459a9c",
  "sequence_number": 5
}