This section describes how file system change notifications work in Qumulo Core and explains request filtering, recursion, and the three configuration modes for notification requests.

Qumulo Core can stream file system change notifications to a client whenever someone modifies a file or directory. The client can specify for which directories in the file system to receive notifications and what notification types Qumulo Core sends for these directories.

Qumulo Core supports two protocols for streaming file system change notifications. Both protocols provide roughly the same functionality.

The Qumulo Core notification system guarantees that:

  • The system never misses a notification.

  • The system sends notifications in real time.

  • A client connected to any node in a cluster receives a notification which might originate from any node in the cluster.

  • The system sends notifications in accurate chronological order. (For example, the system doesn’t send a child_file_added event after a child_file_removed event.)

  • In case a client can’t keep up with the amount of events that the system emits, the cluster stops queuing events and produces an error the next time the client attempts to contact the cluster.

How Request Filtering Works

A client can request Qumulo Core to filter notifications. Although available filters differ between protocols, they work in a similar way.

For example, you want to configure a client to receive notifications only about files being created but not deleted. In this scenario, you can make a notification request with the child_file_added filter for your protocol.

How Recursion Works

When you don’t use recursion, the system sends notifications for changes that occur immediately within a target directory (changes to files that are children of the watched directory).

Consider the following example with recursion disabled:

  1. You watch the /a/b directory.

  2. You create the /a/b/f file.

  3. You receive a notification that a user created the /a/b/f file.

  4. You create the /a/b/c/f file.

In this example, you receive no additional notifications.

When you use recursion, the system sends notifications for changes that occur in the sub-tree below the target directory. Both protocols let you use recursion.

If you repeat the previous example scenario with recursion enabled, you receive two notifications:

  • You receive a notification that a user created the /a/b/f file.

  • You receive a notification that a user created the /a/b/c/f file.

Configuration Modes for Notification Requests

Qumulo Core has three global configuration modes that affect all recursive notification requests for both protocols.

  • DISABLED_ERROR: Recursive change notification requests return errors immediately.

  • DISABLED_IGNORE: The system accepts recursive change notification requests but sends notifications only for the top directory that it watches. (The system behaves as if the user doesn’t specify the recursive flag.)

    Use this mode to improve compatibility with applications that request recursive behavior but don’t depend on it.

  • ENABLED: This is the default mode. This mode provides full support for recursive change notification requests. The system pushes notifications for all descendants of the watched directory to the watcher.

To select the configuration mode, use the /v1/file-system/settings/notify REST API or the qq fs_set_notify_settings command.

Supported Functionality

Functionality Supported from Qumulo Core Version
Fully featured REST API for streaming file system notifications 6.0.2
  • Full support for SMB CHANGE_NOTIFY
  • Parity with Windows Server
  • Full support for recursion
  • No limit on maximum directory size
  • Configuration options for controlling recursive behavior
6.0.1
  • Improved compatibility with Windows applications
  • Configuration options for controlling behavior of unsupported features
5.3.3
  • Support for all possible SMB CHANGE_NOTIFY types except for Alternate Data Streams (ADS)
5.3.1
SMB2 CHANGE_NOTIFY support for adding and removing files and directories 5.3.0