mmwatch command

Administers clustered watch folder watches.

Synopsis


mmwatch Device list [--events] [--watch-id WatchID] [-Y]

mmwatch Device list --watch-id WatchID --config [-Y]

mmwatch all list [--events] [-Y]

mmwatch all producerRestart -N { NodeName[,NodeName...] | NodeFile | NodeClass } [-q]

mmwatch all status [-Y]

mmwatch Device status [--watch-id WatchID [-v | -Y]]

mmwatch Device enable {-F ConfigFilePath |
          [--fileset FSetName] [--description Description]
          [--events {Event[,Event...] | ALL}]
          --event-handler handlertype
          --sink-brokers BrokerIP:Port[,BrokerIP:Port...]
          --sink-topic Topic
          [--sink-auth-config Path]}

mmwatch Device disable --watch-id {WatchID | all}

Availability

Available with IBM Storage Scale Advanced Edition, IBM Storage Scale Data Management Edition, IBM Storage Scale Developer Edition, or IBM Storage Scale Erasure Code Edition.

Description

The mmwatch command is used to enable, disable, list, and generally administer persistent and fault-tolerant clustered watches. The purpose of clustered watch folder is to monitor file system event activity and produce events to an external event handler, which is referenced as a sink. Errors are logged to /var/adm/ras/mmwatch.log, /var/adm/ras/mmwfclient.log, and /var/log/messages.

Remember: To use this command to enable, disable, and administer clustered watch folder, your cluster code level must be at IBM Spectrum® Scale 5.0.3 or later, and the file system on which the clustered watch folder is set must be at IBM Spectrum Scale 5.0.2 or later.

Parameters

Device

Specifies the device name of the file system upon which the clustered watch folder configuration change or listing is to occur.

Note: You must specify the Device or use the all keyword for mmwatch operations.

all

Lists the active clustered watches for all file systems.

Note: You must specify the Device or use the all keyword for mmwatch operations.

list [--events] [-Y]

Displays the details of active clustered watches for the specified device. The optional --events option lists the monitored clustered watch folder events for each specific watch for the specified device. The -Y parameter provides output in machine-readable (colon-delimited) format.

Note: Fields that have a colon (:) are encoded to prevent confusion. For the set of characters that might be encoded, see the command documentation of mmclidecode. Use the mmclidecode command to decode the field.

producerRestart -N { NodeName[,NodeName...] | NodeFile | NodeClass }

Restarts the producers for all file systems under watch on the nodes specified by the -N option. The -N option supports a comma-separated list of nodes, a full path name to a file containing node names, or a predefined node class.

Note: Issuing this command causes the event producers for file audit logging to be restarted as well.

-q

Suppresses all [I] informational messages.

status

Provides the status of the nodes sending watch events to the external Kafka sink, and is subject to the following:

If all is used in place of a device name, the status is provided for all clustered watches that are enabled within the cluster. If no clustered watches are found, a statement stating this is returned but this scenario is not considered an error.
If a Device is specified without a watch ID, then the status is provided for all clustered watches that are enabled within the cluster associated with that device. If no clustered watches exist for the device, a statement stating this is returned and this is considered an error.
If Device and --watch-id WatchID are both specified, then the status is provided for the single clustered watch that is associated with the given device and watch ID. If the clustered watch cannot be found, a statement stating this is returned and this is considered an error.
Note: The -v flag can only be used when a watch ID is given. It provides up to the last 10 entries for the given watch ID for each component.

enable

Enables a clustered watch for the given device. The scope of the watch is the whole file system unless the --fileset option is provided. If --fileset is provided, then the watch type will be fileset watch for dependent filesets and inode space watch for independent filesets. Enablement entails setting up and validating the configuration, and applying the respective policy partition rules based on the watched events.

-F ConfigFilePath

Specifies the path to the configuration file.

The configuration file is populated with key:value pairs, which include all of the required parameters for enable and any optional fields desired in the following format:

