scalectl utils command

Performs parallel file copies and synchronizes files from a source to a target within a single IBM Storage Scale cluster. Verifies the results of copy and synchronization operations. Lists information about active copy operations and sets the maximum number of parallel copy operations that can run in the cluster.

Synopsis

scalectl utils xcp enable -s Directory [-d Device] [-f FilesetName] [-n SnapshotName] -t Directory
[--force] [--copy-attributes {Attribute[,Attribute...]}] [--copy-migrated] [--hard-links] [--nodes {Node[,Node...]}]
[--scan-threads IscanThreads] [--max-files MaxFiles] [--global-work-directory GlobalWorkDirectory] [--logging-level LoggingLevel] [--thread-level ThreadLevel] [--directory-thread-level DirThreadLevel]
[--local-work-directory LocalWorkDirectory] [--sort-buffer-size Size] [--qos QOSClass]
Or
scalectl utils xcp get
Or
scalectl utils xcp getconfig [--all-domains]
Or
scalectl utils xcp list [--all-domains] [-n MaxItems] [-x]
Or
scalectl utils xcp sync [-d Device] [-f FilesetName] [-n SnapshotName] [-s Directory] [-t Directory]
Or
scalectl utils xcp updateconfig [--all-domains] [--max-files MaxFiles] [--max-parallel MaxParallel] [--max-threads MaxThreads]
Or
scalectl utils xcp verify [-a {Attribute[,Attribute...]}] [-d Device] [-f FilesetName] [-n SnapshotName] [-s Directory] [-t Directory]

Availability

Available on all IBM Storage Scale editions.

Description

The scalectl utils xcp command provides the functions of the mmxcp command through the scalectl interface.

The enable command performs parallel copies of files from the specified source to the specified target in a single IBM Storage Scale cluster. It internally invokes scalectl policy apply and uses the policy engine LIST rule functions to execute the /usr/lpp/mmfs/bin/xcputil.sh script. You can use the enable command to copy files within a single file system, copy files between file systems in the same cluster, copy from live file systems, and copy from snapshots; cross-cluster copy is not supported.

The get retrieves the configuration information of a the specified xcpID.

The getConfig command retrieves the current values of the maximum configuration parameters for parallel copy commands that are allowed in the cluster

The list command lists configuration information of all currently running instances of xcp / mmxcp within the cluster.

The sync command performs a synchronization operation from the source directory to the target directory by using a single process and copies only files that are missing or appear different.
Note: The /usr/bin/rsync utility must be installed to use this feature.

The updateConfig command sets the value of the maximum configuration parameters for parallel copy commands that are allowed in the cluster

