mmchfileset command

Availability

Available on all IBM Storage Scale editions.

Description

The mmchfileset command changes attributes for an existing GPFS fileset.

For information on GPFS filesets, see Filesets.

Parameters

Device

The device name of the file system that contains the fileset.

File system names need not be fully qualified. fs0 is as acceptable as /dev/fs0.

FilesetName

Specifies the name of the fileset.

-J JunctionPath

Specifies the junction path name for the fileset.

A junction is a special directory entry that connects a name in a directory of one fileset to the root directory of another fileset.

-j NewFilesetName

Specifies the new name that is to be given to the fileset. This name must be fewer than 256 characters in length. The root fileset cannot be renamed.

-t NewComment

Specifies an optional comment that appears in the output of the mmlsfileset command. This comment must be fewer than 256 characters in length. This option cannot be used on the root fileset.

-p afmAttribute=Value

Specifies an AFM configuration attribute and its value. More than one -p option can be specified.

The following AFM configuration attributes are valid:

afmAsyncDelay

Specifies (in seconds) the amount of time by which write operations are delayed (because write operations are asynchronous with respect to remote clusters). For write-intensive applications that keep writing to the same set of files, this delay is helpful because it replaces multiple writes to the home cluster with a single write containing the latest data. However, setting a very high value weakens the consistency of data on the remote cluster.

This configuration parameter is applicable only for writer caches (Single writer, Independent writer, and Primary ) in which data from cache is pushed to home.

Valid values are 1 - 2147483647. The default is 15.

afmDirLookupRefreshInterval

Controls the frequency of data revalidations that are triggered by such lookup operations as ls or stat (specified in seconds). When a lookup operation is done on a directory, if the specified amount of time has passed, AFM sends a message to the home cluster to find out whether the metadata of that directory has been modified since the last time it was checked. If the time interval has not passed, AFM does not check the home cluster for updates to the metadata.

Valid values are 0 through 2147483647. The default is 60. In situations where home cluster data changes frequently, a value of 0 is recommended.

afmDirOpenRefreshInterval

Controls the frequency of data revalidations that are triggered by such I/O operations as read or write (specified in seconds). After a directory has been cached, open requests resulting from I/O operations on that object are directed to the cached directory until the specified amount of time has passed. Once the specified amount of time has passed, the open request gets directed to a gateway node rather than to the cached directory.

Valid values are between 0 and 2147483647. The default is 60. Setting a lower value guarantees a higher level of consistency.

afmObjectDirectoryObj

AFM to cloud object storage supports directory objects. All directories with and without objects can now be synchronized to the cloud object storage. You can now set extended attributes on directories with the directory object support. To enable afmObjectDirectoryObj parameter, stop the fileset, enable the parameter and start the fileset.

afmEnableAutoEviction

Enables eviction on a given fileset. A yes value specifies that eviction is allowed on the fileset. A no value specifies that eviction is not allowed on the fileset.

Metadata eviction feature helps optimize storage usage by selectively removing metadata or inodes from the local AFM fileset for better utilization of space.

See also the topic about cache eviction in the IBM Storage Scale: Administration Guide.

afmEvictRange

Evicts only specified ranges of data blocks from a specified file, when this parameter is set to yes on an AFM fileset. The AFM range eviction feature provides a file granular capability to evict only desired data blocks, which are not required on the cache storage.

When the afmEvictRange option is set on a fileset, the auto-eviction and the manual eviction (without range) evict all the data blocks except first and last data blocks. Valid value is 'yes' or 'no'.

By default the whole file is evicted. After this parameter enabled on an AFM fileset, a list of files contains offset and length that can be provided for eviction. An example of the range eviction is as follows:

1. List information about a file.

    ls -lsh /gpfs/fs1/ro1/bigfile1

   Sample output is as follows:

   19458 100G -rw-r--r-- 1 root root 100G Jul 16 23:35 /ibm/fs1/file1

   The format of the list-file for the range eviction is as follows:

   <Start_Offset> <length> <filepath>