FILESET:<fileset name>
EVENTS:<Event1>,<Event2> | ALL
EVENT_HANDLER:kafkasink
SINK_BROKERS:<sink broker:port>
SINK_TOPIC:<sink topic>
SINK_AUTH_CONFIG:</path/to/auth/config>
WATCH_DESCRIPTION:<description_string>

Note: If this option is given, then the other command line options that are used to enable a watch are invalid and produce a syntax error. Using the --fileset, --events, --event-handler, --sink-brokers, --sink-topic, or --sink-auth-config options in combination with the -F option produces a syntax error.

--fileset FSetName

Specifies the name of the fileset within the given file system to watch. If the fileset is dependent, then the watch type is fileset. No nested filesets are watched within a dependent fileset. If the fileset is independent, then the watch type is inodespace. Only nested dependent filesets are included in the watch of an independent fileset. The --fileset option is optional.

--description Description

The watch description is an optional parameter that identifies how a watch is being used. It can be any combination of letters, numbers, and spaces, but it is limited to 50 total characters.

--config

Displays the configuration details for the specified active watch WatchID.

--events Event[,Event...] | ALL}

Defines a comma-separated string of events to monitor. The --events option is optional. The following events can be watched:

IN_ACCESS
IN_ATTRIB
IN_CLOSE_NOWRITE
IN_CLOSE_WRITE
IN_CREATE
IN_DELETE
IN_DELETE_SELF
IN_MODIFY
IN_MOVED_FROM
IN_MOVED_TO
IN_MOVE_SELF
IN_OPEN

If the --events option is not included, all events are watched.

--event-handler handlertype

The only type of event handler that is currently supported is kafkasink. The --event-handler option is required.

--sink-brokers BrokerIP:Port[,BrokerIP:Port...]

Includes a comma-separated list of broker:port pairs for the sink Kafka cluster (the external Kafka cluster where the events are sent). The --sink-brokers option is required.

When specifying IP addresses in IPv6 format, you must enclose the IP address with []. For example: [2002:90b:e006:86:19:1:186:13]:9092,[2002:90b:e006:86:19:1:186:13]:9092.

--sink-topic Topic

The topic that producers write to in the sink Kafka cluster. The --sink-topic option is required.

--sink-auth-config Path

The full path to the file that contains the authentication details to the sink Kafka cluster. The --sink-auth-config option is optional. For an example of how to use this flag, see Interaction between the clustered watch folder and the external Kafka sink.

disable

Disables a clustered watch for the given device. Disablement removes the configuration and deletes the policy partition rules for the watch.

Exit status

0: Successful completion.
nonzero: A failure occurs.

Security

You must have root authority to run the mmwatch command.

Examples

To list all current clustered watches that are active, issue the following command:

# mmwatch all list

A sample output is as follows:


# mmwatch all list
Filesystem audit1 has 1 watcher(s):
  Cluster ID             WatchID/PID     Type       Start Time                Path      Description
  --------------------------------------------------------------------------------------------------
  10019023689338312536   CLW1601406018   FSYS       Tue Sep 29 15-00-19 2020  /audit1   WatchID1234
Filesystem audit2 has no watchers.
Filesystem fs402 is at an unsupported filesystem level for watch folder.
Filesystem watch1 has 1 watcher(s):
  Cluster ID             WatchID/PID     Type       Start Time                Path      Description
  ---------------------------------------------------------------------------------------------------
  10019023689338312536   CLW1601405441   FSYS       Tue Sep 29 14-50-41 2020  /watch1

To list all current clustered watches with associated events, issue the following command:

# mmwatch all list --events

A sample output is as follows:


# mmwatch all list --events
Filesystem audit1 has 1 watcher(s):
  Cluster ID             WatchID/PID     Monitored Events
  ----------------------------------------------------------------------------------
  10019023689338312536   CLW1601409402   IN_ACCESS,IN_ATTRIB,IN_CLOSE_NOWRITE,IN_CLOSE_WRITE,
                                         IN_CREATE,IN_DELETE,IN_DELETE_SELF,IN_MODIFY,
                                         IN_MOVED_FROM,IN_MOVED_TO,IN_MOVE_SELF,
