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

Versioning Initial Pass (#294)

Browse Source 
* Versioning Initial Pass

* Poornas first pass review

* Refactoring for single sourcing

* Fixups, added mc tag, remaining versioned commands
This commit is contained in:
Ravind Kumar
2020-09-21 19:32:09 -04:00
committed by GitHub
parent 833931246f
commit 61884974d1
15 changed files with 1095 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
source/includes/facts-versioning.rst Normal file
View File

@ -0,0 +1,131 @@
.. start-rewind-desc
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"``.
- To rewind a duration in time, specify the duration as a string in
``#d#hh#mm#ss`` format. For example: ``--rewind "1d2hh3mm4ss"``.
|rewind| requires that the specified |alias| be an S3-compatible service
that supports :ref:`minio-bucket-versioning`. For MinIO deployments, use
:mc-cmd:`mc version` to enable or disable bucket versioning.
.. end-rewind-desc
.. start-versions-desc
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
:mc-cmd:`mc version` to enable or disable bucket versioning.
.. end-versions-desc
.. start-version-id-desc
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
:mc-cmd:`mc version` to enable or disable bucket versioning.
.. 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

10
source/minio-cli/minio-mc.rst
View File

@ -185,6 +185,11 @@ The following table lists :mc-cmd:`mc` commands:
- .. include:: /minio-cli/minio-mc/mc-lock.rst
:start-after: start-mc-lock-desc
:end-before: end-mc-lock-desc
* - :mc:`mc ls`
- .. include:: /minio-cli/minio-mc/mc-ls.rst
:start-after: start-mc-ls-desc
:end-before: end-mc-ls-desc
* - :mc:`mc mb`
- .. include:: /minio-cli/minio-mc/mc-mb.rst
@ -235,6 +240,11 @@ The following table lists :mc-cmd:`mc` commands:
- .. include:: /minio-cli/minio-mc/mc-stat.rst
:start-after: start-mc-stat-desc
:end-before: end-mc-stat-desc
* - :mc:`mc tag`
- .. include:: /minio-cli/minio-mc/mc-tag.rst
:start-after: start-mc-tag-desc
:end-before: end-mc-tag-desc
* - :mc:`mc tree`
- .. include:: /minio-cli/minio-mc/mc-tree.rst

28
source/minio-cli/minio-mc/mc-alias.rst
View File

@ -24,6 +24,34 @@ 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>`.
.. important::
:mc-cmd:`mc alias` requires specifying an access key and corresponding
secret key for a user on the S3-compatible host. :program:`mc` can
only perform operations on that host for which the user has explicit
permission. If the specified user cannot perform an action or access
a resource on the S3 host, :program:`mc` inherits those restrictions.
Quick Reference
---------------
:mc-cmd:`mc alias add ALIAS HOSTNAME ACCESSKEY SECRETKEY <mc alias add>`
Adds the specified S3-compatible host to the
:program:`mc` :ref:`configuration file <mc-configuration>`.
:program:`mc` commands can access the host using the
specified ``ALIAS``.
:mc-cmd:`mc alias remove ALIAS <mc alias remove>`
Removes the S3-compatible host associated to the specified alias from the
:program:`mc` :ref:`configuration file <mc-configuration>`.
:mc-cmd:`mc alias list <mc alias list>`
Lists all S3-compatible hosts and aliases in the :program:`mc`
:ref:`configuration file <mc-configuration>`.
Syntax
------

65
source/minio-cli/minio-mc/mc-cat.rst
View File

@ -22,9 +22,44 @@ display the contents of the specified file or object to ``STDOUT``.
.. end-mc-cat-desc
Quick Reference
---------------
:mc-cmd:`mc cat play\object.txt <mc cat SOURCE>`
Returns the contents of ``object.txt``. ``play`` corresponds to the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible service.
:mc-cmd:`mc cat --rewind "30d" play\myobject.txt <mc cat rewind>`
Returns the contents of the ``object.txt`` as it existed ``30`` days
prior to the current date. ``play`` corresponds to the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible service.
:mc-cmd-option:`mc cat rewind` requires :ref:`bucket versioning
<minio-bucket-versioning>`. Use :mc:`mc version` to enable versioning
on a bucket.
:mc-cmd:`mc cat --version-id 4f85ff5c-ade5-4fb7-be54-1b62dd00f45f play\myobject.txt <mc cat version-id>`
Returns the contents of the ``object.txt`` version with matching
``--version-id``. ``play`` corresponds to the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible service.
:mc-cmd-option:`mc cat version-id` requires :ref:`bucket versioning
<minio-bucket-versioning>`. Use :mc:`mc version` to enable versioning
on a bucket.
Use :mc-cmd:`mc ls versions play\myobject.txt <mc ls versions>` to list all
versions of the object.
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
@ -42,19 +77,16 @@ Syntax
.. mc-cmd:: rewind
:option:
Returns the contents of the object at a specified date or after the
specified duration. Enclose the specified date or duration in double
quotes ``"``.
.. include:: /includes/facts-versioning.rst
:start-after: start-rewind-desc
:end-before: end-rewind-desc
:mc-cmd:`mc cat rewind` requires the specified :mc-cmd:`~mc cat SOURCE`
bucket to have Bucket Versioning enabled. See
:mc-cmd:`mc versioning`.
.. mc-cmd:: version-id, vid
:option:
- For a date in time, specify an ISO8601-formatted timestamp. For example:
``--rewind "2020.03.24T10:00"``.
- For duration, specify a string in ``#d#hh#mm#ss`` format. For example:
``--rewind "1d2hh3mm4ss"``.
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
.. mc-cmd:: encrypt-key
:option:
@ -73,7 +105,6 @@ Syntax
environment variable for retrieving a list of encryption key-value pairs
as an alternative to specifying them on the command line.
Examples
--------
@ -117,7 +148,7 @@ Display the Past Contents of an Object
:end-before: end-play-alias-only
To retrieve the contents of an object a specific number of days in the past,
specify :mc-cmd:`mc cat --rewind` with a duration of ``##d``:
specify :mc-cmd-option:`mc cat rewind` with a duration of ``##d``:
.. code-block:: shell
:class: copyable
@ -125,9 +156,13 @@ specify :mc-cmd:`mc cat --rewind` with a duration of ``##d``:
mc cat --rewind "10d" play/mybucket/object.txt
To retrieve the contents of an object at a specific date or time in the past,
specify :mc-cmd:`mc cat --rewind` with an ISO8601-formatted timestamp:
specify :mc-cmd-option:`mc cat rewind` with an ISO8601-formatted timestamp:
.. code-block:: shell
:class: copyable
mc cat --rewind "2020.03.04T12:34" play/mybucket/object.txt
mc cat --rewind "2020.03.04T12:34" play/mybucket/object.txt
:mc-cmd-option:`mc cat rewind` requires :ref:`bucket versioning
<minio-bucket-versioning>`. Use :mc:`mc version` to enable versioning
on a bucket.

39
source/minio-cli/minio-mc/mc-cp.rst
View File

@ -20,9 +20,34 @@ S3-compatible service.
.. end-mc-cp-desc
Quick Reference
---------------
:mc-cmd:`mc cp ~/Data/myobject.txt play/data/myobject.txt <mc cp>`
Copies ``myobject.txt`` from the local filesystem ``~/Data`` folder to the
``data`` bucket. ``play`` corresponds to the :mc-cmd:`alias <mc alias>` of a
configured S3-compatible service.
:mc-cmd:`mc cp --recursive ~/Data/ play/data <mc cp recursive`
Recursively copies the contents of ``~/Data/`` to the ``data`` bucket.
``play`` corresponds to the :mc-cmd:`alias <mc alias>` of a configured
S3-compatible service.
:mc-cmd:`mc cp --rewind "30d" play/data/object.txt play/data/object-30d.txt <mc cp rewind>`
Copies ``object.txt`` from the ``data`` bucket as it existed 30 days prior to
the current date. The command creates the copy ``objects-30d.txt`` in the
same bucket. ``play`` corresponds to the :mc-cmd:`alias <mc alias>` of a
configured S3-compatible service.
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
@ -72,6 +97,20 @@ Syntax
: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:

51
source/minio-cli/minio-mc/mc-head.rst
View File

@ -20,9 +20,46 @@ where ``n`` is an argument specified to the command.
.. end-mc-head-desc
Quick Reference
---------------
:mc-cmd:`mc head play/object.txt <mc head SOURCE>`
Returns the first 10 lines of ``object.txt``. ``play`` corresponds to the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible service.
:mc-cmd:`mc head --lines 20 play/object.txt <mc head lines>`
Returns the first 20 lines of ``object.txt``. ``play`` corresponds to the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible service.
:mc-cmd:`mc head --rewind "30d" play/object.txt <mc head rewind>`
Returns the first 10 lines of ``object.txt`` as it existed 30 days prior to
the current date. ``play`` corresponds to the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible service.
:mc-cmd-option:`mc head rewind` requires :ref:`bucket versioning
<minio-bucket-versioning>`. Use :mc:`mc version` to enable versioning
on a bucket.
:mc-cmd:`mc head --version-id 4f85ff5c-ade5-4fb7-be54-1b62dd00f45f play/object.txt <mc head version-id>`
Returns the first 10 lines of the ``object.txt`` version with matching
``--version-id``. ``play`` corresponds to the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible service.
:mc-cmd-option:`mc head version-id` requires :ref:`bucket versioning
<minio-bucket-versioning>`. Use :mc:`mc version` to enable versioning
on a bucket.
Use :mc-cmd:`mc ls versions play\myobject.txt <mc ls versions>` to list all
versions of the object.
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`
:mc:`~mc head` has the following syntax:
.. code-block:: shell
@ -50,6 +87,20 @@ Syntax
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:

213
source/minio-cli/minio-mc/mc-legalhold.rst
View File

@ -6,7 +6,7 @@
.. contents:: On This Page
:local:
:depth: 1
:depth: 2
.. mc:: mc legalhold
@ -30,60 +30,207 @@ mode on the object.
See :mc-cmd-option:`mc mb with-lock` for documentation on creating
buckets with object locking enabled.
Quick Reference
---------------
:mc-cmd:`mc legalhold set play/mybucket/myobject.txt <mc legalhold set>`
Enables legalhold on the ``myobject.txt`` object in the ``mybucket`` bucket.
``play`` corresponds to the :mc-cmd:`alias <mc alias>` of a configured
S3-compatible service.
:mc-cmd:`mc legalhold set --recursive play/mybucket <mc legalhold set recursive>`
Recursively enables legalhold on the contents of the ``mybucket`` bucket.
``play`` corresponds to the :mc-cmd:`alias <mc alias>` of a configured
S3-compatible service.
:mc-cmd:`mc legalhold set --rewind "30d" --recursive play/mybucket <mc legalhold set rewind>`
Recursively enables legalhold on the contents of the ``mybucket`` bucket
as they existed 30 days prior to the current date. ``play`` corresponds
to the :mc-cmd:`alias <mc alias>` of a configured S3-compatible service.
:mc-cmd-option:`mc legalhold set rewind` requires :ref:`bucket versioning
<minio-bucket-versioning>`. Use :mc:`mc version` to enable versioning
on a bucket.
:mc-cmd:`mc legalhold clear play/mybucket/myobject.txt <mc legalhold clear>`
Removes legalhold on the ``myobject.txt`` object in the ``mybucket``
bucket. ``play`` corresponds to the :mc-cmd:`alias <mc alias>` of a
configured S3-compatible service.
:mc-cmd:`mc legalhold info play/mybucket/myobject.txt <mc legalhold info>`
Retrieves the legalhold status of the ``myobject.txt`` object in the
``mybucket`` bucket. ``play`` corresponds to the :mc-cmd:`alias <mc alias>`
of a configured S3-compatible service.
Syntax
------
:mc:`~mc legalhold` has the following syntax:
.. code-block:: shell
:class: copyable
mc legalhold [FLAGS] TARGET [ ON | OFF ]
mc legalhold COMMAND
:mc:`~mc legalhold` supports the following arguments:
:mc:`~mc legalhold` supports the following commands:
.. mc-cmd:: TARGET
.. replacements for mc legalhold set
*Required* The full path to the object or bucket on which to enable or
disable the legal hold. Specify the :mc-cmd:`alias <mc alias>`
of a configured S3 service as the prefix to the ``TARGET`` path. For example:
.. |command| replace:: :mc-cmd:`mc legalhold set`
.. |rewind| replace:: :mc-cmd-option:`~mc legalhold info 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 play/mybucket
mc legalhold set [FLAGS] TARGET
You can specify a bucket prefix to apply the legal hold to only objects
in the specified prefix. For example:
The command accepts the following arguments:
.. code-block:: shell
.. mc-cmd:: TARGET
mc legalhold play/mybucket/mydata
*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:
If you specify a path to a bucket or bucket prefix, you must also specify
:mc-cmd-option:`mc legalhold recursive`.
.. code-block::
.. mc-cmd:: recursive, r
mc legalhold set play/mybucket/myobject.txt
Applies the legal hold recursively to all objects in the
:mc-cmd:`~mc legalhold TARGET` bucket.
If you specify a path to a bucket or bucket prefix, you must also
specify :mc-cmd-option:`mc legalhold set recursive`.
.. mc-cmd:: ACTION
.. mc-cmd:: recursive, r
:option:
*Required*
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:
Specify ``ON`` to enable legal hold on the :mc-cmd:`~mc legalhold TARGET`
path.
.. include:: /includes/facts-versioning.rst
:start-after: start-version-id-desc
:end-before: end-version-id-desc
Specify ``OFF`` to disable legal hold on the :mc-cmd:`~mc legalhold TARGET`
path.
.. replacements for mc legalhold clear
Behavior
--------
.. |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:`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.
.. 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
Examples
--------
@ -101,7 +248,7 @@ with object locking enabled.
.. code-block:: shell
mc legalhold --recursive play/mybucket ON
mc legalhold set --recursive play/mybucket
Enable Legal Hold on an Object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -116,5 +263,5 @@ with object locking enabled.
.. code-block:: shell
mc legalhold --recursive play/mybucket/myobject.csv ON
mc legalhold set play/mybucket/myobject.csv

125
source/minio-cli/minio-mc/mc-ls.rst Normal file
View File

@ -0,0 +1,125 @@
=========
``mc ls``
=========
.. default-domain:: minio
.. contents:: On This Page
:local:
:depth: 1
.. 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
Quick Reference
---------------
:mc-cmd:`mc ls play/mybucket <mc ls TARGET>`
Lists the contents of the ``mybucket`` bucket. ``play`` corresponds to the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible service.
:mc-cmd:`mc ls --recursive play <mc ls recursive>`
Recursively lists all buckets and objects on the S3-compatible service.
``play`` corresponds to the :mc-cmd:`alias <mc alias>` of a configured
S3-compatible service.
:mc-cmd:`mc ls --versions play/myversionedbucket <mc ls versions>`
Lists the version of all objects in the ``myversionbucket`` bucket. ``play``
corresponds to the :mc-cmd:`alias <mc alias>` of a configured S3-compatible
service.
:mc-cmd-option:`mc ls versions` requires :ref:`bucket versioning
<minio-bucket-versioning>`. Use :mc:`mc version` to enable versioning
on a bucket.
:mc-cmd:`mc ls --rewind 7d play/myversionedbucket <mc ls versions>`
Lists the contents of the ``myversionedbucket`` bucket as they
existed 7 days prior to the current date. ``play`` corresponds to the
:mc-cmd:`alias <mc alias>` of a configured S3-compatible service.
:mc-cmd-option:`mc ls versions` requires :ref:`bucket versioning
<minio-bucket-versioning>`. Use :mc:`mc version` to enable versioning
on a bucket.
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
:fullpath:
*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.

68
source/minio-cli/minio-mc/mc-rm.rst
View File

@ -23,6 +23,12 @@ To completely remove a bucket, use :mc:`mc rb` instead.
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
@ -81,12 +87,30 @@ Syntax
Allows running :mc:`mc rm` when the :mc-cmd:`~mc rm TARGET` specifies the
root (all buckets) on the S3-compatible service.
.. mc-cmd:: version-id
.. mc-cmd:: versions
:option:
Removes the specified version of the :mc-cmd:`~mc rm TARGET` object. Requires
the bucket to have versioning enabled. Use :mc:`mc version` to enable bucket
versioning.
.. 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:
@ -94,42 +118,6 @@ Syntax
- :mc-cmd-option:`~mc rm rewind`
- :mc-cmd-option:`~mc rm recursive`
.. mc-cmd:: versions
:option:
Removes all versions of the :mc-cmd:`~mc rm TARGET` object or
object(s). Requires the bucket to have versioning enabled. Use
:mc:`mc version` to enable bucket versioning.
Use :mc-cmd-option:`~mc rm rewind` and
:mc-cmd-option:`~mc rm versions` together to clear the
object lock settings of all versions of the object or object(s) which
existed at the specified duration prior to the current date. *or* at the
specified date.
Mutually exclusive with :mc-cmd-option:`~mc rm version-id`.
.. mc-cmd:: rewind
:option:
Removes the latest version of the object or object(s) which existed at either
the specified duration prior to the current date *or* at a specific date.
- For duration, specify a string in ``#d#hh#mm#ss`` format. For example:
``--rewind "1d2hh3mm4ss"``.
- For a date in time, specify an ISO8601-formatted timestamp. For example:
``--rewind "2020.03.24T10:00"``.
For example, to clear the object lock settings to the object or object(s)
as they existed 30 days prior to the current date: ``--rewind "30d"``
Use :mc-cmd-option:`~mc rm rewind` and :mc-cmd-option:`~mc rm versions`
together to remove all versions of the object or object(s) which existed at
the specified duration prior to the current date *or* at the specified date.
Mutually exclusive with :mc-cmd-option:`~mc rm version-id`.
.. mc-cmd:: older-than
:option:

12
source/minio-cli/minio-mc/mc-share.rst
View File

@ -28,6 +28,10 @@ documentation on :aws-docs:`Pre-Signed URLs
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`
.. code-block:: shell
mc share COMMAND
@ -35,6 +39,7 @@ Syntax
:mc:`~mc share` supports the following commands:
.. mc-cmd:: download
:fullpath:
Generates a URL for using an HTTP GET request to retrieve the
object(s).
@ -62,6 +67,13 @@ Syntax
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:

223
source/minio-cli/minio-mc/mc-tag.rst Normal file
View File

@ -0,0 +1,223 @@
==========
``mc tag``
==========
.. default-domain:: minio
.. contents:: On This Page
: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.
Quick Reference
---------------
:mc-cmd:`mc tag set play/mybucket/myobject.csv "tag1=value1,tag2=value2" <mc tag set>`
Applies the tags ``tag1`` and ``tag2`` and their corresponding values to
the ``myobject.csv`` object in the ``mybucket`` bucket. ``play``
corresponds to the :mc-cmd:`alias <mc alias>` of a configured S3-compatible
service.
:mc-cmd:`mc tag remove play/mybucket/myobject.csv <mc tag remove>`
Removes all tags assigned to the ``myobject.csv`` bucket. ``play``
corresponds to the :mc-cmd:`alias <mc alias>` of a configured S3-compatible
service.
:mc-cmd:`mc tag info play/mybucket/myobject.csv <mc tag info>`
Retrieves the tags assigned to the ``myobject.csv`` bucket. ``play``
corresponds to the :mc-cmd:`alias <mc alias>` of a configured S3-compatible
service.
Syntax
------
.. code-block:: shell
mc tag COMMAND
:mc:`mc tag` supports the following commands:
.. |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 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 rm versions` and
:mc-cmd-option:`~mc rm 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 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 rm versions` and
:mc-cmd-option:`~mc rm 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-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
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 rm versions` and
:mc-cmd-option:`~mc rm 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-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

11
source/minio-cli/minio-mc/mc-tree.rst
View File

@ -28,6 +28,10 @@ tree listing of the directory and all of its subdirectories.
Syntax
------
.. |command| replace:: :mc-cmd:`mc tree`
.. |rewind| replace:: :mc-cmd-option:`~mc tree set rewind`
.. |alias| replace:: :mc-cmd-option:`~mc tree set TARGET`
:mc:`~mc tree` has the following syntax:
.. code-block:: shell
@ -55,6 +59,13 @@ Syntax
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
Examples
--------

161
source/minio-cli/minio-mc/mc-version.rst
View File

@ -6,7 +6,7 @@
.. contents:: On This Page
:local:
:depth: 1
:depth: 2
.. mc:: mc version
@ -19,54 +19,6 @@ The :mc:`mc version` command enables or disables bucket versioning.
.. end-mc-version-desc
.. note::
The :release:`RELEASE.2020-08-08T02-33-58Z` release renamed
``mc versioning`` to :mc:`mc version`.
Syntax
------
:mc:`~mc version` has the following syntax:
.. code-block:: shell
:class: copyable
mc version TARGET COMMAND
:mc:`~mc version` supports the following arguments:
.. mc-cmd:: TARGET
**Required** The full path to the bucket on which to enable or
disable bucket versioning. Specify the
:command:`alias <mc alias>` of a configured S3-compatible service as the
prefix to the :mc-cmd:`~mc version TARGET` path. For example:
.. code-block:: shell
mc version play/mybucket COMMAND
.. mc-cmd:: enable
The :mc-cmd:`mc version TARGET enable <mc version enable>` command
enables bucket versioning on the :mc-cmd:`~mc version TARGET` bucket.
.. mc-cmd:: suspend
The :mc-cmd:`mc version TARGET suspend <mc version suspend>` command
disables bucket versioning on the :mc-cmd:`~mc version TARGET` bucket.
.. mc-cmd:: info
The :mc-cmd:`mc version TARGET info <mc version info>` command
returns the current bucket versioning configuration.
Behavior
--------
Object Locking Enables Bucket Versioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -75,8 +27,8 @@ 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.
Requires Erasure Coding
~~~~~~~~~~~~~~~~~~~~~~~
Bucket Versioning Requires Erasure Coding
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Bucket versioning requires that the MinIO deployment supports erasure coding.
See <erasure coding link> for more information.
@ -90,7 +42,112 @@ 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:`mc rm` to delete an object *and* all its versions.
:mc-cmd:`mc rm --versions ALIAS/BUCKET/OBJECT <mc rm versions>` to delete an
object *and* all its versions.
Quick Reference
---------------
:mc-cmd:`mc version enable play/mybucket <mc version enable>`
Enables bucket versioning on the ``mybucket`` bucket. ``play``
corresponds to the :mc-cmd:`alias <mc alias>` of a configured
S3-compatible service.
:mc-cmd:`mc version disable play/mybucket <mc version disable>`
Disables bucket versioning on the ``mybucket`` bucket. ``play``
corresponds to the :mc-cmd:`alias <mc alias>` of a configured
S3-compatible service.
:mc-cmd:`mc version info play/mybucket <mc version info>`
Retrieves the bucket versioning status of the ``mybucket`` bucket. ``play``
corresponds to the :mc-cmd:`alias <mc alias>` of a configured
S3-compatible service.
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 :command:`alias <mc alias>` of a configured
S3-compatible service as the prefix to the :mc-cmd:`~mc version 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 :command:`alias <mc alias>` of a configured
S3-compatible service as the prefix to the :mc-cmd:`~mc version 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 :command:`alias <mc alias>` of a configured
S3-compatible service as the prefix to the :mc-cmd:`~mc version TARGET`
path. For example:
.. code-block:: shell
mc version info play/mybucket
Examples
--------

87
source/minio-features/bucket-versioning.rst Normal file
View File

@ -0,0 +1,87 @@
.. _minio-bucket-versioning:
=================
Bucket Versioning
=================
.. default-domain:: minio
.. contents:: On This Page
:local:
:depth: 2
MinIO supports keeping multiple "versions" of an object in a single bucket.
Write operations which would normally overwrite an existing object instead
result in the creation of a new versioned object. MinIO versioning protects from
unintended overwrites and deletions while providing support for "undoing" a
write operation. Bucket versioning also supports retention and archive policies.
<Diagram>
MinIO generates a unique immutable ID for each object. If a ``PUT`` request
contains an object name which duplicates an existing object, MinIO does *not*
overwrite the "older" object. Instead, MinIO retains all object versions while
considering the most recently written "version" of the object as "latest".
Applications retrieve the latest object version by default, but *may* retrieve
any other version in the history of that object. To view all versions of an
object or objects in a bucket, use the :mc-cmd-option:`mc ls versions` command.
By default, deleting an object does *not* remove all existing versions of
that object. Instead, MinIO places a "delete" marker for the object, such that
applications requesting only the latest object versions do not see the object.
Applications *may* retrieve earlier versions of that object. To completely
delete an object and its entire version history, use the
:mc-cmd-option:`mc rm versions` command.
Enable Bucket Versioning
------------------------
Enabling bucket versioning on a MinIO deployment requires that the deployment
have *at least* four disks. Specifically, Bucket Versioning depends on
:doc:`Erasure Coding </introduction/erasure-coding>`. For MinIO deployments that
meet the disk requirements, use the :mc-cmd:`mc version enable` command to
enable versioning on a specific bucket.
The :mc-cmd:`mc version` command *may* work on other S3-compatible services
depending on their implementation of and support for the AWS S3 API.
Buckets with Existing Content
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After enabling bucket versioning, MinIO begins generating version IDs for
*new* objects created in the bucket. MinIO does *not* iterate through existing
objects to generate version IDs. Existing unversioned objects in a versioned
bucket have a ``null`` version ID.
Suspend Bucket Versioning
-------------------------
You can suspend bucket versioning at any time using
:mc-cmd:`mc version suspend`. MinIO retains all existing object versions. During
suspension, MinIO allows overwrites of any *unversioned* object. Applications
can continue referencing any existing object version.
You can later re-enable object versioning on the bucket. MinIO resumes
generating version IDs for *new* objects, and does not retroactively generate
version IDs for existing unversioned objects. MinIO lists unversioned
objects with a ``null`` version ID.
Version ID Generation
---------------------
MinIO version ID's are DCE 1.1/RFC 4122-compliant Universally Unique Identifiers
(UUID) version 4. Each UUID is a random 128-bit number intended to have a high
likelihood of uniqueness over space and time, *and* that are computationally
difficult to guess. UUID's are globally unique that can be generated without
contacting a global registration authority.
MinIO object version UUID's are *immutable* after creation.
Versioning Dependent Features
-----------------------------
The following MinIO features *require* bucket versioning for functionality:
- Object Locking (:mc-cmd:`mc lock` and :mc-cmd-option:`mc mb with-lock`)
- Object Legal Hold (:mc-cmd:`mc legalhold`)
- Bucket Replication (:mc-cmd:`mc admin bucket remote` and :mc-cmd:`mc replicate`)

15
source/minio-features/overview.rst
View File

@ -16,13 +16,20 @@ The following table lists MinIO features and their corresponding documentation:
* - Feature
- Description
* - :doc:`Bucket Versioning </minio-features/bucket-notifications>`
- MinIO Bucket Versioning allows you to automatically publish notifications
to one or more configured notification targets when specific events
occur in a bucket.
* - :doc:`Bucket Notifications </minio-features/bucket-notifications>`
- MinIO Bucket Notifications allows you to automatically publish
notifications to one or more configured notification targets when
specific events occur in a bucket.
* - :doc:`Bucket Versioning </minio-features/bucket-versioning>`
- MinIO Bucket Versioning supports keeping multiple "versions" of an
object in a single bucket. Write operations which would normally
overwrite an existing object instead result in the creation of a new
versioned object.
.. toctree::
:titlesonly:
:hidden:
/minio-features/bucket-notifications
/minio-features/bucket-versioning