2. Copy the list-file.

   cat /tmp/rangefile

   Sample output is as follows:

   10G 15G /gpfs/fs1/ro1/bigfile1

3. Evict a range of data blocks from the list-file.

    mmafmctl fs1 evict -j fileset --list-file /tmp/rangefile --range

   AFM evicts data 5G data blocks starting from 10G till 15G, offset and length are aligned on the block boundary.

afmExpirationTimeout

Is used with afmDisconnectTimeout (which can be set only through mmchconfig) to control how long a network outage between the cache and home clusters can continue before the data in the cache is considered out of sync with home. After afmDisconnectTimeout expires, cached data remains available until afmExpirationTimeout expires, at which point the cached data is considered expired and cannot be read until a reconnect occurs.

Valid values are 0 through 2147483647. The default is disable.

afmFastCreate

Enable at the AFM cache and AFM-DR primary fileset level. AFM sends RPC to the gateway node for each update that is happening on the fileset. If the workload mostly involves new files creation, this parameter reduces the RPC exchanges between the application and the gateway node, improves the application performance, and minimizes the memory queue requirement at the gateway node.

To set or unset the afmFastCreate parameter on an AFM or AFM-DR fileset, you need to stop or unlink the fileset. For more information, see Stop and start replication on a fileset.

Valid values are 'yes' or no'.

afmFileLookupRefreshInterval

Controls the frequency of data revalidations that are triggered by such lookup operations as ls or stat (specified in seconds). When a lookup operation is done on a file, if the specified amount of time has passed, AFM sends a message to the home cluster to find out whether the metadata of the file has been modified since the last time it was checked. If the time interval has not passed, AFM does not check the home cluster for updates to the metadata.

Valid values are 0 through 2147483647. The default is 30. In situations where home cluster data changes frequently, a value of 0 is recommended.

afmFileOpenRefreshInterval

Controls the frequency of data revalidations that are triggered by such I/O operations as read or write (specified in seconds). After a file has been cached, open requests resulting from I/O operations on that object are directed to the cached file until the specified amount of time has passed. Once the specified amount of time has passed, the open request gets directed to a gateway node rather than to the cached file.

Valid values are 0 through 2147483647. The default is 30. Setting a lower value guarantees a higher level of consistency.

afmGateway

Specifies the user-defined gateway node for an AFM or AFM DR fileset, that gets preference over internal hashing algorithm. If the specified gateway node is not available, then AFM internally assigns a gateway node from the available list to the fileset. afmHashVersion value must be already set as '5'. Before setting the afmGateway value; stop replication on the fileset or unlink the AFM fileset. After setting the value, start replication on the fileset or link the AFM fileset.

An example of setting the gateway node by using stop and start AFM fileset -

        #mmafmctl <fs> stop -j <fileset> 		
        #mmchfileset <fs> <fileset> -p afmGateway=<GateWayNode>
        #mmlsfileset <fs>  -L --afm
        #mmafmctl <fs> start -j <fileset>

An example of setting the gateway node by using unlink and link AFM fileset -

        #mmunlinkfileset <fs> <fileset> -f
        #mmchfileset <fs> <fileset> -p afmGateway=<GateWayNode>
        #mmlsfileset <fs>  -L --afm
        #mmlinkfileset <fs> -J <filesetPath>

To revert to the internal hashing algorithm of assigning gateway nodes, you must delete the assigned gateway node value of the AFM fileset.

An example of deleting the gateway node by using stop and start AFM fileset -

        #mmafmctl <fs> stop -j <fileset> 		
        #mmchfileset <fs> <fileset> -p afmGateway=delete
        #mmlsfileset <fs>  -L --afm
        #mmafmctl <fs> start -j <fileset>

An example of deleting the gateway node by using unlink and link AFM fileset -

        #mmunlinkfileset <fs> <fileset> -f
        #mmchfileset <fs> <fileset> -p afmGateway=delete
        #mmlsfileset <fs>  -L --afm
        #mmlinkfileset <fs> -J <filesetPath>

