mc cp

The mc cp command copies objects to or from an AIStor deployment, where the source can be either an AIStor deployment or a local filesystem.

You can also use mc cp against the local filesystem to produce similar results to the cp commandline tool.

mc cp copies only the latest version or the specified version of an object without any version information or modification date.

To copy all versions, version information, and related metadata, use one of the following:

Bucket Replication - mc replicate add
Batch Replication - mc batch generate
Site Replication - mc admin replicate

Syntax

Example Syntax

The mc cp command has the following syntax:

mc [GLOBALFLAGS] cp                                                        \
                 [--attr "string"]                                         \
                 [--disable-multipart]                                     \
                 [--enc-kms "string"]                                      \
                 [--enc-s3 "string"]                                       \
                 [--enc-c "string"]                                        \
                 [--legal-hold "on"]                                       \
                 [--limit-download string]                                 \
                 [--limit-upload string]                                   \
                 [--md5]                                                   \
                 [--newer-than "string"]                                   \
                 [--older-than "string"]                                   \
                 [--preserve]                                              \
                 [--recursive]                                             \
                 [--retention-mode "string" --retention-duration "string"] \
                 [--rewind "string"]                                       \
                 [--storage-class "string"]                                \
                 [--tags "string"]                                         \
                 [--version-id "string"]                                   \
                 [--zip]                                                   \
                 SOURCE [SOURCE ...]                                       \
                 TARGET

Brackets [] indicate optional parameters.
Parameters sharing a line are mutually dependent.
Parameters separated using the pipe | operator are mutually exclusive.

Copy the example to a text editor and modify as-needed before running the command in the terminal/shell.

Parameters

SOURCE

Required

The object or objects to copy.

For copying an object from AIStor, specify the alias and the full path to that object (e.g. bucket and path to object). For example:

mc cp play/mybucket/object.txt ~/mydata/object.txt

Specify multiple SOURCE paths to copy multiple objects to the specified TARGET. mc cp treats the last specified alias or filesystem path as the TARGET. For example:

mc cp ~/data/object.txt myminio/mydata/object.txt play/mydata/

For copying an object from a local filesystem, specify the full path to that object. For example:

mc cp ~/mydata/object.txt play/mybucket/object.txt

If you specify a directory or bucket to SOURCE, you must also specify --recursive to recursively copy the contents of that directory or bucket. If you omit the --recursive argument, cp only copies objects in the top level of the specified directory or bucket.

TARGET

Required

The full path to which mc cp copies the object.

For copying an object to AIStor, specify the alias and the full path to that object (e.g. bucket and path to object). For example:

mc cp ~/mydata/object.txt play/mybucket/object.txt

For copying an object from a local filesystem, specify the full path to thatobject. For example:

mc cp play/mybucket/object.txt ~/mydata/object.txt

--attr

Optional

Add custom metadata for the object. Specify key-value pairs as KEY=VALUE\;. For example, --attr key1=value1\;key2=value2\;key3=value3.

--checksum

Optional

Add a checksum to an uploaded object.

Valid values are:

MD5
CRC32
CRC32C
SHA1
SHA256

The flag requires server trailing headers and works with AWS or AIStor targets.

--disable-multipart

Optional

Disables multipart upload for the copy session.

--enc-kms

Encrypt or decrypt objects using server-side SSE-KMS encryption with client-managed keys.

The parameter accepts a key-value pair formatted as KEY=VALUE

Parameter	Description
`KEY`	The full path to the object as `alias/bucket/path/object.ext`. You can specify only the top-level path to use a single encryption key for all operations in that path.
`VALUE`	Specify an existing data key on the external KMS. See the `mc admin kms key create` reference for creating data keys.

For example:

--enc-kms "myminio/mybucket/prefix/object.obj=mybucketencryptionkey"

You can specify multiple encryption keys by repeating the parameter.

Specify the path to a prefix to apply encryption to all matching objects at that path:

--enc-kms "myminio/mybucket/prefix/=mybucketencryptionkey"

--enc-s3

Optional

Encrypt or decrypt objects using server-side SSE-S3 encryption with KMS-managed keys. Specify the full path to the object as alias/bucket/prefix/object.

For example:

--enc-s3 "myminio/mybucket/prefix/object.obj"

You can specify the parameter multiple times to denote different object(s) to encrypt:

--enc-s3 "myminio/mybucket/foo/fooobject.obj" --enc-s3 "myminio/mybucket/bar/barobject.obj"

Specify the path to a prefix to apply encryption to all matching objects at that path:

--enc-s3 "myminio/mybucket/foo"

--enc-c

Optional

Encrypt or decrypt objects using server-side SSE-C encryption with client-managed keys.

The parameter accepts a key-value pair formatted as KEY=VALUE

