mmchattr command

Changes attributes of one or more GPFS™ files.

Synopsis

mmchattr [-m MetadataReplicas] [-M MaxMetadataReplicas]
         [-r DataReplicas] [-R MaxDataReplicas] [-P DataPoolName]
         [-D {yes | no}] [-I {yes | defer}] [-i {yes | no}]
         [-a {yes | no}] [-l]
         [{--set-attr AttributeName[=Value] [--pure-attr-create | --pure-attr-replace]} |
          {--delete-attr AttributeName [--pure-attr-delete]}]
         [--hex-attr] [--hex-attr-name] [--no-attr-ctime]
         [--compact]
         [--compression {yes | no}]
         [--block-group-factor BlockGroupFactor]
         [--write-affinity-depth WriteAffinityDepth]
         [--write-affinity-failure-group "WadfgValueString"]
         [--indefinite-retention {yes | no}]
         [--expiration-time yyyy-mm-dd[@hh:mm:ss]]
         Filename [Filename...]

Availability

Available on all IBM Spectrum Scale™ editions.

Description

Use the mmchattr command to change the replication attributes, storage pool assignments, retention and immutability attributes, I/O caching policy, and file compression or decompression of files in the file system.

The replication factor must be less than or equal to the maximum replication factor for the file. If insufficient space is available in the file system to increase the number of replicas to the value requested, the mmchattr command ends. However, some blocks of the file might have their replication factor increased after the mmchattr command ends. If more free space becomes available in the file system later (when, for example, you add another disk to the file system), you can then issue the mmrestripefs command with the -r or -b option to complete the replication of the file. The mmrestripefile command can be used in a similar manner. You can use the mmlsattr command to display the replication values.

Data of a file is stored in a specific storage pool. A storage pool is a collection of disks or RAIDs with similar properties. Because these storage devices have similar properties, you can manage them as a group. You can use storage pools to do the following tasks:

Partition storage for the file system
Assign file storage locations
Improve system performance
Improve system reliability

The Direct I/O caching policy bypasses file cache and transfers data directly from disk into the user space buffer, as opposed to using the normal cache policy of placing pages in kernel memory. Applications with poor cache hit rates or a large amount of I/O might benefit from the use of Direct I/O.

The mmchattr command can be run against a file in use.

You must have write permission for the files whose attributes you are changing.

Parameters

-m MetadataReplicas

Specifies how many copies of the file system's metadata to create. Valid values are 1, 2, and (for GPFS V3.5.0.7 and later) 3. This value cannot be greater than the value of the MaxMetadataReplicas attribute of the file.

-M MaxMetadataReplicas

Specifies the maximum number of copies of indirect blocks for a file. Space is reserved in the inode for all possible copies of pointers to indirect blocks. Valid values are 1, 2, and (for GPFS V3.5.0.7 and later) 3. This value cannot be less than the value of the DefaultMetadataReplicas attribute of the file.

-r DataReplicas

Specifies how many copies of the file data to create. Valid values are 1, 2, and (for GPFS V3.5.0.7 and later) 3. This value cannot be greater than the value of the MaxDataReplicas attribute of the file.

-R MaxDataReplicas

Specifies the maximum number of copies of data blocks for a file. Space is reserved in the inode and indirect blocks for all possible copies of pointers to data blocks. Valid values are 1, 2, and (for GPFS V3.5.0.7 and later) 3. This value cannot be less than the value of the DefaultDataReplicas attribute of the file.

-P DataPoolName

Changes the assigned storage pool of the file to the specified DataPoolName. The caller must have superuser or root privileges to change the assigned storage pool.

-D {yes | no}

Enable or disable the Direct I/O caching policy for files.

-I {yes | defer}

Specifies whether replication and migration between pools, or file compression or decompression, is to be performed immediately (-I yes), or deferred until a later call to mmrestripefs or mmrestripefile (-I defer). By deferring the operation, you can complete it when the system is not loaded with processes or I/O. Also, if multiple files are affected, the data movement can be done in parallel. The default is -I yes. For more information about file compression and decompression, see the --compression option in this topic.

-i {yes | no}

Specifies whether the file is immutable (-i yes) or not immutable (-i no).

Note: The immutability attribute is specific to the current instance of the file. Restoring an image of the file to another location does not retain the immutability option. You must set it yourself.

-a {yes | no}

Specifies whether the file is in appendOnly mode (-a yes) or not (-a no).

Notes:

The appendOnly setting is specific to the current instance of the file. Restoring an image of the file to another location does not retain the appendOnly mode. You must set it yourself.
appendOnly mode is not supported for AFM filesets.

-l

Specifies that this command works only with regular files and directories and does not follow symlinks. The default is to follow symlinks.

--set-attr AttributeName[=Value]

Sets the specified extended attribute name to the specified Value for each file. If no Value is specified, --set-attr AttributeName sets the extended attribute name to a zero-length value.

--pure-attr-create

When this option is used, the command fails if the specified extended attribute exists.

--pure-attr-replace

When this option is used, the command fails if the specified extended attribute does not exist.

--delete-attr AttributeName

Removes the extended attribute.

For example, To remove wad, wadfg, and bgf, enter the following command:

mmchattr --delete-attr gpfs.WAD,gpfs.WADFG,gpfs.BGF

--pure-attr-delete

When this option is used, the command fails if the specified extended attribute does not exist.

--hex-attr

Inputs the attribute value in hex.

--hex-attr-name

Inputs the attribute name in hex.

--no-attr-ctime

Changes the attribute without setting the ctime of the file. This is restricted to root only.

--compact