The verify command performs a quick comparison of the data in the source and target directories and flags any metadata differences.

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 scalectl updateConfig command.
Important: When you use the --json flag with the enable action, this endpoint method returns quickly because it submits an LRO operation to the LRO manager. You must check the operation status until the request reaches a completion state. You can verify the status by using the scalectl operation get <operation_id> CLI. After the operation is in a completion state, you can run further commands, such as verify, to check the details of the parallel copy.
--copy-attributes {Attribute[,Attribute...]}
Supports copying of the specified IBM Storage Scale file attributes.
--copy-migrated
Reads the content of any file in the Directory in IBM Spectrum® Protect for space management migrated state and then copies it.
--directory-thread-level {DirThreadLevel}
Specifies the number of threads that are created and dispatched during the directory scan phase of command processing.
--force
If an existing destination file cannot be overwritten, removes it and tries again.
--global-work-directory {GlobalWorkDirectory}
Specifies a global work directory in which one or more nodes can store temporary files during command processing.
--hard-links
Executes an additional pass through the source files looking specifically for hard-linked files and copies these files as a single batch.
--local-work-directory {LocalWorkDirectory}
Specifies a local directory in which one or more nodes can store temporary files during command processing.
--logging-level {LoggingLevel}
Controls the level of information that is displayed during command processing. Larger values indicate the display of more detailed information.
--max-files {MaxFiles}
Specifies the maximum number of files that are processed in a batch.
--nodes {Node[,Node...]}
Limits the nodes that perform the copy operation to the specified nodes that also have both the source and target file systems mounted in the cluster.
--qos QOSClass
Specifies the Quality of Service (QoS) class for I/O operations to which the command instance is assigned. If you do not specify this parameter, the command instance is assigned to the maintenance QoS class by default. This parameter has no effect unless the QoS service is enabled.
--scan-threads {IscanThreads}
Specifies the number of threads and sort pipelines that each node runs during the parallel inode scan and ploicy evaluation.
-d or --snapshot-device <Device:[FilesetName:]SnapshotName>
Specifies the file system device that contains the snapshot.
-f or --snapshot-fileset-name <Device:[FilesetName:]SnapshotName>
Specifies the fileset that contains the snapshot.
-n or --snapshot-name <Device:[FilesetName:]SnapshotName>
Specifies the name of the snapshot to copy.
--sort-buffer-size {Size}
Sets the sort buffer size that is passed to the sort command. This flag is optional.
-s or --source Directory
Specifies the fully qualified path of the IBM Storage Scale file system subtree that is the source of the copy operation.
-t or --target Directory
Specifies the fully qualified path of the IBM Storage Scale file system subtree that is the destination of the copy operation.
--thread-level {ThreadLevel}
Specifies the number of threads that are created and dispatched during the execution phase of command processing. This flag is optional.
getConfig
Retrieves the current values of the maximum configuration parameters for parallel copy commands that are allowed in the cluster.
--all-domains
Runs the request against all possible domains that the user can access.
list
Lists configuration information of all currently running instances of xcp or mmxcp within the cluster.
--all-domains
Runs the request against all possible domains that the user can access.
-n or --max-items MaxItems
Specifies the maximum number of items to list at a time.
-x or --no-pagination
Disables following pagination tokens on the client side.
sync
Performs a synchronization operation from the source directory to the target directory by using a single process and copies only files that are missing or appear different.
-d or --snapshot-device Device
Specifies the file system device where the snapshot resides.
-f or --snapshot-fileset-name FilesetName
Specifies the fileset where the snapshot resides.
-n or --snapshot-name SnapshotName
Specifies the name of the snapshot to copy.
-s or --source Directory
Specifies the source path to be copied.
-t or --target Directory
Specifies the target path where source files are copied.
updateConfig
Sets the values of the maximum configuration parameters for parallel copy commands that are allowed in the cluster.
--all-domains
Runs the request against all possible domains that the user can access.
--max-files MaxFiles
Sets the maximum number of files that are handled during each internal XCP apply policy invocation. A value of 0 clears any set value.
--max-parallel MaxParallel
Sets the maximum number of parallel copy commands that can be active in the cluster simultaneously. A value of 0 clears the value.
--max-threads MaxThreads
Sets the maximum number of threads that are created and dispatched during each apply policy invocation. A value of 0 clears any set value.
verify
Performs a quick compare of metadata between a source/snapshot and a target directory from a previously executed scale utilis xcp copy command. Several attributes are checked for each object including file type, user/owner, group, and access rights.
-a or --check-attributes {Attribute[,Attribute...]}
Specifies a list of additional attributes to compare.
-d or --snapshot-device Device
Specifies the file system device where the snapshot resides.
-f or --snapshot-fileset-name FilesetName
Specifies the fileset where the snapshot resides.
-n or --snapshot-name SnapshotName
Specifies the name of the snapshot to copy.
-s or --source Directory
Specifies the source path to be verified.
-t or --target Directory
Specifies the target path where the source files were copied.

Global flags

Use the following global flags with any scalectl command and subcommand:
--bearer
If true, reads the OIDC_TOKEN from the environment and sends it as the authorization bearer header for the request. Use this flag with the --url option.
--user-cert {Certificate}
Specifies the path to the client certificate file for authentication.
--user-cacert {CA_Certificate}
Specifies the path to the certificate authority (CA) trust chain to validate a server certificate.
--debug {Filepath[="stderr"]}
Enables the debug logging for the current request. Accepts an absolute file path to store logs by using --debug=<file>. If no file path is specified, logs are sent to stderr.
-h or --help
Lists the help for scalectl commands.
--domain {DomainName}
Sets the domain for the request. The default value is StorageScaleDomain.
--insecure-skip-tls-verify
If true, skips to verify the server certificate for validity. This option makes HTTPS connections insecure.
--json
Displays output in JSON format.
Note: When you use the --json flag with an endpoint method that is a long-running operation (LRO), the LRO is submitted to the LRO manager, which handles its lifecycle. The lifecycle includes accepting, running, and monitoring operations. Although the command request returns quickly, you must ensure that the submitted operation reaches a Done state. Review any metadata that is associated with the request to ensure that it completed successfully. This step is especially important for endpoint methods that have follow-on methods. These follow-on methods are valid only if the initial method completed successfully. For more information about LRO, see Long-running operations.
--user-key {PrivateKeyFile}
Specifies the path to the client certificate private key file for authentication.
--url {ip_address}
Sends the request over HTTPS to the specified endpoint <FQDN/IP>:<port>. For IPv6 address, use square brackets. For example, [IPv6]:<port>. If no port specified, 46443 is used by default.
--version
Specifies the scalectl build information. The --version flag is valid only with the top-level scalectl command.

Exit status

0
Successful completion.
nonzero
A failure occurred.

Security

You must have the specific role-based access control (RBAC) permission to run the command. For more information, see Role-based access control.