Parameter	Description
`KEY`	The full path to the object as `alias/bucket/path/object.ext`. You can specify only the top-level path to use a single encryption key for all operations in that path.
`VALUE`	Specify either a 32-byte RawBase64-encoded key or a 64-byte hex-encoded key for use with SSE-C encryption. Raw Base64 encoding rejects `=`-padded keys. Omit the padding or use a Base64 encoder that supports RAW formatting.

For example:

# RawBase64-Encoded string "mybucket32byteencryptionkeyssec"
--enc-c "myminio/mybucket/prefix/object.obj=bXlidWNrZXQzMmJ5dGVlbmNyeXB0aW9ua2V5c3NlYwo"

You can specify multiple encryption keys by repeating the parameter.

Specify the path to a prefix to apply encryption to all matching objects at that path:

--enc-c "myminio/mybucket/prefix/=bXlidWNrZXQzMmJ5dGVlbmNyeXB0aW9ua2V5c3NlYwo"

AIStor strongly recommends against using SSE-C encryption in production workloads. Use SSE-KMS via the --enc-kms or SSE-S3 via --enc-s3 parameters instead.

--legal-hold

Optional

Enables indefinite legal hold object locking on the copied objects.

Specify on.

--limit-download

Optional

Limit client-side download rates to no more than a specified rate in KiB/s, MiB/s, or GiB/s. This affects only the download to the local device running the AIStor client. Valid units include:

B for bytes
K for kilobytes
M for megabytes
G for gigabytes
T for terabytes
Ki for kibibytes
Mi for mibibytes
Gi for gibibytes
Ti for tebibytes

For example, to limit download rates to no more than 1 GiB/s, use the following:

--limit-download 1G

If not specified, AIStor uses an unlimited download rate.

--limit-upload

Optional

Limit client-side upload rates to no more than the specified rate in KiB/s, MiB/s, or GiB/s. This affects only the upload from the local device running the AIStor client. Valid units include:

B for bytes
K for kilobytes
M for megabytes
G for gigabytes
T for terabytes
Ki for kibibytes
Mi for mibibytes
Gi for gibibytes
Ti for tebibytes

For example, to limit upload rates to no more than 1 GiB/s, use the following:

--limit-upload 1G

If not specified, AIStor uses an unlimited upload rate.

--newer-than

Optional

Copy object(s) newer than the specified number of days. Specify a string in #d#hh#mm#ss format. For example: --older-than 1d2hh3mm4ss

Defaults to 0 (all objects).

--older-than

Optional

Copy object(s) older than the specified time limit. Specify a string in #d#hh#mm#ss format. For example: --older-than 1d2hh3mm4ss

Defaults to 0 (all objects).

--preserve, a

Optional

Preserve file system attributes and bucket policy rules of the SOURCE directories, buckets, and objects on the TARGET bucket(s). Starting in RELEASE.2025-04-18T01-55-54Z, symlinks are also preserved.

--recursive

Alias: -r

Optional

Recursively copy the contents of each bucket or directory SOURCE to the TARGET bucket.

--retention-duration

Optional

The duration of the WORM retention mode to apply to the copied object(s).

Specify the duration as a string in #d#hh#mm#ss format. For example: --retention-duration "1d2hh3mm4ss".

Requires specifying --retention-mode.

--retention-mode

Optional

Enables object locking mode on the copied object(s). Supports the following values:

GOVERNANCE
COMPLIANCE

Requires specifying --retention-duration.

--rewind

Optional

Directs mc cp to operate only on the object version(s) that existed at specified point-in-time.

To rewind to a specific date in the past, specify the date as an ISO8601-formattedtimestamp. For example: --rewind "2020.03.24T10:00".
To rewind a duration in time, specify the duration as a string in #d#hh#mm#ssformat. For example: --rewind "1d2hh3mm4ss".

--rewind requires that the specified SOURCE be an S3-compatible service that supports Bucket Versioning. For AIStor deployments, use mc version to enable or disable bucket versioning.

--storage-class, sc

Optional

Set the storage class for the new object(s) on the TARGET.

See https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-class-intro.html for more information on S3 storage classes.

--tags

Optional

Applies one or more tags to the copied objects.

Specify an ampersand-separated list of key-value pairs as KEY1=VALUE1&KEY2=VALUE2, where each pair represents one tag to assign to the objects.

--version-id

Alias: --vid

Optional

Directs mc cp to operate only on the specified object version.

--version-id requires that the specified SOURCE be an S3-compatible service that supports Bucket Versioning. For AIStor deployments, use mc version to enable or disable bucket versioning.

--zip

Optional

During copy, extract files from a .zip archive. Only functional when the source archive file exists on a AIStor deployment.