mmafmctl command

Availability

Available on all IBM Spectrum Scale editions. Available on AIX® and Linux.

Description

The usage of options of this command for different operations on both AFM (RO/SW/IW/LU) filesets and AFM primary/secondary filesets are explained with examples.

File system should be mounted on all gateway nodes for mmafmctl functions to work.

Parameters

Device

Specifies the device name of the file system.

-j FilesetName

Specifies the fileset name.

-Y

Displays the command output in a parseable format with a colon (:) as a field delimiter. Each column is described by a header.

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.

-s LocalWorkDirectory

Specifies the temporary working directory.

mmafmctl Device {resync | expire | unexpire | stop|start} -j FilesetName 

resync

This option is available only for SW cache. In case of inadvertent changes made at home of an SW fileset, such as delete of a file or change of data in a file etc., the administrator can correct the home by sending all contents from cache to home using this option. The limitation of this option that renamed files at home may not be fixed by resync. Using resync requires the cache to be either in NeedsResync or Active state.

expire | unexpire

This option is available only for RO cache to manually expire or unexpire. When an RO cache is disconnected, the cached contents are still accessible for the user. However, the administrator can define a timeout from home beyond which access to the cached contents becomes stale. Such an event would occur automatically after disconnection (when cached contents are no longer accessible) and is called expiration; the cache is said to be expired. This option is used to manually force the cache state to 'Expired'. To expire a fileset manually, the afmExpirationTimeout must be set on the fileset.

When the home comes back or reconnects, the cache contents become automatically accessible again and the cache is said to un-expire. The unexpire option is used to force cache to come out of the 'Expired' state.

The manual expiration and un-expiration can be forced on a cache even when the home is in a connected state. If a cache is expired manually, the same cache must be unexpired manually.

stop

Run on an AFM or AFM DR fileset to stop replication. You can use this command during maintenance or downtime, when the I/O activity on the filesets is stopped, or is minimal. After the fileset moves to a 'Stopped' state, changes or modifications to the fileset are not sent to the gateway node for queuing.

start

Run on a 'Stopped' AFM or AFM DR fileset to start sending updates to the gateway node and resume replication on the fileset.

mmafmctl Device {getstate | resumeRequeued} -j FilesetName  

getstate

This option is applicable for all AFM (RO/SW/IW/LU) and AFM primary filesets. It displays the status of the fileset in the following fields:

Fileset Name

The name of the fileset.

Fileset Target

The host server and the exported path on it.

Gateway Node

Primary gateway of the fileset. This gateway node is handling requests for this fileset.

Queue Length

Current length of the queue on the primary gateway.

Queue numExec

Number of operations played at home since the fileset is last Active.

Cache State

• Cache states applicable for all AFM RO/SW/IW/LU filesets:

  Active, Inactive, Dirty, Disconnected, Stopped, Unmounted

• Cache states applicable for RO filesets:

  Expired

• Cache states applicable for SW and IW filesets:

  Recovery, FlushOnly, QueueOnly, Dropped, NeedsResync, FailoverInProgress

• Cache states applicable for IW filesets:

  FailbackInProgress, FailbackCompleted, NeedsFailback

• Cache states applicable for AFM primary filesets:

  PrimInitInProg, PrimInitFail, Active, Inactive, Dirty, Disconnected, Unmounted, FailbackInProg, Recovery, FlushOnly, QueueOnly, Dropped, Stopped, NeedsResync

For more information on all cache states, see the AFM and AFM-based DR chapters in the IBM Spectrum Scale: Concepts, Planning, and Installation Guide.

resumeRequeued

This option is applicable for SW/IW and primary filesets. If there are operations in the queue that were re-queued due to errors at home, the Administrator should correct those errors and can run this option to retry the re-queued operations.

mmafmctl Device flushPending [-j FilesetName [--list-file ListFile]]
             [-s LocalWorkDirectory]  

flushPending

Flushes all point-in-time pending messages in the normal queue on the fileset to home. Requeued messages and messages in the priority queue for the fileset are not flushed by this command.