Note: Ensure that the file system is upgraded to IBM Storage Scale 5.0.2 or later.

This parameter also accepts 'all' as a value. afmGateway=all can be set on RO and LU mode AFM fileset. This parameter supports the value 'all' for the file system-level migration. This value improves the file system level migration performance by using the inode-based hashing. When this value is set, all operations that belong to an inode are queued to the gateway node. It helps load balance operations by using inode number.

Set afmGateway=all by using the stop and start AFM fileset. For example,

# mmafmctl <fs> stop -j <fileset>
# mmchfileset <fs> <fileset> -p afmGateway=all
# mmafmctl <fs> start -j <fileset>

afmMode

Specifies the mode in which the cache operates. Valid values are the following:

single-writer | sw

Specifies single-writer mode.

read-only | ro

Specifies read-only mode. (For mmcrfileset, this is the default value.)

local-updates | lu

Specifies local-updates mode.

manual-updates | mu

Specifies manual update mode.

independent-writer | iw

Specifies independent-writer mode.

Primary | drp

Specifies the primary mode for AFM asynchronous data replication.

Secondary | drs

Specifies the secondary mode for AFM asynchronous data replication.

Changing from single-writer/read-only modes to read-only/local-updates/single-writer is supported. When changing from read-only to single-writer, the read-only cache is up-to-date. When changing from single-writer to read-only, all requests from cache should have been played at home. Changing from local-updates to read-only/local-updates/single-writer is restricted. A typical dataset is set up to include a single cache cluster in single-writer mode (which generates the data) and one or more cache clusters in local-updates or read-only mode. AFM single-writer/independent-writer filesets can be converted to primary. Primary/secondary filesets cannot be converted to AFM filesets.

In case of AFM asynchronous data replication, the mmchfileset command cannot be used to convert to primary from secondary. See AFM-based asynchronous disaster recovery (AFM DR) for detailed information.

For more information, see the topic about caching modes in the IBM Storage Scale: Administration Guide chapter about active file management.

afmMUAutoRemove

When the afmMUAutoRemove option is set to 'yes' on MU mode fileset, remove operations on the files are queued on the gateway node to delete the files at cloud object storage automatically. After this option is set to yes, it overrides –from-cache and –from-target options of mmafmcosctl command. The default value of this option is 'no'.

afmNFSV4

Specifies NFS version 4 (NFSv4) that can be enabled on individual AFM and AFM DR filesets.

When you enable this parameter on a specified fileset, the fileset behavior to use NFSv4 protocol version is modified. However, other filesets in the cluster can continue using other NFS version.

AFM first tries NFSv4.2 for mount. If this version is not available, AFM tries NFSv4.1. If both are failed, the fileset state becomes Unmounted.

Allowed values are 'yes' and 'no'. To enable NFSv4 on the specified fileset during the fileset creation, you can specify afmNFSV4=yes.

For example,

• Enable NFSv4 on a fileset.
  1. Specify NFSv4 on a fileset, when you are creating the fileset.

      mmcrfileset fs1 testfset -p afmnfsv4=yes,...

     Note: On an existing fileset, you need not to specify NFSv4 version. You can stop the fileset, set the parameter value, and start the fileset.
  2. Stop the fileset.

      mmafmctl fs1 stop -j testfset

  3. Set the parameter value.

      mmchfileset fs1 testfset -p afmnfsv4=yes

  4. Start the fileset.

      mmafmctl fs1 start -j testfset

• Disable NFSv4 on an existing fileset.
  1. Stop the fileset.

      mmafmctl fs1 stop -j testfset

  2. Set the parameter value.

      mmchfileset fs1 testfset -p afmnfsv4=no

  3. Start the fileset.

      mmafmctl fs1 start -j testfset

The afmNFSVersion is the cluster level configuration option, which affects all the AFM filesets. This parameter enables NFSv4 at the fileset level. To enable similar NFSv4 at the fileset level, the afmNFSV4 parameter is introduced. After you enabled this parameter on a fileset, AFM first tries afmNFSVersion=4.2 for mount. If afmNFSVersion=4.2 fails, AFM tries the afmNFSVersion=4.1 for mount.