Examples

  1. To enable parallel copies of files, issue the following command: 
    scalectl utils xcp enable -s /fs1/source -t /fs1/target --json
    A sample output is as follows:
    {
"name":  "MTo4OWU5YWFlNi1kYThkLTQ4ZTItYWUwYi0wODg3NzNmNDgzYWQ=",
"metadata":  {
"@type":  "type.googleapis.com/generic.v3.LongRunningOperationMetadata",
"job_id":  "MTo4OWU5YWFlNi1kYThkLTQ4ZTItYWUwYi0wODg3NzNmNDgzYWQ=",
"operation_details":  {
"@type":  "type.googleapis.com/utils.v3.EnableXCPOperationRequest",
"source":  "/fs1/source",
"target":  "/fs1/target",
"snapshot_device":  "",
"snapshot_fileset_name":  "",
"snapshot_name":  "",
"force":  false,
"copy_attributes":  [],
"copy_migrated":  false,
"hard_links":  false,
"nodes":  [],
"global_work_dir":  "",
"local_work_directory":  "",
"qos":  ""
},
"status":  "RUNNING",
"check_point":  "",
"request_time":  "2026-02-09T19:34:21.834174923Z",
"completion_time":  null,
"last_update_time":  "2026-02-09T19:34:22.092195599Z",
"output":  "[I] Beginning verification of pa...",
"domain_ids":  [
0
]
},
"done":  false
}
  2. To list the active parallel copy operations, issue the following command: 
    scalectl utils xcp list --json
    A sample output is as follows:
    {
"xcp_operations":  [
{
"tracking_id":  "XCP1770665664028506358",
"source_path":  "/fs1/source",
"target_path":  "/fs1/target",
"source_device_name":  "fs1",
"target_device_name":  "fs1",
"nodes":  [
"10.0.100.120"
],
"start_time":  "2026-02-09T20:34:24Z",
"host_name":  "scale-51.openstacklocal",
"process_id":  "1518723"
}
]
}
  3. To get details about a specific parallel copy operation, issue the following command: 
    scalectl utils xcp get XCP1770665664028506358
    A sample output is as follows:
    Tracking Id             | Source Path | Target Path | Source Device Name | Target Device Name | Cluster Nodes | Start Time                    | Host Name               | Process ID
===============================================================================================================================================================================
XCP1770665664028506358 | /fs1/source | /fs1/target | fs1                | fs1                | 10.0.100.120  | 2026-02-09 20:34:24 +0000 UTC | scale-51.openstacklocal | 1518723
  4. To display the current xcp configuration settings, issue the following command: 
    scalectl utils xcp getConfig --json
    A sample output is as follows:
    {
"max_parallel": "10",
"max_files": "0",
"max_threads": "0"
}
  5. To update the xcp configuration settings, issue the following command: 
    scalectl utils xcp updateConfig \
  --max-parallel 4 \
  --max-files 1000 \
  --max-threads 16
    A sample output is as follows:
    configuration settings applied
  6. To verify copied files on the same file system, issue the following command: 
    scalectl utils xcp verify --source /gpfs/gpfs0/bigsrc --target /gpfs/gpfs0/bigdst
    A sample output is as follows:
    Running job 'MTozM2ZiNGMyMy1jY2Y3LTQ2NzktYTM1My0wNDBhZTA4Y2Y4NjE='
[I] Beginning verification.
[I] Compare contents of /gpfs/gpfs0/bigsrc against /gpfs/gpfs0/bigdst
[I] Processed 5000 items for copy verification.
[I] Verify Success.
  7. To synchronize copied files, issue the following command: 
    scalectl utils xcp sync --source /gpfs/gpfs0/bigsrc --target /gpfs/gpfs0/bigdst
    A sample output is as follows:
    Failed to start /usr/bin/rsync.
fork/exec /usr/bin/rsync: no such file or directory
  8. To enable parallel copies of hard-linked files, issue the following command: 
    scalectl utils xcp enable \
  -s /gpfs/gpfs0/hard_src \
  -t /gpfs/gpfs0/hard_dst \
  --hard-links \
  --json
    A sample output is as follows:
    {
"name": "MTpiYWYwMGI2NC1jZjc4LTRjNGMtYWY2Yi0wMWRhMWU0MmMwOWQ=",
"metadata": {
"@type": "type.googleapis.com/generic.v3.LongRunningOperationMetadata",
"job_id": "MTpiYWYwMGI2NC1jZjc4LTRjNGMtYWY2Yi0wMWRhMWU0MmMwOWQ=",
"operation_details": {
"@type": "type.googleapis.com/utils.v3.EnableXCPOperationRequest",
"source": "/gpfs/gpfs0/hard_src",
"target": "/gpfs/gpfs0/hard_dst",
"snapshot_device": "",
"snapshot_fileset_name": "",
"snapshot_name": "",
"force": false,
"copy_attributes": [],
"copy_migrated": false,
"hard_links": false,
"nodes": [],
"global_work_dir": "",
"local_work_directory": "",
"qos": ""
},
"status": "RUNNING",
"check_point": "",
"request_time": "2026-02-24T18:08:52.014173209Z",
"completion_time": null,
"last_update_time": "2026-02-24T18:08:52.222748358Z",
"output": "[I] Beginning verification of pa...",
"domain_ids": [
0
]
},
"done": false
}

See also

Location

/usr/lpp/mmfs/bin