When --list-file ListFile is specified, the messages pending on the files listed in the list file are flushed to home. ListFile contains a list of files that you want to flush, one file per line. All files must have absolute path names, specified from the fileset linked path. If the list of files has filenames with special characters, use a policy to generate the listfile. Edit to remove all entries other than the filenames. FlushPending is applicable for SW/IW and primary filesets.

mmafmctl Device failover -j FilesetName
             --new-target NewAfmTarget [--target-only] [-s LocalWorkDirectory]  

This option is applicable only for SW/IW filesets. This option pushes all the data from cache to home. It should be used only in case home is completely lost due to a disaster and a new home is being set up. Failover often takes a long time to complete; status can be checked using the afmManualResyncComplete callback or via mmafmctl getstate command.

--new-target NewAfmTarget

Specifies a new home server and path, replacing the home server and path originally set by the afmTarget parameter of the mmcrfileset command. Specified in either of the following formats:

nfs://{Host|Map}/Target_Path

or

gpfs://[Map]/Target_Path

where:

nfs:// or gpfs://

Specifies the transport protocol.

Host|Map

Host

Specifies the server domain name system (DNS) name or IP address.

Map

Specifies the export map name. Information about Mapping is contained in the AFM Overview > Parallel data transfers section.

See the following examples:

1. An example of using the nfs:// protocol with a map name:

   mmcrfileset fs3 singleWriter2 -p 
           afmtarget=nfs://<map1>/gpfs/fs1/target1 -p afmmode=sw --inode-space new

2. An example of using the nfs:// protocol with a host name:

   mmcrfileset fs3 singleWriter2 -p
           afmtarget=nfs://<hostname>/gpfs/fs1/target1 -p afmmode=sw --inode-space new

3. An example of using the gpfs:// protocol without a map name:

   mmcrfileset fs3 singleWriter1 -p 
            afmtarget=gpfs:///gpfs/thefs1/target1 -p afmmode=sw --inode-space new

   Note: If you are not specifying the map name, a '/' is still needed to indicate the path.
4. An example of using the gpfs:// protocol with a map name:

   mmcrfileset fs3 singleWriter1 -p
           afmtarget=gpfs://<map>/gpfs/thefs1/target1 -p afmmode=sw --inode-space new

Target_Path

Specifies the export path.

It is possible to change the protocol along with the target using failover. For example, a cache using an NFS target bear110:/gpfs/gpfsA/home can be switched to a GPFS target whose remote file system is mounted at /gpfs/fs1, and vice-versa, as follows:

mmafmctl fs0 failover -j afm-mc1 --new-target gpfs:///gpfs/fs1
mmafmctl fs0 failover -j afm-mc1 --new-target nfs://bear110/gpfs/gpfsA/home

Note that in the first command, /// is needed because Host is not provided.

--target-only

This option is used to change the mount path or IP address in the target path. The new NFS server must be in the same home cluster and must have the same architecture as the existing NFS server in the target path. This option must not be used to change the target location or protocol. You must ensure that the new NFS server exports the same target path that has the same FSID.

mmafmctl Device prefetch -j FilesetName [-s LocalWorkDirectory]
             [--retry-failed-file-list|--enable-failed-file-list] 
             [--directory LocalDirectoryPath]|
             {--list-fileListFile|--home-list-fileHomeListFile}[--policy]|--home-inode-filePolicyListFile]
             [--home-fs-path HomeFileSystemPath][--metadata-only]
                          

mmafmctl: Performing prefetching of fileset: <fileset>
Queued (Total) Failed TotalData (approx in Bytes)
0      (56324) 0      0
5      (56324) 2      1353559
56322  (56324) 2      14119335

mmafmctl Device evict -j FilesetName 
            [--safe-limit SafeLimit] [--order {LRU | SIZE}]
            [--log-file LogFile] [--filter Attribute=Value ...]
            [--list-file ListFile] [--file FilePath]

