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[=NumDirectoryEntries]]
         [--compression {yes | no | z | lz4 | zfast | alphae | alphah}]
         [--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 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 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 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 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[=NumDirectoryEntries]

Sets the minimum compaction size of the directories that are specified in the Filename parameter. The minimum compaction size is the number of directory slots, including both full and empty slots, that a directory is allowed to retain when it is automatically compacted. In IBM Spectrum Scale v4.1 or later, by default, a directory is automatically compacted as far as possible. However, in systems in which many files are added to and removed from a directory in a short time, file system performance might be improved by setting the minimum compaction size of the directory.

The compact parameter sets the minimum compaction size of a directory to the specified number of slots. For example, if a directory contains 5,000 files and you set the minimum compaction size to 50,000, then the file system adds 45,000 directory slots. The directory can grow beyond 50,000 entries, but the file system does not allow the directory to be compacted below 50,000 slots.

Set NumDirectoryEntries to the total number of directory slots that you want to keep, including files that the directory already contains. You can specify the number of directory slots either as an integer or as an integer followed by the letter k (1000 slots) or m (1,000,000 slots). If you expect the average length of file names to be greater than 19 bytes, calculate the number of slots by the following formula:

NumDirectoryEntries = n * ( 1 + ceiling((namelen - 19)/32)

where:

n: Specifies the number of entries (file names) in the directory.
ceiling(): A function that rounds a fractional number up to the next highest integer. For example, ceiling(1.03125) returns 2.
namelen: Specifies the expected average length of file names.

For example, if you want 50,000 entries with an average file name length of 48, then NumDirectoryEntries = 50000 * (1 + 1) = 100000.

To restore the default behavior of the file system, specify the compact=0. The directory is compacted as far as possible.

To see the current value of this parameter, run the mmlsattr command with the -L option. For more information, see the topic mmlsattr command. To set or read the value of this parameter in a program, see the topics gpfs_prealloc() subroutine and gpfs_fstat_x() subroutine.

Note: If the file system was created earlier than IBM Spectrum Scale v4.1, the NumDirectoryEntries value is not supported. The compact parameter specified by itself converts the directory to v4.1 format and compacts the directory as far as possible.

--compression {yes | no | z | lz4 | zfast | alphae | alphah}

Compresses or decompresses the specified files. The compression libraries are intended primarily for the following uses:

z: Cold data. Favors compression efficiency over access speed.
lz4: Active, nonspecific data. Favors access speed over compression efficiency.
zfast: Active genomic data in FASTA, SAM, or VCF format.
alphae: Active genomic data in FASTQ format. Slightly favors compression efficiency over access speed.
alphah: Active genomic data in FASTQ format. Slightly favors access speed over compression efficiency.

The following table summarizes the effect of each option on compressed or uncompressed files:

Table 1. Effects of options on compressed or uncompressed files.
Option	Uncompressed files	Compressed files that were generated with a different compression library	Compressed files that were generated with the same compression library
yes	Compress with z	Not affected	Not affected
no	Not affected	Decompress	Decompress
z	Compress with z	Re-compress with z	Not affected
lz4	Compress with lz4	Re-compress with lz4	Not affected
zfast	Compress with zfast	Re-compress with zfast	Not affected
alphae	Compress with alphae	Re-compress with alphae	Not affected
alphah	Compress with alphah	Re-compress with alphah	Not affected

You can use the -I defer option to defer the operation until a later call to mmrestripefs or mmrestripefile. For more information, see 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