mmaddcallback command
Registers a user-defined command that GPFS™ will execute when certain events occur.
Synopsis
mmaddcallback CallbackIdentifier --command CommandPathname
--event Event[,Event...] [--priority Value]
[--async | --sync [--timeout Seconds] [--onerror Action]]
[-N {Node[,Node...] | NodeFile | NodeClass}]
[--parms ParameterString ...]
or
mmaddcallback {-S Filename | --spec-file Filename}
Availability
Available on all IBM Spectrum Scale™ editions.
Description
Use the mmaddcallback command to register a user-defined command that GPFS executes when certain events occur.
The callback mechanism is intended to provide notifications when node and cluster events occur. Invoking complex or long-running commands, or commands that involve GPFS files, may cause unexpected and undesired results, including loss of file system availability. This is particularly true when the --sync option is specified.
Parameters
- CallbackIdentifier
- Specifies a user-defined unique name that identifies the callback. It can be up to 255 characters long. It cannot contain special characters (for example, a colon, semicolon, blank, tab, or comma) and it cannot start with the letters gpfs or mm (which are reserved for GPFS internally defined callbacks).
- --command CommandPathname
- Specifies the full path name of the
executable to run when the event occurs. On Windows, CommandPathname must
be a Korn shell script because it will be invoked in the Cygwin ksh environment.
The executable called by the callback facility must be installed on all nodes on which the callback can be triggered. Place the executable in a local file system (not in a GPFS file system) so that it is accessible even when the GPFS file system is unavailable.
- --event Event[,Event...]
- Specifies a list of events that trigger the callback. The value
defines when the callback is invoked. There are two kinds of events:
global events and local events. A global event triggers a callback
on all nodes in the cluster, such as a nodeLeave event,
which informs all nodes in the cluster that a node has failed. A local
event triggers a callback only on the node on which the event occurred,
such as mounting a file system on one of the nodes.
Table 1 lists the supported global events and their parameters.
Table 2 lists the supported local events and their parameters.
Local events for IBM Spectrum Scale RAID are documented in IBM Spectrum Scale RAID: Administration.
- --priority Value
- Specifies a floating point number that controls the order in which callbacks for a given event are run. Callbacks with a smaller numerical value are run before callbacks with a larger numerical value. Callbacks that do not have an assigned priority are run last. If two callbacks have the same priority, the order in which they are run is undetermined.
- --async | --sync [--timeout Seconds] [--onerror Action]
- Specifies whether GPFS will
wait for the user program to complete and for how long it will wait.
The default is --async (GPFS invokes the command asynchronously). --onerror Action specifies
one of the following actions that GPFS is
to take if the callback command returns a nonzero error code:
- continue
- GPFS ignores the result from executing the user-provided command. This is the default.
- quorumLoss
- The node executing the user-provided command will voluntarily resign as, or refrain from taking over as, cluster manager. This action is valid only in conjunction with the tiebreakerCheck event.
- shutdown
- GPFS will be shut down on the node executing the user-provided command.
- -N {Node[,Node...] | NodeFile | NodeClass}
- Defines the set of nodes on which the callback is invoked. For
global events, the callback is invoked only on the specified set of
nodes. For local events, the callback is invoked only if the node
on which the event occurred is one of the nodes specified by the -N option.
The default is -N all. For general information
on how to specify node names, see Specifying nodes as input to GPFS commands .
This command does not support a NodeClass of mount.
- --parms ParameterString ...
- Specifies parameters to be passed to the executable specified
with the --command parameter. The --parms parameter
can be specified multiple times.
When the callback is invoked, the combined parameter string is tokenized on white-space boundaries. Constructs of the form %name and %name.qualifier are assumed to be GPFS variables and are replaced with their appropriate values at the time of the event. If a variable does not have a value in the context of a particular event, the string UNDEFINED is returned instead.
GPFS recognizes the following variables:- %blockLimit
- Specifies the current hard quota limit in KB.
- %blockQuota
- Specifies the current soft quota limit in KB.
- %blockUsage
- Specifies the current usage in KB for quota-related events.
- %ccrObjectName
- Specifies the name of the modified object.
- %ccrObjectValue
- Specifies the value of the modified object.
- %ccrObjectVersion
- Specifies the version of the modified object.
- %clusterManager[.qualifier]
- Specifies the current cluster manager node.
- %clusterName
- Specifies the name of the cluster where this callback was triggered.
- %ckDataLen
- Specifies the length of data involved in a checksum mismatch.
- %ckErrorCountClient
- Specifies the cumulative number of errors for the client side in a checksum mismatch.
- %ckErrorCountNSD
- Specifies the cumulative number of errors for the NSD side in a checksum mismatch.
- %ckErrorCountServer
- Specifies the cumulative number of errors for the server side in a checksum mismatch.
- %ckNSD
- Specifies the NSD involved.
- %ckOtherNode
- Specifies the IP address of the other node in an NSD checksum event.
- %ckReason
- Specifies the reason string indicating why a checksum mismatch callback was invoked.
- %ckReportingInterval
- Specifies the error-reporting interval in effect at the time of a checksum mismatch.
- %ckRole
- Specifies the role (client or server) of a GPFS node.
- %ckStartSector
- Specifies the starting sector of a checksum mismatch.
- %daName
- Specifies the name of the declustered array involved.
- %daRemainingRedundancy
- Specifies the remaining fault tolerance in a declustered array.
- %diskName
- Specifies a disk or a comma-separated list of disk names for which this callback is triggered.
- %downNodes[.qualifier]
- Specifies a comma-separated list of nodes that are currently down. Only nodes local to the given cluster are listed. Nodes which are in a remote cluster but have temporarily joined the cluster are not included.
- %eventName
- Specifies the name of the event that triggered this callback.
- %eventNode[.qualifier]
- Specifies a node or comma-separated list of nodes on which this callback is triggered. Note that the list may include nodes which are not local to the given cluster, but have temporarily joined the cluster to mount a file system provided by the local cluster. Those remote nodes could leave the cluster if there is a node failure or if the file systems are unmounted.
- %filesLimit
- Specifies the current hard quota limit for the number of files.
- %filesQuota
- Specifies the current soft quota limit for the number of files.
- %filesUsage
- Specifies the current number of files for quota-related events.
- %filesetName
- Specifies the name of a fileset for which the callback is being executed.
- %filesetSize
- Specifies the size of the fileset.
- %fsErr
- Specifies the file system structure error code.
- %fsName
- Specifies the file system name for file system events.
- %hardLimit
- Specifies the hard limit for the block.
- %homeServer
- Specifies the name of the home server.
- %inodeLimit
- Specifies the hard limit of the inode.
- %inodeQuota
- Specifies the soft limit of the inode.
- %inodeUsage
- Specifies the total number of files in the fileset.
- %myNode[.qualifier]
- Specifies the node where callback script is invoked.
- %nodeName
- Specifies the node name to which the request is sent.
- %nodeNames
- Specifies a space-separated list of node names to which the request is sent.
- %pcacheEvent
- Specifies the pcache related events.
- %pdFru
- Specifies the FRU (field replaceable unit) number of the pdisk.
- %pdLocation
- The physical location code of a pdisk.
- %pdName
- The name of the pdisk involved.
- %pdPath
- The block device path of the pdisk.
- %pdPriority
- The replacement priority of the pdisk.
- %pdState
- The state of the pdisk involved.
- %pdWwn
- The worldwide name of the pdisk.
- %prepopAlreadyCachedFiles
- Specifies the number of files that are cached. These number of files are not read into cache because data is same between cache and home.
- %prepopCompletedReads
- Specifies the number of reads executed during a prefetch operation.
- %prepopData
- Specifies the total data read from the home as part of a prefetch operation.
- %prepopFailedReads
- Specifies the number of files for which prefetch failed. Messages are logged to indicate the failure. However, there is no indication about the file names that failed to read.
- %quorumNodes[.qualifier]
- Specifies a comma-separated list of quorum nodes.
- %quotaEventType
- Specifies either the blockQuotaExceeded event or the inodeQuotaExceeded event. These events are related to soft quota limit being exceeded,
- %quotaID
- Specifies the numerical ID of the quota owner (UID, GID, or fileset ID).
- %quotaOwnerName
- Specifies the name of the quota owner (user name, group name, or fileset name).
- %quotaType
- Specifies the type of quota for quota-related events. Possible values are USR, GRP, or FILESET.
- %reason
- Specifies the reason for triggering the event. For the preUnmount and unmount events, the possible values are normal and forced. For the preShutdown and shutdown events, the possible values are normal and abnormal. For all other events, the value is UNDEFINED.
- %requestType
- Specifies the type of request to send to the target nodes.
- %rgCount
- The number of recovery groups involved.
- %rgErr
- A code from a recovery group, where 0 indicates no error.
- %rgName
- The name of the recovery group involved.
- %rgReason
- The reason string indicating why a recovery group callback was invoked.
- %senseDataFormatted
- Sense data for the specific fileset structure error in a formatted string output.
- %senseDataHex
- Sense data for the specific fileset structure error in Big endian hex output.
- %snapshotID
- Specifies the identifier of the new snapshot.
- %snapshotName
- Specifies the name of the new snapshot.
- %softLimit
- Specifies the soft limit of the block.
- %storagePool
- Specifies the storage pool name for space-related events.
- %upNodes[.qualifier]
- Specifies a comma-separated list of nodes that are currently up. Only nodes local to the given cluster are listed. Nodes which are in a remote cluster but have temporarily joined the cluster are not included.
- %userName
- Specifies the user name.
- %waiterLength
- Specifies the length of the waiter in seconds.
Variables recognized by IBM Spectrum Scale RAID are documented in IBM Spectrum Scale RAID: Administration.
Variables that represent node identifiers accept an optional qualifier that can be used to specify how the nodes are to be identified. When specifying one of these optional qualifiers, separate it from the variable with a period, as shown here:
The value for qualifier can be one of the following:variable.qualifier
- ip
- Specifies that GPFS should use the nodes' IP addresses.
- name
- Specifies that GPFS should use fully-qualified node names. This is the default.
- shortName
- Specifies that GPFS should strip the domain part of the node names.
Events and supported parameters
Global event | Supported parameters |
---|---|
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%eventNode |
|
%eventNode |
|
%quorumNodes |
|
N/A |
|
%eventNode |
|
%eventNode |
|
N/A |
Local event | Supported parameters |
---|---|
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %reason |
|
%fsName %filesetName %prepopCompletedReads %prepopFailedReads %prepopAlreadyCachedFiles %prepopData |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%fsName %filesetName %pcacheEvent %homeServer %reason |
|
%ccrObjectName %ccrObjectVersion |
|
%ccrObjectName %ccrObjectValue %ccrObjectVersion |
|
%myNode %rgName %daName %daRemainingRedundancy |
|
%eventName %myNode %waiterLength |
|
%eventName %nodeName |
|
%eventName %diskName %fsName |
|
%filesetName %fsName %filesetSize %softLimit %hardLimit %inodeUsage %inodeQuota %inodeLimit %quotaEventType |
|
%fsName %fsErr %senseDataFormatted %senseDataHex |
|
%storagePool %fsName |
|
%storagePool %fsName %reason %filesetName |
|
%myNode %ckRole %ckOtherNode %ckNSD %ckReason %ckStartSector %ckDataLen %ckErrorCountClient %ckErrorCountServer %ckErrorCountNSD %ckReportingInterval |
|
%myNode %rgName %daName %pdName %pdLocation %pdFru %pdWwn %pdState |
|
%myNode %rgName %daName %pdName %pdLocation %pdFru %pdWwn %pdPath |
|
%myNode %rgName %daName %pdName %pdLocation %pdFru %pdWwn %pdState %pdPriority |
|
%myNode %rgName %daName %pdName %pdLocation %pdFru %pdWwn |
|
%fsName %reason |
|
%myNode %rgName %rgErr %rgCount %rgReason |
|
%myNode %rgName %rgErr %rgCount %rgReason |
|
%reason |
|
N/A |
|
%myNode %rgName %rgErr %rgCount %rgReason |
|
%myNode %rgName %rgErr %rgCount %rgReason |
|
%myNode %rgName %rgErr %rgReason |
|
%myNode %rgName %rgErr %rgReason |
|
%eventName %requestType %nodeNames |
|
%reason |
|
%snapshotID %snapshotName %fsName %filesetName |
|
%fsName %filesetName %quotaId %quotaType %quotaOwnerName %blockUsage %blockQuota %blockLimit %filesUsage %filesQuota %filesLimit |
|
N/A |
|
N/A |
|
N/A |
|
%fsName %filesetName %fsName %quotaId %quotaType %quotaOwnerName %blockUsage %blockQuota %blockLimit %filesUsage %filesQuota %filesLimit |
Options
- -S Filename | --spec-file Filename
- Specifies a file with multiple callback definitions, one per line. The first token on each line must be the callback identifier.
Exit status
- 0
- Successful completion.
- nonzero
- A failure has occurred.
Security
You must have root authority to run the mmaddcallback command.
The node on which the command is issued must be able to execute remote shell commands on any other node in the cluster without the use of a password and without producing any extraneous messages. For more information, see Requirements for administering a GPFS file system.
Examples
- To register command /tmp/myScript to run after GPFS startup, issue this command:
mmaddcallback test1 --command=/tmp/myScript --event startup
The system displays information similar to:mmaddcallback: Propagating the cluster configuration data to all affected nodes. This is an asynchronous process.
- To register a callback on the NFS
servers to export or to unexport a particular file system after it
has been mounted or before it has been unmounted, issue this command:
The system displays information similar to:mmaddcallback NFSexport --command /usr/local/bin/NFSexport --event mount,preUnmount -N nfsserver1, nfsserver2 --parms "%eventName %fsName" --parms "%eventName %fsName"
mmaddcallback: 6027-1371 Propagating the cluster configuration data to all affected nodes. This is an asynchronous process.
Location
/usr/lpp/mmfs/bin