This option is applicable for RO/SW/IW/LU filesets. When cache space exceeds the allocated quota, data blocks from non-dirty are automatically de-allocated with the eviction process. This option can be used for a file that is specifically to be de-allocated based on some criteria. All options can be combined with each other.

--safe-limit SafeLimit

This is a compulsory parameter for the manual evict option, for order and filter attributes. Specifies target quota limit (which is used as the low water mark) for eviction in bytes; must be less than the soft limit. This parameter can be used alone or can be combined with one of the following parameters (order or filter attributes). Specify the parameter in bytes.

--order LRU | SIZE

Specifies the order in which files are to be chosen for eviction:

LRU

Least recently used files are to be evicted first.

SIZE

Larger-sized files are to be evicted first.

--log-file LogFile

Specifies the file where the eviction log is to be stored. The default is that no logs are generated.

--filter Attribute=Value

Specifies attributes that enable you to control how data is evicted from the cache. Valid attributes are:

FILENAME=FileName

Specifies the name of a file to be evicted from the cache. This uses an SQL-type search query. If the same file name exists in more than one directory, it will evict all the files with that name. The complete path to the file should not be given here.

MINFILESIZE=Size

Sets the minimum size of a file to evict from the cache. This value is compared to the number of blocks allocated to a file (KB_ALLOCATED), which may differ slightly from the file size.

MAXFILESIZE=Size

Sets the maximum size of a file to evict from the cache. This value is compared to the number of blocks allocated to a file (KB_ALLOCATED), which may differ slightly from the file size.

--list-file ListFile

Contains a list of files that you want to evict, one file per line. All files must have fully qualified path names. Filesystem quotas need not be specified. If the list of files has filenames with special characters, use a policy to generate the listfile. Edit to remove all entries other than the filenames.

--file FilePath

The fully qualified name of the file that needs to be evicted. Filesystem quotas need not be specified.

mmafmctl Device failback -j FilesetName {{--start --failover-time Time} | --stop}

        [-sLocalWorkDirectory]

failback is applicable only for IW filesets.

failback --start --failover-time Time

Specifies the point in time at the home cluster, from which the independent-writer cache taking over as writer should sync up. Time can be specified in date command format with time zones. It will use the cluster's time-zone and year by default.

failback --stop

An option to be run after the failback process is complete and the fileset moves to FailbackCompleted state. This will move the fileset to Active state.

mmafmctl Device failoverToSecondary -j FilesetName [--norestore |--restore ]

This is to be run on a secondary fileset.

When primary experiences a disaster, all applications will need to be moved to the secondary to ensure business continuity. The secondary has to be first converted to an acting primary using this option.

There is a choice of restoring the latest snapshot data on the secondary during the failover process or leave the data as is using the --norestore option. Once this is complete, the secondary becomes ready to host applications.

--norestore

Specifies that restoring from the latest RPO snapshot is not required. This is the default setting.

--restore

Specifies that data must be restored from the latest RPO snapshot.

mmafmctl Device convertToPrimary -j FilesetName
         [ --afmtarget Target { --inband | --secondary-snapname SnapshotName }]
         [ --check-metadata | --nocheck-metadata ] [--rpo RPO] [-s LocalWorkDirectory]

This is to be run on a GPFS fileset or SW/IW fileset which is intended to be converted to primary.

--afmtargetTarget

Specifies the secondary that needs to be configured for this primary. Need not be used for AFM filesets as target would already have been defined.

--inband

Used for inband trucking. Inband trucking copies data from the primary site to an empty secondary site during conversion of GPFS filesets to AFM DR primary filesets. If you have already copied data to the secondary site, AFM checks mtime of files at the primary and secondary site. Here, granularity of mtime is in microseconds. If mtime values of both files match, data is not copied again and existing data on the secondary site is used. If mtime values of both files do not match, existing data on the secondary site is discarded and data from the primary site is written to the secondary site.

--check-metadata

This is the default option. Checks if the disallowed types (like immutable/append-only files) are present in the GPFS fileset on the primary site before the conversion. Conversion with this option fails if such files exist.

