docs/source/reference/minio-mc/mc-mirror.rst

mc mirror

minio

Table of Contents

mc mirror

Syntax

The mc mirror command synchronizes content to MinIO deployment, similar to the rsync utility. mc mirror supports filesystems, MinIO deployments, and other S3-compatible hosts as the synchronization source.

Note

mc mirror only synchronizes the current object without any version information or metadata. To synchronize an object's version history and metadata, consider using mc replicate or mc admin replicate.

EXAMPLE

The following command synchronizes content from a local filesystem directory to the mydata bucket on the myminio MinIO deployment.

mc mirror --watch ~/mydata myminio/mydata

The command "watches" for files added or removed on the local filesystem and synchronizes those operations to MinIO until explicitly terminated.

mc mirror --watch updates files changed on the local filesystem to MinIO (see ~mc mirror --overwrite). --watch does not remove other files from MinIO not present on the local filesystem (see ~mc mirror --remove).

SYNTAX

The command has the following syntax:

mc [GLOBALFLAGS] mirror                            \
                 [--attr "string"]                 \
                 [--disable-multipart]             \
                 [--dry-run]                       \
                 [--encrypt-key "string"]          \
                 [--exclude "string"]              \
                 [--exclude-storageclass "string"] \
                 [--limit-download string]         \
                 [--limit-upload string]           \
                 [--md5]                           \
                 [--monitoring-address "string"]   \
                 [--newer-than "string"]           \
                 [--older-than "string"]           \
                 [--preserve]                      \
                 [--region "string"]               \
                 [--remove]                        \
                 [--storage-class "string"]        \
                 [--watch]                         \
                 SOURCE                            \ 
                 TARGET

Parameters

SOURCE

REQUIRED The file(s) or object(s) to synchronize to the ~mc mirror TARGET S3 host.

For objects on S3-compatible hosts, specify the path to the object as ALIAS/PATH, where:

• ALIAS is the alias <mc alias> of a configured S3-compatible host, and
• PATH is the path to the bucket or object. If specifying a bucket, mc mirror synchronizes all objects in the bucket.

mc mirror [FLAGS] play/mybucket/ myminio/mybucket

For files on a filesystem, specify the full filesystem path to the file or directory :

mc mirror [FLAGS] ~/data/ myminio/mybucket

If specifying a directory, mc mirror synchronizes all files in the directory.

TARGET

REQUIRED The full path to bucket to which mc mirror synchronizes SOURCE objects. Specify the TARGET as ALIAS/PATH, where:

• ALIAS is the alias <mc alias> of a configured S3-compatible host, and
• PATH is the path to the bucket.

mc mirror SOURCE play/mybucket

mc mirror uses the object or file names from the ~mc mirror SOURCE when synchronizing to the TARGET bucket.

--attr

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

--disable-multipart

Disables multipart upload for the synchronization session.

--encrypt-key

Encrypt or decrypt objects using server-side encryption with client-specified keys. Specify key-value pairs as KEY=VALUE.

• Each KEY represents a bucket or object.
• Each VALUE represents the data key to use for encrypting object(s).

Enclose the entire list of key-value pairs passed to :mc-cmd:~mc mirror --encrypt-key in double quotes ".

~mc mirror --encrypt-key can use the MC_ENCRYPT_KEY environment variable for retrieving a list of encryption key-value pairs as an alternative to specifying them on the command line.

You can only delete encrypted objects if you specify the correct ~mc mirror --encrypt-key secret key.

--exclude

Exclude object(s) in the ~mc mirror SOURCE path that match the specified object name pattern.

--exclude-storageclass

Exclude object(s) on the ~mc mirror SOURCE that have the specified storage class. You can use this flag multiple times in a command to exclude objects from more than one storage class.

Use this to exclude objects with storage classes that require rehydration or restoration of objects, such as migrating from an AWS S3 bucket where some objects have the GLACIER or DEEP_ARCHIVE storage classes.

--dry-run

Perform a mock mirror operation. Use this operation to test that the mc mirror operation will only mirror the desired objects or buckets.

--md5

Forces all uploads to calculate MD5 checksums.

--monitoring-address

Creates a Prometheus endpoint for monitoring mirroring activity. Specify the local network adapter and port address on which to create the scraping endpoint. Defaults to localhost:8081).

--newer-than

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

--older-than

Mirror 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).

--overwrite

Overwrites object(s) on the ~mc mirror TARGET.

For example, consider an active mc mirror --overwrite synchronizing content from Source to Destination.

If an object on Source changes, mc mirror --overwrite synchronizes and overwrites any matching file on Destination.

Without --overwrite, if an object already exists on the Destination, the mirror process fails to synchronize that object. mc mirror logs an error and continues to synchronize other objects.

--preserve, a

Preserve file system attributes and bucket policy rules of the ~mc mirror SOURCE on the ~mc mirror TARGET.

