This section describes how to configure Qumulo Core and watch for file attribute and directory changes by using REST.

Qumulo Core streams notifications to the client by using HTML server-sent events (SSE). For more information about the SSE syntax, see Server-sent events in the HTML Living Standard documentation.

  • The comment syntax—any line that begins with a colon (:)— shows that the call has registered successfully for notifications and periodic keep-alive connections.

  • The data syntax (data: payload) shows the event content.

Qumulo Core continues to stream events until the client closes the connection.

How SSE Event Payloads are Structured for Recursive Notification Requests

An SSE event payload is a JSON-encoded list of notification objects. The following is a format example of the SSE event payload.

[
  {
    "type": "<type>",
    "path": "<path>",
    "spine": ["<file_id_1>", "<file_id_2>", ...],
    "stream_name": "<optional_stream_name>"
  },
  {
  ...
  }
]

  • type: One of the possible notification types.

  • path: The path to the file for which the notification occurred.

    This path is relative to the watched directory.

  • spine: A representation of the file path that uses Qumulo file IDs (rather than path components).

    • The first file ID in the spine is the oldest ancestor in the path.

    • The last file ID in the spine is the file for which the system sends the notification.

  • stream_name: The name of an alternate data stream (ADS) for the file.

    When this value is null, the notification is for the file’s default stream. Otherwise, the notification is for the listed stream.

SSE Payload Notification Types

The following is a list of available notification types in SSE event payloads.

  • The type field shows a single notification type.

  • The filter field shows multiple notification types in comma-separated format.

Notification Type Description
child_acl_changed The ACL for the listed or directory has been modified.
child_atime_changed

The atime (access time) of the listed file or directory has been modified.
child_btime_changed The btime (creation time) of the listed file or directory has been modified.
child_mtime_changed The mtime (modification time) of the listed file or directory has been modified.
child_data_written Data has been written to the listed file.
child_dir_added The listed directory has been created.
child_dir_removed The listed directory has been removed.
child_dir_moved_from

A directory has been moved from the listed location.
child_dir_moved_to

A directory has been moved to the listed location.
child_extra_attrs_changed

The additional attributes for the listed file or directory have been modified.
child_file_added The listed file has been created.
child_file_removed The listed file has been removed.
child_file_moved_from

A file has been moved from the listed location.
child_file_moved_to

A file has been moved from the listed location.
child_group_changed The group for the listed file or directory has been changed.
child_owner_changed The owner for the listed file or directory has been changed.
child_size_changed The size of the listed file has been changed.
child_stream_added The listed alternate data stream (ADS) has been added to the listed file or directory.
child_stream_data_written Data has been written to the listed ADS.
child_stream_moved_from The listed ADS has been moved to the listed file or directory.
child_stream_moved_to The listed ADS has been moved from the listed file or directory.
child_stream_removed The listed ADS has been removed from the listed file or directory.
child_stream_size_changed The size of the listed ADS for the listed file or directory has been changed.
self_removed

The directory from which then system streams notifications has been removed from the file system.

Streaming Change Notifications by Using the qq CLI

Run the qq fs_notify command and specify the path to a directory. For example:

qq fs_notify --path /my/directory

In this example, Qumulo Core streams all notification types for files immediately under the /my/directory directory.

To terminate the stream, send a SIGQUIT signal.

Streaming Change Notifications by Using the Qumulo Core REST API

Make a GET request to the REST endpoint in the following format:

/v1/files/<ref>/notify&filter=<filter>&recursive=<recursive>

In the following example:

  • ref: An absolute path or a numeric file ID for the directory to watch.

  • filter: A comma-separated list of notification types.

  • recursive: When set to true, enables recursive change notifications.

/v1/files/my/directory/notify&filter=child_file_added,child_dir_removed&recursive=true