For more information, see AFM Network File System version 4 supportAFM Network File System version 4 support.

afmNumFlushThreads

Defines the number of threads used on each gateway to synchronize updates to the home cluster. The default value is 4, which is sufficient for most installations. The current maximum value is 1024, which is too high for most installations; setting this parameter to such an extreme value should be avoided.

afmNumReadThreads

Defines the number of threads that can be used on each participating gateway node during parallel read. The default value of this parameter is 1; that is, one reader thread will be active on every gateway node for each big read operation qualifying for splitting per the parallel read threshold value. The valid range of values is 1 to 64.

afmNumWriteThreads

Defines the number of threads that can be used on each participating gateway node during parallel write. The default value of this parameter is 1; that is, one writer thread will be active on every gateway node for each big write operation qualifying for splitting per the parallel write threshold value. Valid values can range from 1 to 64.

afmObjectACL

Enables the cache to synchronize ACL to the cloud object storage server. If this parameter is not specified, AFM does not synchronize ACLs to cloud object storage. By default, the ACL synchronization is disabed.

afmObjectAZ

Enables the migration of existing AFM to cloud object storage filesets configured by using S3 gateway or MinIO between AFM and Azure Blob to Azure Blob native API support.

After this parameter is enabled, you can migrate existing AFM to cloud object storage filesets that communicate directly with Azure Blob native API. S3 gateway MinIO can be removed after the migration.

afmObjectDirectoryObj

AFM to cloud object storage supports directory objects. All directories with and without objects can now be synchronized to the cloud object storage. You can now set extended attributes on directories with the directory object support. To enable afmObjectDirectoryObj parameter, stop the fileset, enable the parameter and start the fileset.

afmObjectFastReaddir

Improves the objects download and readdir performance, when the afmObjectFastReaddir parameter value is set to 'yes' at the fileset level. Extended attributes and ACLs are not fetched from a cloud object storage when this parameter is enabled. Also, deleted objects on a cloud object storage system are not reflected immediately on a cache when this parameter is enabled. You can use this option to pull the objects into the cache to run quick analytics on the target data.

The valid values for the afmObjectFastReaddir parameter are 'no' and 'yes'. The default value is 'no'. This parameter can be set on AFM SW, RO, LU, and IW mode cloud object storage filesets.

Improves the readdir performance of an AFM to cloud object storage fileset by skipping synchronization of extended attributes and ACLs of an object between a cloud object storage server and a cache fileset. When this option is set, deleted objects on the cloud object storage server will not be reflected immediately on the cache fileset.

This option cannot be used with the --xattr option.

afmObjectGCS

Makes AFM to cloud object storage compatible with the list operations used by the Google cloud object. This parameter is used for Google cloud object storage backend.

afmObjectSSL

Specifies the SSL certificate verification. This option is valid only with HTTPS. Default value of this parameter is disabled.

afmObjectSyncOpenFiles

Synchronizes open files in the AFM cloud object storage fileset to the target cloud object storage bucket.

During this synchronization, the application might keep some files open for processing. By default, AFM skips files that the application keeps open during the replication to the cloud object storage bucket, and replicates data from only closed files where data is synchronized on the disk. Open files data might be changed many times.

After this parameter is enabled, AFM synchronizes open files and replicates the existing data on a disk to the bucket. For a closed file, modified data on a disk replicates again.

Valid values are 'yes' and 'no'.

afmObjectUserKeys

Specifies adding a callback to collect an access key and a secret key from a file. When this option is enabled, AFM retrieves the access key and the secrete key by calling the /var/mmfs/etc/mmuid2keys file. The returned value must be in the Access_Key:Secret_Key format. The mmuid2keys file must be available on the gateway node(s) and must have executable permission.

