mmxcp command

Performs parallel copies of files and synchronization of files from source to target in a single IBM Storage Scale cluster. Verifies the result of a copy or sync operation. Lists information about any currently running mmxcp commands and configures the maximum number of mmxcp commands that can run at a single time.

Synopsis

mmxcp enable --source Directory [--snapshot <Device:[FilesetName:]SnapshotName>] --target Directory
            [--force] [--copy-attrs {Attribute[,Attribute...] | ALL}] [--copy-migrated] [--hardlinks] [-N {Node[,Node...] | NodeFile | NodeClass}]
            [-a IscanThreads] [-B MaxFiles] [-g GlobalWorkDirectory] [-L n] [-m ThreadLevel] [-n DirThreadLevel] 
            [-s LocalWorkDirectory] [--sort-buffer-size Size] [--qos QOSClass]

mmxcp sync --source Directory [--snapshot <Device:[FilesetName:]SnapshotName>] --target Directory

mmxcp verify --source Directory [--snapshot <Device:[FilesetName:]SnapshotName>] --target Directory
            [--check {Attribute[,Attribute...] | ALL}]

mmxcp list {all | xcpID} [-Y]

mmxcp config {--get-max-value | --set-max-value Value | --clear-max-value |
              --get-default-max-files | --set-default-max-files defaultMaxFiles | --clear-default-max-files |             
              --get-default-thread-level | --set-default-thread-level defaultThreadLevel | --clear-default-thread-level
                           }

Availability

Available on all IBM Spectrum® Scale editions. Available on Linux® x86_64 and Linux PPC64LE.

Description

The mmxcp enable command performs parallel copies of files from the specified source to the specified target in a single IBM Storage Scale cluster. It calls the mmapplypolicy command directly and uses the policy engine LIST rule functions to execute the /usr/lpp/mmfs/bin/xcputil.sh script. It can copy files within a single file system or between file systems in a single cluster. It cannot copy across clusters. It can copy in a live file system or from snapshots.

The mmxcp sync command performs a synchronize operation from the source directory to the target directory. It uses only a single process, but will only try to copy files that are missing or appear to be different.

The mmxcp verify command performs a quick compare of the data in the source and target directories. Any difference in the metadata will be flagged.

The mmxcp list command lists configuration information of all currently running instances of mmxcp within the cluster, or the configuration of the specified xcpID.

The mmxcp config command either retrieves the current value of the maximum number of parallel copy commands allowed in the cluster, or sets this value.

Command messages are written to the /var/adm/ras/mmxcp.log. The log files are rotated by using the Linux log rotate function at 1 M size.

Parameters

enable

Enables a single instance of a parallel copy. Multiple parallel copies with different source and targets can run at the same time until the limit defined with the --get-max-value value option of the mmxcp config command.

--source Directory

Specifies the fully qualified path of an IBM Storage Scale file system subtree that is the source of the copy operation, or if the --snapshot flag is included, this path is relative from the snapshot location. To include all of the files in the snapshot, specify ".". This file system must be mounted on the node where the command is run.

--snapshot <Device:[FilesetName:]SnapshotName>

Indicates that the source path is a relative one within a snapshot. At a minimum, the file system name and snapshot name must be provided. If a fileset name is provided then that fileset is verified to be an independent fileset within the file system and the snapshot name is a snapshot of the fileset. This flag is optional.

--target Directory

Specifies the fully qualified path name of an IBM Storage Scale file system subtree, which is the destination of the copy operation. This file system must be mounted on the node where the command is run.

--force

If an existing destination file cannot be overwritten, remove it and try again. This flag is optional.

--copy-attrs {Attribute[,Attribute...] | ALL}

Supports copying of specified IBM Storage Scale file attributes or ALL additional attributes.

appendonly: Copies the IBM Storage Scale appendonly attributes, if present.
compression: Copies IBM Storage Scale compression attributes, if present. If any of the source files are compressed using mmchattr, then this option does the same for the target files. If the source file is marked as illcompressed and the compression attribute is specified, then the target file will be compressed.

Note: Only Linux nodes in the same cluster running IBM Storage Scale 5.1.4 and later can replicate the compression attribute on any files they are recruited to copy.
immutable: Copies the IBM Storage Scale immutable attributes, if present.

--copy-migrated

Reads the content of any file in the Directory in IBM Spectrum Protect for space management migrated state and then copies it. By that, the file is recalled. This is not recommended when many files are migrated. By default, files that are migrated will be skipped and not copied. This flag is optional.

--hardlinks

Executes an additional pass through the source files looking specifically for hardlinked files and copies these files as a single batch. This action links any files that were initially copied as normal files due to the mmxcp command dividing the work for parallel execution. End of change

-N {Node[,Node...] | NodeFile | NodeClass}

Limits the nodes that perform the copy operation to be the intersection of these nodes with the Linux nodes that have both the source and target file systems that are mounted in the cluster. If the intersection results in no nodes, an error is returned. The -N option supports a comma-separated list of nodes, a full path name to a file containing node names, or a predefined node class. If the -N option is not specified, then the command runs parallel instances of the copy process on the nodes that are specified by the defaultHelperNodes attribute of the mmchconfig command. If the defaultHelperNodes attribute is not set, then the command runs only on the node where the mmxcp command is issued. For more information about the defaultHelperNodes attribute, see mmchconfig command. This flag is optional.

