mc mirror

Parameters

SOURCE

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

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

• ALIAS is the 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 in which mc mirror copies synchronized SOURCE objects. Specify the TARGET as ALIAS/PATH, where:

• ALIAS is the 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 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 copy 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 ".

--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 --encrypt-key secret key.

--exclude

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

--fake

Perform a fake mirror operation. Use this operation to perform validate 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 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 SOURCE on the 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 copy 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 --overwrite or --watch.

storage-class, sc

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

See the Amazon documentation on Storage Classes 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 --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

--debug

Optional

Enables verbose output to the console.

For example:

mc --debug COMMAND

--config-dir

Optional

The path to a JSON formatted configuration file that mc uses for storing data. See Configuration File for more information on how mc uses the configuration file.

--JSON

Optional

Enables JSON lines formatted output to the console.

For example:

mc --JSON COMMAND

--no-color

Optional

Disables the built-in color theme for console output. Useful for dumb terminals.

--quiet

Optional

Suppresses console output.

--insecure

Optional

Disables TLS/SSL certificate verification. Allows TLS connectivity to servers with invalid certificates. Exercise caution when using this option against untrusted S3 hosts.

--version

Optional

Displays the current version of mc.

--help

Optional

Displays a summary of command usage on the terminal.

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 with the full file path to the directory to mirror.

• Replace ALIAS with the alias of a configured S3-compatible host.

• Replace PATH with the destination bucket.

Continuously Mirror a Local Directory to an S3-Compatible Host

Use mc mirror with --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 with the full file path to the directory to mirror.

• Replace ALIAS with the alias of a configured S3-compatible host.

• Replace PATH with the destination bucket.

Continuously Mirror S3 Bucket to an S3-Compatible Host

Use mc mirror with --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.f

mc mirror --watch SRCALIAS/SRCPATH TGTALIAS/TGTPATH

• Replace SRCALIAS with alias of a configured S3-compatible host.

• Replace SRCPATH with the bucket to mirror.

• Replace TGTALIAS with the alias of a configured S3-compatible host.

• Replace TGTPATH with the destination bucket.

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.

mc mirror --watch relies on the mc removal API for deleting objects. As part of removing the last object in a bucket prefix, mc also recursively removes each empty part of the prefix up to the bucket root. mc only applies the recursive removal to prefixes created implicitly as part of object write operations - that is, the prefix was not created using an explicit directory creation command such as mc mb.

For example, consider a bucket photos with the following object prefixes:

• photos/2021/january/myphoto.jpg

• photos/2021/february/myotherphoto.jpg

• photos/NYE21/NewYears.jpg

photos/NYE21 is the only prefix explicitly created using mc mb. All other prefixes were implicitly created as part of writing the object located at that prefix.

If an mc command removes myphoto.jpg, the removal API automatically trims the empty /january prefix. If a subsequent mc command removes myotherphoto.jpg, the removal API automatically trims both the /february prefix and the now-empty /2021 prefix. If an mc command removes NewYears.jpg, the /NYE21 prefix remains in place since it was explicitly created.

If using mc mirror --watch for operations on a filesystem, mc applies this same behavior by recursively trimming empty directory paths up to the root. However, the mc remove API cannot distinguish between an explicitly created directory path and an implicitly created one. If mc mirror --watch deletes the last object at a filesystem path, mc recursively deletes all empty directories within that path up to the root as part of the removal operation.

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested MinIO and AWS S3 for expected functionality and behavior.

MinIO provides no guarantees for other S3-compatible services, as their S3 API implementation is unknown and therefore unsupported. While mc commands may work as documented, any such usage is at your own risk.