If you want to create a fileset by using Security Token Service (STS), add STS key along with Access_key and Secret_Key in the format as shown in the following example of the mmuid2keys file. The returned value must be in the Access_Key:Secret_Key:STS format.

Examples of the mmuid2keys file are as follows:

• Example 1

  #!/usr/lpp/mmfs/bin/mmksh
  # input:
  #
  #- UID : User Id configured on the system. It could be local
  # user or LDAP/AD configured user.
  #- bucket : The name of the bucket for which keys are required.
  #- endpoint : The endpoint of the fileset for which keys are required.
  #
  # output:
  #
  # accesskey:secretkey
  # In the output, keys="AccessKey:SecretKey:STS", the 'STS' field is optional.
  cmd=$1
  uid=$2
  bucket=$3
  endpoint=$4
  # check for bucket, endpoint and return key
  if [[ $bucket == "bkt1" && $endpoint =~ "ap-southeast-2@192.168.1.1:443" ]]
  then
  keys="AccessKey1:SecretKey1:STS"
  elif [[ $bucket == "bkt2" && $endpoint =~ "eu-west-2@192.168.1.2:80" ]]
  then
  keys="AccessKey2:SecretKey2:STS"
  else
  keys="AccessKey:SecretKey:STS"
  fi
  echo "$keys"
  exit 0

• Example 2: In the following simplified example of the mmuid2keys file. Where, all the filesets are created by using the --user-keys option and mmuid2keys file returns required credentials as shown.

  #!/usr/lpp/mmfs/bin/mmksh
  echo "Akey:Skey:STS"
   #The'STS'field is optional.

afmObjectXattr

Specifies user-extended attributes to be synchronized with a cloud object storage. If this option is skipped, the AFM to cloud object storage does not synchronize user-extended attributes with the cloud object storage.

afmParallelMounts

When this parameter is enabled, the primary gateway node of a fileset at a cache cluster attempts to mount the exported path from multiple NFS servers that are defined in the mapping. Then, this primary gateway node sends unique messages through each NFS mount to improve performance by transferring data in parallel.

Before enabling this parameter, define the mapping between the primary gateway node and NFS servers by issuing the mmafmconfig command.

afmParallelReadChunkSize

Defines the minimum chunk size of the read that needs to be distributed among the gateway nodes during parallel reads. Values are interpreted in terms of bytes. The default value of this parameter is 128 MiB, and the valid range of values is 0 to 2147483647. It can be changed cluster wide with the mmchconfig command. It can be set at fileset level using mmcrfileset or mmchfileset commands.

afmParallelReadThreshold

Defines the threshold beyond which parallel reads become effective. Reads are split into chunks when file size exceeds this threshold value. Values are interpreted in terms of MiB. The default value is 1024 MiB. The valid range of values is 0 to 2147483647. It can be changed cluster wide with the mmchconfig command. It can be set at fileset level using mmcrfileset or mmchfileset commands.

afmParallelWriteChunkSize

Defines the minimum chunk size of the write that needs to be distributed among the gateway nodes during parallel writes. Values are interpreted in terms of bytes. The default value of this parameter is 128 MiB, and the valid range of values is 0 to 2147483647. It can be changed cluster wide with the mmchconfig command. It can be set at fileset level using mmcrfileset or mmchfileset commands.

afmParallelWriteThreshold

Defines the threshold beyond which parallel writes become effective. Writes are split into chunks when file size exceeds this threshold value. Values are interpreted in terms of MiB. The default value of this parameter is 1024 MiB, and the valid range of values is 0 to 2147483647. It can be changed cluster wide with the mmchconfig command. It can be set at fileset level using mmcrfileset or mmchfileset commands.

afmPrefetchThreshold

Controls partial file caching and prefetching. Valid values are the following:

0

Enables full file prefetching. This is useful for sequentially accessed files that are read in their entirety, such as image files, home directories, and development environments. The file will be prefetched after three blocks have been read into the cache.

1-99

Specifies the percentage of file size that must be cached before the entire file is prefetched. A large value is suitable for a file accessed either randomly or sequentially but partially, for which it might be useful to ingest the rest of the file when most of it has been accessed.