Add the following flags that are passed directly to the mmapplypolicy command to improve performance of the copy.

When there are many millions of files to scan and process, the mmapplypolicy command can be very demanding of memory, CPU, I/O, and storage resources. For more information, see mmapplypolicy command.

-g GlobalWorkDirectory

Specifies a global work directory in which one or more nodes can store temporary files during mmapplypolicy command processing. The default location is the directory .mmSharedTmpDir at the root level of the source file system. This flag is optional.

-a IscanThreads

Specifies the number of threads and sort pipelines each node runs during the parallel inode scan and policy evaluation. It affects the execution of the high-performance protocol that is used when both -g and -N are specified. The default value is 2. This flag is optional.

-B MaxFiles

Specifies how many files are passed for each invocation of the EXEC script. The default value is 100. This flag is optional.

-L n

Controls the level of information that is displayed by the mmapplypolicy command. Larger values indicate the display of more detailed information. This flag is optional.

-m ThreadLevel

The number of threads that are created and dispatched within each mmapplypolicy process during the policy execution phase. The default value is 24. This flag is optional.

-n DirThreadLevel

The number of threads that are created and dispatched within each mmapplypolicy process during the directory scan phase. The default value is 24. This flag is optional.

-s LocalWorkDirectory

Specifies a local directory in which one or more nodes can store temporary files during mmapplypolicy command processing. The default local work directory is /tmp. This flag is optional.

--sort-buffer-size Size

Sets the sort-buffer size that is passed to the sort command. This flag is optional.

--qos QosClass

Specifies the Quality of Service for I/O operations (QoS) class to which the instance of the command is assigned. If you do not specify this parameter, the instance of the command is assigned by default to the maintenance QoS class. This parameter has no effect unless the QoS service is enabled. For more information, see the topic mmchqos command. Specify one of the following QoS classes:

maintenance: This QoS class is typically configured to have a smaller share of file system IOPS. Use this class for I/O-intensive, potentially long-running IBM Storage Scale commands, so that they contribute less to reducing overall file system performance.
other: This QoS class is typically configured to have a larger share of file system IOPS. Use this class for administration commands that are not I/O-intensive.

For more information, see Setting the Quality of Service for I/O operations.

sync

Performs a single process sync operation between a source/snapshot and a target directory from a previously executed mmxcp copy. Files that appear different or are missing will be copied to the target directory. Several attributes are checked for each object including file size and last modification time. Sync will not enforce file compression. Sync of migrated files will cause a file to be recalled prior to copy. Command executes on the node from which it is issued only. Multiple copies and syncs with different source and targets can run at the same time up until the limit defined with the --get-max-value value option of the mmxcp config command.

--source Directory: Specifies the fully qualified path of an IBM Storage Scale file system subtree that is the source of the sync operation, or if the --snapshot flag is included, this path is relative from the snapshot location. To include all of the files in the snapshot, specify ".". This file system must be mounted on the node where the command is run.

--snapshot <Device:[FilesetName:]SnapshotName>: Indicates that the source path is a relative one within a snapshot. At a minimum, the file system name and snapshot name must be provided. If a fileset name is provided then that fileset is verified to be an independent fileset within the file system and the snapshot name is a snapshot of the fileset. This flag is optional.

--target Directory: Specifies the fully qualified path name of an IBM Storage Scale file system subtree, which is the destination of the sync operation. This file system must be mounted on the node where the command is run.

verify

Performs a quick compare of metadata between a source/snapshot and a target directory from a previously executed mmxcp copy. Several attributes are checked for each object including file type, user/owner, group, and access rights.

--source Directory

Specifies the fully qualified path of an IBM Storage Scale file system subtree that is the source of the verify operation, or if the --snapshot flag is included, this path is relative from the snapshot location. To verify all of the files in the snapshot, specify ".". This file system must be mounted on the node where the command is run.

--snapshot <Device:[FilesetName:]SnapshotName>

--target Directory

Specifies the fully qualified path name of an IBM Storage Scale file system subtree containing files to be verified against the source subtree. This file system must be mounted on the node where the command is run.

--check {Attribute[,Attribute...] | ALL}

Specifies a list of additional attributes to compare, or ALL additional attributes. Standard metadata is verified with this option as well. Extra processing is required and might add to the time needed to complete the verification. This flag is optional. Attributes currently supported are:

acl: Compares NFSv4 ACLs or extended POSIX ACLs, if present.
appendonly: Compares the IBM Storage Scale appendonly attributes, if present.
compression: Compares IBM Storage Scale compression attributes, if present.
immutable: Compares the IBM Storage Scale immutable attributes, if present.

list

Lists configuration information of all currently running instances of mmxcp within the cluster, or the configuration of the specified xcpID.

all: Lists configuration of all currently running instances of mmxcp command in the cluster
xcpID: Show the configuration for the specified xcpID
-Y: Show with the output in machine-readable (colon delimited) format

