mmafmctl command

Availability

Available with IBM Spectrum Scale™ Standard Edition or higher. 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.

-s LocalWorkDirectory

Specifies the temporary working directory.

mmafmctl Device {resync | expire | unexpire} -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. When an RO cache is disconnected, the cached contents are still accessible for the user. However the administrator can define a time 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 state can also be forced manually using the expire parameter.

When the home comes back or reconnects, the cache contents become automatically accessible again and the cache is said to un-expire. This can be forced manually using the unexpire parameter.

The manual expiration and un-expiration can be forced on a cache even when the home is in a connected state. For expiring a fileset manually the afmExpirationTimeout needs to have been set on the fileset. If a cache is expired using this manual method, it will also have to be manually unexpired.

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

Metadata server or MDS of the fileset. This gateway node is handling requests for this fileset.

Queue Length

Current length of the queue on the MDS.

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, 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, NeedsResync

All cache states are explained in AFM and AFM Disaster Recovery chapters in the IBM Spectrum Scale: Advanced Administration Guide. Please refer to them for more information.

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.

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:

Protocol://[Host|Map]/Path

or

{Host|Map}:Path

where:

Protocol://

Specifies the transport protocol. Valid values are nfs:// or gpfs://.

Host|Map

Host

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

Map

Specifies the export map name.

Notes:

1. When specifying nfs:// as the value for Protocol://, you must provide a value for Host or Map.
2. When specifying gpfs:// as the value for Protocol://, do not provide a value for Host. However, provide a value for Map if it refers to an export map entry.

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 is used if the user wants to change the mount path/IP address in the target path. The new NFS server should be in the same home cluster and should be of the same architecture as the existing NFS server in the target path. This option should not be used to change the target location or protocol.

mmafmctl Device prefetch -j FilesetName [--metadata-only]
             [{--list-file ListFile} | 
             [--home-fs-path HomeFileSystemPath]
             [-s LocalWorkDirectory]             

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

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.

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 peer snapshot is not required.

--restore

Specifies that the restoring of data is to be done from the latest peer snapshot. This is the default.

mmafmctl Device convertToPrimary -j FilesetName
         [ --afmtarget Target { --inband | --outband | --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 is copying the data while setting up a primary/secondary relationship from GPFS filesets, where primary site has contents and secondary site is empty.

--outband

Used for outband trucking. Outband trucking is copying data manually using other ways such as ftp, scp, rsync etc. This should be completed before the relationship is established.

--check-metadata

This 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.

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 ID of the primary with which the secondary will be associated.

--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 | --outband ] 
         [-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 | --outband

Used based on the method used to truck data.

--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 will create a latest snapshot of the acting primary. This command deletes any old peer snapshots on the acting primary and creates a new initial peer snapshot psnap0.

This snapshot will be 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 option does not complete due to errors and not allow for failback to be stopped.

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. See the following IBM Spectrum Scale: Administration and Programming Reference topic: Requirements for administering a GPFS file system.

See also

Location

/usr/lpp/mmfs/bin