100

Disables full file prefetching. This value only fetches and caches data that is read by the application. This is useful for large random-access files, such as databases, that are either too big to fit in the cache or are never expected to be read in their entirety. When all data blocks are accessed in the cache, the file is marked as cached.

0 is the default value.

For local-updates mode, the whole file is prefetched when the first update is made.

afmPrimaryID

Specifies the unique primary ID of the primary fileset for asynchronous data replication. This is used for connecting a secondary to a primary.

afmRecoveryUseFset

Enables the specified AFM fileset to use the custom storage path, which the afmRecoveryDir parameter specifies at the cluster level, for the recovery or reconcile instead of the default location.

During the event of recovery, if resync or reconcile operations are triggered on the AFM fileset, AFM uses the /var/mmfs/afm/ default location to store the recovery data. AFM uses these files to synchronize the pending data to the target.

AFM uses a default or non-default path based on combination of setting the afmRecoveryDir and afmRecoveryUseFset parameters setting. For example,

• If the afmRecoveryDir and afmRecoveryUseFset parameters are set, then the AFM recovery uses the custom location that the afmRecoveryDir parameter specified. If afmRecoveryDir and afmRecoveryUseFset parameters are not set, then AFM recovery uses the default location, that is, /var/mmfs/afm/<fs>-<fsetid>/.
• If the afmRecoveryDir parameter is not set but the afmRecoveryUseFset parameter is set on the fileset, then AFM recovery use the /<FS_mount_Path>/<Fset>/.afm/recovery path.

For example,

• Set afmRecoveryUseFset on an AFM fileset.

   mmchfileset fs1 ADR-1 -p afmRecoveryUseFset=yes

  A sample output is as follows:

   Fileset ADR-1 changed.

• Unset afmRecoveryUseFset on an AFM fileset.

   mmchfileset fs1 ADR-1 -p afmRecoveryUseFset=no

  A sample output is as follows:

   Fileset ADR-1 changed.

Valid values are 'yes' and 'no'. After this parameter is set, the next recovery uses this configuration.

afmReadDirOnce

Enables AFM to perform one-time readdir of a directory from the home after the data migration to the cache and the application is started on the cache data. That is, the application is moved from the home to the cache and the application modifies the directory, which makes the directory dirty. When this parameter is set for a fileset, the prefetch operation is run on the fileset by using --readdir-only to move new or modified data from the home to the cache, even if the cache directory is dirty. After the data migration to the cache and the application is started on the cache data, this parameter synchronizes new files at the home directory to the cache for a single time.

Valid values are 'yes' and 'no'. This parameter can be set on AFM RO, LU, and IW filesets. This parameter is not useful for the DMAPI migration.

afmReadSparseThreshold

Specifies the size in MB for files in cache beyond which sparseness is maintained. For all files below the specified threshold, sparseness is not maintained.

afmRefreshOnce

Enables AFM to perform revalidation on files and directories only one time. This parameter improves the application performance after the data migration to the cache and the application is started on the cache data during the migration from old system to the new system. When this parameter is set to yes, files and directories revalidation is performed only one time. Therefore, only one revalidation request goes to the home or target.

Valid values are 'yes' and 'no'. This parameter can be set on AFM RO, LU, and IW filesets. This parameter is not useful for the DMAPI migration.

afmRecoveryVer2

Enables optimized version of the recovery on the AFM Single Writer or AFM DR Primary fileset. After the optimized recovery version is set, AFM avoids using the older version of the recovery and uses the version V2 to identify the remove and rename operations. The new recovery version identify the home directory entries by running the GPFS policy at the home when recovery event is triggered.

The preceding method is helpful when the directory has large set of rename and remove operations that are yet to sync to the home in case of the recovery event. This process requires home to be IBM Storage Scale GPFS file system so that GPFS policy can be run.

The V2 version of the recovery avoids reading of home directory and run GPFS policy at the home to identify the pending changes from cache which needs to be sync to the home. If GPFS policy faces issue while running at home then the AFM will failback to older version of recovery and complete the operation.