config

Manages the default values for the specified configuration parameters.

--get-max-value: Displays the current value of the maximum number of parallel copy commands that can be active in the cluster simultaneously. The default value is 10.
--set-max-value: Sets the maximum number of parallel copy commands that can be active in the cluster simultaneously. Valid values are between 1 and 100.
--clear-max-value: Removes the value set by the --set-max-value option, if present.
--get-default-max-files: Displays the new default value for MaxFiles, if present. See the -B MaxFile option for this setting.

--set-default-max-files defaultMaxFiles: Sets a new default value for MaxFiles.

--clear-default-max-files: Removes the value set by the --set-default-max-files option, if present.

--get-default-thread-level: Displays the new default value for ThreadLevel, if present. See the -m ThreadLevel option for this setting.

--set-default-thread-level defaultThreadLevel: Sets a new default value for ThreadLevel.

--clear-default-thread-level: Removes the value set by the --set-default-thread-level option, if present.

Exit status

0: Successful completion.
nonzero: A failure has occurred. Errors are written to /var/adm/ras/mmxcp.log.

Security

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

Examples

To copy a global snapshot of file system, newfs, to the target file system, nextfs, with 500 files that are passed to each cp exec script, by using a global subdirectory to store policy temp files, issue the following command:

# mmxcp enable --source . --snapshot newfs:snap1 --target /nextfs -g /global -B 500

A sample output is as follows:

[I] Beginning verification of parallel copy command parameters.
[I] Running policy commands with generated rules based on input configuration.
[I] Participating nodes will log information to their copy of /var/adm/ras/mmxcp.log.
[I] 2021-07-16@18:14:06.548 Directory entries scanned: 11088.
[I] 2021-07-16@18:23:36.540 Parallel-piped sort and policy evaluation. 11088 files scanned.
[I] 2021-07-16@18:23:36.691 Piped sorting and candidate file choosing. 11088 records scanned.
[I] 2021-07-16@18:35:19.751 Policy execution. 11088 files dispatched.  .....=..
[I] 2021-07-16@18:38:47.819 Policy execution. 11088 files dispatched.
[I] Successfully completed running parallel copy command.

To copy from one subdirectory to another within the same file system by using all the nodes in the cluster, issue the following command:

# mmxcp enable --source /newfs/source --target /newfs/target -N all

A sample output is as follows:

[I] Beginning verification of parallel copy command parameters.
[I] Running policy commands with generated rules based on input configuration.
[I] Participating nodes will log information to their copy of /var/adm/ras/mmxcp.log.
[I] 2021-07-16@19:26:31.625 Directory entries scanned: 17248.
[I] 2021-07-16@19:26:38.971 Parallel-piped sort and policy evaluation. 17248 files scanned.
[I] 2021-07-16@19:26:43.410 Piped sorting and candidate file choosing. 17248 records scanned.
[I] 2021-07-16@19:40:31.272 Policy execution. 17248 files dispatched.
[I] Successfully completed running parallel copy command.

To limit the maximum number of mmxcp commands that can run concurrently in the cluster to 1, issue the following command:
```
# mmxcp config --set-max-value 1
```
A sample output is as follows:
```
[I] Successfully set maximum number of parallel copy commands in this cluster: 1
```
To set a new default value for the number of files that can be passed to each invocation of the EXEC script, issue the following command:
```
# mmxcp config --set-default-max-files 5000
```
A sample output is as follows:
```
[I] Successfully set the default value for MaxFiles in this cluster: 5000
```
To set a new default value for the number of threads that mmapplypolicy might create during the execution phase, issue the following command:
```
# mmxcp config --set-default-thread-level 30
```
A sample output is as follows:
```
[I] Successfully set the default value for ThreadLevel in this cluster: 30
```

To verify the files copied, issue the following command:

# mmxcp verify --source /testfs/source2 --target /testfs/target2 --check ALL

A sample output is as follows:

[I] Beginning verification.
[I] Compare contents of /testfs/source2 against /testfs/target2
[E] MetaData Doesn't Match - ./1Kfile9.new:regular file 0 0 -rw-r--r-- 1024 2022-07-28 11:29:12.504449000 -0400 != /testfs/target2/1Kfile9.new:regular file 0 0 -rwxrwxrwx 1024 2022-07-28 11:29:12.504449000 -0400
[I] Processed 10 items for copy verification.
[E] Verify Failed. 1 errors encountered.
mmxcp: Command failed. Examine previous error messages to determine cause.

To synchronize the contents of one directory to another, issue the following command:

# mmxcp sync --source /ibm/fs0/source --target /ibm/fs0/target

A sample output is as follows:

[I] Beginning verification of sync command parameters.
[I] Starting to sync contents of /ibm/fs0/source to /ibm/fs0/target
    Please be patient ...
[I] Information will be logged to /var/adm/ras/mmxcp.log.
[I] Successfully completed running sync command.

Location

/usr/lpp/mmfs/bin

mmxcp command

Synopsis

Availability

Description

Parameters

Exit status

Security

Examples

See also

Location