mmcrfileset command

Availability

Available with IBM Spectrum Scale™ Standard Edition or higher.

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 newly created fileset.

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

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.

For example:

• The following command creates a single-writer AFM fileset in a GPFS file system fs3 with a remote file system mounted at /gpfs/thefs1 from node c41bn3, using protocol nfs://:

  mmcrfileset fs3 singleWriter2  -p afmtarget=nfs://c41bn3/gpfs/thefs1/target2 -p afmmode=sw --inode-space new 
  
  Fileset singleWriter2 created with id 23 root inode 3145731. 

• The following command creates a single-writer AFM fileset in a GPFS file system fs3 with a GPFS remote file system mounted at /gpfs/thefs1, using protocol gpfs://:

  mmcrfileset fs3 singleWriter1  -p afmtarget=gpfs:///gpfs/thefs1/target1 -p afmmode=sw --inode-space new
  
  Fileset singleWriter1 created with id 21 root inode 2883587.

  Note that in this case /// is needed because Host is not provided.

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

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.

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 Spectrum 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 MB, 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 MB. The default value is 1024 MB. 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 MB, 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 MB. The default value of this parameter is 1024 MB, 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.

afmRPO

Specifies the recovery point objective (RPO) interval in minutes for a primary fileset. Disabled by default.

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 cache and home should not be the same.

yes

Specifies that the home snapshot link directory is visible.

no

Specifies that the home snapshot link directory is not visible.

See Peer snapshot -psnap.

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

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

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