To set or unset the afmRecoveryVer2 parameter on an AFM Single-Writer or AFM-DR Primary fileset, you must stop or unlink the fileset. For more information, see Stop and start replication on a fileset. The valid values for the afmRecoveryVer2 are 'yes' or no'.

afmResyncVer2

Increases the replication performance and scalability of a system that has heavy stress and workloads. It increases the message queuing performance by using an on-demand dependency resolution for queued messages, in case of recovery and/or resync is running.

Enable this parameter at the fileset level on an AFM single writer cache fileset and an AFM-DR primary fileset. For more information, see AFM resync version 2.

Valid values are 'yes' or no'. To set or unset the afmResyncVer2 parameter on an AFM or AFM-DR fileset, you need to stop or unlink the fileset. For more information, see Stop and start replication on a fileset.

afmRPO

Specifies the recovery point objective (RPO) interval for an AFM DR fileset. This attribute is disabled by default. You can specify a value with the suffix M for minutes, H for hours, or W for weeks. For example, for 12 hours specify 12H. If you do not add a suffix, the value is assumed to be in minutes. The range of valid values is 60 minutes - 2147483647 minutes.

To disable afmRPO, you can set the parameter value to afmRPO=disable. For example, mmchfileset fs1 afmFileset -p afmRPO=disable.

afmShowHomeSnapshot

Controls the visibility of the home snapshot directory in cache. For this to be visible in cache, this variable has to be set to yes, and the snapshot directory name in the cache and home cannot be the same.

yes

Specifies that the home snapshot link directory is visible.

no

Specifies that the home snapshot link directory is not visible.

For more information about the snapshot, see Peer snapshot -psnap.

afmSyncReadMount

Creates a separate mount path at the gateway node through which synchronous read calls are sent to the home cluster separately. This arrangement helps other operations that are running on the AFM fileset to synchronize with the home cluster by using the default mount path.

If the home cluster is responding slow or busy, the synchronous read operations request that are coming through separate mount path at the gateway node gets killed and the read request is re-tried without affecting the other operations as the current operation is performed on the separate mount path.

In case of AFM (SW/IW) fileset , when you enable the afmSyncReadMount parameter, it avoids dropping the whole read request queue during a busy or slow home response, thus avoid sending EIO back to the application which is performing the read operation at the Cache cluster. This behavior skip moving AFM fileset into a stale state and avoid recovery process for AFM SW/IW fileset.

You can enable afmSyncReadMount parameter on the AFM Single-Writer (SW), Independent-Writer(IW), Local-Update(LU), and Read-Only(RO) mode fileset by using mmcrfileset or mmchfileset command.

The valid values for the afmSyncReadMount parameter are yes or no.

To set or unset the afmSyncReadMount parameter on an AFM Single-Writer or AFM Independent-Writer mode fileset, you must stop or unlink the fileset. For more information, see Stop and start replication on a fileset.

afmTarget

There are two options allowed for afmTarget attribute value, disable and disable-online.

The disable option is used to convert AFM filesets to regular independent filesets; for example:

mmchfileset fs1 ro -p afmTarget=disable

You can use the optional --yes flag (hidden) with afmTarget parameter to disable AFM on the target fileset without warning and user confirmation. An example is shown:

mmchfileset fs1 ro -p afmTarget=disable --yes
         Fileset ro changed

After an AFM fileset is converted to a regular fileset, the fileset cannot be changed back to an AFM fileset.

The disable-online option is used to disable AFM fileset without unlinking the AFM RO and LU mode fileset. An example is shown as follows:

mmchfileset <filesystemname>  <filesetname>  -p  afmTarget=disable-online

When disable-online option is used for AFM fileset, the option disables the AFM target. Files and directories in that fileset are no longer in sync to the target or remote cluster.

After the AFM fileset is online disabled, the AFM fileset status cannot be converted back to the AFM fileset with target association. The disable-online option is supported on RO and LU mode fileset.