Filesystem watch1 has 1 watcher(s):
  Cluster ID             WatchID/PID     Monitored Events
  ----------------------------------------------------------------------------------
  10019023689338312536   CLW1601405441   IN_ACCESS,IN_DELETE

To list the current configuration for a clustered watch, issue the following command:

# mmwatch Device list --watch-id WatchID --config

A sample output is as follows:

# mmwatch audit1 list --watch-id CLW1601409402 --config
WATCH_ID:CLW1601409402
DEVICE:audit1
START_TIME:Tue Sep 29 15-56-42 2020
WATCH_PATH:/audit1
EVENTS:ALL
EVENT_HANDLER:kafkasink
SINK_BROKERS:hs22n55:9092
SINK_TOPIC:SpectrumScale_154_6666561368425248142_22_FSYS_fs1_audit
SINK_AUTH_TYPE:NONE
WATCH_TYPE:FSYS
WATCH_DESCRIPTION:WatchID1234

To check the status, issue the following command:

# mmwatch all status

A sample output is as follows:


# mmwatch all status
Device    Watch Path                  Watch ID       Watch State
watch1    /watch1                     CLW1601405441  Active
          Node Name                                          Status
          c35f1m4n07.gpfs.net                                TIPS
          c6f2bc3n10.gpfs.net                                HEALTHY
          c6f2bc3n2.gpfs.net                                 HEALTHY
audit1    /audit1                     CLW1601409402  Active
          Node Name                                          Status
          c35f1m4n07.gpfs.net                                HEALTHY
          c6f2bc3n10.gpfs.net                                HEALTHY
          c6f2bc3n2.gpfs.net                                 HEALTHY

To enable a clustered watch using an input configuration file, issue the following command:

# mmwatch audit1 enable -F audit1_watch_config

Where audit1_watch_config looks like:


# file for creating watch on audit1
EVENTS:ALL
FILESET:ind1
EVENT_HANDLER:kafkasink
SINK_BROKERS:hs22n55.gpfs.net:9092
SINK_TOPIC:SpectrumScale_154_6666561368425248142_22_FSYS_fs1_audit
SINK_AUTH_CONFIG:audit1_auth_file
WATCH_DESCRIPTION:"This_is_my_description"

Enabling an independent fileset displays information similar to the following output:


# mmwatch audit1 enable --event-handler kafkasink --sink-brokers hs22n55:9092 --sink-topic SpectrumScale_154_6666561368425248142_22_FSYS_fs1_audit --description "WatchID1234" --fileset ind1
[I] Beginning enablement of Clustered Watch with newly created watch ID: CLW1601410684
[I] Verified the watch type is INODE for independent fileset ind1
[I] Successfully added Clustered Watch configuration file into CCR for watch: CLW1601410684
[I] Successfully added Clustered Watch configuration in the Spectrum Scale file system: audit1 for watch: CLW1601410684
[I] Successfully added Clustered Watch policy rules for watch: CLW1601410684
[I] Successfully checked or created Clustered Watch global catchall and config fileset skip partitions for watch: CLW1601410684
[I] Successfully checked or created Clustered Watch policy skip partitions for watch: CLW1601410684
[I] Successfully enabled Clustered Watch: CLW1601410684

To disable a clustered watch, issue the following command:

# mmwatch Device disable --watch-id WatchID

A sample output is as follows:


# mmwatch audit1 disable --watch-id CLW1601410684
[I] Successfully checked or deleted Clustered Watch policy skip partitions for watch: CLW1601410684
[I] Successfully removed Clustered Watch policy rules for watch: CLW1601410684
[I] Successfully removed Clustered Watch configuration file from the CCR for watch: CLW1601410684
[I] Successfully removed Clustered Watch configuration directory for watch: CLW1601410684
[I] Successfully checked or removed Clustered Watch global catchall and config fileset skip partitions for watch: CLW1601410684
[I] Successfully disabled Clustered Watch: CLW1601410684

Location

/usr/lpp/mmfs/bin

mmwatch command

Synopsis

Availability

Description

Parameters

Exit status

Security

Examples

See also

Location