mmcrfileset command

Availability

Available on all IBM Storage Scale editions.

Description

The mmcrfileset command constructs a new fileset with the specified name. The new fileset is empty except for a root directory, and does not appear in the directory namespace until the mmlinkfileset command is issued. The mmcrfileset command is separate from the mmlinkfileset command to allow the administrator to establish policies and quotas on the fileset before it is linked into the namespace.

For information on filesets, see Filesets.

Parameters

Device

The device name of the file system to contain the new fileset.

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

FilesetName

Specifies the name of the fileset to be created.

Note the following restrictions on fileset names:

• The name must be unique within the file system.
• The length of the name must be in the range 1-255.
• The name root is reserved for the fileset of the root directory of the file system.
• The name cannot be the reserved word new. However, the character string new can appear within a fileset name.
• The name cannot begin with a hyphen (-).
• The name cannot contain the following characters: / ? $ & * ( ) ` # | [ ] \
• The name cannot contain a white-space character such as blank space or tab.

-p afmAttribute=Value

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

The following AFM configuration parameter is required for the mmcrfileset command:

afmTarget

Identifies the home that is associated with the cache; specified in either of the following forms:

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

The following optional AFM configuration parameters are also 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 (SW, IW, and primary), where data from cache is pushed to home.

Valid values are between 1 and 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.

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.

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

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.

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.

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

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

The following command is an example of setting a user-defined gateway node to an AFM or AFM DR fileset -

#mmcrfileset <FileSystem> <fileset> -p afmMode=<afmMode>,afmGateway=<GatewayNode> --inode-space new -p afmTarget=<Target>

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.

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.

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.

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

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.

-t Comment

Specifies an optional comment that appears in the output of the mmlsfileset command. This comment must be less than 256 characters in length.

--inode-space {new | ExistingFileset}

Specifies the type of fileset to create, which controls how inodes are allocated:

new

Creates an independent fileset and its own dedicated inode space.

ExistingFileset

Creates a dependent fileset that will share inode space with the specified ExistingFileset. The ExistingFileset can be root or any other independent fileset.

If --inode-space is not specified, a dependent fileset will be created in the root inode space.

--inode-limit MaxNumInodes[:NumInodesToPreallocate]

Specifies the inode limit for the new inode space. The NumInodesToPreallocate specifies an optional number of inodes to preallocate when the fileset is created. This option is valid only when creating an independent fileset with the --inode-space new parameter.

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.

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

Exit status

0

Successful completion.

nonzero

A failure has occurred.

Security

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