Converts a directory to GPFS 4.1 format (if needed) and then compacts the directory, potentially reducing its size. If many files were previously removed from the directory, --compact can improve the performance of directory operations. The directory name is specified as Filename. If the value specified for Filename is not a directory, it is ignored.

Note: Directories that are created with a GPFS 4.1 or higher file system, or directories that were previously converted to GPFS 4.1 format, are compacted automatically as files are removed. Using the --compact option is not necessary in these instances.

--compression {yes | no}

Compresses or decompresses the specified files. You can use the -I defer option to defer the operation until a later call to mmrestripefs or mmrestripefile. For more information, see the topic File compression.

--block-group-factor BlockGroupFactor

Specifies how many file system blocks are laid out sequentially on disk to behave like a single large block. This option only works if --allow-write-affinity is set for the data pool. This applies only to a new data block layout; it does not migrate previously existing data blocks.

--write-affinity-depth WriteAffinityDepth

Specifies the allocation policy to be used. This option only works if --allow-write-affinity is set for the data pool. This applies only to a new data block layout; it does not migrate previously existing data blocks.

--write-affinity-failure-group "WadfgValueString"

Indicates the range of nodes (in a shared nothing architecture) where replicas of blocks in the file are to be written. You use this parameter to determine the layout of a file in the cluster so as to optimize the typical access patterns of your applications. This applies only to a new data block layout; it does not migrate previously existing data blocks.

"WadfgValueString" is a semicolon-separated string identifying one or more failure groups in the following format:

FailureGroup1[;FailureGroup2[;FailureGroup3]]

where each FailureGroupx is a comma-separated string identifying the rack (or range of racks), location (or range of locations), and node (or range of nodes) of the failure group in the following format:

Rack1{:Rack2{:...{:Rackx}}},Location1{:Location2{:...{:Locationx}}},ExtLg1{:ExtLg2{:...{:ExtLgx}}}

For example, the following value

1,1,1:2;2,1,1:2;2,0,3:4

means that the first failure group is on rack 1, location 1, extLg 1 or 2; the second failure group is on rack 2, location 1, extLg 1 or 2; and the third failure group is on rack 2, location 0, extLg 3 or 4.

If the end part of a failure group string is missing, it is interpreted as 0. For example, the following are interpreted the same way:

2
2,0
2,0,0

Notes:

Only the end part of a failure group string can be left off. The missing end part may be the third field only, or it may be both the second and third fields; however, if the third field is provided, the second field must also be provided. The first field must always be provided. In other words, every comma must both follow and precede a number; therefore, none of the following are valid:
```
2,0,
2,
,0,0
0,,0
,,0
```
Wildcard characters (*) are supported in these fields.

--indefinite-retention {yes | no}

Turns indefinite retention on or off. An alternative form of this parameter is -e {yes | no}. See --expiration-time.

--expiration-time yyyy-mm-dd[@hh:mm:ss]

Specifies the expiration time. An alternative form of this parameter is -E yyyy-mm-dd[@hh:mm:ss]. Expiration time and indefinite retention are independent attributes. You can change the value of either one without affecting the value of the other.

Filename

The name of the file to be changed. You must enter at least one file name; if you specify more than one, delimit each file name by a space. Wildcard characters are supported in file names; for example, project*.sched.

Exit status

0: Successful completion.

nonzero: A failure has occurred.

Security

You must have write access to the file to run the mmchattr command.

You can issue the mmchattr command only from a node in the GPFS cluster where the file system is mounted.

Examples

To change the metadata replication factor to 2 and the data replication factor to 2 for the project7.resource file in file system fs1, issue this command:
```
mmchattr -m 2 -r 2 /fs1/project7.resource
```
To confirm the change, issue this command:
```
mmlsattr project7.resource
```
The system displays information similar to:
```
   replication factors
 metadata(max) data(max) file    [flags]
 ------------- --------- ---------------
       2 (  2)   2 (  2) /fs1/project7.resource
```
Migrating data from one storage pool to another using the mmchattr command with the -I defer option, or the mmapplypolicy command with the -I defer option causes the data to be ill-placed. This means that the storage pool assignment for the file has changed, but the file data has not yet been migrated to the assigned storage pool.
The mmlsattr -L command causes show ill-placed flags on the files that are ill-placed. The mmrestripefs, or mmrestripefile command can be used to migrate data to the correct storage pool, and the ill-placed flag is cleared. This is an example of an ill-placed file:
```
mmlsattr -L 16Kfile6.tmp 
```
The system displays output similar to this:
```
file name:            16Kfile6.tmp
metadata replication: 1 max 2
data replication:     1 max 2
immutable:            no
appendOnly:           no
flags:                directio
storage pool name:    system
fileset name:         root
snapshot name:
creation time:        Thu Mar 28 14:49:23 2013
Misc attributes:      ARCHIVE
```

The following example shows the result of using the --set-attr parameter.

mmchattr --set-attr user.pfs001=testuser 16Kfile7.tmp
mmlsattr -L -d 16Kfile7.tmp

The system displays output similar to this:

file name:            16Kfile7.tmp
metadata replication: 1 max 2
data replication:     1 max 2
immutable:            no
appendOnly:           no
flags:
storage pool name:    system
fileset name:         root
snapshot name:
creation Time:        Fri Feb 24 12:00:13 2012
Misc attributes:      ARCHIVE
user.pfs001:         "testuser"

To set the write affinity failure group for a file and to see the results, issue these commands:

mmchattr --write-affinity-failure-group="64,0,0;128,0,1;128,0,2" /gpfs1/testfile
mmlsattr -L /gpfs1/testfile