minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-28 19:42:10 +03:00
Code Activity

DOCS-380: Refactor CLI reference

Browse Source
This commit is contained in:
ravindk89
2021-12-16 14:19:49 -05:00
committed by Ravind Kumar
parent 0d3be1d74f
commit ef30821063
127 changed files with 10929 additions and 6960 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
source/concepts/bucket-versioning.rst
View File

@ -243,19 +243,19 @@ enable versioning on only a prefix or subset of objects in a bucket.
.. tab-item:: MinIO CLI
Use the :mc-cmd:`mc version enable` command to enable versioning on an
Use the :mc-cmd:`mc version suspend` command to enable versioning on an
existing bucket:
.. code-block:: shell
:class: copyable
mc version enable ALIAS/BUCKET
mc version ALIAS/BUCKET
- Replace ``ALIAS`` with the :mc:`alias <mc alias>` of a configured
MinIO deployment.
- Replace ``BUCKET`` with the
:mc:`target bucket <mc version enable TARGET>` on which to enable
:mc:`target bucket <mc version ALIAS>` on which to enable
versioning.
Objects created prior to enabling versioning have a
@ -295,19 +295,19 @@ MinIO :mc:`mc` CLI, or using an S3-compatible SDK.
.. tab-item:: MinIO CLI
Use the :mc-cmd:`mc version disable` command to enable versioning on an
Use the :mc-cmd:`mc version suspend` command to enable versioning on an
existing bucket:
.. code-block:: shell
:class: copyable
mc version disable ALIAS/BUCKET
mc version suspend ALIAS/BUCKET
- Replace ``ALIAS`` with the :mc:`alias <mc alias>` of a configured
MinIO deployment.
- Replace ``BUCKET`` with the
:mc:`target bucket <mc version enable TARGET>` on which to disable
:mc:`target bucket <mc version ALIAS>` on which to disable
versioning.
Objects created while versioning is suspended are assigned a

2
source/conf.py
View File

@ -78,7 +78,7 @@ templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['includes/*.rst', 'includes/imports/*']
exclude_patterns = ['includes/*.rst', 'includes/imports/*', '*-template.rst']
# Copy-Button Customization

96
source/includes/common-minio-mc.rst Normal file
View File

@ -0,0 +1,96 @@
.. start-minio-mc-globals
.. mc-cmd:: debug
:option:
Enables verbose output to the console.
For example:
.. code-block:: shell
:class: copyable
mc --debug COMMAND
.. mc-cmd:: config-dir
:option:
The path to a ``JSON`` formatted configuration file that
:program:`mc` uses for storing data. See :ref:`mc-configuration` for
more information on how :program:`mc` uses the configuration file.
.. start-minio-mc-json-globals
.. mc-cmd:: JSON
:option:
Enables `JSON lines <http://jsonlines.org/>`_ formatted output to the
console.
For example:
.. code-block:: shell
:class: copyable
mc --JSON COMMAND
.. end-minio-mc-json-globals
.. mc-cmd:: no-color
:option:
Disables the built-in color theme for console output. Useful for dumb
terminals.
.. mc-cmd:: quiet
:option:
Suppresses console output.
.. mc-cmd:: insecure
:option:
Disables TLS/SSL certificate verification. Allows TLS connectivity to
servers with invalid certificates. Exercise caution when using this
option against untrusted S3 hosts.
.. mc-cmd:: version
:option:
Displays the current version of :mc-cmd:`mc`.
.. mc-cmd:: help
:option:
Displays a summary of command usage on the terminal.
.. end-minio-mc-globals
.. start-minio-mc-no-flags
This command supports only global flags
.. end-minio-mc-no-flags
.. start-minio-mc-s3-compatibility
The :program:`mc` commandline tool is built for compatibility with the AWS S3
API and is tested MinIO and AWS S3 for expected functionality and behavior.
MinIO provides no guarantees for other S3-compatible services, as their S3 API
implementation is unknown and therefore unsupported. While :program:`mc`
commands *may* work as documented, any such usage is at your own risk.
.. end-minio-mc-s3-compatibility
.. start-minio-syntax
- Brackets ``[]`` indicate optional parameters.
- Parameters sharing a line are mutually dependent.
- Parameters sharing a line *and* seperated using the pipe ``|`` operator are
mutually exclusive.
Copy the example to a text editor and modify as-needed before running the
command in the terminal/shell.
.. end-minio-syntax

10
source/includes/common-minio-tiering.rst
View File

@ -23,11 +23,11 @@ The example above specifies the following arguments:
* - Argument
- Description
* - :mc-cmd:`ALIAS <mc ilm add TARGET>`
* - :mc-cmd:`ALIAS <mc ilm add ALIAS>`
- Specify the :mc:`alias <mc alias>` of the MinIO deployment for which
you are creating the lifecycle management rule.
* - :mc-cmd:`BUCKET <mc ilm add TARGET>`
* - :mc-cmd:`BUCKET <mc ilm add ALIAS>`
- Specify the full path to the bucket for which you are
creating the lifecycle management rule.
@ -41,13 +41,15 @@ The example above specifies the following arguments:
* - :mc-cmd:`DAYS <mc ilm add transition-days>`
- The number of calendar days after which MinIO marks an object as
eligible for transition.
eligible for transition. Specify the number of days as an integer,
e.g. ``30`` for 30 days.
* - :mc-cmd:`NONCURRENT_DAYS <mc ilm add noncurrentversion-transition-days>`
- The number of calendar days after which MinIO marks a noncurrent
object version as eligible for transition. MinIO specifically measures
the time since an object *became* non-current instead of the object
creation time.
creation time. Specify the number of days as an integer,
e.g. ``90`` for 90 days.
Omit this value to ignore noncurrent object versions.

104
source/includes/facts-versioning.rst
View File

@ -1,7 +1,7 @@
.. start-rewind-desc
Directs |command| to operate only on the object version(s) that existed at
specified point-in-time.
*Optional* Directs |command| 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"``.
@ -17,7 +17,8 @@ that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
.. start-versions-desc
Directs |command| to operate on all object versions that exist in the bucket.
*Optional* Directs |command| to operate on all object versions that exist in the
bucket.
|versions| requires that the specified |alias| be an S3-compatible service
that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
@ -27,7 +28,7 @@ that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
.. start-version-id-desc
Directs |command| to operate only on the specified object version.
*Optional* Directs |command| to operate only on the specified object version.
|versionid| requires that the specified |alias| be an S3-compatible service
that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
@ -35,101 +36,6 @@ that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
.. end-version-id-desc
..
So this is an ugly workaround. Since you can't override substitutions
on a single page, those reference commands with multiple subcommands
get kind of messy. Instead, the following sections "duplicate"
the core content for supporting commands with multiple subcommands that
support versioning arguments.
The ideal path forward would be to extend the include directive to
allow for per-directive replacement, but that will take significant
engineering effort. So until then, kludges it is.
..
----------------- 2nd Argument --------------------
.. start-rewind-desc-2
Directs |command-2| 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-2| requires that the specified |alias-2| be an S3-compatible service
that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
:mc-cmd:`mc version` to enable or disable bucket versioning.
.. end-rewind-desc-2
.. start-versions-desc-2
Directs |command-2| to operate on all object versions that exist in the bucket.
|versions-2| requires that the specified |alias-2| be an S3-compatible service
that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
:mc-cmd:`mc version` to enable or disable bucket versioning.
.. end-versions-desc-2
.. start-version-id-desc-2
Directs |command-2| to operate only on the specified object version.
|versionid-2| requires that the specified |alias-2| be an S3-compatible service
that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
:mc-cmd:`mc version` to enable or disable bucket versioning.
.. end-version-id-desc-2
..
-------------- 3rd Subcommand --------------
.. start-rewind-desc-3
Directs |command-3| 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-3| requires that the specified |alias-3| be an S3-compatible service
that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
:mc-cmd:`mc version` to enable or disable bucket versioning.
.. end-rewind-desc-3
.. start-versions-desc-3
Directs |command-3| to operate on all object versions that exist in the bucket.
|versions-3| requires that the specified |alias-3| be an S3-compatible service
that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
:mc-cmd:`mc version` to enable or disable bucket versioning.
.. end-versions-desc-3
.. start-version-id-desc-3
Directs |command-3| to operate only on the specified object version.
|versionid-3| requires that the specified |alias-3| be an S3-compatible service
that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
:mc-cmd:`mc version` to enable or disable bucket versioning.
.. end-version-id-desc-3
.. start-versioning-admonition
.. admonition:: Requires Versioning

21
source/includes/minio-mc-installation.rst
View File

@ -1,26 +1,5 @@
.. tab-set::
.. tab-item:: Docker
**Stable**
.. code-block:: shell
:class: copyable
docker pull minio/mc
docker run minio/mc admin info play
**Edge**
*Do not use bleeding-edge deployments of MinIO in production environments*
.. code-block:: shell
:class: copyable
docker pull minio/mc:edge
docker run minio/mc:edge admin info server play
.. tab-item:: Linux
The following commands add a *temporary* extension to your system

28
source/index.rst
View File

@ -27,7 +27,7 @@ The MinIO Client :mc:`mc` commandline interface includes an
mc mb --with-lock play/mynewbucket
mc cp ~/data/mytestdata play/mynewbucket
See the :doc:`MinIO Client Complete Reference </reference/minio-cli/minio-mc>`
See the :doc:`MinIO Client Complete Reference </reference/minio-mc>`
for complete documentation on the available :mc:`mc` commands.
- First-time users of MinIO *or* object storage services should start with
@ -128,6 +128,28 @@ such as versioning and replication.
Identity and Access Management, Metrics and Log Monitoring, or
Server Configuration. See :ref:`minio-console` for more information.
Licensing
---------
We have designed MinIO as an Open Source software for the Open Source software
community. This requires applications to consider whether their usage of MinIO
is in compliance with the
:minio-git:`GNU AGPLv3 license <mc/blob/master/LICENSE>`.
MinIO cannot make the determination as to whether your application's usage of
MinIO is in compliance with the AGPLv3 license requirements. You should instead
rely on your own legal counsel or licensing specialists to audit and ensure your
application is in compliance with the licenses of MinIO and all other
open-source projects with which your application integrates or interacts. We
understand that AGPLv3 licensing is complex and nuanced. It is for that reason
we strongly encourage using experts in licensing to make any such determinations
around compliance instead of relying on apocryphal or anecdotal advice.
`MinIO Commercial Licensing <https://min.io/pricing>`__ is the best option for
applications that trigger AGPLv3 obligations (e.g. open sourcing your
application). Applications using MinIO - or any other OSS-licensed code -
without validating their usage do so at their own risk.
.. toctree::
:titlesonly:
:hidden:
@ -140,8 +162,8 @@ such as versioning and replication.
/replication/replication-overview
/security/security-overview
/monitoring/monitoring-overview
/reference/minio-cli/minio-mc
/reference/minio-cli/minio-mc-admin
/reference/minio-mc
/reference/minio-mc-admin
/reference/minio-server/minio-server
/reference/minio-server/minio-gateway
/console/minio-console

68
source/installation/deploy-minio-standalone.rst
View File

@ -108,7 +108,6 @@ command:
export MINIO_ROOT_USER=minio-admin
export MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME
#export MINIO_SERVER_URL=https://minio.example.net
#export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
minio server /data --console-address ":9001"
@ -136,40 +135,6 @@ The example command breaks down as follows:
as a :rfc:`Subject Alternative Name <5280#section-4.2.1.6>`.
Specify a hostname covered by one of the TLS certificate SAN entries.
* - :envvar:`MINIO_KMS_SECRET_KEY`
- The key to use for encrypting the MinIO backend (users, groups,
policies, and server configuration). Single-key backend encryption
provides a baseline of security for non-production environments, and does
not support features like key rotation. You can leave this command
commented to deploy MinIO without backend encryption.
Do not use this setting in production environments. Use the MinIO
:minio-git:`Key Encryption Service (KES) <kes>` and an external Key
Management System (KMS) to enable encryption functionality. Specify the
name of the encryption key to use to the :envvar:`MINIO_KMS_KES_KEY_NAME`
instead. See :minio-git:`KMS IAM/Config Encryption
<minio/blob/master/docs/kms/IAM.md>` for more information.
Use the following format when specifying the encryption key:
``<key-name>:<encryption-key>``
- Replace the ``<key-name>`` with any string. You must use this
key name if you later migrate to using a dedicated KMS for
managing encryption keys. See :minio-git:`KMS IAM/Config Encryption
<minio/blob/master/docs/kms/IAM.md>` for more information.
- Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
For example:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
Save the encryption key to a secure location. You cannot restart the
MinIO server without this key.
* - ``/data``
- The path to each disk on the host machine.
@ -257,7 +222,6 @@ following environment variables:
export MINIO_ROOT_USER=minio-admin
export MINIO_ROOT_PASSWORD=minio-secret-key-CHANGE-ME
#export MINIO_SERVER_URL=https://minio.example.net
#export MINIO_KMS_SECRET_KEY=my-minio-encryption-key:bXltaW5pb2VuY3J5cHRpb25rZXljaGFuZ2VtZTEyMwo=
Create the Podman secret using the ``config.env`` file:
@ -290,39 +254,7 @@ The following table details each environment variable set in ``config.env``:
as a :rfc:`Subject Alternative Name <5280#section-4.2.1.6>`.
Specify a hostname covered by one of the TLS certificate SAN entries.
* - :envvar:`MINIO_KMS_SECRET_KEY`
- The key to use for encrypting the MinIO backend (users, groups,
policies, and server configuration). Single-key backend encryption
provides a baseline of security for non-production environments, and does
not support features like key rotation. You can leave this command
commented to deploy MinIO without backend encryption.
Do not use this setting in production environments. Use the MinIO
:minio-git:`Key Encryption Service (KES) <kes>` and an external Key
Management System (KMS) to enable encryption functionality. Specify the
name of the encryption key to use to the :envvar:`MINIO_KMS_KES_KEY_NAME`
instead. See :minio-git:`KMS IAM/Config Encryption
<minio/blob/master/docs/kms/IAM.md>` for more information.
Use the following format when specifying the encryption key:
``<key-name>:<encryption-key>``
- Replace the ``<key-name>`` with any string. You must use this
key name if you later migrate to using a dedicated KMS for
managing encryption keys. See :minio-git:`KMS IAM/Config Encryption
<minio/blob/master/docs/kms/IAM.md>` for more information.
- Replace ``<encryption-key>`` with a 32-bit base64 encoded value.
For example:
.. code-block:: shell
:class: copyable
cat /dev/urandom | head -c 32 | base64 -
Save the encryption key to a secure location. You cannot restart the
MinIO server without this key.
You may specify other :ref:`environment variables
<minio-server-environment-variables>` as required by your deployment.

10
source/lifecycle-management/create-lifecycle-management-expiration-rule.rst
View File

@ -70,13 +70,13 @@ expire bucket contents a number of days after object creation:
mc ilm add ALIAS/PATH --expiry-days "DAYS"
- Replace :mc-cmd:`ALIAS <mc ilm add TARGET>` with the
- Replace :mc-cmd:`ALIAS <mc ilm add ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ilm add TARGET>` with the path to the bucket on the
- Replace :mc-cmd:`PATH <mc ilm add ALIAS>` with the path to the bucket on the
S3-compatible host.
- Replace :mc-cmd:`DATE <mc ilm add expiry-date>` with the number of days after
- Replace :mc-cmd:`DAYS <mc ilm add expiry-days>` with the number of days after
which to expire the object. For example, specify ``30`` to expire the
object 30 days after creation.
@ -99,10 +99,10 @@ delete markers:
--noncurrentversion-expiration-days NONCURRENT_DAYS \
--expired-object-delete-marker
- Replace :mc-cmd:`ALIAS <mc ilm add TARGET>` with the
- Replace :mc-cmd:`ALIAS <mc ilm add ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ilm add TARGET>` with the path to the bucket on the
- Replace :mc-cmd:`PATH <mc ilm add ALIAS>` with the path to the bucket on the
S3-compatible host.
- Replace :mc-cmd:`NONCURRENT_DAYS

10
source/lifecycle-management/lifecycle-management-overview.rst
View File

@ -85,14 +85,8 @@ older than 365 days.
.. todo: Diagram of MinIO Expiration
Use the :mc-cmd:`mc ilm add` command with one of the following commandline
options to create new expiration rules on a bucket:
- :mc-cmd-option:`mc ilm add expiry-date` to expire objects after
a specified calendar date.
- :mc-cmd-option:`mc ilm add expiry-days` to expire objects after a
specified number of calendar days.
Use :mc-cmd-option:`mc ilm add expiry-days` to expire objects after a specified
number of calendar days.
For buckets with :ref:`replication <minio-bucket-replication>` configured, MinIO
does not replicate objects deleted by a lifecycle management expiration rule.

4
source/lifecycle-management/transition-objects-to-azure.rst
View File

@ -206,8 +206,8 @@ rules:
mc ilm ls ALIAS/PATH --transition
- Replace :mc-cmd:`ALIAS <mc ilm ls TARGET>` with the :mc:`alias <mc alias>`
- Replace :mc-cmd:`ALIAS <mc ilm ls ALIAS>` with the :mc:`alias <mc alias>`
of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc ilm ls TARGET>` with the name of the bucket for
- Replace :mc-cmd:`PATH <mc ilm ls ALIAS>` with the name of the bucket for
which to retrieve the configured lifecycle management rules.

4
source/lifecycle-management/transition-objects-to-gcs.rst
View File

@ -200,8 +200,8 @@ rules:
mc ilm ls ALIAS/PATH --transition
- Replace :mc-cmd:`ALIAS <mc ilm ls TARGET>` with the :mc:`alias <mc alias>`
- Replace :mc-cmd:`ALIAS <mc ilm ls ALIAS>` with the :mc:`alias <mc alias>`
of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc ilm ls TARGET>` with the name of the bucket for
- Replace :mc-cmd:`PATH <mc ilm ls ALIAS>` with the name of the bucket for
which to retrieve the configured lifecycle management rules.

4
source/lifecycle-management/transition-objects-to-s3.rst
View File

@ -218,8 +218,8 @@ rules:
mc ilm ls ALIAS/PATH --transition
- Replace :mc-cmd:`ALIAS <mc ilm ls TARGET>` with the :mc:`alias <mc alias>`
- Replace :mc-cmd:`ALIAS <mc ilm ls ALIAS>` with the :mc:`alias <mc alias>`
of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc ilm ls TARGET>` with the name of the bucket for
- Replace :mc-cmd:`PATH <mc ilm ls ALIAS>` with the name of the bucket for
which to retrieve the configured lifecycle management rules.

53
source/monitoring/bucket-notifications/bucket-notifications.rst
View File

@ -104,18 +104,34 @@ Object Events
MinIO supports triggering notifications on the following S3 object events:
.. data:: s3:ObjectRemoved:DeleteMarkerCreated
.. data:: s3:ObjectRemoved:Delete
.. data:: s3:ObjectCreated:PutRetention
.. data:: s3:ObjectCreated:PutLegalHold
.. data:: s3:ObjectCreated:Put
.. data:: s3:ObjectCreated:Post
.. data:: s3:ObjectCreated:Copy
.. data:: s3:ObjectCreated:CompleteMultipartUpload
.. data:: s3:ObjectAccessed:Head
.. data:: s3:ObjectAccessed:GetRetention
.. data:: s3:ObjectAccessed:GetLegalHold
.. data:: s3:ObjectAccessed:Get
.. data:: s3:ObjectAccessed:GetLegalHold
.. data:: s3:ObjectAccessed:GetRetention
.. data:: s3:ObjectAccessed:Head
.. data:: s3:ObjectCreated:CompleteMultipartUpload
.. data:: s3:ObjectCreated:Copy
.. data:: s3:ObjectCreated:DeleteTagging
.. data:: s3:ObjectCreated:Post
.. data:: s3:ObjectCreated:Put
.. data:: s3:ObjectCreated:PutLegalHold
.. data:: s3:ObjectCreated:PutRetention
.. data:: s3:ObjectCreated:PutTagging
.. data:: s3:ObjectRemoved:Delete
.. data:: s3:ObjectRemoved:DeleteMarkerCreated
Specify the wildcard ``*`` character to select all events related to a prefix:
.. data:: s3:ObjectAccessed:*
Selects all ``s3:ObjectAccessed``\ -prefixed events.
.. data:: s3:ObjectCreated:*
Selects all ``s3:ObjectCreated``\ -prefixed events.
.. data:: s3:ObjectRemoved:*
Selects all ``s3:ObjectRemoved``\ -prefixed events.
Replication Events
~~~~~~~~~~~~~~~~~~
@ -129,6 +145,10 @@ events:
.. data:: s3:Replication:OperationNotTracked
.. data:: s3:Replication:OperationReplicatedAfterThreshold
Specify the wildcard ``*`` character to select all ``s3:Replication`` events:
.. data:: s3:Replication:*
ILM Transition Events
~~~~~~~~~~~~~~~~~~~~~
@ -137,10 +157,18 @@ events:
.. data:: s3:ObjectRestore:Post
.. data:: s3:ObjectRestore:Completed
.. data:: s3:ObjectTransition:*
.. data:: s3:ObjectTransition:Failed
.. data:: s3:ObjectTransition:Complete
Specify the wildcard ``*`` character to select all events related to a prefix:
.. data:: s3:ObjectTransition:*
Selects all ``s3:ObjectTransition``\ -prefixed events.
.. data:: s3:ObjectRestore:*
Selects all ``s3:ObjectRestore``\ -prefixed events.
Global Events
~~~~~~~~~~~~~
@ -152,7 +180,6 @@ You can only listen to these events through the :legacy:`ListenNotification
.. data:: s3:BucketCreated
.. data:: s3:BucketRemoved
.. todo
.. toctree::

16
source/object-retention/minio-object-locking.rst
View File

@ -212,7 +212,7 @@ the MinIO :mc:`mc` CLI, or using an S3-compatible SDK.
.. tab-item:: MinIO CLI
:sync: cli
Use the :mc-cmd:`mc mb` command with the :mc-cmd-option:`~mc mb with-lock`
Use The command command with the :mc-cmd-option:`~mc mb with-lock`
option to create a bucket with object locking enabled:
.. code-block:: shell
@ -224,7 +224,7 @@ the MinIO :mc:`mc` CLI, or using an S3-compatible SDK.
MinIO deployment.
- Replace ``BUCKET`` with the
:mc:`name <mc version enable TARGET>` of the bucket to create.
:mc:`name <mc version ALIAS>` of the bucket to create.
Configure Bucket-Default Object Retention
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -282,7 +282,7 @@ preferred SDK.
.. tab-item:: MinIO CLI
:sync: cli
Use the :mc-cmd:`mc retention` command with the
Use The command command with the
:mc-cmd-option:`--recursive <mc retention set recursive>` and
:mc-cmd-option:`--default <mc retention set default>` options to set the
default retention mode for a bucket:
@ -299,10 +299,10 @@ preferred SDK.
- Replace :mc-cmd:`DURATION <mc retention set VALIDITY>` with the
duration for which the object lock remains in effect.
- Replace :mc-cmd:`ALIAS <mc retention set TARGET>` with the
- Replace :mc-cmd:`ALIAS <mc retention set ALIAS>` with the
:mc:`alias <mc alias>` of a configured MinIO deployment.
- Replace :mc-cmd:`BUCKET <mc retention set TARGET>` with the
- Replace :mc-cmd:`BUCKET <mc retention set ALIAS>` with the
name of the bucket on which to set the default retention rule.
Enable Legal Hold Retention
@ -341,7 +341,7 @@ WORM locked until the retention lock expires *and* the legal hold is lifted.
.. tab-item:: MinIO CLI
:sync: cli
Use the :mc-cmd:`mc legalhold` command to enable or disable the legal
Use The command command to enable or disable the legal
hold on an object.
.. code-block:: shell
@ -349,10 +349,10 @@ WORM locked until the retention lock expires *and* the legal hold is lifted.
mc legalhold set ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc legalhold set TARGET>` with the
- Replace :mc-cmd:`ALIAS <mc legalhold set ALIAS>` with the
:mc:`alias <mc alias>` of a configured MinIO deployment.
- Replace :mc-cmd:`PATH <mc legalhold set TARGET>` with the
- Replace :mc-cmd:`PATH <mc legalhold set ALIAS>` with the
path to the object for which to enable the legal hold.
.. _minio-object-locking-retention-modes:

368
source/reference/minio-cli/minio-mc.rst
View File

@ -1,368 +0,0 @@
=====================
MinIO Client (``mc``)
=====================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
.. mc:: mc
The MinIO Client :mc-cmd:`mc` command line tool provides a modern alternative
to UNIX commands like ``ls``, ``cat``, ``cp``, ``mirror``, and ``diff`` with
support for both filesystems and Amazon S3-compatible cloud storage services
(AWS Signature v2 and v4).
:mc-cmd:`mc` has the following syntax:
.. code-block:: shell
mc [FLAGS] COMMAND [ARGUMENTS...] [COMMAND FLAGS | -h]
See :ref:`minio-mc-commands` for a list of supported commands:
.. _mc-install:
Quickstart
----------
1) Install ``mc``
~~~~~~~~~~~~~~~~~
Install the :program:`mc` command line tool onto the host machine. Click
the tab that corresponds to the host machine operating system or environment:
.. include:: /includes/minio-mc-installation.rst
2) Add an S3-Compatible Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. important::
The following example temporarily disables the bash history to mitigate the
risk of authentication credentials leaking in plain text. This is a basic
security measure and does not mitigate all possible attack vectors. Defer to
security best practices for your operating system for inputting sensitive
information on the command line.
Use the :mc-cmd:`mc alias set` command to add an Amazon S3-compatible service
to the :mc-cmd:`mc` :ref:`configuration <mc-configuration>`.
.. code-block:: shell
:class: copyable
bash +o history
mc alias set ALIAS HOSTNAME ACCESS_KEY SECRET_KEY
bash -o history
- Replace ``ALIAS`` with a name to associate to the S3 service.
:mc-cmd:`mc` commands typically require ``ALIAS`` as an argument for
identifying which S3 service to execute against.
- Replace ``HOSTNAME`` with the URL endpoint or IP address of the S3 service.
- Replace ``ACCESS_KEY`` and ``SECRET_KEY`` with the access and secret
keys for a user on the S3 service.
Replace each argument with the required values. Specifying only the
``mc config host add`` command starts an input prompt for entering the
required values.
Each of the following tabs contains a provider-specific example:
.. tab-set::
.. tab-item:: MinIO Server
.. code-block:: shell
:class: copyable
mc alias set myminio https://minioserver.example.net ACCESS_KEY SECRET KEY
.. tab-item:: AWS S3 Storage
.. code-block:: shell
:class: copyable
mc alias set myS3 https://s3.amazon.com/endpoint ACCESS_KEY SECRET KEY
.. tab-item:: Google Cloud Storage
.. code-block:: shell
:class: copyable
mc alias set myGCS https://storage.googleapis.com/endpoint ACCESS_KEY SECRET KEY
3) Test the Connection
~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`mc admin info` command to test the connection to
the newly added MinIO deployment:
.. code-block:: shell
:class: copyable
mc admin info myminio
The command returns information on the S3 service if successful. If
unsuccessful, check each of the following:
- The host machine has connectivity to the S3 service URL (i.e. using ``ping``
or ``traceroute``).
- The specified ``ACCESSKEY`` and ``SECRETKEY`` correspond to a user on the
S3 service. The user must have permission to perform actions on the
service.
For MinIO deployments, see :ref:`minio-access-management`
for more information on user access permissions. For other S3-compatible
services, defer to the documentation for that service.
.. _minio-mc-commands:
Command Quick Reference
-----------------------
The following table lists :mc-cmd:`mc` commands:
.. list-table::
:header-rows: 1
:widths: 25 75
:width: 100%
* - Command
- Description
* - :mc:`mc alias`
- .. include:: /reference/minio-cli/minio-mc/mc-alias.rst
:start-after: start-mc-alias-desc
:end-before: end-mc-alias-desc
* - :mc:`mc cat`
- .. include:: /reference/minio-cli/minio-mc/mc-cat.rst
:start-after: start-mc-cat-desc
:end-before: end-mc-cat-desc
* - :mc:`mc cp`
- .. include:: /reference/minio-cli/minio-mc/mc-cp.rst
:start-after: start-mc-cp-desc
:end-before: end-mc-cp-desc
* - :mc:`mc diff`
- .. include:: /reference/minio-cli/minio-mc/mc-diff.rst
:start-after: start-mc-diff-desc
:end-before: end-mc-diff-desc
* - :mc:`mc encrypt`
- .. include:: /reference/minio-cli/minio-mc/mc-encrypt.rst
:start-after: start-mc-encrypt-desc
:end-before: end-mc-encrypt-desc
* - :mc:`mc event`
- .. include:: /reference/minio-cli/minio-mc/mc-event.rst
:start-after: start-mc-event-desc
:end-before: end-mc-event-desc
* - :mc:`mc find`
- .. include:: /reference/minio-cli/minio-mc/mc-find.rst
:start-after: start-mc-find-desc
:end-before: end-mc-find-desc
* - :mc:`mc head`
- .. include:: /reference/minio-cli/minio-mc/mc-head.rst
:start-after: start-mc-head-desc
:end-before: end-mc-head-desc
* - :mc:`mc ilm`
- .. include:: /reference/minio-cli/minio-mc/mc-ilm.rst
:start-after: start-mc-ilm-desc
:end-before: end-mc-ilm-desc
* - :mc:`mc legalhold`
- .. include:: /reference/minio-cli/minio-mc/mc-legalhold.rst
:start-after: start-mc-legalhold-desc
:end-before: end-mc-legalhold-desc
* - :mc:`mc lock`
- Deprecated since
:mc-release:`RELEASE.2020-09-18T00-13-21Z`. Use :mc:`mc retention`.
* - :mc:`mc ls`
- .. include:: /reference/minio-cli/minio-mc/mc-ls.rst
:start-after: start-mc-ls-desc
:end-before: end-mc-ls-desc
* - :mc:`mc mb`
- .. include:: /reference/minio-cli/minio-mc/mc-mb.rst
:start-after: start-mc-mb-desc
:end-before: end-mc-mb-desc
* - :mc:`mc mirror`
- .. include:: /reference/minio-cli/minio-mc/mc-mirror.rst
:start-after: start-mc-mirror-desc
:end-before: end-mc-mirror-desc
* - :mc:`mc mv`
- .. include:: /reference/minio-cli/minio-mc/mc-mv.rst
:start-after: start-mc-mv-desc
:end-before: end-mc-mv-desc
* - :mc:`mc policy`
- .. include:: /reference/minio-cli/minio-mc/mc-policy.rst
:start-after: start-mc-policy-desc
:end-before: end-mc-policy-desc
* - :mc:`mc rb`
- .. include:: /reference/minio-cli/minio-mc/mc-rb.rst
:start-after: start-mc-rb-desc
:end-before: end-mc-rb-desc
* - :mc:`mc retention`
- .. include:: /reference/minio-cli/minio-mc/mc-retention.rst
:start-after: start-mc-retention-desc
:end-before: end-mc-retention-desc
* - :mc:`mc rm`
- .. include:: /reference/minio-cli/minio-mc/mc-rm.rst
:start-after: start-mc-rm-desc
:end-before: end-mc-rm-desc
* - :mc:`mc share`
- .. include:: /reference/minio-cli/minio-mc/mc-share.rst
:start-after: start-mc-share-desc
:end-before: end-mc-share-desc
* - :mc:`mc sql`
- .. include:: /reference/minio-cli/minio-mc/mc-sql.rst
:start-after: start-mc-sql-desc
:end-before: end-mc-sql-desc
* - :mc:`mc stat`
- .. include:: /reference/minio-cli/minio-mc/mc-stat.rst
:start-after: start-mc-stat-desc
:end-before: end-mc-stat-desc
* - :mc:`mc tag`
- .. include:: /reference/minio-cli/minio-mc/mc-tag.rst
:start-after: start-mc-tag-desc
:end-before: end-mc-tag-desc
* - :mc:`mc tree`
- .. include:: /reference/minio-cli/minio-mc/mc-tree.rst
:start-after: start-mc-tree-desc
:end-before: end-mc-tree-desc
* - :mc:`mc update`
- .. include:: /reference/minio-cli/minio-mc/mc-update.rst
:start-after: start-mc-update-desc
:end-before: end-mc-update-desc
* - :mc:`mc version`
- .. include:: /reference/minio-cli/minio-mc/mc-version.rst
:start-after: start-mc-version-desc
:end-before: end-mc-version-desc
* - :mc:`mc watch`
- .. include:: /reference/minio-cli/minio-mc/mc-watch.rst
:start-after: start-mc-watch-desc
:end-before: end-mc-watch-desc
:mc-cmd:`mc` also includes an administration extension for managing MinIO
deployments. See :mc-cmd:`mc admin` for more complete documentation.
.. _mc-configuration:
Configuration File
------------------
:mc-cmd:`mc` uses a ``JSON`` formatted configuration file used for storing
certain kinds of information, such as the :mc-cmd:`aliases <mc alias>` for
each configured S3-compatible service.
For Linux and OSX, the default configuration file location is
``~/.mc/config.json``.
For Windows, :mc-cmd:`mc` attempts to construct a default file path by trying
specific environment variables. If a variable is unset, :mc-cmd:`mc` moves
to the next variable. If all attempts fail, :mc-cmd:`mc` returns an error.
The following list describes each possible file path location in the order
:mc-cmd:`mc` checks them:
#. ``HOME\.mc\config.json``
#. ``USERPROFILE\.mc\config.json``
#. ``HOMEDRIVE+HOMEPATH\.mc\config.json``
You can use the ``--config-dir``
.. _minio-mc-global-options:
Global Options
--------------
.. program:: mc
All :ref:`commands <minio-mc-commands>` support the following global options:
.. option:: --debug
Enables verbose output to the console.
For example, the following operation adds verbose output to the
:mc:`mc ls` command:
.. code-block:: shell
:class: copyable
mc --debug ls play
.. option:: --config-dir
The path to a ``JSON`` formatted configuration file that
:program:`mc` uses for storing data. See :ref:`mc-configuration` for
more information on how :program:`mc` uses the configuration file.
.. option:: --JSON
Enables `JSON lines <http://jsonlines.org/>`_ formatted output to the
console.
For example, the following operation adds JSON Lines output to the
:mc:`mc ls` command:
.. code-block:: shell
:class: copyable
mc --JSON ls play
.. option:: --no-color
Disables the built-in color theme for console output. Useful for dumb
terminals.
.. option:: --quiet
Suppresses console output.
.. option:: --insecure
Disables TLS/SSL certificate verification. Allows TLS connectivity to
servers with invalid certificates. Exercise caution when using this
option against untrusted S3 hosts.
.. option:: --version
Displays the current version of :mc-cmd:`mc`.
.. toctree::
:titlesonly:
:hidden:
:glob:
/reference/minio-cli/minio-mc/*

181
source/reference/minio-cli/minio-mc/mc-alias.rst
View File

@ -1,181 +0,0 @@
.. _minio-mc-alias:
============
``mc alias``
============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc alias
Description
-----------
.. start-mc-alias-desc
The :mc-cmd:`mc alias` command provides a convenient interface for
managing the list of S3-compatible hosts that :mc-cmd:`mc` can
connect to and run operations against.
:mc-cmd:`mc` commands that operate on S3-compatible services *require*
specifying an alias for that service.
.. end-mc-alias-desc
Using :mc-cmd:`mc alias` to add or remove an S3-compatible host is equivalent
to manually editing entries in the :program:`mc`
:ref:`configuration file <mc-configuration>`.
Required Credentials and Access Control
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:mc-cmd:`mc alias` requires specifying an access key and corresponding secret
key for the S3-compatible host. :program:`mc` functionality is limited based
on the policies associated to the specified credentials. For example,
if the specified credentials do not have read/write access to a specific bucket,
:program:`mc` cannot perform read or write operations on that bucket.
For more information on MinIO Access Control, see
:ref:`minio-access-management`.
For more complete documentation on S3 Access Control, see
:s3-docs:`Amazon S3 Security <security.html>`.
For all other S3-compatible services, defer to the documentation for that
service.
Examples
--------
Add an S3-Compatible Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc alias set` to add an S3-compatible service for use with
:program:`mc`:
.. code-block:: shell
:class: copyable
mc alias set ALIAS HOSTNAME ACCESSKEY SECRETKEY
- Replace :mc-cmd:`~mc alias set ALIAS` with the alias to associate
to the S3-compatible service.
- Replace :mc-cmd:`~mc alias set HOSTNAME` with the hostname or IP address of
the S3-compatible service.
- Replace :mc-cmd:`~mc alias set ACCESSKEY` and
:mc-cmd:`~mc alias set SECRETKEY` with the access and secret key for a user on
the S3-compatible service.
Remove a Configured S3-Compatible Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc alias remove` to remove an S3-compatible alias from the
:program:`mc` configuration:
.. code-block:: shell
:class: copyable
mc alias remove ALIAS
- Replace :mc-cmd:`~mc alias remove ALIAS` with the alias of the S3-compatible
service to remove.
Use :mc-cmd:`mc alias list` to list the currently configured aliases and their
associated S3-compatible service.
List Configured S3-Compatible Services
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc alias list` to list all configured S3-compatible aliases:
.. code-block:: shell
:class: copyable
mc alias list
Syntax
------
.. mc-cmd:: set, s
:fullpath:
Adds a new S3-compatible host to the configuration file. The command
has the following syntax:
.. code-block:: shell
:class: copyable
mc alias set ALIAS HOSTNAME ACCESSKEY SECRETKEY --api [S3v2|S3v4]
:mc-cmd:`mc alias set` supports the following arguments:
.. mc-cmd:: ALIAS
*Required* The name to associate to the S3-compatible service.
The specified string cannot match any existing host aliases. Use
:mc-cmd:`~mc alias list` to view the current host aliases before
adding a new host.
.. mc-cmd:: HOSTNAME
*Required* The URL for the S3-compatible service endpoint.
.. mc-cmd:: ACCESSKEY
*Required* The access key for authenticating to the S3 service. The
``ACCESSKEY`` must correspond to a user or role on the S3 service.
:mc-cmd:`mc` can only perform an operation on the S3 service if
the ``ACCESSKEY`` user or role grants the required permissions.
.. mc-cmd:: SECRETKEY
*Required* The corresponding secret for the specified ``ACCESSKEY``.
.. mc-cmd:: api
:option:
*Optional* The Amazon S3 Signature version to use when connecting to the
S3 service. Supports the following values:
- ``S3v2``
- ``S3v4`` (Default)
.. mc-cmd:: remove, rm
:fullpath:
Removes a host entry from the configuration file. The command has the
following syntax:
.. code-block:: shell
:class: copyable
mc alias remove ALIAS
.. mc-cmd:: ALIAS
*Required* The alias to remove.
Use :mc-cmd:`~mc alias list` to validate the alias and its associated
S3-compatible service before removing it.
.. mc-cmd:: list, ls
:fullpath:
Lists all hosts in the configuration file. The command has the following
syntax:
.. code-block:: shell
:class: copyable
mc alias list

65
source/reference/minio-cli/minio-mc/mc-diff.rst
View File

@ -1,65 +0,0 @@
===========
``mc diff``
===========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
.. mc:: mc diff
Description
-----------
.. start-mc-diff-desc
The :mc:`mc diff` mc computes the differences between two filesystem directories
or S3-compatible buckets. :mc:`mc diff` lists only those objects which are
missing or which differ in size. :mc:`mc diff` does **not** compare the contents
of objects.
.. end-mc-diff-desc
Output Legend
~~~~~~~~~~~~~
:mc:`mc diff` uses the following legend when formatting the diff output:
.. code-block:: none
FIRST < SECOND - object exists only in FIRST
FIRST > SECOND - object exists only in SECOND
FIRST ! SECOND - Newer object exists in FIRST
Examples
--------
.. include:: /includes/play-alias-available.rst
:start-after: play-alias-only
:end-before: end-play-alias-only
.. code-block:: shell
:class: copyable
mc diff play/bucket1 play/bucket2
Syntax
------
:mc:`mc diff` has the following syntax:
.. code-block:: shell
mc diff FIRST SECOND
:mc:`~mc diff` supports the following arguments:
.. mc-cmd:: FIRST
The path to a filesystem directory or S3-compatible bucket.
.. mc-cmd:: SECOND
The path to a filesystem directory or S3-compatible bucket.

132
source/reference/minio-cli/minio-mc/mc-encrypt.rst
View File

@ -1,132 +0,0 @@
==============
``mc encrypt``
==============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc encrypt
Description
-----------
.. start-mc-encrypt-desc
The :mc:`mc encrypt` mc sets, updates, or disables the default bucket
Server-Side Encryption (SSE) mode. MinIO automatically encrypts objects using
the specified SSE mode.
.. end-mc-encrypt-desc
For more information on configuring SSE, see
:ref:`minio-sse`
Behavior
~~~~~~~~
:mc:`mc encrypt` makes no assumptions about the MinIO server's current
encryption state. Specifying default encryption settings which the
server cannot support may result in undesired behavior.
Setting or modifying the default server-side encryption settings does *not*
automatically encrypt or decrypt the existing bucket contents. If the bucket
contents *must* have consistent encryption, use the
:mc:`mc mv` mc with the :mc-cmd-option:`~mc mv encrypt` or
:mc-cmd-option:`~mc mv encrypt-key` arguments to manually modify the
encryption settings or encrypted state of the bucket contents *before*
changing the bucket default.
Syntax
------
.. mc-cmd:: set
:fullpath:
Sets the default encryption settings for the bucket. The command has the
following syntax:
.. code-block:: shell
:class: copyable
mc encrypt set ENCRYPTION [KMSKEY] TARGET
The mc requires the following arguments:
.. mc-cmd:: ENCRYPTION
Specify the server-side encryption type to use as the default SSE mode.
Supports the following values:
- ``sse-kms`` - Encrypt objects using the key specified in
:mc-cmd:`~mc encrypt set KMSKEY`. MinIO
must have access to the specified key on the external KMS to
successfully encrypt or decrypt objects protected using SSE-KMS.
- ``sse-s3`` - Encrypt objects using the key specified to
:envvar:`MINIO_KMS_KES_KEY_NAME`. MinIO must have access to the
specified key on the external KMS to successfully encrypt or decrypt
objects protected using SSE-S3.
.. mc-cmd:: KMSKEY
Specify the KMS Master Key to use for performing SSE object encryption.
Only required if :mc-cmd:`~mc encrypt set ENCRYPTION` is ``sse-kms``.
.. mc-cmd:: TARGET
The full path to the bucket on which to set the default SSE mode. Specify
the :mc-cmd:`~mc alias` of a configured S3 service as the prefix to the
TARGET path. For example:
.. code-block:: shell
mc encrypt set ENCRYPTION [KMSKEY] play/mybucket
.. mc-cmd:: clear
:fullpath:
Removes the default encryption settings for the bucket. The command has
the following syntax:
.. code-block:: shell
mc encrypt clear TARGET
The command requires the following argument:
.. mc-cmd:: TARGET
The full path to the bucket on which to clear the default SSE mode.
Specify the :mc-cmd:`~mc alias` of a configured S3 service as the prefix
to the ``TARGET`` path. For example:
.. code-block:: shell
mc encrypt remove play/mybucket
.. mc-cmd:: info
:fullpath:
Returns the current default bucket encryption settings. The command
has the following syntax:
.. code-block:: shell
mc encrypt info TARGET
The command requires the following argument:
.. mc-cmd:: TARGET
The full path to the bucket on which to return the default SSE mode.
Specify the :mc-cmd:`~mc alias` of a configured S3 service as the prefix
to the ``TARGET`` path. For example:
.. code-block:: shell
mc encrypt remove play/mybucket

301
source/reference/minio-cli/minio-mc/mc-event.rst
View File

@ -1,301 +0,0 @@
============
``mc event``
============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc event
Description
-----------
.. start-mc-event-desc
The :mc:`mc event` command supports adding, removing, and listing
the bucket event notifications.
MinIO automatically sends triggered events to the configured notification
targets. MinIO supports notification targets like AMQP (RabbitMQ), Redis,
ElasticSearch, NATS and PostgreSQL. See
:doc:`MinIO Bucket Notifications </monitoring/bucket-notifications/bucket-notifications>` for more
information.
.. end-mc-event-desc
.. _mc-event-supported-events:
Supported Bucket Events
~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports the following S3 event types:
- :data:`s3:ObjectRemoved:DeleteMarkerCreated`
- :data:`s3:ObjectRemoved:Delete`
- :data:`s3:ObjectCreated:PutRetention`
- :data:`s3:ObjectCreated:PutLegalHold`
- :data:`s3:ObjectCreated:Put`
- :data:`s3:ObjectCreated:Post`
- :data:`s3:ObjectCreated:Copy`
- :data:`s3:ObjectCreated:CompleteMultipartUpload`
- :data:`s3:ObjectAccessed:Head`
- :data:`s3:ObjectAccessed:GetRetention`
- :data:`s3:ObjectAccessed:GetLegalHold`
- :data:`s3:ObjectAccessed:Get`
- :data:`s3:Replication:OperationCompletedReplication`
- :data:`s3:Replication:OperationFailedReplication`
- :data:`s3:Replication:OperationMissedThreshold`
- :data:`s3:Replication:OperationNotTracked`
- :data:`s3:Replication:OperationReplicatedAfterThreshold`
- :data:`s3:ObjectRestore:Post`
- :data:`s3:ObjectRestore:Completed`
- :data:`s3:BucketCreated`
- :data:`s3:BucketRemoved`
For more complete documentation on the listed S3 events, see
:s3-docs:`S3 Supported Event Types
<NotificationHowTo.html#notification-how-to-event-types-and-destinations>`.
Examples
--------
Add New Event Notification to a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc event add` to add a notification event to a bucket:
.. code-block:: shell
:class: copyable
mc event add ALIAS/PATH ARN --event EVENTS
- Replace :mc-cmd:`ALIAS <mc event add TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc event add TARGET>` with the path to the bucket on
the S3-compatible host.
- Replace :mc-cmd:`ARN <mc event add ARN>` with the
:aws-docs:`Amazon Resource Name (ARN)
<general/latest/gr/aws-arns-and-namespaces>` of the notification target.
- Replace :mc-cmd:`EVENTS <mc event add event>` with a comma-separated list of
:ref:`events <mc-event-supported-events>`.
Remove an Event Notification from a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc event remove` to remove a notification event from a bucket:
.. code-block:: shell
:class: copyable
mc event remove ALIAS/PATH ARN --event EVENTS
- Replace :mc-cmd:`ALIAS <mc event add TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc event add TARGET>` with the path to the bucket on
the S3-compatible host.
- Replace :mc-cmd:`ARN <mc event add ARN>` with the
:aws-docs:`Amazon Resource Name (ARN)
<general/latest/gr/aws-arns-and-namespaces>` of the notification target.
- Replace :mc-cmd:`EVENTS <mc event add event>` with a comma-separated list of
:ref:`events <mc-event-supported-events>` to remove.
List Bucket Notification Events
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc event list` to list all configured notification events on a
bucket:
.. code-block:: shell
:class: copyable
mc event list ALIAS/PATH ARN
- Replace :mc-cmd:`ALIAS <mc event add TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc event add TARGET>` with the path to the bucket on
the S3-compatible host.
- Replace :mc-cmd:`ARN <mc event add ARN>` with the
:aws-docs:`Amazon Resource Name (ARN)
<general/latest/gr/aws-arns-and-namespaces>` of the notification target.
Syntax
------
.. mc-cmd:: add
:fullpath:
Adds a new bucket event notification. For supported event types, see
:ref:`mc-event-supported-events`. The command has the following syntax:
.. code-block:: shell
:class: copyable
mc event add TARGET ARN [FLAGS]
.. mc-cmd:: TARGET
*Required* The S3 service :mc:`alias <mc alias>` and bucket to
which the command adds the new event notification. Specify the
:mc-cmd:`alias <mc alias>` of a configured S3 service as the prefix to
the ``TARGET`` path. For example:
.. code-block:: shell
mc event add play/mybucket
.. mc-cmd:: ARN
*Required* The :aws-docs:`Amazon Resource Name (ARN)
<general/latest/gr/aws-arns-and-namespaces>` of the notification target.
The MinIO server outputs an ARN for each configured
notification target at server startup. See
:doc:`/monitoring/bucket-notifications/bucket-notifications` for more
information.
.. mc-cmd:: event
:option:
The event(s) for which MinIO generates bucket notifications.
Specify multiple events using a comma ``,`` delimiter.
See :ref:`mc-event-supported-events` for supported events.
Defaults to ``put,delete, get``.
.. mc-cmd:: prefix
:option:
The bucket prefix in which the specified
:mc-cmd-option:`~mc event add event` can trigger a bucket notification.
For example, given a :mc-cmd:`~mc event add TARGET` of ``play/mybucket``
and a :mc-cmd-option:`~mc event add prefix` of ``photos``, only events in
``play/mybucket/photos`` trigger bucket notifications.
.. mc-cmd:: suffix
:option:
The bucket suffix in which the specified
:mc-cmd-option:`~mc event add event` can trigger a bucket notification.
For example, given a :mc-cmd:`~mc event add TARGET` of ``play/mybucket``
and a :mc-cmd-option:`~mc event add suffix` of ``.jpg``, only events in
``play/mybucket/*.jpg`` trigger bucket notifications.
.. mc-cmd:: remove
:fullpath:
Removes an existing bucket event notification. The command has the
following syntax:
.. code-block:: shell
:class: copyable
mc event remove TARGET ARN [FLAGS]
.. mc-cmd:: TARGET
*Required* The S3 service :mc:`alias <mc alias>` and bucket from
which the command removes the event notification. Specify the
:mc-cmd:`alias <mc alias>` of a configured S3 service as the prefix to
the ``TARGET`` path. For example:
.. code-block:: shell
mc event add play/mybucket
.. mc-cmd:: ARN
*Required* The :aws-docs:`Amazon Resource Name (ARN)
<general/latest/gr/aws-arns-and-namespaces>` of the notification target.
The MinIO server outputs an ARN for each configured
notification target at server startup. See
:doc:`/monitoring/bucket-notifications/bucket-notifications` for more information.
.. mc-cmd:: force
:option:
Removes all events on the :mc-cmd:`~mc event remove TARGET` bucket with
the :mc-cmd-option:`~mc event remove ARN` notification target.
.. mc-cmd:: event
:option:
The event(s) to remove. Specify multiple events using a comma ``,``
delimiter. See :ref:`mc-event-supported-events` for supported events.
Defaults to removing all events on the :mc-cmd:`~mc event remove TARGET`
bucket with the :mc-cmd-option:`~mc event remove ARN` notification target.
.. mc-cmd:: prefix
:option:
The bucket prefix in which the command removes bucket notifications.
For example, given a :mc-cmd:`~mc event remove TARGET` of
``play/mybucket`` and a :mc-cmd-option:`~mc event remove prefix` of
``photos``, the command only removes bucket notifications in
``play/mybucket/photos``.
.. mc-cmd:: suffix
:option:
The bucket suffix in which the command removes bucket notifications.
For example, given a :mc-cmd:`~mc event remove TARGET` of
``play/mybucket`` and a :mc-cmd-option:`~mc event remove suffix` of
``.jpg``, the command only removes bucket notifications in
``play/mybucket/*.jpg``.
.. mc-cmd:: list
:fullpath:
Lists bucket event notifications.
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc event add TARGET ARN [FLAGS]
:mc-cmd:`~mc alias list` supports the following arguments
.. mc-cmd:: TARGET
*Required* The S3 service :mc:`alias <mc alias>` and bucket to
which the command lists event notification. Specify the
:mc-cmd:`alias <mc alias>` of a configured S3 service as the prefix to
the ``TARGET`` path. For example:
.. code-block:: shell
mc event add play/mybucket
.. mc-cmd:: ARN
*Required* The :aws-docs:`Amazon Resource Name (ARN)
<general/latest/gr/aws-arns-and-namespaces>` of the bucket resource.
The MinIO server outputs an ARN for each configured
notification target at server startup. See
:doc:`/monitoring/bucket-notifications/bucket-notifications` for more information.

274
source/reference/minio-cli/minio-mc/mc-find.rst
View File

@ -1,274 +0,0 @@
===========
``mc find``
===========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc find
Description
-----------
.. start-mc-find-desc
The :mc:`mc find` command supports querying for objects on an S3-compatible
host. You can also use the command to search for files on a filesystem.
.. end-mc-find-desc
.. _mc-find-units:
Units of Measurement
~~~~~~~~~~~~~~~~~~~~
The :mc-cmd-option:`mc find smaller` and :mc-cmd-option:`mc find larger` flags
accept the following case-insensitive suffixes to represent the unit of the
specified size value:
.. list-table::
:header-rows: 1
:widths: 20 80
:width: 100%
* - Suffix
- Unit Size
* - ``k``
- KB (Kilobyte, 1000 Bytes)
* - ``m``
- MB (Megabyte, 1000 Kilobytes)
* - ``g``
- GB (Gigabyte, 1000 Megabytes)
* - ``t``
- TB (Terrabyte, 1000 Gigabytes)
* - ``ki``
- KiB (Kibibyte, 1024 Bites)
* - ``mi``
- MiB (Mebibyte, 1024 Kibibytes)
* - ``gi``
- GiB (Gibibyte, 1024 Mebibytes)
* - ``ti``
- TiB (Tebibyte, 1024 Gibibytes)
Omitting the suffix defaults to ``bytes``.
.. _mc-find-substitution-format:
Substitution Format
~~~~~~~~~~~~~~~~~~~
The :mc-cmd-option:`mc find exec` and :mc-cmd-option:`mc find print` commands
support string substitutions with special interpretations for following
keywords.
The following keywords are supported for both filesystem and S3 service targets:
- ``{}`` - Substitutes to full path.
- ``{base}`` - Substitutes to basename of path.
- ``{dir}`` - Substitutes to dirname of the path.
- ``{size}`` - Substitutes to object size of the path.
- ``{time}`` - Substitutes to object modified time of the path.
The following keyword is supported only for S3 service targets:
- ``{url}`` - Substitutes to a shareable URL of the path.
Examples
--------
Find a Specific Object
~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: shell
:class: copyable
mc find ALIAS/PATH --name NAME
- Replace :mc-cmd:`ALIAS <mc find PATH>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc find PATH>` with the path to a bucket on the
S3-compatible host. Omit the path to search from the root of the S3 host.
- Replace :mc-cmd:`NAME <mc find name>` with the object.
Find Objects with File Extention in Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: shell
:class: copyable
mc find ALIAS/PATH --name *.EXTENSION
- Replace :mc-cmd:`ALIAS <mc find PATH>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc find PATH>` with the path to a bucket on the
S3-compatible host.
- Replace :mc-cmd:`EXTENSION <mc find name>` with the file extention of the
object.
Find All Matching Files and Copy To S3 Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc:`mc find` with the :mc-cmd-option:`~mc find exec` option to find
files on a local filesystem and pass them to an :program:`mc` command for
further processing. The following example uses :mc:`mc cp` to copy the
output of :mc:`mc find` to an S3-compatible host.
.. code-block:: shell
:class: copyable
mc find FILEPATH --name "*.EXTENSION" --exec "mc cp {} ALIAS/PATH"
- Replace :mc-cmd:`FILEPATH <mc find PATH>` with the full file path to the
directory to search.
- Replace :mc-cmd:`EXTENSION <mc find name>` with the file extention of the
object.
- Replace :mc-cmd:`ALIAS <mc find PATH>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc find PATH>` with the path to a bucket on the
S3-compatible host.
To continuously watch the specified directory and copy new objects,
include the :mc-cmd-option:`~mc find watch` argument:
.. code-block:: shell
:class: copyable
mc find --watch FILEPATH --name "*.EXTENSION" --exec "mc cp {} ALIAS/PATH"
Syntax
------
:mc:`mc find` has the following syntax:
.. code-block:: shell
:class: copyable
mc find PATH [FLAGS]
:mc:`~mc find` supports the following arguments:
.. mc-cmd:: PATH
*Required*
The full path to search.
For objects on S3-compatible hosts, specify the path to the object as
``ALIAS/PATH``, where:
- ``ALIAS`` is the :mc:`alias <mc alias>` of a configured S3-compatible host,
*and*
- ``PATH`` is the path to the object.
.. code-block:: shell
mc find play/mybucket
For files on a filesystem, specify the full filesystem path to the file
as ``PATH``:
.. code-block:: shell
mc find ~/Documents/
Issuing :mc-cmd:`mc find PATH` with no other arguments returns a list of
*all* objects or files at the specified path, similar to :mc-cmd:`mc ls`.
.. mc-cmd:: exec
:option:
Spawns an external process for each object returned by
:mc:`mc find`. Supports
:ref:`substitution formatting <mc-find-substitution-format>` of the
output.
.. mc-cmd:: ignore
:option:
Exclude objects whose names match the specified wildcard pattern.
.. mc-cmd:: name
:option:
Return objects whose names match the specified wildcard pattern.
.. mc-cmd:: older
:option:
Mirror object(s) older than the specified time limit. Specify a string
in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``
Defaults to ``0`` (all objects).
.. mc-cmd:: newer
:option:
Mirror object(s) newer than the specified number of days. Specify a
string in ``#d#hh#mm#ss`` format. For example:
``--older-than 1d2hh3mm4ss``
.. mc-cmd:: path
:option:
Return the contents of directories whose names match the specified
wildcard pattern.
.. mc-cmd:: print
:option:
Prints results to ``STDOUT``. Supports
:ref:`substitution formatting <mc-find-substitution-format>` of the
output.
.. mc-cmd:: regex
:option:
Returns objects or the contents of directories whose names match the
specified PCRE regex pattern.
.. mc-cmd:: larger
:option:
Match all objects larger than the specified size in
:ref:`units <mc-find-units>`.
.. mc-cmd:: smaller
:option:
Match all objects smaller than the specifized size in
:ref:`units <mc-find-units>`.
.. mc-cmd:: maxdepth
:option:
Limits directory navigation to the specified depth.
.. mc-cmd:: watch
:option:
Continuously monitor the :mc-cmd:`~mc find PATH` and return
any new objects which match the specified criteria.

699
source/reference/minio-cli/minio-mc/mc-ilm.rst
View File

@ -1,699 +0,0 @@
==========
``mc ilm``
==========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc ilm
Description
-----------
.. start-mc-ilm-desc
The :mc:`mc ilm` command manages object lifecycle management
rules on a bucket. See the AWS documentation on
:s3-docs:`Object Lifecycle Management <object-lifecycle-mgmt.html>` for more
information.
.. end-mc-ilm-desc
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 :ref:`minio-lifecycle-management-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-cmd:`mc ilm ls` to review the currently configured object lifecycle
management rules for any potential interactions between expiry and transition
rules.
Examples
--------
Expire Bucket Contents After Number of Days
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc ilm add` with :mc-cmd-option:`~mc ilm add expiry-days` to
expire bucket contents a number of days after object creation:
.. code-block:: shell
:class: copyable
mc ilm add ALIAS/PATH --expiry-days "DAYS"
- Replace :mc-cmd:`ALIAS <mc ilm add TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ilm add TARGET>` with the path to the bucket on the
S3-compatible host.
- Replace :mc-cmd:`DATE <mc ilm add expiry-date>` with the number of days after
which to expire the object. For example, specify ``30d`` to expire the
object 30 days after creation.
List Bucket Lifecycle Management Rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc ilm ls` to list a bucket's lifecycle management rules:
.. code-block:: shell
:class: copyable
mc ilm ls ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc ilm ls TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ilm ls TARGET>` with the path to the bucket on the
S3-compatible host.
Remove a Bucket Lifecycle Management Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc ilm remove` to remove a bucket lifecycle management rule:
.. code-block:: shell
:class: copyable
mc ilm remove --id "RULE" ALIAS/PATH
- Replace :mc-cmd:`RULE <mc ilm remove id>` with the unique name of the lifecycle
management rule.
- Replace :mc-cmd:`ALIAS <mc ilm remove TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ilm remove TARGET>` with the path to the bucket on the
S3-compatible host.
Syntax
------
.. mc-cmd:: ls
:fullpath:
Lists the current lifecycle management rules of the specified bucket. The
subcommand has the following syntax:
.. code-block:: shell
:class: copyable
mc ilm ls TARGET [FLAGS]
The subcommand supports the following arguments:
.. mc-cmd:: TARGET
*Required* The full path to the bucket from which to list existing
lifecycle management rules. Specify the :mc-cmd:`alias <mc alias>`
of a configured S3 service as the prefix to the ``TARGET`` path.
For example:
.. code-block:: shell
mc ilm ls play/mybucket
.. mc-cmd:: expiry
:option:
:mc-cmd:`mc ilm` returns only fields related to lifecycle rule expiration.
.. mc-cmd:: transition
:option:
:mc-cmd:`mc ilm` returns only fields related to lifecycle rule transition.
.. mc-cmd:: minimum
:option:
:mc-cmd:`mc ilm` returns only the following fields:
- ``id``
- ``prefix``
- ``status``
- ``transition set``
- ``expiry set``
.. mc-cmd:: add
:fullpath:
Adds a new bucket lifecycle management rules. The command has
the following syntax:
.. code-block:: shell
:class: copyable
mc ilm add TARGET [FLAGS]
.. mc-cmd:: TARGET
*Required*
The full path to the bucket from which to add the lifecycle
management rule. Specify the :mc-cmd:`alias <mc alias>` of a configured S3
service as the prefix to the ``TARGET`` path.
For example:
.. code-block:: shell
mc ilm add play/mybucket [FLAGS]
.. mc-cmd:: prefix
:option:
The path to the specific subset of the :mc-cmd:`~mc ilm add TARGET` bucket
on which to apply the lifecycle configuration rule. MinIO appends the
:mc-cmd-option:`~mc ilm add prefix` field to the ``TARGET`` path to
construct the full path.
Omit to apply the rule to the entire ``TARGET`` bucket.
.. mc-cmd:: tags
:option:
One or more ampersand ``&``-delimited key-value pairs describing
the object tags to which to apply the lifecycle configuration rule.
This option is mutually exclusive with the following option:
- :mc-cmd-option:`~mc ilm add expired-object-delete-marker`
.. mc-cmd:: expiry-date
:option:
The ISO-8601-formatted calendar date until which MinIO retains an object
after being created. MinIO marks the object for deletion once the
system host datetime passes that calendar date.
Exercise caution when using this option, as its behavior can result in
immediate expiration of uploaded objects. Any objects created *after*
the specified expiration date are automatically eligible for expiration.
Similarly, specifying a calendar date that is *prior* to the current
system host datetime marks all objects covered by the rule for deletion.
Consider immediately removing any ILM rule using this option once the
specified calendar date has passed.
For versioned buckets, the expiry rule applies only to the *current*
object version. Use the
:mc-cmd-option:`~mc ilm add noncurrentversion-expiration-days` option
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 :ref:`minio-lifecycle-management-scanner` for more information.
Mutually exclusive with the following options:
- :mc-cmd-option:`~mc ilm add expiry-days`
- :mc-cmd-option:`~mc ilm add expired-object-delete-marker`
.. mc-cmd:: expiry-days
:option:
The number of days to retain an object after being created. MinIO
marks the object for deletion after the specified number of days pass.
For versioned buckets, the expiry rule applies only to the *current*
object version. Use the
:mc-cmd-option:`~mc ilm add noncurrentversion-expiration-days` option
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 :ref:`minio-lifecycle-management-scanner` for more information.
Mutually exclusive with the following options:
- :mc-cmd-option:`~mc ilm add expiry-date`
- :mc-cmd-option:`~mc ilm add expired-object-delete-marker`
.. mc-cmd:: noncurrentversion-expiration-days
:option:
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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: expired-object-delete-marker
:option:
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:
- :mc-cmd-option:`~mc ilm add tags`
- :mc-cmd-option:`~mc ilm add expiry-date`
- :mc-cmd-option:`~mc ilm add expiry-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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: transition-date
:option:
The ISO-8601-formatted calendar date after which MinIO marks an object as
eligible for transition to the remote tier. MinIO transitions the object
to the configured remote storage tier specified to the
:mc-cmd-option:`~mc ilm add storage-class` once the system host datetime
passes that calendar date.
Exercise caution when using this option, as its behavior can result in
immediate transition of uploaded objects. Any objects created *after*
the specified transition date are automatically eligible for transition.
Similarly, specifying a calendar date that is *prior* to the current
system host datetime marks all objects covered by the rule for transition.
Consider immediately removing any ILM rule using this option once the
specified calendar date has passed.
For versioned buckets, the transition rule applies only to the *current*
object version. Use the
:mc-cmd-option:`~mc ilm add noncurrentversion-transition-days` option
to apply transition behavior to noncurrent object versions.
Requires specifying :mc-cmd-option:`~mc ilm add storage-class`.
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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: transition-days
:option:
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 storage tier specified to the
:mc-cmd-option:`~mc ilm add storage-class`.
For versioned buckets, the transition rule applies only to the *current*
object version. Use the
:mc-cmd-option:`~mc ilm add noncurrentversion-transition-days` option
to apply transition behavior to noncurrent object versions.
Requires specifying :mc-cmd-option:`~mc ilm add storage-class`.
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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: noncurrentversion-transition-days
:option:
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 storage tier specified to the
:mc-cmd-option:`~mc ilm add storage-class` once the system host datetime
passes that calendar date.
This option has no effect on non-versioned buckets. Requires specifying
:mc-cmd-option:`~mc ilm add noncurrentversion-transition-storage-class`.
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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: noncurrentversion-transition-storage-class
:option:
The remote storage tier to which MinIO
:ref:`transitions noncurrent objects versions
<minio-lifecycle-management-tiering>`.
Specify a remote storage tier created by :mc-cmd:`mc admin tier`.
.. mc-cmd:: storage-class
:option:
The remote storage tier to which MinIO
:ref:`transition objects <minio-lifecycle-management-tiering>`.
Specify a remote storage tier created by :mc-cmd:`mc admin tier`.
.. mc-cmd:: disable
:option:
Disables the rule.
To enable a disabled rule, specify ``--disable=false``
.. mc-cmd:: edit
:fullpath:
Edits an existing lifecycle management rule in the bucket. The command
has the following syntax:
.. code-block:: shell
:class: copyable
mc ilm edit --id "RULE_ID" TARGET [FLAGS]
The command supports the following arguments:
.. mc-cmd:: TARGET
*Required*
The full path to the bucket from which to modify the
specified lifecycle management rule. Specify the :mc-cmd:`alias
<mc alias>` of a configured S3 service as the prefix to the
``TARGET`` path.
For example:
.. code-block:: shell
mc ilm edit --id "RULE_ID" play/mybucket [FLAGS]
.. mc-cmd:: id
:option:
*Required*
The unique ID of the rule. Use :mc-cmd:`mc ilm ls` to list bucket rules
and retrieve the ``id`` for the rule you want to modify.
.. mc-cmd:: tags
:option:
One or more ampersand ``&``-delimited key-value pairs describing
the object tags to which to apply the lifecycle configuration rule.
This option is mutually exclusive with the following option:
- :mc-cmd-option:`~mc ilm edit expired-object-delete-marker`
.. mc-cmd:: expiry-date
:option:
The ISO-8601-formatted calendar date until which MinIO retains an object
after being created. MinIO marks the object for deletion once the
system host datetime passes that calendar date.
Specifying a calendar date that is *prior* to the current system host
datetime marks all objects covered by the rule for deletion.
For versioned buckets, the expiry rule applies only to the *current*
object version. Use the
:mc-cmd-option:`~mc ilm edit noncurrentversion-expiration-days` option
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 :ref:`minio-lifecycle-management-scanner` for more information.
Mutually exclusive with the following options:
- :mc-cmd-option:`~mc ilm edit expiry-days`
- :mc-cmd-option:`~mc ilm edit expired-object-delete-marker`
.. mc-cmd:: expiry-days
:option:
The number of days to retain an object after being created. MinIO
marks the object for deletion after the specified number of days pass.
Exercise caution when using this option, as its behavior can result in
immediate expiration of uploaded objects. Any objects created *after*
the specified expiration date are automatically eligible for expiration.
Similarly, specifying a calendar date that is *prior* to the current
system host datetime marks all objects covered by the rule for deletion.
Consider immediately removing any ILM rule using this option once the
specified calendar date has passed.
For versioned buckets, the expiry rule applies only to the *current*
object version. Use the
:mc-cmd-option:`~mc ilm edit noncurrentversion-expiration-days` option
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 :ref:`minio-lifecycle-management-scanner` for more information.
Mutually exclusive with the following options:
- :mc-cmd-option:`~mc ilm edit expiry-date`
- :mc-cmd-option:`~mc ilm edit expired-object-delete-marker`
.. mc-cmd:: noncurrentversion-expiration-days
:option:
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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: expired-object-delete-marker
:option:
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:
- :mc-cmd-option:`~mc ilm edit tags`
- :mc-cmd-option:`~mc ilm edit expiry-date`
- :mc-cmd-option:`~mc ilm edit expiry-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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: transition-date
:option:
The ISO-8601-formatted calendar date after which MinIO marks an object as
eligible for transition to the remote tier. MinIO transitions the object
to the configured remote storage tier specified to the
:mc-cmd-option:`~mc ilm edit storage-class` once the system host datetime
passes that calendar date.
Exercise caution when using this option, as its behavior can result in
immediate transition of uploaded objects. Any objects created *after*
the specified transition date are automatically eligible for transition.
Similarly, specifying a calendar date that is *prior* to the current
system host datetime marks all objects covered by the rule for transition.
Consider immediately removing any ILM rule using this option once the
specified calendar date has passed.
For versioned buckets, the transition rule applies only to the *current*
object version. Use the
:mc-cmd-option:`~mc ilm edit noncurrentversion-transition-days` option
to apply transition behavior to noncurrent object versions.
Requires specifying :mc-cmd-option:`~mc ilm edit storage-class`.
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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: transition-days
:option:
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 storage tier specified to the
:mc-cmd-option:`~mc ilm edit storage-class`.
For versioned buckets, the transition rule applies only to the *current*
object version. Use the
:mc-cmd-option:`~mc ilm edit noncurrentversion-transition-days` option
to apply transition behavior to noncurrent object versions.
Requires specifying :mc-cmd-option:`~mc ilm edit storage-class`.
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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: noncurrentversion-transition-days
:option:
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 storage tier specified to the
:mc-cmd-option:`~mc ilm edit storage-class` once the system host datetime
passes that calendar date.
This option has no effect on non-versioned buckets. Requires specifying
:mc-cmd-option:`~mc ilm edit noncurrentversion-transition-storage-class`.
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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: noncurrentversion-transition-storage-class
:option:
The remote storage tier to which MinIO
:ref:`transitions noncurrent objects versions
<minio-lifecycle-management-tiering>`.
Specify a remote storage tier created by :mc-cmd:`mc admin tier`.
MinIO does *not* automatically migrate objects from the previously
specified remote tier to the new remote tier. MinIO continues to
route requests for objects stored on the old remote tier.
.. mc-cmd:: storage-class
:option:
The remote storage tier to which MinIO
:ref:`transition objects <minio-lifecycle-management-tiering>`.
Specify a remote storage tier created by :mc-cmd:`mc admin tier`.
MinIO does *not* automatically migrate objects from the previously
specified remote tier to the new remote tier. MinIO continues to
route requests for objects stored on the old remote tier.
.. mc-cmd:: disable
:option:
Disables the rule.
.. mc-cmd:: remove
:fullpath:
Removes an existing lifecycle management rule from the bucket. The
command has the following syntax:
.. code-block:: shell
:class: copyable
mc ilm remove [FLAGS] TARGET
The command supports the following arguments:
.. mc-cmd:: TARGET
*Required* The full path to the bucket from which to remove the
specified lifecycle management rule. Specify the :mc-cmd:`alias
<mc alias>` of a configured S3 service as the prefix to the
``TARGET`` path.
For example:
.. code-block:: shell
mc ilm remove [FLAGS] play/mybucket
.. mc-cmd:: id
*Required*
The unique ID of the rule. Use :mc-cmd:`mc ilm ls` to list bucket rules
and retrieve the ``id`` for the rule you want to remove.
Mutually exclusive with :mc-cmd-option:`mc ilm remove all`
.. mc-cmd:: all
*Required* Removes all rules in the bucket. Mutually exclusive with
:mc-cmd-option:`mc ilm remove id`.
Requires including :mc-cmd-option:`~mc ilm remove force`.
.. mc-cmd:: force
Required if specifying :mc-cmd-option:`~mc ilm remove all`.
.. mc-cmd:: export
:fullpath:
Export the JSON-formatted lifecycle configuration to ``STDOUT``. The command
has the following syntax:
.. code-block:: shell
:class: copyable
mc ilm export TARGET
The command supports the following arguments:
.. mc-cmd:: TARGET
*Required* The full path to the bucket from which to export the
configured lifecycle management rules. Specify the
:mc-cmd:`alias <mc alias>` of a configured S3 service as the prefix
to the ``TARGET`` path. For example:
.. code-block:: shell
mc ilm export play/mybucket > play_mybucket_lifecycle_rules.json
.. mc-cmd:: import
:fullpath:
Import a JSON-formatted lifecycle configuration from ``STDIN``. The command
has the following syntax:
.. code-block:: shell
:class: copyable
mc ilm import TARGET
The command supports the following arguments:
.. mc-cmd:: TARGET
*Required* The full path to the bucket from which to apply the imported
lifecycle management rules. Specify the :mc-cmd:`alias <mc alias>` of a
configured S3 service as the prefix to the ``TARGET`` path. For example:
.. code-block:: shell
mc ilm import play/mybucket < play_mybucket_lifecycle_rules.json

253
source/reference/minio-cli/minio-mc/mc-legalhold.rst
View File

@ -1,253 +0,0 @@
================
``mc legalhold``
================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc legalhold
Description
-----------
.. start-mc-legalhold-desc
The :mc:`mc legalhold` command enables or disables object legal hold.
Enabling legal hold on an object prevents any modification or deletion
of the object and is equivalent to setting Write-Once Read-Only (WORM)
mode on the object.
.. end-mc-legalhold-desc
.. important::
:mc:`mc legalhold` *requires* that the specified bucket has object locking
enabled. You can **only** enable object locking at bucket creation.
See :mc-cmd-option:`mc mb with-lock` for documentation on creating
buckets with object locking enabled.
Examples
--------
Enable Legal Hold On Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc legalhold set` to enable legal hold on objects:
.. code-block:: shell
:class: copyable
mc legalhold set [--recursive] ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc legalhold set TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc legalhold set TARGET>` with the path to the bucket
or object on the S3-compatible host. If specifying the path to a bucket,
include the :mc-cmd-option:`~mc legalhold set recursive` option.
Remove Legal Hold From Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc legalhold clear` to remove legal hold on objects:
.. code-block:: shell
:class: copyable
mc legalhold clear [--recursive] ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc legalhold clear TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc legalhold clear TARGET>` with the path to the bucket
or object on the S3-compatible host. If specifying the path to a bucket,
include the :mc-cmd-option:`~mc legalhold clear recursive` option.
Retrieve the Legal Hold Status Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc legalhold info` to retrieve the legal hold status of an object.
Include :mc-cmd-option:`~mc legalhold info recursive` to return the legal hold
status of the contents of a bucket:
.. code-block:: shell
:class: copyable
mc legalhold clear [--recursive] ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc legalhold clear TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc legalhold clear TARGET>` with the path to the object
or bucket on the S3-compatible host. If specifying the path to a bucket,
include the :mc-cmd-option:`~mc legalhold info recursive` option.
Syntax
------
.. replacements for mc legalhold set
.. |command| replace:: :mc-cmd:`mc legalhold set`
.. |rewind| replace:: :mc-cmd-option:`~mc legalhold set rewind`
.. |versionid| replace:: :mc-cmd-option:`~mc legalhold set version-id`
.. |alias| replace:: :mc-cmd-option:`~mc legalhold set TARGET`
.. mc-cmd:: set
:fullpath:
Enables legal hold on an object or object(s).
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc legalhold set [FLAGS] TARGET
The command accepts the following arguments:
.. mc-cmd:: TARGET
*Required*
The full path to the object or bucket on which to enable
the legal hold. Specify the :mc-cmd:`alias <mc alias>` of a configured
S3-compatible service as the prefix to the ``TARGET`` path. For example:
.. code-block:: shell
mc legalhold set play/mybucket/myobject.txt
If you specify a path to a bucket or bucket prefix, you must also
specify :mc-cmd-option:`mc legalhold set recursive`.
.. mc-cmd:: recursive, r
:option:
Applies the legal hold to all objects in the
:mc-cmd:`~mc legalhold set TARGET` bucket or bucket prefix.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
.. replacements for mc legalhold clear
.. |command-2| replace:: :mc-cmd:`mc legalhold clear`
.. |rewind-2| replace:: :mc-cmd-option:`~mc legalhold clear rewind`
.. |versionid-2| replace:: :mc-cmd-option:`~mc legalhold clear version-id`
.. |alias-2| replace:: :mc-cmd-option:`~mc legalhold clear TARGET`
.. mc-cmd:: clear
Removes legal hold on an object or object(s).
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc legalhold clear [FLAGS] TARGET
The command accepts the following arguments:
.. mc-cmd:: TARGET
*Required* The full path to the object or bucket on which to remove
the legal hold. Specify the :mc-cmd:`alias <mc alias>` of a configured
S3-compatible service as the prefix to the ``TARGET`` path. For example:
.. code-block::
mc legalhold set play/mybucket/myobject.txt
If you specify a path to a bucket or bucket prefix, you must also
specify :mc-cmd-option:`mc legalhold set recursive`.
.. mc-cmd:: recursive, r
:option:
Removes the legal hold from all objects in the
:mc-cmd:`~mc legalhold set TARGET` bucket or bucket prefix.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc-2
:end-before: end-rewind-desc-2
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc-2
:end-before: end-version-id-desc-2
.. replacements for mc legalhold info
.. |command-3| replace:: :mc-cmd:`mc legalhold info`
.. |rewind-3| replace:: :mc-cmd-option:`~mc legalhold info rewind`
.. |versionid-3| replace:: :mc-cmd-option:`~mc legalhold info version-id`
.. |alias-3| replace:: :mc-cmd-option:`~mc legalhold info TARGET`
.. mc-cmd:: info
Retrieves the legal hold status of an object or object(s).
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc legalhold info [FLAGS] TARGET
The command accepts the following arguments:
.. mc-cmd:: TARGET
*Required* The full path to the object or bucket on which to retrieve
the legal hold status. Specify the :mc-cmd:`alias <mc alias>` of a configured
S3-compatible service as the prefix to the ``TARGET`` path. For example:
.. code-block::
mc legalhold set play/mybucket/myobject.txt
If you specify a path to a bucket or bucket prefix, you must also
specify :mc-cmd-option:`mc legalhold set recursive`.
.. mc-cmd:: recursive, r
:option:
Retrieves the legal hold from all objects in the
:mc-cmd:`~mc legalhold set TARGET` bucket or bucket prefix.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc-3
:end-before: end-rewind-desc-3
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc-3
:end-before: end-version-id-desc-3

27
source/reference/minio-cli/minio-mc/mc-lock.rst
View File

@ -1,27 +0,0 @@
===========
``mc lock``
===========
.. default-domain:: minio
.. mc:: mc lock
Description
-----------
.. start-mc-lock-desc
The :mc:`mc lock` command sets or gets the bucket default object lock
configuration. Object locking enables Write-Once Read-Many (WORM)
object retention for a configurable period of time.
.. end-mc-lock-desc
.. admonition:: DEPRECATED
:class: important
:mc:`mc lock` was deprecated in :mc-release:`RELEASE.2020-09-18T00-13-21Z`. Use
:mc:`mc retention` to set, retrieve, or clear the bucket default object lock
configuration.
For older versions of :program:`mc`, use ``mc lock --help`` for usage.

160
source/reference/minio-cli/minio-mc/mc-ls.rst
View File

@ -1,160 +0,0 @@
=========
``mc ls``
=========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc ls
Description
-----------
.. start-mc-ls-desc
The :mc:`mc ls` command lists all buckets and objects on the target
S3-compatible service. For targets on a filesystem, :mc:`mc ls` has the same
functionality as the ``ls`` command.
.. end-mc-ls-desc
Examples
--------
List Bucket Contents
~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc ls <mc ls TARGET>` to list the contents of a bucket:
.. code-block:: shell
:class: copyable
mc ls [--recursive] ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc ls TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ls TARGET>` with the path to the bucket on the
S3-compatible host.
If specifying the path to the S3 root (``ALIAS`` only), include the
:mc-cmd-option:`~mc ls recursive` option.
List Object Versions
~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd-option:`mc ls versions` to list all versions of an object:
.. code-block:: shell
:class: copyable
mc ls --versions ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc ls TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ls TARGET>` with the path to the bucket or object on
the S3-compatible host.
.. include:: /includes/facts-versioning.rst
:start-after: start-versioning-admonition
:end-before: end-versioning-admonition
List Bucket Contents at Point in Time
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd-option:`mc ls versions` to list all versions of an object:
.. code-block:: shell
:class: copyable
mc ls --rewind DURATION ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc ls TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ls TARGET>` with the path to the bucket or object on
the S3-compatible host.
- Replace :mc-cmd:`DURATION <mc ls rewind>` with the point-in-time in the past
at which the command returns the object. For example, specify ``30d`` to
return the version of the object 30 days prior to the current date.
.. include:: /includes/facts-versioning.rst
:start-after: start-versioning-admonition
:end-before: end-versioning-admonition
Syntax
------
.. Replacement substitutions
.. |command| replace:: :mc-cmd:`mc ls`
.. |rewind| replace:: :mc-cmd-option:`~mc ls rewind`
.. |versions| replace:: :mc-cmd-option:`~mc ls versions`
.. |alias| replace:: :mc-cmd-option:`~mc ls TARGET`
:mc-cmd:`mc ls` has the following syntax:
.. code-block:: shell
:class: copyable
mc ls [FLAGS] TARGET [TARGET ...]
:mc-cmd:`mc ls` supports the following arguments:
.. mc-cmd:: TARGET
*Required* The full path to one or more locations whose contents the command
lists.
- To list the root contents of an S3-compatible service, specify the
:mc-cmd:`alias <mc alias>` of that service. For example:
``mc ls play``
- To list the contents of a bucket on an S3-compatible service,
specify the :mc-cmd:`alias <mc alias>` of that service as a prefix to
the bucket. For example: ``mc ls play/mybucketname``.
- To list the contents of a directory on a filesystem, specify the path
to that directory. For example: ``mc ls ~/Documents``.
If specifying multiple ``TARGET`` locations, :mc-cmd:`mc ls` collates
the contents of each location sequentially.
.. mc-cmd:: recursive, r
:option:
Recursively lists the contents of each bucket or directory in the
:mc-cmd:`~mc ls TARGET`.
.. mc-cmd:: versions
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-versions-desc
:end-before: end-versions-desc
Use :mc-cmd-option:`~mc ls versions` and
:mc-cmd-option:`~mc ls rewind` together to display on those object
versions which existed at a specific point in time.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
Use :mc-cmd-option:`~mc ls rewind` and
:mc-cmd-option:`~mc ls versions` together to display on those object
versions which existed at a specific point in time.
.. mc-cmd:: incomplete, -I
:option:
Returns any incomplete uploads on the specified :mc-cmd:`~mc ls TARGET`
bucket.

105
source/reference/minio-cli/minio-mc/mc-mb.rst
View File

@ -1,105 +0,0 @@
=========
``mc mb``
=========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc mb
Description
-----------
.. start-mc-mb-desc
The :mc:`mc mb` command creates a new bucket or directory at the
specified path. For targets on an S3-compatible service, :mc:`mc mb`
creates a new bucket. For targets on a filesystem, :mc:`mc mb` has
equivalent functionality to ``mkdir -p``.
.. end-mc-mb-desc
Bucket Limits for Non-MinIO S3 Services
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Certain S3 services may restrict the number of buckets a given user or account
can create. For example, Amazon S3 limits each account to
:s3-docs:`100 buckets <BucketRestrictions.html>`. :mc:`mc mb` may return an
error if the user has reached bucket limits on the target S3 service.
MinIO Object Storage deployments do not place any limits on the number of
buckets each user can create.
Examples
--------
Create Bucket
~~~~~~~~~~~~~
Use :mc:`mc mb` to create a bucket on an S3-compatible host. The
:mc-cmd-option:`~mc mb with-lock` option creates the bucket with locking
enabled:
.. code-block:: shell
:class: copyable
mc mb --with-lock ALIAS/BUCKET
- Replace :mc-cmd:`ALIAS <mc mb TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`BUCKET <mc mb TARGET>` with the bucket to create.
Syntax
------
:mc:`~mc mb` has the following syntax:
.. code-block:: shell
:class: copyable
mc mb [FLAGS] TARGET [TARGET...]
:mc:`~mc mb` supports the following arguments:
.. mc-cmd:: TARGET
*Required* The full path to the bucket or directory to create. If
creating a directory on a filesystem, :mc:`mc mb` creates all required
folders in the specified path similar to ``mkdir -p``.
To create a bucket, specify the :mc-cmd:`alias <mc alias>` of a configured
S3 service as the prefix to the ``TARGET`` path. For example:
.. code-block:: shell
mc mb [FLAGS] play/mybucket
.. mc-cmd:: region
:option:
The region in which to create the specified bucket. Has no effect if the
specified :mc-cmd:`~mc mb TARGET` is a filesystem directory.
.. mc-cmd:: ignore-existing, p
:option:
Directs :mc-cmd:`mc mb` to do nothing if the bucket or directory already
exists.
.. mc-cmd:: with-lock, l
:option:
Enables object locking on the specified bucket. Has no effect if the
specified :mc-cmd:`~mc mb TARGET` is a filesystem directory.
.. important::
You can *only* enable object locking when creating the bucket.
You cannot use features like Bucket Lifecycle Management,
Bucket Object Retention, or Bucket Legal Hold if object locking is
disabled for a bucket.

271
source/reference/minio-cli/minio-mc/mc-policy.rst
View File

@ -1,271 +0,0 @@
=============
``mc policy``
=============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc policy
Description
-----------
.. start-mc-policy-desc
The :mc:`mc policy` command supports setting or removing anonymous
policies to a bucket and its contents using AWS S3
:s3-docs:`JSON policies <using-iam-policies>`. Buckets with anonymous
policies allow public access where clients can perform any action
granted by the policy without.
.. end-mc-policy-desc
You can set or remove policies on individual folders or objects inside of a
bucket for more granular control over anonymous access to a bucket's
contents.
Examples
--------
Get Current Anonymous Policy for Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc policy get` to retrieve the current anonymous policy for a
bucket:
.. code-block:: shell
:class: copyable
mc policy get ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc policy get TARGET>` with the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc policy get TARGET>` with the destination bucket.
Use :mc-cmd:`mc policy get-json` to retrieve the
:s3-docs:`IAM JSON policy document <using-iam-policies>` of a bucket:
.. code-block:: shell
:class: copyable
mc policy get-json ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc policy get-json TARGET>` with the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc policy get-json TARGET>` with the destination
bucket.
Set Anonymous Policy for Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc policy set` to set the anonymous policy for a
bucket:
.. code-block:: shell
:class: copyable
mc policy set POLICY ALIAS/PATH
- Replace :mc-cmd:`POLICY <mc policy set PERMISSION>` with a supported
:mc-cmd:`permission <mc policy set PERMISSION>`.
- Replace :mc-cmd:`ALIAS <mc policy set TARGET>` with the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc policy set TARGET>` with the destination bucket.
Use :mc-cmd:`mc policy set-json` to use a
:s3-docs:`IAM JSON policy document <using-iam-policies>` to set the anonymous
policy for a bucket:
.. code-block:: shell
:class: copyable
mc policy set-json POLICY ALIAS/PATH
- Replace :mc-cmd:`POLICY <mc policy set-json FILE>` with the JSON-formatted
IAM policy document to use for setting the anonymous policy.
- Replace :mc-cmd:`ALIAS <mc policy set-json TARGET>` with the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc policy set-json TARGET>` with the destination
bucket.
Remove Anonymous Policy for Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc policy set` to clear the anonymous policy for a
bucket:
.. code-block:: shell
:class: copyable
mc policy set none ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc policy set TARGET>` with the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc policy set TARGET>` with the destination bucket.
Syntax
------
:mc:`~mc policy` has the following syntax:
.. code-block:: shell
mc policy COMMAND [ARGUMENTS]
:mc:`~mc policy` supports the following commands:
.. mc-cmd:: set
:fullpath:
Adds one of the following built-in policies to the specified
bucket. The command has the following syntax:
.. code-block:: shell
:class: copyable
mc policy set PERMISSION TARGET
The command requires the following arguments:
.. mc-cmd:: PERMISSION
Name of the policy to assign to the specified ``TARGET``
:mc-cmd:`mc policy set PERMISSION` supports the following built-in
policies:
- ``none`` - Disable anonymous access to the ``TARGET``.
- ``download`` - Enable download-only access to the ``TARGET``.
- ``upload`` - Enable upload-only access to the ``TARGET``.
- ``public`` - Enable download and upload access to the ``TARGET``.
.. mc-cmd:: TARGET
The full path to the bucket, folder, or object to which the command
applies the specified :mc-cmd:`~mc policy set PERMISSION`. Specify the
:mc:`alias <mc alias>` of a configured S3 service as the
prefix to the ``TARGET`` path. For example:
.. code-block:: shell
mc set public play/mybucket
.. mc-cmd:: set-json
:fullpath:
Adds an AWS S3 :s3-docs:`JSON policy <using-iam-policies>` to the
specified bucket. The command has the following syntax:
.. code-block:: shell
:class: copyable
mc policy set-json FILE TARGET
The command requires the following arguments:
.. mc-cmd:: FILE
The full path to the S3 policy ``.json`` file which the
command applies to the specified :mc-cmd:`~mc policy set-json TARGET`
.. mc-cmd:: TARGET
The full path to the bucket, folder, or object to which the command applies
the specified :mc-cmd:`~mc policy set-json FILE` S3 policy document.
Specify the :mc:`alias <mc alias>` of a configured S3 service as the
prefix to the ``TARGET`` path. For example:
.. code-block:: shell
mc set public play/mybucket
.. mc-cmd:: get
:fullpath:
Prints the current anonymous policy for the specified bucket, folder,
or object on the console.
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc policy get TARGET
The command requires the following arguments:
.. mc-cmd:: TARGET
The full path to the bucket, folder, or object for which the command
returns the current anonymous policy. Specify the :mc:`alias <mc alias>`
of a configured S3 service as the prefix to the ``TARGET`` path. For
example:
.. code-block:: shell
mc set public play/mybucket
.. mc-cmd:: get-json
:fullpath:
Returns the current anonymous policy for the specified bucket, folder,
or object in ``JSON`` format.
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc policy get-json TARGET
The command requires the following arguments:
.. mc-cmd:: TARGET
The full path to the bucket, folder, or object for which the command
returns the current anonymous policy JSON document. Specify the :mc:`alias
<mc alias>` of a configured S3 service as the prefix to the ``TARGET``
path. For example:
.. code-block:: shell
mc set public play/mybucket
.. mc-cmd:: list
:fullpath:
Prints the anonymous policy for the specified bucket and any folders
or objects with a different anonymous policy from the bucket.
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc policy list TARGET
The command requires the following arguments:
.. mc-cmd:: TARGET
The full path to the bucket, folder, or object for which the command
returns the current anonymous policy JSON document. Specify the :mc:`alias
<mc alias>` of a configured S3 service as the prefix to the ``TARGET``
path. For example:
.. code-block:: shell
mc set public play/mybucket

73
source/reference/minio-cli/minio-mc/mc-rb.rst
View File

@ -1,73 +0,0 @@
=========
``mc rb``
=========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc rb
Description
-----------
.. start-mc-rb-desc
The :mc:`mc rb` command removes a bucket and all its contents on the target
S3-compatible service.
Removing a bucket with :mc:`mc rb` also removes any configurations associated to
that bucket. To remove only the contents of a bucket, use :mc:`mc rm` instead.
.. end-mc-rb-desc
Example
-------
Remove a Bucket
~~~~~~~~~~~~~~~
.. code-block:: shell
:class: copyable
mc rb ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc rb TARGET>` with the :mc-cmd:`alias <mc alias>` of
a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc rb TARGET>` with the path to the bucket to remove.
Syntax
------
:mc:`~mc rb` has the following syntax:
.. code-block:: shell
:class: copyable
mc rb [FLAGS] TARGET [TARGET...]
.. mc-cmd:: TARGET
*REQUIRED*
The full path to the bucket to remove. Specify ``TARGET`` as
``ALIAS/PATH``, where:
- ``ALIAS`` is the :mc:`alias <mc alias>` of a configured S3-compatible
host, *and*
- ``PATH`` is the path to the bucket.
.. mc-cmd:: force
:option:
Allows running :mc:`mc rb` on a bucket with versioning enabled.
.. mc-cmd:: dangerous
:option:
Allows running :mc:`mc rb` when the :mc-cmd:`~mc rb TARGET` specifies the
root (all buckets) on the S3-compatible service.

849
source/reference/minio-cli/minio-mc/mc-replicate.rst
View File

@ -1,849 +0,0 @@
================
``mc replicate``
================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc replicate
Description
-----------
.. start-mc-replicate-desc
The :mc:`mc replicate` command configures
:ref:`Server-Side Bucket Replication <minio-bucket-replication-serverside>`
between MinIO deployments.
.. end-mc-replicate-desc
Create Remote Target Before Configuring Replication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:mc:`mc replicate` depends on the ARN resource returned by
:mc:`mc admin bucket remote`.
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-cmd:`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-cmd:`mc version enable` command to enable versioning on
*both* the source and destination bucket before starting this procedure:
.. code-block:: shell
:class: copyable
mc version enable ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc version enable TARGET>` with the
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc version enable TARGET>` with the bucket on which
to enable versioning.
Required Permissions
~~~~~~~~~~~~~~~~~~~~
MinIO strongly recommends creating users specifically for supporting
bucket replication operations. See
:mc:`mc admin user` and :mc:`mc admin policy` for more complete
documentation on adding users and policies to a MinIO deployment.
.. tab-set::
.. tab-item:: Replication Admin
The following policy provides permissions for configuring and enabling
replication on a deployment.
.. literalinclude:: /extra/examples/ReplicationAdminPolicy.json
:class: copyable
:language: json
- The ``"EnableRemoteBucketConfiguration"`` statement grants permission
for creating a remote target for supporting replication.
- The ``"EnableReplicationRuleConfiguration"`` statement grants permission
for creating replication rules on a bucket. The ``"arn:aws:s3:::*``
resource applies the replication permissions to *any* bucket on the
source deployment. You can restrict the user policy to specific buckets
as-needed.
Use the :mc-cmd:`mc admin policy add` to add this policy to each
deployment acting as a replication source. Use :mc-cmd:`mc admin user add`
to create a user on the deployment and :mc-cmd:`mc admin policy set`
to associate the policy to that new user.
.. tab-item:: Replication Remote User
The following policy provides permissions for enabling synchronization of
replicated data *into* the deployment.
.. literalinclude:: /extra/examples/ReplicationRemoteUserPolicy.json
:class: copyable
:language: json
- The ``"EnableReplicationOnBucket"`` statement grants permission for
a remote target to retrieve bucket-level configuration for supporting
replication operations on *all* buckets in the MinIO deployment. To
restrict the policy to specific buckets, specify those buckets as an
element in the ``Resource`` array similar to
``"arn:aws:s3:::bucketName"``.
- The ``"EnableReplicatingDataIntoBucket"`` statement grants permission
for a remote target to synchronize data into *any* bucket in the MinIO
deployment. To restrict the policy to specific buckets, specify those
buckets as an element in the ``Resource`` array similar to
``"arn:aws:s3:::bucketName/*"``.
Use the :mc-cmd:`mc admin policy add` to add this policy to each
deployment acting as a replication target. Use :mc-cmd:`mc admin user add`
to create a user on the deployment and :mc-cmd:`mc admin policy set`
to associate the policy to that new user.
Replication of Existing Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Starting with :mc:`mc` :minio-git:`RELEASE.2021-06-13T17-48-22Z
<mc/releases/tag/RELEASE.2021-06-13T17-48-22Z>` and :mc:`minio`
:minio-git:`RELEASE.2021-06-07T21-40-51Z
<minio/releases/tag/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
<https://aws.amazon.com/blogs/storage/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-cmd-option:`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-cmd-option:`mc replicate add replicate`. You must specify *all*
desired replication features when editing the replication rule.
See :ref:`minio-replication-behavior-existing-objects` for more complete
documentation on this behavior.
Synchronization of Metadata Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports :ref:`two-way active-active
<minio-bucket-replication-serverside-twoway>` replication configurations, where
MinIO synchronizes new and modified objects between a bucket on two MinIO
deployments. Starting with :mc:`mc` :minio-git:`RELEASE.2021-05-18T03-39-44Z
<mc/releases/tag/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
:ref:`replication status <minio-replication-process>` 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-cmd-option:`mc replicate edit 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
:s3-docs:`Delete Markers <versioning-workflows.html>` *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
:ref:`lifecycle management expiration rules
<minio-lifecycle-management-expiration>`. MinIO only replicates explicit
client-driven delete operations.
MinIO requires explicitly enabling replication of delete operations using the
:mc-cmd-option:`mc replicate add replicate` flag. This procedure includes the
required flags for enabling replication of delete operations and delete markers.
See :ref:`minio-replication-behavior-delete` 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* :ref:`enabling TLS <minio-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).
Examples
--------
See the following tutorials for more complete procedures on configuring
server-side replication with :mc:`mc replicate`:
- :ref:`minio-bucket-replication-serverside-oneway`
Add a New Replication Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc replicate add` to add a new replication rule to a bucket or bucket
prefix. :mc:`mc replicate` depends on the ARN resource returned by
:mc:`mc admin bucket remote`.
.. code-block:: shell
:class: copyable
mc replicate add ALIAS/PATH \
--arn ARN \
--remote-bucket BUCKET \
[--FLAGS]
- Replace :mc-cmd:`ALIAS <mc replicate add SOURCE>` with the
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate add SOURCE>` with the path to the
bucket or bucket prefix on which to add the new rule.
- Replace :mc-cmd:`ARN <mc replicate add arn>` with the ARN of the
remote bucket target created by :mc:`mc admin bucket remote`.
- Replace :mc-cmd:`BUCKET <mc replicate add remote-bucket>` with the name of the
remote bucket target. The specified bucket name *must* match the ``ARN``
bucket.
Include all other optional flags.
Modify an Existing Replication Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc replicate edit` to modify an existing replication rule.
.. code-block:: shell
:class: copyable
mc replicate edit ALIAS/PATH \
--id ID \
[--FLAGS]
- Replace :mc-cmd:`ALIAS <mc replicate edit SOURCE>` with the
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate edit SOURCE>` with the path to the
bucket or bucket prefix on which the rule exists.
- Replace :mc-cmd:`ID <mc replicate edit id>` with the unique identifier for the
rule to modify. Use :mc-cmd:`mc replicate ls` to retrieve the list of
replication rules on the bucket and their corresponding identifiers.
.. important::
MinIO applies replication rules to objects as part of write operations.
Modifying a replication rule has no effect on existing objects in the
bucket. For example, enabling delete marker replication through the
:mc-cmd-option:`~mc replicate edit replicate` option does not automatically
replicate existing delete markers or deleted object versions.
Disable or Enable an Existing Replication Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc replicate edit` with the
:mc-cmd-option:`~mc replicate edit state` flag to disable or enable a
replication rule.
.. code-block:: shell
:class: copyable
mc replicate edit ALIAS/PATH \
--id ID \
--state "disabled"|"enabled"
- Replace :mc-cmd:`ALIAS <mc replicate edit SOURCE>` with the
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate edit SOURCE>` with the path to the
bucket or bucket prefix on which the rule exists.
- Replace :mc-cmd:`ID <mc replicate edit id>` with the unique identifier for the
rule to modify. Use :mc-cmd:`mc replicate ls` to retrieve the list of
replication rules on the bucket and their corresponding identifiers.
- Specify either ``"disabled"`` or ``"enabled"`` to the
:mc-cmd:`~mc replicate edit state` flag to disable or enable the replication
rule.
.. important::
MinIO applies replication rules to objects as part of write operations.
Modifying a replication rule has no effect on existing objects in the
bucket. In context of enabling or disabling a replication rule,
objects written to a bucket with no enabled replication rules are
not automatically replicated if one or more rules are enabled later.
Remove a Replication Rule
~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc replicate rm` to remove an existing replication rule:
.. code-block:: shell
:class: copyable
mc replicate rm ALIAS/PATH --id ID
- Replace :mc-cmd:`ALIAS <mc replicate rm SOURCE>` with the
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate rm SOURCE>` with the path to the
bucket or bucket prefix on which the rule exists.
- Replace :mc-cmd:`ID <mc replicate rm id>` with the unique identifier for the
rule to modify. Use :mc-cmd:`mc replicate ls` to retrieve the list of
replication rules on the bucket and their corresponding identifiers.
.. important::
MinIO applies replication rules to objects as part of write operations.
Deleting a replication rule has no effect on objects replicated as
part of that rule.
Syntax
------
.. mc-cmd:: add
:fullpath:
Adds a new server-side replication configuration rule for a bucket.
Requires specifying the resource returned by
:mc:`mc admin bucket remote`.
:mc-cmd:`mc replicate add` has the following syntax:
.. code-block:: shell
:class: copyable
mc replicate add SOURCE \
--arn ARN \
--remote-bucket DESTINATION \
--replicate OPTIONS \
[FLAGS]
:mc-cmd:`mc replicate add` supports the following arguments:
.. mc-cmd:: SOURCE
*Required*
The full path to the bucket on which to add the bucket
replication configuration. Specify the
:mc:`alias <mc alias>` of a configured MinIO service as the prefix to the
:mc-cmd:`~mc replicate add SOURCE` path. For example:
.. code-block:: shell
mc replicate add play/mybucket
.. mc-cmd:: arn
:option:
*Deprecated in* :mc-release:`RELEASE.2021-09-23T05-44-03Z`.
:mc-cmd-option:`mc replicate add remote-bucket` supersedes all
functionality provided by this option.
.. mc-cmd:: remote-bucket
:option:
*Required*
Specify the ARN for the destination deployment and bucket. You can
retrieve the ARN using :mc-cmd:`mc admin bucket remote`:
- Use the :mc-cmd:`mc admin bucket remote ls` to retrieve a list of
ARNs for the bucket on the destination deployment.
- Use the :mc-cmd:`mc admin bucket remote add` to create a replication ARN
for the bucket on the destination deployment.
The specified ARN bucket *must* match the value specified to
:mc-cmd-option:`~mc replicate add remote-bucket`.
*Added in* :mc-release:`RELEASE.2021-09-23T05-44-03Z`. Requires
MinIO server :minio-release:`RELEASE.2021-09-23T04-46-24Z`.
.. mc-cmd:: replicate
:option:
*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.
.. mc-cmd:: tags
:option:
*Optional*
Specify one or more ampersand ``&`` separated key-value pair tags which
MinIO uses for filtering objects to replicate. For example:
.. code-block:: shell
--tags "TAG1=VALUE&TAG2=VALUE&TAG3=VALUE"
MinIO applies the replication rule to any object whose tag set
contains the specified replication tags.
.. mc-cmd:: id
:option:
*Optional*
Specify a unique ID for the replication rule. MinIO automatically
generates an ID if one is not specified.
.. mc-cmd:: priority
:option:
*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``.
.. mc-cmd:: storage-class
:option:
*Optional*
Specify the MinIO :ref:`storage class <minio-ec-storage-class>` to
apply to replicated objects.
.. mc-cmd:: insecure
:option:
*Optional*
Disables verification of the destination deployment's TLS certificate.
This option may be required if the destination deployment uses a
self-signed certificate *or* a certificate signed by an unknown
Certificate Authority.
.. mc-cmd:: disable
:option:
*Optional*
Creates the replication rule in the "disabled" state. MinIO
does not begin replicating objects using the rule until it
is enabled using :mc-cmd:`mc replicate edit`.
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-cmd-option:`mc replicate edit replicate`. See
:ref:`minio-replication-behavior-existing-objects` for more
information.
.. mc-cmd:: edit
:fullpath:
Modifies an existing server-side replication configuration rule for a bucket.
:mc-cmd:`mc replicate edit` has the following syntax:
.. code-block:: shell
:class: copyable
mc replicate edit SOURCE --id IDENTIFIER [FLAGS]
:mc-cmd:`mc replicate edit` supports the following arguments:
.. mc-cmd:: SOURCE
*Required*
The full path to the bucket on which to edit the bucket
replication configuration. Specify the
:mc:`alias <mc alias>` of a configured MinIO service as the prefix to the
:mc-cmd:`~mc replicate edit SOURCE` path. For example:
.. code-block:: shell
mc replicate edit play/mybucket
.. mc-cmd:: id
:option:
*Required*
Specify the unique ID for a configured replication rule.
.. mc-cmd:: remote-bucket
:option:
*Optional*
Specify the name of the bucket on the destination deployment. The
name *must* match the replication rule ARN. Use
:mc-cmd:`mc replicate ls` to validate the ARN for each configured
replication rule on the bucket.
.. mc-cmd:: replicate
:option:
*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.
- ``replica-metadata-sync`` - Directs MinIO to synchronize metadata-only
changes on a replicated object back to the source. This feature only
effects :ref:`two-way active-active
<minio-bucket-replication-serverside-twoway>` replication
configurations.
Omitting this value directs MinIO to stop replicating metadata-only
changes back to the source.
- ``existing-objects`` - Directs MinIO to replicate objects created
prior to configuring or enabling replication. MinIO by default does
*not* synchronize existing objects to the remote target.
See :ref:`minio-replication-behavior-existing-objects` for more
information.
.. mc-cmd:: tags
:option:
*Optional*
Specify one or more ampersand ``&`` separated key-value pair tags which
MinIO uses for filtering objects to replicate. For example:
.. code-block:: shell
--tags "TAG1=VALUE&TAG2=VALUE&TAG3=VALUE"
MinIO applies the replication rule to any object whose tag set
contains the specified replication tags.
.. mc-cmd:: priority
:option:
*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.
.. mc-cmd:: storage-class
:option:
*Optional*
Specify the MinIO :ref:`storage class <minio-ec-storage-class>` to
apply to replicated objects.
.. mc-cmd:: insecure
:option:
*Optional*
Disables verification of the destination deployment's TLS certificate.
This option may be required if the destination deployment uses a
self-signed certificate *or* a certificate signed by an unknown
Certificate Authority.
.. mc-cmd:: state
:option:
*Optional*
Enables or disables the replication rule. Specify one of the following
values:
- ``"enable"`` - Enables the replication rule.
- ``"disable"`` - Disables the replication rule.
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-cmd-option:`mc replicate edit replicate`. See
:ref:`minio-replication-behavior-existing-objects` for more information.
.. mc-cmd:: ls
:fullpath:
Lists the server-side replication configuration rules for a bucket.
:mc-cmd:`mc replicate ls` has the following syntax:
.. code-block:: shell
:class: copyable
mc replicate ls SOURCE [FLAGS]
:mc-cmd:`mc replicate ls` supports the following arguments:
.. mc-cmd:: SOURCE
*Required*
The full path to the bucket on which to list the
replication configurations. Specify the
:mc:`alias <mc alias>` of a configured MinIO service as the prefix to the
:mc-cmd:`~mc replicate ls SOURCE` path. For example:
.. code-block:: shell
mc replicate ls play/mybucket
.. mc-cmd:: insecure
:option:
*Optional*
Disables verification of the destination deployment's TLS certificate.
This option may be required if the destination deployment uses a
self-signed certificate *or* a certificate signed by an unknown
Certificate Authority.
.. mc-cmd:: status
:option:
*Optional*
Filter replication rules on the bucket based on their status. Specify
one of the following values:
- ``enabled`` - Show only enabled replication rules.
- ``disabled`` - Show only disabled replication rules.
If omitted, :mc-cmd:`mc replicate ls` defaults to showing all replication
rules.
.. mc-cmd:: export
:fullpath:
Exports all server-side replication configuration rules for a bucket as a
JSON document.
:mc-cmd:`mc replicate export` has the following syntax:
.. code-block:: shell
:class: copyable
mc replicate export SOURCE [FLAGS]
:mc-cmd:`mc replicate export` supports the following arguments:
.. mc-cmd:: SOURCE
*Required*
The full path to the bucket for which to export the
replication configurations. Specify the
:mc:`alias <mc alias>` of a configured MinIO service as the prefix to the
:mc-cmd:`~mc replicate add SOURCE` path. For example:
.. code-block:: shell
mc replicate export play/mybucket
.. mc-cmd:: insecure
:option:
*Optional*
Disables verification of the destination deployment's TLS certificate.
This option may be required if the destination deployment uses a
self-signed certificate *or* a certificate signed by an unknown
Certificate Authority.
.. mc-cmd:: import
:fullpath:
Imports JSON-formatted server-side replication rules for a bucket through
``STDIN``.
:mc-cmd:`mc replicate import` has the following syntax:
.. code-block:: shell
:class: copyable
mc replicate import SOURCE [FLAGS]
:mc-cmd:`mc replicate import` also supports input redirection for
specifying the path to the JSON-formatted rules:
.. code-block:: shell
:class: copyable
mc replicate import SOURCE [FLAGS] < /path/to/config
:mc-cmd:`mc replicate import` supports the following arguments:
.. mc-cmd:: SOURCE
*Required*
The full path to the bucket to which to import the
replication configurations. Specify the
:mc:`alias <mc alias>` of a configured MinIO service as the prefix to the
:mc-cmd:`~mc replicate import SOURCE` path. For example:
.. code-block:: shell
mc replicate import play/mybucket
.. mc-cmd:: insecure
:option:
*Optional*
Disables verification of the destination deployment's TLS certificate.
This option may be required if the destination deployment uses a
self-signed certificate *or* a certificate signed by an unknown
Certificate Authority.
.. mc-cmd:: rm
:fullpath:
Removes one or more server-side replication rules on a bucket.
:mc-cmd:`mc replicate rm` has the following syntax:
.. code-block:: shell
:class: copyable
mc replicate rm SOURCE --id ID [FLAGS]
:mc-cmd:`mc replicate rm` supports the following arguments:
.. mc-cmd:: SOURCE
*Required*
The full path to the bucket on which to remove the bucket
replication configuration. Specify the
:mc:`alias <mc alias>` of a configured MinIO service as the prefix to the
:mc-cmd:`~mc replicate rm SOURCE` path. For example:
.. code-block:: shell
mc replicate edit play/mybucket
.. mc-cmd:: id
:option:
*Optional*
Specify the unique ID for a configured replication rule.
.. mc-cmd:: all
:option:
Removes all replication rules on the specified bucket. Requires
specifying the :mc-cmd-option:`~mc replicate rm force` flag.
.. mc-cmd:: force
:option:
*Optional*
Required if specifying :mc-cmd-option:`~mc replicate rm all` .
.. mc-cmd:: resync, reset
:fullpath:
Resynchronizes all objects in the specified bucket to the remote target
bucket. See :ref:`minio-replication-behavior-resync` for
more complete documentation.
:mc-cmd:`mc replicate resync` has the following syntax:
.. code-block:: shell
:class: copyable
mc replicate resync SOURCE [args]
:mc-cmd:`mc replicate resync` supports the following arguments:
.. mc-cmd:: SOURCE
*Required*
The full path to the bucket on which to resync the bucket
replication status. Specify the
:mc:`alias <mc alias>` of a configured MinIO service as the prefix to the
:mc-cmd:`~mc replicate edit SOURCE` path. For example:
.. code-block:: shell
mc replicate resync play/mybucket
.. mc-cmd:: older-than
*Optional*
Specify a duration in days where MinIO only resynchronizes objects
older than the specified duration.

622
source/reference/minio-cli/minio-mc/mc-retention.rst
View File

@ -1,622 +0,0 @@
.. _minio-bucket-locking:
================
``mc retention``
================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc retention
Description
-----------
.. start-mc-retention-desc
The :mc:`mc retention` command configures the :ref:`Write-Once Read-Many (WORM)
locking <minio-object-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.
.. end-mc-retention-desc
To lock an object under :ref:`legal hold <minio-object-locking-legalhold>`,
use :mc:`mc legalhold`.
.. note::
Starting in version :mc-release:`RELEASE.2020-09-18T00-13-21Z`,
:mc:`mc retention` fully replaces :mc:`mc lock` for setting the default
object lock settings for a bucket.
Use :mc-cmd:`mc retention set` with the
:mc-cmd-option:`~mc retention set default` option to set the default
object lock settings for a bucket.
Bucket Must Enable Object Locking
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:mc:`mc retention` *requires* that the specified bucket has object locking
enabled. You can **only** enable object locking at bucket creation. See
:mc-cmd-option:`mc mb with-lock` for documentation on creating buckets with
object locking enabled.
Retention of Object Versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For buckets with :mc:`versioning enabled <mc version>`, :mc:`mc retention` by
default operates on the *latest* version of the target object or object(s).
:mc:`mc retention` includes specific options that when *explicitly* specified
direct the command to operate on either a specific object version *or* all
versions of an object:
.. tab-set::
.. tab-item:: Specific Object Version
To direct :mc:`mc retention` to operate on a specific version of an
object, include the ``--version-id`` argument:
- :mc-cmd-option:`mc retention set version-id`
- :mc-cmd-option:`mc retention clear version-id`
- :mc-cmd-option:`mc retention info version-id`
.. tab-item:: All Object Versions
To direct :mc:`mc retention` to operate on *all* versions of an object,
include the ``--versions`` argument:
- :mc-cmd-option:`mc retention set versions`
- :mc-cmd-option:`mc retention clear versions`
- :mc-cmd-option:`mc retention info versions`
Interaction with Legal Holds
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Locking an object prevents any modification or deletion of that
object, similar to the :mc-cmd:`COMPLIANCE <mc retention set MODE>` 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-cmd:`mc legalhold`.
Examples
--------
Set Default Bucket Retention Settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc retention set` with the
:mc-cmd-option:`~mc retention set recursive` and
:mc-cmd-option:`~mc retention set default` to set the default bucket
retention settings.
.. code-block:: shell
:class: copyable
mc retention set --recursive --default MODE DURATION ALIAS/PATH
- Replace :mc-cmd:`MODE <mc retention set MODE>` with the retention mode to
enable. MinIO supports the AWS S3 retention modes ``governance`` and
``compliance``.
- Replace :mc-cmd:`DURATION <mc retention set VALIDITY>` with the duration which
the object lock should remain in effect. For example, to set a retention
period of 30 days, specify ``30d``.
- Replace :mc-cmd:`ALIAS <mc retention set TARGET>` with the
:mc:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc retention set TARGET>` with the path to the bucket.
.. include:: /includes/facts-locking.rst
:start-after: start-command-requires-locking-desc
:end-before: end-command-requires-locking-desc
Set Object Lock Configuration for Versioned Object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Specific Version
Use :mc-cmd:`mc retention set` with
:mc-cmd-option:`~mc retention set version-id` to apply the retention
settings to a specific object version:
.. code-block:: shell
:class: copyable
mc retention set --version-id VERSION MODE DURATION ALIAS/PATH
- Replace :mc-cmd:`VERSION <mc retention set version-id>` with the version
of the object.
- Replace :mc-cmd:`MODE <mc retention set MODE>` with the retention mode
to enable. MinIO supports the AWS S3 retention modes ``governance`` and
``compliance``.
- Replace :mc-cmd:`DURATION <mc retention set VALIDITY>` with the duration
which the object lock should remain in effect. For example, to set a
retention period of 30 days, specify ``30d``.
- Replace :mc-cmd:`ALIAS <mc retention set TARGET>` with the
:mc:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc retention set TARGET>` with the path to the
object.
.. tab-item:: All Versions
Use :mc-cmd:`mc retention set` with
:mc-cmd-option:`~mc retention set versions` to apply the retention
settings to a specific object version:
.. code-block:: shell
:class: copyable
mc retention set --versions MODE DURATION ALIAS/PATH
- Replace :mc-cmd:`MODE <mc retention set MODE>` with the retention mode
to enable. MinIO supports the AWS S3 retention modes ``governance`` and
``compliance``.
- Replace :mc-cmd:`DURATION <mc retention set VALIDITY>` with the duration
which the object lock should remain in effect. For example, to set a
retention period of 30 days, specify ``30d``.
- Replace :mc-cmd:`ALIAS <mc retention set TARGET>` with the
:mc:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc retention set TARGET>` with the path to the
object.
.. include:: /includes/facts-locking.rst
:start-after: start-command-requires-locking-desc
:end-before: end-command-requires-locking-desc
Retrieve Object Lock Settings for an Object or Object(s)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Specific Object
.. code-block:: shell
:class: copyable
mc retention info ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc retention info TARGET>` with the
:mc:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc retention info TARGET>` with the path to the
object.
.. tab-item:: Multiple Objects
Use :mc-cmd:`mc retention info` with
:mc-cmd-option:`~mc retention info recursive` to retrieve the retention
settings for all objects in a bucket:
.. code-block:: shell
:class: copyable
mc retention info --recursive ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc retention info TARGET>` with the
:mc:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc retention info TARGET>` with the path to the
bucket.
.. include:: /includes/facts-locking.rst
:start-after: start-command-requires-locking-desc
:end-before: end-command-requires-locking-desc
Retrieve Default Object Lock Settings for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc retention info` with
:mc-cmd-option:`~mc retention info default` to retrieve the default
object lock settings for a bucket:
.. code-block:: shell
:class: copyable
mc retention info --default ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc retention info TARGET>` with the
:mc:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc retention info TARGET>` with the path to the
bucket.
.. include:: /includes/facts-locking.rst
:start-after: start-command-requires-locking-desc
:end-before: end-command-requires-locking-desc
Clear Object Lock Settings for an Object or Object(s)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Specific Object
.. code-block:: shell
:class: copyable
mc retention clear ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc retention clear TARGET>` with the
:mc:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc retention clear TARGET>` with the path to the
object.
.. tab-item:: Multiple Objects
Use :mc-cmd:`mc retention clear` with
:mc-cmd-option:`~mc retention clear recursive` to clear the retention
settings from all objects in a bucket:
.. code-block:: shell
:class: copyable
mc retention clear --recursive ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc retention clear TARGET>` with the
:mc:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc retention clear TARGET>` with the path to the
bucket.
.. include:: /includes/facts-locking.rst
:start-after: start-command-requires-locking-desc
:end-before: end-command-requires-locking-desc
Syntax
------
.. replacements for mc retention set
.. |command| replace:: :mc-cmd:`mc retention set`
.. |rewind| replace:: :mc-cmd-option:`~mc retention set rewind`
.. |versionid| replace:: :mc-cmd-option:`~mc retention set version-id`
.. |alias| replace:: :mc-cmd-option:`~mc retention set TARGET`
.. |versions| replace:: :mc-cmd-option:`~mc retention set versions`
.. mc-cmd:: set
:fullpath:
Sets the object lock settings for the specified
:mc-cmd:`~mc retention set TARGET` object.
:mc-cmd:`mc retention set` has the following syntax:
.. code-block:: shell
:class: copyable
mc retention set [FLAGS] MODE VALIDITY TARGET
:mc-cmd:`mc retention set` supports the following arguments:
.. mc-cmd:: MODE
Sets the locking mode for the :mc-cmd:`~mc retention set TARGET`.
Specify one of the following supported values:
- ``governance``
- ``compliance``
See the AWS S3 documentation on :s3-docs:`Object Lock Overview
<object-lock-overview.html>` for more information on the supported
modes.
Requires specifying :mc-cmd:`~mc retention set VALIDITY`.
.. mc-cmd:: VALIDITY
The duration which objects remain in the specified
:mc-cmd:`~mc retention set 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.
.. mc-cmd:: TARGET
*Required*
The full path to the object or objects for which to set object lock
configuration. Specify the :mc-cmd:`alias <mc alias>` of a configured
S3-compatible service as the prefix to the ``TARGET`` bucket path. For
example:
.. code-block:: shell
mc retention play/mybucket/object.txt MODE VALIDITY
- If the ``TARGET`` specifies a bucket or bucket prefix, include
:mc-cmd-option:`~mc retention set recursive` to apply the object lock
settings to the bucket contents.
- If the ``TARGET`` bucket has versioning enabled,
:mc-cmd:`mc retention set`
by default applies to only the latest object version. Use
:mc-cmd-option:`~mc retention set version-id` or
:mc-cmd-option:`~mc retention set versions` to apply the object lock
settings to a specific version or to all versions of the object.
.. mc-cmd:: bypass
:option:
Allows a user with the ``s3:BypassGovernanceRetention`` permission
to modify the object. Requires the ``governance`` retention
:mc-cmd:`~mc retention set MODE`
.. mc-cmd:: recursive, r
:option:
Recursively applies the object lock settings to all objects in the
specified :mc-cmd:`~mc retention set TARGET` path.
Mutually exclusive with :mc-cmd-option:`~mc retention set version-id`.
.. mc-cmd:: default
:option:
Sets the default object lock settings for the bucket specified to
:mc-cmd:`~mc retention set TARGET` using the
:mc-cmd:`~mc retention set MODE` and :mc-cmd:`~mc retention set VALIDITY`.
Any objects created in the bucket inherit the default object lock settings
unless explicitly overriden using :mc-cmd:`mc retention set`.
If specifying :mc-cmd-option:`~mc retention set default`,
:mc-cmd:`mc retention set` ignores all other flags.
Starting in :mc-release:`RELEASE.2020-09-18T00-13-21Z`,
:mc-cmd-option:`mc retention set default` replaces the functionality of
the deprecated :mc-cmd:`mc lock` command.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
Mutually exclusive with any of the following flags:
- :mc-cmd-option:`~mc retention set versions`
- :mc-cmd-option:`~mc retention set rewind`
- :mc-cmd-option:`~mc retention set recursive`
.. mc-cmd:: versions
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-versions-desc
:end-before: end-versions-desc
Use :mc-cmd-option:`~mc retention set versions` and
:mc-cmd-option:`~mc retention set rewind` together to apply the
retention settings to all object versions that existed at a
specific point-in-time.
.. |command-2| replace:: :mc-cmd:`mc retention info`
.. |rewind-2| replace:: :mc-cmd-option:`~mc retention info rewind`
.. |versionid-2| replace:: :mc-cmd-option:`~mc retention info version-id`
.. |versions-2| replace:: :mc-cmd-option:`~mc retention info versions`
.. |alias-2| replace:: :mc-cmd-option:`~mc retention info TARGET`
.. mc-cmd:: info
:fullpath:
Returns the current object lock setting for the specified
:mc-cmd:`~mc retention info TARGET`.
:mc-cmd:`mc retention info` has the following syntax:
.. code-block:: shell
:class: copyable
mc retention info [ARGUMENTS] TARGET
:mc-cmd:`mc retention info` supports the following arguments:
.. mc-cmd:: TARGET
*Required*
The full path to the object for which to retreive
the object lock configuration. Specify the :mc-cmd:`alias <mc alias>` of a
configured S3-compatible service as the prefix to the ``TARGET`` bucket
path. For example:
.. code-block:: shell
mc retention info play/mybucket/object.txt
- If the ``TARGET`` specifies a bucket or bucket prefix, include
:mc-cmd-option:`~mc retention info recursive` to return the object
lock settings for all objects in the bucket or bucket prefix.
- If the ``TARGET`` bucket has versioning enabled,
:mc-cmd:`mc retention info` by default applies to only the latest object
version. Use :mc-cmd-option:`~mc retention info version-id` or
:mc-cmd-option:`~mc retention info versions` to return the object lock
settings for a specific version or for all versions of the object.
.. mc-cmd:: recursive, r
:option:
Recursively returns the object lock settings for all objects in the
specified :mc-cmd:`~mc retention info TARGET` path.
Mutually exclusive with :mc-cmd-option:`~mc retention info version-id`.
.. mc-cmd:: default
:option:
Returns the default object lock settings for the bucket specified to
:mc-cmd:`~mc retention info TARGET`.
If specifying :mc-cmd-option:`~mc retention info default`,
:mc-cmd:`mc retention info` ignores all other flags.
Starting in :mc-release:`RELEASE.2020-09-18T00-13-21Z`,
:mc-cmd-option:`mc retention info default` replaces the functionality of
the deprecated :mc-cmd:`mc lock` command.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc-2
:end-before: end-rewind-desc-2
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc-2
:end-before: end-version-id-desc-2
Mutually exclusive with any of the following flags:
- :mc-cmd-option:`~mc retention info versions`
- :mc-cmd-option:`~mc retention info rewind`
- :mc-cmd-option:`~mc retention info recursive`
.. mc-cmd:: versions
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-versions-desc-2
:end-before: end-versions-desc-2
Use :mc-cmd-option:`~mc retention info versions` and
:mc-cmd-option:`~mc retention info rewind` together to retrieve the
retention settings for all object versions that existed at a
specific point-in-time.
.. |command-3| replace:: :mc-cmd:`mc retention clear`
.. |rewind-3| replace:: :mc-cmd-option:`~mc retention clear rewind`
.. |versionid-3| replace:: :mc-cmd-option:`~mc retention clear version-id`
.. |versions-3| replace:: :mc-cmd-option:`~mc retention clear versions`
.. |alias-3| replace:: :mc-cmd-option:`~mc retention clear TARGET`
.. mc-cmd:: clear
:fullpath:
Clears the object lock setting for the specified ``TARGET``.
:mc-cmd:`mc retention clear` has the following syntax:
.. code-block:: shell
:class: copyable
mc retention clear [ARGUMENTS] TARGET
:mc-cmd:`mc retention clear` supports the following arguments:
.. mc-cmd:: TARGET
*Required* The full path to the object or objects for which to clear
the object lock configuration. Specify the :mc-cmd:`alias <mc alias>` of a
configured S3-compatible service as the prefix to the ``TARGET`` bucket
path. For example:
.. code-block:: shell
mc retention clear play/mybucket/object.txt
- If the ``TARGET`` specifies a bucket or bucket prefix, include
:mc-cmd-option:`~mc retention clear recursive` to clear the object lock
settings to the bucket contents.
- If the ``TARGET`` bucket has versioning enabled,
:mc-cmd:`mc retention clear` by default applies to only the latest
object version. Use :mc-cmd-option:`~mc retention clear version-id` or
:mc-cmd-option:`~mc retention clear versions` to clear the object lock
settings for a specific version or for all versions of the object.
.. mc-cmd:: recursive, r
:option:
Recursively clears the object lock settings for all objects in the
specified :mc-cmd:`~mc retention clear TARGET` path.
Mutually exclusive with :mc-cmd-option:`~mc retention clear version-id`.
.. mc-cmd:: default
:option:
Clears the default object lock settings for the bucket specified to
:mc-cmd:`~mc retention clear TARGET`.
If specifying :mc-cmd-option:`~mc retention clear default`,
:mc-cmd:`mc retention clear` ignores all other flags.
Starting in :mc-release:`RELEASE.2020-09-18T00-13-21Z`,
:mc-cmd-option:`mc retention clear default` replaces the functionality of
the deprecated :mc-cmd:`mc lock` command.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc-3
:end-before: end-rewind-desc-3
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc-3
:end-before: end-version-id-desc-3
Mutually exclusive with any of the following flags:
- :mc-cmd-option:`~mc retention clear versions`
- :mc-cmd-option:`~mc retention clear rewind`
- :mc-cmd-option:`~mc retention clear recursive`
.. mc-cmd:: versions
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-versions-desc-3
:end-before: end-versions-desc-3
Use :mc-cmd-option:`~mc retention clear versions` and
:mc-cmd-option:`~mc retention clear rewind` together to remove the
retention settings from all object versions that existed at a
specific point-in-time.

286
source/reference/minio-cli/minio-mc/mc-rm.rst
View File

@ -1,286 +0,0 @@
=========
``mc rm``
=========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc rm
Description
-----------
.. start-mc-rm-desc
The :mc:`mc rm` command removes objects on a target S3-compatible service.
To completely remove a bucket, use :mc:`mc rb` instead.
.. end-mc-rm-desc
Deleting Bucket Contents
~~~~~~~~~~~~~~~~~~~~~~~~
Using :mc:`mc rm` to remove all contents in a bucket does not delete the bucket
itself. Any configurations associated to the bucket remain in place, such as
:mc-cmd-option:`default object lock settings <mc retention set default>`.
To completely remove a bucket, use :mc:`mc rb` instead of :mc:`mc rm`.
MinIO Trims Empty Prefixes on Object Removal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/common-admonitions.rst
:start-after: start-remove-api-trims-prefixes
:end-before: end-remove-api-trims-prefixes
.. include:: /includes/common-admonitions.rst
:start-after: start-remove-api-trims-prefixes-fs
:end-before: end-remove-api-trims-prefixes-fs
Examples
--------
Remove a Single Object
~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: shell
:class: copyable
mc rm ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc rm TARGET>` with the :mc:`alias <mc alias>` of
a configured S3-compatible service.
- Replace :mc-cmd:`PATH <mc rm TARGET>` with the path to the object.
Recursively Remove a Bucket's Contents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc:`mc rm` with the
:mc-cmd-option:`~mc rm recursive` and :mc-cmd-option:`~mc rm force` options
to recursively remove a bucket's contents.
.. code-block:: shell
:class: copyable
mc rm --recursive --force ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc rm TARGET>` with the :mc:`alias <mc alias>` of
a configured S3-compatible service.
- Replace :mc-cmd:`PATH <mc rm TARGET>` with the path to the bucket.
This operation does *not* remove the bucket. Use :mc:`mc rb` to remove the
bucket along with all contents and associated configurations.
Remove All Incomplete Upload Files for an Object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc:`mc rm` with the :mc-cmd-option:`~mc rm incomplete` option to remove
incomplete upload files for an object.
.. code-block:: shell
:class: copyable
mc rm --recursive --force ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc rm TARGET>` with the :mc:`alias <mc alias>` of
a configured S3-compatible service.
- Replace :mc-cmd:`PATH <mc rm TARGET>` with the path to the object.
Removing incomplete upload files prevents resuming the upload using the
:mc-cmd-option:`mc mv continue` or :mc-cmd-option:`mc cp continue` commands.
Roll Object Back To Previous Version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc:`mc rm` with :mc-cmd-option:`~mc rm versions` and
:mc-cmd-option:`~mc rm newer-than` to
remove all object versions newer than the specified duration of time. This
effectively "rolls back" the object to its state at that time.
.. important::
Removing specific versions of an object is a *destructive* action. You cannot
restore the deleted object versions.
.. code-block:: shell
:class: moveable
mc rm ALIAS/PATH --versions --newer-than DURATION
- Replace :mc-cmd:`ALIAS <mc rm TARGET>` with the :mc:`alias <mc alias>` of
a configured S3-compatible service.
- Replace :mc-cmd:`PATH <mc rm TARGET>` with the path to the object. For
example, ``/mybucket/myobject``.
- Replace :mc-cmd:`DURATION <mc rm newer-than>` with the number of days in the
past from the current host time from which the operation begins removing
versions of the object. For example, to remove all versions of the object
created in the last 30 days, specify ``"30d"``.
Syntax
------
.. |command| replace:: :mc-cmd:`mc rm`
.. |rewind| replace:: :mc-cmd-option:`~mc rm rewind`
.. |versions| replace:: :mc-cmd-option:`~mc rm versions`
.. |versionid| replace:: :mc-cmd-option:`~mc rm version-id`
.. |alias| replace:: :mc-cmd-option:`~mc rm TARGET`
:mc:`mc rm` has the following syntax:
.. code-block:: shell
mc rm [FLAGS] TARGET [TARGET ...]
:mc:`~mc rm` supports the following arguments:
.. mc-cmd:: TARGET
**REQUIRED**
The full path to object to remove.
Specify the :mc:`alias <mc alias>` of a configured S3 service as the
prefix to the :mc-cmd-option:`~mc rm TARGET` path.
For example:
.. code-block:: shell
mc rm play/mybucket/object.txt play/mybucket/otherobject.txt
If specifying the path to a bucket or bucket prefix, you **must** also
specify the :mc-cmd-option:`~mc rm recursive` and
:mc-cmd-option:`~mc rm force` arguments. For example:
.. code-block:: shell
mc rm --recursive --force play/mybucket/
mc rm --recursive --force play/mybucket/myprefix
.. mc-cmd:: recursive, r
:option:
Recursively remove the contents of each :mc-cmd-option:`~mc rm TARGET`
bucket or bucket prefix.
If specifying :mc-cmd-option:`~mc rm recursive`, you **must** also
specify :mc-cmd-option:`~mc rm force`.
Mutually exclusive with :mc-cmd-option:`mc rm version-id`
.. mc-cmd:: force
:option:
Allows running :mc:`mc rm` with any of the following arguments:
- :mc-cmd-option:`~mc rm recursive`
- :mc-cmd-option:`~mc rm versions`
- :mc-cmd-option:`~mc rm stdin`
.. mc-cmd:: dangerous
:option:
Allows running :mc:`mc rm` when the :mc-cmd:`~mc rm TARGET` specifies the
root (all buckets) on the S3-compatible service.
.. mc-cmd:: versions
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-versions-desc
:end-before: end-versions-desc
Use :mc-cmd-option:`~mc rm versions` and
:mc-cmd-option:`~mc rm rewind` together to remove all object
versions which existed at a specific point in time.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
Mutually exclusive with any of the following flags:
- :mc-cmd-option:`~mc rm versions`
- :mc-cmd-option:`~mc rm rewind`
- :mc-cmd-option:`~mc rm recursive`
.. mc-cmd:: older-than
:option:
Remove object(s) older than the specified time limit. Specify a string
in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``.
Defaults to ``0`` (all objects).
.. mc-cmd:: newer-than
:option:
Remove object(s) newer than the specified number of days. Specify a
string in ``#d#hh#mm#ss`` format. For example:
``--newer-than 1d2hh3mm4ss``
Defaults to ``0`` (all objects).
.. mc-cmd:: incomplete, I
:option:
Remove incomplete uploads for the specified object.
If any :mc-cmd-option:`~mc rm TARGET` specifies a bucket,
you **must** also specify :mc-cmd-option:`~mc rm recursive`
and :mc-cmd-option:`~mc rm force`.
.. mc-cmd:: fake
:option:
Perform a fake remove operation. Use this operation to perform
validate that the :mc:`mc rm` operation will only
remove the desired objects or buckets.
.. mc-cmd:: stdin
:option:
Read object names or buckets from ``STDIN``.
.. mc-cmd:: encrypt-key
:option:
The encryption key to use for performing Server-Side Encryption with Client
Keys (SSE-C). Specify comma seperated key-value pairs as ``KEY=VALUE,...``.
- For ``KEY``, specify the S3-compatible service
:mc-cmd:`alias <mc alias>` and full path to the bucket, including any
bucket prefixes. Separate the alias and bucket path with a forward slash
``\``. For example, ``play/mybucket``
- For ``VALUE``, specify the data key to use for encryption object(s) in
the bucket or bucket prefix specified to ``KEY``.
:mc-cmd-option:`~mc rm encrypt-key` can use the ``MC_ENCRYPT_KEY``
environment variable for populating the list of encryption key-value
pairs as an alternative to specifying them on the command line.

286
source/reference/minio-cli/minio-mc/mc-share.rst
View File

@ -1,286 +0,0 @@
============
``mc share``
============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc share
Description
-----------
.. start-mc-share-desc
The :mc:`mc share` command generates temporary URLs with integrated
access credentials for uploading or downloading objects to an S3-compatible
host. The temporary URL expires after a configurable time limit.
.. end-mc-share-desc
For more information on shareable object URLs, see the Amazon S3
documentation on :aws-docs:`Pre-Signed URLs
<AmazonS3/latest/dev/ShareObjectPreSignedURL.html>`.
Examples
--------
Generate a CURL GET Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Get Specific Object
Use :mc-cmd:`mc share download` to generate a URL that supports
``GET`` requests for an object:
.. code-block:: shell
:class: copyable
mc share download --expire DURATION ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc share download TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc share download TARGET>` with the path to the
object on the S3-compatible host.
- Replace :mc-cmd:`DURATION <mc share download expire>` with the duration
after which the URL expires. For example, to set a 30 day expiry,
specify ``30d``.
.. tab-item:: Get Object(s) in a Bucket
Use :mc-cmd:`mc share download` with the
:mc-cmd-option:`~mc share download recursive` option to generate a URL for
each object in a bucket. Each URL supports ``GET`` requests for its
associated object:
.. code-block:: shell
:class: copyable
mc share download --recursive --expire DURATION ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc share download TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc share download TARGET>` with the path to the
bucket or bucket prefix on the S3-compatible host.
- Replace :mc-cmd:`DURATION <mc share download expire>` with the duration
after which the URL expires. For example, to set a 30 day expiry,
specify ``30d``.
Generate a CURL POST Command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Upload to Object
Use :mc-cmd:`mc share upload` to generate a URL that supports
``POST`` requests for uploading a file to a specific object location
on an S3-compatible host:
.. code-block:: shell
:class: copyable
mc share upload --expire DURATION ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc share upload TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc share upload TARGET>` with the path to the
object on the S3-compatible host.
- Replace :mc-cmd:`DURATION <mc share upload expire>` with the duration
after which the URL expires. For example, to set a 30 day expiry,
specify ``30d``.
.. tab-item:: Upload File(s) to Bucket
Use :mc-cmd:`mc share upload` with the
:mc-cmd-option:`~mc share upload recursive` option to generate a URL that
supports ``POST`` requests for uploading files to a bucket on an
S3-compatible host:
.. code-block:: shell
:class: copyable
mc share upload --recursive --expire DURATION ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc share upload TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc share upload TARGET>` with the path to the
bucket or bucket prefix on the S3-compatible host.
- Replace :mc-cmd:`DURATION <mc share upload expire>` with the duration
after which the URL expires. For example, to set a 30 day expiry,
specify ``30d``.
The command returns a CURL command for uploading an object to the
specified bucket prefix.
- Replace the ``<FILE>`` string in the returned CURL command with the path
to the file to upload.
- Replace the ``<NAME>`` string in the returned CURL command with the name
of the file in the bucket.
You can use a shell script loop to recursively upload the contents of a
filesystem directory to the S3-compatible service:
.. code-block:: shell
#!/bin/sh
for file in ~/Documents/photos/
do
curl https://play.min.io/mybucket/ \
-F policy=AAAAA -F x-amz-algorithm=AWS4-HMAC-SHA256 \
-F x-amz-credential=AAAA/us-east-1/s3/aws4_request \
-F x-amz-date=20200812T202556Z \
-F x-amz-signature=AAAA \
-F bucket=rkbucket -F key=mydata/${file} -F file=@${file}
done
Defer to the documented best practices for your preferred scripting language
for iterating through files in a directory.
Syntax
------
.. |command| replace:: :mc-cmd:`mc share download`
.. |versionid| replace:: :mc-cmd-option:`~mc share download version-id`
.. |alias| replace:: :mc-cmd-option:`~mc share download TARGET`
.. mc-cmd:: download
:fullpath:
Generates a URL for using an HTTP GET request to retrieve the
object(s).
:mc-cmd:`~mc share download` has the following syntax:
.. code-block:: shell
mc share download [FLAGS] TARGET [TARGET ...]
:mc-cmd:`~mc share download` supports the following arguments:
.. mc-cmd:: TARGET
The full path to the object for which :mc:`mc share download` generates a
URL.
If any ``TARGET`` specifies a path to a bucket, :mc:`mc share` *must*
include the :mc-cmd-option:`mc share download recursive` argument.
.. mc-cmd:: recursive, r
:option:
Recursively generate URLs for all objects in a
:mc-cmd:`mc share download TARGET` bucket or bucket prefix.
Required if any ``TARGET`` specifies a path to a bucket or bucket prefix.
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
.. mc-cmd:: expire, E
:option:
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).
.. mc-cmd:: upload
Generates a ``CURL`` command for uploading object(s) using ``HTTP POST``.
:mc-cmd:`~mc share upload` has the following syntax:
.. code-block:: shell
mc share upload [FLAGS] TARGET [TARGET ...]
:mc-cmd:`~mc share upload` supports the following arguments:
.. mc-cmd:: TARGET
The full path to the object for which :mc:`mc share upload` generates a
URL.
If the ``TARGET`` specifies a single object, :mc-cmd:`mc share upload`
names the uploaded object based on the name specified to ``TARGET``.
If the ``TARGET`` specifies a path to a bucket or bucket prefix,
:mc-cmd:`mc share upload` *must* include the
:mc-cmd-option:`~mc share upload recursive` argument.
.. mc-cmd:: recursive, r
:option:
Modifies the CURL URL to support uploading objects to a bucket or bucket
prefix. Required if any ``TARGET`` specifies a path to a bucket or bucket
prefix. The modified CURL output resembles the following:
.. code-block:: shell
curl ... -F key=TARGET/<NAME> -F file=@<FILE>
Replace ``<FILE>`` with the path to the file to upload.
Replace ``<NAME>`` with the file once uploaded.
.. mc-cmd:: expire, E
:option:
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).
.. mc-cmd:: list
List all unexpired upload or download URLs generated by
:mc-cmd:`mc share download` and :mc-cmd:`mc share upload`.
:mc-cmd:`~mc share list` has the following syntax:
.. code-block:: shell
mc share list SUBCOMMAND
:mc-cmd:`~mc share download` supports the following subcommands:
.. mc-cmd:: upload
List all unexpired URLs generated by :mc-cmd:`mc share upload`.
.. mc-cmd:: download
List all unexpired URLs generated by :mc-cmd:`mc share download`.

108
source/reference/minio-cli/minio-mc/mc-stat.rst
View File

@ -1,108 +0,0 @@
===========
``mc stat``
===========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc stat
Description
-----------
.. start-mc-stat-desc
The :mc:`mc stat` command displays information on objects contained in the
specified S3-compatible service bucket. :mc:`mc stat` has similar functionality
as the ``stat`` command when used on a filesystem path.
.. end-mc-stat-desc
Examples
--------
.. tab-set::
.. tab-item:: Single Object
.. code-block:: shell
:class: copyable
mc stat ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc stat TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc stat TARGET>` with the path to the bucket
or object on the S3-compatible host.
.. tab-item:: Object(s) in Bucket
Use :mc:`mc stat` with the :mc-cmd-option:`~mc stat recursive` option
to apply the operation to all objects in the bucket:
.. code-block:: shell
:class: copyable
mc stat --recursive ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc stat TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc stat TARGET>` with the path to the bucket
or object on the S3-compatible host.
Syntax
------
:mc:`~mc stat` has the following syntax:
.. code-block:: shell
:class: copyable
mc stat [FLAGS] TARGET
:mc:`~mc stat` supports the following arguments:
.. mc-cmd:: TARGET
The full path to an object or file.
For objects on an S3-compatible service, specify the :mc:`alias <mc alias>`
of a configured S3 service as the prefix to the :mc-cmd:`~mc stat TARGET`
path. For example:
.. code-block:: shell
mc stat [FLAGS] play/mybucket
If you specify a directory or bucket, you must also specify
:mc-cmd-option:`mc stat recursive` to recursively apply the command to
the contents of that directory or bucket.
.. mc-cmd:: recursive, r
:option:
Recursively :mc:`mc stat` the contents of
:mc-cmd:`~mc stat TARGET`.
.. mc-cmd:: encrypt-key
:option:
Encrypt or decrypt objects using server-side encryption with
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc stat encrypt-key` in double quotes ``"``.
:mc-cmd-option:`~mc stat encrypt-key` can use the ``MC_ENCRYPT_KEY``
environment variable for retrieving a list of encryption key-value pairs
as an alternative to specifying them on the command line.

253
source/reference/minio-cli/minio-mc/mc-tag.rst
View File

@ -1,253 +0,0 @@
==========
``mc tag``
==========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc tag
Description
-----------
.. start-mc-tag-desc
The :mc:`mc tag` command adds, removes, and lists the tags associated to a
bucket or object.
.. end-mc-tag-desc.
Examples
--------
Apply Tags to a Bucket or Object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc tag set` to apply tags to a bucket or object:
.. code-block:: shell
:class: copyable
mc tag set ALIAS/PATH "TAGS"
- Replace :mc-cmd:`ALIAS <mc tag set TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc tag set TARGET>` with the path to the bucket
or object on the S3-compatible host.
- Replace :mc-cmd:`TAGS <mc tag set TAGS>` with one or more comma-separated
key-value pairs for each tag and its corresponding value.
Remove Tags from a Bucket or Object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc tag remove` to remove all tags from a bucket or object:
.. code-block:: shell
:class: copyable
mc tag remove ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc tag remove TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc tag remove TARGET>` with the path to the bucket
or object on the S3-compatible host.
List Tags for a Bucket or Object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc tag list` to retrieve all tags for a bucket or object:
.. code-block:: shell
:class: copyable
mc tag list ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc tag list TARGET>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc tag list TARGET>` with the path to the bucket
or object on the S3-compatible host.
Syntax
------
.. |command| replace:: :mc-cmd:`mc tag set`
.. |rewind| replace:: :mc-cmd-option:`~mc tag set rewind`
.. |versions| replace:: :mc-cmd-option:`~mc tag set versions`
.. |versionid| replace:: :mc-cmd-option:`~mc tag set version-id`
.. |alias| replace:: :mc-cmd-option:`~mc tag set TARGET`
.. mc-cmd:: set
:fullpath:
Sets the tags for a bucket or object. :mc-cmd:`mc tag set`
overwrites any existing tags on the bucket or object.
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc tag set [FLAGS] TARGET "TAG1=VALUE1,[TAG2=VALUE2]"
The command accepts the following arguments:
.. mc-cmd:: TARGET
**Required** The full path to the bucket or object to which to set the
:mc-cmd-option:`~mc tag set TAGS`. Specify the :mc-cmd:`alias <mc alias>`
of a configured S3-compatible service as the prefix to the
:mc-cmd:`~mc tag set TARGET` path. For example:
.. code-block:: shell
mc version set play/mybucket
.. mc-cmd:: TAGS
One or more comma-separated key-value pairs, where each pair describes a
single tag.
.. mc-cmd:: versions
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-versions-desc
:end-before: end-versions-desc
Use :mc-cmd-option:`~mc tag set versions` and
:mc-cmd-option:`~mc tag set rewind` together to apply the tag all object
versions which existed at a specific point in time.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
.. |command-2| replace:: :mc-cmd:`mc tag remove`
.. |versions-2| replace:: :mc-cmd-option:`~mc tag remove versions`
.. |rewind-2| replace:: :mc-cmd-option:`~mc tag remove rewind`
.. |versionid-2| replace:: :mc-cmd-option:`~mc tag remove version-id`
.. |alias-2| replace:: :mc-cmd-option:`~mc tag remove TARGET`
.. mc-cmd:: remove
:fullpath:
Removes *all* tags from a bucket or object.
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc tag remove [FLAGS] TARGET
The command accepts the following arguments:
.. mc-cmd:: TARGET
**Required** The full path to the bucket or object from which to remove
tags. Specify the :mc-cmd:`alias <mc alias>` of a configured S3-compatible
service as the prefix to the :mc-cmd:`~mc tag remove TARGET` path. For
example:
.. code-block:: shell
mc version remove play/mybucket
.. mc-cmd:: versions
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-versions-desc-2
:end-before: end-versions-desc-2
Use :mc-cmd-option:`~mc tag remove versions` and
:mc-cmd-option:`~mc tag remove rewind` together to remove the tag from
object versions which existed at a specific point in time.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc-2
:end-before: end-rewind-desc-2
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc-2
:end-before: end-version-id-desc-2
.. |command-3| replace:: :mc-cmd:`mc tag list`
.. |versions-3| replace:: :mc-cmd-option:`~mc tag list versions`
.. |rewind-3| replace:: :mc-cmd-option:`~mc tag list rewind`
.. |versionid-3| replace:: :mc-cmd-option:`~mc tag list version-id`
.. |alias-3| replace:: :mc-cmd-option:`~mc tag list TARGET`
.. mc-cmd:: list
:fullpath:
Lists the tags assigned to a bucket or object.
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc tag <CMD> [FLAGS] TARGET
The command accepts the following arguments:
.. mc-cmd:: TARGET
**Required** The full path to the bucket or object for which the command
lists tags. Specify the :mc-cmd:`alias <mc alias>` of a
configured S3-compatible service as the prefix to the
:mc-cmd:`~mc tag list TARGET` path. For example:
.. code-block:: shell
mc version <CMD> play/mybucket
.. mc-cmd:: versions
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-versions-desc-3
:end-before: end-versions-desc-3
Use :mc-cmd-option:`~mc tag list versions` and
:mc-cmd-option:`~mc tag list rewind` together to list all tags applied to
all object versions which existed at a specific point in time.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc-3
:end-before: end-rewind-desc-3
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc-3
:end-before: end-version-id-desc-3

82
source/reference/minio-cli/minio-mc/mc-tree.rst
View File

@ -1,82 +0,0 @@
===========
``mc tree``
===========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc tree
Description
-----------
.. start-mc-tree-desc
The :mc:`mc tree` command lists buckets and directories in a tree format.
.. end-mc-tree-desc
- When applied to an S3-compatible service bucket, :mc:`mc tree` returns
a tree listing of the bucket and all bucket prefixes.
- When applied to a local filesystem directory, :mc:`mc tree` returns a
tree listing of the directory and all of its subdirectories.
Examples
--------
.. code-block:: shell
:class: copyable
mc tree ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc tree TARGET>` with the :mc:`alias <mc alias>`
of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc tree TARGET>` with the path to the bucket on the
S3-compatible host.
Syntax
------
.. |command| replace:: :mc-cmd:`mc tree`
.. |rewind| replace:: :mc-cmd-option:`~mc tree rewind`
.. |alias| replace:: :mc-cmd-option:`~mc tree TARGET`
:mc:`~mc tree` has the following syntax:
.. code-block:: shell
:class: copyable
mc tree [FLAGS] TARGET [TARGET...]
:mc:`~mc tree` supports the following arguments:
.. mc-cmd:: TARGET
*Required* The full path to an S3-compatible service bucket *or* local
filesystem directory.
For objects on an S3-compatible service, specify the :mc:`alias <mc alias>`
of a configured service as the prefix to the :mc-cmd:`~mc tree TARGET`
path. For example:
.. code-block:: shell
mc stat [FLAGS] play/mybucket
.. mc-cmd:: files, f
:option:
Includes files in the object or directory in the :mc:`mc tree` output.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc

33
source/reference/minio-cli/minio-mc/mc-update.rst
View File

@ -1,33 +0,0 @@
=============
``mc update``
=============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
.. mc:: mc update
Description
-----------
.. start-mc-update-desc
The :mc:`mc update` command automatically updates the :program:`mc` binary to
the latest stable version.
.. end-mc-update-desc
Syntax
------
:mc:`mc update` has the following syntax:
.. code-block:: shell
mc update
Use :mc:`mc update` after updating the :program:`minio` server binary to
ensure consistent behavior and compatibility.

182
source/reference/minio-cli/minio-mc/mc-version.rst
View File

@ -1,182 +0,0 @@
==============
``mc version``
==============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc version
Description
-----------
.. start-mc-version-desc
The :mc:`mc version` command enables or disables bucket versioning.
.. end-mc-version-desc
Object Locking Enables Bucket Versioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
While bucket versioning is disabled by default, configuring
object locking on a bucket or an object in that bucket automatically
enables versioning for the bucket. See
:mc:`mc lock` for more information on configuring object locking.
Bucket Versioning Requires Erasure Coding
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Bucket versioning requires that the MinIO deployment supports erasure coding.
See <erasure coding link> for more information.
Bucket Versioning with Existing Data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Enabling bucket versioning on a bucket with existing data immediately applies
a versioning ID to any unversioned object.
Disabling bucket versioning on a bucket with existing versioned data does
*not* remove any versioned objects. Applications can continue to access
versioned data after disabling bucket versioning. Use
:mc-cmd:`mc rm --versions ALIAS/BUCKET/OBJECT <mc rm versions>` to delete an
object *and* all its versions.
Common Operations
-----------------
Enable Bucket Versioning
~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc version enable` to enable versioning on a bucket:
.. code-block:: shell
:class: copyable
mc version enable ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc version enable TARGET>` with the
:mc:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc version enable TARGET>` with the bucket on which
to enable versioning.
Disable Bucket Versioning
~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc version disable` to disable versioning on a bucket:
.. code-block:: shell
:class: copyable
mc version disable ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc version disable TARGET>` with the
:mc:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc version disable TARGET>` with the bucket on which
to disable versioning.
Get Bucket Versioning Status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc version info` to enable versioning on a bucket:
.. code-block:: shell
:class: copyable
mc version info ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc version info TARGET>` with the
:mc:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc version info TARGET>` with the bucket on which
to retrieve the versioning status.
Syntax
------
.. code-block:: shell
mc version COMMAND
:mc:`~mc version` supports the following commands:
.. mc-cmd:: enable
:fullpath:
Enables bucket versioning on the specified bucket.
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc version enable TARGET
The command accepts the following arguments:
.. mc-cmd:: TARGET
**Required** The full path to the bucket on which to enable bucket
versioning. Specify the :mc:`alias <mc alias>` of a configured
S3-compatible service as the prefix to the
:mc-cmd:`~mc version enable TARGET` path. For example:
.. code-block:: shell
mc version enable play/mybucket
.. mc-cmd:: disable
:fullpath:
Disables bucket versioning on the specified bucket.
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc version disable TARGET
The command accepts the following arguments:
.. mc-cmd:: TARGET
**Required** The full path to the bucket on which to disable bucket
versioning. Specify the :mc:`alias <mc alias>` of a configured
S3-compatible service as the prefix to the
:mc-cmd:`~mc version disable TARGET` path. For example:
.. code-block:: shell
mc version disable play/mybucket
.. mc-cmd:: info
:fullpath:
Retrieves the bucket versioning status for the specified bucket.
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc version info TARGET
The command accepts the following arguments:
.. mc-cmd:: TARGET
**Required** The full path to the bucket on which to retrieve the bucket
versioning status. Specify the :mc:`alias <mc alias>` of a configured
S3-compatible service as the prefix to the
:mc-cmd:`~mc version info TARGET` path. For example:
.. code-block:: shell
mc version info play/mybucket

98
source/reference/minio-cli/minio-mc/mc-watch.rst
View File

@ -1,98 +0,0 @@
============
``mc watch``
============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc watch
Description
-----------
.. start-mc-watch-desc
The :mc:`mc watch` command watches for events on the specified S3-compatible
service bucket or local filesystem path. For S3 services, use :mc:`mc event` to
configure bucket event notifications on S3-compatible services.
.. end-mc-watch-desc
Examples
--------
Watch for Events in a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: shell
:class: copyable
mc watch --recursive ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc watch TARGET>` with the :mc:`alias <mc alias>`
of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc watch TARGET>` with the path to the bucket.
Syntax
------
:mc:`~mc watch` has the following syntax:
.. code-block:: shell
:class: copyable
mc watch [FLAGS] TARGET
:mc:`~mc watch` supports the following arguments:
.. mc-cmd:: TARGET
*Required* The S3 service :mc:`alias <mc alias>` and bucket *or* the local
filesystem directory to watch for event notifications. Specify the
:mc-cmd:`alias <mc alias>` of a configured S3 service as the prefix to the
``TARGET`` path. For example:
.. code-block:: shell
mc event add play/mybucket
.. mc-cmd:: event
:option:
The event(s) to watch for. Specify multiple events using a comma ``,``
delimiter. See :ref:`mc-event-supported-events` for supported events.
Defaults to ``put,delete, get``.
.. mc-cmd:: prefix
:option:
The bucket prefix in which to watch for the specified
:mc-cmd-option:`~mc watch event`.
For example, given a :mc-cmd:`~mc watch TARGET` of ``play/mybucket`` and a
:mc-cmd-option:`~mc watch prefix` of ``photos``, only events in
``play/mybucket/photos`` trigger bucket notifications.
.. mc-cmd:: suffix
:option:
The bucket suffix in which to watch for the specified
:mc-cmd-option:`~mc watch event`.
For example, given a :mc-cmd:`~mc watch TARGET` of ``play/mybucket`` and a
:mc-cmd-option:`~mc watch suffix` of ``.jpg``, only events in
``play/mybucket/*.jpg`` trigger bucket notifications.
.. mc-cmd:: recursive, r
:option:
Recursively watch for events in the specified
:mc-cmd:`~mc watch TARGET` bucket path or local directory.

38
source/reference/minio-cli/minio-mc-admin.rst → source/reference/minio-mc-admin.rst
View File

@ -10,7 +10,7 @@ MinIO Admin (``mc admin``)
.. mc:: mc admin
The MinIO Client :mc-cmd:`mc` command line tool provides the :mc-cmd:`mc admin`
The MinIO Client :mc-cmd:`mc` command line tool provides The command
command for performing administrative tasks on your MinIO deployments.
While :mc-cmd:`mc` supports any S3-compatible service,
@ -36,87 +36,87 @@ The following table lists :mc-cmd:`mc admin` commands:
- Description
* - :mc:`mc admin bucket remote`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst
- .. include:: /reference/minio-mc-admin/mc-admin-bucket-remote.rst
:start-after: start-mc-admin-bucket-remote-desc
:end-before: end-mc-admin-bucket-remote-desc
* - :mc:`mc admin bucket quota`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst
- .. include:: /reference/minio-mc-admin/mc-admin-bucket-quota.rst
:start-after: start-mc-admin-bucket-quota-desc
:end-before: end-mc-admin-bucket-quota-desc
* - :mc:`mc admin group`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-group.rst
- .. include:: /reference/minio-mc-admin/mc-admin-group.rst
:start-after: start-mc-admin-group-desc
:end-before: end-mc-admin-group-desc
* - :mc:`mc admin heal`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-heal.rst
- .. include:: /reference/minio-mc-admin/mc-admin-heal.rst
:start-after: start-mc-admin-heal-desc
:end-before: end-mc-admin-heal-desc
* - :mc:`mc admin info`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-info.rst
- .. include:: /reference/minio-mc-admin/mc-admin-info.rst
:start-after: start-mc-admin-info-desc
:end-before: end-mc-admin-info-desc
* - :mc:`mc admin kms key`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-kms-key.rst
- .. include:: /reference/minio-mc-admin/mc-admin-kms-key.rst
:start-after: start-mc-admin-kms-key-desc
:end-before: end-mc-admin-kms-key-desc
* - :mc:`mc admin obd`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-obd.rst
- .. include:: /reference/minio-mc-admin/mc-admin-obd.rst
:start-after: start-mc-admin-obd-desc
:end-before: end-mc-admin-obd-desc
* - :mc:`mc admin policy`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-policy.rst
- .. include:: /reference/minio-mc-admin/mc-admin-policy.rst
:start-after: start-mc-admin-policy-desc
:end-before: end-mc-admin-policy-desc
* - :mc:`mc admin profile`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-profile.rst
- .. include:: /reference/minio-mc-admin/mc-admin-profile.rst
:start-after: start-mc-admin-profile-desc
:end-before: end-mc-admin-profile-desc
* - :mc:`mc admin prometheus`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-prometheus.rst
- .. include:: /reference/minio-mc-admin/mc-admin-prometheus.rst
:start-after: start-mc-admin-prometheus-desc
:end-before: end-mc-admin-prometheus-desc
* - :mc:`mc admin service`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-service.rst
- .. include:: /reference/minio-mc-admin/mc-admin-service.rst
:start-after: start-mc-admin-service-desc
:end-before: end-mc-admin-service-desc
* - :mc:`mc admin speedtest`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-speedtest.rst
- .. include:: /reference/minio-mc-admin/mc-admin-speedtest.rst
:start-after: start-mc-admin-speedtest-desc
:end-before: end-mc-admin-speedtest-desc
* - :mc:`mc admin tier`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-tier.rst
- .. include:: /reference/minio-mc-admin/mc-admin-tier.rst
:start-after: start-mc-admin-tier-desc
:end-before: end-mc-admin-tier-desc
* - :mc:`mc admin top`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-top.rst
- .. include:: /reference/minio-mc-admin/mc-admin-top.rst
:start-after: start-mc-admin-top-desc
:end-before: end-mc-admin-top-desc
* - :mc:`mc admin trace`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-trace.rst
- .. include:: /reference/minio-mc-admin/mc-admin-trace.rst
:start-after: start-mc-admin-trace-desc
:end-before: end-mc-admin-trace-desc
* - :mc:`mc admin update`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-update.rst
- .. include:: /reference/minio-mc-admin/mc-admin-update.rst
:start-after: start-mc-admin-update-desc
:end-before: end-mc-admin-update-desc
* - :mc:`mc admin user`
- .. include:: /reference/minio-cli/minio-mc-admin/mc-admin-user.rst
- .. include:: /reference/minio-mc-admin/mc-admin-user.rst
:start-after: start-mc-admin-user-desc
:end-before: end-mc-admin-user-desc
@ -174,4 +174,4 @@ Global Options
:hidden:
:glob:
/reference/minio-cli/minio-mc-admin/*
/reference/minio-mc-admin/*

0
source/reference/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst → source/reference/minio-mc-admin/mc-admin-bucket-quota.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst → source/reference/minio-mc-admin/mc-admin-bucket-remote.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-console.rst → source/reference/minio-mc-admin/mc-admin-console.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-group.rst → source/reference/minio-mc-admin/mc-admin-group.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-heal.rst → source/reference/minio-mc-admin/mc-admin-heal.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-info.rst → source/reference/minio-mc-admin/mc-admin-info.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-kms-key.rst → source/reference/minio-mc-admin/mc-admin-kms-key.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-obd.rst → source/reference/minio-mc-admin/mc-admin-obd.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-policy.rst → source/reference/minio-mc-admin/mc-admin-policy.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-profile.rst → source/reference/minio-mc-admin/mc-admin-profile.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-prometheus.rst → source/reference/minio-mc-admin/mc-admin-prometheus.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-service.rst → source/reference/minio-mc-admin/mc-admin-service.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-speedtest.rst → source/reference/minio-mc-admin/mc-admin-speedtest.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-tier.rst → source/reference/minio-mc-admin/mc-admin-tier.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-top.rst → source/reference/minio-mc-admin/mc-admin-top.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-trace.rst → source/reference/minio-mc-admin/mc-admin-trace.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-update.rst → source/reference/minio-mc-admin/mc-admin-update.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin-user.rst → source/reference/minio-mc-admin/mc-admin-user.rst
View File

0
source/reference/minio-cli/minio-mc-admin/mc-admin.config.rst → source/reference/minio-mc-admin/mc-admin.config.rst
View File

489
source/reference/minio-mc.rst Normal file
View File

@ -0,0 +1,489 @@
=====================
MinIO Client (``mc``)
=====================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 1
.. mc:: mc
The MinIO Client :mc-cmd:`mc` command line tool provides a modern alternative
to UNIX commands like ``ls``, ``cat``, ``cp``, ``mirror``, and ``diff`` with
support for both filesystems and Amazon S3-compatible cloud storage services.
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: minio-mc-s3-compatibility
:mc-cmd:`mc` has the following syntax:
.. code-block:: shell
mc [GLOBALFLAGS] COMMAND --help
See :ref:`minio-mc-commands` for a list of supported commands.
.. admonition:: AGPLv3
:class: note
:program:`mc` is :minio-git:`AGPLv3 <mc/blob/master/LICENSE>`
licensed Free and Open Source (FOSS) software.
Applications integrating :program:`mc` may trigger AGPLv3 compliance
requirements. `MinIO Commericla Licensing <https://min.io/pricing>`__
is the best option for applications which trigger AGPLv3 obligations where
open-sourcing the application is not an option.
.. _mc-install:
Quickstart
----------
1) Install ``mc``
~~~~~~~~~~~~~~~~~
Install the :program:`mc` command line tool onto the host machine. Click
the tab that corresponds to the host machine operating system or environment:
.. include:: /includes/minio-mc-installation.rst
2) Create an Alias for the S3-Compatible Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. important::
The following example temporarily disables the bash history to mitigate the
risk of authentication credentials leaking in plain text. This is a basic
security measure and does not mitigate all possible attack vectors. Defer to
security best practices for your operating system for inputting sensitive
information on the command line.
Use the :mc-cmd:`mc alias set` command to add an Amazon S3-compatible service
to the :mc-cmd:`mc` :ref:`configuration <mc-configuration>`.
.. code-block:: shell
:class: copyable
bash +o history
mc alias set ALIAS HOSTNAME ACCESS_KEY SECRET_KEY
bash -o history
- Replace ``ALIAS`` with a name to associate to the S3 service.
:mc-cmd:`mc` commands typically require ``ALIAS`` as an argument for
identifying which S3 service to execute against.
- Replace ``HOSTNAME`` with the URL endpoint or IP address of the S3 service.
- Replace ``ACCESS_KEY`` and ``SECRET_KEY`` with the access and secret
keys for a user on the S3 service.
Replace each argument with the required values. Specifying only the
``mc config host add`` command starts an input prompt for entering the
required values.
Each of the following tabs contains a provider-specific example:
.. tab-set::
.. tab-item:: MinIO Server
.. code-block:: shell
:class: copyable
mc alias set myminio https://minioserver.example.net ACCESS_KEY SECRET KEY
.. tab-item:: AWS S3 Storage
.. code-block:: shell
:class: copyable
mc alias set myS3 https://s3.amazon.com/endpoint ACCESS_KEY SECRET KEY
.. tab-item:: Google Cloud Storage
.. code-block:: shell
:class: copyable
mc alias set myGCS https://storage.googleapis.com/endpoint ACCESS_KEY SECRET KEY
3) Test the Connection
~~~~~~~~~~~~~~~~~~~~~~
Use the :mc-cmd:`mc admin info` command to test the connection to
the newly added MinIO deployment:
.. code-block:: shell
:class: copyable
mc admin info myminio
The command returns information on the S3 service if successful. If
unsuccessful, check each of the following:
- The host machine has connectivity to the S3 service URL (i.e. using ``ping``
or ``traceroute``).
- The specified ``ACCESSKEY`` and ``SECRETKEY`` correspond to a user on the
S3 service. The user must have permission to perform actions on the
service.
For MinIO deployments, see :ref:`minio-access-management`
for more information on user access permissions. For other S3-compatible
services, defer to the documentation for that service.
.. _minio-mc-commands:
Command Quick Reference
-----------------------
The following table lists :mc-cmd:`mc` commands:
.. list-table::
:header-rows: 1
:widths: 30 70
:width: 100%
* - Command
- Description
* - | :mc:`mc alias set`
| :mc:`mc alias remove`
| :mc:`mc alias list`
- The command command provides a convenient interface for
managing the list of S3-compatible hosts that :mc-cmd:`mc` can connect to
and run operations against.
:mc-cmd:`mc` commands that operate on S3-compatible services *require*
specifying an alias for that service.
* - :mc:`mc cat`
- .. include:: /reference/minio-mc/mc-cat.rst
:start-after: start-mc-cat-desc
:end-before: end-mc-cat-desc
* - :mc:`mc cp`
- .. include:: /reference/minio-mc/mc-cp.rst
:start-after: start-mc-cp-desc
:end-before: end-mc-cp-desc
* - :mc:`mc diff`
- .. include:: /reference/minio-mc/mc-diff.rst
:start-after: start-mc-diff-desc
:end-before: end-mc-diff-desc
* - | :mc:`mc encrypt set`
| :mc:`mc encrypt info`
| :mc:`mc encrypt clear`
- The ``mc encrypt`` command sets, updates, or disables the default bucket
Server-Side Encryption (SSE) mode. MinIO automatically encrypts objects
using the specified SSE mode.
* - | :mc:`mc event add`
| :mc:`mc event remove`
| :mc:`mc event list`
- The ``mc event`` command supports adding, removing, and listing
the bucket event notifications.
MinIO automatically sends triggered events to the configured notification
targets. MinIO supports notification targets like AMQP (RabbitMQ), Redis,
ElasticSearch, NATS and PostgreSQL. See :ref:`MinIO Bucket Notifications
<minio-bucket-notifications>` for more information.
* - :mc:`mc find`
- .. include:: /reference/minio-mc/mc-find.rst
:start-after: start-mc-find-desc
:end-before: end-mc-find-desc
* - :mc:`mc head`
- .. include:: /reference/minio-mc/mc-head.rst
:start-after: start-mc-head-desc
:end-before: end-mc-head-desc
* - | :mc:`mc ilm add`
| :mc:`mc ilm ls`
| :mc:`mc ilm edit`
| :mc:`mc ilm rm`
| :mc:`mc ilm export`
| :mc:`mc ilm import`
- The ``mc ilm`` command supports managing
:ref:`object lifecycle management rules <minio-lifecycle-management>`
on a MinIO deployment.
Use this command to set both :ref:`minio-lifecycle-management-tiering`
and :ref:`minio-lifecycle-management-expiration` rules on a bucket.
* - | :mc:`mc legalhold set`
| :mc:`mc legalhold info`
| :mc:`mc legalhold clear`
- The ``mc legalhold`` command sets, removes, or retrieves
the :ref:`Object Legal Hold (WORM) <minio-object-locking-legalhold>`
settings for object(s).
* - :mc:`mc ls`
- .. include:: /reference/minio-mc/mc-ls.rst
:start-after: start-mc-ls-desc
:end-before: end-mc-ls-desc
* - :mc:`mc mb`
- .. include:: /reference/minio-mc/mc-mb.rst
:start-after: start-mc-mb-desc
:end-before: end-mc-mb-desc
* - :mc:`mc mirror`
- .. include:: /reference/minio-mc/mc-mirror.rst
:start-after: start-mc-mirror-desc
:end-before: end-mc-mirror-desc
* - :mc:`mc mv`
- .. include:: /reference/minio-mc/mc-mv.rst
:start-after: start-mc-mv-desc
:end-before: end-mc-mv-desc
* - | :mc:`mc policy set`
| :mc:`mc policy set-json`
| :mc:`mc policy get`
| :mc:`mc policy get-json`
| :mc:`mc policy list`
| :mc:`mc policy links`
- The :mc:`mc policy` command supports setting or removing anonymous
:ref:`policies <minio-policy>` to a bucket and its contents. Buckets with
anonymous policies allow public access where clients can perform any
action granted by the policy without :ref:`authentication
<minio-authentication-and-identity-management>`.
* - :mc:`mc rb`
- .. include:: /reference/minio-mc/mc-rb.rst
:start-after: start-mc-rb-desc
:end-before: end-mc-rb-desc
* - | :mc:`mc retention set`
| :mc:`mc retention info`
| :mc:`mc retention clear`
- The :mc:`mc retention` command configures the
:ref:`Write-Once Read-Many (WORM) locking <minio-object-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.
* - | :mc:`mc replicate add`
| :mc:`mc replicate edit`
| :mc:`mc replicate ls`
| :mc:`mc replicate status`
| :mc:`mc replicate resync`
| :mc:`mc replicate export`
| :mc:`mc replicate import`
| :mc:`mc replicate rm`
- The :mc:`mc replicate <mc replicate add>` command configures and
manages the :ref:`Server-Side Bucket Replication
<minio-bucket-replication-serverside>` for a MinIO deployment, including
:ref:`active-active replication configurations
<minio-bucket-replication-serverside-twoway>` and
:ref:`resynchronization <minio-replication-behavior-resync>`.
* - :mc:`mc rm`
- .. include:: /reference/minio-mc/mc-rm.rst
:start-after: start-mc-rm-desc
:end-before: end-mc-rm-desc
* - | :mc:`mc share download`
| :mc:`mc share upload`
| :mc:`mc share list`
- The :mc-cmd:`mc share download` and :mc-cmd:`mc share upload`
commands generate presigned URLs for downloading and uploading
objects to a MinIO bucket.
* - :mc:`mc sql`
- .. include:: /reference/minio-mc/mc-sql.rst
:start-after: start-mc-sql-desc
:end-before: end-mc-sql-desc
* - :mc:`mc stat`
- .. include:: /reference/minio-mc/mc-stat.rst
:start-after: start-mc-stat-desc
:end-before: end-mc-stat-desc
* - | :mc:`mc tag set`
| :mc:`mc tag remove`
| :mc:`mc tag list`
- The :mc:`mc tag` command adds, removes, and lists tags associated to
a bucket or object.
* - :mc:`mc tree`
- .. include:: /reference/minio-mc/mc-tree.rst
:start-after: start-mc-tree-desc
:end-before: end-mc-tree-desc
* - :mc:`mc update`
- .. include:: /reference/minio-mc/mc-update.rst
:start-after: start-mc-update-desc
:end-before: end-mc-update-desc
* - :mc:`mc version`
- .. include:: /reference/minio-mc/mc-version.rst
:start-after: start-mc-version-desc
:end-before: end-mc-version-desc
* - :mc:`mc watch`
- .. include:: /reference/minio-mc/mc-watch.rst
:start-after: start-mc-watch-desc
:end-before: end-mc-watch-desc
:mc-cmd:`mc` also includes an administration extension for managing MinIO
deployments. See :mc-cmd:`mc admin` for more complete documentation.
.. _mc-configuration:
Configuration File
------------------
:mc-cmd:`mc` uses a ``JSON`` formatted configuration file used for storing
certain kinds of information, such as the :mc-cmd:`aliases <mc alias>` for
each configured S3-compatible service.
For Linux and OSX, the default configuration file location is
``~/.mc/config.json``.
For Windows, :mc-cmd:`mc` attempts to construct a default file path by trying
specific environment variables. If a variable is unset, :mc-cmd:`mc` moves
to the next variable. If all attempts fail, :mc-cmd:`mc` returns an error.
The following list describes each possible file path location in the order
:mc-cmd:`mc` checks them:
#. ``HOME\.mc\config.json``
#. ``USERPROFILE\.mc\config.json``
#. ``HOMEDRIVE+HOMEPATH\.mc\config.json``
You can use the ``--config-dir``
.. _minio-mc-global-options:
Global Options
--------------
.. program:: mc
All :ref:`commands <minio-mc-commands>` support the following global options:
.. option:: --debug
Enables verbose output to the console.
For example, the following operation adds verbose output to the
:mc:`mc ls` command:
.. code-block:: shell
:class: copyable
mc --debug ls play
.. option:: --config-dir
The path to a ``JSON`` formatted configuration file that
:program:`mc` uses for storing data. See :ref:`mc-configuration` for
more information on how :program:`mc` uses the configuration file.
.. option:: --JSON
Enables `JSON lines <http://jsonlines.org/>`_ formatted output to the
console.
For example, the following operation adds JSON Lines output to the
:mc:`mc ls` command:
.. code-block:: shell
:class: copyable
mc --JSON ls play
.. option:: --no-color
Disables the built-in color theme for console output. Useful for dumb
terminals.
.. option:: --quiet
Suppresses console output.
.. option:: --insecure
Disables TLS/SSL certificate verification. Allows TLS connectivity to
servers with invalid certificates. Exercise caution when using this
option against untrusted S3 hosts.
.. option:: --version
Displays the current version of :mc-cmd:`mc`.
.. toctree::
:titlesonly:
:hidden:
/reference/minio-mc/mc-alias-set
/reference/minio-mc/mc-alias-list
/reference/minio-mc/mc-alias-remove
/reference/minio-mc/mc-cat
/reference/minio-mc/mc-cp
/reference/minio-mc/mc-diff
/reference/minio-mc/mc-encrypt-set
/reference/minio-mc/mc-encrypt-info
/reference/minio-mc/mc-encrypt-clear
/reference/minio-mc/mc-event-add
/reference/minio-mc/mc-event-list
/reference/minio-mc/mc-event-remove
/reference/minio-mc/mc-find
/reference/minio-mc/mc-head
/reference/minio-mc/mc-ilm-add
/reference/minio-mc/mc-ilm-edit
/reference/minio-mc/mc-ilm-ls
/reference/minio-mc/mc-ilm-restore
/reference/minio-mc/mc-ilm-rm
/reference/minio-mc/mc-ilm-export
/reference/minio-mc/mc-ilm-import
/reference/minio-mc/mc-legalhold-set
/reference/minio-mc/mc-legalhold-info
/reference/minio-mc/mc-legalhold-clear
/reference/minio-mc/mc-ls
/reference/minio-mc/mc-mb
/reference/minio-mc/mc-mirror
/reference/minio-mc/mc-mv
/reference/minio-mc/mc-policy-set
/reference/minio-mc/mc-policy-get
/reference/minio-mc/mc-policy-list
/reference/minio-mc/mc-policy-links
/reference/minio-mc/mc-policy-get-json
/reference/minio-mc/mc-policy-set-json
/reference/minio-mc/mc-rb
/reference/minio-mc/mc-replicate-add
/reference/minio-mc/mc-replicate-edit
/reference/minio-mc/mc-replicate-ls
/reference/minio-mc/mc-replicate-resync
/reference/minio-mc/mc-replicate-rm
/reference/minio-mc/mc-replicate-status
/reference/minio-mc/mc-replicate-export
/reference/minio-mc/mc-replicate-import
/reference/minio-mc/mc-retention-set
/reference/minio-mc/mc-retention-info
/reference/minio-mc/mc-retention-clear
/reference/minio-mc/mc-rm
/reference/minio-mc/mc-share-download
/reference/minio-mc/mc-share-upload
/reference/minio-mc/mc-share-list
/reference/minio-mc/mc-sql
/reference/minio-mc/mc-stat
/reference/minio-mc/mc-tag-set
/reference/minio-mc/mc-tag-list
/reference/minio-mc/mc-tag-remove
/reference/minio-mc/mc-template
/reference/minio-mc/mc-tree
/reference/minio-mc/mc-update
/reference/minio-mc/mc-version
/reference/minio-mc/mc-watch

123
source/reference/minio-mc/mc-alias-list.rst Normal file
View File

@ -0,0 +1,123 @@
.. _minio-mc-alias-list:
=================
``mc alias list``
=================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc alias list
Syntax
------
.. start-mc-alias-list-desc
The :mc:`mc alias list` command lists all aliases in the local
:program:`mc` configuration.
.. end-mc-alias-list-desc
The command output includes the configured access key and secret key associated
to each alias.
.. tab-set::
.. tab-item:: EXAMPLE
The following command lists all :ref:`aliases <alias>` configured
on the local host machine:
.. code-block:: shell
:class: copyable
mc alias list
.. tab-item:: SYNTAX
The :mc-cmd:`mc alias list` command has the following syntax:
.. code-block:: shell
mc [GLOBALFLAGS] alias list [ALIAS]
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Optional* The name of a specific alias to display.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
List All Configured Aliases
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Example
The following :mc-cmd:`mc alias list` command lists all configured aliases
in the local :program:`mc` configuration.
.. code-block:: shell
:class: copyable
mc alias list
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
mc alias list
List a Specific Alias
~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Example
The following :mc-cmd:`mc alias list` command lists the details of a
specific alias in the local :program:`mc` configuration.
.. code-block:: shell
:class: copyable
mc alias list myminio
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
mc alias list ALIAS
- Replace ``ALIAS`` with the the name of the alias to return.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

101
source/reference/minio-mc/mc-alias-remove.rst Normal file
View File

@ -0,0 +1,101 @@
.. _minio-mc-alias-remove:
===================
``mc alias remove``
===================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc alias remove
Syntax
------
.. start-mc-alias-remove-desc
The :mc:`mc alias remove` removes an existing alias from the local
:program:`mc` configuration.
.. end-mc-alias-remove-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command removes the ``myminio`` :ref:`alias <alias>` for a
MinIO deployment from the host machine:
.. code-block:: shell
:class: copyable
mc alias remove myminio
.. tab-item:: SYNTAX
The :mc-cmd:`mc alias remove` command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] alias remove ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The alias to remove from the local :program:`mc` configuration.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Remove an Alias from the ``mc`` Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc alias remove` to remove an existing alias from the
:program:`mc` configuration:
.. tab-set::
.. tab-item:: Example
The following command removes the ``myminio`` alias.
.. code-block:: shell
:class: copyable
mc alias remove myminio
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
mc alias remove ALIAS
Replace ``ALIAS`` with the the name of the alias to remove.
Behavior
~~~~~~~~
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

202
source/reference/minio-mc/mc-alias-set.rst Normal file
View File

@ -0,0 +1,202 @@
.. _minio-mc-alias-set:
.. _minio-mc-alias:
.. _alias:
================
``mc alias set``
================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc alias
.. mc:: mc alias set
.. |command| replace:: :mc-cmd:`mc alias set`
Syntax
------
.. start-mc-alias-set-desc
The :mc:`mc alias set` command adds or updates an alias to the local
:program:`mc` configuration.
.. end-mc-alias-set-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command adds an :ref:`alias <alias>` for a MinIO
deployment ``myminio`` running at the URL
``https://myminio.example.net``. :program:`mc` uses the specified
username and password for authenticating to the MinIO deployment:
.. code-block:: shell
:class: copyable
mc alias set myminio https://myminio.example.net minioadminuser minioadminpassword
If the ``myminio`` alias already exists, the command overwrites that
alias with the new URL, access key, and secret key.
.. tab-item:: SYNTAX
The :mc-cmd:`mc alias set` command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] alias set \
[--api "string"] \
[--path "string"] \
ALIAS \
URL \
ACCESSKEY \
SECRETKEY
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The name to associate to the S3-compatible service.
.. mc-cmd:: URL
*Required* The URL to the S3-compatible service endpoint. For example:
``https://minio.example.net``
.. mc-cmd:: ACCESSKEY
*Required*
The access key for authenticating to the S3 service.
.. mc-cmd:: SECRETKEY
*Required*
The secret key for authenticating to the S3 service.
.. mc-cmd:: api
:option:
*Optional*
Specifies the signature calculation method to use when connecting to the
S3-compatible service. Supports the following values:
- ``S3v4`` (Default)
- ``S3v2``
.. note::
AWS Signature V2 is considered
`deprecated <https://aws.amazon.com/blogs/aws/amazon-s3-update-sigv2-deprecation-period-extended-modified/>`__
by AWS. :mc-cmd:`mc alias set` includes this option only for S3 buckets
or services still reliant on the Signature V2.
Use ``S3v4`` unless explicitly required by the S3-compatible service.
MinIO server does not rely on nor require ``S3v2``, nor are all API
operations available on ``S3v2``.
.. mc-cmd:: path
:option:
*Optional*
Specifies the bucket path lookup setting used by the server. Supports the
following values:
- ``"auto"`` (Default)
- ``"on"``
- ``"off"``
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Add or Update an Alias for a MinIO Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc alias set` to add an S3-compatible service for use with
:program:`mc`:
.. tab-set::
.. tab-item:: Example
The following command creates a new alias ``myminio`` pointing at a
MinIO deployment at ``https://minio.example.net``. The
alias uses the ``miniouser`` and ``miniopassword`` credentials for
performing operations against the deployment.
.. code-block:: shell
:class: copyable
mc alias set myminio https://minio.example.net miniouser miniopassword
If the ``myminio`` alias already exists, the
:mc-cmd:`mc alias set` command overwrites that alias with the specified
arguments.
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
mc alias set ALIAS HOSTNAME ACCESSKEY SECRETKEY
- Replace ``ALIAS`` with the the name to associate to the
MinIO service.
- Replace ``HOSTNAME`` with the URL for any node in the MinIO
deployment. You can alternatively specify the URL for a load balancer
or reverse proxy managing connections to the MinIO deployment.
- Replace ``ACCESSKEY`` and ``SECRETKEY`` with credentials for a user
on the MinIO deployment.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility
Required Credentials and Access Control
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:mc-cmd:`mc alias set` requires specifying an access key and corresponding
secret key for the S3-compatible host. :program:`mc` functionality is limited
based on the policies associated to the specified credentials. For example, if
the specified credentials do not have read/write access to a specific bucket,
:program:`mc` cannot perform read or write operations on that bucket.
For more information on MinIO Access Control, see
:ref:`minio-access-management`.
For more complete documentation on S3 Access Control, see
:s3-docs:`Amazon S3 Security <security.html>`.
For all other S3-compatible services, defer to the documentation for that
service.

218
source/reference/minio-cli/minio-mc/mc-cat.rst → source/reference/minio-mc/mc-cat.rst
View File

@ -1,3 +1,5 @@
.. _minio-mc-cat:
==========
``mc cat``
==========
@ -10,8 +12,15 @@
.. mc:: mc cat
Description
-----------
.. Replacement substitutions
.. |command| replace:: :mc-cmd:`mc cat`
.. |rewind| replace:: :mc-cmd-option:`~mc cat rewind`
.. |versionid| replace:: :mc-cmd-option:`~mc cat version-id`
.. |alias| replace:: :mc-cmd-option:`~mc cat ALIAS`
Syntax
------
.. start-mc-cat-desc
@ -22,116 +31,50 @@ display the contents of the specified file or object to ``STDOUT``.
.. end-mc-cat-desc
Common Operations
-----------------
.. tab-set::
View an S3 Object
~~~~~~~~~~~~~~~~~
.. tab-item:: EXAMPLE
Use :mc-cmd:`mc cat` to return the object:
The following command concatenates the contents of an object on a
MinIO deployment to ``STDOUT``:
.. code-block:: shell
:class: copyable
.. code-block:: shell
:class: copyable
mc cat ALIAS/PATH
mc cat play/mybucket/myobject.txt
- Replace :mc-cmd:`ALIAS <mc cat SOURCE>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
.. tab-item:: SYNTAX
- Replace :mc-cmd:`PATH <mc cat SOURCE>` with the path to the object on the
S3-compatible host.
The command command has the following syntax:
View an S3 Object at a Point-In-Time
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: shell
:class: copyable
Use :mc-cmd-option:`mc cat rewind` to return the object at a specific
point-in-time in the past:
mc [GLOBALFLAGS] cat \
[--rewind] \
[--version-id] \
[--encrypt-key] \
PATH
.. code-block:: shell
:class: copyable
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
mc cat ALIAS/PATH --rewind DURATION
- Replace :mc-cmd:`ALIAS <mc cat SOURCE>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
You can also use :mc:`mc cat` against a local filesystem to produce similar
results to the ``cat`` commandline tool:
- Replace :mc-cmd:`PATH <mc cat SOURCE>` with the path to the object on the
S3-compatible host.
Parameters
~~~~~~~~~~
- Replace :mc-cmd:`DURATION <mc cat rewind>` with the point-in-time in the past
at which the command returns the object. For example, specify ``30d`` to
return the version of the object 30 days prior to the current date.
.. mc-cmd:: ALIAS
.. include:: /includes/facts-versioning.rst
:start-after: start-versioning-admonition
:end-before: end-versioning-admonition
*Required* The :ref:`alias <alias>` of a MinIO or other S3-compatible
service.
View an S3 Object with Specific Version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd-option:`mc cat version-id` to return a specific version of the
object:
.. code-block:: shell
mc cat ALIAS/PATH --version-id VERSION
- Replace :mc-cmd:`ALIAS <mc cat SOURCE>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc cat SOURCE>` with the path to the object on the
S3-compatible host.
- Replace :mc-cmd:`VERSION <mc cat version-id>` with the specific version of the
object to return.
.. include:: /includes/facts-versioning.rst
:start-after: start-versioning-admonition
:end-before: end-versioning-admonition
Syntax
------
.. Replacement substitutions
.. |command| replace:: :mc-cmd:`mc cat`
.. |rewind| replace:: :mc-cmd-option:`~mc cat rewind`
.. |versionid| replace:: :mc-cmd-option:`~mc cat version-id`
.. |alias| replace:: :mc-cmd-option:`~mc cat SOURCE`
:mc:`~mc cat` has the following syntax:
.. code-block:: shell
mc cat [FLAGS] SOURCE [SOURCE ...]
:mc:`~mc cat` supports requires following arguments:
.. mc-cmd:: SOURCE
**REQUIRED**
The object to concatenate.
For objects on S3-compatible hosts, specify the path to the object as
``ALIAS/PATH``, where:
- ``ALIAS`` is the :mc:`alias <mc alias>` of a configured S3-compatible host,
*and*
- ``PATH`` is the path to the object.
.. code-block:: shell
mc cat play/mybucket/object.txt
For files on a filesystem, specify the full filesystem path to the file as
``SOURCE``:
.. code-block:: shell
mc cat ~/data/object.txt
.. mc-cmd:: PATH
*Required* The full path to an object on the specified alias.
.. mc-cmd:: rewind
:option:
@ -164,3 +107,86 @@ Syntax
environment variable for retrieving a list of encryption key-value pairs
as an alternative to specifying them on the command line.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
View an S3 Object
~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc cat` to return the object:
.. code-block:: shell
:class: copyable
mc cat ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc cat ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc cat ALIAS>` with the path to the object on the
S3-compatible host.
View an S3 Object at a Point-In-Time
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd-option:`mc cat rewind` to return the object at a specific
point-in-time in the past:
.. code-block:: shell
:class: copyable
mc cat ALIAS/PATH --rewind DURATION
- Replace :mc-cmd:`ALIAS <mc cat ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc cat ALIAS>` with the path to the object on the
S3-compatible host.
- Replace :mc-cmd:`DURATION <mc cat rewind>` with the point-in-time in the past
at which the command returns the object. For example, specify ``30d`` to
return the version of the object 30 days prior to the current date.
.. include:: /includes/facts-versioning.rst
:start-after: start-versioning-admonition
:end-before: end-versioning-admonition
View an S3 Object with Specific Version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd-option:`mc cat version-id` to return a specific version of the
object:
.. code-block:: shell
mc cat ALIAS/PATH --version-id VERSION
- Replace :mc-cmd:`ALIAS <mc cat ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc cat ALIAS>` with the path to the object on the
S3-compatible host.
- Replace :mc-cmd:`VERSION <mc cat version-id>` with the specific version of the
object to return.
.. include:: /includes/facts-versioning.rst
:start-after: start-versioning-admonition
:end-before: end-versioning-admonition
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

531
source/reference/minio-cli/minio-mc/mc-cp.rst → source/reference/minio-mc/mc-cp.rst
View File

@ -1,3 +1,5 @@
.. _minio-mc-cp:
=========
``mc cp``
=========
@ -10,18 +12,274 @@
.. mc:: mc cp
Description
-----------
.. |command| replace:: :mc-cmd:`mc cp`
.. |rewind| replace:: :mc-cmd-option:`~mc cp rewind`
.. |versionid| replace:: :mc-cmd-option:`~mc cp version-id`
.. |alias| replace:: :mc-cmd-option:`~mc cp SOURCE`
Syntax
------
.. start-mc-cp-desc
The :mc:`mc cp` command copies data from one or more sources to a target
S3-compatible service.
The :mc:`mc cp` command copies objects to or from a MinIO deployment, where
the source can MinIO *or* a local filesystem.
.. end-mc-cp-desc
You can also use :mc:`mc cp` against the local filesystem to produce
similar results to the ``cp`` commandline tool.
.. tab-set::
.. tab-item:: EXAMPLE
The following command copies files from a local filesystem directory
to the ``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc cp --recursive ~/mydata/ myminio/mydata/
.. tab-item:: SYNTAX
The command command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] cp \
[--attr "string"] \
[--continue] \
[--disable-multipart] \
[--encrypt "string"] \
[--encrypt-key] \
[--legal-hold "on"] \
[--md5] \
[--newer-than "string"] \
[--older-than "string"] \
[--preserve] \
[--recursive] \
[--retention-mode "string" --retention-duration "string"] \
[--rewind "string"] \
[--storage-class "string"] \
[--tags "string"] \
[--version-id "string"] \
SOURCE TARGET
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: SOURCE
*Required* The object or objects to copy.
For copying an object from MinIO or another S3-compatible service,
specify the :ref:`alias <alias>` and the full path to that
object (e.g. bucket and path to object). For example:
.. code-block:: none
mc cp play/mybucket/object.txt ~/mydata/object.txt
For copying an object from a local filesystem, specify the full
path to that object. For example:
.. code-block:: none
mc cp ~/mydata/object.txt play/mybucket/object.txt
If you specify a directory or bucket to :mc-cmd:`~mc cp SOURCE`, you must
also specify :mc-cmd-option:`~mc cp recursive` to recursively copy the
contents of that directory or bucket. If you omit the ``--recursive``
argument, :mc:`~mc cp` only copies objects in the top level of the specified
directory or bucket.
.. mc-cmd:: TARGET
*Required* The full path to which :mc:`mc cp` copies the object.
For copying an object to MinIO or another S3-compatible service,
specify the :mc:`alias <mc alias>` and the full path to that object
(e.g. bucket and path to object). For example:
.. code-block:: none
mc cp ~/mydata/object.txt play/mybucket/object.txt
For copying an object from a local filesystem, specify the full
path to that object. For example:
.. code-block:: none
mc cp play/mybucket/object.txt ~/mydata/object.txt
.. mc-cmd:: attr
:option:
*Optional* Add custom metadata for the object. Specify key-value pairs as
``KEY=VALUE\;``. For example, ``--attr
key1=value1\;key2=value2\;key3=value3``.
.. mc-cmd:: continue, c
:option:
*Optional* Create or resume a copy session.
.. mc-cmd:: disable-multipart
:option:
*Optional* Disables multipart upload for the copy session.
.. mc-cmd:: encrypt
:option:
*Optional* Encrypt or decrypt objects using
:ref:`server-side encryption <minio-sse>` with
server-managed keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc cp encrypt` in double-quotes ``"``.
:mc-cmd-option:`~mc cp encrypt` can use the ``MC_ENCRYPT`` environment
variable for retrieving a list of encryption key-value pairs as an
alternative to specifying them on the command line.
.. mc-cmd:: encrypt-key
:option:
*Optional* Encrypt or decrypt objects using server-side encryption with
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc cp encrypt-key` in double quotes ``"``.
:mc-cmd-option:`~mc cp encrypt-key` can use the ``MC_ENCRYPT_KEY``
environment variable for retrieving a list of encryption key-value pairs
as an alternative to specifying them on the command line.
.. mc-cmd:: legal-hold
:option:
*Optional* Enables indefinite :ref:`Legal Hold
<minio-object-locking-legalhold>` object locking on the copied objects.
Specify ``on``.
.. mc-cmd:: md5
:option:
*Optional* Forces all uploads to calculate MD5 checksums.
.. mc-cmd:: newer-than
:option:
*Optional* Remove object(s) newer than the specified number of days. Specify
a string in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``
Defaults to ``0`` (all objects).
.. mc-cmd:: older-than
:option:
*Optional* Remove object(s) older than the specified time limit. Specify a
string in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``
Defaults to ``0`` (all objects).
.. mc-cmd:: preserve, a
:option:
*Optional* Preserve file system attributes and bucket policy rules of the
:mc-cmd:`~mc cp SOURCE` directories, buckets, and objects on the
:mc-cmd:`~mc cp TARGET` bucket(s).
.. mc-cmd:: recursive, r
:option:
*Optional* Recursively copy the contents of each bucket or directory
:mc-cmd:`~mc cp SOURCE` to the :mc-cmd:`~mc cp TARGET` bucket.
.. mc-cmd:: retention-duration
:option:
*Optional* The duration of the :ref:`WORM retention mode
<minio-object-locking-retention-modes>` to apply to the copied object(s).
Specify the duration as a string in
``#d#hh#mm#ss`` format. For example: ``--retention-duration "1d2hh3mm4ss"``.
Requires specifying :mc-cmd-option:`~mc cp retention-mode`.
.. mc-cmd:: retention-mode
:option:
*Optional* enables :ref:`object locking mode
<minio-object-locking-retention-modes>` on the copied object(s).
Supports the following values:
- ``GOVERNANCE``
- ``COMPLIANCE``
Requires specifying :mc-cmd-option:`~mc cp retention-duration`.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
.. mc-cmd:: storage-class, sc
:option:
*Optional* Set the storage class for the new object(s) on the
:mc-cmd:`~mc cp TARGET`.
See :aws-docs:`AmazonS3/latest/dev/storage-class-intro.html` for
more information on S3 storage classses.
.. mc-cmd:: tags
:option:
*Optional* Applies one or more tags to the copied objects.
Specify an ampersand-seperated list of key-value pairs as
``KEY1=VALUE1&KEY2=VALUE2``, where each pair represents one tag to
assign to the objects.
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
~~~~~~~~
--------
Copy Object to S3
~~~~~~~~~~~~~~~~~
@ -177,155 +435,6 @@ command only applies to S3-to-S3 copy.
:start-after: start-versioning-admonition
:end-before: end-versioning-admonition
Syntax
------
.. |command| replace:: :mc-cmd:`mc cp`
.. |rewind| replace:: :mc-cmd-option:`~mc cp rewind`
.. |versionid| replace:: :mc-cmd-option:`~mc cp version-id`
.. |alias| replace:: :mc-cmd-option:`~mc cp SOURCE`
:mc:`mc cp` has the following syntax:
.. code-block:: shell
mc cp [FLAGS] SOURCE [SOURCE...] TARGET
:mc:`~mc cp` supports the following arguments:
.. mc-cmd:: SOURCE
**REQUIRED**
The object or objects to copy. You can specify both local paths
and S3 paths using a configured S3 service :mc:`alias <mc alias>`.
For example:
.. code-block:: none
mc cp play/mybucket/object.txt ~/localfiles/mybucket/object.txt TARGET
If you specify a directory or bucket to :mc-cmd:`~mc cp SOURCE`, you must
also specify :mc-cmd-option:`~mc cp recursive` to recursively copy the
contents of that directory or bucket. If you omit the ``--recursive``
argument, :mc:`~mc cp` only copies objects in the top level of the specified
directory or bucket.
.. mc-cmd:: TARGET
**REQUIRED**
The full path to the bucket to copy the specified
:mc-cmd:`~mc cp SOURCE` to. Specify the :mc:`alias <mc alias>`
of a configured S3 service as the prefix to the
:mc-cmd:`~mc cp TARGET` path.
For example:
.. code-block:: shell
mc cp ~/localfiles/object.txt play/mybucket/
.. mc-cmd:: recursive, r
:option:
Recursively copy the contents of each bucket or directory
:mc-cmd:`~mc cp SOURCE` to the :mc-cmd:`~mc cp TARGET`
bucket.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
.. mc-cmd:: older-than
:option:
Remove object(s) older than the specified time limit. Specify a string
in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``
Defaults to ``0`` (all objects).
.. mc-cmd:: newer-than
:option:
Remove object(s) newer than the specified number of days. Specify a
string in ``#d#hh#mm#ss`` format. For example:
``--older-than 1d2hh3mm4ss``
Defaults to ``0`` (all objects).
.. mc-cmd:: storage-class, sc
:option:
Set the storage class for the new object(s) on the
:mc-cmd:`~mc cp TARGET`.
See :aws-docs:`AmazonS3/latest/dev/storage-class-intro.html` for
more information on S3 storage classses.
.. mc-cmd:: preserve, a
:option:
Preserve file system attributes and bucket policy rules of the
:mc-cmd:`~mc cp SOURCE` directories, buckets, and objects on the
:mc-cmd:`~mc cp TARGET` bucket(s).
.. mc-cmd:: attr
:option:
Add custom metadata for the object. Specify key-value pairs as
``KEY=VALUE\;``. For example,
``--attr key1=value1\;key2=value2\;key3=value3``.
.. mc-cmd:: continue, c
:option:
Create or resume a copy session.
.. mc-cmd:: encrypt
:option:
Encrypt or decrypt objects using server-side encryption with
server-managed keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc cp encrypt` in double-quotes ``"``.
:mc-cmd-option:`~mc cp encrypt` can use the ``MC_ENCRYPT`` environment
variable for retrieving a list of encryption key-value pairs as an
alternative to specifying them on the command line.
.. mc-cmd:: encrypt-key
:option:
Encrypt or decrypt objects using server-side encryption with
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc cp encrypt-key` in double quotes ``"``.
:mc-cmd-option:`~mc cp encrypt-key` can use the ``MC_ENCRYPT_KEY``
environment variable for retrieving a list of encryption key-value pairs
as an alternative to specifying them on the command line.
Behavior
--------
@ -337,113 +446,9 @@ Interrupted or failed copy operations can resume from the point of failure
by issuing the :mc:`mc cp` operation again with the
:mc-cmd-option:`~mc cp continue` argument.
Examples
--------
Copy a text file to an object storage.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/play-alias-available.rst
:start-after: play-alias-only
:end-before: end-play-alias-only
.. code-block:: shell
:class: copyable
mc cp myobject.txt play/mybucket
Copy a text file to an object storage with specified metadata.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/play-alias-available.rst
:start-after: play-alias-only
:end-before: end-play-alias-only
.. code-block:: shell
:class: copyable
mc cp --attr key1=value1;key2=value2 myobject.txt play/mybucket
Copy a folder recursively from MinIO cloud storage to Amazon S3 cloud storage with specified metadata.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/play-alias-available.rst
:start-after: play-alias-only
:end-before: end-play-alias-only
.. code-block:: shell
:class: copyable
mc cp --attr Cache-Control=max-age=90000,min-fresh=9000\;key1=value1\;key2=value2 \
--recursive play/mybucket/bucketname/ s3/mybucket/
Copy a text file to an object storage and assign ``storage-class`` REDUCED_REDUNDANCY to the uploaded object.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/play-alias-available.rst
:start-after: play-alias-only
:end-before: end-play-alias-only
.. code-block:: shell
:class: copyable
mc cp --storage-class REDUCED_REDUNDANCY myobject.txt play/mybucket
Copy a server-side encrypted file to an object storage.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example assumes that the ``s3`` and ``myminio`` aliases
exists in the :mc:`mc` :ref:`configuration file <mc-configuration>`. See
:mc:`mc alias` for more information on aliases.
.. code-block:: shell
:class: copyable
mc cp --recursive \
--encrypt-key "s3/documents/=32byteslongsecretkeymustbegiven1 , myminio/documents/=32byteslongsecretkeymustbegiven2" \
s3/documents/myobject.txt myminio/documents/
Perform key-rotation on a server-side encrypted object.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:mc:`mc cp` key rotation requires creating an additional alias with the same
endpoing as the target S3 service alias. :mc:`mc cp` effectively decrypts
the object using the old secret key, encrypts the object using the new
secret key, and replaces the old object with the newly encrypted object.
The following example assumes that the ``myminio1`` and ``myminio2`` aliases
exists in the :mc:`mc` :ref:`configuration file <mc-configuration>`. See
:mc:`mc alias` for more information on aliases.
.. code-block:: shell
:class: copyable
mc cp --encrypt-key 'myminio1/mybucket=32byteslongsecretkeymustgenerate , myminio2/mybucket/=32byteslongsecretkeymustgenerat1' \
myminio1/mybucket/encryptedobject myminio2/mybucket/encryptedobject
Copy a javascript file to object storage and assign ``Cache-Control`` header to the uploaded object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/play-alias-available.rst
:start-after: play-alias-only
:end-before: end-play-alias-only
.. code-block:: shell
:class: copyable
mc cp --attr Cache-Control=no-cache myscript.js play/mybucket
Copy a text file to an object storage and preserve the filesyatem attributes.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/play-alias-available.rst
:start-after: play-alias-only
:end-before: end-play-alias-only
.. code-block:: shell
:class: copyable
mc cp -a myobject.txt play/mybucket
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

134
source/reference/minio-mc/mc-diff.rst Normal file
View File

@ -0,0 +1,134 @@
.. _minio-mc-diff:
===========
``mc diff``
===========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc diff
Syntax
------
.. start-mc-diff-desc
The :mc:`mc diff` mc computes the differences between two filesystem directories
or MinIO buckets. :mc:`mc diff` lists only those objects which are missing or
which differ in size. :mc:`mc diff` does **not** compare the contents of
objects.
.. end-mc-diff-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command computes the difference between an object on
a local filesystem and an object in the ``mydata`` bucket on the
``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc diff ~/mydata/myobject.txt myminio/mydata/myobject.txt
.. tab-item:: SYNTAX
The command command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] diff SOURCE TARGET
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: SOURCE
*Required* The object to compare to the ``TARGET``.
For an object from MinIO or another S3-compatible service,
specify the :mc:`alias <mc alias>` and the full path to that
object (e.g. bucket and path to object). For example:
.. code-block:: none
mc diff play/mybucket/object.txt ~/mydata/object.txt
For an object from a local filesystem, specify the full
path to that object. For example:
.. code-block:: none
mc diff ~/mydata/object.txt play/mybucket/object.txt
.. mc-cmd:: TARGET
*Required* The object to compare to the ``SOURCE``.
For an object from MinIO or another S3-compatible service,
specify the :mc:`alias <mc alias>` and the full path to that
object (e.g. bucket and path to object). For example:
.. code-block:: none
mc diff play/mybucket/object.txt ~/mydata/object.txt
For an object from a local filesystem, specify the full
path to that object. For example:
.. code-block:: none
mc diff ~/mydata/object.txt play/mybucket/object.txt
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
.. include:: /includes/play-alias-available.rst
:start-after: play-alias-only
:end-before: end-play-alias-only
.. code-block:: shell
:class: copyable
mc diff play/bucket1 play/bucket2
Behavior
--------
Output Legend
~~~~~~~~~~~~~
:mc:`mc diff` uses the following legend when formatting the diff output:
.. code-block:: none
FIRST < SECOND - object exists only in FIRST
FIRST > SECOND - object exists only in SECOND
FIRST ! SECOND - Newer object exists in FIRST
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

115
source/reference/minio-mc/mc-encrypt-clear.rst Normal file
View File

@ -0,0 +1,115 @@
.. _minio-mc-encrypt-clear:
====================
``mc encrypt clear``
====================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc encrypt clear
Syntax
------
.. start-mc-encrypt-clear-desc
The :mc:`mc encrypt clear` command removes the current default
encryption settings for a bucket.
.. end-mc-encrypt-clear-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command removes the default encryption settings for
the ``mydata`` bucket on the MinIO deployment associated with the
``myminio`` :ref:`alias <alias>`:
.. code-block:: shell
:class: copyable
mc encrypt clear myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] encrypt clear ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
The full path to the bucket on which to remove the default SSE mode.
Specify the :ref:`alias <alias>` of the MinIO deployment as the prefix to the
ALIAS path. For example:
.. code-block:: shell
mc encrypt clear play/mybucket
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Remove the Automatic Server-Side Encryption Settings for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Example
.. code-block:: shell
:class: copyable
mc encrypt clear myminio/data
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
mc encrypt clear ALIAS
- Replace ``ALIAS`` with the :ref:`alias <alias>` of the
MinIO deployment on which to remove automatic server-side bucket
encryption.
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
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

104
source/reference/minio-mc/mc-encrypt-info.rst Normal file
View File

@ -0,0 +1,104 @@
.. _minio-mc-encrypt-info:
===================
``mc encrypt info``
===================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc encrypt info
Syntax
------
.. start-mc-encrypt-info-desc
The :mc:`mc encrypt info` command returns the current default
encryption settings for a bucket.
.. end-mc-encrypt-info-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command returns the default encryption setting for the
``mydata`` bucket on the ``myminio`` MinIO deployment.
.. code-block:: shell
:class: copyable
mc encrypt info myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] encrypt info ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
The full path to the bucket on which to retrieve the default SSE mode.
Specify the :ref:`alias <alias>` of the MinIO deployment as the prefix to the
ALIAS path. For example:
.. code-block:: shell
mc encrypt info play/mybucket
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Retrieve the Automatic Server-Side Encryption Settings for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Example
.. code-block:: shell
:class: copyable
mc encrypt info myminio/data
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
mc encrypt info ALIAS
- Replace ``ALIAS`` with the :ref:`alias <alias>` of the
MinIO deployment on which to configure automatic server-side bucket
encryption.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

151
source/reference/minio-mc/mc-encrypt-set.rst Normal file
View File

@ -0,0 +1,151 @@
.. _minio-mc-encrypt-set:
==================
``mc encrypt set``
==================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc encrypt set
Syntax
------
.. start-mc-encrypt-set-desc
The :mc:`mc encrypt set` encrypt command sets or updates the default
bucket :ref:`Server-Side Encryption (SSE) mode <minio-sse>`. MinIO automatically
encrypts objects written to that bucket using the specified SSE mode.
.. end-mc-encrypt-set-desc
:mc:`mc encrypt set` only supports :ref:`SSE-KMS <minio-encryption-sse-kms>`
and :ref:`SSE-S3 <minio-encryption-sse-s3>`.
.. tab-set::
.. tab-item:: EXAMPLE
The following command sets the default
:ref:`SSE-KMS encryption key <minio-encryption-sse-kms>` for the bucket
``mydata`` on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc encrypt set sse-kms "minio-encryption-key" myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] encrypt set ENCRYPTION [KMSKEY] ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ENCRYPTION
Specify the server-side encryption type to use as the default SSE mode.
Supports the following values:
- ``sse-kms`` - Encrypt objects using the key specified in
:mc-cmd:`~mc encrypt set KMSKEY`. MinIO
must have access to the specified key on the external KMS to
successfully encrypt or decrypt objects protected using SSE-KMS.
- ``sse-s3`` - Encrypt objects using the key specified to
:envvar:`MINIO_KMS_KES_KEY_NAME`. MinIO must have access to the
specified key on the external KMS to successfully encrypt or decrypt
objects protected using SSE-S3.
.. mc-cmd:: KMSKEY
Specify the KMS Master Key to use for performing SSE object encryption. This
option only applies if :mc-cmd:`~mc encrypt set ENCRYPTION` is
``sse-kms``.
Omit this option to direct MinIO to use the
:envvar:`MINIO_KMS_KES_KEY_NAME`.
.. mc-cmd:: ALIAS
The full path to the bucket on which to set the default SSE mode. Specify the
:ref:`alias <alias>` of the MinIO deployment as the prefix to the TARGET
path. For example:
.. code-block:: shell
mc encrypt set ENCRYPTION [KMSKEY] play/mybucket
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Enable Automatic Server-Side Bucket Encryption
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Example
The following commands assumes that:
- The MinIO server configuration supports
:ref:`SSE-KMS <minio-encryption-sse-kms>`
- The root has an encryption key ``minio-encryption-key``.
.. code-block:: shell
:class: copyable
mc encrypt set sse-kms minio-encryption-key myminio/data
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
mc encrypt set ENCRYPTION KMSKEY TARGET
- Replace ``ENCRYPTION`` with ``sse-kms`` or ``sse-s3`` depending
on the preferred encryption mode.
- Replace ``KMSKEY`` with the name of the encryption key on the
configured root KMS. This argument has no effect with ``sse-s3``.
- Replace ``TARGET`` with the :ref:`alias <alias>` of the
MinIO deployment on which to configure automatic server-side bucket
encryption.
Behavior
--------
:mc:`mc encrypt set` makes no assumptions about the MinIO server's current
encryption state. Specifying default encryption settings which the
server cannot support may result in undesired behavior.
Setting or modifying the default server-side encryption settings does *not*
automatically encrypt or decrypt the existing bucket contents. If the bucket
contents *must* have consistent encryption, use the
:mc:`mc mv` mc with the :mc-cmd-option:`~mc mv encrypt` or
:mc-cmd-option:`~mc mv encrypt-key` arguments to manually modify the
encryption settings or encrypted state of the bucket contents *before*
changing the bucket default.

239
source/reference/minio-mc/mc-event-add.rst Normal file
View File

@ -0,0 +1,239 @@
.. _minio-mc-event-add:
================
``mc event add``
================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc event add
Syntax
------
.. start-mc-event-add-desc
The :mc:`mc event add` command adds event notification triggers to a bucket.
.. end-mc-event-add-desc
MinIO automatically sends triggered events to the configured
:ref:`notification target <minio-bucket-notifications>`.
.. tab-set::
.. tab-item:: EXAMPLE
The following command creates a new event notification trigger for
all ``PUT`` and ``DELETE`` operations for the ``mydata`` bucket on the
``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc event add --event "put,delete" myminio/mydata arn:aws:sqs::primary:target
The specified ARN corresponds to a configured
:ref:`bucket notification target <minio-bucket-notifications>` on the
``myminio`` deployment.
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] event add \
[--event "string"] \
[--ignore-existing] \
[--prefix "string"] \
[--suffix "string"] \
ALIAS \
ARN
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The MinIO :ref:`alias <alias>` and bucket to
which the command adds the new event notification. For example:
.. code-block:: shell
mc event add play/mybucket
.. mc-cmd:: ARN
*Required* The :aws-docs:`Amazon Resource Name (ARN)
<general/latest/gr/aws-arns-and-namespaces>` of the notification target.
The MinIO server outputs an ARN for each configured
notification target at server startup. See
:doc:`/monitoring/bucket-notifications/bucket-notifications` for more
information.
.. mc-cmd:: event
:option:
*Optional* The event(s) for which MinIO generates bucket notifications.
Supports the following values:
- ``put``
- ``get``
- ``delete``
Specify multiple value using a comma ``,`` delimiter.
Defaults to ``put,delete,get``.
See :ref:`mc-event-supported-events` for a detailed list of S3 events
associated to each of the supported values.
.. mc-cmd:: ignore-existing, p
:option:
*Optional* Directs MinIO to ignore applying the specified event
triggers if an existing matching trigger exists.
.. mc-cmd:: prefix
:option:
*Optional* The bucket prefix in which the specified
:mc-cmd-option:`~mc event add event` can trigger a bucket notification.
For example, given a :mc-cmd:`~mc event add ALIAS` of ``play/mybucket``
and a :mc-cmd-option:`~mc event add 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.
.. mc-cmd:: suffix
:option:
*Optional* The bucket suffix in which the specified
:mc-cmd-option:`~mc event add event` can trigger a bucket notification.
For example, given a :mc-cmd:`~mc event add ALIAS` of ``play/mybucket``
and a :mc-cmd-option:`~mc event add 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
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Add an Event Notification to a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Example
The following command adds a new event notification trigger for all
S3 ``PUT``, ``GET``, and ``DELETE`` operations on a bucket. The command
assumes the MinIO deployment has at least one configured
:ref:`bucket notification target <minio-bucket-notifications>`:
.. code-block:: shell
:class: copyable
mc event add myminio/mydata arn:minio:sqs::primary:webhook
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
mc event add ALIAS ARN
- Replace ``ALIAS`` with the :ref:`alias <alias>` of the MinIO
deployment and the bucket on which to add the bucket notification event.
For example:
``myminio/mydata``
- Replace ``ARN`` with the notification target
:mc-cmd:`ARN <mc event add ARN>`.
Behavior
--------
.. _mc-event-supported-events:
Supported Bucket Events
~~~~~~~~~~~~~~~~~~~~~~~
The following table lists the supported :mc-cmd:`mc event add` values and their
corresponding :ref:`S3 events <minio-bucket-notifications-event-types>`:
.. list-table::
:header-rows: 1
:widths: 30 70
:width: 100%
* - Supported Vluae
- Corresponding S3 Events
* - ``put``
- | :data:`s3:ObjectCreated:CompleteMultipartUpload`
| :data:`s3:ObjectCreated:Copy`
| :data:`s3:ObjectCreated:DeleteTagging`
| :data:`s3:ObjectCreated:Post`
| :data:`s3:ObjectCreated:Put`
| :data:`s3:ObjectCreated:PutLegalHold`
| :data:`s3:ObjectCreated:PutRetention`
| :data:`s3:ObjectCreated:PutTagging`
* - ``get``
- | :data:`s3:ObjectAccessed:Head`
| :data:`s3:ObjectAccessed:Get`
| :data:`s3:ObjectAccessed:GetRetention`
| :data:`s3:ObjectAccessed:GetLegalHold`
* - ``delete``
- | :data:`s3:ObjectRemoved:Delete`
| :data:`s3:ObjectRemoved:DeleteMarkerCreated`
* - ``replica``
- | :data:`s3:Replication:OperationCompletedReplication`
| :data:`s3:Replication:OperationFailedReplication`
| :data:`s3:Replication:OperationMissedThreshold`
| :data:`s3:Replication:OperationNotTracked`
| :data:`s3:Replication:OperationReplicatedAfterThreshold`
* - ``ilm``
- | :data:`s3:ObjectTransition:Failed`
| :data:`s3:ObjectTransition:Complete`
| :data:`s3:ObjectRestore:Post`
| :data:`s3:ObjectRestore:Completed`
For more complete documentation on the listed S3 events, see
:s3-docs:`S3 Supported Event Types
<NotificationHowTo.html#notification-how-to-event-types-and-destinations>`.
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

128
source/reference/minio-mc/mc-event-list.rst Normal file
View File

@ -0,0 +1,128 @@
.. _minio-mc-event-list:
=================
``mc event list``
=================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc event list
Syntax
------
.. start-mc-event-list-desc
The :mc:`mc event list` command lists all event notification triggers for a
bucket.
.. end-mc-event-list-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command lists all configured event notifications for the
specified :ref:`bucket notification target <minio-bucket-notifications>`
for the ``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc event list myminio myminio/mydata arn:aws:sqs::primary:target
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS]
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
.. code-block:: shell
mc [GLOBALFLAGS] event remove [FLAGS] ALIAS ARN
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The S3 service :ref:`alias <alias>` and bucket to
which the command lists event notification. For example:
.. code-block:: shell
mc event add play/mybucket
.. mc-cmd:: ARN
*Required* The :aws-docs:`Amazon Resource Name (ARN)
<general/latest/gr/aws-arns-and-namespaces>` of the bucket resource.
The MinIO server outputs an ARN for each configured notification target at
server startup. See
:doc:`/monitoring/bucket-notifications/bucket-notifications` for more
information.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
List Event Notifications on a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Example
The following command lists all event notification triggers on a bucket.
.. code-block:: shell
:class: copyable
mc event list myminio/mydata
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
mc event list ALIAS ARN
- Replace ``ALIAS`` with the :ref:`alias <alias>` of the MinIO
deployment on which to add the bucket notification event. For example:
``myminio/mydata``
- Replace ``ARN`` with the notification target
:mc-cmd:`ARN <mc event add ARN>`.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

170
source/reference/minio-mc/mc-event-remove.rst Normal file
View File

@ -0,0 +1,170 @@
.. _minio-mc-event-remove:
===================
``mc event remove``
===================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc event remove
Syntax
------
.. start-mc-event-remove-desc
The :mc:`mc event remove` command removes event notification triggers on a
bucket.
.. end-mc-event-remove-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command removes a configured event notifications for the
specified :ref:`bucket notification target <minio-bucket-notifications>`
for the ``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc event remove myminio/mydata arn:aws:sqs::primary:target
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] event remove \
[--event "string"] \
[--force] \
[--prefix "string"] \
[--suffix "string"] \
ALIAS \
[ARN]
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
.. code-block:: shell
mc [GLOBALFLAGS] event remove [FLAGS] ALIAS ARN
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The S3 service :ref:`alias <alias>` and bucket from
which the command removes the event notification. For example:
.. code-block:: shell
mc event add play/mybucket
.. mc-cmd:: ARN
*Required* The :aws-docs:`Amazon Resource Name (ARN)
<general/latest/gr/aws-arns-and-namespaces>` of the notification target.
The MinIO server outputs an ARN for each configured
notification target at server startup. See
:ref:`minio-bucket-notifications` for more
information.
.. mc-cmd:: event
:option:
*Optional* The event(s) to remove. Specify multiple events using a comma
``,`` delimiter. See :ref:`mc-event-supported-events` for supported events.
Defaults to removing all events on the :mc-cmd:`~mc event remove ALIAS`
bucket with the :mc-cmd-option:`~mc event remove ARN` notification target.
.. mc-cmd:: force
:option:
*Optional* Removes all events on the :mc-cmd:`~mc event remove ALIAS` bucket
with the :mc-cmd-option:`~mc event remove ARN` notification target.
.. mc-cmd:: prefix
:option:
*Optional* The bucket prefix in which the command removes bucket
notifications.
For example, given a :mc-cmd:`~mc event remove ALIAS` of
``play/mybucket`` and a :mc-cmd-option:`~mc event remove prefix` of
``photos``, the command only removes bucket notifications in
``play/mybucket/photos``.
.. mc-cmd:: suffix
:option:
*Optional* The bucket suffix in which the command removes bucket
notifications.
For example, given a :mc-cmd:`~mc event remove ALIAS` of
``play/mybucket`` and a :mc-cmd-option:`~mc event remove suffix` of
``.jpg``, the command only removes bucket notifications in
``play/mybucket/*.jpg``.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Remove Event Notifications from a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Example
The following command removes all event notification triggers on a bucket.
The command assumes the MinIO deployment has at least one configured
:ref:`bucket notification target <minio-bucket-notifications>`:
.. code-block:: shell
:class: copyable
mc event remove myminio/mydata arn:minio:sqs::primary:webhook
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
mc event remove ALIAS ARN
- Replace ``ALIAS`` with the :ref:`alias <alias>` of the MinIO
deployment on which to add the bucket notification event. For example:
``myminio/mydata``
- Replace ``ARN`` with the notification target
:mc-cmd:`ARN <mc event add ARN>`.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

312
source/reference/minio-mc/mc-find.rst Normal file
View File

@ -0,0 +1,312 @@
.. _minio-mc-find:
===========
``mc find``
===========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc find
Syntax
------
.. start-mc-find-desc
The :mc:`mc find` command supports searching for objects on a MinIO
deployment. You can also use the command to search for files on a filesystem.
.. end-mc-find-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command searches for all objects matching the specified
pattern in the ``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc find myminio/mydata --name "*.jpg"
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] find \
[--exec "string"] \
[--ignore "string"] \
[--larger "string"] \
[--maxdepth "string"] \
[--name "string"] \
[--newer-than "string"] \
[--older-than "string"] \
[--path "string"] \
[--print "string"] \
[--regex "string"] \
[--smaller "string"] \
[--watch] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required*
For objects on MinIO or an S3-compatible host, specify the
:ref:`alias <alias>` and the full path to search
(e.g. bucket and prefixes). For example:
.. code-block:: none
mc find play/mydata/
For objects on a filesyste, specify the full path to search. For
example:
.. code-block:: shell
mc find ~/mydata/
Issuing :mc-cmd:`mc find ALIAS` with no other arguments returns a list of
*all* objects or files at the specified path, similar to :mc-cmd:`mc ls`.
.. mc-cmd:: exec
:option:
*Optional* Spawns an external process for each object returned by
:mc:`mc find`. Supports :ref:`substitution formatting
<mc-find-substitution-format>` of the output.
.. mc-cmd:: ignore
:option:
*Optional* Exclude objects whose names match the specified wildcard pattern.
.. mc-cmd:: larger
:option:
*Optional* Match all objects larger than the specified size in
:ref:`units <mc-find-units>`.
.. mc-cmd:: maxdepth
:option:
*Optional* Limits directory navigation to the specified depth.
.. mc-cmd:: name
:option:
*Optional* Return objects whose names match the specified wildcard pattern.
.. mc-cmd:: newer-than
:option:
*Optional* Mirror object(s) newer than the specified number of days. Specify
a string in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``
.. mc-cmd:: older-than
:option:
*Optional* Mirror object(s) older than the specified time limit. Specify a
string in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``
Defaults to ``0`` (all objects).
.. mc-cmd:: path
:option:
*Optional* Return the contents of directories whose names match the specified
wildcard pattern.
.. mc-cmd:: print
:option:
*Optional* Prints results to ``STDOUT``. Supports
:ref:`substitution formatting <mc-find-substitution-format>` of the output.
.. mc-cmd:: regex
:option:
*Optional* Returns objects or the contents of directories whose names match
the specified PCRE regex pattern.
.. mc-cmd:: smaller
:option:
*Optional* Match all objects smaller than the specifized size in
:ref:`units <mc-find-units>`.
.. mc-cmd:: watch
:option:
*Optional* Continuously monitor the :mc-cmd:`~mc find ALIAS` and return any
new objects which match the specified criteria.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Find a Specific Object in a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: shell
:class: copyable
mc find ALIAS/PATH --name NAME
- Replace :mc-cmd:`ALIAS <mc find ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc find ALIAS>` with the path to a bucket on the
S3-compatible host. Omit the path to search from the root of the S3 host.
- Replace :mc-cmd:`NAME <mc find name>` with the object.
Find Objects with File Extention in Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: shell
:class: copyable
mc find ALIAS/PATH --name *.EXTENSION
- Replace :mc-cmd:`ALIAS <mc find ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc find ALIAS>` with the path to a bucket on the
S3-compatible host.
- Replace :mc-cmd:`EXTENSION <mc find name>` with the file extention of the
object.
Find All Matching Files and Copy To S3 Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc:`mc find` with the :mc-cmd-option:`~mc find exec` option to find
files on a local filesystem and pass them to an :program:`mc` command for
further processing. The following example uses :mc:`mc cp` to copy the
output of :mc:`mc find` to an S3-compatible host.
.. code-block:: shell
:class: copyable
mc find FILEPATH --name "*.EXTENSION" --exec "mc cp {} ALIAS/PATH"
- Replace :mc-cmd:`FILEPATH <mc find ALIAS>` with the full file path to the
directory to search.
- Replace :mc-cmd:`EXTENSION <mc find name>` with the file extention of the
object.
- Replace :mc-cmd:`ALIAS <mc find ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc find ALIAS>` with the path to a bucket on the
S3-compatible host.
To continuously watch the specified directory and copy new objects,
include the :mc-cmd-option:`~mc find watch` argument:
.. code-block:: shell
:class: copyable
mc find --watch FILEPATH --name "*.EXTENSION" --exec "mc cp {} ALIAS/PATH"
Behavior
--------
.. _mc-find-units:
Units of Measurement
~~~~~~~~~~~~~~~~~~~~
The :mc-cmd-option:`mc find smaller` and :mc-cmd-option:`mc find larger` flags
accept the following case-insensitive suffixes to represent the unit of the
specified size value:
.. list-table::
:header-rows: 1
:widths: 20 80
:width: 100%
* - Suffix
- Unit Size
* - ``k``
- KB (Kilobyte, 1000 Bytes)
* - ``m``
- MB (Megabyte, 1000 Kilobytes)
* - ``g``
- GB (Gigabyte, 1000 Megabytes)
* - ``t``
- TB (Terrabyte, 1000 Gigabytes)
* - ``ki``
- KiB (Kibibyte, 1024 Bites)
* - ``mi``
- MiB (Mebibyte, 1024 Kibibytes)
* - ``gi``
- GiB (Gibibyte, 1024 Mebibytes)
* - ``ti``
- TiB (Tebibyte, 1024 Gibibytes)
Omitting the suffix defaults to ``bytes``.
.. _mc-find-substitution-format:
Substitution Format
~~~~~~~~~~~~~~~~~~~
The :mc-cmd-option:`mc find exec` and :mc-cmd-option:`mc find print` commands
support string substitutions with special interpretations for following
keywords.
The following keywords are supported for both filesystem and S3 service targets:
- ``{}`` - Substitutes to full path.
- ``{base}`` - Substitutes to basename of path.
- ``{dir}`` - Substitutes to dirname of the path.
- ``{size}`` - Substitutes to object size of the path.
- ``{time}`` - Substitutes to object modified time of the path.
The following keyword is supported only for S3 service targets:
- ``{url}`` - Substitutes to a shareable URL of the path.
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

197
source/reference/minio-cli/minio-mc/mc-head.rst → source/reference/minio-mc/mc-head.rst
View File

@ -1,3 +1,5 @@
.. _minio-mc-head:
===========
``mc head``
===========
@ -10,8 +12,14 @@
.. mc:: mc head
Description
-----------
.. |command| replace:: :mc-cmd:`mc head`
.. |rewind| replace:: :mc-cmd-option:`~mc head rewind`
.. |versionid| replace:: :mc-cmd-option:`~mc head version-id`
.. |alias| replace:: :mc-cmd-option:`~mc head ALIAS`
Syntax
------
.. start-mc-head-desc
@ -21,7 +29,109 @@ where ``n`` is an argument specified to the command.
.. end-mc-head-desc
:mc:`mc head` does not perform any transformation or formatting of object
contents to facilitate readability.
contents to facilitate readability. You can also use :mc:`mc head` against
the local filesystem to produce similar results to the ``head`` commandline
tool.
.. tab-set::
.. tab-item:: EXAMPLE
The following command returns the first 10 lines of an object in the
``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc head myminio/mydata/myobject.txt
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] head \
[--lines int] \
[--rewind "string"] \
[--version-id "string"] \
[--encrypt-key "string"] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The object or objects to print.
For an object on MinIO or another S3-compatible service, specify the
:ref:`alias <alias>` and the full path to that object (e.g. bucket and path
to object). For example:
For example:
.. code-block:: none
mc head play/mybucket/object.txt
For an object on a local filesystem, specify the full path to that object.
For example:
.. code-block:: none
mc head ~/mydata/object.txt
.. mc-cmd:: lines, n
:option:
*Optional* The number of lines to print.
Defaults to ``10``.
.. mc-cmd:: encrypt-key
:option:
*Optional* Encrypt or decrypt objects using server-side encryption with
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc head encrypt-key` in double quotes ``"``.
:mc-cmd-option:`~mc head encrypt-key` can use the ``MC_ENCRYPT_KEY``
environment variable for retrieving a list of encryption key-value pairs
as an alternative to specifying them on the command line.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
@ -36,10 +146,10 @@ Use :mc-cmd:`mc head` to return the first 10 lines of an object:
mc head ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc head SOURCE>` with the
- Replace :mc-cmd:`ALIAS <mc head ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc head SOURCE>` with the path to the object on the
- Replace :mc-cmd:`PATH <mc head ALIAS>` with the path to the object on the
S3-compatible host.
View Partial Contents of an Object at a Point in Time
@ -53,10 +163,10 @@ object at a specific point-in-time in the past:
mc head ALIAS/PATH --rewind DURATION
- Replace :mc-cmd:`ALIAS <mc head SOURCE>` with the
- Replace :mc-cmd:`ALIAS <mc head ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc head SOURCE>` with the path to the object on the
- Replace :mc-cmd:`PATH <mc head ALIAS>` with the path to the object on the
S3-compatible host.
- Replace :mc-cmd:`DURATION <mc head rewind>` with the point-in-time in the past
@ -78,10 +188,10 @@ object at a specific point-in-time in the past:
mc head ALIAS/PATH --version-id VERSION
- Replace :mc-cmd:`ALIAS <mc head SOURCE>` with the
- Replace :mc-cmd:`ALIAS <mc head ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc head SOURCE>` with the path to the object on the
- Replace :mc-cmd:`PATH <mc head ALIAS>` with the path to the object on the
S3-compatible host.
- Replace :mc-cmd:`VERSION <mc head version-id>` with the version of the object.
@ -92,68 +202,13 @@ object at a specific point-in-time in the past:
:start-after: start-versioning-admonition
:end-before: end-versioning-admonition
Syntax
------
.. |command| replace:: :mc-cmd:`mc head`
.. |rewind| replace:: :mc-cmd-option:`~mc head rewind`
.. |versionid| replace:: :mc-cmd-option:`~mc head version-id`
.. |alias| replace:: :mc-cmd-option:`~mc head SOURCE`
Behavior
--------
:mc:`~mc head` has the following syntax:
S3 Compatibility
~~~~~~~~~~~~~~~~
.. code-block:: shell
mc head [FLAGS] SOURCE [SOURCE...]
:mc:`~mc head` supports the following arguments:
.. mc-cmd:: --lines, -n
The number of lines to print.
Defaults to ``10``.
.. mc-cmd:: SOURCE
**REQUIRED**
The object or objects to print. You can specify both local paths
and S3 paths using a configured S3 service :mc:`alias <mc alias>`.
For example:
.. code-block:: none
mc head play/mybucket/object.txt ~/localfiles/mybucket/object.txt
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
.. mc-cmd:: encrypt-key
:option:
Encrypt or decrypt objects using server-side encryption with
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc head encrypt-key` in double quotes ``"``.
:mc-cmd-option:`~mc head encrypt-key` can use the ``MC_ENCRYPT_KEY``
environment variable for retrieving a list of encryption key-value pairs
as an alternative to specifying them on the command line.
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

288
source/reference/minio-mc/mc-ilm-add.rst Normal file
View File

@ -0,0 +1,288 @@
.. _minio-mc-ilm-add:
==============
``mc ilm add``
==============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc ilm add
Syntax
------
.. start-mc-ilm-add-desc
The :mc:`mc ilm add` command adds an object lifecycle management rule to a
bucket.
.. end-mc-ilm-add-desc
The command supports adding both
:ref:`Transition (Tiering) <minio-lifecycle-management-tiering>` and
:ref:`Expiration <minio-lifecycle-management-expiration>` lifecycle management
rules.
.. tab-set::
.. tab-item:: EXAMPLE
The following command adds new lifecycle management rules to the
``mydata`` bucket on the ``myminio`` deployment:
.. code-block:: shell
:class: copyable
mc ilm add --expiry-days 90 --noncurrentversion-expiry-days 30 mydata/myminio
mc ilm add --expired-object-delete-marker mydata/myminio
mc ilm add --transition-days 30 --storage-class "COLDTIER" mydata/myminio
mc ilm add --noncurrentversion-transition-days 7 --noncurrent-version-transition-storage-class "COLDTIER"
The configured rules have the following effect:
- Delete objects more than 90 days old
- Delete objects 30 days after they become non-current
- Delete ``DeleteMarker`` tombstones if that object has no other versions
remaining.
- Transition objects more than 30 days old to the ``COLDTIER`` remote
tier.
- Transition objects 7 days after they become non-current to the
``COLDTIER`` remote tier.
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] ilm add \
--expiry-days "string" | --expired-object-delete-marker \
--transition-days "string" --storage-class "string" \
[--noncurrentversion-expiration-days "string"] \
[--noncurrentversion-transition-days "string" --noncurrentversion-transition-storage-class "string"] \
[--tags] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The :ref:`alias <alias>` and full path to the bucket on the MinIO
deployment to which to add the object lifecycle management rule. For example:
.. code-block:: none
mc ilm add myminio/mydata
To restrict the management rule to a specific bucket prefix, specify that
prefix as part of the ``ALIAS``. For example:
.. code-block:: none
mc ilm add myminio/mydata/someprefix
.. mc-cmd:: expiry-days
:option:
*Required* 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, e.g. ``30`` for 30 days.
For versioned buckets, the expiry rule applies only to the *current*
object version. Use the
:mc-cmd-option:`~mc ilm add noncurrentversion-expiration-days` option
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 :ref:`minio-lifecycle-management-scanner` for more information.
Mutually exclusive with the following options:
- :mc-cmd-option:`~mc ilm add expired-object-delete-marker`
For more complete documentation on object expiration, see
:ref:`minio-lifecycle-management-expiration`.
.. mc-cmd:: expired-object-delete-marker
:option:
*Required* 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:
- :mc-cmd-option:`~mc ilm add tags`
- :mc-cmd-option:`~mc ilm add expiry-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 :ref:`minio-lifecycle-management-scanner` for more information.
For more complete documentation on object expiration, see
:ref:`minio-lifecycle-management-expiration`.
.. mc-cmd:: transition-days
:option:
*Required* 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 storage tier specified to the
:mc-cmd-option:`~mc ilm add storage-class`. Specify the number of days as an
integer, e.g. ``30`` for 30 days.
For versioned buckets, the transition rule applies only to the *current*
object version. Use the
:mc-cmd-option:`~mc ilm add noncurrentversion-transition-days` option
to apply transition behavior to noncurrent object versions.
Requires specifying :mc-cmd-option:`~mc ilm add storage-class`.
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 :ref:`minio-lifecycle-management-scanner` for more information.
For more complete documentation on object transition, see
:ref:`minio-lifecycle-management-tiering`.
.. mc-cmd:: storage-class
:option:
*Required* The remote storage tier to which MinIO
:ref:`transition objects <minio-lifecycle-management-tiering>`.
Specify a remote storage tier created by :mc-cmd:`mc admin tier`.
Required if specifying :mc-cmd-option:`~mc ilm add transition-days`.
.. mc-cmd:: tags
:option:
*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:
- :mc-cmd-option:`~mc ilm add expired-object-delete-marker`
.. mc-cmd:: noncurrentversion-expiration-days
:option:
*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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: noncurrentversion-transition-days
:option:
*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 storage tier specified to the
:mc-cmd-option:`~mc ilm add storage-class` once the system host datetime
passes that calendar date.
This option has no effect on non-versioned buckets. Requires specifying
:mc-cmd-option:`~mc ilm add noncurrentversion-transition-storage-class`.
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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: noncurrentversion-transition-storage-class
:option:
*Optional* The remote storage tier to which MinIO
:ref:`transitions noncurrent objects versions
<minio-lifecycle-management-tiering>`. Specify a remote storage tier created
by :mc-cmd:`mc admin tier`.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Expire Bucket Contents After Number of Days
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc ilm add` with :mc-cmd-option:`~mc ilm add expiry-days` to
expire bucket contents a number of days after object creation:
.. code-block:: shell
:class: copyable
mc ilm add ALIAS/PATH --expiry-days "DAYS"
- Replace :mc-cmd:`ALIAS <mc ilm add ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ilm add ALIAS>` with the path to the bucket on the
S3-compatible host.
- Replace :mc-cmd:`DATE <mc ilm add expiry-days>` with the number of days after
which to expire the object. For example, specify ``30`` to expire the
object 30 days after creation.
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 :ref:`minio-lifecycle-management-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-cmd:`mc ilm ls` to review the currently configured object lifecycle
management rules for any potential interactions between expiry and transition
rules.
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

268
source/reference/minio-mc/mc-ilm-edit.rst Normal file
View File

@ -0,0 +1,268 @@
.. _minio-mc-ilm-edit:
===============
``mc ilm edit``
===============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc ilm edit
Syntax
------
.. start-mc-ilm-edit-desc
The :mc:`mc ilm edit` command modifies an existing object lifecycle management
rule on a MinIO bucket.
.. end-mc-ilm-edit-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command modifies existing lifecycle management rules for
the ``mydata`` bucket on the ``myminio`` deployment:
.. code-block:: shell
:class: copyable
mc ilm edit --id "c79ntj94b0t6rukh6lr0" --expiry-days 90 mydata/myminio
mc ilm edit --id "c79nu2p4b0t6qko19rgg" --expired-object-delete-marker mydata/myminio
mc ilm edit --id "c79n19dn10dnab109fg1" --transition-days 30 --storage-class "COLDTIER"
The command modifies the specified rules as follows:
- Delete objects more than 90 days old.
- Delete ``DeleteMarker`` tombstones if that object has no other versions
remaining.
- Transition objects more than 30 days old to the ``COLDTIER`` remote
tier.
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] ilm edit \
--id "string" \
[--expiry-days "string" | --expired-object-delete-marker] \
[--transition-days "string"] --storage-class "string" \
[--noncurrentversion-expiration-days "string"] \
[--noncurrentversion-transition-days "string" --noncurrentversion-transition-storage-class "string"] \
[--tags] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The :ref:`alias <alias>` and full path to the bucket on the MinIO
deployment to which to modify the object lifecycle management rule. For
example:
.. code-block:: none
mc ilm edit myminio/mydata
.. mc-cmd:: id
:option:
*Required* The unique ID of the rule. Use :mc-cmd:`mc ilm ls` to list bucket
rules and retrieve the ``id`` for the rule you want to modify.
.. mc-cmd:: expiry-days
:option:
*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.
Exercise caution when using this option, as its behavior can result in
immediate expiration of uploaded objects. Any objects created *after*
the specified expiration date are automatically eligible for expiration.
Similarly, specifying a calendar date that is *prior* to the current
system host datetime marks all objects covered by the rule for deletion.
Consider immediately removing any ILM rule using this option once the
specified calendar date has passed.
For versioned buckets, the expiry rule applies only to the *current*
object version. Use the
:mc-cmd-option:`~mc ilm edit noncurrentversion-expiration-days` option
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 :ref:`minio-lifecycle-management-scanner` for more information.
Mutually exclusive with the following options:
- :mc-cmd-option:`~mc ilm edit expired-object-delete-marker`
.. mc-cmd:: expired-object-delete-marker
:option:
*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:
- :mc-cmd-option:`~mc ilm edit tags`
- :mc-cmd-option:`~mc ilm edit expiry-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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: noncurrentversion-expiration-days
:option:
*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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: noncurrentversion-transition-days
:option:
*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 storage tier specified to the
:mc-cmd-option:`~mc ilm edit storage-class` once the system host datetime
passes that calendar date.
This option has no effect on non-versioned buckets. Requires specifying
:mc-cmd-option:`~mc ilm edit noncurrentversion-transition-storage-class`.
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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: noncurrentversion-transition-storage-class
:option:
*Optional* The remote storage tier to which MinIO
:ref:`transitions noncurrent objects versions
<minio-lifecycle-management-tiering>`. Specify a remote storage tier created
by :mc-cmd:`mc admin tier`.
MinIO does *not* automatically migrate objects from the previously
specified remote tier to the new remote tier. MinIO continues to
route requests for objects stored on the old remote tier.
.. mc-cmd:: tags
:option:
*Optional* One or more ampersand ``&``-delimited key-value pairs describing
the object tags to which to apply the lifecycle configuration rule.
This option is mutually exclusive with the following option:
- :mc-cmd-option:`~mc ilm edit expired-object-delete-marker`
.. mc-cmd:: transition-days
:option:
*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 storage tier specified to the
:mc-cmd-option:`~mc ilm edit storage-class`.
For versioned buckets, the transition rule applies only to the *current*
object version. Use the
:mc-cmd-option:`~mc ilm edit noncurrentversion-transition-days` option
to apply transition behavior to noncurrent object versions.
Requires specifying :mc-cmd-option:`~mc ilm edit storage-class`.
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 :ref:`minio-lifecycle-management-scanner` for more information.
.. mc-cmd:: storage-class
:option:
*Optional* The remote storage tier to which MinIO
:ref:`transition objects <minio-lifecycle-management-tiering>`. Specify a
remote storage tier created by :mc-cmd:`mc admin tier`.
Required if specifying :mc-cmd-option:`~mc ilm edit transition-days`.
MinIO does *not* automatically migrate objects from the previously
specified remote tier to the new remote tier. MinIO continues to
route requests for objects stored on the old remote tier.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Modify an Existing Lifecycle Management Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc ilm edit` with :mc-cmd-option:`~mc ilm edit id` to modify
an existing object expiration rule:
.. code-block:: shell
:class: copyable
mc ilm edit ALIAS/PATH --id "RULEID" [FLAGS]
- Replace :mc-cmd:`ALIAS <mc ilm edit ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ilm edit ALIAS>` with the path to the bucket on the
S3-compatible host.
- Replace ``RULEID`` with the unique ID of the object lifecycle management
rule.
- Specify any additional flags to add or modify the lifecycle management
rule. For example, specify
:mc-cmd:`~mc ilm edit transition-days` to override the existing
transition days value for the rule.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

119
source/reference/minio-mc/mc-ilm-export.rst Normal file
View File

@ -0,0 +1,119 @@
.. _minio-mc-ilm-export:
=================
``mc ilm export``
=================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc ilm export
Syntax
------
.. start-mc-ilm-export-desc
The :mc:`mc ilm export` command exports the object lifecycle management
configuration for a MinIO bucket.
.. end-mc-ilm-export-desc
The :mc:`mc ilm export` command outputs to ``STDOUT`` by default. You can
output the contents to a ``.json`` file for archival or ingestion using
:mc:`mc ilm import`.
.. tab-set::
.. tab-item:: EXAMPLE
The following command exports the lifecycle management configuration
of the ``mydata`` bucket on the ``myminio`` deployment to the
``mydata-lifecycle-config.json`` file:
.. code-block:: shell
:class: copyable
mc ilm export myminio/mydata > mydata-lifecycle-config.json
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] ilm export ALIAS > STDOUT
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The :ref:`alias <alias>` and full path to the bucket on the MinIO
deployment for which to export object lifecycle management rules. For
example:
.. code-block:: none
mc ilm export myminio/mydata > bucket-lifecycle.json
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Export the Bucket Lifecycle Management Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Example
The following command exports the bucket lifecycle management
configuration to the ``bucket-lifecycle.json`` file:
.. code-block:: shell
:class: copyable
mc ilm export myminio/mybucket > bucket-lifecycle.json
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
mc ilm export ALIAS > file.json
- Replace ``ALIAS`` with the :ref:`alias <alias>` of the MinIO
deployment and the bucket for which to export object lifecycle
management rules:
``myminio/mydata``
- Replace ``file.json`` with the name of the file to which to export the
lifecycle management rules.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

126
source/reference/minio-mc/mc-ilm-import.rst Normal file
View File

@ -0,0 +1,126 @@
.. _minio-mc-ilm-import:
=================
``mc ilm import``
=================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc ilm import
Syntax
------
.. start-mc-ilm-import-desc
The :mc:`mc ilm import` command imports an object lifecycle management
configuration and applies it to a MinIO bucket.
.. end-mc-ilm-import-desc
The :mc:`mc ilm import` command imports from ``STDIN`` by default. You can
input the contents from a ``.json`` file, such as one produced by
:mc:`mc ilm export`.
.. tab-set::
.. tab-item:: EXAMPLE
The following command imports the lifecycle management configuration from
``mydata-lifecycle-config.json`` and applies it to the ``mydata`` bucket
on the ``myminio`` deployment:
.. code-block:: shell
:class: copyable
mc ilm import myminio/mydata <> mydata-lifecycle-config.json
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] ilm import ALIAS < STDIN
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The :ref:`alias <alias>` and full path to the bucket on the MinIO
deployment into which to import object lifecycle management rules. For
example:
.. code-block:: none
mc ilm import myminio/mydata < bucket-lifecycle.json
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Import the Bucket Lifecycle Management Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
.. tab-item:: Example
The following command imports the bucket lifecycle management
configuration from the ``bucket-lifecycle.json`` file:
.. code-block:: shell
:class: copyable
mc ilm import myminio/mybucket < bucket-lifecycle.json
.. tab-item:: Syntax
.. code-block:: shell
:class: copyable
mc ilm import ALIAS < file.json
- Replace ``ALIAS`` with the :ref:`alias <alias>` of the MinIO
deployment and the bucket into which to import object lifecycle
management rules:
``myminio/mydata``
- Replace ``file.json`` with the name of the file from which to import the
lifecycle management rules.
Behavior
--------
Importing Configuration Overrides Existing Rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:mc-cmd:`mc ilm import` replaces the current bucket lifecycle management
rules with those defined in the imported JSON configuration.
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

116
source/reference/minio-mc/mc-ilm-ls.rst Normal file
View File

@ -0,0 +1,116 @@
.. _minio-mc-ilm-ls:
=============
``mc ilm ls``
=============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc ilm ls
Syntax
------
.. start-mc-ilm-ls-desc
The :mc:`mc ilm ls` command lists all configured object lifecycle management
rules on a MinIO bucket.
.. end-mc-ilm-ls-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command lists all lifecycle management rules for the
``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc ilm ls myminio/mydata
.. tab-item:: SYNTAX
The :mc-cmd:`mc ilm ls` command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] ilm ls \
[--expiry | --transition] \
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The :ref:`alias <alias>` and full path to the bucket on the MinIO
deployment for which to list the object lifecycle management rules. For
example:
.. code-block:: none
mc ilm ls myminio/mydata
.. mc-cmd:: expiry
:option:
*Optional* :mc-cmd:`mc ilm ls` returns only fields related to lifecycle rule
expiration.
Mutually exclusive with :mc-cmd-option:`~mc ilm ls transition`.
.. mc-cmd:: transition
:option:
*Optional* :mc-cmd:`mc ilm ls` returns only fields related to lifecycle rule
transition.
Mutually exclusive with :mc-cmd-option:`~mc ilm ls expiry`.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
List Bucket Lifecycle Management Rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc ilm ls` to list a bucket's lifecycle management rules:
.. code-block:: shell
:class: copyable
mc ilm ls ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc ilm ls ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ilm ls ALIAS>` with the path to the bucket on the
S3-compatible host.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

162
source/reference/minio-mc/mc-ilm-restore.rst Normal file
View File

@ -0,0 +1,162 @@
.. _minio-mc-ilm-restore:
==================
``mc ilm restore``
==================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc ilm restore
Syntax
------
.. start-mc-ilm-restore-desc
The :mc:`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.
.. end-mc-ilm-restore-desc
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.
.. tab-set::
.. tab-item:: EXAMPLE
The following command restores a copy of a transitioned object from the
remote tier back to the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc ilm restore myminio/mybucket/object.txt
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] ilm restore \
[--days "int" ] \
[--recursive] \
[--vid "string"] \
[--versions] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The MinIO :ref:`alias <alias>`, bucket, and path to the
archived object to restore.
.. code-block:: shell
mc ilm restore myminio/mybucket/object.txt
.. mc-cmd:: days value
:option:
*Optional* The number of days after which MinIO expires the restored copy
of the archived object.
.. mc-cmd:: recursive, r
:option:
*Optional* Restores all objects under the specified prefix.
.. mc-cmd:: versions
:option:
*Optional* Restores all versions of the object on the remote tier.
.. mc-cmd:: version-id, vid
:option:
*Optional* Restores the specified version of the object on the remote tier.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Restore an Archived Object
~~~~~~~~~~~~~~~~~~~~~~~~~~
The following command restores an object archived to a remote tier:
.. code-block:: shell
:class: copyable
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:
.. code-block:: shell
:class: copyable
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:
.. code-block:: shell
:class: copyable
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
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

122
source/reference/minio-mc/mc-ilm-rm.rst Normal file
View File

@ -0,0 +1,122 @@
.. _minio-mc-ilm-rm:
=============
``mc ilm rm``
=============
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc ilm rm
Syntax
------
.. start-mc-ilm-rm-desc
The :mc:`mc ilm rm` command removes an object lifecycle management rule from a
MinIO Bucket.
.. end-mc-ilm-rm-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command removes a single lifecycle management rule from
the ``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc ilm rm --id "bgrt1ghju" myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] ilm rm \
--id "string" | (--all --force) \
ALIAS \
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The :ref:`alias <alias>` and full path to the bucket on the MinIO
deployment to which to remove the object lifecycle management rule. For
example:
.. code-block:: none
mc ilm rm myminio/mydata
.. mc-cmd:: all
*Required* Removes all rules in the bucket. Mutually exclusive with
:mc-cmd-option:`mc ilm rm id`.
Mutually exclusive with :mc-cmd-option:`mc ilm rm id`
Requires including :mc-cmd-option:`~mc ilm rm force`.
.. mc-cmd:: force
Required if specifying :mc-cmd-option:`~mc ilm rm all`.
.. mc-cmd:: id
*Required* The unique ID of the rule. Use :mc-cmd:`mc ilm ls` to list bucket
rules and retrieve the ``id`` for the rule you want to remove.
Mutually exclusive with :mc-cmd-option:`mc ilm rm all`
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Remove a Bucket Lifecycle Management Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc ilm rm` to remove a bucket lifecycle management rule:
.. code-block:: shell
:class: copyable
mc ilm rm --id "RULE" ALIAS/PATH
- Replace :mc-cmd:`RULE <mc ilm rm id>` with the unique name of the lifecycle
management rule.
- Replace :mc-cmd:`ALIAS <mc ilm rm ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ilm rm ALIAS>` with the path to the bucket on the
S3-compatible host.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

135
source/reference/minio-mc/mc-legalhold-clear.rst Normal file
View File

@ -0,0 +1,135 @@
.. _minio-mc-legalhold-clear:
======================
``mc legalhold clear``
======================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc legalhold clear
.. |command| replace:: :mc-cmd:`mc legalhold clear`
.. |rewind| replace:: :mc-cmd-option:`~mc legalhold clear rewind`
.. |versionid| replace:: :mc-cmd-option:`~mc legalhold clear version-id`
.. |alias| replace:: :mc-cmd-option:`~mc legalhold clear ALIAS`
Syntax
------
.. start-mc-legalhold-clear-desc
The :mc:`mc legalhold clear` command removes the current :ref:`legal hold
<minio-object-locking-legalhold>` setting for an object or objects.
.. end-mc-legalhold-clear-desc
Removing the legal hold on object(s) does *not* remove any other
:ref:`minio-object-locking-governance` and
:ref:`minio-object-locking-compliance` retention settings in place for
the object(s)
.. tab-set::
.. tab-item:: EXAMPLE
The following command removes the legal hold on all objects in the
``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc legalhold clear --recursive myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] legalhold clear \
[--recursive] \
[--rewind] \
[--version-id] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The MinIO :ref:`alias <alias>` and path to the object or
objects on which to remove the legal hold. For example:
.. code-block:: shell
mc legalhold clear play/mybucket/myobjects/objects.txt
.. mc-cmd:: recursive, r
:option:
Removes the legal hold on all objects in the
:mc-cmd:`~mc legalhold clear ALIAS` bucket or bucket prefix.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Retrieve the Legal Hold Status Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc legalhold clear` to retrieve the legal hold status of an object.
Include :mc-cmd-option:`~mc legalhold clear recursive` to return the legal hold
status of the contents of a bucket:
.. code-block:: shell
:class: copyable
mc legalhold clear [--recursive] ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc legalhold clear ALIAS>` with the
:ref:`alias <alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc legalhold clear ALIAS>` 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 :mc-cmd-option:`~mc legalhold clear recursive`
option.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

135
source/reference/minio-mc/mc-legalhold-info.rst Normal file
View File

@ -0,0 +1,135 @@
.. _minio-mc-legalhold-info:
=====================
``mc legalhold info``
=====================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc legalhold info
.. |command| replace:: :mc-cmd:`mc legalhold info`
.. |rewind| replace:: :mc-cmd-option:`~mc legalhold info rewind`
.. |versionid| replace:: :mc-cmd-option:`~mc legalhold info version-id`
.. |alias| replace:: :mc-cmd-option:`~mc legalhold info ALIAS`
Syntax
------
.. start-mc-legalhold-info-desc
The :mc:`mc legalhold info` command returns the current :ref:`legal hold
<minio-object-locking-legalhold>` setting for an object or objects.
.. end-mc-legalhold-info-desc
:mc:`mc legalhold` *requires* that the specified bucket has object locking
enabled. You can **only** enable object locking at bucket creation. See
:mc-cmd-option:`mc mb with-lock` for documentation on creating buckets with
object locking enabled.
.. tab-set::
.. tab-item:: EXAMPLE
The following command retrieves the current legalhold status for objects
in the ``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc legalhold info --recursive myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] legalhold info \
[--recursive] \
[--rewind] \
[--version-id] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The MinIO :ref:`alias <alias>` and path to the object or
objects on which to enable the legal hold. For example:
.. code-block:: shell
mc legalhold info play/mybucket/myobjects/objects.txt
.. mc-cmd:: recursive, r
:option:
Returns the legal hold status of all objects in the
:mc-cmd:`~mc legalhold info ALIAS` bucket or bucket prefix.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Retrieve the Legal Hold Status Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc legalhold info` to retrieve the legal hold status of an object.
Include :mc-cmd-option:`~mc legalhold info recursive` to return the legal hold
status of the contents of a bucket:
.. code-block:: shell
:class: copyable
mc legalhold clear [--recursive] ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc legalhold info ALIAS>` with the
:ref:`alias <alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc legalhold info ALIAS>` 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 :mc-cmd-option:`~mc legalhold info recursive`
option.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

149
source/reference/minio-mc/mc-legalhold-set.rst Normal file
View File

@ -0,0 +1,149 @@
.. _minio-mc-legalhold-set:
====================
``mc legalhold set``
====================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc legalhold
.. mc:: mc legalhold set
.. |command| replace:: :mc-cmd:`mc legalhold set`
.. |rewind| replace:: :mc-cmd-option:`~mc legalhold set rewind`
.. |versionid| replace:: :mc-cmd-option:`~mc legalhold set version-id`
.. |alias| replace:: :mc-cmd-option:`~mc legalhold set ALIAS`
Syntax
------
.. start-mc-legalhold-set-desc
The :mc:`mc legalhold set` command enables :ref:`legal hold
<minio-object-locking-legalhold>` Write-Once Read-Many (WORM) object locking on
an object or objects.
.. end-mc-legalhold-set-desc
:mc:`mc legalhold` *requires* that the specified bucket has
:ref:`object locking enabled <minio-object-locking>`. You can **only** enable
object locking at bucket creation. See :mc-cmd-option:`mc mb with-lock` for
documentation on creating buckets with object locking enabled.
.. tab-set::
.. tab-item:: EXAMPLE
The following command enables legalhold WORM locking on all objects
in the ``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc legalhold set --recursive myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] legalhold set \
[--recursive] \
[--rewind] \
[--version-id] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The MinIO :ref:`alias <alias>` and path to the object or
objects on which to enable the legal hold. For example:
.. code-block:: shell
mc legalhold set play/mybucket/myobjects/objects.txt
.. mc-cmd:: recursive, r
:option:
*Optional* Applies the legal hold to all objects in the
:mc-cmd:`~mc legalhold set ALIAS` bucket or bucket prefix.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
.. mc-cmd:: version-id, vid
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Use :mc-cmd:`mc legalhold set` to enable legal hold on objects:
.. code-block:: shell
:class: copyable
mc legalhold set [--recursive] ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc legalhold set ALIAS>` with the
:ref:`alias <alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc legalhold set ALIAS>` 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 :mc-cmd-option:`~mc legalhold set recursive`
option.
Behavior
--------
Legal Holds Require Explicit Removal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Legal Holds are indefinite and enforce complete immutability for locked objects.
Only privileged users with the :policy-action:`s3:PutObjectLegalHold` can set or
lift the Legal Hold.
Legal Holds Complement Other Retention Modes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Legal holds are complementary to both :ref:`minio-object-locking-governance` and
:ref:`minio-object-locking-compliance` retention settings. An object held under
both legal hold *and* a ``GOVERNANCE/COMPLIANCE`` retention rule remains WORM
locked until the legal hold is lifed *and* the rule expires.
For ``GOVERNANCE`` locked objects, the legal hold prevents mutating the object
*even if* the user has the necessary privileges to bypass retention.
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

215
source/reference/minio-mc/mc-ls.rst Normal file
View File

@ -0,0 +1,215 @@
=========
``mc ls``
=========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc ls
.. Replacement substitutions
.. |command| replace:: :mc-cmd:`mc ls`
.. |rewind| replace:: :mc-cmd-option:`~mc ls rewind`
.. |versions| replace:: :mc-cmd-option:`~mc ls versions`
.. |alias| replace:: :mc-cmd-option:`~mc ls ALIAS`
Syntax
------
.. start-mc-ls-desc
The :mc:`mc ls` command lists buckets and objects on MinIO or another
S3-compatible service.
.. end-mc-ls-desc
You can also use :mc:`mc ls` against the local filesystem to produce similar
results as the ``ls`` command.
.. tab-set::
.. tab-item:: EXAMPLE
The following command lists all objects *and* object versions in the
``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc ls --recursive --versions myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] ls \
[--incomplete] \
[--recursive] \
[--rewind] \
[--versions] \
[--summarize] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The object or objects to copy.
For listing objects on MinIO or another S3-compatible service,
specify the :ref:`alias <alias>` and the full path to that
object (e.g. bucket and path to object). For example:
.. code-block:: none
mc ls play/mybucket/object.txt
For listing objects on a local filesystem, specify the full
path to that object. For example:
.. code-block:: none
mc ls ~/mydata/object.txt
If you specify a directory or bucket to :mc-cmd:`~mc ls ALIAS`, you must
also specify :mc-cmd-option:`~mc ls recursive` to recursively list the
contents of that directory or bucket. If you omit the ``--recursive``
argument, :mc:`~mc ls` only lists objects in the top level of the specified
directory or bucket.
.. mc-cmd:: incomplete, -I
:option:
*Optional* Returns any incomplete uploads on the specified
:mc-cmd:`~mc ls ALIAS` bucket.
.. mc-cmd:: recursive, r
:option:
*Optional* Recursively lists the contents of each bucket or directory in the
:mc-cmd:`~mc ls ALIAS`.
.. mc-cmd:: rewind
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
Use :mc-cmd-option:`~mc ls rewind` and
:mc-cmd-option:`~mc ls versions` together to display on those object
versions which existed at a specific point in time.
.. mc-cmd:: versions
:option:
.. include:: /includes/facts-versioning.rst
:start-after: start-versions-desc
:end-before: end-versions-desc
Use :mc-cmd-option:`~mc ls versions` and
:mc-cmd-option:`~mc ls rewind` together to display on those object
versions which existed at a specific point in time.
.. mc-cmd:: summarize
:option:
*Optional* Displays summarized information for the specified ``ALIAS`` path.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
List Bucket Contents
~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc ls <mc ls ALIAS>` to list the contents of a bucket:
.. code-block:: shell
:class: copyable
mc ls [--recursive] ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc ls ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ls ALIAS>` with the path to the bucket on the
S3-compatible host.
If specifying the path to the S3 root (``ALIAS`` only), include the
:mc-cmd-option:`~mc ls recursive` option.
List Object Versions
~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd-option:`mc ls versions` to list all versions of an object:
.. code-block:: shell
:class: copyable
mc ls --versions ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc ls ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ls ALIAS>` with the path to the bucket or object on
the S3-compatible host.
.. include:: /includes/facts-versioning.rst
:start-after: start-versioning-admonition
:end-before: end-versioning-admonition
List Bucket Contents at Point in Time
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd-option:`mc ls versions` to list all versions of an object:
.. code-block:: shell
:class: copyable
mc ls --rewind DURATION ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc ls ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`PATH <mc ls ALIAS>` with the path to the bucket or object on
the S3-compatible host.
- Replace :mc-cmd:`DURATION <mc ls rewind>` with the point-in-time in the past
at which the command returns the object. For example, specify ``30d`` to
return the version of the object 30 days prior to the current date.
.. include:: /includes/facts-versioning.rst
:start-after: start-versioning-admonition
:end-before: end-versioning-admonition
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

164
source/reference/minio-mc/mc-mb.rst Normal file
View File

@ -0,0 +1,164 @@
=========
``mc mb``
=========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc mb
Syntax
------
.. start-mc-mb-desc
The :mc:`mc mb` command creates a new bucket or directory at the
specified path.
.. end-mc-mb-desc
You can also use :mc:`mc mb` against the local filesystem to produce
similar results to the ``mkdir -p`` commandline tool.
.. tab-set::
.. tab-item:: EXAMPLE
The following command creates a new bucket ``mydata`` on the
``myminio`` MinIO deployment. The command creates the bucket
with :ref:`object locking enabled <minio-object-locking>`.
.. code-block:: shell
:class: copyable
mc mb --with-locks myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] mb \
[--ignore-existing] \
[--region "string"] \
[--with-lock] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The MinIO or other S3-compatible service on which to create the
new bucket.
For creating a bucket on MinIO or another S3-compatible service, specify the
:ref:`alias <alias>` and the name of the bucket. For example:
.. code-block:: none
mc mb play/mybucket
For creating a directory on a local filesystem, specify the full
path to that directory. For example:
.. code-block:: none
mc ls ~/mydata/object.txt
.. mc-cmd:: ignore-existing, p
:option:
Directs :mc-cmd:`mc mb` to do nothing if the bucket or directory already
exists.
.. mc-cmd:: region
:option:
The region in which to create the specified bucket. Has no effect if the
specified :mc-cmd:`~mc mb ALIAS` is a filesystem directory.
.. mc-cmd:: with-lock, l
:option:
Enables :ref:`object locking <minio-object-locking>` on the specified
bucket. Has no effect if the specified ``ALIAS`` is a
:ref:`standalone <minio-installation-comparison>` MinIO deployments *or*
a filesystem directory.
.. important::
You can *only* enable object locking when creating the bucket.
Buckets created without object locking cannot use
:ref:`Bucket Lifecycle Management <minio-lifecycle-management>` or
:ref:`Bucket Object Locking <minio-object-locking>` functionality.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Create Bucket
~~~~~~~~~~~~~
Use :mc:`mc mb` to create a bucket on an S3-compatible host. The
:mc-cmd-option:`~mc mb with-lock` option creates the bucket with locking
enabled:
.. code-block:: shell
:class: copyable
mc mb --with-lock ALIAS/BUCKET
- Replace :mc-cmd:`ALIAS <mc mb ALIAS>` with the
:mc:`alias <mc alias>` of the S3-compatible host.
- Replace :mc-cmd:`BUCKET <mc mb ALIAS>` with the bucket to create.
Behavior
--------
Bucket Limits for Non-MinIO S3 Services
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Certain S3 services may restrict the number of buckets a given user or account
can create. For example, Amazon S3 limits each account to
:s3-docs:`100 buckets <BucketRestrictions.html>`. :mc:`mc mb` may return an
error if the user has reached bucket limits on the target S3 service.
MinIO Object Storage deployments do not place any limits on the number of
buckets each user can create.
Enable Object Locking at Bucket Creation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO follows
:s3-docs:`AWS S3 behavior <object-lock-overview.html#object-lock-bucket-config>`
where you *must* enable :ref:`object locking <minio-object-locking>` at
bucket creation. Buckets created without object can *never* enable object
retention or locking.
Enabling bucket locking does *not* set any object locking or retention settings.
Consider enabling bucket locking as standard practice.
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

396
source/reference/minio-cli/minio-mc/mc-mirror.rst → source/reference/minio-mc/mc-mirror.rst
View File

@ -10,33 +10,231 @@
.. mc:: mc mirror
Description
-----------
Syntax
------
.. start-mc-mirror-desc
The :mc:`mc mirror` command synchronizes content to an S3-compatible host,
similar to the ``rsync`` utility. :mc:`mc mirror` supports both filesystems and
S3-compatible hosts as the synchronization source.
The :mc:`mc mirror` command synchronizes content to MinIO deployment, similar to
the ``rsync`` utility. :mc:`mc mirror` supports filesystems, MinIO deployments,
and other S3-compatible hosts as the synchronization source.
.. end-mc-mirror-desc
MinIO Trims Empty Prefixes on Object Removal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-set::
The :mc-cmd-option:`mc mirror watch` command continuously synchronizes the
source and destination targets. This includes automatically removing objects
on the destination if they are removed on the source.
.. tab-item:: EXAMPLE
.. |command| replace:: :mc-cmd-option:`mc mirror watch`
The following command synchronizes content from a local filesystem
directory to the ``mydata`` bucket on the ``myminio`` MinIO deployment.
.. include:: /includes/common-admonitions.rst
:start-after: start-remove-api-trims-prefixes
:end-before: end-remove-api-trims-prefixes
.. code-block:: shell
:class: copyable
.. include:: /includes/common-admonitions.rst
:start-after: start-remove-api-trims-prefixes-fs
:end-before: end-remove-api-trims-prefixes-fs
mc mirror --watch ~/mydata myminio/mydata
The command "watches" the local filesystem and synchronizes any additional
operations to MinIO until explicitly terminated from the terminal:
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] mirror \
[--attr "string"] \
[--disable-multipart] \
[--encrypt-key "string"] \
[--exclude "string"] \
[--fake] \
[--md5] \
[--monitoring-address "string"] \
[--newer-than "string"] \
[--older-than "string"] \
[--preserve] \
[--region "string"] \
[--remove] \
[--storage-class "string"] \
[--watch] \
SOURCE \
TARGET
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: SOURCE
*REQUIRED* The file(s) or object(s) to synchronize to the
:mc-cmd:`~mc mirror TARGET` S3 host.
For objects on S3-compatible hosts, specify the path to the object as
``ALIAS/PATH``, where:
- ``ALIAS`` is the :mc:`alias <mc alias>` of a configured S3-compatible host,
*and*
- ``PATH`` is the path to the bucket or object. If specifying a bucket,
:mc:`mc mirror` synchronizes all objects in the bucket.
.. code-block:: shell
mc mirror [FLAGS] play/mybucket/ myminio/mybucket
For files on a filesystem, specify the full filesystem path to the file or
directory :
.. code-block:: shell
mc mirror [FLAGS] ~/data/ myminio/mybucket
If specifying a directory, :mc-cmd:`mc mirror` synchronizes all files in the
directory.
.. mc-cmd:: TARGET
*REQUIRED* The full path to bucket in which :mc:`mc mirror` copies
synchronized SOURCE objects. Specify the ``TARGET`` as
``ALIAS/PATH``, where:
- ``ALIAS`` is the :mc:`alias <mc alias>` of a configured S3-compatible
host, *and*
- ``PATH`` is the path to the bucket.
.. code-block:: shell
mc mirror SOURCE play/mybucket
:mc:`mc mirror` uses the object or file names from the
:mc-cmd:`~mc mirror SOURCE` when synchronizing to the ``TARGET`` bucket.
.. mc-cmd:: attr
:option:
Add custom metadata for mirrored objects. Specify key-value pairs as
``KEY=VALUE\;``. For example,
``--attr key1=value1\;key2=value2\;key3=value3``.
.. mc-cmd:: disable-multipart
:option:
Disables multipart upload for the copy session.
.. mc-cmd:: encrypt-key
:option:
Encrypt or decrypt objects using server-side encryption with
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc mirror encrypt-key` in double quotes ``"``.
:mc-cmd-option:`~mc mirror encrypt-key` can use the ``MC_ENCRYPT_KEY``
environment variable for retrieving a list of encryption key-value pairs
as an alternative to specifying them on the command line.
You can only delete encrypted objects if you specify the correct
:mc-cmd-option:`~mc mirror encrypt-key` secret key.
.. mc-cmd:: exclude
:option:
Exclude object(s) in the :mc-cmd:`~mc mirror SOURCE` path that
match the specified object name pattern.
.. mc-cmd:: fake
:option:
Perform a fake mirror operation. Use this operation to perform
validate that the :mc:`mc mirror` operation will only
mirror the desired objects or buckets.
.. mc-cmd:: md5
:option:
Forces all uploads to calculate MD5 checksums.
.. mc-cmd:: monitoring-address
:option:
Creates a `Prometheus <https://prometheus.io/>`__ endpoint for monitoring
mirroring activity. Specify the local network adapter and port address on
which to create the scraping endpoint. Defaults to ``localhost:8081``).
.. mc-cmd:: newer-than
:option:
Mirror object(s) newer than the specified number of days. Specify a
string in ``#d#hh#mm#ss`` format. For example:
``--older-than 1d2hh3mm4ss``.
.. mc-cmd:: older-than
:option:
Mirror object(s) older than the specified time limit. Specify a string
in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``.
Defaults to ``0`` (all objects).
.. mc-cmd:: overwrite
:option:
Overwrites object(s) on the :mc-cmd:`~mc mirror TARGET`.
.. mc-cmd:: preserve, a
:option:
Preserve file system attributes and bucket policy rules of the
:mc-cmd:`~mc mirror SOURCE` on the
:mc-cmd:`~mc mirror TARGET`.
.. mc-cmd:: region
:option:
Specify the ``string`` region when creating new bucket(s) on the
target.
Defaults to ``"us-east-1"``.
.. mc-cmd:: remove
:option:
Removes extraneous object(s) on the target.
.. mc-cmd:: storage-class, sc
:option:
Set the storage class for the new object(s) on the
:mc-cmd:`~mc mirror TARGET`.
See the Amazon documentation on
:aws-docs:`Storage Classes <AmazonS3/latest/dev/storage-class-intro.html>`
for more information on S3 storage classses.
.. mc-cmd:: watch, w
:option:
Continuously monitor the :mc-cmd:`~mc mirror SOURCE` path and
synchronize changes.
Defaults to ``0`` (all objects).
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
@ -100,155 +298,29 @@ host.
- Replace :mc-cmd:`TGTPATH <mc mirror TARGET>` with the destination bucket.
Syntax
------
Behavior
--------
:mc:`~mc mirror` has the following syntax:
MinIO Trims Empty Prefixes on Object Removal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: shell
The :mc-cmd-option:`mc mirror watch` command continuously synchronizes the
source and destination targets. This includes automatically removing objects
on the destination if they are removed on the source.
mc mirror [FLAGS] SOURCE TARGET
.. |command| replace:: :mc-cmd-option:`mc mirror watch`
:mc:`~mc mirror` supports the following arguments:
.. include:: /includes/common-admonitions.rst
:start-after: start-remove-api-trims-prefixes
:end-before: end-remove-api-trims-prefixes
.. mc-cmd:: SOURCE
.. include:: /includes/common-admonitions.rst
:start-after: start-remove-api-trims-prefixes-fs
:end-before: end-remove-api-trims-prefixes-fs
*REQUIRED*
The file(s) or object(s) to synchronize to the :mc-cmd:`~mc mirror TARGET`
S3 host.
For objects on S3-compatible hosts, specify the path to the object as
``ALIAS/PATH``, where:
- ``ALIAS`` is the :mc:`alias <mc alias>` of a configured S3-compatible host,
*and*
- ``PATH`` is the path to the bucket or object. If specifying a bucket,
:mc:`mc mirror` synchronizes all objects in the bucket.
.. code-block:: shell
mc mirror [FLAGS] play/mybucket/ TARGET
For files on a filesystem, specify the full filesystem path to the file or
directory :
.. code-block:: shell
mc mirror [FLAGS] ~/data/ TARGET
If specifying a directory, :mc-cmd:`mc mirror` synchronizes all files in the
directory.
.. mc-cmd:: TARGET
*REQUIRED*
The full path to bucket in which :mc:`mc mirror` copies
synchronized SOURCE objects. Specify the ``TARGET`` as
``ALIAS/PATH``, where:
- ``ALIAS`` is the :mc:`alias <mc alias>` of a configured S3-compatible
host, *and*
- ``PATH`` is the path to the bucket.
.. code-block:: shell
mc mirror SOURCE play/mybucket
:mc:`mc mirror` uses the object or file names from the
:mc-cmd:`~mc mirror SOURCE` when synchronizing to the ``TARGET`` bucket.
.. mc-cmd:: overwrite
:option:
Overwrites object(s) on the :mc-cmd:`~mc mirror TARGET`.
.. mc-cmd:: remove
:option:
Removes extraneous object(s) on the target.
.. mc-cmd:: watch, w
:option:
Continuously monitor the :mc-cmd:`~mc mirror SOURCE` path and
synchronize changes.
.. mc-cmd:: region
:option:
Specify the ``string`` region when creating new bucket(s) on the
target.
Defaults to ``"us-east-1"``.
.. mc-cmd:: preserve, a
:option:
Preserve file system attributes and bucket policy rules of the
:mc-cmd:`~mc mirror SOURCE` on the
:mc-cmd:`~mc mirror TARGET`.
.. mc-cmd:: exclude
:option:
Exclude object(s) in the :mc-cmd:`~mc mirror SOURCE` path that
match the specified object name pattern.
.. mc-cmd:: older-than
:option:
Mirror object(s) older than the specified time limit. Specify a string
in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``
Defaults to ``0`` (all objects).
.. mc-cmd:: newer-than
:option:
Mirror object(s) newer than the specified number of days. Specify a
string in ``#d#hh#mm#ss`` format. For example:
``--older-than 1d2hh3mm4ss``
Defaults to ``0`` (all objects).
.. mc-cmd:: fake
:option:
Perform a fake mirror operation. Use this operation to perform
validate that the :mc:`mc mirror` operation will only
mirror the desired objects or buckets.
.. mc-cmd:: storage-class, sc
:option:
Set the storage class for the new object(s) on the
:mc-cmd:`~mc mirror TARGET`.
See the Amazon documentation on
:aws-docs:`Storage Classes <AmazonS3/latest/dev/storage-class-intro.html>`
for more information on S3 storage classses.
.. mc-cmd:: encrypt-key
:option:
Encrypt or decrypt objects using server-side encryption with
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc mirror encrypt-key` in double quotes ``"``.
:mc-cmd-option:`~mc mirror encrypt-key` can use the ``MC_ENCRYPT_KEY``
environment variable for retrieving a list of encryption key-value pairs
as an alternative to specifying them on the command line.
You can only delete encrypted objects if you specify the correct
:mc-cmd-option:`~mc mirror encrypt-key` secret key.
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

365
source/reference/minio-cli/minio-mc/mc-mv.rst → source/reference/minio-mc/mc-mv.rst
View File

@ -10,40 +10,209 @@
.. mc:: mc mv
Description
-----------
Syntax
------
.. start-mc-mv-desc
The :mc:`mc mv` command moves data from one or more sources to a target
S3-compatible service.
The :mc:`mc mv` command moves an object from source to the target, such as
between MinIO deployments *or* between buckets on the same MinIO deployment.
:mc:`mc mv` also supports moving objects between a local filesystem and MinIO.
.. end-mc-mv-desc
Checksum Verification
~~~~~~~~~~~~~~~~~~~~~
You can also use :mc:`mc mv` against the local filesystem to produce
similar results to the ``mv`` commandline tool.
:mc:`mc mv` verifies all move operations to object storage using MD5SUM
checksums.
.. tab-set::
Resume Move Operations
~~~~~~~~~~~~~~~~~~~~~~
.. tab-item:: EXAMPLE
Use :mc-cmd-option:`mc mv continue` to resume an interrupted or failed
move operation from the point of failure.
The following command moves objects from the ``mydata`` bucket to the
``archive`` bucket on the ``myminio`` MinIO deployment:
MinIO Trims Empty Prefixes on Object Removal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: shell
:class: copyable
.. |command| replace:: :mc-cmd:`mc mv`
mc mv --recursive myminio/mydata myminio/archive
.. include:: /includes/common-admonitions.rst
:start-after: start-remove-api-trims-prefixes
:end-before: end-remove-api-trims-prefixes
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] mv \
[--attr "string"] \
[--continue] \
[--encrypt "string"] \
[--encrypt-key "string"] \
[--newer-than "string"] \
[--older-than "string"] \
[--preserve] \
[--recursive] \
[--storage-class "string"] \
SOURCE \
TARGET
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: SOURCE
*Required* The object or objects to move.
For moving an object from MinIO or another S3-compatible service,
specify the :ref:`alias <alias>` and hte full path to the object(s)
(e.g. bucket and path to objects). For example:
.. code-block:: shell
mc mv play/mybucket/object.txt play/myotherbucket/object.txt
For moving an object from a local filesystem, specify the full path to that
object. For example:
.. code-block:: shell
mc mv ~/mydata/object.txt play/mybucket/object.txt
You can specify both local paths
and S3 paths using a configured S3 service :mc:`alias <mc alias>`.
If you specify a directory or bucket to :mc-cmd:`~mc mv SOURCE`, you must
also specify :mc-cmd-option:`~mc mv recursive` to recursively move the
contents of that directory. If you omit the :mc-cmd-option:`~mc mv recursive`
argument, :mc:`~mc mv` only moves objects in the top level of the specified
directory or bucket.
.. mc-cmd:: TARGET
*Required* The full path to the bucket to which the command moves the
object(s) at the specified :mc-cmd:`~mc mv SOURCE`. Specify the
:ref:`alias <alias>` of a configured S3 service as the prefix to the
:mc-cmd:`~mc mv TARGET` path.
For moving an object from MinIO or another S3-compatible service,
specify the :ref:`alias <alias>` and hte full path to the object(s)
(e.g. bucket and path to objects). For example:
.. code-block:: shell
mc mv play/mybucket/object.txt play/myotherbucket/object.txt
For moving an object from a local filesystem, specify the full path to that
object. For example:
.. code-block:: shell
mc mv ~/mydata/object.txt play/mybucket/object.txt
The ``TARGET`` object name can differ from the ``SOURCE`` to
"rename" the object as part of the move operation.
If running :mc-cmd:`mc mv` with the :mc-cmd-option:`~mc mv recursive` option,
:mc-cmd:`mc mv` treats the ``TARGET`` as the bucket prefix for all
objects at the ``SOURCE``.
.. mc-cmd:: attr
:option:
*Optional* Add custom metadata for the object. Specify key-value pairs as
``KEY=VALUE\;``. For example,
``--attr key1=value1\;key2=value2\;key3=value3``.
.. mc-cmd:: continue, c
:option:
*Optional* Create or resume a move session.
.. mc-cmd:: encrypt
:option:
*Optional* Encrypt or decrypt objects using server-side encryption with
server-managed keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc mv encrypt` in double-quotes ``"``.
:mc-cmd-option:`~mc mv encrypt` can use the ``MC_ENCRYPT`` environment
variable for retrieving a list of encryption key-value pairs as an
alternative to specifying them on the command line.
.. mc-cmd:: encrypt-key
:option:
*Optional* Encrypt or decrypt objects using server-side encryption with
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc mv encrypt-key` in double quotes ``"``.
:mc-cmd-option:`~mc mv encrypt-key` can use the ``MC_ENCRYPT_KEY``
environment variable for retrieving a list of encryption key-value pairs
as an alternative to specifying them on the command line.
.. mc-cmd:: newer-than
:option:
*Optional* Remove object(s) newer than the specified number of days. Specify
a string in ``##d#hh#mm#ss`` format. For example:
``--newer-than 1d2hh3mm4ss``.
Defaults to ``0`` (all objects).
.. mc-cmd:: older-than
:option:
*Optional* Remove object(s) older than the specified time limit. Specify a
string in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``.
Defaults to ``0`` (all objects).
.. mc-cmd:: preserve, a
:option:
*Optional* Preserve file system attributes and bucket policy rules of the
:mc-cmd:`~mc mv SOURCE` directories, buckets, and objects on the
:mc-cmd:`~mc mv TARGET` bucket(s).
.. mc-cmd:: recursive, r
:option:
*Optional* Recursively move the contents of each bucket or directory
:mc-cmd:`~mc mv SOURCE` to the :mc-cmd:`~mc mv TARGET` bucket.
.. mc-cmd:: storage-class, sc
:option:
*Optional* Set the storage class for the new object(s) on the
:mc-cmd:`~mc mv TARGET`.
See the Amazon documentation on
:aws-docs:`Storage Classes <AmazonS3/latest/dev/storage-class-intro.html>`
for more information on S3 storage classses.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
.. include:: /includes/common-admonitions.rst
:start-after: start-remove-api-trims-prefixes-fs
:end-before: end-remove-api-trims-prefixes-fs
Examples
--------
@ -145,139 +314,55 @@ the storage class on the destination S3-compatible host.
mc mv --storage-class REDUCED_REDUNDANCY myobject.txt play/mybucket
Behavior
~~~~~~~~
Object Names on Move
~~~~~~~~~~~~~~~~~~~~
Syntax
------
MinIO uses the :mc-cmd-option:`~mc mv SOURCE` object name when moving
the object to the :mc-cmd-option:`~mc mv TARGET` if no explicit target
object name is specified.
:mc:`~mc mv` has the following syntax:
You can specify a different object name for the
:mc-cmd-option:`~mc mv TARGET` with the same object path to "rename"
an object. For example:
.. code-block:: shell
mc mv [FLAGS] SOURCE [SOURCE...] TARGET
mc mv play/mybucket/object.txt play/mybucket/myobject.txt
:mc:`~mc mv` supports the following arguments:
For recursive move operations (:mc-cmd-option:`mc mv recursive`), MinIO
treats the ``TARGET`` path as a prefix for objects on the ``SOURCE``.
.. mc-cmd:: SOURCE
Checksum Verification
~~~~~~~~~~~~~~~~~~~~~
*REQUIRED*
:mc:`mc mv` verifies all move operations to object storage using MD5SUM
checksums.
The object or objects to move. You can specify both local paths
and S3 paths using a configured S3 service :mc:`alias <mc alias>`.
Resume Move Operations
~~~~~~~~~~~~~~~~~~~~~~
For example:
Use :mc-cmd-option:`mc mv continue` to resume an interrupted or failed
move operation from the point of failure.
.. code-block:: none
MinIO Trims Empty Prefixes on Object Removal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
mc mv play/mybucket/object.txt ~/localfiles/mybucket/object.txt TARGET
.. |command| replace:: :mc-cmd:`mc mv`
If you specify a directory or bucket to :mc-cmd:`~mc mv SOURCE`, you must
also specify :mc-cmd-option:`~mc mv recursive` to recursively move the
contents of that directory. If you omit the :mc-cmd-option:`~mc mv recursive`
argument, :mc:`~mc mv` only moves objects in the top level of the specified
directory or bucket.
.. mc-cmd:: TARGET
*REQUIRED*
The full path to the bucket to move the specified
:mc-cmd:`~mc mv SOURCE` to. Specify the :mc:`alias <mc alias>`
of a configured S3 service as the prefix to the
:mc-cmd:`~mc mv TARGET` path.
For example:
.. code-block:: shell
mc mv ~/localfiles/object.txt play/mybucket/
.. mc-cmd:: recursive, r
:option:
Recursively move the contents of each bucket or directory
:mc-cmd:`~mc mv SOURCE` to the :mc-cmd:`~mc mv TARGET`
bucket.
.. mc-cmd:: older-than
:option:
Remove object(s) older than the specified time limit. Specify a string
in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``.
Defaults to ``0`` (all objects).
.. mc-cmd:: newer-than
:option:
Remove object(s) newer than the specified number of days. Specify a
string in ``##d#hh#mm#ss`` format. For example:
``--newer-than 1d2hh3mm4ss``.
Defaults to ``0`` (all objects).
.. mc-cmd:: storage-class, sc
:option:
Set the storage class for the new object(s) on the
:mc-cmd:`~mc mv TARGET`.
See the Amazon documentation on
:aws-docs:`Storage Classes <AmazonS3/latest/dev/storage-class-intro.html>`
for more information on S3 storage classses.
.. mc-cmd:: preserve, a
:option:
Preserve file system attributes and bucket policy rules of the
:mc-cmd:`~mc mv SOURCE` directories, buckets, and objects on the
:mc-cmd:`~mc mv TARGET` bucket(s).
.. mc-cmd:: attr
:option:
Add custom metadata for the object. Specify key-value pairs as
``KEY=VALUE\;``. For example,
``--attr key1=value1\;key2=value2\;key3=value3``.
.. mc-cmd:: continue, c
:option:
Create or resume a move session.
.. mc-cmd:: encrypt
:option:
Encrypt or decrypt objects using server-side encryption with
server-managed keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc mv encrypt` in double-quotes ``"``.
:mc-cmd-option:`~mc mv encrypt` can use the ``MC_ENCRYPT`` environment
variable for retrieving a list of encryption key-value pairs as an
alternative to specifying them on the command line.
.. mc-cmd:: encrypt-key
:option:
Encrypt or decrypt objects using server-side encryption with
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
- Each ``KEY`` represents a bucket or object.
- Each ``VALUE`` represents the data key to use for encrypting
object(s).
Enclose the entire list of key-value pairs passed to
:mc-cmd-option:`~mc mv encrypt-key` in double quotes ``"``.
:mc-cmd-option:`~mc mv encrypt-key` can use the ``MC_ENCRYPT_KEY``
environment variable for retrieving a list of encryption key-value pairs
as an alternative to specifying them on the command line.
.. include:: /includes/common-admonitions.rst
:start-after: start-remove-api-trims-prefixes
:end-before: end-remove-api-trims-prefixes
.. include:: /includes/common-admonitions.rst
:start-after: start-remove-api-trims-prefixes-fs
:end-before: end-remove-api-trims-prefixes-fs
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

104
source/reference/minio-mc/mc-policy-get-json.rst Normal file
View File

@ -0,0 +1,104 @@
.. _minio-mc-policy-get-json:
======================
``mc policy get-json``
======================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc policy get-json
Syntax
------
.. start-mc-policy-get-json-desc
The :mc:`mc policy get-json` command gets anonymous (i.e. unauthenticated or
public) access :ref:`policies <minio-policy>` for a bucket.
.. end-mc-policy-get-json-desc
Buckets with anonymous policies allow clients to access the bucket contents
and perform actions consistent with the specified policy without
:ref:`authentication <minio-authentication-and-identity-management>`.
.. tab-set::
.. tab-item:: EXAMPLE
The following command retrieves the JSON-formatted anonymous
policy for the ``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc policy get-json myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] get-json ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The full path to the bucket or bucket prefix for which to get the
anonymous bucket policy.
Specify the :ref:`alias <alias>` of the MinIO or other
S3-compatible service *and* the full path to the bucket or bucket
prefix. For example:
.. code-block:: shell
mc get-json public play/mybucket
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Get Anonymous Policy for Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc policy get-json` to get the anonymous policy for a
bucket:
.. code-block:: shell
:class: copyable
mc policy get-json ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc policy get-json ALIAS>` with the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc policy get-json ALIAS>` with the destination bucket.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

108
source/reference/minio-mc/mc-policy-get.rst Normal file
View File

@ -0,0 +1,108 @@
.. _minio-mc-policy-get:
=================
``mc policy get``
=================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc policy get
Syntax
------
.. start-mc-policy-get-desc
The :mc:`mc policy get` command gets the anonymous (i.e. unauthenticated or
public) access :ref:`policies <minio-policy>` for a bucket.
.. end-mc-policy-get-desc
Buckets with anonymous policies allow clients to access the bucket contents
and perform actions consistent with the specified policy without
:ref:`authentication <minio-authentication-and-identity-management>`.
To get the :s3-docs:`JSON policy <using-iam-policies>` assigned to the bucket,
use the :mc-cmd:`mc policy get-json` command.
.. tab-set::
.. tab-item:: EXAMPLE
The following command retrieves the anonymous access policy for the
``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc policy get myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] policy get ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The full path to the bucket or bucket prefix for which the
command retrieves the anonymous bucket policy.
Specify the :ref:`alias <alias>` of the MinIO or other
S3-compatible service *and* the full path to the bucket or bucket
prefix. For example:
.. code-block:: shell
mc get public play/mybucket
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Get Anonymous Policy for Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc policy get` to get the anonymous policy for a
bucket:
.. code-block:: shell
:class: copyable
mc policy get ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc policy get ALIAS>` with the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc policy get ALIAS>` with the destination bucket.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

111
source/reference/minio-mc/mc-policy-links.rst Normal file
View File

@ -0,0 +1,111 @@
.. _minio-mc-policy-links:
===================
``mc policy links``
===================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc policy links
Syntax
------
.. start-mc-policy-links-desc
The :mc:`mc policy links` retrieves the HTTP URL for anonymous (i.e.
unauthenticated or public) access to a bucket.
.. end-mc-policy-links-desc
Buckets with anonymous policies allow clients to access the bucket contents
and perform actions consistent with the specified policy without
:ref:`authentication <minio-authentication-and-identity-management>`.
.. tab-set::
.. tab-item:: EXAMPLE
The following command retrieves HTTP URLs for the ``mydata`` bucket
on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc policy links --recursive myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] policy links \
[--recursive] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The full path to the bucket or bucket prefix for which the
command retrieves the anonymous bucket policies.
Specify the :ref:`alias <alias>` of the MinIO or other
S3-compatible service *and* the full path to the bucket or bucket
prefix. For example:
.. code-block:: shell
mc links public [FLAGS] play/mybucket
.. mc-cmd:: recursive
:option:
*Optional* Retrieve the HTTP links recursively.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
List Anonymous Policies for Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc policy links` to links the anonymous policies for a
bucket:
.. code-block:: shell
:class: copyable
mc policy links ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc policy get ALIAS>` with the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc policy get ALIAS>` with the destination bucket.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

105
source/reference/minio-mc/mc-policy-list.rst Normal file
View File

@ -0,0 +1,105 @@
.. _minio-mc-policy-list:
==================
``mc policy list``
==================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc policy list
Syntax
------
.. start-mc-policy-list-desc
The :mc:`mc policy list` retrieves all anonymous (i.e. unauthenticated or
public) access policies for a bucket.
.. end-mc-policy-list-desc
Buckets with anonymous policies allow clients to access the bucket contents
and perform actions consistent with the specified policy without
:ref:`authentication <minio-authentication-and-identity-management>`.
.. tab-set::
.. tab-item:: EXAMPLE
The following command lists all anonymous access policies for the
``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc policy list myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The full path to the bucket or bucket prefix for which the
command retrieves the anonymous bucket policies.
Specify the :ref:`alias <alias>` of the MinIO or other
S3-compatible service *and* the full path to the bucket or bucket
prefix. For example:
.. code-block:: shell
mc list public play/mybucket
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
List Anonymous Policies for Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc policy list` to list the anonymous policies for a
bucket:
.. code-block:: shell
:class: copyable
mc policy list ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc policy get ALIAS>` with the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc policy get ALIAS>` with the destination bucket.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

130
source/reference/minio-mc/mc-policy-set-json.rst Normal file
View File

@ -0,0 +1,130 @@
.. _minio-mc-policy-set-json:
======================
``mc policy set-json``
======================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc policy set-json
Syntax
------
.. start-mc-policy-set-json-desc
The :mc:`mc policy set-json` command sets anonymous (i.e. unauthenticated or
public) access :ref:`policies <minio-policy>` for a bucket using using an IAM
:s3-docs:`JSON policy document <using-iam-policies>`.
.. end-mc-policy-set-json-desc
Buckets with anonymous policies allow clients to access the bucket contents
and perform actions consistent with the specified policy without
:ref:`authentication <minio-authentication-and-identity-management>`.
.. tab-set::
.. tab-item:: EXAMPLE
The following command applies the JSON-formatted anonymous policy
to the ``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc policy set-json ~/mydata-anonymous.json myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] set-json POLICY ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: POLICY
*Required* The path to the JSON-formatted policy to assign to the specified
``ALIAS``.
.. mc-cmd:: ALIAS
*Required* The full path to the bucket or bucket prefix to which the
command applies the specified :mc-cmd:`~mc policy set-json POLICY`.
Specify the :ref:`alias <alias>` of the MinIO or other
S3-compatible service *and* the full path to the bucket or bucket
prefix. For example:
.. code-block:: shell
mc set-json public play/mybucket
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Set Anonymous Policy for Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc policy set-json` to set the anonymous policy for a
bucket:
.. code-block:: shell
:class: copyable
mc policy set-json POLICY ALIAS/PATH
- Replace :mc-cmd:`POLICY <mc policy set-json POLICY>` with a supported
:mc-cmd:`POLICY <mc policy set-json POLICY>`.
- Replace :mc-cmd:`ALIAS <mc policy set-json ALIAS>` with the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc policy set-json ALIAS>` with the destination bucket.
Remove Anonymous Policy for Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc policy set` to clear the anonymous policy for a
bucket:
.. code-block:: shell
:class: copyable
mc policy set none ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc policy set ALIAS>` with the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc policy set ALIAS>` with the destination bucket.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

140
source/reference/minio-mc/mc-policy-set.rst Normal file
View File

@ -0,0 +1,140 @@
.. _minio-mc-policy-set:
=================
``mc policy set``
=================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc policy
.. mc:: mc policy set
Syntax
------
.. start-mc-policy-set-desc
The :mc:`mc policy set` command sets anonymous (i.e. unauthenticated or public)
access :ref:`policies <minio-policy>` for a bucket.
.. end-mc-policy-set-desc
Buckets with anonymous policies allow clients to access the bucket contents
and perform actions consistent with the specified policy without
:ref:`authentication <minio-authentication-and-identity-management>`.
To set anonymous bucket policies using an IAM
:s3-docs:`JSON policy <using-iam-policies>`, use the
:mc-cmd:`mc policy set-json` command.
.. tab-set::
.. tab-item:: EXAMPLE
The following command sets anonymous access policies for several
buckets on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc policy set upload myminio/uploads
mc policy set download myminio/downloads
mc policy set public myminio/public
Applications can perform the following operations without authentication:
- ``PUT`` objects to ``myminio/uploads`` and ``myminio/public``.
- ``GET`` objects from ``myminio/downloads`` and ``myminio/public``.
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] policy set PERMISSION ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: PERMISSION
*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``.
.. mc-cmd:: ALIAS
*Required* The full path to the bucket or bucket prefix to which the
command applies the specified :mc-cmd:`~mc policy set PERMISSION`.
Specify the :ref:`alias <alias>` of the MinIO or other
S3-compatible service *and* the full path to the bucket or bucket
prefix. For example:
.. code-block:: shell
mc 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:
.. code-block:: shell
mc set download play/mybucket/downloads
mc set upload play/mybucket/uploads
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Set Anonymous Policy for Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc policy set` to set the anonymous policy for a
bucket:
.. code-block:: shell
:class: copyable
mc policy set POLICY ALIAS/PATH
- Replace :mc-cmd:`POLICY <mc policy set PERMISSION>` with a supported
:mc-cmd:`permission <mc policy set PERMISSION>`.
- Replace :mc-cmd:`ALIAS <mc policy set ALIAS>` with the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc policy set ALIAS>` with the destination bucket.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

147
source/reference/minio-mc/mc-rb.rst Normal file
View File

@ -0,0 +1,147 @@
=========
``mc rb``
=========
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc rb
Syntax
------
.. start-mc-rb-desc
The :mc:`mc rb` command removes one or more buckets on MinIO *or*
another S3-compatible service.
To remove only the contents of a bucket, use :mc:`mc rm` instead.
.. end-mc-rb-desc
.. important::
:mc:`mc rb` *permanently deletes bucket(s)* on the target deployment,
including any and all :ref:`object versions <minio-bucket-versioning>`
and bucket configurations such as
:ref:`lifecycle management <minio-lifecycle-management>` or
:ref:`replication <minio-bucket-replication-serverside>`.
You can also use :mc:`mc rb` against the local filesystem to produce
similar results to the ``rm --rf`` commandline tool.
.. tab-set::
.. tab-item:: EXAMPLE
The following command removes the ``mydata`` bucket on the
``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc rb --force myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] rb \
--force \
[--dangerous] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* The :ref:`alias <alias>` of a MinIO or other S3-compatible
service and the full path to the bucket to remove. For example:
.. code-block:: none
mc rb --force myminio/mydata
Omit the bucket path to perform a site-wide removal of buckets on the MinIO
deployment. This operation *requires* specifying
:mc-cmd-option:`~mc rb dangerous` to explicitly acknowledge the permanent
removal of *all* data on the deployment. For example:
.. code-block:: none
mc rb --force --dangerous myminio
For removing a directory and its contents on a local filesystem, specify
the full path to that directory. The
:mc-cmd-option:`~mc rb force` flag is ignored if specified. For example:
.. code-block:: none
mc rb ~/data/myolddata
.. mc-cmd:: force
:option:
*Required* Safety flag to confirm removal of the bucket contents.
.. mc-cmd:: dangerous
:option:
*Optional* Directs :mc:`mc rb` to perform a site-wide removal of all
buckets on each specified :mc-cmd:`~mc rb ALIAS` (e.g. ``myminio/``).
If any ``ALIAS`` specifies a filesystem directory, this option
results in the removal of all subdirectories and files at that directory
path similar to ``rm --rf``.
.. warning::
Running :mc-cmd-option:`mc rb dangerous` is irreversible. Exercise all
possible due diligence in ensuring the command applies to only the
desired ``ALIAS`` targets prior to execution.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Example
-------
Remove a Bucket
~~~~~~~~~~~~~~~
.. code-block:: shell
:class: copyable
mc rb --force ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc rb ALIAS>` with the :mc-cmd:`alias <mc alias>` of
a configured S3-compatible host.
- Replace :mc-cmd:`PATH <mc rb ALIAS>` with the path to the bucket to remove.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

421
source/reference/minio-mc/mc-replicate-add.rst Normal file
View File

@ -0,0 +1,421 @@
.. _minio-mc-replicate-add:
====================
``mc replicate add``
====================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc replicate
.. mc:: mc replicate add
Syntax
------
.. start-mc-replicate-add-desc
The :mc:`mc replicate add` command creates a new :ref:`server-side replication
<minio-bucket-replication-serverside>` rule for a bucket on a MinIO deployment.
.. end-mc-replicate-add-desc
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.
This command *requires* first configuring the remote bucket target using the
:mc-cmd:`mc admin bucket remote add` command. You must specify the resulting
remote ARN as part of running :mc-cmd:`mc replicate add`.
.. tab-set::
.. tab-item:: EXAMPLE
The following command adds a new replication rule for the ``mydata``
bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc replicate add \
--remote-bucket "arn:minio:replication:aefc8b3a-1f6c-4d7a-86dc-1b0bdffa9100:mydata" \
--replicate "delete,delete-marker,existing-objects" \
myminio/mydata
The replication rule synchronizes versioned delete operations, delete
markers, and existing objects to the remote MinIO deployment.
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] replicate add \
--remote-bucket "string" \
[--disable] \
[--id "string"] \
[--replicate "string"] \
[--storage-class "string"] \
[--tags "string"] \
[--priority int] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* the :ref:`alias <alias>` of the MinIO deployment and full path to
the bucket or bucket prefix on which to create the replication rule. For
example:
.. code-block:: none
mc replicate add --remote-bucket "arn:minio:replica::UUID" play/mybucket
.. mc-cmd:: remote-bucket
:option:
*Required* Specify the ARN for the destination deployment and bucket. You
can retrieve the ARN using :mc-cmd:`mc admin bucket remote`:
- Use the :mc-cmd:`mc admin bucket remote ls` to retrieve a list of
ARNs for the bucket on the destination deployment.
- Use the :mc-cmd:`mc admin bucket remote add` to create a replication ARN
for the bucket on the destination deployment.
.. mc-cmd:: disable
:option:
*Optional* Creates the replication rule in the "disabled" state. MinIO does
not begin replicating objects using the rule until it is enabled using
:mc-cmd:`mc replicate edit`.
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-cmd-option:`mc replicate edit replicate`. See
:ref:`minio-replication-behavior-existing-objects` for more
information.
.. mc-cmd:: id
:option:
*Optional* Specify a unique ID for the replication rule. MinIO automatically
generates an ID if one is not specified.
.. mc-cmd:: replicate
:option:
*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.
.. mc-cmd:: storage-class
:option:
*Optional*
Specify the MinIO :ref:`storage class <minio-ec-storage-class>` to
apply to replicated objects.
.. mc-cmd:: tags
:option:
*Optional* Specify one or more ampersand ``&`` separated key-value pair tags
which MinIO uses for filtering objects to replicate. For example:
.. code-block:: shell
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.
.. mc-cmd:: priority
:option:
*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``.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Configure Bucket Replication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following :mc-cmd:`mc replicate add` command creates a replication
configuration that synchronizes all new objects, existing objects, delete
operations, and delete markers to the remote target:
.. code-block:: shell
:class: copyable
mc replicate add myminio/mybucket \
--remote-bucket "arn:minio:replica::UUID" \
--replicate "delete,delete-marker,existing-objects"
- Replace ``myminio/mybucket`` with the :mc-cmd:`~mc replicate add ALIAS` and
full bucket path for which to create the replication configuration.
- Replace the :mc-cmd-option:`~mc replicate add remote-bucket` value with the
ARN of the remote target. Use :mc-cmd:`mc admin bucket remote ls` to list
all configured remote replication targets.
- The :mc-cmd-option:`~mc replicate add replicate` flag directs MinIO to
replicate all delete operations, delete markers, and existing objects to the
remote. See :ref:`minio-replication-behavior-delete` and
:ref:`minio-replication-behavior-existing-objects` for more information on
replication behavior.
Configure Bucket Replication for Historical Data Record
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following :mc-cmd:`mc replicate add` command creates a new bucket
replication configuration that synchronizes all new and existing objects
to the remote target:
.. code-block:: shell
:class: copyable
mc replicate add myminio/mybucket \
--remote-bucket "arn:minio:replica::UUID" \
--replicate "existing-objects"
- Replace ``myminio/mybucket`` with the :mc-cmd:`~mc replicate add ALIAS` and
full bucket path for which to create the replication configuration.
- Replace the :mc-cmd-option:`~mc replicate add remote-bucket` value with the
ARN of the remote target. Use :mc-cmd:`mc admin bucket remote ls` to list
all configured remote replication targets.
- The :mc-cmd-option:`~mc replicate add replicate` flag directs MinIO to
replicate all existing objects to the remote. See
:ref:`minio-replication-behavior-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-cmd:`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-cmd:`mc version suspend` command to enable versioning on
*both* the source and destination bucket before starting this procedure:
.. code-block:: shell
:class: copyable
mc version ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc version ALIAS>` with the
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc version ALIAS>` with the bucket on which
to enable versioning.
Required Permissions
~~~~~~~~~~~~~~~~~~~~
MinIO strongly recommends creating users specifically for supporting
bucket replication operations. See
:mc:`mc admin user` and :mc:`mc admin policy` for more complete
documentation on adding users and policies to a MinIO deployment.
.. tab-set::
.. tab-item:: Replication Admin
The following policy provides permissions for configuring and enabling
replication on a deployment.
.. literalinclude:: /extra/examples/ReplicationAdminPolicy.json
:class: copyable
:language: json
- The ``"EnableRemoteBucketConfiguration"`` statement grants permission
for creating a remote target for supporting replication.
- The ``"EnableReplicationRuleConfiguration"`` statement grants permission
for creating replication rules on a bucket. The ``"arn:aws:s3:::*``
resource applies the replication permissions to *any* bucket on the
source deployment. You can restrict the user policy to specific buckets
as-needed.
Use the :mc-cmd:`mc admin policy add` to add this policy to each
deployment acting as a replication source. Use :mc-cmd:`mc admin user add`
to create a user on the deployment and :mc-cmd:`mc admin policy set`
to associate the policy to that new user.
.. tab-item:: Replication Remote User
The following policy provides permissions for enabling synchronization of
replicated data *into* the deployment.
.. literalinclude:: /extra/examples/ReplicationRemoteUserPolicy.json
:class: copyable
:language: json
- The ``"EnableReplicationOnBucket"`` statement grants permission for
a remote target to retrieve bucket-level configuration for supporting
replication operations on *all* buckets in the MinIO deployment. To
restrict the policy to specific buckets, specify those buckets as an
element in the ``Resource`` array similar to
``"arn:aws:s3:::bucketName"``.
- The ``"EnableReplicatingDataIntoBucket"`` statement grants permission
for a remote target to synchronize data into *any* bucket in the MinIO
deployment. To restrict the policy to specific buckets, specify those
buckets as an element in the ``Resource`` array similar to
``"arn:aws:s3:::bucketName/*"``.
Use the :mc-cmd:`mc admin policy add` to add this policy to each
deployment acting as a replication target. Use :mc-cmd:`mc admin user add`
to create a user on the deployment and :mc-cmd:`mc admin policy set`
to associate the policy to that new user.
Replication of Existing Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Starting with :mc:`mc`
:minio-git:`RELEASE.2021-06-13T17-48-22Z <mc/releases/tag/RELEASE.2021-06-13T17-48-22Z>`
and :mc:`minio`
:minio-git:`RELEASE.2021-06-07T21-40-51Z <minio/releases/tag/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
<https://aws.amazon.com/blogs/storage/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-cmd-option:`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-cmd-option:`mc replicate add replicate`. You must specify *all*
desired replication features when editing the replication rule.
See :ref:`minio-replication-behavior-existing-objects` for more complete
documentation on this behavior.
Synchronization of Metadata Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO supports :ref:`two-way active-active
<minio-bucket-replication-serverside-twoway>` replication configurations, where
MinIO synchronizes new and modified objects between a bucket on two MinIO
deployments. Starting with :mc:`mc`
:minio-git:`RELEASE.2021-05-18T03-39-44Z <mc/releases/tag/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
:ref:`replication status <minio-replication-process>` 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-cmd-option:`mc replicate edit 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
:s3-docs:`Delete Markers <versioning-workflows.html>` *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
:ref:`lifecycle management expiration rules
<minio-lifecycle-management-expiration>`. MinIO only replicates explicit
client-driven delete operations.
MinIO requires explicitly enabling replication of delete operations using the
:mc-cmd-option:`mc replicate add replicate` flag. This procedure includes the
required flags for enabling replication of delete operations and delete markers.
See :ref:`minio-replication-behavior-delete` 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* :ref:`enabling TLS <minio-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
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

318
source/reference/minio-mc/mc-replicate-edit.rst Normal file
View File

@ -0,0 +1,318 @@
.. _minio-mc-replicate-edit:
=====================
``mc replicate edit``
=====================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc replicate edit
Syntax
------
.. start-mc-replicate-edit-desc
The :mc:`mc replicate edit` command modifies an existing
:ref:`bucket replication rule <minio-bucket-replication-serverside>`.
.. end-mc-replicate-edit-desc
.. code-block:: shell
mc [GLOBALFLAGS] replicate edit FLAGS [FLAGS] ARGUMENTS [ARGUMENTS]
.. tab-set::
.. tab-item:: EXAMPLE
The following command modifies an existing replication rule for the
``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc replicate edit --id "c76um9h4b0t1ijr36mug" \
--replicate "delete,delete-marker,existing-objects" \
myminio/mydata
The new replication configuration synchronizes all versioned delete
operations, delete marker creation, and existing objects to the remote
MinIO deployment.
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] replicate edit \
--id "string" \
[--remote-bucket "string"] \
[--disable] \
[--id "string"] \
[--replicate "string"] \
[--state "string"] \
[--storage-class "string"] \
[--tags "string"] \
[--priority int] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* the :ref:`alias <alias>` of the MinIO deployment and full path to
the bucket or bucket prefix on which to modify the replication rule. For
example:
.. code-block:: none
mc replicate edit --id "c75nrap4b0talo3ipthg" [FLAGS]
.. mc-cmd:: id
:option:
*Required* Specify the unique ID for a configured replication rule.
Use the :mc-cmd:`mc replicate ls` command to list the replication rules
for a bucket.
.. mc-cmd:: priority
:option:
*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.
.. mc-cmd:: remote-bucket
:option:
*Optional* Specify the ARN for the destination deployment and bucket. You
can retrieve the ARN using :mc-cmd:`mc admin bucket remote`:
- Use the :mc-cmd:`mc admin bucket remote ls` to retrieve a list of
ARNs for the bucket on the destination deployment.
- Use the :mc-cmd:`mc admin bucket remote add` to create a replication ARN
for the bucket on the destination deployment.
.. mc-cmd:: replicate
:option:
*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.
- ``replica-metadata-sync`` - Directs MinIO to synchronize metadata-only
changes on a replicated object back to the source. This feature only
effects :ref:`two-way active-active
<minio-bucket-replication-serverside-twoway>` replication
configurations.
Omitting this value directs MinIO to stop replicating metadata-only
changes back to the source.
- ``existing-objects`` - Directs MinIO to replicate objects created
prior to configuring or enabling replication. MinIO by default does
*not* synchronize existing objects to the remote target.
See :ref:`minio-replication-behavior-existing-objects` for more
information.
.. mc-cmd:: state
:option:
*Optional* Enables or disables the replication rule. Specify one of the
following values:
- ``"enable"`` - Enables the replication rule.
- ``"disable"`` - Disables the replication rule.
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-cmd-option:`mc replicate edit replicate`. See
:ref:`minio-replication-behavior-existing-objects` for more information.
.. mc-cmd:: storage-class
:option:
*Optional* Specify the MinIO :ref:`storage class <minio-ec-storage-class>`
to apply to replicated objects.
.. mc-cmd:: tags
:option:
*Optional* Specify one or more ampersand ``&`` separated key-value pair tags
which MinIO uses for filtering objects to replicate. For example:
.. code-block:: shell
mc replicate edit --id "ID" --tags "TAG1=VALUE&TAG2=VALUE&TAG3=VALUE"
MinIO applies the replication rule to any object whose tag set
contains the specified replication tags.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Modify an Existing Replication Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc replicate edit` to modify an existing replication rule.
.. code-block:: shell
:class: copyable
mc replicate edit ALIAS/PATH \
--id ID \
[--FLAGS]
- Replace :mc-cmd:`ALIAS <mc replicate edit ALIAS>` with the
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate edit ALIAS>` with the path to the
bucket or bucket prefix on which the rule exists.
- Replace :mc-cmd:`ID <mc replicate edit id>` with the unique identifier for the
rule to modify. Use :mc-cmd:`mc replicate ls` to retrieve the list of
replication rules on the bucket and their corresponding identifiers.
.. note::
Modifying a replication configuration rule does not effect already replicated
objects. For example, modifying the :mc-cmd-option:`~mc replicate edit tags`
filter does not result in the removal of replicated objects which do not
meet the filter.
Disable or Enable an Existing Replication Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc replicate edit` with the
:mc-cmd-option:`~mc replicate edit state` flag to disable or enable a
replication rule.
.. code-block:: shell
:class: copyable
mc replicate edit ALIAS/PATH \
--id ID \
--state "disabled"|"enabled"
- Replace :mc-cmd:`ALIAS <mc replicate edit ALIAS>` with the
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate edit ALIAS>` with the path to the
bucket or bucket prefix on which the rule exists.
- Replace :mc-cmd:`ID <mc replicate edit id>` with the unique identifier for the
rule to modify. Use :mc-cmd:`mc replicate ls` to retrieve the list of
replication rules on the bucket and their corresponding identifiers.
- Specify either ``"disabled"`` or ``"enabled"`` to the
:mc-cmd:`~mc replicate edit state` flag to disable or enable the replication
rule.
.. note::
MinIO requires enabling :ref:`existing object replication
<minio-replication-behavior-existing-objects>` to synchronize objects
written or removed after disabling a replication rule.
For rules *without* existing object replication, MinIO synchronizes only
those write or delete operations issued while the replication rule is
*enabled*.
Behavior
--------
Required Permissions
~~~~~~~~~~~~~~~~~~~~
MinIO strongly recommends creating users specifically for supporting
bucket replication operations. See
:mc:`mc admin user` and :mc:`mc admin policy` for more complete
documentation on adding users and policies to a MinIO deployment.
.. tab-set::
.. tab-item:: Replication Admin
The following policy provides permissions for configuring and enabling
replication on a deployment.
.. literalinclude:: /extra/examples/ReplicationAdminPolicy.json
:class: copyable
:language: json
- The ``"EnableRemoteBucketConfiguration"`` statement grants permission
for creating a remote target for supporting replication.
- The ``"EnableReplicationRuleConfiguration"`` statement grants permission
for creating replication rules on a bucket. The ``"arn:aws:s3:::*``
resource applies the replication permissions to *any* bucket on the
source deployment. You can restrict the user policy to specific buckets
as-needed.
Use the :mc-cmd:`mc admin policy add` to add this policy to each
deployment acting as a replication source. Use :mc-cmd:`mc admin user add`
to create a user on the deployment and :mc-cmd:`mc admin policy set`
to associate the policy to that new user.
.. tab-item:: Replication Remote User
The following policy provides permissions for enabling synchronization of
replicated data *into* the deployment.
.. literalinclude:: /extra/examples/ReplicationRemoteUserPolicy.json
:class: copyable
:language: json
- The ``"EnableReplicationOnBucket"`` statement grants permission for
a remote target to retrieve bucket-level configuration for supporting
replication operations on *all* buckets in the MinIO deployment. To
restrict the policy to specific buckets, specify those buckets as an
element in the ``Resource`` array similar to
``"arn:aws:s3:::bucketName"``.
- The ``"EnableReplicatingDataIntoBucket"`` statement grants permission
for a remote target to synchronize data into *any* bucket in the MinIO
deployment. To restrict the policy to specific buckets, specify those
buckets as an element in the ``Resource`` array similar to
``"arn:aws:s3:::bucketName/*"``.
Use the :mc-cmd:`mc admin policy add` to add this policy to each
deployment acting as a replication target. Use :mc-cmd:`mc admin user add`
to create a user on the deployment and :mc-cmd:`mc admin policy set`
to associate the policy to that new user.
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

98
source/reference/minio-mc/mc-replicate-export.rst Normal file
View File

@ -0,0 +1,98 @@
.. _minio-mc-replicate-export:
=======================
``mc replicate export``
=======================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc replicate export
Syntax
------
.. start-mc-replicate-export-desc
The :mc:`mc replicate export` command exports the JSON-formatted
:ref:`replication rules <minio-bucket-replication-serverside>` for a
MinIO bucket to ``STDOUT``.
.. end-mc-replicate-export-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command exports the replication configuration for the
``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc replicate export myminio/mydata > mydata-replication.json
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] export ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* the :ref:`alias <alias>` of the MinIO deployment and full path to
the bucket or bucket prefix for which to export the replication rules. For
example:
.. code-block:: none
mc replicate export myminio/mybucket
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Export Existing Replication Rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc replicate export` to export bucket replication rules:
.. code-block:: shell
:class: copyable
mc replicate export ALIAS/PATH > bucket-replication-rules.json
- Replace :mc-cmd:`ALIAS <mc replicate export ALIAS>` with the
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate export ALIAS>` with the path to the
bucket or bucket prefix.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

104
source/reference/minio-mc/mc-replicate-import.rst Normal file
View File

@ -0,0 +1,104 @@
.. _minio-mc-replicate-import:
=======================
``mc replicate import``
=======================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc replicate import
Syntax
------
.. start-mc-replicate-import-desc
The :mc:`mc replicate import` command imports JSON-formatted
:ref:`replication rules <minio-bucket-replication-serverside>` for a
MinIO bucket from ``STDIN``.
.. end-mc-replicate-import-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command imports the replication configuration for the
``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc replicate import myminio/mydata < mydata-replication.json
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] import ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* the :ref:`alias <alias>` of the MinIO deployment and full path to
the bucket or bucket prefix for which to import the replication rules. For
example:
.. code-block:: none
mc replicate import myminio/mybucket
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Import Existing Replication Rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc replicate import` to import bucket replication rules:
.. code-block:: shell
:class: copyable
mc replicate import ALIAS/PATH < bucket-replication-rules.json
- Replace :mc-cmd:`ALIAS <mc replicate import ALIAS>` with the
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate import ALIAS>` with the path to the
bucket or bucket prefix.
Behavior
--------
Importing Configuration Overrides Existing Rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:mc-cmd:`mc replicate import` replaces the current bucket replication
rules with those defined in the imported JSON configuration.
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

113
source/reference/minio-mc/mc-replicate-ls.rst Normal file
View File

@ -0,0 +1,113 @@
.. _minio-mc-replicate-ls:
===================
``mc replicate ls``
===================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc replicate ls
Syntax
------
.. start-mc-replicate-ls-desc
The :mc:`mc replicate ls` command lists all
:ref:`replication rules <minio-bucket-replication-serverside>` on a
MinIO bucket.
.. end-mc-replicate-ls-desc
.. tab-set::
.. tab-item:: EXAMPLE
The following command lists all enabled replication rules for the
``mydata`` bucket on the ``myminio`` MinIO deployment:
.. code-block:: shell
:class: copyable
mc replicate ls --status "enabled" myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] replicate ls \
[--status "string"] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* the :ref:`alias <alias>` of the MinIO deployment and full path to
the bucket or bucket prefix for which to list the replication rules. For
example:
.. code-block:: none
mc replicate ls myminio/mybucket
.. mc-cmd:: status
:option:
*Optional* Filter replication rules on the bucket based on their status.
Specify one of the following values:
- ``enabled`` - Show only enabled replication rules.
- ``disabled`` - Show only disabled replication rules.
If omitted, :mc-cmd:`mc replicate ls` defaults to showing all replication
rules.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
List Existing Replication Rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use :mc-cmd:`mc replicate ls` to list bucket replication rules:
.. code-block:: shell
:class: copyable
mc replicate ls ALIAS/PATH
- Replace :mc-cmd:`ALIAS <mc replicate ls ALIAS>` with the
:mc:`alias <mc alias>` of the MinIO deployment.
- Replace :mc-cmd:`PATH <mc replicate ls ALIAS>` with the path to the
bucket or bucket prefix.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

136
source/reference/minio-mc/mc-replicate-resync.rst Normal file
View File

@ -0,0 +1,136 @@
.. _minio-mc-replicate-resync:
=======================
``mc replicate resync``
=======================
.. default-domain:: minio
.. contents:: Table of Contents
:local:
:depth: 2
.. mc:: mc replicate reset
.. mc:: mc replicate resync
Syntax
------
.. start-mc-replicate-resync-desc
The :mc:`mc replicate resync` command resynchronizes all objects in the
specified MinIO bucket to a remote :ref:`replication
<minio-bucket-replication-serverside>` target.
.. end-mc-replicate-resync-desc
This command *requires* first configuring the remote bucket target using the
:mc-cmd:`mc admin bucket remote add` command. You must specify the resulting
remote ARN as part of running :mc-cmd:`mc replicate resync`.
This command supports rebuilding a MinIO deployment using an active-active
replication remote as the "backup" source. See the following tutorials
for more information on active-active replication:
- :ref:`minio-bucket-replication-serverside-twoway`
- :ref:`minio-bucket-replication-serverside-multi`
.. tab-set::
.. tab-item:: EXAMPLE
The following command resynchronizes the content of the
``mydata`` bucket on the ``myminio`` MinIO deployment to the remote
MinIO deployment associated to the specified ``--remote-bucket``:
.. code-block:: shell
:class: copyable
mc replicate resync \
--remote-bucket "arn:minio:replication::d3c086c7-1d64-40c2-954b-fe8222907033:mydata" \
myminio/mydata
.. tab-item:: SYNTAX
The command has the following syntax:
.. code-block:: shell
:class: copyable
mc [GLOBALFLAGS] replicate resync \
--remote-bucket "string" \
[--older-than "string"] \
ALIAS
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-syntax
:end-before: end-minio-syntax
Parameters
~~~~~~~~~~
.. mc-cmd:: ALIAS
*Required* the :ref:`alias <alias>` of the MinIO deployment and full path to
the bucket or bucket prefix which MinIO uses as the replication source. For
example:
.. code-block:: none
mc replicate resync myminio/mybucket
.. mc-cmd:: remote-bucket
:option:
*Required* Specify the ARN for the destination deployment and bucket. You
can retrieve the ARN using :mc-cmd:`mc admin bucket remote`:
- Use the :mc-cmd:`mc admin bucket remote ls` to retrieve a list of
ARNs for the bucket on the destination deployment.
- Use the :mc-cmd:`mc admin bucket remote add` to create a replication ARN
for the bucket on the destination deployment.
.. mc-cmd:: older-than
*Optional* Specify a duration in days where MinIO only resynchronizes
objects older than the specified duration.
Global Flags
~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-globals
:end-before: end-minio-mc-globals
Examples
--------
Resynchronize Remote Replication Target from Source Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following :mc-cmd:`mc replicate resync` command resynchronizes all objects
on the specified source bucket to the remote target regardless of their
replication status:
.. code-block:: shell
:class: copyable
mc replicate resync --remote-bucket "arn:minio:replication::UUID:mybucket" myminio/mybucket
- Replace ``myminio/mybucket`` with the :mc-cmd:`~mc replicate add ALIAS` and
full bucket path for which to create the replication configuration.
- Replace the :mc-cmd-option:`~mc replicate add remote-bucket` value with the
ARN of the remote target. Use :mc-cmd:`mc admin bucket remote ls` to list
all configured remote replication targets.
Behavior
--------
S3 Compatibility
~~~~~~~~~~~~~~~~
.. include:: /includes/common-minio-mc.rst
:start-after: start-minio-mc-s3-compatibility
:end-before: end-minio-mc-s3-compatibility

Some files were not shown because too many files have changed in this diff Show More