--region

Specify the string region when creating new bucket(s) on the target.

Defaults to "us-east-1".

--remove

Removes object(s) on the Target that do not exist on the Source.

Use the --remove flag to have the same list of objects on both Source and Target.

For example, objects A, B, and C exist on Source. Objects C, D, and E exist on Target.

When running mc mirror --remove, objects A and B synchronize to Target and objects D and E are removed from Target. Since an object C already exists on both, nothing moves from Source to Target.

After the action, only objects A, B, and C exist on both the Source and the Target.

mc mirror --remove does not verify that the contents of object C are the same on both Source and Target, only that an object called C exists on both. To ensure objects on the Source and Target match both names and content, use ~mc mirror --overwrite or ~mc mirror --watch.

RELEASE.2023-05-04T18-10-16Z

mc mirror --remove returns an error if the target path is a local filesystem directory that does not exist.

In prior versions, specifying /path/to/directory would result in the removal of the /path/to folder if directory did not exist.

--retry

In case of errors during mirror process, retry on each errored object.

storage-class, sc

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

See the Amazon documentation on Storage Classes <AmazonS3/latest/dev/storage-class-intro.html> for more information on S3 storage classses.

--watch, w

Use --watch flag to mirror objects from Source to Target, where the Target may also have additional objects not present on the Source.

• --watch continuously synchronizes files from Source to Target until explicitly terminated
• The Target may have files that do not exist on Source
• --watch overwrites objects on the Target if a match exists on Source, like the ~mc mirror --overwrite flag

Defaults to 0 (all objects).

For example, object A and B exist on the watched Source. Objects A, B, and C exist on the watched Target.

A client writes object D to Source and removes object B.

After the operation, objects A and D exist on the Source. Objects A, C, and D exist on the Target.

Global Flags

Examples

Mirror a Local Directory to an S3-Compatible Host

Use mc mirror to mirror files from a filesystem to an S3 Host:

mc mirror FILEPATH ALIAS/PATH

• Replace FILEPATH <mc mirror SOURCE> with the full file path to the directory to mirror.
• Replace ALIAS <mc mirror TARGET> with the alias <mc alias> of a configured S3-compatible host.
• Replace PATH <mc mirror TARGET> with the destination bucket.

Continuously Mirror a Local Directory to an S3-Compatible Host

Use mc mirror with ~mc mirror --watch to continuously mirror files from a filesystem to an S3-compatible host where objects added to or deleted from the filesystem are added to or deleted from the host:

mc mirror --watch FILEPATH ALIAS/PATH

• Replace FILEPATH <mc mirror SOURCE> with the full file path to the directory to mirror.
• Replace ALIAS <mc mirror TARGET> with the alias <mc alias> of a configured S3-compatible host.
• Replace PATH <mc mirror TARGET> with the destination bucket.

Continuously Mirror S3 Bucket to an S3-Compatible Host

Use mc mirror with ~mc mirror --watch to continuously mirror objects in a bucket on one S3-compatible host to another S3-compatible host where objects added to or deleted from the bucket are added to or deleted from the host.

mc mirror --watch SRCALIAS/SRCPATH TGTALIAS/TGTPATH

• Replace SRCALIAS <mc mirror SOURCE> with alias <mc alias> of a configured S3-compatible host.
• Replace SRCPATH <mc mirror SOURCE> with the bucket to mirror.
• Replace TGTALIAS <mc mirror TARGET> with the alias <mc alias> of a configured S3-compatible host.
• Replace TGTPATH <mc mirror TARGET> with the destination bucket.

Mirror Objects from AWS S3 to MinIO Skipping Objects in GLACIER

Use mc mirror with ~mc mirror --exclude-storageclass to mirror objects from AWS S3 to MinIO without mirroring objects in GLACIER or DEEP_ARCHIVE storage.

mc mirror --exclude-storageclass GLACIER  \
   --exclude-storageclass DEEP_ARCHIVE SRCALIAS/SRCPATH TGALIAS/TGPATH

• Replace SRCALIAS <mc mirror SOURCE> with the alias <mc alias> of a configured S3 host.
• Replace SRCPATH <mc mirror SOURCE> with the bucket to mirror.
• Replace TGTALIAS <mc mirror TARGET> with the alias <mc alias> of a configured S3 host.
• Replace TGTPATH <mc mirror TARGET> with the destination bucket.

Behavior

Mirror Continues on Failed Object

If an object of the same name exists on the target, MinIO outputs an error for the duplicate object. mc mirror continues to mirror other objects from the source to the destination after the error.

MinIO Trims Empty Prefixes on Object Removal

The mc mirror --watch command continuously synchronizes the source and destination targets for added and deleted objects. This includes automatically removing objects on the destination if they are removed on the source.

For objects updated on the source to also update on the target, use --overwrite. To remove objects from the target that are not on the source, use --remove.

S3 Compatibility