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[=[Option][,Option]...]]
         [--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]]
         {--inode-number [SnapPath/]InodeNumber [[SnapPath/]InodeNumber...] |
          Filename [Filename...]}

Availability

Available on all IBM Storage Scale editions.

Description

Use the mmchattr command to change the replication attributes, storage pool assignments, retention and immutability attributes, I/O caching policy, file compression or decompression of files in the file system, and resolve data block replica mismatches using the gpfs.readReplicaRule extended attribute. For more information, see Replica mismatches.

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, replication factor for some blocks of the file might increase after the mmchattr command ends. If later (when you add another disk), free space becomes available in 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 unless you are changing the gpfs.readReplicaRule extended attribute and you are the file owner, in which case read permission is sufficient.

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[=Option][,Option]...]]

Where Option can be either NumDirectoryEntries, indblk or fragment.

Performs any of the three operations:

Sets the minimum compaction size of the directories that are specified in the Filename parameter.
Deletes the indirect blocks that are redundant.
Reduces the last logical data block to the number of subblocks that are required to store the data.

NumDirectoryEntries

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. By default, in IBM Storage Scale 4.1 or later, a directory is compacted as much 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: The NumDirectoryEntries value is not supported if the file system was created in IBM Storage Scale 4.1 or earlier. The compact parameter that is specified converts the directory to 4.1 format and compacts the directory as far as possible.

The mmchattr --compact=NumDirectoryEntries command run for a regular file will fail with the following error message Compact failed: NumDirectoryEntries is supported only for directory.

indblk

Deallocates all redundant indirect blocks of a regular file.

When a file is truncated to zero file size, its indirect blocks can be deallocated. However, in versions earlier than 5.0.4.1, IBM Storage Scale retains the redundant indirect blocks in such scenarios. For a file system that has a large number of files, the metadata disk space wasted by these indirect blocks can be significant. You can use the indblk option to deallocate the unnecessary indirect blocks.

fragment

Applies a ShrinktoFit operation on a regular file to reduce disk usage.

The fragment option reduces the last logical block of data of the file to the actual number of subblocks that are required. When a file is closed after being written to, GPFS tries to reduce the last logical block of data of the file to the actual number of subblocks required to save disk space. Under normal circumstances, the file is compacted when it is closed. In a few rare cases, however, the shrink might fail and leave a full data block for the last logical block of data of the file. The fragment option shrinks the last logical block to the actual number of subblocks required.

Note: Specify only the --compact parameter, without any of the suboptions, to perform both the indblk and fragment operations.

--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	Will it benefit from the hardware compression feature that is available starting with IBM® z15®?
yes	Compress with z	Not affected	Not affected	Yes
no	Not affected	Decompress	Decompress	Yes
z	Compress with z	Re-compress with z	Not affected	Yes
lz4	Compress with lz4	Re-compress with lz4	Not affected	No
zfast	Compress with zfast	Re-compress with zfast	Not affected	Yes
alphae	Compress with alphae	Re-compress with alphae	Not affected	Yes
alphah	Compress with alphah	Re-compress with alphah	Not affected	Yes

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.

--inode-number [SnapPath/]InodeNumber

The inode number of the file to be changed. You must enter at least one inode number or file name, but not both; if you specify more than one inode number, delimit each inode number by a space. If the current working directory is not already inside the active file system or snapshot, then the inode number has to be prefixed by the path to the active file system or snapshot. For example:

mmchattr –inode-number /fs0/.snapshots/snap1/34608

You must have root authority to use this option.

Filename

The name of the file to be changed. You must enter at least one file name or inode number, but not both; if you specify more than one file name, 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 unless you are changing the gpfs.readReplicaRule extended attribute and you are the file owner, in which case read permission is sufficient.

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 the following command:
```
# mmchattr -m 2 -r 2 /fs1/project7.resource
```
To confirm the change, issue the following command:
```
# mmlsattr project7.resource
```
A sample output is as follows:
```
   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 
```
A sample output is as follows:
```
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

A sample output is as follows:

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 the following commands:

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