The disable-online option facilitates disabling of AFM fileset without unlinking or downtime.

--allow-permission-change PermissionChangeMode

Specifies the new permission change mode. This mode controls how chmod and ACL operations are handled on objects in the fileset. Valid modes are as follows:

chmodOnly

Specifies that only the UNIX change mode operation (chmod) is allowed to change access permissions (ACL commands and API will not be accepted).

setAclOnly

Specifies that permissions can be changed using ACL commands and API only (chmod will not be accepted).

chmodAndSetAcl

Specifies that chmod and ACL operations are permitted. If the chmod command (or setattr file operation) is issued, the result depends on the type of ACL that was previously controlling access to the object:

• If the object had a Posix ACL, it will be modified accordingly.
• If the object had an NFSv4 ACL, it will be replaced by the given UNIX mode bits.

Note: This is the default setting when a fileset is created.

chmodAndUpdateAcl

Specifies that chmod and ACL operations are permitted. If chmod is issued, the ACL will be updated by privileges derived from UNIX mode bits.

Note: The ACL will be updated in the following manner:

New access control entries (ACE) will be created from the mode bits for the special entries OWNER, GROUP, and EVERYONE and inserted in the beginning of the ACL.

The rest of the ACEs are then processed in this way:

1. If the ACE is not Allow/Deny or not for OWNER/GROUP/EVERYONE, it is left unchanged.
2. If the InheritOnly flag is set in the ACE, it is left unchanged.
3. If the InheritOnly flag is not set in the ACE:
   1. If the FileInherit or DirInherit flag is set, set the InheritOnly flag and unset the Inherited flag.
   2. Else, the ACE is deleted.

The mode is then derived from the ACL and set for the object.

Specific user/group and audit/alarm ACEs are untouched.

--allow-permission-inherit PermissionInheritMode

Specifies the new permission inherit mode. This mode controls how the permissions of a newly created object are inherited from its parent that has an NFSv4 ACL. Valid modes are as follows:

inheritAclOnly

Specifies that permissions of a newly created object will be inherited only from its parent's NFSv4 ACL.

Note: This is the default setting when a fileset is created.

inheritAclAndAddMode

Specifies that permissions of a newly created object will be inherited from its parent's NFSv4 ACL and the special entries OWNER, GROUP, and EVERYONE will use the provided mode and the umask from the open() or creat() call to set the new mode permissions.

--inode-limit MaxNumInodes[:NumInodesToPreallocate]

Specifies the new inode limit for the inode space that is owned by the specified fileset. The FilesetName or JunctionPath must refer to an independent fileset. The NumInodesToPreallocate specifies an optional number of additional inodes to pre-allocate for the inode space. Use the mmchfs command to change inode limits for the root fileset.

The MaxNumInodes and NumInodesToPreallocate values can be specified with a suffix, for example 100 K or 2 M.

Note: Preallocated inodes cannot be deleted or moved to another independent fileset. It is recommended to avoid preallocating too many inodes because there can be both performance and memory allocation costs associated with such preallocations. In most cases, there is no need to preallocate inodes because GPFS dynamically allocates inodes as needed.

--iam-mode Mode

Specifies an integrated archive manager (IAM) mode for the fileset. You can set IAM modes to modify some of the file-operation restrictions that normally apply to immutable filesets. The IAM modes are as follows, listed in order of increasing strictness:

• ad | advisory
• nc | noncompliant
• co | compliant
• cp | compliant-plus

Note that IAM modes can be upgraded from advisory to noncompliant to compliant to compliant-plus, but not downgraded. When a fileset is set to one of these IAM modes, a number of operations on files and directories are no longer allowed. Because the IAM mode for a fileset cannot be downgraded, those disallowed operations become persistent and cannot be undone. For more information, see Immutability and appendOnly features.

Exit status

0

Successful completion.

nonzero

A failure has occurred.

Security

You must have root authority or be a fileset owner to run the mmchfileset command with the -t option. All other options require root authority.

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