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:

KeyValueDescription
eventTypeOne 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:

FieldTypeExplanation
source_instancestringThis is the name of the unFTP instance as set by the --instance-name variable. Default is 'unFTP'.
hostnamestringThe operating system host name where unFTP is running.
payloadPayload ObjectMore detail on the specific event type. See below.
usernamestringThe name used during FTP login or "unknown" if not logged in yet.
trace_idstringA number that uniquely identifies the FTP connection or session.
sequence_numbernumberIdentifies 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
}

Powered by Doctave