Silo Client (mcli / mc)

• 1: mc alias list
• 2: mc anonymous set
• 3: mc batch cancel
• 4: mc encrypt clear
• 5: mc event add
• 6: mc idp ldap accesskey disable
• 7: mc idp ldap add
• 8: mc idp ldap policy attach
• 9: mc ilm restore
• 10: mc ilm rule add
• 11: mc ilm tier add
• 12: mc legalhold clear
• 13: mc license info
• 14: mc replicate add
• 15: mc retention set
• 16: mc share download
• 17: mc support callhome
• 18: mc support top api
• 19: mc tag set
• 20: mc version enable
• 21: Silo Client Settings
• 22: mc alias
• 23: mc alias remove
• 24: mc anonymous get
• 25: mc batch describe
• 26: mc encrypt info
• 27: mc event ls
• 28: mc idp ldap accesskey edit
• 29: mc idp ldap disable
• 30: mc idp ldap policy detach
• 31: mc ilm rule
• 32: mc ilm rule edit
• 33: mc ilm tier check
• 34: mc legalhold info
• 35: mc license register
• 36: mc replicate backlog
• 37: mc retention info
• 38: mc share upload
• 39: mc support diag
• 40: mc support top locks
• 41: mc tag list
• 42: mc version info
• 43: mc alias set
• 44: mc anonymous
• 45: mc anonymous list
• 46: mc batch generate
• 47: mc encrypt set
• 48: mc event rm
• 49: mc idp ldap accesskey enable
• 50: mc idp ldap enable
• 51: mc idp ldap policy entities
• 52: mc ilm rule export
• 53: mc ilm tier
• 54: mc ilm tier info
• 55: mc legalhold set
• 56: mc license update
• 57: mc replicate ls
• 58: mc retention clear
• 59: mc share ls
• 60: mc support inspect
• 61: mc support top disk
• 62: mc tag remove
• 63: mc version suspend
• 64: mc alias import
• 65: mc anonymous links
• 66: mc batch
• 67: mc batch list
• 68: mc idp ldap accesskey info
• 69: mc idp ldap info
• 70: mc ilm rule import
• 71: mc ilm tier ls
• 72: mc replicate update
• 73: mc support perf
• 74: mc support top net
• 75: mc alias export
• 76: mc anonymous get-json
• 77: mc batch start
• 78: mc cat
• 79: mc idp ldap accesskey ls
• 80: mc idp ldap ls
• 81: mc ilm rule ls
• 82: mc ilm tier rm
• 83: mc replicate resync
• 84: mc support profile
• 85: mc support top rpc
• 86: mc anonymous set-json
• 87: mc batch status
• 88: mc cp
• 89: mc idp ldap accesskey rm
• 90: mc idp ldap rm
• 91: mc ilm rule rm
• 92: mc ilm tier update
• 93: mc replicate rm
• 94: mc support proxy
• 95: mc diff
• 96: mc idp ldap update
• 97: mc replicate status
• 98: mc support top
• 99: mc du
• 100: mc replicate export
• 101: mc support upload
• 102: mc encrypt
• 103: mc replicate import
• 104: mc event
• 105: mc find
• 106: mc get
• 107: mc head
• 108: mc idp ldap
• 109: mc idp ldap accesskey
• 110: mc idp ldap accesskey create-with-login
• 111: mc idp ldap policy
• 112: mc idp openid
• 113: mc ilm
• 114: mc legalhold
• 115: mc license
• 116: mc ls
• 117: mc mb
• 118: mc mirror
• 119: mc mv
• 120: mc od
• 121: mc ping
• 122: mc pipe
• 123: mc put
• 124: mc rb
• 125: mc ready
• 126: mc replicate
• 127: mc retention
• 128: mc rm
• 129: mc share
• 130: mc sql
• 131: mc stat
• 132: mc support
• 133: mc tag
• 134: mc tree
• 135: mc undo
• 136: mc update
• 137: mc version
• 138: mc watch
• 139: mc idp ldap accesskey create

mc [GLOBALFLAGS] COMMAND --help

git clone https://github.com/pgsty/mc.git
cd mc
make build
./mc --version

bash +o history
mc alias set ALIAS HOSTNAME ACCESS_KEY SECRET_KEY
bash -o history

mc alias set silo https://silo.example.net ACCESS_KEY SECRET_KEY

mc alias set myS3 https://s3.{your-region-code}.amazonaws.com/endpoint ACCESS_KEY SECRET_KEY

mc alias set myGCS https://storage.googleapis.com/endpoint ACCESS_KEY SECRET_KEY

mc admin info silo

~/.mc/certs/ # certificates
~/.mc/certs/CAs/ # Certificate Authorities

C:\Users\[username]\mc\certs\ # certificates
C:\Users\[username]\mc\certs\CAs\ # Certificate Authorities

mc --debug ls play

mc --json ls play

--resolve HOST[:PORT]=IP

mc alias set --resolve myminio.example.com:9000=192.168.188.118 'myminio' 'https://myminio.example.com:9000' 'miniouser' 'miniosecret'

1 - mc alias list

Syntax

The mc alias list command lists all aliases in the local mc configuration.

The command output includes the configured access key and secret key associated to each alias.

mc alias list

mc [GLOBALFLAGS] alias list [ALIAS]

Parameters

ALIAS

mc-cmd

Optional The name of a specific alias to display.

Global Flags

This command supports any of the global flags.

Examples

List All Configured Aliases

mc alias list

mc alias list

List a Specific Alias

mc alias list myminio

mc alias list ALIAS

Behavior

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

2 - mc anonymous set

Syntax

The mc anonymous set command sets anonymous (i.e. unauthenticated or public) access policies for a bucket.

Buckets with anonymous policies allow clients to access the bucket contents and perform actions consistent with the specified policy without authentication.

To set anonymous bucket policies using an IAM JSON policy, use the mc anonymous set-json command.

mc anonymous set upload myminio/uploads
mc anonymous set download myminio/downloads
mc anonymous set public myminio/public

mc [GLOBALFLAGS] policy set PERMISSION ALIAS

Parameters

PERMISSION

mc-cmd

Required Name of the policy to assign to the specified ALIAS. Specify one of the following values:

• none - Disable anonymous access to the ALIAS.
• download - Enable download-only access to the ALIAS.
• upload - Enable upload-only access to the ALIAS.
• public - Enable download and upload access to the ALIAS.

ALIAS

mc-cmd

Required The full path to the bucket or bucket prefix to which the command applies the specified PERMISSION.

Specify the alias of the MinIO or other S3-compatible service and the full path to the bucket or bucket prefix. For example:

mc anonymous set public play/mybucket

Specify a bucket prefix to set the policy on only that prefix. For example, this command sets distinct anonymous bucket policies on the mybucket/downloads and mybucket/uploads prefixes:

mc anonymous set download play/mybucket/downloads
mc anonymous set upload play/mybucket/uploads

Global Flags

This command supports any of the global flags.

Examples

Set Anonymous Policy for Bucket

Use mc anonymous set to set the anonymous policy for a bucket:

mc anonymous set POLICY ALIAS/PATH

• Replace POLICY with a supported permission.
• Replace ALIAS with the alias of a configured S3-compatible host.
• Replace PATH with the destination bucket.

Behavior

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

3 - mc batch cancel

Syntax

The mc batch cancel stops an ongoing batch job.

You must specify the job ID. To find the job ID, use mc batch list.

mc batch cancel myminio KwSysDpxcBU9FNhGkn2dCf

mc [GLOBALFLAGS] batch cancel ALIAS JOBID

Parameters

ALIAS

mc-cmd

Required

The alias for the MinIO deployment on which the job is currently running.

JOBID

mc-cmd

Required

The unique identifier of the batch job to cancel. To find the ID of a job, use mc batch list.

Global Flags

This command supports any of the global flags.

Example

Cancel an ongoing batch job

The following command cancels the job with ID KwSysDpxcBU9FNhGkn2dCf on the deployment at alias myminio:

mc batch cancel myminio KwSysDpxcBU9FNhGkn2dCf

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

4 - mc encrypt clear

Syntax

The mc encrypt clear command removes the current default encryption settings for a bucket.

mc encrypt clear myminio/mydata

mc [GLOBALFLAGS] encrypt clear ALIAS

Parameters

ALIAS

mc-cmd

The full path to the bucket on which to remove the default SSE mode. Specify the alias of the MinIO deployment as the prefix to the ALIAS path. For example:

mc encrypt clear play/mybucket

Global Flags

This command supports any of the global flags.

Examples

Remove the Automatic Server-Side Encryption Settings for a Bucket

 mc encrypt clear myminio/data

mc encrypt clear ALIAS

Behavior

Modifying Bucket Encryption Settings Does Not Affect Encrypted Objects

Disabling automatic bucket encryption does not decrypt any objects in the bucket.

To permanently decrypt objects in the bucket, you can perform an in-place copy after disabling object decryption. For versioned buckets, the previous object versions remain encrypted.

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

5 - mc event add

Syntax

The mc event add command adds event notification triggers to a bucket.

MinIO automatically sends triggered events to the configured notification target.

mc event add --event "put,delete" myminio/mydata arn:aws:sqs::primary:target

mc [GLOBALFLAGS] event add \
                 [--event "string"]  \
                 [--ignore-existing] \
                 [--prefix "string"] \
                 [--suffix "string"] \
                 ALIAS               \
                 ARN