For SW/IW filesets, presence of orphans and incomplete directories are also checked. SW/IW filesets should have established contact with at least once home for this option to succeed.

--nocheck-metadata

Used if one needs to proceed with conversion without checking for appendonly/immutable files.

--secondary-snapname SnapshotName

Used while establishing a new primary for an existing secondary or acting primary during failback.

--rpo RPO

Specifies the RPO interval in minutes for this primary fileset. Disabled by default.

mmafmctl Device convertToSecondary -j FilesetName --primaryid  PrimaryId [ --force ]

This is to be run on a GPFS fileset on the secondary site. This converts a GPFS independent fileset to a secondary and sets the primary ID.

--primaryid PrimaryId

Specifies the unique identifier of the AFM-DR primary fileset which needs to be set at AFM-DR Secondary fileset to initiate a relationship. You can obtain this fileset identifier by executing the mmlsfileset command using the --afm and -L options.

For example,

#mmlsfileset <FileSystem> <AFM DR Fileset> -L --afm |grep 'Primary Id'

--force

If convertToSecondary failed or got interrupted, it will not create afmctl file at the secondary. The command should be rerun with the --force option.

mmafmctl Device changeSecondary -j FilesetName 
--new-target NewAfmTarget [ --target-only |--inband ] 
         [-s LocalWorkDirectory]

This is to be run on a primary fileset only.

A disaster at the secondary can take place due to which secondary is not available.

Run this command on the primary when a secondary fails and this primary needs to be connected with a new secondary. On the new secondary site a new GPFS independent fileset has to be created. Data on the primary can be copied to the new GPFS fileset that was created with this command using other means such as ftp, scp etc. Alternatively it can be decided that data will be trucked using the relationship.

--new-target NewAfmTarget

Used to mention the new secondary.

--inband

Used for inband trucking. Copies data to a new empty secondary. If you have already copied data to the secondary site, mtime of files at the primary and secondary site is checked. Here, granularity of mtime is in microseconds. If mtime values of both files match, data is not copied again and existing data on the secondary site is used. If mtime values of both files do not match, existing data on the secondary site is discarded and data from the primary site is written to the secondary site.

--target-only

Used when you want to change the IP address or NFS server name for the same target path. The new NFS server must be in the same home cluster and must be of the same architecture(power or x86) as the existing NFS server in the target path. This option can be used to move from NFS to a mapping target.

mmafmctl Device replacePrimary -j FilesetName

This is used on an acting primary only. This creates a latest snapshot of the acting primary. This command deletes any old RPO snapshots on the acting primary and creates a new initial RPO snapshot psnap0.

This RPO snapshot is used in the setup of the new primary.

mmafmctl Device failbackToPrimary -j FilesetName {--start | --stop} [--force] 

This is to be run on an old primary that came back after the disaster, or on a new primary that is to be configured after an old primary went down with a disaster. The new primary should have been converted from GPFS to primary using convertToPrimary option.

--start

Restores the primary to the contents from the last RPO on the primary before the disaster. This option will put the primary in read-only mode, to avoid accidental corruption until the failback process is completed. In case of new primary that is setup using convertToPrimary, the failback --start does no change.

--stop

Used to complete the Failback process. This will put the fileset in read-write mode. The primary is now ready for starting applications.

--force

Used if --stop or --start does not complete successfully due to any errors, and not allow failbackToPrimary to stop or start again.

mmafmctl Device {applyUpdates |getPrimaryId } -j FilesetName 

Both options are intended for the primary fileset.

applyUpdates

Run this on the primary after running the failback --start command. All the differences can be brought over in one go or through multiple iterations. For minimizing application downtime, this command can be run multiple times to bring the primary's contents in sync with the acting primary. When the contents are as close as possible or minimal, applications should take a downtime and then this command should be run one last time.

It is possible that applyUpdates fails with an error during instances when the acting primary is overloaded. In such cases the command has to be run again.

getPrimaryID

Used to get primary Id of a primary fileset.

Exit status

Security

You must have root authority to run the mmafmctl 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.

See also

Location

/usr/lpp/mmfs/bin