Parameters

ALIAS

mc-cmd

Required

The MinIO alias and bucket to which the command adds the new event notification. For example:

mc event add play/mybucket

ARN

mc-cmd

Required

The Amazon Resource Name (ARN) of the notification target.

The MinIO server outputs an ARN for each configured notification target at server startup. See Bucket Notifications for more information.

--event

mc-cmd

Optional

The event(s) for which MinIO generates bucket notifications.

Supports the following values:

• put
• get
• delete

Specify multiple value using a comma , delimiter. Do not add any whitespace between values.

If not specified, defaults to put,delete,get.

See Supported Bucket Events for a detailed list of S3 events associated to each of the supported values.

ignore-existing, p

mc-cmd

Optional

Directs MinIO to ignore the specified event triggers if a matching trigger already exists.

--prefix

mc-cmd

Optional

The bucket prefix in which the specified --event can trigger a bucket notification.

For example, given a ALIAS of play/mybucket and a --prefix of photos, only events in play/mybucket/photos trigger bucket notifications.

Omit to trigger the event for all prefixes and objects in the bucket.

--suffix

mc-cmd

Optional

The bucket suffix in which the specified --event can trigger a bucket notification.

For example, given a ALIAS of play/mybucket and a --suffix of .jpg, only events in play/mybucket/*.jpg trigger bucket notifications.

Omit to trigger the event for all objects regardless of suffix.

Global Flags

This command supports any of the global flags.

Examples

Add an Event Notification to a Bucket

mc event add myminio/mydata arn:minio:sqs::primary:webhook

mc event add ALIAS ARN

Behavior

Supported Bucket Events

The following table lists the supported mc event add values and their corresponding S3 events:

For more complete documentation on the listed S3 events, see S3 Supported Event Types.

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

6 - mc idp ldap accesskey disable

Description

mc idp ldap accesskey disable disables the specified access key on the MinIO deployment.

mc idp ldap accesskey disable minio mykey

mc [GLOBALFLAGS] idp ldap accesskey disable  \
                                 ALIAS       \
                                 KEY

Parameters

ALIAS

mc-cmd

Required

The alias of the MinIO deployment configured for AD/LDAP.

For example:

mc idp ldap accesskey disable minio

KEY

mc-cmd

Required

The configured access key to disable.

Example

Disable the access key mykey from the minio deployment.

mc idp ldap accesskey disable minio/ mykey

Global Flags

This command supports any of the global flags.

Behavior

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

7 - mc idp ldap add

Description

The mc idp ldap add command creates an AD/LDAP IDP server configuration.

MinIO supports no more than one (1) AD/LDAP provider per deployment.

mc idp ldap add                                                            \
            myminio                                                        \
            server_addr=myldapserver:636                                   \
            lookup_bind_dn=cn=admin,dc=min,dc=io                           \
            lookup_bind_password=somesecret                                \
            user_dn_search_base_dn=dc=min,dc=io                            \
            user_dn_search_filter="(uid=%s)"                               \
            group_search_base_dn=ou=swengg,dc=min,dc=io                    \
            group_search_filter="(&(objectclass=groupofnames)(member=%d))"

mc [GLOBALFLAGS] idp ldap add               \
                          ALIAS             \
                          [CFG_PARAM1]      \
                          [CFG_PARAM2]...

Parameters

ALIAS

mc-cmd

Required

The alias of the MinIO deployment on which to add an AD/LDAP integration.

For example:

mc idp ldap add myminio                               \
                server_addr=myldapserver:636          \
                lookup_bind_dn=cn=admin,dc=min,dc=io  \
                lookup_bind_password=somesecret       \
                user_dn_search_base_dn=dc=min,dc=io   \
                user_dn_search_filter="(uid=%s)"      \

server_addr

mc-cmd

Required

Specify the hostname for the Active Directory / LDAP server. For example:

ldapserver.com:636

This parameter corresponds with the MINIO_IDENTITY_LDAP_SERVER_ADDR environment variable.

lookup_bind_dn

mc-cmd

Required

Specify the Distinguished Name (DN) for an AD/LDAP account MinIO uses when querying the AD/LDAP server. Enables Lookup-Bind authentication to the AD/LDAP server.

The DN account should be a read-only access keys with sufficient privileges to support querying performing user and group lookups.

This parameter corresponds with the MINIO_IDENTITY_LDAP_LOOKUP_BIND_DN environment variable.

lookup_bind_password

mc-cmd

Required

Specify the password for the Lookup-Bind user account.

This parameter corresponds with the MINIO_IDENTITY_LDAP_LOOKUP_BIND_PASSWORD environment variable.

user_dn_attributes

mc-cmd

Optional

Comma-separated list of user DN attributes.

Some valid values include, uid,cn,mail,sshPublicKey.

To enable public authentication for LDAP users, pass sshPublicKey as a DN attribute. The user can then use the passed SSH Public Key to log in to SFTP servers.

mc idp ldap update ALIAS user_dn_attributes=sshPublicKey

user_dn_search_base_dn

mc-cmd

Required

Specify the base Distinguished Name (DN) MinIO uses when querying for user credentials matching those provided by an authenticating client.

Separate multiple DNs with a semicolon (;).

For example:

cn=miniousers,dc=myldapserver,dc=net;ou=swengg,dc=min,dc=io

Supports Lookup-Bind mode.

This parameter corresponds with the MINIO_IDENTITY_LDAP_USER_DN_SEARCH_BASE_DN environment variable.

user_dn_search_filter

mc-cmd

Required

Specify the AD/LDAP search filter MinIO uses when querying for user credentials matching those provided by an authenticating client.

Use the %s substitution character to insert the client-specified username into the search string. For example:

(userPrincipalName=%s)

This parameter corresponds with the MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER environment variable.

comment

mc-cmd

Optional

Specify a comment to associate to the AD/LDAP configuration.

This parameter corresponds with the MINIO_IDENTITY_LDAP_COMMENT environment variable.

enabled

mc-cmd

Optional

Set to false to disable the AD/LDAP configuration.

If false, applications cannot generate STS credentials or otherwise authenticate to MinIO using the configured provider.

Defaults to true or “enabled”.

group_search_base_dn

mc-cmd

Optional

Specify a semicolon-separated (;) list of group search base Distinguished Names MinIO uses when performing group lookups.

For example:

cn=miniogroups,dc=myldapserver,dc=net;ou=swengg,dc=min,dc=io

This parameter corresponds with the MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN environment variable.

group_search_filter

mc-cmd

Optional

Specify an AD/LDAP search filter for performing group lookups for the authenticated user

Use the %s substitution character to insert the client-specified username into the search string. Use the %d substitution character to insert the Distinguished Name of the client-specified username into the search string.

For example:

(&(objectclass=groupOfNames)(memberUid=%s))

When providing an AD/LDAP group search filter, configure a filter that returns the minimum number of relevant groups for the purpose of supporting authentication. Filters that return large group assignments increase the size of associated calls and resources. Functions sensitive to large request or response bodies may exhibit unexpected behaviors as a result.

This parameter corresponds with the MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER environment variable.

server_insecure

mc-cmd

Optional

Specify on to allow unsecured (non-TLS encrypted) connections to the AD/LDAP server.

MinIO sends AD/LDAP user credentials in plain text to the AD/LDAP server, such that enabling TLS is required to prevent reading credentials over the wire. Using this option presents a security risk where any user with access to network traffic can observe the unencrypted plaintext credentials.

Defaults to off.

This parameter corresponds with the MINIO_IDENTITY_LDAP_SERVER_INSECURE environment variable.

server_starttls

mc-cmd

Optional

Specify on to enable StartTLS connections to an AD/LDAP server.

Defaults to off

For more about StartTLS, refer to section 4.14 of the LDAP RFC 4511 specification.

This parameter corresponds with the MINIO_IDENTITY_LDAP_SERVER_STARTTLS environment variable.

srv_record_name

mc-cmd

Optional

Specify the appropriate value to enable MinIO to select an AD/LDAP server using a DNS SRV record request.

When enabled, MinIO selects an AD/LDAP server by:

• Constructing the target SRV record name following standard naming conventions.
• Requesting a list of available AD/LDAP servers.
• Choosing an appropriate target based on priority and weight.

The configuration examples below presume the AD/LDAP server address is set to example.com and the SRV record protocol is _tcp.

For SRV record names beginning with _ldap, specify ldap. The constructed DNS SRV record name resembles the following:

_ldap._tcp.example.com

For SRV record names with beginning with _ldaps, specify ldaps. The constructed DNS SRV record name resembles the following:

_ldaps._tcp.example.com

If your DNS SRV record name uses alternate service or protocol names, specify on and provide the full record name as your LDAP server address. Example: _ldapserver._specialtcp.example.com

For more about DNS SRV records, see DNS SRV Records for LDAP.

This parameter corresponds with the MINIO_IDENTITY_LDAP_SRV_RECORD_NAME environment variable.

tls_skip_verify

mc-cmd

Optional

Specify on to trust the AD/LDAP server TLS certificates without verification. This option may be required if the AD/LDAP server TLS certificates are signed by an untrusted Certificate Authority (e.g. self-signed).

Defaults to off

This parameter corresponds with the MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY environment variable.

Global Flags

This command supports any of the global flags.

Behavior

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

8 - mc idp ldap policy attach

Description

The mc idp ldap policy attach command attaches one or more polices to an entity.

mc idp ldap policy attach myminio                                                  \
                          userpolicy                                               \
                          --user='uid=bobfisher,ou=people,ou=hwengg,dc=min,dc=io'

mc [GLOBALFLAGS] idp ldap policy attach             \
                                 POLICYNAME         \
                                 [POLICY2] ...      \
                                 ALIAS              \
                                 [--user=`USER`]    \
                                 [--group=`GROUP`]

Parameters

ALIAS

mc-cmd

Required

The alias of the MinIO deployment with the entity to which to attach a policy.

For example:

mc idp ldap policy attach myminio                                                  \
                          userpolicy                                               \
                          --user='uid=bobfisher,ou=people,ou=hwengg,dc=min,dc=io'

Example

The following example attaches two policies, policy1 and policy2, to the projectb group on the myminio deployment:

mc idp ldap policy attach myminio                                                 \
                          policy1                                                 \
                          policy2                                                 \
                          --group='cn=projectb,ou=groups,ou=swengg,dc=min,dc=io'

Global Flags

This command supports any of the global flags.

Behavior

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

9 - mc ilm restore

Syntax

The mc ilm restore command creates a temporary copy of an object archived on a remote tier. The copy automatically expires after 1 day by default.

Use this command to allow applications to access a tiered object through the MinIO deployment (e.g. “hot tier”). The archived object remains on the remote tier, while the temporary copy becomes HEAD for that object.

mc ilm restore myminio/mybucket/object.txt

mc [GLOBALFLAGS] ilm restore         \
                 [--days "int" ]     \
                 [--recursive]       \
                 [--vid "string"]    \
                 [--versions]        \
                 [--enc-c "string"]  \
                 ALIAS

Parameters

ALIAS

mc-cmd

Required

The MinIO alias, bucket, and path to the archived object to restore.

mc ilm restore myminio/mybucket/object.txt

--days

mc-cmd

Optional

The number of days after which MinIO expires the restored copy of the archived object.

--enc-c

mc-cmd

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

• KEY - the full path to the object as alias/bucket/path/object.
• VALUE - the 32-byte RAW Base64-encoded data key to use for encrypting object(s).

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"

--recursive, r

mc-cmd

Optional

Restores all objects under the specified prefix.

--versions

mc-cmd

Optional

Restores all versions of the object on the remote tier.

--version-id, vid

mc-cmd

Optional

Restores the specified version of the object on the remote tier.

Global Flags

This command supports any of the global flags.

Examples

Restore an Archived Object

The following command restores an object archived to a remote tier:

mc ilm restore myminio/mybucket/object.txt

Restore a Specific Archived Object Version

The following command restore a specific object version archived to a remote tier:

mc ilm restore --vid "VERSIONID" myminio/mybucket/object.txt

Restore All Archived Objects at a Bucket Prefix

The following command restores all objects archived under a specified prefix on the remote tier:

mc ilm restore --recursive myminio/mybucket/data/

Behavior

Restored Objects Expire Automatically

MinIO automatically expires the restored object copy after the specified number of days (Default: 1 day).

Restored Objects Become HEAD

The restored object copy becomes HEAD for that object namespace regardless of it’s versioning history. This can result in applications returning “stale” data while the local copy exists.

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

10 - mc ilm rule add

Syntax

The mc ilm rule add command adds an object lifecycle management rule to a bucket.

The command supports adding both Transition (Tiering) and Expiration lifecycle management rules.

mc ilm rule add --expire-days 90 --noncurrent-expire-days 30  myminio/mydata

mc ilm rule add --expire-delete-marker myminio/mydata

mc ilm rule add --transition-days 30 --transition-tier "COLDTIER" myminio/mydata

mc ilm rule add --noncurrent-transition-days 7 --noncurrent-transition-tier "COLDTIER"

mc [GLOBALFLAGS] ilm rule add                               \
                 [--prefix string]                          \
                 [--tags string]                            \
                 [--expire-days "integer"]                  \
                 [--expire-all-object-versions]             \
                 [--expire-delete-marker]                   \
                 [--transition-days "string"]               \
                 [--transition-tier "string"]               \
                 [--noncurrent-expire-days "integer"]       \
                 [--noncurrent-expire-newer "integer"]      \
                 [--noncurrent-transition-days "integer"]   \
                 [--noncurrent-transition-tier "string"]    \
                 [--site-gt "string"]                       \
                 [--size-lt "string"]                       \
                 ALIAS

Parameters

ALIAS

mc-cmd

Required

The alias and bucket on the MinIO deployment to which to add the object lifecycle management rule.

For example:

mc ilm rule add myminio/mydata

--prefix

mc-cmd

Optional

Restrict the management rule to a specific object prefix.

For example:

mc ilm rule add --prefix "meetingnotes/" myminio/mydata --expire-days "90"

The command creates a rule that expires objects in the mydata bucket of the myminio ALIAS after 90 days for any object with the meetingnotes/ prefix.

--tags

mc-cmd

Optional

One or more ampersand &-delimited key-value pairs describing the object tags to use for filtering objects to which the lifecycle configuration rule applies.

This option is mutually exclusive with the following option:

• --expire-delete-marker

--expire-all-object-versions

mc-cmd

Optional

Expire all current and noncurrent versions of an object. Use with the --expire-days option to specify the number of days after which all versions of an object should be deleted by the scanner process.

After the scanner processes this command, no versions of the object remain on the deployment.

This flag only applies to objects that do not have a delete marker as the latest version.

--expire-days

mc-cmd

Optional

The number of days to retain an object after being created. MinIO marks the object for deletion after the specified number of days pass. Specify the number of days as an integer, for example 30 for 30 days.

For versioned buckets, the expiry rule applies only to the current object version. Use either the --noncurrent-expire-days flag or the --expire-all-object-versions flag to apply expiration behavior to noncurrent object versions.

MinIO uses a scanner process to check objects against all configured lifecycle management rules. Slow scanning due to high IO workloads or limited system resources may delay application of lifecycle management rules. See Lifecycle Management Object Scanner for more information.

Mutually exclusive with the following options:

• --expire-delete-marker

For more complete documentation on object expiration, see Object Expiration and Object Deletion.

--expire-delete-marker

mc-cmd

Optional

Specify this option to direct MinIO to remove delete markers for objects with no remaining object versions. Specifically, the delete marker is the only remaining “version” of the given object.

This option is mutually exclusive with the following option:

• --tags
• --expire-days

MinIO uses a scanner process to check objects against all configured lifecycle management rules. Slow scanning due to high IO workloads or limited system resources may delay application of lifecycle management rules. See Lifecycle Management Object Scanner for more information.

For more complete documentation on object expiration, see Object Expiration and Object Deletion.

--transition-days

mc-cmd

Optional

The number of calendar days from object creation after which MinIO marks an object as eligible for transition. MinIO transitions the object to the configured remote tier specified to the --transition-tier. Specify the number of days as an integer, e.g. 30 for 30 days. If the remote tier is another MinIO deployment, you can set the value to 0 to mark new objects as immediately eligible for transition to the remote tier.

For versioned buckets, the transition rule applies only to the current object version. Use the --noncurrent-transition-days option to apply transition behavior to noncurrent object versions.

Requires specifying --transition-tier.

MinIO uses a scanner process to check objects against all configured lifecycle management rules. Slow scanning due to high IO workloads or limited system resources may delay application of lifecycle management rules. See Lifecycle Management Object Scanner for more information.

For more complete documentation on object transition, see Object Transition (“Tiering”).

--transition-tier

mc-cmd

Optional

The remote tier to which MinIO transition objects. Specify an existing remote tier created by mc ilm tier add.

Required if specifying --transition-days.

--noncurrent-expire-days

mc-cmd

Optional

The number of days to retain an object version after becoming non-current (i.e. a different version of that object is now the HEAD). MinIO marks noncurrent object versions for deletion after the specified number of days pass.

This option has the same behavior as the S3 NoncurrentVersionExpiration action.

MinIO uses a scanner process to check objects against all configured lifecycle management rules. Slow scanning due to high IO workloads or limited system resources may delay application of lifecycle management rules. See Lifecycle Management Object Scanner for more information.

--noncurrent-transition-days

mc-cmd

Optional

The number of days an object has been non-current (i.e. replaced by a newer version of that same object) after which MinIO marks the object version as eligible for transition. MinIO transitions the object to the configured remote tier specified to the --transition-tier once the system host datetime passes that calendar date.

This option has no effect on non-versioned buckets. Requires specifying --noncurrent-transition-tier.

This option has the same behavior as the S3 NoncurrentVersionTransition action.

MinIO uses a scanner process to check objects against all configured lifecycle management rules. Slow scanning due to high IO workloads or limited system resources may delay application of lifecycle management rules. See Lifecycle Management Object Scanner for more information.

--noncurrent-transition-tier

mc-cmd

Optional

The remote tier to which MinIO transitions noncurrent objects versions. Specify a remote tier created by mc ilm tier add.

--noncurrent-expire-newer

mc-cmd

Optional

The maximum number of non-current object versions to retain, ordered from newest to oldest.

Use this flag to retain a certain number of past versions of a file in a first in, first out fashion. After retaining the maximum number of non-current versions, MinIO marks any remaining older non-current object versions as eligible for expiration.

The following table lists a number of object versions and their expiration eligibility based on --noncurrent-expire-newer 3:

MinIO retains the current version, v5. MinIO also retains the next 3 non-current versions, starting with the newest. This means MinIO marks v4, v3, and v2 for the three non-current version to retain.

v1 would be a fourth non-current version, which falls outside the limit of non-current versions to retain, so MinIO marks v1 for expiration.

Updating the number for this flag only impacts the unmarked versions of objects. Any versions already marked for expiration do not change if you increase the number to retain.

MinIO uses a scanner process to check objects against all configured lifecycle management rules. Slow scanning due to high IO workloads or limited system resources may delay application of lifecycle management rules. See Lifecycle Management Object Scanner for more information.

--size-gt

mc-cmd

Optional

Select objects larger than the specified value. Enter the value as a number and a unit, such as 5GiB for 5 gibibytes.

Valid units include:

--size-lt

mc-cmd

Optional

Select objects smaller than the specified value. Enter the value as a number and a unit, such as 1M for 1 megabyte.

Valid units include:

Global Flags

This command supports any of the global flags.

Examples

Expire All Bucket Contents After Number of Days

Use mc ilm rule add with the --expire-all-object-versions and --expire-days flags to mark all current and non-current bucket contents for expiration after a number of days pass from the object’s creation:

mc ilm rule add ALIAS/PATH --expire-all-object-versions --expire-days "DAYS"

• Replace ALIAS with the alias of the S3-compatible host.
• Replace PATH with the path to the bucket on the S3-compatible host.
• Replace DAYS with the number of days after which to expire each object. For example, specify 30 to expire objects 30 days after creation.

Transition Non-Current Object Versions at a Prefix to a Different Tier

Use the mc ilm rule add with --prefix and --transition-tier to transition older non-current versions of an object to a different storage tier.

mc ilm rule add --prefix "doc/" --transition-days "90" --transition-tier "MINIOTIER-1"  \
       --noncurrent-transition-days "45" --noncurrent-transition-tier "MINIOTIER-2"    \
       myminio/mybucket

This command looks at the contents with the doc/ prefix in the mybucket bucket on the myminio deployment.

• Current objects in the prefix older than 90 days move to the MINIOTIER-1 storage tier.
• Non-current objects in the prefix older than 45 days move to the MINIOTIER-2 storage tier.
• Both MINIOTIER-1 and MINIOTIER-2 have already been created with mc admin tier add.

Expire All Objects at a Prefix, Retain Current Object Versions Longer Than Non-Current Object Versions

Use the mc ilm rule add command with --prefix, --expire-days, and --noncurrent-expire-days to expire current and non-current versions of an object at different times.

mc ilm rule add --prefix "doc/" --expire-days "300" --noncurrent-expire-days "100" myminio/mybucket

This command looks at the contents with the doc/ prefix in the mybucket bucket on the myminio deployment.

• Current objects expire after 300 days.
• Non-current objects expire after 100 days.

Transition noncurrent versions in the prefix /doc with a size greater the 1MiB

Use the mc ilm rule add command with --prefix, --size-gt, and --noncurrent-expire-days to expire current and non-current versions of an object at different times.

mc ilm rule add --prefix "doc/" --size-gt 1MiB --transition-days "90" --transition-tier "MINIOTIER-1" \
      --noncurrent-transition-days "45" --noncurrent-transition-tier "MINIOTIER-1" \
      myminio/mybucket/

This command looks at the contents with the doc/ prefix in the mybucket bucket on the myminio deployment.

The command selects the following objects:

• Current objects older than 90 days larger than 1MiB.
• Non-current objects older than 45 days larger than 1MiB.

Selected objects transition to MINIOTIER-1.

Remove Delete Markers

The following command removes delete markers for objects where the delete marker is the only version of the object that remains.

mc ilm rule add ALIAS/PATH --expire-delete-marker

• Replace ALIAS with the alias of the S3-compatible host.
• Replace PATH with the path to the bucket on the S3-compatible host.

Required Permissions

For permissions required to add a rule, refer to the required permissions on the parent command.

Behavior

Lifecycle Management Object Scanner

MinIO uses a scanner process to check objects against all configured lifecycle management rules. Slow scanning due to high IO workloads or limited system resources may delay application of lifecycle management rules. See Lifecycle Management Object Scanner for more information.

Expiry vs Transition

MinIO supports specifying both expiry and transition rules in the same bucket or bucket prefix. MinIO can execute an expiration rule on an object regardless of its transition status. Use mc ilm rule ls to review the currently configured object lifecycle management rules for any potential interactions between expiry and transition rules.

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

11 - mc ilm tier add

Description

The mc ilm tier add command creates a new remote storage tier to a supported storage services.

See Object Transition for a complete list.

Supported S3 Services

mc ilm tier add supports only the following S3-compatible services as a remote target for object tiering:

• MinIO
• Amazon S3
• Google Cloud Storage
• Azure Blob Storage

Permissions

MinIO requires the following administrative permissions on the cluster in which you create remote tiers for object transition lifecycle management rules:

• admin:SetTier
• admin:ListTier

For example, the following policy provides permission for configuring object transition lifecycle management rules on any bucket in the cluster:

{
   "Version": "2012-10-17",
   "Statement": [
      {
            "Action": [
               "admin:SetTier",
               "admin:ListTier"
            ],
            "Effect": "Allow",
            "Sid": "EnableRemoteTierManagement"
      },
      {
            "Action": [
               "s3:PutLifecycleConfiguration",
               "s3:GetLifecycleConfiguration"
            ],
            "Resource": [
                        "arn:aws:s3:::*"
            ],
            "Effect": "Allow",
            "Sid": "EnableLifecycleManagementRules"
      }
   ]
}

Syntax

 mc ilm tier add minio myminio WARM-MINIO-TIER                     \
                               --endpoint https://warm-minio.com   \
                               --access-key ACCESSKEY              \
                               --secret-key SECRETKEY              \
                               --bucket mybucket                   \
                               --prefix myprefix/

mc ilm tier add TIER_TYPE                    \
                TARGET                       \
                TIER_NAME                    \
                --bucket value               \
                [--endpoint string]          \
                [--region string]            \
                [--access-key value^]        \
                [--secret-key value^]        \
                [--use-aws-role^]            \
                [--aws-role-arn^]            \
                [--aws-web-identity-file^]   \
                [--azure-sp-tenant-id^]      \
                [--azure-sp-client-id^]      \
                [--azure-sp-client-secret^]  \
                [--account-name value^]      \
                [--account-key value^]       \
                [--credentials-file value^]  \
                [--prefix value]             \
                [--storage-class value]

Parameters

The command accepts the following arguments:

TIER_TYPE

mc-cmd

Required

The Cloud Service Provider storage backend (“Tier”) to which MinIO transitions objects. Specify one of the following supported values:

TARGET

mc-cmd

Required

The alias of a configured MinIO deployment on which the command creates the new remote tier. You can then create new rules with mc ilm rule add specifying the new remote tier.

TIER_NAME

mc-cmd

Required

The name to associate with the new remote tier. The name must be unique across all configured tiers on the MinIO cluster.

You must specify the tier in all-caps, e.g. WARM_TIER.

--endpoint

mc-cmd

Optional

The URL endpoint for the S3 or MinIO storage. The URL endpoint must resolve to the provider specified to TIER_TYPE.

Required for s3 or minio tier types, optional for azure. This option has no effect for any other value of TIER_TYPE.

--access-key

mc-cmd

Optional

The access key for a user on the remote S3 or minio tier types. The user must have permission to perform read/write/list/delete operations on the remote bucket or bucket prefix.

Required if TIER_TYPE is s3 or minio. This option has no effect for any other value of TIER_TYPE.

--secret-key

mc-cmd

Optional

The secret key for a user on the remote s3 or minio tier types.

Required if TIER_TYPE is s3 or minio. This option has no effect for any other value of TIER_TYPE.

--account-name

mc-cmd

Optional

The Storage Account to use as the remote storage resource.

Required if TIER_TYPE is azure. This option has no effect for any other value of TIER_TYPE.

MinIO does not support changing the storage account name associated to an Azure remote tier. Azure storage backends are tied to the storage account, such that changing this value would change the storage backend and prevent access to any objects transitioned to the original account/backend.

--account-key

mc-cmd

Optional

The corresponding shared account key for the --account-name associated to the remote Azure tier.

The account key must have an assigned Azure policy with the required permissions.

Required if TIER_TYPE is azure. This option has no effect for any other value of TIER_TYPE.

--credentials-file

mc-cmd

Optional

The credential file for a user on the remote Google Cloud Storage tier. The user must have permission to perform read/write/list/delete operations on the remote bucket or bucket prefix.

Required if TIER_TYPE is gcs. This option has no effect for any other value of TIER_TYPE.

--bucket

mc-cmd

Required

The bucket on the remote tier to which MinIO transitions objects.

For azure remote tiers, this value corresponds to the Container name

--prefix

mc-cmd

Optional

The prefix path for the specified --bucket to which MinIO transitions objects.

Omit this field to transition objects into the bucket root.

--storage-class

mc-cmd

Optional

The storage class (“access tier” for Microsoft Azure) MinIO applies to objects transitioned to the remote bucket.

The storage class to apply to objects transitioned by MinIO to the remote bucket. MinIO tiering behavior depends on the remote storage returning objects immediately (milliseconds to seconds) upon request. MinIO therefore cannot support remote storage which requires rehydration, wait periods, or manual intervention.

Select the tab corresponding to the TIER_TYPE for a list of supported values for each tier:

If omitted, objects use the default storage class defined for the remote bucket.

--region

mc-cmd

Optional

The S3 backend region for the specified TIER_TYPE, such as us-west-1.

This option only applies if TIER_TYPE is s3 or minio. This option has no effect for any other value of TIER_TYPE.

--use-aws-role

mc-cmd

Optional

Use the access permission for the locally configured AWS Role.

This option only applies if TIER_TYPE is s3 or minio. This option has no effect for any other value of TIER_TYPE.

--aws-role-arn

mc-cmd

Optional

The AWS S3 role name to use when transitioning objects.

This option only applies if TIER_TYPE is s3 and the source is a MinIO pod on Amazon EKS.

--aws-web-identity-file

mc-cmd

Optional

Specify the web identity token file to use when transitioning objects.

This option only applies if TIER_TYPE is s3 and the source is a MinIO pod on Amazon EKS.

--azure-sp-tenant-id

mc-cmd

Optional

Tenant ID for the service principal account to use to log in to Azure storage.

This option only applies if TIER_TYPE is azure and you log in using a service principal identity. This option has no effect for any other value of TIER_TYPE.

--azure-sp-client-id

mc-cmd

Optional

Client ID for the service principal account to use to log in to Azure storage.

This option only applies if TIER_TYPE is azure and you log in using a service principal identity. This option has no effect for any other value of TIER_TYPE.

--azure-sp-client-secret

mc-cmd

Optional

The client secret for the service principal account to use to log in to Azure storage.

This option only applies if TIER_TYPE is azure and you log in using a service principal identity. This option has no effect for any other value of TIER_TYPE.

Global Flags

This command supports any of the global flags.

Examples

Configure a Tier to Transition Objects to a MinIO Deployment

The following example creates a new tier on a local deployment that a configured rule can use to transition objects to a separate, remote MinIO deployment.

mc ilm tier add minio myminio WARM-MINIO-TIER --endpoint https://warm-minio.com \
     --access-key ACCESSKEY --secret-key SECRETKEY --bucket mybucket --prefix myprefix/

This command creates a new tier called WARM-MINIO-TIER for a minio type of remote storage on the myminio deployment.

• The remote MinIO storage is located at https://warm-minio.com.
• The command includes credentials for a user with read, write, list, and delete privileges to the bucket and prefix.
• The tier transitions objects to the mybucket bucket and the myprefix prefix on the remote MinIO storage.

Configure a Tier to Transition Objects to an Azure Blob Storage Location

The following example creates a new tier on a local deployment that a configured rule can use to transition objects to Azure Blob Storage.

mc ilm tier add azure myminio AZTIER --account-name ACCOUNT-NAME --account-key ACCOUNT-KEY \
     --bucket myazurebucket --prefix myazureprefix/

This command creates a new tier called AZTIER for an azure type of remote storage on the myminio deployment.

• The remote Azure storage is accessed by the provided account name and key.
• The tier transitions objects to the myazurebucket bucket and the myazureprefix prefix on the Azure storage.

Configure a Tier to Transition Objects to Google Cloud Storage

The following example creates a new tier on a local deployment that a configured rule can use to transition objects to Google Cloud Storage.

 mc ilm tier add gcs myminio GCSTIER --credentials-file /path/to/credentials.json \
     --bucket mygcsbucket  --prefix mygcsprefix/

This command creates a new tier called GCSTIER for a gcs type of remote storage on the myminio deployment.

• The remote GCS storage is accessed by the provided credentials file.
• The tier transitions objects to the mygcsbucket bucket and the mygcsprefix prefix on the GCS storage.

Configure a Tier to Transition Objects to Amazon Simple Storage Service (S3)

The following example creates a new tier on a local deployment that a configured rule can use to transition objects to a STANDARD storage on S3.

 mc ilm tier add s3 myminio S3TIER --endpoint https://s3.amazonaws.com \
     --access-key ACCESSKEY --secret-key SECRETKEY --bucket mys3bucket --prefix mys3prefix/ \
     --storage-class "STANDARD" --region us-west-2

This command creates a new tier called S3TIER for a s3 type of remote storage on the myminio deployment.

• The S3 storage is located at the provided endpoint.
• The remotes S3 storage is accessed by the provided access key and secret key.
• The tier transitions objects to the mys3bucket bucket and the mys3prefix prefix on the GCS storage.
• The tier utilizes S3 STANDARD storage class located in the us-west-2 S3 region.

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

Required Permissions

For permissions required to add a tier, refer to the required permissions on the parent command.

12 - mc legalhold clear

Syntax

The mc legalhold clear command removes the current legal hold setting for an object or objects.

Removing the legal hold on object(s) does not remove any other GOVERNANCE Mode and COMPLIANCE Mode retention settings in place for the object(s)

mc legalhold clear --recursive myminio/mydata

mc [GLOBALFLAGS] legalhold clear \
                 [--recursive]   \
                 [--rewind]      \
                 [--version-id]  \
                 ALIAS

Parameters

ALIAS

mc-cmd

Required

The MinIO alias and path to the object or objects on which to remove the legal hold. For example:

mc legalhold clear play/mybucket/myobjects/objects.txt

--recursive, r

mc-cmd

Optional

Removes the legal hold on all objects in the ALIAS bucket or bucket prefix.

--rewind

mc-cmd

Optional

Directs mc legalhold clear 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-formatted timestamp. For example: --rewind "2020.03.24T10:00".
• To rewind a duration in time, specify the duration as a string in #d#hh#mm#ss format. For example: --rewind "1d2hh3mm4ss".

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

--version-id, vid

mc-cmd

Optional

Directs mc legalhold clear to operate only on the specified object version.

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

Global Flags

This command supports any of the global flags.

Examples

Retrieve the Legal Hold Status Objects

Use mc legalhold clear to retrieve the legal hold status of an object. Include --recursive to return the legal hold status of the contents of a bucket:

mc legalhold clear [--recursive] ALIAS/PATH

• Replace ALIAS with the alias of the S3-compatible host.
• Replace PATH with the path to the bucket or object on the S3-compatible host. If specifying the path to a bucket or bucket prefix, include the --recursive option.

Behavior

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

13 - mc license info

Description

The mc license info command displays information about the MinIO deployment’s license status. Specifically, whether the deployment uses the AGPLv3 Open Source license of the MinIO Commercial License.

You must register your deployment with MinIO MinIO SUBNET to activate your commercial license.

For example, the command returns the following information for an unregistered deployment:

You are using GNU AFFERO GENERAL PUBLIC LICENSE Version 3 (https://www.gnu.org/licenses/agpl-3.0.txt)

If you are building proprietary applications, you may want to choose the commercial license
included as part of the Standard and Enterprise subscription plans. (https://min.io/signup?ref=mc)

Applications must otherwise comply with all the GNU AGPLv3 License & Trademark obligations.

Use mc license register to associate your deployment with your SUBNET account. If you are not already signed up for SUBNET, see the Registration page.

Examples

Display the Current License for a Deployment with Alias minio1

mc license info minio1

If a deployment uses an expired MinIO Commercial License, the command outputs an error message.

Syntax

The command has the following syntax:

mc [GLOBALFLAGS] license info       \
                         ALIAS      \
                         [--airgap]

Parameters

ALIAS

mc-cmd

Required

The alias of the MinIO deployment.

--airgap

mc-cmd

Optional

Use in environments where the client machine running the minio client does not have network access to SUBNET (for example, airgapped, firewalled, or similar configuration) to display instructions for how to register the deployment with SUBNET.

If the deployment is airgapped, but the local device has network access, you do not need to use the --airgap flag.

Global Flags

This command supports any of the global flags.

14 - mc replicate add

Syntax

The mc replicate add command creates a new server-side replication rule for a bucket on a MinIO deployment.

The remote bucket must be on a MinIO deployment running the same version of MinIO as the local deployment.

The MinIO deployment automatically begins synchronizing new objects to the remote MinIO deployment after creating the rule. You can optionally configure synchronization of existing objects, delete operations, and fully-deleted objects.

mc replicate add                                                     \
   --remote-bucket https://user:[email protected]:9001/bucket  \
   --replicate "delete,delete-marker,existing-objects"               \
   myminio/mydata

mc [GLOBALFLAGS] replicate add                     \
                 --remote-bucket string          \
                 [--bandwidth "string"]            \
                 [--disable]                       \
                 [--disable-proxy]                 \
                 [--healthcheck-seconds integer]   \
                 [--id "string"]                   \
                 [--limit-upload "string"]         \
                 [--limit-download "string"]       \
                 [--path "string"]                 \
                 [--region "string"]               \
                 [--replicate "string"]            \
                 [--storage-class "string"]        \
                 [--sync]                          \
                 [--tags "string"]                 \
                 [--priority int]                  \
                 ALIAS

Parameters

ALIAS

mc-cmd

Required

The alias of the MinIO deployment and full path to the bucket or bucket prefix on which to create the replication rule. For example:

mc replicate add --remote-bucket https://user:[email protected]:9001/bucket play/mybucket

--remote-bucket

mc-cmd

Required

Specify the credentials, destination deployment, and bucket of the remote location. Value may be an IP address, URL, or alias/bucket.

For example, a URL based target might look like the following:

https://user:[email protected]:9001/bucket

An alias based target might look like the following:

--remote-bucket minio-target/my-bucket

--bandwidth

mc-cmd

Optional

Limit bandwidth rates to no more than the specified rate in KiB/s, MiB/s, or GiB/s. Valid units include:

• B for bytes
• K for kilobytes
• G for gigabytes
• T for terabytes
• Ki for kibibytes
• Gi for gibibytes
• Ti for tebibytes

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

--limit-upload 1Gi

If not specified, MinIO does not limit the bandwidth rate.

--disable

mc-cmd

Optional

Creates the replication rule in the “disabled” state. MinIO does not begin replicating objects using the rule until it is enabled using mc replicate update.

Objects created while replication is disabled are not immediately eligible for replication after enabling the rule. You must explicitly enable replication of existing objects by including "existing-objects" to the list of replication features specified to mc replicate update --replicate. See Replication of Existing Objects for more information.

--disable-proxy

mc-cmd

Optional

When defining active-active replication between buckets, do not proxy.

By default, MinIO proxies.

--healthcheck-seconds

mc-cmd

Optional

The length of time in seconds between checks on the health of the remote bucket.

If not specified, MinIO uses an interval of 60 seconds.

--id

mc-cmd

Optional

Specify a unique ID for the replication rule. MinIO automatically generates an ID if one is not specified.

--limit-download

mc-cmd

Optional

Limit download rates to no more than a specified rate in KiB/s, MiB/s, or GiB/s. Valid units include:

• B for bytes
• K for kilobytes
• G for gigabytes
• T for terabytes
• Ki for kibibytes
• 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, MinIO uses an unlimited download rate.

--limit-upload

mc-cmd

Optional

Limit upload rates to no more than the specified rate in KiB/s, MiB/s, or GiB/s. Valid units include:

• B for bytes
• K for kilobytes
• G for gigabytes
• T for terabytes
• Ki for kibibytes
• 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, MinIO uses an unlimited upload rate.

--path

mc-cmd

Optional

Enable path-style lookup support for the remote bucket.

Valid values include:

• on - use a path lookup to find the remote bucket
• off - use a resource locator style (such as a domain or IP address) lookup to find the remote bucket
• auto - ask MinIO to identify the correct type of lookup to use to find the remote bucket

When not defined, MinIO uses the auto value.

--priority

mc-cmd

Optional

Specify the integer priority of the replication rule. The value must be unique among all other rules on the source bucket. Higher values imply a higher priority than all other rules.

The default value is 0.

--region

mc-cmd

Optional

The region of the destination bucket to replicate contents to.

--replicate

mc-cmd

Optional

Specify a comma-separated list of the following values to enable extended replication features.

• delete - Directs MinIO to replicate DELETE operations to the destination bucket.

• delete-marker - Directs MinIO to replicate delete markers to the destination bucket.

• existing-objects - Directs MinIO to replicate objects created before replication was enabled or while replication was suspended.

• metadata-sync - Directs MinIO to replicate metadata for each object. For active-active replication situations only.

  Omitting this value directs MinIO to stop replicating metadata-only changes back to the source.

If not specified, MinIO syncs all options.

--storage-class

mc-cmd

Optional

Specify the MinIO storage class to apply to replicated objects.

--sync

mc-cmd

Optional

Enable synchronous replication for this remote target.

By default, MinIO uses asynchronous replication.

--tags

mc-cmd

Optional

Specify one or more ampersand & separated key-value pair tags which MinIO uses for filtering objects to replicate. For example:

mc replicate add --tags "TAG1=VALUE&TAG2=VALUE&TAG3=VALUE" ALIAS

MinIO applies the replication rule to any object whose tag set contains the specified replication tags.

Global Flags

This command supports any of the global flags.

Examples

Configure Bucket Replication

The following mc replicate add command creates a replication configuration that synchronizes all new objects, existing objects, delete operations, and delete markers to the remote target:

mc replicate add myminio/mybucket \
   --remote-bucket https://user:[email protected]/remotebucket \
   --replicate "delete,delete-marker,existing-objects"

• Replace myminio/mybucket with the ALIAS and full bucket path for which to create the replication configuration.
• Replace the --remote-bucket value with the URL or path of the remote target. If using a file path format location, use the --path on option.
• The --replicate flag directs MinIO to replicate all delete operations, delete markers, and existing objects to the remote. See Replication of Delete Operations and Replication of Existing Objects for more information on replication behavior.

Configure Bucket Replication for Historical Data Record

The following mc replicate add command creates a new bucket replication configuration that synchronizes all new and existing objects to the remote target:

mc replicate add myminio/mybucket \
   --remote-bucket https://user:[email protected]/remotebucket \
   --replicate "existing-objects"

• Replace myminio/mybucket with the ALIAS and full bucket path for which to create the replication configuration.
• Replace the --remote-bucket value with the location of the remote target. If using a file path format location, use the --path on option.
• The --replicate flag directs MinIO to replicate all existing objects to the remote. See Replication of Existing Objects for more information on replication behavior.

The resulting remote copy represents a historical record of objects on the remote, where delete operations on the source have no effect on the remote copy.

Behavior

Server-Side Replication Requires MinIO Source and Destination

MinIO server-side replication only works between MinIO deployments. Both the source and destination deployments must run MinIO.

To configure replication between arbitrary S3-compatible services, use mc mirror.

Enable Versioning on Source and Destination Buckets

MinIO relies on the immutability protections provided by versioning to synchronize objects between the source and replication target.

Use the mc version enable command to enable versioning on both the source and destination bucket before starting this procedure:

mc version enable ALIAS/PATH

• Replace ALIAS with the alias of the MinIO deployment.
• Replace PATH with the bucket on which to enable versioning.

Required Permissions

MinIO strongly recommends creating users specifically for supporting bucket replication operations. See mc admin user and mc admin policy for more complete documentation on adding users and policies to a MinIO deployment.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "admin:SetBucketTarget",
                "admin:GetBucketTarget",
                "admin:ListBatchJobs",
                "admin:DescribeBatchJob",
                "admin:StartBatchJob",
                "admin:CancelBatchJob"
            ],
            "Effect": "Allow",
            "Sid": "EnableRemoteBucketConfiguration"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetReplicationConfiguration",
                "s3:ListBucket",
                "s3:ListBucketMultipartUploads",
                "s3:GetBucketLocation",
                "s3:GetBucketVersioning",
                "s3:GetObjectRetention",
                "s3:GetObjectLegalHold",
                "s3:PutReplicationConfiguration"
            ],
            "Resource": [
                "arn:aws:s3:::*"
            ],
            "Sid": "EnableReplicationRuleConfiguration"
        }
    ]
}

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetReplicationConfiguration",
                "s3:ListBucket",
                "s3:ListBucketMultipartUploads",
                "s3:GetBucketLocation",
                "s3:GetBucketVersioning",
                "s3:GetBucketObjectLockConfiguration",
                "s3:GetEncryptionConfiguration"
            ],
            "Resource": [
                "arn:aws:s3:::*"
            ],
            "Sid": "EnableReplicationOnBucket"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetReplicationConfiguration",
                "s3:ReplicateTags",
                "s3:AbortMultipartUpload",
                "s3:GetObject",
                "s3:GetObjectVersion",
                "s3:GetObjectVersionTagging",
                "s3:PutObject",
                "s3:PutObjectRetention",
                "s3:PutBucketObjectLockConfiguration",
                "s3:PutObjectLegalHold",
                "s3:DeleteObject",
                "s3:ReplicateObject",
                "s3:ReplicateDelete"
            ],
            "Resource": [
                "arn:aws:s3:::*"
            ],
            "Sid": "EnableReplicatingDataIntoBucket"
        }
    ]
}

Replication of Existing Objects

Starting with mc RELEASE.2021-06-13T17-48-22Z and minio RELEASE.2021-06-07T21-40-51Z, MinIO supports automatically replicating existing objects in a bucket. MinIO existing object replication implements functionality similar to AWS Replicating existing objects between S3 buckets without the overhead of contacting technical support.

• To enable replication of existing objects when creating a new replication rule, include "existing-objects" to the list of replication features specified to mc replicate add --replicate.
• To enable replication of existing objects for an existing replication rule, add "existing-objects" to the list of existing replication features using mc replicate add --replicate. You must specify all desired replication features when editing the replication rule.

See Replication of Existing Objects for more complete documentation on this behavior.

Synchronization of Metadata Changes

MinIO supports two-way active-active replication configurations, where MinIO synchronizes new and modified objects between a bucket on two MinIO deployments. Starting with mc RELEASE.2021-05-18T03-39-44Z, MinIO by default synchronizes metadata-only changes to a replicated object back to the “source” deployment. Prior to the this update, MinIO did not support synchronizing metadata-only changes to a replicated object.

With metadata synchronization enabled, MinIO resets the object replication status to indicate replication eligibility. Specifically, when an application performs a metadata-only update to an object with the REPLICA status, MinIO marks the object as PENDING and eligible for replication.

To disable metadata synchronization, use the mc replicate update --replicate command and omit replica-metadata-sync from the replication feature list.

Replication of Delete Operations

MinIO supports replicating delete operations onto the target bucket. Specifically, MinIO can replicate both Delete Markers and the deletion of specific versioned objects:

• For delete operations on an object, MinIO replication also creates the delete marker on the target bucket.
• For delete operations on versions of an object, MinIO replication also deletes those versions on the target bucket.

MinIO does not replicate objects deleted due to lifecycle management expiration rules. MinIO only replicates explicit client-driven delete operations.

MinIO requires explicitly enabling replication of delete operations using the mc replicate add --replicate flag. This procedure includes the required flags for enabling replication of delete operations and delete markers. See Replication of Delete Operations for more complete documentation on this behavior.

Replication of Encrypted Objects

MinIO supports replicating objects encrypted with automatic Server-Side Encryption (SSE-S3). Both the source and destination buckets must have automatic SSE-S3 enabled for MinIO to replicate an encrypted object.

As part of the replication process, MinIO decrypts the object on the source bucket and transmits the unencrypted object. The destination MinIO deployment then re-encrypts the object using the destination bucket SSE-S3 configuration. MinIO strongly recommends enabling TLS on both source and destination deployments to ensure the safety of objects during transmission.

MinIO does not support replicating client-side encrypted objects (SSE-C).

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

15 - mc retention set

Syntax

The mc retention set command configures the Write-Once Read-Many (WORM) locking settings for an object or object(s) in a bucket. You can also set the default object lock settings for a bucket, where all objects without explicit object lock settings inherit the bucket default.

To lock an object under legal hold, use mc legalhold set.

mc retention set requires that the specified bucket has object locking enabled. You can only enable object locking at bucket creation. See mc mb --with-lock for documentation on creating buckets with object locking enabled.

mc retention set --default GOVERNANCE "30d" myminio/mydata

mc [GLOBALFLAGS] retention set                         \
                 [--bypass]                            \
                 [--default]                           \
                 [--recursive]                         \
                 [--rewind "string"]                   \
                 [--versions]                          \
                 [--version-id "string"]*              \
                 MODE                                  \
                 "VALIDITY"                            \
                 ALIAS

Parameters

MODE

mc-cmd

Required

Sets the locking mode for the ALIAS. Specify one of the following supported values:

• governance
• compliance

See the AWS S3 documentation on Object Lock Overview for more information on the supported modes.

Requires specifying VALIDITY.

VALIDITY

mc-cmd

Required

The duration which objects remain in the specified MODE after creation.

• For days, specify a string formatted as Nd. For example,

  30d for 30 days after object creation.

• For years, specify a string formatted as Ny. For example,

  1y for 1 year after object creation.

ALIAS

mc-cmd

Required

The full path to the object or objects for which to set object lock configuration. Specify the alias for the MinIO or S3-compatible service and the full path to bucket. For example:

mc retention set play/mybucket/object.txt MODE VALIDITY

• If the ALIAS specifies a bucket or bucket prefix, include --recursive to apply the object lock settings to the bucket contents.
• mc retention set by default applies to only the latest object version. Use --version-id or --versions to apply the object lock settings to a specific version or to all versions of the object respectively.

--bypass

mc-cmd

Optional

Allows a user with the s3:BypassGovernanceRetention permission to modify the object. Requires the governance retention MODE

--default

mc-cmd

Optional

Sets the default object lock settings for the bucket specified to ALIAS using the MODE and VALIDITY. Any objects created in the bucket inherit the default object lock settings unless explicitly overriden using mc retention set.

If specifying --default, mc retention set ignores all other flags.

--recursive, --r

mc-cmd

Optional

Recursively applies the object lock settings to all objects in the specified ALIAS path.

Mutually exclusive with --version-id.

--rewind

mc-cmd

Optional

Directs mc retention set 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-formatted timestamp. For example: --rewind "2020.03.24T10:00".
• To rewind a duration in time, specify the duration as a string in #d#hh#mm#ss format. For example: --rewind "1d2hh3mm4ss".

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

--version-id, --vid

mc-cmd

Optional

Directs mc retention set to operate only on the specified object version.

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

Mutually exclusive with any of the following flags:

• --versions
• --rewind
• --recursive

--versions

mc-cmd

Optional

Directs mc retention set to operate on all object versions that exist in the bucket.

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

Use --versions and --rewind together to apply the retention settings to all object versions that existed at a specific point-in-time.

Global Flags

This command supports any of the global flags.

Examples

Set Default Bucket Retention Settings

Use mc retention set with the --recursive and --default to set the default bucket retention settings.

mc retention set  --recursive --default MODE DURATION ALIAS/PATH

• Replace MODE with the retention mode to enable. MinIO supports the AWS S3 retention modes governance and compliance.
• Replace DURATION with the duration which the object lock should remain in effect. For example, to set a retention period of 30 days, specify 30d.
• Replace ALIAS with the alias of a configured S3-compatible host.
• Replace PATH with the path to the bucket.

The bucket must have object locking enabled to use this command. You can only enable object locking when creating a bucket. See mc mb --with-lock for more information on creating buckets with object locking enabled.

Set Object Lock Configuration for Versioned Object

mc retention set --version-id VERSION MODE DURATION ALIAS/PATH

mc retention set --versions  MODE DURATION ALIAS/PATH

The bucket must have object locking enabled to use this command. You can only enable object locking when creating a bucket. See mc mb --with-lock for more information on creating buckets with object locking enabled.

Behavior

Retention of Object Versions

For buckets with versioning enabled, mc retention set by default operates on the latest version of the target object or object(s). mc retention set includes specific options that when explicitly specified direct the command to operate on either a specific object version or all versions of an object:

Interaction with Legal Holds

Locking an object prevents any modification or deletion of that object, similar to the COMPLIANCE object locking mode. Objects can have simultaneous retention-based locks and legal hold locks.

The legal hold lock overrides any retention locking, such that an object under legal hold remains locked even if the retention period expires. Setting, modifying, or clearing retention settings for an object under legal hold has no effect until the legal hold either expires or is explicitly disabled.

For more information on object legal holds, see mc legalhold.

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

16 - mc share download

Syntax

The mc share download command generates a temporary presigned URL with integrated access credentials for downloading objects from a MinIO bucket. The temporary URL expires after a configurable time limit.

• Applications can perform a GET to retrieve the object from the URL.
• Users can open the URL in a browser to download the object.

For more information on shareable object URLs, see the Amazon S3 documentation on Pre-Signed URLs.

mc share download --recursive myminio/mydata

mc [GLOBALFLAGS] share download           \
                 [--expire "string"]      \
                 [--recursive]            \
                 [--version-id "string"]  \
                 ALIAS

Parameters

ALIAS

mc-cmd

Required

The alias of a MinIO deplyment and the full path to the object for which to generate a download URL. For example:

mc share download play/mybucket/object.txt

You can specify multiple objects on the same or different MinIO deployments. For example:

mc share download play/mybucket/object.txt play/mybucket/otherobject.txt

If specifying the path to a bucket or bucket prefix, you must also specify the --recursive argument. For example:

mc share download --recursive play/mybucket/

mc share download --recursive play/mybucket/myprefix/

--expire, E

mc-cmd

Optional

Set the expiration time limit for all generated URLs.

Specify a string with format ##h##m##s format. For example: 12h34m56s for an expiry of 12 hours, 34 minutes, and 56 seconds after URL generation.

Defaults to 168h or 168 hours (7 days).

--recursive, r

mc-cmd

Optional

Recursively generate URLs for all objects in a mc share download ALIAS bucket or bucket prefix.

Required if any ALIAS specifies a path to a bucket or bucket prefix.

--version-id, vid

mc-cmd

Optional

Directs mc share download to operate only on the specified object version.

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

Global Flags

This command supports any of the global flags.

Examples

Generate a URL to Download Object(s)

mc share download --expire DURATION ALIAS/PATH

mc share download --recursive --expire DURATION ALIAS/PATH

Behavior

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

17 - mc support callhome

Description

The mc support callhome command allows the enabling or disabling of diagnostic information from a deployment to MinIO SUBNET.

All mc support commands require an active SUBNET subscription.

When enabled, MinIO sends diagnostic information to SUBNET.

MinIO disables this functionality by default, regardless of registration status. You must explicitly enable the callhome function to begin information upload.

Syntax

mc support callhome enable

mc-cmd

Begin sending a deployment’s diagnostics, logs, or both to SUBNET.

mc support callhome enable    \
                    ALIAS     \
                    [--logs]  \
                    [--diag]

mc support callhome disable

mc-cmd

Stop sending a deployment’s diagnostics, logs, or both to SUBNET.

mc support callhome disable  \
                    ALIAS    \
                    [--logs] \
                    [--diag]

mc support callhome status

mc-cmd

Output whether a deployment currently sends diagnostics, logs, or both to SUBNET.

mc support callhome status   \
                    ALIAS    \
                    [--diag]

Parameters

ALIAS

mc-cmd

Required

The alias of the MinIO deployment.

--diag

mc-cmd

Optional

Send or stop sending deployment diagnostic information to SUBNET every 24 hours.

Examples

Enable callhome reporting

Enable sending diagnostic information to SUBNET for a deployment registered to SUBNET with an alias of minio1.

mc support callhome enable minio1

Disable callhome reporting

Disable sending diagnostic information to SUBNET for a deployment registered to SUBNET with an alias of minio1.

mc support callhome disable minio1

Display Current callhome settings

Display whether a deployment with the alias minio1 sends information to SUBNET.

mc support callhome status minio1

Global Flags

This command supports any of the global flags.

18 - mc support top api

Syntax

The mc support top api command summarizes the real-time API events on a MinIO deployment server.

mc support top api myminio/

mc [GLOBALFLAGS] support top api    \
                 TARGET             \
                 [--name "string"]  \
                 [--path "string"]  \
                 [--node "string"]  \
                 [--errors, -e]

Parameters

TARGET

mc-cmd

Required

The full path to the alias, prefix, or object where the command should run. The path must include at least an ALIAS.

--name

mc-cmd

Optional

Outputs a summary of current API calls matching the entered string.

--path

mc-cmd

Optional

Outputs a summary of current API calls for a specified path.

--node

mc-cmd

Optional

Outputs a summary of the current API calls on matching servers.

--errors, -e

mc-cmd

Optional

Outputs a summary of current API calls returning errors.

Global Flags

This command supports any of the global flags.

Examples

Display All Current In-progress S3 API Calls

The following command displays all in-progress S3 calls for the myminio deployment:

mc support top api myminio/

Display Current, In-progress s3.PutObject Calls

The following command displays all in-progress s3.PutObject calls for the myminio deployment:

mc support top api --name s3.PutObject myminio/

19 - mc tag set

Syntax

The mc tag set command sets one or more tags to a bucket or object.

MinIO supports adding up to 10 custom tags to an object.

mc tag set myminio/mydata "tag1=value1&tag2=value2"

mc [GLOBALFLAGS] tag set                   \
                 [--rewind "string"]       \
                 [--versions]              \
                 [--version-id "string"]*  \
                 ALIAS                     \
                 "TAGS"

Parameters

ALIAS

mc-cmd

Required

The alias for a MinIO deployment and the full path to the object on which to apply the tag (e.g. bucket and path to object). For example:

mc tag set myminio/mybucket/object.txt

TAGS

mc-cmd

Required

An ampersand-seperated (&) list of key-value pairs (KEY=VALUE), where each pair represents one tag to assign to the object. For example:

mc tag set myminio/mybucket/object.txt "key1=value1&key2=value2"

--exclude-folders

mc-cmd

Optional

When used with --recursive, causes mc tag set to not traverse child prefixes. Tags are only applied to objects at the specified path. Requires --recursive.

The following example applies the tag destination=international to objects at vacation-photos/cancun/ but not vacation-photos/cancun/ocean/ or other prefixes.

For example, the above would add the tags to the object at vacation-photos/cancun/pretty-beach.jpg but not to the object at vacation-photos/cancun/ocean/tropical-fish.jpg.

mc tag set myminio/vacation-photos/cancun "destination=international" --exclude-folders --recursive

--recursive, r

mc-cmd

Optional

Recursively applies the tag to all objects at the path specified to ALIAS.

--rewind

mc-cmd

Optional

Directs mc tag set 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-formatted timestamp. For example: --rewind "2020.03.24T10:00".
• To rewind a duration in time, specify the duration as a string in #d#hh#mm#ss format. For example: --rewind "1d2hh3mm4ss".

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

--versions

mc-cmd

Optional

Directs mc tag set to operate on all object versions that exist in the bucket.

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

Use --versions and --rewind together to apply the tag all object versions which existed at a specific point in time.

--version-id, --vid

mc-cmd

Optional

Directs mc tag set to operate only on the specified object version.

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

Mutually exclusive with the following parameters:

• --rewind
• --versions

Global Flags

This command supports any of the global flags.

Examples

Apply Tags to a Bucket or Object

Use mc tag set to apply tags to a bucket or object:

mc tag set ALIAS/PATH "TAGS"

• Replace ALIAS with the alias of the MinIO deployment.
• Replace PATH with the path to the bucket or object on the MinIO deployment.
• Replace TAGS with one or more ampersand-separated (&) key-value pairs for each tag and its corresponding value.

Behavior

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

20 - mc version enable

Syntax

The mc version enable command enables versioning on the specified bucket.

 mc version enable myminio/mybucket

mc [GLOBALFLAGS] version enable ALIAS                \
                                --exclude-folders    \
                                --excluded-prefixes

Parameters

ALIAS

mc-cmd

Required

The alias of a MinIO deployment and the full path to the bucket for which to enable versioning. For example:

mc version enable myminio/mybucket

--exclude-folders

mc-cmd

Optional

Disable versioning on all folders (objects whose name ends with /) in the specified bucket.

--excluded-prefixes

mc-cmd

Optional

Disable versioning on objects matching a list of prefixes, up to 10. The list of prefixes match all objects containing the specified strings in their prefix or name, similar to a regular expression of the form prefix*. To match objects by prefix only, use prefix/*.

For example, the following command excludes any objects containing _test or _temp in their prefix or name from versioning:

mc version enable --excluded-prefixes "_test, _temp" myminio/mybucket

Global Flags

This command supports any of the global flags.

Example

Enable Bucket Versioning

Use mc version enable to enable versioning for a bucket:

mc version enable ALIAS/PATH

• Replace ALIAS with the alias of a configured MinIO deployment.
• Replace PATH with the bucket on which to enable versioning.

Behavior

Bucket Versioning with Existing Data

Enabling bucket versioning on a bucket with existing data immediately creates a NULL value version ID for each unversioned object.

S3 Compatibility

The mc commandline tool is built for compatibility with the AWS S3 API and is tested with 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.

21 - Silo Client Settings

This page covers settings for the MinIO Client.

You can establish or modify settings by defining:

• an environment variable on the host system prior to starting or restarting the MinIO Server. Refer to your operating system’s documentation for how to define an environment variable.
• a configuration setting using mc admin config set.

If you define both an environment variable and the similar configuration setting, MinIO uses the environment variable value.

Some settings have only an environment variable or a configuration setting, but not both.

Settings

Host Credentials

Use this setting to add a temporary alias to use for mc commands. For example, for use with scripting.

The temporary alias uses the AWS s3v4 signature.

Examples

Static Credentials

export MC_HOST_<alias>=https://<Access Key>:<Secret Key>@<YOUR-S3-ENDPOINT>

export MC_HOST_myalias=https://Q3AM3UQ867SPQQA43P2F:[email protected]

Security Token Service (STS) Credentials

export MC_HOST_<alias>=https://<Access Key>:<Secret Key>:<Session Token>@<YOUR-S3-ENDPOINT>

export MC_HOST_myalias=https://Q3AM3UQ867SPQQA43P2F:zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG:eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhY2Nlc3NLZXkiOiJOVUlCT1JaWVRWMkhHMkJNUlNYUiIsImF1ZCI6IlBvRWdYUDZ1Vk80NUlzRU5SbmdEWGo1QXU1WWEiLCJhenAiOiJQb0VnWFA2dVZPNDVJc0VOUm5nRFhqNUF1NVlhIiwiZXhwIjoxNTM0ODk2NjI5LCJpYXQiOjE1MzQ4OTMwMjksImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0Ojk0NDMvb2F1dGgyL3Rva2VuIiwianRpIjoiNjY2OTZjZTctN2U1Ny00ZjU5LWI0MWQtM2E1YTMzZGZiNjA4In0.eJONnVaSVHypiXKEARSMnSKgr-2mlC2Sr4fEGJitLcJF_at3LeNdTHv0_oHsv6ZZA3zueVGgFlVXMlREgr9LXA@play.min.io

STS Service

Use this setting to add an STS endpoint to use for mc commands.

Supports adding multiple environment variables by alias.

export MC_STS_ENDPOINT_myalias=https://sts.minio-operator.svc.cluster.local:4223/sts/ns-1

Web Token Identity

Use this setting to add a web token identity to use for mc commands.

Supports adding multiple environment variables by alias.

export MC_WEB_IDENTITY_TOKEN_FILE_myalias=/var/run/secrets/kubernetes.io/serviceaccount/token

Configuration Directory

Specify the path to the configuration folder the MinIO Client should use.

Progress Bar

Disable the MinIO Client progress bar.

Pager

Disable the pager functionality of the MinIO Client in the CLI. When used, output prints to raw STDOUT instead.

Color Theme

Disable the color theme used for MinIO Client output.

JSON

Enable formatting the output as JSON lines.

Debug

Enable the debug output.

Disable SSL

Disable SSL certificate verification.

Limit Download Bandwidth

Limit the download bandwidth the MinIO Client uses for certain commands.

If not specified, the MinIO Client uses all available bandwidth.

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

• B for bytes
• K for kilobytes
• M for megabytes
• G for gigabytes
• Ki for kibibytes
• Mi for mibibytes
• Gi for gibibytes

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

export MC_LIMIT_DOWNLOAD=1G

Refer to your operating system instructions for equivalent commands on non-Linux systems.

Limit Upload Bandwidth

Limit the upload bandwidth the MinIO Client uses for certain commands.

If not specified, the MinIO Client uses all available bandwidth.

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 MinIO Client. Valid units include:

• B for bytes
• K for kilobytes
• M for megabytes
• G for gigabytes
• Ki for kibibytes
• Mi for mibibytes
• Gi for gibibytes

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

export MC_LIMIT_UPLOAD=1G

Refer to your operating system instructions for equivalent commands on non-Linux systems.

SSE-KMS Encryption

Encrypt and decrypt options using SSE-KMS with server managed keys.

SSE-S3 Encryption

Encrypt and decrypt options using SSE-KMS with server managed keys.

22 - mc alias

Description

The mc alias commands provide a convenient interface for managing the list of S3-compatible hosts that mc can connect to and run operations against.

Subcommands

mc alias includes the following subcommands:

23 - mc alias remove

Syntax

The mc alias remove removes an existing alias from the local mc configuration.

mc alias remove myminio

mc [GLOBALFLAGS] alias remove ALIAS

Parameters

ALIAS

mc-cmd