From ef30821063a2f20510bcce42e98a74b7222763f0 Mon Sep 17 00:00:00 2001 From: ravindk89 Date: Thu, 16 Dec 2021 14:19:49 -0500 Subject: [PATCH] DOCS-380: Refactor CLI reference --- source/concepts/bucket-versioning.rst | 12 +- source/conf.py | 2 +- source/includes/common-minio-mc.rst | 96 ++ source/includes/common-minio-tiering.rst | 10 +- source/includes/facts-versioning.rst | 104 +-- source/includes/minio-mc-installation.rst | 21 - source/index.rst | 28 +- .../installation/deploy-minio-standalone.rst | 68 -- ...e-lifecycle-management-expiration-rule.rst | 10 +- .../lifecycle-management-overview.rst | 10 +- .../transition-objects-to-azure.rst | 4 +- .../transition-objects-to-gcs.rst | 4 +- .../transition-objects-to-s3.rst | 4 +- .../bucket-notifications.rst | 53 +- .../object-retention/minio-object-locking.rst | 16 +- source/reference/minio-cli/minio-mc.rst | 368 -------- .../reference/minio-cli/minio-mc/mc-alias.rst | 181 ---- .../reference/minio-cli/minio-mc/mc-diff.rst | 65 -- .../minio-cli/minio-mc/mc-encrypt.rst | 132 --- .../reference/minio-cli/minio-mc/mc-event.rst | 301 ------- .../reference/minio-cli/minio-mc/mc-find.rst | 274 ------ .../reference/minio-cli/minio-mc/mc-ilm.rst | 699 -------------- .../minio-cli/minio-mc/mc-legalhold.rst | 253 ------ .../reference/minio-cli/minio-mc/mc-lock.rst | 27 - source/reference/minio-cli/minio-mc/mc-ls.rst | 160 ---- source/reference/minio-cli/minio-mc/mc-mb.rst | 105 --- .../minio-cli/minio-mc/mc-policy.rst | 271 ------ source/reference/minio-cli/minio-mc/mc-rb.rst | 73 -- .../minio-cli/minio-mc/mc-replicate.rst | 849 ------------------ .../minio-cli/minio-mc/mc-retention.rst | 622 ------------- source/reference/minio-cli/minio-mc/mc-rm.rst | 286 ------ .../reference/minio-cli/minio-mc/mc-share.rst | 286 ------ .../reference/minio-cli/minio-mc/mc-stat.rst | 108 --- .../reference/minio-cli/minio-mc/mc-tag.rst | 253 ------ .../reference/minio-cli/minio-mc/mc-tree.rst | 82 -- .../minio-cli/minio-mc/mc-update.rst | 33 - .../minio-cli/minio-mc/mc-version.rst | 182 ---- .../reference/minio-cli/minio-mc/mc-watch.rst | 98 -- .../{minio-cli => }/minio-mc-admin.rst | 38 +- .../minio-mc-admin/mc-admin-bucket-quota.rst | 0 .../minio-mc-admin/mc-admin-bucket-remote.rst | 0 .../minio-mc-admin/mc-admin-console.rst | 0 .../minio-mc-admin/mc-admin-group.rst | 0 .../minio-mc-admin/mc-admin-heal.rst | 0 .../minio-mc-admin/mc-admin-info.rst | 0 .../minio-mc-admin/mc-admin-kms-key.rst | 0 .../minio-mc-admin/mc-admin-obd.rst | 0 .../minio-mc-admin/mc-admin-policy.rst | 0 .../minio-mc-admin/mc-admin-profile.rst | 0 .../minio-mc-admin/mc-admin-prometheus.rst | 0 .../minio-mc-admin/mc-admin-service.rst | 0 .../minio-mc-admin/mc-admin-speedtest.rst | 0 .../minio-mc-admin/mc-admin-tier.rst | 0 .../minio-mc-admin/mc-admin-top.rst | 0 .../minio-mc-admin/mc-admin-trace.rst | 0 .../minio-mc-admin/mc-admin-update.rst | 0 .../minio-mc-admin/mc-admin-user.rst | 0 .../minio-mc-admin/mc-admin.config.rst | 0 source/reference/minio-mc.rst | 489 ++++++++++ source/reference/minio-mc/mc-alias-list.rst | 123 +++ source/reference/minio-mc/mc-alias-remove.rst | 101 +++ source/reference/minio-mc/mc-alias-set.rst | 202 +++++ .../{minio-cli => }/minio-mc/mc-cat.rst | 218 +++-- .../{minio-cli => }/minio-mc/mc-cp.rst | 531 +++++------ source/reference/minio-mc/mc-diff.rst | 134 +++ .../reference/minio-mc/mc-encrypt-clear.rst | 115 +++ source/reference/minio-mc/mc-encrypt-info.rst | 104 +++ source/reference/minio-mc/mc-encrypt-set.rst | 151 ++++ source/reference/minio-mc/mc-event-add.rst | 239 +++++ source/reference/minio-mc/mc-event-list.rst | 128 +++ source/reference/minio-mc/mc-event-remove.rst | 170 ++++ source/reference/minio-mc/mc-find.rst | 312 +++++++ .../{minio-cli => }/minio-mc/mc-head.rst | 197 ++-- source/reference/minio-mc/mc-ilm-add.rst | 288 ++++++ source/reference/minio-mc/mc-ilm-edit.rst | 268 ++++++ source/reference/minio-mc/mc-ilm-export.rst | 119 +++ source/reference/minio-mc/mc-ilm-import.rst | 126 +++ source/reference/minio-mc/mc-ilm-ls.rst | 116 +++ source/reference/minio-mc/mc-ilm-restore.rst | 162 ++++ source/reference/minio-mc/mc-ilm-rm.rst | 122 +++ .../reference/minio-mc/mc-legalhold-clear.rst | 135 +++ .../reference/minio-mc/mc-legalhold-info.rst | 135 +++ .../reference/minio-mc/mc-legalhold-set.rst | 149 +++ source/reference/minio-mc/mc-ls.rst | 215 +++++ source/reference/minio-mc/mc-mb.rst | 164 ++++ .../{minio-cli => }/minio-mc/mc-mirror.rst | 396 ++++---- .../{minio-cli => }/minio-mc/mc-mv.rst | 365 +++++--- .../reference/minio-mc/mc-policy-get-json.rst | 104 +++ source/reference/minio-mc/mc-policy-get.rst | 108 +++ source/reference/minio-mc/mc-policy-links.rst | 111 +++ source/reference/minio-mc/mc-policy-list.rst | 105 +++ .../reference/minio-mc/mc-policy-set-json.rst | 130 +++ source/reference/minio-mc/mc-policy-set.rst | 140 +++ source/reference/minio-mc/mc-rb.rst | 147 +++ .../reference/minio-mc/mc-replicate-add.rst | 421 +++++++++ .../reference/minio-mc/mc-replicate-edit.rst | 318 +++++++ .../minio-mc/mc-replicate-export.rst | 98 ++ .../minio-mc/mc-replicate-import.rst | 104 +++ source/reference/minio-mc/mc-replicate-ls.rst | 113 +++ .../minio-mc/mc-replicate-resync.rst | 136 +++ source/reference/minio-mc/mc-replicate-rm.rst | 158 ++++ .../minio-mc/mc-replicate-status.rst | 89 ++ .../reference/minio-mc/mc-retention-clear.rst | 199 ++++ .../reference/minio-mc/mc-retention-info.rst | 226 +++++ .../reference/minio-mc/mc-retention-set.rst | 350 ++++++++ source/reference/minio-mc/mc-rm.rst | 411 +++++++++ .../reference/minio-mc/mc-share-download.rst | 185 ++++ source/reference/minio-mc/mc-share-list.rst | 131 +++ source/reference/minio-mc/mc-share-upload.rst | 209 +++++ .../{minio-cli => }/minio-mc/mc-sql.rst | 364 ++++---- source/reference/minio-mc/mc-stat.rst | 195 ++++ source/reference/minio-mc/mc-tag-list.rst | 139 +++ source/reference/minio-mc/mc-tag-remove.rst | 138 +++ source/reference/minio-mc/mc-tag-set.rst | 155 ++++ source/reference/minio-mc/mc-template.rst | 78 ++ source/reference/minio-mc/mc-tree.rst | 128 +++ source/reference/minio-mc/mc-update.rst | 59 ++ source/reference/minio-mc/mc-version.rst | 186 ++++ source/reference/minio-mc/mc-watch.rst | 138 +++ .../reference/minio-server/minio-server.rst | 46 +- ...ver-side-multi-site-bucket-replication.rst | 8 +- ...server-side-one-way-bucket-replication.rst | 23 +- ...server-side-two-way-bucket-replication.rst | 37 +- source/replication/replication-overview.rst | 24 +- .../server-side-encryption-sse-c.rst | 8 +- .../server-side-encryption-sse-kms.rst | 4 +- .../server-side-encryption-sse-s3.rst | 4 +- 127 files changed, 10929 insertions(+), 6960 deletions(-) create mode 100644 source/includes/common-minio-mc.rst delete mode 100644 source/reference/minio-cli/minio-mc.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-alias.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-diff.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-encrypt.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-event.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-find.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-ilm.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-legalhold.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-lock.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-ls.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-mb.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-policy.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-rb.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-replicate.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-retention.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-rm.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-share.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-stat.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-tag.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-tree.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-update.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-version.rst delete mode 100644 source/reference/minio-cli/minio-mc/mc-watch.rst rename source/reference/{minio-cli => }/minio-mc-admin.rst (75%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-bucket-quota.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-bucket-remote.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-console.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-group.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-heal.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-info.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-kms-key.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-obd.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-policy.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-profile.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-prometheus.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-service.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-speedtest.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-tier.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-top.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-trace.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-update.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin-user.rst (100%) rename source/reference/{minio-cli => }/minio-mc-admin/mc-admin.config.rst (100%) create mode 100644 source/reference/minio-mc.rst create mode 100644 source/reference/minio-mc/mc-alias-list.rst create mode 100644 source/reference/minio-mc/mc-alias-remove.rst create mode 100644 source/reference/minio-mc/mc-alias-set.rst rename source/reference/{minio-cli => }/minio-mc/mc-cat.rst (62%) rename source/reference/{minio-cli => }/minio-mc/mc-cp.rst (58%) create mode 100644 source/reference/minio-mc/mc-diff.rst create mode 100644 source/reference/minio-mc/mc-encrypt-clear.rst create mode 100644 source/reference/minio-mc/mc-encrypt-info.rst create mode 100644 source/reference/minio-mc/mc-encrypt-set.rst create mode 100644 source/reference/minio-mc/mc-event-add.rst create mode 100644 source/reference/minio-mc/mc-event-list.rst create mode 100644 source/reference/minio-mc/mc-event-remove.rst create mode 100644 source/reference/minio-mc/mc-find.rst rename source/reference/{minio-cli => }/minio-mc/mc-head.rst (57%) create mode 100644 source/reference/minio-mc/mc-ilm-add.rst create mode 100644 source/reference/minio-mc/mc-ilm-edit.rst create mode 100644 source/reference/minio-mc/mc-ilm-export.rst create mode 100644 source/reference/minio-mc/mc-ilm-import.rst create mode 100644 source/reference/minio-mc/mc-ilm-ls.rst create mode 100644 source/reference/minio-mc/mc-ilm-restore.rst create mode 100644 source/reference/minio-mc/mc-ilm-rm.rst create mode 100644 source/reference/minio-mc/mc-legalhold-clear.rst create mode 100644 source/reference/minio-mc/mc-legalhold-info.rst create mode 100644 source/reference/minio-mc/mc-legalhold-set.rst create mode 100644 source/reference/minio-mc/mc-ls.rst create mode 100644 source/reference/minio-mc/mc-mb.rst rename source/reference/{minio-cli => }/minio-mc/mc-mirror.rst (65%) rename source/reference/{minio-cli => }/minio-mc/mc-mv.rst (59%) create mode 100644 source/reference/minio-mc/mc-policy-get-json.rst create mode 100644 source/reference/minio-mc/mc-policy-get.rst create mode 100644 source/reference/minio-mc/mc-policy-links.rst create mode 100644 source/reference/minio-mc/mc-policy-list.rst create mode 100644 source/reference/minio-mc/mc-policy-set-json.rst create mode 100644 source/reference/minio-mc/mc-policy-set.rst create mode 100644 source/reference/minio-mc/mc-rb.rst create mode 100644 source/reference/minio-mc/mc-replicate-add.rst create mode 100644 source/reference/minio-mc/mc-replicate-edit.rst create mode 100644 source/reference/minio-mc/mc-replicate-export.rst create mode 100644 source/reference/minio-mc/mc-replicate-import.rst create mode 100644 source/reference/minio-mc/mc-replicate-ls.rst create mode 100644 source/reference/minio-mc/mc-replicate-resync.rst create mode 100644 source/reference/minio-mc/mc-replicate-rm.rst create mode 100644 source/reference/minio-mc/mc-replicate-status.rst create mode 100644 source/reference/minio-mc/mc-retention-clear.rst create mode 100644 source/reference/minio-mc/mc-retention-info.rst create mode 100644 source/reference/minio-mc/mc-retention-set.rst create mode 100644 source/reference/minio-mc/mc-rm.rst create mode 100644 source/reference/minio-mc/mc-share-download.rst create mode 100644 source/reference/minio-mc/mc-share-list.rst create mode 100644 source/reference/minio-mc/mc-share-upload.rst rename source/reference/{minio-cli => }/minio-mc/mc-sql.rst (64%) create mode 100644 source/reference/minio-mc/mc-stat.rst create mode 100644 source/reference/minio-mc/mc-tag-list.rst create mode 100644 source/reference/minio-mc/mc-tag-remove.rst create mode 100644 source/reference/minio-mc/mc-tag-set.rst create mode 100644 source/reference/minio-mc/mc-template.rst create mode 100644 source/reference/minio-mc/mc-tree.rst create mode 100644 source/reference/minio-mc/mc-update.rst create mode 100644 source/reference/minio-mc/mc-version.rst create mode 100644 source/reference/minio-mc/mc-watch.rst diff --git a/source/concepts/bucket-versioning.rst b/source/concepts/bucket-versioning.rst index 51344109..99f7503c 100644 --- a/source/concepts/bucket-versioning.rst +++ b/source/concepts/bucket-versioning.rst @@ -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 ` of a configured MinIO deployment. - Replace ``BUCKET`` with the - :mc:`target bucket ` on which to enable + :mc:`target bucket ` 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 ` of a configured MinIO deployment. - Replace ``BUCKET`` with the - :mc:`target bucket ` on which to disable + :mc:`target bucket ` on which to disable versioning. Objects created while versioning is suspended are assigned a diff --git a/source/conf.py b/source/conf.py index 288c1852..fd4e9063 100644 --- a/source/conf.py +++ b/source/conf.py @@ -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 diff --git a/source/includes/common-minio-mc.rst b/source/includes/common-minio-mc.rst new file mode 100644 index 00000000..9ba3376d --- /dev/null +++ b/source/includes/common-minio-mc.rst @@ -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 `_ 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 \ No newline at end of file diff --git a/source/includes/common-minio-tiering.rst b/source/includes/common-minio-tiering.rst index ec11f96f..c4d7625d 100644 --- a/source/includes/common-minio-tiering.rst +++ b/source/includes/common-minio-tiering.rst @@ -23,11 +23,11 @@ The example above specifies the following arguments: * - Argument - Description - * - :mc-cmd:`ALIAS ` + * - :mc-cmd:`ALIAS ` - Specify the :mc:`alias ` of the MinIO deployment for which you are creating the lifecycle management rule. - * - :mc-cmd:`BUCKET ` + * - :mc-cmd:`BUCKET ` - 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 ` - 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 ` - 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. diff --git a/source/includes/facts-versioning.rst b/source/includes/facts-versioning.rst index 4e9fd833..b45739a9 100644 --- a/source/includes/facts-versioning.rst +++ b/source/includes/facts-versioning.rst @@ -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 diff --git a/source/includes/minio-mc-installation.rst b/source/includes/minio-mc-installation.rst index 717b31b6..f37718a0 100644 --- a/source/includes/minio-mc-installation.rst +++ b/source/includes/minio-mc-installation.rst @@ -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 diff --git a/source/index.rst b/source/index.rst index d5c4b60e..3a625f3d 100644 --- a/source/index.rst +++ b/source/index.rst @@ -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 ` +See the :doc:`MinIO Client Complete Reference ` 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 `. + +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 `__ 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 diff --git a/source/installation/deploy-minio-standalone.rst b/source/installation/deploy-minio-standalone.rst index 167f02bf..55ef936d 100644 --- a/source/installation/deploy-minio-standalone.rst +++ b/source/installation/deploy-minio-standalone.rst @@ -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) ` 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 - ` for more information. - - Use the following format when specifying the encryption key: - - ``:`` - - - Replace the ```` 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 - ` for more information. - - - Replace ```` 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) ` 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 - ` for more information. - Use the following format when specifying the encryption key: - - ``:`` - - - Replace the ```` 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 - ` for more information. - - - Replace ```` 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 ` as required by your deployment. diff --git a/source/lifecycle-management/create-lifecycle-management-expiration-rule.rst b/source/lifecycle-management/create-lifecycle-management-expiration-rule.rst index 2d4efdf1..27620ec4 100644 --- a/source/lifecycle-management/create-lifecycle-management-expiration-rule.rst +++ b/source/lifecycle-management/create-lifecycle-management-expiration-rule.rst @@ -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 ` with the +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the S3-compatible host. -- Replace :mc-cmd:`PATH ` with the path to the bucket on the +- Replace :mc-cmd:`PATH ` with the path to the bucket on the S3-compatible host. -- Replace :mc-cmd:`DATE ` with the number of days after +- Replace :mc-cmd:`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 ` with the +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the S3-compatible host. -- Replace :mc-cmd:`PATH ` with the path to the bucket on the +- Replace :mc-cmd:`PATH ` with the path to the bucket on the S3-compatible host. - Replace :mc-cmd:`NONCURRENT_DAYS diff --git a/source/lifecycle-management/lifecycle-management-overview.rst b/source/lifecycle-management/lifecycle-management-overview.rst index 67a884d8..c38feb96 100644 --- a/source/lifecycle-management/lifecycle-management-overview.rst +++ b/source/lifecycle-management/lifecycle-management-overview.rst @@ -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 ` configured, MinIO does not replicate objects deleted by a lifecycle management expiration rule. diff --git a/source/lifecycle-management/transition-objects-to-azure.rst b/source/lifecycle-management/transition-objects-to-azure.rst index 3a86d97b..912ca105 100644 --- a/source/lifecycle-management/transition-objects-to-azure.rst +++ b/source/lifecycle-management/transition-objects-to-azure.rst @@ -206,8 +206,8 @@ rules: mc ilm ls ALIAS/PATH --transition -- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the MinIO deployment. -- Replace :mc-cmd:`PATH ` with the name of the bucket for +- Replace :mc-cmd:`PATH ` with the name of the bucket for which to retrieve the configured lifecycle management rules. diff --git a/source/lifecycle-management/transition-objects-to-gcs.rst b/source/lifecycle-management/transition-objects-to-gcs.rst index 8ea6236a..a66f9822 100644 --- a/source/lifecycle-management/transition-objects-to-gcs.rst +++ b/source/lifecycle-management/transition-objects-to-gcs.rst @@ -200,8 +200,8 @@ rules: mc ilm ls ALIAS/PATH --transition -- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the MinIO deployment. -- Replace :mc-cmd:`PATH ` with the name of the bucket for +- Replace :mc-cmd:`PATH ` with the name of the bucket for which to retrieve the configured lifecycle management rules. diff --git a/source/lifecycle-management/transition-objects-to-s3.rst b/source/lifecycle-management/transition-objects-to-s3.rst index bfce401c..948ae45d 100644 --- a/source/lifecycle-management/transition-objects-to-s3.rst +++ b/source/lifecycle-management/transition-objects-to-s3.rst @@ -218,8 +218,8 @@ rules: mc ilm ls ALIAS/PATH --transition -- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the MinIO deployment. -- Replace :mc-cmd:`PATH ` with the name of the bucket for +- Replace :mc-cmd:`PATH ` with the name of the bucket for which to retrieve the configured lifecycle management rules. diff --git a/source/monitoring/bucket-notifications/bucket-notifications.rst b/source/monitoring/bucket-notifications/bucket-notifications.rst index ae514f2e..90ec6899 100644 --- a/source/monitoring/bucket-notifications/bucket-notifications.rst +++ b/source/monitoring/bucket-notifications/bucket-notifications.rst @@ -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:: diff --git a/source/object-retention/minio-object-locking.rst b/source/object-retention/minio-object-locking.rst index 3a8b6428..57e6d096 100644 --- a/source/object-retention/minio-object-locking.rst +++ b/source/object-retention/minio-object-locking.rst @@ -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 ` of the bucket to create. + :mc:`name ` 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 ` and :mc-cmd-option:`--default ` options to set the default retention mode for a bucket: @@ -299,10 +299,10 @@ preferred SDK. - Replace :mc-cmd:`DURATION ` with the duration for which the object lock remains in effect. - - Replace :mc-cmd:`ALIAS ` with the + - Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of a configured MinIO deployment. - - Replace :mc-cmd:`BUCKET ` with the + - Replace :mc-cmd:`BUCKET ` 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 ` with the + - Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of a configured MinIO deployment. - - Replace :mc-cmd:`PATH ` with the + - Replace :mc-cmd:`PATH ` with the path to the object for which to enable the legal hold. .. _minio-object-locking-retention-modes: diff --git a/source/reference/minio-cli/minio-mc.rst b/source/reference/minio-cli/minio-mc.rst deleted file mode 100644 index bc014b57..00000000 --- a/source/reference/minio-cli/minio-mc.rst +++ /dev/null @@ -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 `. - -.. 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 ` 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 ` 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 `_ 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/* - - - - diff --git a/source/reference/minio-cli/minio-mc/mc-alias.rst b/source/reference/minio-cli/minio-mc/mc-alias.rst deleted file mode 100644 index 07c0de3d..00000000 --- a/source/reference/minio-cli/minio-mc/mc-alias.rst +++ /dev/null @@ -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 `. - -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 `. - -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 - diff --git a/source/reference/minio-cli/minio-mc/mc-diff.rst b/source/reference/minio-cli/minio-mc/mc-diff.rst deleted file mode 100644 index 268ba422..00000000 --- a/source/reference/minio-cli/minio-mc/mc-diff.rst +++ /dev/null @@ -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. \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc/mc-encrypt.rst b/source/reference/minio-cli/minio-mc/mc-encrypt.rst deleted file mode 100644 index 7b0abba9..00000000 --- a/source/reference/minio-cli/minio-mc/mc-encrypt.rst +++ /dev/null @@ -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 - - diff --git a/source/reference/minio-cli/minio-mc/mc-event.rst b/source/reference/minio-cli/minio-mc/mc-event.rst deleted file mode 100644 index 017482eb..00000000 --- a/source/reference/minio-cli/minio-mc/mc-event.rst +++ /dev/null @@ -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 ` 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 -`. - -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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the path to the bucket on - the S3-compatible host. - -- Replace :mc-cmd:`ARN ` with the - :aws-docs:`Amazon Resource Name (ARN) - ` of the notification target. - -- Replace :mc-cmd:`EVENTS ` with a comma-separated list of - :ref:`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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the path to the bucket on - the S3-compatible host. - -- Replace :mc-cmd:`ARN ` with the - :aws-docs:`Amazon Resource Name (ARN) - ` of the notification target. - -- Replace :mc-cmd:`EVENTS ` with a comma-separated list of - :ref:`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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the path to the bucket on - the S3-compatible host. - -- Replace :mc-cmd:`ARN ` with the - :aws-docs:`Amazon Resource Name (ARN) - ` 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 ` and bucket to - which the command adds the new event notification. Specify the - :mc-cmd:`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) - ` 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 ` and bucket from - which the command removes the event notification. Specify the - :mc-cmd:`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) - ` 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 ` and bucket to - which the command lists event notification. Specify the - :mc-cmd:`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) - ` 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. - - - diff --git a/source/reference/minio-cli/minio-mc/mc-find.rst b/source/reference/minio-cli/minio-mc/mc-find.rst deleted file mode 100644 index 6fee1fa0..00000000 --- a/source/reference/minio-cli/minio-mc/mc-find.rst +++ /dev/null @@ -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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`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 ` 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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the path to a bucket on the - S3-compatible host. - -- Replace :mc-cmd:`EXTENSION ` 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 ` with the full file path to the - directory to search. - -- Replace :mc-cmd:`EXTENSION ` with the file extention of the - object. - -- Replace :mc-cmd:`ALIAS ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`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 ` 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 ` 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 ` 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-cmd:: smaller - :option: - - Match all objects smaller than the specifized size in - :ref:`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. - - - - \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc/mc-ilm.rst b/source/reference/minio-cli/minio-mc/mc-ilm.rst deleted file mode 100644 index 928960ff..00000000 --- a/source/reference/minio-cli/minio-mc/mc-ilm.rst +++ /dev/null @@ -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 ` 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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the path to the bucket on the - S3-compatible host. - -- Replace :mc-cmd:`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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` with the unique name of the lifecycle - management rule. - -- Replace :mc-cmd:`ALIAS ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` - 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 ` 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 - `. - 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 `. - 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 - ` 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 - `. - 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 `. - 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 - ` 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 ` 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 ` 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 - diff --git a/source/reference/minio-cli/minio-mc/mc-legalhold.rst b/source/reference/minio-cli/minio-mc/mc-legalhold.rst deleted file mode 100644 index 50a628af..00000000 --- a/source/reference/minio-cli/minio-mc/mc-legalhold.rst +++ /dev/null @@ -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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` 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 ` 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 ` 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 - diff --git a/source/reference/minio-cli/minio-mc/mc-lock.rst b/source/reference/minio-cli/minio-mc/mc-lock.rst deleted file mode 100644 index 6e8ff53f..00000000 --- a/source/reference/minio-cli/minio-mc/mc-lock.rst +++ /dev/null @@ -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. \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc/mc-ls.rst b/source/reference/minio-cli/minio-mc/mc-ls.rst deleted file mode 100644 index e49ad9c3..00000000 --- a/source/reference/minio-cli/minio-mc/mc-ls.rst +++ /dev/null @@ -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 ` to list the contents of a bucket: - -.. code-block:: shell - :class: copyable - - mc ls [--recursive] ALIAS/PATH - -- Replace :mc-cmd:`ALIAS ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the path to the bucket or object on - the S3-compatible host. - -- Replace :mc-cmd:`DURATION ` 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 ` 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 ` 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. \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc/mc-mb.rst b/source/reference/minio-cli/minio-mc/mc-mb.rst deleted file mode 100644 index 8263ccb1..00000000 --- a/source/reference/minio-cli/minio-mc/mc-mb.rst +++ /dev/null @@ -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 `. :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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`BUCKET ` 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 ` 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. - diff --git a/source/reference/minio-cli/minio-mc/mc-policy.rst b/source/reference/minio-cli/minio-mc/mc-policy.rst deleted file mode 100644 index 2882679c..00000000 --- a/source/reference/minio-cli/minio-mc/mc-policy.rst +++ /dev/null @@ -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 `. 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 ` with the - :mc-cmd:`alias ` of a configured S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the destination bucket. - -Use :mc-cmd:`mc policy get-json` to retrieve the -:s3-docs:`IAM JSON policy document ` of a bucket: - -.. code-block:: shell - :class: copyable - - mc policy get-json ALIAS/PATH - -- Replace :mc-cmd:`ALIAS ` with the - :mc-cmd:`alias ` of a configured S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` with a supported - :mc-cmd:`permission `. - -- Replace :mc-cmd:`ALIAS ` with the - :mc-cmd:`alias ` of a configured S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the destination bucket. - -Use :mc-cmd:`mc policy set-json` to use a -:s3-docs:`IAM JSON policy document ` to set the anonymous -policy for a bucket: - -.. code-block:: shell - :class: copyable - - mc policy set-json POLICY ALIAS/PATH - -- Replace :mc-cmd:`POLICY ` with the JSON-formatted - IAM policy document to use for setting the anonymous policy. - -- Replace :mc-cmd:`ALIAS ` with the - :mc-cmd:`alias ` of a configured S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` with the - :mc-cmd:`alias ` of a configured S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` 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 ` 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 ` 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 ` - 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 - ` 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 - ` of a configured S3 service as the prefix to the ``TARGET`` - path. For example: - - .. code-block:: shell - - mc set public play/mybucket - - - diff --git a/source/reference/minio-cli/minio-mc/mc-rb.rst b/source/reference/minio-cli/minio-mc/mc-rb.rst deleted file mode 100644 index f7c79b03..00000000 --- a/source/reference/minio-cli/minio-mc/mc-rb.rst +++ /dev/null @@ -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 ` with the :mc-cmd:`alias ` of - a configured S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` 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. diff --git a/source/reference/minio-cli/minio-mc/mc-replicate.rst b/source/reference/minio-cli/minio-mc/mc-replicate.rst deleted file mode 100644 index 498ab8db..00000000 --- a/source/reference/minio-cli/minio-mc/mc-replicate.rst +++ /dev/null @@ -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 ` -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 ` with the - :mc:`alias ` of the MinIO deployment. - -- Replace :mc-cmd:`PATH ` 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 -` and :mc:`minio` -:minio-git:`RELEASE.2021-06-07T21-40-51Z -`, MinIO supports automatically -replicating existing objects in a bucket. MinIO existing object replication -implements functionality similar to -`AWS: Replicating existing objects between S3 buckets -`__ -without the overhead of contacting technical support. - -- To enable replication of existing objects when creating a new replication - rule, include ``"existing-objects"`` to the list of replication features - specified to :mc-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 -` 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 -`, 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 ` 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 ` *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 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 ` 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 ` with the - :mc:`alias ` of the MinIO deployment. - -- Replace :mc-cmd:`PATH ` with the path to the - bucket or bucket prefix on which to add the new rule. - -- Replace :mc-cmd:`ARN ` with the ARN of the - remote bucket target created by :mc:`mc admin bucket remote`. - -- Replace :mc-cmd:`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 ` with the - :mc:`alias ` of the MinIO deployment. - -- Replace :mc-cmd:`PATH ` with the path to the - bucket or bucket prefix on which the rule exists. - -- Replace :mc-cmd:`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 ` with the - :mc:`alias ` of the MinIO deployment. - -- Replace :mc-cmd:`PATH ` with the path to the - bucket or bucket prefix on which the rule exists. - -- Replace :mc-cmd:`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 ` with the - :mc:`alias ` of the MinIO deployment. - -- Replace :mc-cmd:`PATH ` with the path to the - bucket or bucket prefix on which the rule exists. - -- Replace :mc-cmd:`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 ` 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 ` 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 ` 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 - ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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. diff --git a/source/reference/minio-cli/minio-mc/mc-retention.rst b/source/reference/minio-cli/minio-mc/mc-retention.rst deleted file mode 100644 index 022ac6fc..00000000 --- a/source/reference/minio-cli/minio-mc/mc-retention.rst +++ /dev/null @@ -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 ` 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 `, -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:`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 ` 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 ` with the retention mode to - enable. MinIO supports the AWS S3 retention modes ``governance`` and - ``compliance``. - -- Replace :mc-cmd:`DURATION ` with the duration which - the object lock should remain in effect. For example, to set a retention - period of 30 days, specify ``30d``. - -- Replace :mc-cmd:`ALIAS ` with the - :mc:`alias ` of a configured S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` with the version - of the object. - - - Replace :mc-cmd:`MODE ` with the retention mode - to enable. MinIO supports the AWS S3 retention modes ``governance`` and - ``compliance``. - - - Replace :mc-cmd:`DURATION ` with the duration - which the object lock should remain in effect. For example, to set a - retention period of 30 days, specify ``30d``. - - - Replace :mc-cmd:`ALIAS ` with the - :mc:`alias ` of a configured S3-compatible host. - - - Replace :mc-cmd:`PATH ` 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 ` with the retention mode - to enable. MinIO supports the AWS S3 retention modes ``governance`` and - ``compliance``. - - - Replace :mc-cmd:`DURATION ` with the duration - which the object lock should remain in effect. For example, to set a - retention period of 30 days, specify ``30d``. - - - - Replace :mc-cmd:`ALIAS ` with the - :mc:`alias ` of a configured S3-compatible host. - - - Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of a configured S3-compatible host. - - - Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of a configured S3-compatible host. - - - Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of a configured S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of a configured S3-compatible host. - - - Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of a configured S3-compatible host. - - - Replace :mc-cmd:`PATH ` 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 - ` 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 ` 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 ` 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 ` 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. - - - - diff --git a/source/reference/minio-cli/minio-mc/mc-rm.rst b/source/reference/minio-cli/minio-mc/mc-rm.rst deleted file mode 100644 index cbb7f15b..00000000 --- a/source/reference/minio-cli/minio-mc/mc-rm.rst +++ /dev/null @@ -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 `. - -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 ` with the :mc:`alias ` of - a configured S3-compatible service. - -- Replace :mc-cmd:`PATH ` 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 ` with the :mc:`alias ` of - a configured S3-compatible service. - -- Replace :mc-cmd:`PATH ` 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 ` with the :mc:`alias ` of - a configured S3-compatible service. - -- Replace :mc-cmd:`PATH ` 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 ` with the :mc:`alias ` of - a configured S3-compatible service. - -- Replace :mc-cmd:`PATH ` with the path to the object. For - example, ``/mybucket/myobject``. - -- Replace :mc-cmd:`DURATION ` 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 ` 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 ` 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. - - - - - diff --git a/source/reference/minio-cli/minio-mc/mc-share.rst b/source/reference/minio-cli/minio-mc/mc-share.rst deleted file mode 100644 index e66c856a..00000000 --- a/source/reference/minio-cli/minio-mc/mc-share.rst +++ /dev/null @@ -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 -`. - -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 ` with the - :mc:`alias ` of the S3-compatible host. - - - Replace :mc-cmd:`PATH ` with the path to the - object on the S3-compatible host. - - - Replace :mc-cmd:`DURATION ` 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 ` with the - :mc:`alias ` of the S3-compatible host. - - - Replace :mc-cmd:`PATH ` with the path to the - bucket or bucket prefix on the S3-compatible host. - - - Replace :mc-cmd:`DURATION ` 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 ` with the - :mc:`alias ` of the S3-compatible host. - - - Replace :mc-cmd:`PATH ` with the path to the - object on the S3-compatible host. - - - Replace :mc-cmd:`DURATION ` 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 ` with the - :mc:`alias ` of the S3-compatible host. - - - Replace :mc-cmd:`PATH ` with the path to the - bucket or bucket prefix on the S3-compatible host. - - - Replace :mc-cmd:`DURATION ` 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 ```` string in the returned CURL command with the path - to the file to upload. - - - Replace the ```` 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/ -F file=@ - - Replace ```` with the path to the file to upload. - - Replace ```` 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`. - diff --git a/source/reference/minio-cli/minio-mc/mc-stat.rst b/source/reference/minio-cli/minio-mc/mc-stat.rst deleted file mode 100644 index 2d7f872e..00000000 --- a/source/reference/minio-cli/minio-mc/mc-stat.rst +++ /dev/null @@ -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 ` with the - :mc:`alias ` of the S3-compatible host. - - - Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of the S3-compatible host. - - - Replace :mc-cmd:`PATH ` 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 ` - 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. diff --git a/source/reference/minio-cli/minio-mc/mc-tag.rst b/source/reference/minio-cli/minio-mc/mc-tag.rst deleted file mode 100644 index 05951194..00000000 --- a/source/reference/minio-cli/minio-mc/mc-tag.rst +++ /dev/null @@ -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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the path to the bucket - or object on the S3-compatible host. - -- Replace :mc-cmd:`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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` - 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 ` 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 [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 ` 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 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 diff --git a/source/reference/minio-cli/minio-mc/mc-tree.rst b/source/reference/minio-cli/minio-mc/mc-tree.rst deleted file mode 100644 index f766c17d..00000000 --- a/source/reference/minio-cli/minio-mc/mc-tree.rst +++ /dev/null @@ -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 ` with the :mc:`alias ` - of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` - 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 - diff --git a/source/reference/minio-cli/minio-mc/mc-update.rst b/source/reference/minio-cli/minio-mc/mc-update.rst deleted file mode 100644 index 8e3e6840..00000000 --- a/source/reference/minio-cli/minio-mc/mc-update.rst +++ /dev/null @@ -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. \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc/mc-version.rst b/source/reference/minio-cli/minio-mc/mc-version.rst deleted file mode 100644 index 93a09f5f..00000000 --- a/source/reference/minio-cli/minio-mc/mc-version.rst +++ /dev/null @@ -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 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 ` 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 ` with the - :mc:`alias ` of a configured S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of a configured S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` with the - :mc:`alias ` of a configured S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` 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 ` 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 ` 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 \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc/mc-watch.rst b/source/reference/minio-cli/minio-mc/mc-watch.rst deleted file mode 100644 index dcd12ce9..00000000 --- a/source/reference/minio-cli/minio-mc/mc-watch.rst +++ /dev/null @@ -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 ` with the :mc:`alias ` - of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` 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 ` and bucket *or* the local - filesystem directory to watch for event notifications. Specify the - :mc-cmd:`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. - - - \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc-admin.rst b/source/reference/minio-mc-admin.rst similarity index 75% rename from source/reference/minio-cli/minio-mc-admin.rst rename to source/reference/minio-mc-admin.rst index 374cf17d..39706519 100644 --- a/source/reference/minio-cli/minio-mc-admin.rst +++ b/source/reference/minio-mc-admin.rst @@ -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/* diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst b/source/reference/minio-mc-admin/mc-admin-bucket-quota.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst rename to source/reference/minio-mc-admin/mc-admin-bucket-quota.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst b/source/reference/minio-mc-admin/mc-admin-bucket-remote.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst rename to source/reference/minio-mc-admin/mc-admin-bucket-remote.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-console.rst b/source/reference/minio-mc-admin/mc-admin-console.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-console.rst rename to source/reference/minio-mc-admin/mc-admin-console.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-group.rst b/source/reference/minio-mc-admin/mc-admin-group.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-group.rst rename to source/reference/minio-mc-admin/mc-admin-group.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-heal.rst b/source/reference/minio-mc-admin/mc-admin-heal.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-heal.rst rename to source/reference/minio-mc-admin/mc-admin-heal.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-info.rst b/source/reference/minio-mc-admin/mc-admin-info.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-info.rst rename to source/reference/minio-mc-admin/mc-admin-info.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-kms-key.rst b/source/reference/minio-mc-admin/mc-admin-kms-key.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-kms-key.rst rename to source/reference/minio-mc-admin/mc-admin-kms-key.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-obd.rst b/source/reference/minio-mc-admin/mc-admin-obd.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-obd.rst rename to source/reference/minio-mc-admin/mc-admin-obd.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-policy.rst b/source/reference/minio-mc-admin/mc-admin-policy.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-policy.rst rename to source/reference/minio-mc-admin/mc-admin-policy.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-profile.rst b/source/reference/minio-mc-admin/mc-admin-profile.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-profile.rst rename to source/reference/minio-mc-admin/mc-admin-profile.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-prometheus.rst b/source/reference/minio-mc-admin/mc-admin-prometheus.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-prometheus.rst rename to source/reference/minio-mc-admin/mc-admin-prometheus.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-service.rst b/source/reference/minio-mc-admin/mc-admin-service.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-service.rst rename to source/reference/minio-mc-admin/mc-admin-service.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-speedtest.rst b/source/reference/minio-mc-admin/mc-admin-speedtest.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-speedtest.rst rename to source/reference/minio-mc-admin/mc-admin-speedtest.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-tier.rst b/source/reference/minio-mc-admin/mc-admin-tier.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-tier.rst rename to source/reference/minio-mc-admin/mc-admin-tier.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-top.rst b/source/reference/minio-mc-admin/mc-admin-top.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-top.rst rename to source/reference/minio-mc-admin/mc-admin-top.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-trace.rst b/source/reference/minio-mc-admin/mc-admin-trace.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-trace.rst rename to source/reference/minio-mc-admin/mc-admin-trace.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-update.rst b/source/reference/minio-mc-admin/mc-admin-update.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-update.rst rename to source/reference/minio-mc-admin/mc-admin-update.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin-user.rst b/source/reference/minio-mc-admin/mc-admin-user.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin-user.rst rename to source/reference/minio-mc-admin/mc-admin-user.rst diff --git a/source/reference/minio-cli/minio-mc-admin/mc-admin.config.rst b/source/reference/minio-mc-admin/mc-admin.config.rst similarity index 100% rename from source/reference/minio-cli/minio-mc-admin/mc-admin.config.rst rename to source/reference/minio-mc-admin/mc-admin.config.rst diff --git a/source/reference/minio-mc.rst b/source/reference/minio-mc.rst new file mode 100644 index 00000000..b835f2fd --- /dev/null +++ b/source/reference/minio-mc.rst @@ -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 ` + licensed Free and Open Source (FOSS) software. + + Applications integrating :program:`mc` may trigger AGPLv3 compliance + requirements. `MinIO Commericla Licensing `__ + 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 `. + +.. 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 + ` 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 ` + 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) ` + 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 ` 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 + `. + + * - :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 ` + 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 ` command configures and + manages the :ref:`Server-Side Bucket Replication + ` for a MinIO deployment, including + :ref:`active-active replication configurations + ` and + :ref:`resynchronization `. + + + * - :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 ` 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 ` 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 `_ 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 diff --git a/source/reference/minio-mc/mc-alias-list.rst b/source/reference/minio-mc/mc-alias-list.rst new file mode 100644 index 00000000..e37dc735 --- /dev/null +++ b/source/reference/minio-mc/mc-alias-list.rst @@ -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 ` 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 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-alias-remove.rst b/source/reference/minio-mc/mc-alias-remove.rst new file mode 100644 index 00000000..38d8a380 --- /dev/null +++ b/source/reference/minio-mc/mc-alias-remove.rst @@ -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 ` 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 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-alias-set.rst b/source/reference/minio-mc/mc-alias-set.rst new file mode 100644 index 00000000..e8271c36 --- /dev/null +++ b/source/reference/minio-mc/mc-alias-set.rst @@ -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 ` 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 `__ + 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 `. + +For all other S3-compatible services, defer to the documentation for that +service. \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc/mc-cat.rst b/source/reference/minio-mc/mc-cat.rst similarity index 62% rename from source/reference/minio-cli/minio-mc/mc-cat.rst rename to source/reference/minio-mc/mc-cat.rst index d60063c4..c6ca4892 100644 --- a/source/reference/minio-cli/minio-mc/mc-cat.rst +++ b/source/reference/minio-mc/mc-cat.rst @@ -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 ` with the - :mc:`alias ` of the S3-compatible host. + .. tab-item:: SYNTAX -- Replace :mc-cmd:`PATH ` 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 ` with the - :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 ` with the path to the object on the - S3-compatible host. +Parameters +~~~~~~~~~~ -- Replace :mc-cmd:`DURATION ` 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 ` of a MinIO or other S3-compatible + service. -View an S3 Object with Specific Version -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. mc-cmd:: PATH -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 ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the path to the object on the - S3-compatible host. - -- Replace :mc-cmd:`VERSION ` 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 ` 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 - + *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 ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` with the path to the object on the + S3-compatible host. + +- Replace :mc-cmd:`DURATION ` 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 ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` with the path to the object on the + S3-compatible host. + +- Replace :mc-cmd:`VERSION ` 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 diff --git a/source/reference/minio-cli/minio-mc/mc-cp.rst b/source/reference/minio-mc/mc-cp.rst similarity index 58% rename from source/reference/minio-cli/minio-mc/mc-cp.rst rename to source/reference/minio-mc/mc-cp.rst index 4a50d2fe..d6eefb07 100644 --- a/source/reference/minio-cli/minio-mc/mc-cp.rst +++ b/source/reference/minio-mc/mc-cp.rst @@ -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 ` 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 ` 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 ` 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 + ` 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 + ` 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 + ` 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 `. - - 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 ` - 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 `. 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 `. 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 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-diff.rst b/source/reference/minio-mc/mc-diff.rst new file mode 100644 index 00000000..4a9876e5 --- /dev/null +++ b/source/reference/minio-mc/mc-diff.rst @@ -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 ` 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 ` 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 diff --git a/source/reference/minio-mc/mc-encrypt-clear.rst b/source/reference/minio-mc/mc-encrypt-clear.rst new file mode 100644 index 00000000..e541ef50 --- /dev/null +++ b/source/reference/minio-mc/mc-encrypt-clear.rst @@ -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 `: + + .. 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 ` 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 ` 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 diff --git a/source/reference/minio-mc/mc-encrypt-info.rst b/source/reference/minio-mc/mc-encrypt-info.rst new file mode 100644 index 00000000..12b819df --- /dev/null +++ b/source/reference/minio-mc/mc-encrypt-info.rst @@ -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 ` 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 ` 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 diff --git a/source/reference/minio-mc/mc-encrypt-set.rst b/source/reference/minio-mc/mc-encrypt-set.rst new file mode 100644 index 00000000..d06fffe9 --- /dev/null +++ b/source/reference/minio-mc/mc-encrypt-set.rst @@ -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 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 ` +and :ref:`SSE-S3 `. + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command sets the default + :ref:`SSE-KMS encryption key ` 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 ` 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 ` + + - 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 ` 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. diff --git a/source/reference/minio-mc/mc-event-add.rst b/source/reference/minio-mc/mc-event-add.rst new file mode 100644 index 00000000..ef8b4713 --- /dev/null +++ b/source/reference/minio-mc/mc-event-add.rst @@ -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 `. + +.. 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 ` 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 ` 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) + ` 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 `: + + .. 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 ` 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 `. + + +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 `: + +.. 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 +`. + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility diff --git a/source/reference/minio-mc/mc-event-list.rst b/source/reference/minio-mc/mc-event-list.rst new file mode 100644 index 00000000..44109aee --- /dev/null +++ b/source/reference/minio-mc/mc-event-list.rst @@ -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 ` + 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 ` 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) + ` 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 ` 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 `. + +Behavior +-------- + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility diff --git a/source/reference/minio-mc/mc-event-remove.rst b/source/reference/minio-mc/mc-event-remove.rst new file mode 100644 index 00000000..d577ca5a --- /dev/null +++ b/source/reference/minio-mc/mc-event-remove.rst @@ -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 ` + 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 ` 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) + ` 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 `: + + .. 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 ` 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 `. + +Behavior +-------- + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility diff --git a/source/reference/minio-mc/mc-find.rst b/source/reference/minio-mc/mc-find.rst new file mode 100644 index 00000000..b2d48c78 --- /dev/null +++ b/source/reference/minio-mc/mc-find.rst @@ -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 ` 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 + ` 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-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 ` 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-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 ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`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 ` 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 ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` with the path to a bucket on the + S3-compatible host. + +- Replace :mc-cmd:`EXTENSION ` 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 ` with the full file path to the + directory to search. + +- Replace :mc-cmd:`EXTENSION ` with the file extention of the + object. + +- Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`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" + +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 + \ No newline at end of file diff --git a/source/reference/minio-cli/minio-mc/mc-head.rst b/source/reference/minio-mc/mc-head.rst similarity index 57% rename from source/reference/minio-cli/minio-mc/mc-head.rst rename to source/reference/minio-mc/mc-head.rst index 5318bc37..1d6913c3 100644 --- a/source/reference/minio-cli/minio-mc/mc-head.rst +++ b/source/reference/minio-mc/mc-head.rst @@ -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 ` 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 ` with the +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the S3-compatible host. -- Replace :mc-cmd:`PATH ` with the path to the object on the +- Replace :mc-cmd:`PATH ` 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 ` with the +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the S3-compatible host. -- Replace :mc-cmd:`PATH ` with the path to the object on the +- Replace :mc-cmd:`PATH ` with the path to the object on the S3-compatible host. - Replace :mc-cmd:`DURATION ` 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 ` with the +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the S3-compatible host. -- Replace :mc-cmd:`PATH ` with the path to the object on the +- Replace :mc-cmd:`PATH ` with the path to the object on the S3-compatible host. - Replace :mc-cmd:`VERSION ` 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 `. - - 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 diff --git a/source/reference/minio-mc/mc-ilm-add.rst b/source/reference/minio-mc/mc-ilm-add.rst new file mode 100644 index 00000000..6b52d81e --- /dev/null +++ b/source/reference/minio-mc/mc-ilm-add.rst @@ -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) ` and +:ref:`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 ` 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 `. + 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 + `. 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 ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` with the path to the bucket on the + S3-compatible host. + +- Replace :mc-cmd:`DATE ` 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 diff --git a/source/reference/minio-mc/mc-ilm-edit.rst b/source/reference/minio-mc/mc-ilm-edit.rst new file mode 100644 index 00000000..e0eff965 --- /dev/null +++ b/source/reference/minio-mc/mc-ilm-edit.rst @@ -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 ` 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 + `. 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 `. 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 ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 diff --git a/source/reference/minio-mc/mc-ilm-export.rst b/source/reference/minio-mc/mc-ilm-export.rst new file mode 100644 index 00000000..9d3c70f7 --- /dev/null +++ b/source/reference/minio-mc/mc-ilm-export.rst @@ -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 ` 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 ` 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 diff --git a/source/reference/minio-mc/mc-ilm-import.rst b/source/reference/minio-mc/mc-ilm-import.rst new file mode 100644 index 00000000..d55c0cba --- /dev/null +++ b/source/reference/minio-mc/mc-ilm-import.rst @@ -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 ` 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 ` 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 diff --git a/source/reference/minio-mc/mc-ilm-ls.rst b/source/reference/minio-mc/mc-ilm-ls.rst new file mode 100644 index 00000000..bd8815b6 --- /dev/null +++ b/source/reference/minio-mc/mc-ilm-ls.rst @@ -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 ` 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 ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 diff --git a/source/reference/minio-mc/mc-ilm-restore.rst b/source/reference/minio-mc/mc-ilm-restore.rst new file mode 100644 index 00000000..c8be774d --- /dev/null +++ b/source/reference/minio-mc/mc-ilm-restore.rst @@ -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 `, 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 diff --git a/source/reference/minio-mc/mc-ilm-rm.rst b/source/reference/minio-mc/mc-ilm-rm.rst new file mode 100644 index 00000000..4399fc64 --- /dev/null +++ b/source/reference/minio-mc/mc-ilm-rm.rst @@ -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 ` 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 ` with the unique name of the lifecycle + management rule. + +- Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 diff --git a/source/reference/minio-mc/mc-legalhold-clear.rst b/source/reference/minio-mc/mc-legalhold-clear.rst new file mode 100644 index 00000000..0cf3ac95 --- /dev/null +++ b/source/reference/minio-mc/mc-legalhold-clear.rst @@ -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 +` 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 ` 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 ` with the + :ref:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` with the path to the bucket + or object on the S3-compatible host. If specifying the path to a bucket or + bucket prefix, include the :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 diff --git a/source/reference/minio-mc/mc-legalhold-info.rst b/source/reference/minio-mc/mc-legalhold-info.rst new file mode 100644 index 00000000..964b7810 --- /dev/null +++ b/source/reference/minio-mc/mc-legalhold-info.rst @@ -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 +` 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 ` 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 ` with the + :ref:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` with the path to the bucket + or object on the S3-compatible host. If specifying the path to a bucket or + bucket prefix, include the :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 diff --git a/source/reference/minio-mc/mc-legalhold-set.rst b/source/reference/minio-mc/mc-legalhold-set.rst new file mode 100644 index 00000000..6285ed14 --- /dev/null +++ b/source/reference/minio-mc/mc-legalhold-set.rst @@ -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 +` 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 `. 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 ` 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 ` with the + :ref:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` with the path to the bucket + or object on the S3-compatible host. If specifying the path to a bucket or + bucket prefix, include the :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 diff --git a/source/reference/minio-mc/mc-ls.rst b/source/reference/minio-mc/mc-ls.rst new file mode 100644 index 00000000..0ce3cb65 --- /dev/null +++ b/source/reference/minio-mc/mc-ls.rst @@ -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 ` 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 ` to list the contents of a bucket: + +.. code-block:: shell + :class: copyable + + mc ls [--recursive] ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` with the path to the bucket or object on + the S3-compatible host. + +- Replace :mc-cmd:`DURATION ` 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 diff --git a/source/reference/minio-mc/mc-mb.rst b/source/reference/minio-mc/mc-mb.rst new file mode 100644 index 00000000..497a3feb --- /dev/null +++ b/source/reference/minio-mc/mc-mb.rst @@ -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 `. + + .. 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 ` 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 ` on the specified + bucket. Has no effect if the specified ``ALIAS`` is a + :ref:`standalone ` 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 ` or + :ref:`Bucket 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 ` with the + :mc:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`BUCKET ` 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 `. :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 ` +where you *must* enable :ref:`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 diff --git a/source/reference/minio-cli/minio-mc/mc-mirror.rst b/source/reference/minio-mc/mc-mirror.rst similarity index 65% rename from source/reference/minio-cli/minio-mc/mc-mirror.rst rename to source/reference/minio-mc/mc-mirror.rst index 04c35252..6c2b30ce 100644 --- a/source/reference/minio-cli/minio-mc/mc-mirror.rst +++ b/source/reference/minio-mc/mc-mirror.rst @@ -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 ` 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 ` 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 `__ 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 ` + 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 ` 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 ` 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 ` 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 ` - 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 diff --git a/source/reference/minio-cli/minio-mc/mc-mv.rst b/source/reference/minio-mc/mc-mv.rst similarity index 59% rename from source/reference/minio-cli/minio-mc/mc-mv.rst rename to source/reference/minio-mc/mc-mv.rst index c7eaa83a..cc0271bf 100644 --- a/source/reference/minio-cli/minio-mc/mc-mv.rst +++ b/source/reference/minio-mc/mc-mv.rst @@ -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 ` 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 `. + + 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 ` 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 ` 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 ` + 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* - - The object or objects to move. You can specify both local paths - and S3 paths using a configured S3 service :mc:`alias `. +:mc:`mc mv` verifies all move operations to object storage using MD5SUM +checksums. - For example: +Resume Move Operations +~~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: none +Use :mc-cmd-option:`mc mv continue` to resume an interrupted or failed +move operation from the point of failure. - mc mv play/mybucket/object.txt ~/localfiles/mybucket/object.txt TARGET +MinIO Trims Empty Prefixes on Object Removal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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. +.. |command| replace:: :mc-cmd:`mc mv` -.. mc-cmd:: TARGET - - *REQUIRED* - - The full path to the bucket to move the specified - :mc-cmd:`~mc mv SOURCE` to. Specify the :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 ` - 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 diff --git a/source/reference/minio-mc/mc-policy-get-json.rst b/source/reference/minio-mc/mc-policy-get-json.rst new file mode 100644 index 00000000..199f0837 --- /dev/null +++ b/source/reference/minio-mc/mc-policy-get-json.rst @@ -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 ` 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 `. + +.. 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 ` 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 ` with the + :mc-cmd:`alias ` of a configured S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-policy-get.rst b/source/reference/minio-mc/mc-policy-get.rst new file mode 100644 index 00000000..4551787a --- /dev/null +++ b/source/reference/minio-mc/mc-policy-get.rst @@ -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 ` 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 `. + +To get the :s3-docs:`JSON policy ` 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 ` 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 ` with the + :mc-cmd:`alias ` of a configured S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-policy-links.rst b/source/reference/minio-mc/mc-policy-links.rst new file mode 100644 index 00000000..5fc2fd5f --- /dev/null +++ b/source/reference/minio-mc/mc-policy-links.rst @@ -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 `. + +.. 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 ` 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 ` with the + :mc-cmd:`alias ` of a configured S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-policy-list.rst b/source/reference/minio-mc/mc-policy-list.rst new file mode 100644 index 00000000..79a86be5 --- /dev/null +++ b/source/reference/minio-mc/mc-policy-list.rst @@ -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 `. + +.. 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 ` 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 ` with the + :mc-cmd:`alias ` of a configured S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-policy-set-json.rst b/source/reference/minio-mc/mc-policy-set-json.rst new file mode 100644 index 00000000..81b1f4f3 --- /dev/null +++ b/source/reference/minio-mc/mc-policy-set-json.rst @@ -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 ` for a bucket using using an IAM +:s3-docs:`JSON policy document `. + +.. 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 `. + +.. 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 ` 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 ` with a supported + :mc-cmd:`POLICY `. + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of a configured S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 ` with the + :mc-cmd:`alias ` of a configured S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-policy-set.rst b/source/reference/minio-mc/mc-policy-set.rst new file mode 100644 index 00000000..2b801f97 --- /dev/null +++ b/source/reference/minio-mc/mc-policy-set.rst @@ -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 ` 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 `. + +To set anonymous bucket policies using an IAM +:s3-docs:`JSON policy `, 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 ` 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 ` with a supported + :mc-cmd:`permission `. + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of a configured S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-rb.rst b/source/reference/minio-mc/mc-rb.rst new file mode 100644 index 00000000..cfe1de1d --- /dev/null +++ b/source/reference/minio-mc/mc-rb.rst @@ -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 ` + and bucket configurations such as + :ref:`lifecycle management ` or + :ref:`replication `. + +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 ` 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 ` with the :mc-cmd:`alias ` of + a configured S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 diff --git a/source/reference/minio-mc/mc-replicate-add.rst b/source/reference/minio-mc/mc-replicate-add.rst new file mode 100644 index 00000000..06b150b4 --- /dev/null +++ b/source/reference/minio-mc/mc-replicate-add.rst @@ -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 +` 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 ` 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 ` 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 ` with the + :mc:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` 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 ` +and :mc:`minio` +:minio-git:`RELEASE.2021-06-07T21-40-51Z `, + +MinIO supports automatically replicating existing objects in a bucket. MinIO +existing object replication implements functionality similar to +`AWS Replicating existing objects between S3 buckets +`__ +without the overhead of contacting technical support. + +- To enable replication of existing objects when creating a new replication + rule, include ``"existing-objects"`` to the list of replication features + specified to :mc-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 +` 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 `, +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 ` 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 ` *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 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 ` 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 diff --git a/source/reference/minio-mc/mc-replicate-edit.rst b/source/reference/minio-mc/mc-replicate-edit.rst new file mode 100644 index 00000000..512ad258 --- /dev/null +++ b/source/reference/minio-mc/mc-replicate-edit.rst @@ -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 `. + +.. 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 ` 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 + ` 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 ` + 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 ` with the + :mc:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the path to the + bucket or bucket prefix on which the rule exists. + +- Replace :mc-cmd:`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 ` with the + :mc:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the path to the + bucket or bucket prefix on which the rule exists. + +- Replace :mc-cmd:`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 + ` 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 diff --git a/source/reference/minio-mc/mc-replicate-export.rst b/source/reference/minio-mc/mc-replicate-export.rst new file mode 100644 index 00000000..871946f3 --- /dev/null +++ b/source/reference/minio-mc/mc-replicate-export.rst @@ -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 ` 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 ` 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 ` with the + :mc:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` 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 diff --git a/source/reference/minio-mc/mc-replicate-import.rst b/source/reference/minio-mc/mc-replicate-import.rst new file mode 100644 index 00000000..dcb702bd --- /dev/null +++ b/source/reference/minio-mc/mc-replicate-import.rst @@ -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 ` 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 ` 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 ` with the + :mc:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` 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 diff --git a/source/reference/minio-mc/mc-replicate-ls.rst b/source/reference/minio-mc/mc-replicate-ls.rst new file mode 100644 index 00000000..0dda2cb9 --- /dev/null +++ b/source/reference/minio-mc/mc-replicate-ls.rst @@ -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 ` 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 ` 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 ` with the + :mc:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` 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 diff --git a/source/reference/minio-mc/mc-replicate-resync.rst b/source/reference/minio-mc/mc-replicate-resync.rst new file mode 100644 index 00000000..5751c452 --- /dev/null +++ b/source/reference/minio-mc/mc-replicate-resync.rst @@ -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 +` 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 ` 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 diff --git a/source/reference/minio-mc/mc-replicate-rm.rst b/source/reference/minio-mc/mc-replicate-rm.rst new file mode 100644 index 00000000..b1edaa4a --- /dev/null +++ b/source/reference/minio-mc/mc-replicate-rm.rst @@ -0,0 +1,158 @@ +.. _minio-mc-replicate-rm: + +=================== +``mc replicate rm`` +=================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc replicate rm + +Syntax +------ + +.. start-mc-replicate-rm-desc + +The :mc:`mc replicate rm` command removes a +:ref:`replication rule ` from a +MinIO bucket. + +.. end-mc-replicate-rm-desc + +.. code-block:: shell + + mc [GLOBALFLAGS] replicate rm FLAGS [FLAGS] ALIAS + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command removes the replication rule with specified + id from the ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc replicate rm --id "c76um9h4b0t1ijr36mug" myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] replicate 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 ` of the MinIO deployment and full path to + the bucket or bucket prefix from which to remove the replication rule. For + example: + + .. code-block:: none + + mc replicate rm --id "ID" myminio/mybucket + + +.. mc-cmd:: id + :option: + + *Required* Specify the unique ID for a configured replication rule. + + You can omit this option if specifying :mc-cmd-option:`~mc replicate rm all` + +.. mc-cmd:: all + :option: + + *Optional* 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` . + + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +Remove a Replication Rule from a Bucket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc replicate rm` to remote a bucket replication rule: + +.. code-block:: shell + :class: copyable + + mc replicate rm --id "ID" ALIAS/PATH + +- Replace :mc-cmd-option:`ID ` with the unique ID of the + replication rule to remove. Use :mc-cmd:`mc replicate ls` to list all + replication rules for the bucket. + +- Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the path to the + bucket or bucket prefix. + +Remove All Replication Rules from a Bucket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc replicate rm` to list bucket replication rules: + +.. code-block:: shell + :class: copyable + + mc replicate rm --all --force ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the path to the + bucket or bucket prefix. + +Behavior +-------- + +Removing Replication Rules Does Not Affect Replicated Objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Removing one or all replication rule for a bucket does *not* +remove any objects already replicated under those rule(s). + +Use The command or :mc-cmd:`mc rb` commands to remove replicated +objects on the remote target. You can identify replicated objects using +the ``X-Amz-Replication-Status`` metadata field where the value is +``REPLICA``. Buckets which contain objects from multiple replication sources +may require additional care and filtering to determine the source prior +to removal. + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility diff --git a/source/reference/minio-mc/mc-replicate-status.rst b/source/reference/minio-mc/mc-replicate-status.rst new file mode 100644 index 00000000..f6c30567 --- /dev/null +++ b/source/reference/minio-mc/mc-replicate-status.rst @@ -0,0 +1,89 @@ +.. _minio-mc-replicate-status: + +======================= +``mc replicate status`` +======================= + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc replicate status + +Syntax +------ + +.. start-mc-replicate-status-desc + +The :mc:`mc replicate status` command displays the +:ref:`replication status ` of a +MinIO bucket. + +.. end-mc-replicate-status-desc + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command displays the current replication status of the + ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc replicate status myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] replicate status 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 ` of the MinIO deployment and full path to + the bucket or bucket prefix for which to display the replication status. For + example: + + .. code-block:: none + + mc replicate status myminio/mybucket + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +Display Replication Status +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc replicate status` to show bucket replication status: + +.. code-block:: shell + :class: copyable + + mc replicate status ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the path to the + bucket or bucket prefix. diff --git a/source/reference/minio-mc/mc-retention-clear.rst b/source/reference/minio-mc/mc-retention-clear.rst new file mode 100644 index 00000000..edc6c3c1 --- /dev/null +++ b/source/reference/minio-mc/mc-retention-clear.rst @@ -0,0 +1,199 @@ +====================== +``mc retention clear`` +====================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc retention clear + +.. |command| replace:: :mc-cmd:`mc retention clear` +.. |rewind| replace:: :mc-cmd-option:`~mc retention clear rewind` +.. |versionid| replace:: :mc-cmd-option:`~mc retention clear version-id` +.. |versions| replace:: :mc-cmd-option:`~mc retention clear versions` +.. |alias| replace:: :mc-cmd-option:`~mc retention clear ALIAS` + +Syntax +------ + +.. start-mc-retention-desc + +The :mc:`mc retention clear` command removes the +:ref:`Write-Once Read-Many (WORM) locking ` settings for +an object or object(s) in a bucket. You can also remove the default object lock +settings for a bucket. + +.. end-mc-retention-desc + +To change the retention status of an object under +:ref:`legal hold `, use +:mc:`mc legalhold clear`. + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command removes the default object lock configuration for + the ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc retention clear --default myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] retention clear \ + [--default] \ + [--recursive] \ + [--rewind "string"] \ + [--version-id "string"]* \ + [--versions] \ + ALIAS + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + + :mc-cmd-option:`mc retention clear version-id` is mutually exclusive with + multiple other parameters. See the reference documentation for more + information. + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + + *Required* The full path to the object or objects for which to clear + the object lock configuration. Specify the :mc-cmd:`alias ` of a + configured S3-compatible service as the prefix to the ``ALIAS`` bucket + path. For example: + + .. code-block:: shell + + mc retention clear play/mybucket/object.txt + + - If the ``ALIAS`` 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 ``ALIAS`` 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:: default + :option: + + *Optional* Clears the default object lock settings for the bucket specified + to :mc-cmd:`~mc retention clear ALIAS`. + + If specifying :mc-cmd-option:`~mc retention clear default`, + :mc-cmd:`mc retention clear` ignores all other flags. + +.. mc-cmd:: recursive, r + :option: + + *Optional* Recursively clears the object lock settings for all objects in the + specified :mc-cmd:`~mc retention clear ALIAS` path. + + Mutually exclusive with :mc-cmd-option:`~mc retention clear version-id`. + +.. 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 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 + :end-before: end-versions-desc + + 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. + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +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 ` with the + :mc:`alias ` of a configured S3-compatible host. + + - Replace :mc-cmd:`PATH ` 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 ` with the + :mc:`alias ` of a configured S3-compatible host. + + - Replace :mc-cmd:`PATH ` 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 + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibilit diff --git a/source/reference/minio-mc/mc-retention-info.rst b/source/reference/minio-mc/mc-retention-info.rst new file mode 100644 index 00000000..70a7bc7e --- /dev/null +++ b/source/reference/minio-mc/mc-retention-info.rst @@ -0,0 +1,226 @@ +===================== +``mc retention info`` +===================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc retention info + +.. |command| replace:: :mc-cmd:`mc retention info` +.. |rewind| replace:: :mc-cmd-option:`~mc retention info rewind` +.. |versionid| replace:: :mc-cmd-option:`~mc retention info version-id` +.. |alias| replace:: :mc-cmd-option:`~mc retention info ALIAS` +.. |versions| replace:: :mc-cmd-option:`~mc retention info versions` + +Syntax +------ + +.. start-mc-retention-desc + +The :mc:`mc retention info` command configures the :ref:`Write-Once Read-Many (WORM) +locking ` settings for an object or object(s) in a bucket. +You can also set the default object lock settings for a bucket, where all +objects without explicit object lock settings inherit the bucket default. + +.. end-mc-retention-desc + +To lock an object under :ref:`legal hold `, +use :mc:`mc legalhold`. + +:mc:`mc retention info` *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 returns the default object lock configuration for + the ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc retention info --default myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] retention info \ + [--default] \ + [--recursive] \ + [--rewind "string"] \ + [--version-id "string"]* \ + [--versions] \ + ALIAS + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + + :mc-cmd-option:`mc retention info version-id` is mutually exclusive with + multiple other parameters. See the reference documentation for more + information. + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + + *Required* + + The full path to the object for which to retreive + the object lock configuration. Specify the :ref:`alias ` of a + configured S3-compatible service as the prefix to the ``ALIAS`` bucket + path. For example: + + .. code-block:: shell + + mc retention info play/mybucket/object.txt + + - If the ``ALIAS`` 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 ``ALIAS`` 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:: default + :option: + + *Optional* Returns the default object lock settings for the bucket specified + to :mc-cmd:`~mc retention info ALIAS`. + + If specifying :mc-cmd-option:`~mc retention info default`, + :mc-cmd:`mc retention info` ignores all other flags. + +.. mc-cmd:: recursive, r + :option: + + *Optional* Recursively returns the object lock settings for all objects in the + specified :mc-cmd:`~mc retention info ALIAS` path. + + Mutually exclusive with :mc-cmd-option:`~mc retention info version-id`. + +.. 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 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 + :end-before: end-versions-desc + + 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. + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +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 ` with the + :mc:`alias ` of a configured S3-compatible host. + + - Replace :mc-cmd:`PATH ` 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 ` with the + :mc:`alias ` of a configured S3-compatible host. + + - Replace :mc-cmd:`PATH ` 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 ` with the + :mc:`alias ` of a configured S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility diff --git a/source/reference/minio-mc/mc-retention-set.rst b/source/reference/minio-mc/mc-retention-set.rst new file mode 100644 index 00000000..7d27fdec --- /dev/null +++ b/source/reference/minio-mc/mc-retention-set.rst @@ -0,0 +1,350 @@ +.. _minio-bucket-locking: + +==================== +``mc retention set`` +==================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc retention +.. mc:: mc retention set + +.. 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 ALIAS` +.. |versions| replace:: :mc-cmd-option:`~mc retention set versions` + +Syntax +------ + +.. start-mc-retention-desc + +The :mc:`mc retention set` command configures the +:ref:`Write-Once Read-Many (WORM) locking ` settings for +an object or object(s) in a bucket. You can also set the default object lock +settings for a bucket, where all objects without explicit object lock settings +inherit the bucket default. + +.. end-mc-retention-desc + +To lock an object under :ref:`legal hold `, +use :mc:`mc legalhold`. + +:mc:`mc retention set` *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 sets a default 30 day + :ref:`GOVERNANCE ` object lock on the + ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc retention set --default GOVERNANCE "30d" myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] retention set \ + [--bypass] \ + [--default] \ + [--recursive] \ + [--rewind "string"] \ + [--versions] \ + [--version-id "string"]* \ + MODE \ + "VALIDITY" \ + ALIAS + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + + :mc-cmd-option:`mc retention set version-id` is mutually exclusive with + multiple other parameters. See the reference documentation for more + information. + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: MODE + + Sets the locking mode for the :mc-cmd:`~mc retention set ALIAS`. + Specify one of the following supported values: + + - ``governance`` + - ``compliance`` + + See the AWS S3 documentation on :s3-docs:`Object Lock Overview + ` 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:: ALIAS + + *Required* + + The full path to the object or objects for which to set object lock + configuration. Specify the :ref:`alias ` for the MinIO or + S3-compatible service and the full path to bucket. For + example: + + .. code-block:: shell + + mc retention set play/mybucket/object.txt MODE VALIDITY + + - If the ``ALIAS`` specifies a bucket or bucket prefix, include + :mc-cmd-option:`~mc retention set recursive` to apply the object lock + settings to the bucket contents. + + - :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 + respectively. + +.. mc-cmd:: bypass + :option: + + *Optional* Allows a user with the ``s3:BypassGovernanceRetention`` permission + to modify the object. Requires the ``governance`` retention + :mc-cmd:`~mc retention set MODE` + +.. mc-cmd:: default + :option: + + *Optional* Sets the default object lock settings for the bucket specified to + :mc-cmd:`~mc retention set ALIAS` 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. + +.. mc-cmd:: recursive, r + :option: + + *Optional* Recursively applies the object lock settings to all objects in the + specified :mc-cmd:`~mc retention set ALIAS` path. + + Mutually exclusive with :mc-cmd-option:`~mc retention set version-id`. + +.. 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. + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +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 ` with the retention mode to + enable. MinIO supports the AWS S3 retention modes ``governance`` and + ``compliance``. + +- Replace :mc-cmd:`DURATION ` with the duration which + the object lock should remain in effect. For example, to set a retention + period of 30 days, specify ``30d``. + +- Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of a configured S3-compatible host. + +- Replace :mc-cmd:`PATH ` 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 ` with the version + of the object. + + - Replace :mc-cmd:`MODE ` with the retention mode + to enable. MinIO supports the AWS S3 retention modes ``governance`` and + ``compliance``. + + - Replace :mc-cmd:`DURATION ` with the duration + which the object lock should remain in effect. For example, to set a + retention period of 30 days, specify ``30d``. + + - Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of a configured S3-compatible host. + + - Replace :mc-cmd:`PATH ` 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 ` with the retention mode + to enable. MinIO supports the AWS S3 retention modes ``governance`` and + ``compliance``. + + - Replace :mc-cmd:`DURATION ` with the duration + which the object lock should remain in effect. For example, to set a + retention period of 30 days, specify ``30d``. + + + - Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of a configured S3-compatible host. + + - Replace :mc-cmd:`PATH ` 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 + +Behavior +-------- + +Retention of Object Versions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For buckets with :mc:`versioning enabled `, :mc:`mc retention set` +by default operates on the *latest* version of the target object or object(s). +:mc:`mc retention set` includes specific options that when *explicitly* +specified direct the command to operate on either a specific object version *or* +all versions of an object: + +.. tab-set:: + + .. tab-item:: Specific Object Version + + To direct :mc:`mc retention set` 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 set version-id` + - :mc-cmd-option:`mc retention set version-id` + + .. tab-item:: All Object Versions + + To direct :mc:`mc retention set` to operate on *all* versions of an object, + include the ``--versions`` argument: + + - :mc-cmd-option:`mc retention set versions` + - :mc-cmd-option:`mc retention set versions` + - :mc-cmd-option:`mc retention set versions` + +Interaction with Legal Holds +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Locking an object prevents any modification or deletion of that +object, similar to the :mc-cmd:`COMPLIANCE ` object +locking mode. Objects can have simultaneous retention-based locks *and* +legal hold locks. + +The legal hold lock *overrides* any retention locking, such that an object under +legal hold remains locked *even if* the retention period expires. Setting, +modifying, or clearing retention settings for an object under legal hold has no +effect until the legal hold either expires or is explicitly disabled. + +For more information on object legal holds, see :mc-cmd:`mc legalhold`. + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility diff --git a/source/reference/minio-mc/mc-rm.rst b/source/reference/minio-mc/mc-rm.rst new file mode 100644 index 00000000..d5d874bf --- /dev/null +++ b/source/reference/minio-mc/mc-rm.rst @@ -0,0 +1,411 @@ +========= +``mc rm`` +========= + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc rm + +.. |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 ALIAS` + +Syntax +------ + +.. start-mc-rm-desc + +The :mc:`mc rm` command removes objects from a bucket on a MinIO deployment. +To completely remove a bucket, use :mc:`mc rb` instead. + +.. end-mc-rm-desc + +You can also use :mc:`mc rm` against the local filesystem to produce similar +results to the ``rm`` commandline tool. + +.. important:: + + :mc:`mc rm` supports removing multiple objects *or* files in a single + command. Consider using the :mc-cmd-option:`~mc rm fake` + option to validate that the operation targets only the desired objects/files. + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command removes multiple objects from the + ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc rm --recursive myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] rm \ + [--bypass] \ + [--dangerous] \ + [--fake] \ + [--force]* \ + [--incomplete] \ + [--newer-than "string"] \ + [--non-current] \ + [--older-than "string"] \ + [--recursive] \ + [--rewind "string"] \ + [--stdin] \ + [--version-id "string"]* \ + [--versions] \ + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + + :mc-cmd-option:`mc rm force` is required by multiple parameters. + :mc-cmd-option:`mc rm version-id` is mutually exclusive with multiple + parameters. See the reference documentation for more information. + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + + *Required* The :ref:`alias ` of a MinIO deplyment and the full path to + the object to remove. For example: + + .. code-block:: shell + + mc rm play/mybucket/object.txt + + You can specify multiple objects on the same or different MinIO deployments. + 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/ + + Consider first running the command with the + :mc-cmd-option:`~mc rm fake` flag to validate the scope of the + recursive delete operation. + + For removing a file from a local filesystem, specify the full path to that + file: + + .. code-block:: shell + + mc rm ~/data/myoldobject.txt + +.. mc-cmd:: bypass + :option: + + *Optional* Allows removing an object held under + :ref:`GOVERNANCE ` object locking. + +.. mc-cmd:: dangerous + :option: + + *Optional* Allows running :mc:`mc rm` when the :mc-cmd:`~mc rm ALIAS` + specifies the root (all buckets) on the MinIO deployment. + + When combined with :mc-cmd-option:`~mc rm versions`, this flag + directs :mc-cmd:`mc rm` to permanently remove all objects *and* versions from + the ``ALIAS`` target. + + Consider first running the command with the :mc-cmd-option:`~mc rm fake` to + validate the scope of the site-wide delete operation. + + .. warning:: + + Running :mc-cmd-option:`mc rm dangerous` with the + :mc-cmd-option:`~mc rm versions` flag is irreversible. Exercise all + possible due diligence in ensuring the command applies to only the desired + ``ALIAS`` targets prior to execution. + +.. mc-cmd:: encrypt-key + :option: + + *Optional* 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 ` 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. + +.. mc-cmd:: fake + :option: + + *Optional* 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:: force + :option: + + *Optional* 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:: incomplete, I + :option: + + *Optional* Remove incomplete uploads for the specified object. + + If any :mc-cmd-option:`~mc rm ALIAS` specifies a bucket, + you **must** also specify :mc-cmd-option:`~mc rm recursive` + and :mc-cmd-option:`~mc rm force`. + +.. 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:: non-current + :option: + + *Optional* Removes all :ref:`non-current ` + object versions from the specified :mc-cmd:`~mc rm ALIAS`. + + This option has on effect on buckets without + :ref:`versioning ` enabled. + +.. 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:: recursive, r + :option: + + *Optional* Recursively remove the contents of each :mc-cmd:`~mc rm ALIAS` + bucket or bucket prefix. + + If specifying :mc-cmd-option:`~mc rm recursive`, you **must** also + specify :mc-cmd-option:`~mc rm force`. + + For buckets with :ref:`versioning ` enabled, + this option by default produces a delete marker for each removed object. + Include the :mc-cmd-option:`~mc rm versions` flag to recursively remove + all objects *and* object versions from the bucket. + + Consider first running the command with the + :mc-cmd-option:`~mc rm fake` flag to validate the scope of the + recursive delete operation. + + Mutually exclusive with :mc-cmd-option:`mc rm version-id` + +.. mc-cmd:: rewind + :option: + + .. include:: /includes/facts-versioning.rst + :start-after: start-rewind-desc + :end-before: end-rewind-desc + +.. mc-cmd:: stdin + :option: + + *Optional* Read object names or buckets from ``STDIN``. + +.. 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:: 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` + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +Remove a Single Object +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: shell + :class: copyable + + mc rm ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of + a configured S3-compatible service. + +- Replace :mc-cmd:`PATH ` 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 ` with the :mc:`alias ` of + a configured S3-compatible service. + +- Replace :mc-cmd:`PATH ` 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 ` with the :mc:`alias ` of + a configured S3-compatible service. + +- Replace :mc-cmd:`PATH ` 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 ` with the :mc:`alias ` of + a configured S3-compatible service. + +- Replace :mc-cmd:`PATH ` with the path to the object. For + example, ``/mybucket/myobject``. + +- Replace :mc-cmd:`DURATION ` 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"``. + +Behavior +-------- + +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 `. + +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 + +Delete Operations in Versioned Buckets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MinIO supports keeping multiple :ref:`versions ` of an +object in a single bucket. :ref:`Deleting ` an +object in a versioned bucket results in a special ``DeleteMarker`` tombstone +that marks an object as deleted while retaining all previous versions of that +object. + +- To remove a specific object version from a bucket, use + :mc-cmd-option:`mc rm version-id` + +- To remove all versions of an object from a bucket, use + :mc-cmd-option:`mc rm versions` + +- To remove all non-current versions of an object from a bucket, use + :mc-cmd-option:`mc rm non-current` + + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility diff --git a/source/reference/minio-mc/mc-share-download.rst b/source/reference/minio-mc/mc-share-download.rst new file mode 100644 index 00000000..39cb5671 --- /dev/null +++ b/source/reference/minio-mc/mc-share-download.rst @@ -0,0 +1,185 @@ +===================== +``mc share download`` +===================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc share download + +.. |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 ALIAS` + +Syntax +------ + +.. start-mc-share-download-desc + +The :mc:`mc share download` command generates a temporary presigned URL with +integrated access credentials for downloading objects from a MinIO bucket. The +temporary URL expires after a configurable time limit. + +.. end-mc-share-download-desc + +- Applications can perform a ``GET`` to retrieve the object from the URL. +- Users can open the URL in a browser to download the object. + +For more information on shareable object URLs, see the Amazon S3 +documentation on :aws-docs:`Pre-Signed URLs +`. + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command generates a new presigned download URL for the + ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc share download --recursive myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] share upload \ + [--expire "string"] \ + [--recursive] \ + [--version-id "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 ` of a MinIO deplyment and the full path to + the object for which to generate a download URL. For example: + + .. code-block:: shell + + mc share download play/mybucket/object.txt + + You can specify multiple objects on the same or different MinIO deployments. + For example: + + .. code-block:: shell + + mc share download play/mybucket/object.txt play/mybucket/otherobject.txt + + If specifying the path to a bucket or bucket prefix, you **must** also + specify the :mc-cmd-option:`~mc share download recursive` argument. For + example: + + .. code-block:: shell + + mc share download --recursive play/mybucket/ + + mc share download --recursive play/mybucket/myprefix/ + +.. mc-cmd:: expire, E + :option: + + *Optional* Set the expiration time limit for all generated URLs. + + Specify a string with format ``##h##m##s`` format. For example: + ``12h34m56s`` for an expiry of 12 hours, 34 minutes, and 56 seconds + after URL generation. + + Defaults to ``168h`` or 168 hours (7 days). + +.. mc-cmd:: recursive, r + :option: + + *Optional* Recursively generate URLs for all objects in a + :mc-cmd:`mc share download ALIAS` bucket or bucket prefix. + + Required if any ``ALIAS`` 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 + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +Generate a URL to Download Object(s) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. 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 ` with the + :ref:`alias ` of the MinIO deployment. + + - Replace :mc-cmd:`PATH ` with the path to the + object on the MinIO deployment. + + - Replace :mc-cmd:`DURATION ` 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 ` with the + :ref:`alias ` of the MinIO deployment. + + - Replace :mc-cmd:`PATH ` with the path to the + bucket or bucket prefix on the MinIO deployment. + + - Replace :mc-cmd:`DURATION ` with the duration + after which the URL expires. For example, to set a 30 day expiry, + specify ``30d``. + +Behavior +-------- + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility diff --git a/source/reference/minio-mc/mc-share-list.rst b/source/reference/minio-mc/mc-share-list.rst new file mode 100644 index 00000000..ab8666f0 --- /dev/null +++ b/source/reference/minio-mc/mc-share-list.rst @@ -0,0 +1,131 @@ +=================== +``mc share list`` +=================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc share list + +Syntax +----------- + +.. start-mc-share-upload-desc + +The :mc:`mc share list` command displays any unexpired presigned URLs generated +by :mc-cmd:`mc share upload` or :mc-cmd:`mc share download` + +.. end-mc-share-upload-desc + +Applications can perform a ``PUT`` to retrieve the object from the URL. + +For more information on shareable object URLs, see the Amazon S3 +documentation on :aws-docs:`Pre-Signed URLs +`. + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command lists all upload and download presigned URLs + respectively for the ``mydata`` bucket on the ``myminio`` MinIO + deployment: + + .. code-block:: shell + :class: copyable + + mc share list upload myminio/mydata + mc share list download myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] share list \ + [download | upload] \ + ALIAS + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: download + + *Required* Lists all unexpired presigned download (``GET``) URLs. + + Mutually exclusive with :mc-cmd-option:`mc share list upload` + +.. mc-cmd:: upload + + *Required* Lists all unexpired presigned upload (``PUT``) URLs. + + Mutually exclusive with :mc-cmd-option:`mc share list download` + +.. mc-cmd:: ALIAS + + *Required* The :ref:`alias ` of a MinIO deplyment and the full path to + the object for which to list unexpired presigned URLs. + + + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +List Generated Download and Upload URLs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tab-set:: + + .. tab-item:: List Active Download Presigned URLs + + Use :mc-cmd:`mc share list download` 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 list download ALIAS + + - Replace :mc-cmd:`ALIAS ` with the + :ref:`alias ` of the MinIO deployment. + + .. tab-item:: List Active Upload Presigned URLs + + Use :mc-cmd:`mc share list 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 list upload ALIAS + + - Replace :mc-cmd:`ALIAS ` with the + :ref:`alias ` of 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 diff --git a/source/reference/minio-mc/mc-share-upload.rst b/source/reference/minio-mc/mc-share-upload.rst new file mode 100644 index 00000000..59b8fbe6 --- /dev/null +++ b/source/reference/minio-mc/mc-share-upload.rst @@ -0,0 +1,209 @@ +=================== +``mc share upload`` +=================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc share upload + +Syntax +----------- + +.. start-mc-share-upload-desc + +The :mc:`mc share upload` command generates a temporary presigned URL with +integrated access credentials for downloading objects from a MinIO bucket. The +temporary URL expires after a configurable time limit. + +.. end-mc-share-upload-desc + +Applications can perform a ``PUT`` to retrieve the object from the URL. + +For more information on shareable object URLs, see the Amazon S3 +documentation on :aws-docs:`Pre-Signed URLs +`. + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command generates a new presigned upload URL for the + ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc share upload --recursive myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] share upload \ + [--expire "string"] \ + [--recursive] \ + 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 ` of a MinIO deplyment and the full path to + the object for which to generate an upload URL. For example: + + .. code-block:: shell + + mc share upload play/mybucket/object.txt + + You can specify multiple objects on the same or different MinIO deployments. + For example: + + .. code-block:: shell + + mc share upload 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 share upload recursive` argument. For + example: + + .. code-block:: shell + + mc share upload --recursive play/mybucket/ + + mc share upload --recursive play/mybucket/myprefix/ + +.. mc-cmd:: expire, E + :option: + + *Optional* Set the expiration time limit for all generated URLs. + + Specify a string with format ``##h##m##s`` format. For example: + ``12h34m56s`` for an expiry of 12 hours, 34 minutes, and 56 seconds + after URL generation. + + Defaults to ``168h`` or 168 hours (7 days). + +.. mc-cmd:: recursive, r + :option: + + *Optional* Modifies the CURL URL to support uploading objects to a bucket or + bucket prefix. Required if any ``ALIAS`` specifies a path to a bucket or + bucket prefix. The modified CURL output resembles the following: + + .. code-block:: shell + + curl ... -F key=ALIAS/ -F file=@ + + Replace ```` with the path to the file to upload. + + Replace ```` with the file once uploaded. + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +Generate a URL to Upload Object(s) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tab-set:: + + .. tab-item:: Upload Single 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 a MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc share upload --expire DURATION ALIAS/PATH + + - Replace :mc-cmd:`ALIAS ` with the + :ref:`alias ` of the MinIO deployment. + + - Replace :mc-cmd:`PATH ` with the path to the + object on the MinIO deployment. + + - Replace :mc-cmd:`DURATION ` with the duration + after which the URL expires. For example, to set a 30 day expiry, + specify ``30d``. + + .. tab-item:: Upload Multiple Objects + + 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 a + MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc share upload --recursive --expire DURATION ALIAS/PATH + + - Replace :mc-cmd:`ALIAS ` with the + :ref:`alias ` of the MinIO deployment. + + - Replace :mc-cmd:`PATH ` with the path to the + bucket or bucket prefix on the MinIO deployment. + + - Replace :mc-cmd:`DURATION ` 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 ```` string in the returned CURL command with the path + to the file to upload. + + - Replace the ```` 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=mydata -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. + +Behavior +-------- + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility diff --git a/source/reference/minio-cli/minio-mc/mc-sql.rst b/source/reference/minio-mc/mc-sql.rst similarity index 64% rename from source/reference/minio-cli/minio-mc/mc-sql.rst rename to source/reference/minio-mc/mc-sql.rst index 884b33c5..9258fa43 100644 --- a/source/reference/minio-cli/minio-mc/mc-sql.rst +++ b/source/reference/minio-mc/mc-sql.rst @@ -10,13 +10,13 @@ .. mc:: mc sql -Description ------------ +Syntax +------ .. start-mc-sql-desc The :mc:`mc sql` command provides an S3 Select interface for performing sql -queries on objects in the specified S3-compatible service. +queries on objects in the specified MinIO deployment. .. end-mc-sql-desc @@ -24,6 +24,201 @@ See :s3-docs:`Selecting content from objects ` for more information on S3 Select behavior and limitations. +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command queries all objects in the + ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc sql --recursive --query "select * from S3Object" myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] mc sql \ + --query "string" \ + [--csv-input "string"] \ + [--compression "string"] \ + [--csv-output "string"] \ + [--csv-output-header "string"] \ + [--encrypt-key "string"] \ + [--json-input "string"] \ + [--json-output "string"] \ + [--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 object to run the SQL query + against. Specify the :ref:`alias ` of a configured + S3 service as the prefix to the ``ALIAS`` path. For example: + + .. code-block:: shell + + mc sql [FLAGS] play/mybucket + +.. mc-cmd:: query, e + :option: + + *Required* The SQL statement to execute on the specified + :mc-cmd:`~mc sql ALIAS` directory or object. Wrap the entire SQL query in + double quotes ``"``. + + Defaults to ``"select * from S3Object"``. + +.. mc-cmd:: csv-input + :option: + + *Optional* The data format for ``.csv`` input objects. Specify a string of + comma-seperated ``key=value,...`` pairs. See :ref:`mc-sql-csv-format` for + more information on valid keys. + +.. mc-cmd:: compression + :option: + + *Optional* The compression type of the input object. Specify one of the + following supported values: + + - ``GZIP`` + - ``BZIP2`` + - ``NONE`` (default) + + Compression schemes supported by MinIO backend only: + + - ``ZSTD`` `Zstandard `__ + - ``LZ4`` `LZ4 `__ stream + - ``S2`` `S2 `__ framed stream + - ``SNAPPY`` `Snappy `__ framed stream + +.. mc-cmd:: csv-output + :option: + + *Optional* The data format for ``.csv`` output. Specify a string of + comma-seperated ``key=value,...`` pairs. See :ref:`mc-sql-csv-format` for + more information on valid keys. + + See the S3 API :s3-api:`CSVOutput ` for more + information. + +.. mc-cmd:: csv-output-header + :option: + + *Optional* The header row of the ``.csv`` output file. Specify a string of + comma-separated fields as ``field1,field2,...``. + + Omit to output a ``.csv`` with no header row. + +.. mc-cmd:: encrypt-key + :option: + + *Optional* 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 MinIO deployment + :mc-cmd:`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 sql 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. + +.. mc-cmd:: json-input + :option: + + *Optional* The data format for ``.json`` input objects. Specify the type of + the JSON contents as ``type=``. The value can be either: + + - ``DOCUMENT`` - JSON `document `__. + - ``LINES`` - JSON `lines `__. + + See the S3 API :s3-api:`JSONInput ` for more + information. + +.. mc-cmd:: json-output + :option: + + *Optional* The data format for the ``.json`` output. Supports the + ``rd=value`` key, where ``rd`` is the ``RecordDelimiter`` for the JSON + document. + + Omit to use the default newline character ``\n``. + + See the S3 API :s3-api:`JSONOutput ` for more + information. + +.. mc-cmd:: recursive, r + :option: + + *Optional* Recursively searches the specified :mc-cmd:`~mc sql ALIAS` + directory using the :mc-cmd-option:`~mc sql query` SQL statement. + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +Select all Columns in all Objects in a Bucket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc:`mc sql` with the :mc-cmd-option:`~mc sql recursive` and +:mc-cmd-option:`~mc sql query` options to apply the query to all objects +in a bucket: + +.. code-block:: shell + :class: copyable + + mc sql --recursive --query "select * from S3Object" ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the + :ref:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the path to the bucket + on the MinIO deployment. + +Run an Aggregation Query on an Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc:`mc sql` with the :mc-cmd-option:`~mc sql query` option to query +an object on an MinIO deployment: + +.. code-block:: shell + + mc sql --query "select count(s.power) from S3Object" ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the + :ref:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the path to the object + on the MinIO deployment. + +Behavior +-------- + Input Formats ~~~~~~~~~~~~~ @@ -127,162 +322,9 @@ information on S3 CSV formatting. Corresponds to ``AllowQuotedRecordDelimiter`` in the S3 API ``CSVInput``. -Examples --------- - -Select all Columns in all Objects in a Bucket -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Use :mc:`mc sql` with the :mc-cmd-option:`~mc sql recursive` and -:mc-cmd-option:`~mc sql query` options to apply the query to all objects -in a bucket: - -.. code-block:: shell - :class: copyable - - mc sql --recursive --query "select * from S3Object" ALIAS/PATH - -- Replace :mc-cmd:`ALIAS ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the path to the bucket - on the S3-compatible host. - -Run an Aggregation Query on an Object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Use :mc:`mc sql` with the :mc-cmd-option:`~mc sql query` option to query -an object on an S3-compatible host: - -.. code-block:: shell - - mc sql --query "select count(s.power) from S3Object" ALIAS/PATH - -- Replace :mc-cmd:`ALIAS ` with the - :mc:`alias ` of the S3-compatible host. - -- Replace :mc-cmd:`PATH ` with the path to the object - on the S3-compatible host. - -Syntax ------- - -:mc:`mc sql` has the following syntax: - -.. code-block:: shell - :class: copyable - - mc sql [FLAGS] TARGET [TARGET...] - -:mc:`mc sql` supports the following arguments: - -.. mc-cmd:: TARGET - - *Required* The full path to the bucket or object to run the SQL query - against. Specify the :mc-cmd:`alias ` of a configured - S3 service as the prefix to the ``TARGET`` path. For example: - - .. code-block:: shell - - mc sql [FLAGS] play/mybucket - -.. mc-cmd:: query, e - :option: - - The SQL statement to execute on the specified :mc-cmd:`~mc sql TARGET` - directory or object. Wrap the entire SQL query in double quotes ``"``. - - Defaults to ``"select * from s3object"``. - -.. mc-cmd:: recursive, r - :option: - - Recursively searches the specified :mc-cmd:`~mc sql TARGET` directory - using the :mc-cmd-option:`~mc sql query` SQL statement. - - -.. mc-cmd:: csv-input - :option: - - The data format for ``.csv`` input objects. Specify a string of - comma-seperated ``key=value,...`` pairs. See :ref:`mc-sql-csv-format` - for more information on valid keys. - -.. mc-cmd:: json-input - :option: - - The data format for ``.json`` input objects. Specify the type of the JSON - contents as ``type=``. The value can be either: - - - ``DOCUMENT`` - JSON `document `__. - - ``LINES`` - JSON `lines `__. - - See the S3 API :s3-api:`JSONInput ` for more - information. - -.. mc-cmd:: compression - :option: - - The compression type of the input object. Specify one of the following - supported values: - - - ``GZIP`` - - ``BZIP2`` - - ``NONE`` (default) - - Compression schemes supported by MinIO backend only: - - - ``ZSTD`` `Zstandard `__ - - ``LZ4`` `LZ4 `__ stream - - ``S2`` `S2 `__ framed stream - - ``SNAPPY`` `Snappy `__ framed stream - -.. mc-cmd:: csv-output - :option: - - The data format for ``.csv`` output. Specify a string of comma-seperated - ``key=value,...`` pairs. See :ref:`mc-sql-csv-format` for more information - on valid keys. - - See the S3 API :s3-api:`CSVOutput ` for more - information. - -.. mc-cmd:: csv-output-header - :option: - - The header row of the ``.csv`` output file. Specify a string of - comma-separated fields as ``field1,field2,...``. - - Omit to output a ``.csv`` with no header row. - - -.. mc-cmd:: json-output - :option: - - The data format for the ``.json`` output. Supports the - ``rd=value`` key, where ``rd`` is the ``RecordDelimiter`` for the JSON - document. - - Omit to use the default newline character ``\n``. - - See the S3 API :s3-api:`JSONOutput ` for more - information. - -.. 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 ` 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 sql 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. +S3 Compatibility +~~~~~~~~~~~~~~~~ +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility \ No newline at end of file diff --git a/source/reference/minio-mc/mc-stat.rst b/source/reference/minio-mc/mc-stat.rst new file mode 100644 index 00000000..ad4b5675 --- /dev/null +++ b/source/reference/minio-mc/mc-stat.rst @@ -0,0 +1,195 @@ +=========== +``mc stat`` +=========== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc stat + +.. |command| replace:: :mc-cmd:`mc stat` +.. |rewind| replace:: :mc-cmd-option:`~mc stat rewind` +.. |versions| replace:: :mc-cmd-option:`~mc stat versions` +.. |versionid| replace:: :mc-cmd-option:`~mc stat version-id` +.. |alias| replace:: :mc-cmd-option:`~mc stat ALIAS` + +Syntax +----------- + +.. start-mc-stat-desc + +The :mc:`mc stat` command displays information on objects in a MinIO bucket, +including object metadata. + +.. end-mc-stat-desc + +You can also use :mc:`mc stat` against the local filesystem to produce similar +results to the ``stat`` commandline tool. + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command displays information on all objects in the + ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc stat --recursive myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] stat \ + [--encrypt-key "value"] \ + [--recursive] \ + [--rewind "string"] \ + [--versions] \ + [--version-id "string"]* \ + ALIAS + + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + + :mc-cmd-option:`mc stat version-id` is mutually exclusive with multiple + parameters. See the reference documentation for more information. + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + + The :ref:`alias ` of a MinIO deployment and the full path to the + object for which to retrieve detailed information. For example: + + .. code-block:: shell + + mc stat myminio/mybucket/myobject.txt + + You can specify multiple objects on the same or different MinIO deployments: + + .. code-block:: shell + + mc stat play/mybucket/myobject.txt myminio/mybucket/myobject.txt + + If specifying the path to a bucket or bucket prefixy, you **must** + include the :mc-cmd-option:`mc stat recursive` flag: + + .. code-block:: shell + + mc stat --recursive myminio/mybucket/ + + For retrieving information on a file from a local filesystem, specify the + full path to that file: + + .. code-block:: shell + + mc stat ~/data/myobject.txt + +.. 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 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. + +.. mc-cmd:: recursive, r + :option: + + *Optional* Recursively :mc:`mc stat` the contents of the MinIO bucket + specified to :mc-cmd:`~mc stat ALIAS`. + +.. mc-cmd:: rewind + :option: + + .. include:: /includes/facts-versioning.rst + :start-after: start-rewind-desc + :end-before: end-rewind-desc + +.. mc-cmd:: versions + :option: + + .. include:: /includes/facts-versioning.rst + :start-after: start-versions-desc + :end-before: end-versions-desc + + Use :mc-cmd-option:`~mc stat versions` and + :mc-cmd-option:`~mc stat rewind` together to remove all object + versions which existed at a specific point in time. + +.. 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 stat versions` + - :mc-cmd-option:`~mc stat rewind` + - :mc-cmd-option:`~mc stat recursive` + +Examples +-------- + +.. tab-set:: + + .. tab-item:: Single Object + + .. code-block:: shell + :class: copyable + + mc stat ALIAS/PATH + + - Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of the S3-compatible host. + + - Replace :mc-cmd:`PATH ` 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 ` with the + :mc:`alias ` of the S3-compatible host. + + - Replace :mc-cmd:`PATH ` with the path to the bucket + or object 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 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-tag-list.rst b/source/reference/minio-mc/mc-tag-list.rst new file mode 100644 index 00000000..815e03f0 --- /dev/null +++ b/source/reference/minio-mc/mc-tag-list.rst @@ -0,0 +1,139 @@ +.. _minio-mc-tag-list: + +=============== +``mc tag list`` +=============== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc tag list + +.. |command| replace:: :mc-cmd:`mc tag list` +.. |rewind| replace:: :mc-cmd-option:`~mc tag list rewind` +.. |versions| replace:: :mc-cmd-option:`~mc tag list versions` +.. |versionid| replace:: :mc-cmd-option:`~mc tag list version-id` +.. |alias| replace:: :mc-cmd-option:`~mc tag list ALIAS` + +Syntax +------ + +.. start-mc-tag-list-desc + +The :mc:`mc tag list` command lists all tags from a bucket or object. + +.. end-mc-tag-list-desc + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command lists tags for the ``mydata`` bucket on the + ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc tag list myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] tag set \ + [--rewind "string"] \ + [--versions] \ + [--version-id "string"]* \ + ALIAS + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + + :mc-cmd-option:`mc tag list version-id` is mutually exclusive with + multiple parameters. See the reference documentation for more information. + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + + *Required* The :ref:`alias ` for a MinIO deployment and the + full path to the object for which to list all tags (e.g. bucket and path to + object). For example: + + .. code-block:: none + + mc tag list myminio/mybucket/object.txt + +.. mc-cmd:: rewind + :option: + + .. include:: /includes/facts-versioning.rst + :start-after: start-rewind-desc + :end-before: end-rewind-desc + +.. 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 list versions` and + :mc-cmd-option:`~mc tag list rewind` together to list tags from all + object versions which existed at a specific point in time. + +.. 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 the following parameters: + + - :mc-cmd-option:`~mc tag list rewind` + - :mc-cmd-option:`~mc tag list versions` + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +List Tags for a Bucket or Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc tag list` to list tags for a bucket or object: + +.. code-block:: shell + :class: copyable + + mc tag list ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the + :ref:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the path to the bucket + or object 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 diff --git a/source/reference/minio-mc/mc-tag-remove.rst b/source/reference/minio-mc/mc-tag-remove.rst new file mode 100644 index 00000000..93f438b5 --- /dev/null +++ b/source/reference/minio-mc/mc-tag-remove.rst @@ -0,0 +1,138 @@ +.. _minio-mc-tag-remove: + +================= +``mc tag remove`` +================= + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc tag remove + +.. |command| replace:: :mc-cmd:`mc tag remove` +.. |rewind| replace:: :mc-cmd-option:`~mc tag remove rewind` +.. |versions| replace:: :mc-cmd-option:`~mc tag remove versions` +.. |versionid| replace:: :mc-cmd-option:`~mc tag remove version-id` +.. |alias| replace:: :mc-cmd-option:`~mc tag remove ALIAS` + +Syntax +------ + +.. start-mc-tag-remove-desc + +The :mc:`mc tag remove` command removes all tags from a bucket or object. + +.. end-mc-tag-remove-desc + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command removes tags for the ``mydata`` bucket on the + ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc tag remove myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] tag remove \ + [--rewind "string"] \ + [--versions] \ + [--version-id "string"]* \ + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + + :mc-cmd-option:`mc tag remove version-id` is mutually exclusive with + multiple parameters. See the reference documentation for more information. + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + + *Required* The :ref:`alias ` for a MinIO deployment and the + full path to the object on which to remove all tags (e.g. bucket and path to + object). For example: + + .. code-block:: none + + mc tag remove myminio/mybucket/object.txt + +.. mc-cmd:: rewind + :option: + + .. include:: /includes/facts-versioning.rst + :start-after: start-rewind-desc + :end-before: end-rewind-desc + +.. 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 remove versions` and + :mc-cmd-option:`~mc tag remove rewind` together to remove tags from all + object versions which existed at a specific point in time. + +.. 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 the following parameters: + + - :mc-cmd-option:`~mc tag remove rewind` + - :mc-cmd-option:`~mc tag remove versions` + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +Remove Tags from a Bucket or Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc tag remove` to remove tags from a bucket or object: + +.. code-block:: shell + :class: copyable + + mc tag remove ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the + :ref:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the path to the bucket + or object 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 diff --git a/source/reference/minio-mc/mc-tag-set.rst b/source/reference/minio-mc/mc-tag-set.rst new file mode 100644 index 00000000..e9456cdc --- /dev/null +++ b/source/reference/minio-mc/mc-tag-set.rst @@ -0,0 +1,155 @@ +.. _minio-mc-tag-set: + +============== +``mc tag set`` +============== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc tag +.. mc:: mc tag set + +.. |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 ALIAS` + +Syntax +------ + +.. start-mc-tag-set-desc + +The :mc:`mc tag set` command sets one or more tags to a bucket or object. + +.. end-mc-tag-set-desc + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command sets tags for the ``mydata`` bucket on the + ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc tag set myminio/mydata "tag1=value1&tag2=value2" + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] tag set \ + [--rewind "string"] \ + [--versions] \ + [--version-id "string"]* \ + ALIAS \ + "TAGS" + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + + :mc-cmd-option:`mc tag set version-id` is mutually exclusive with + multiple parameters. See the reference documentation for more information. + + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + + *Required* The :ref:`alias ` for a MinIO deployment and the + full path to the object on which to apply the tag (e.g. bucket and path to + object). For example: + + .. code-block:: none + + mc tag set myminio/mybucket/object.txt + +.. mc-cmd:: TAGS + + *Required* An ampersand-seperated (``&``) list of key-value pairs + (``KEY=VALUE``), where each pair represents one tag to assign to the object. + For example: + + .. code-block:: none + + mc tag set myminio/mybucket/object.txt "key1=value1&key2=value2" + +.. mc-cmd:: rewind + :option: + + .. include:: /includes/facts-versioning.rst + :start-after: start-rewind-desc + :end-before: end-rewind-desc + +.. 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:: version-id, vid + :option: + + .. include:: /includes/facts-versioning.rst + :start-after: start-version-id-desc + :end-before: end-version-id-desc + + Mutually exclusive with the following parameters: + + - :mc-cmd-option:`~mc tag set rewind` + - :mc-cmd-option:`~mc tag set versions` + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +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 ` with the + :ref:`alias ` of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the path to the bucket + or object on the MinIO deployment. + +- Replace :mc-cmd:`TAGS ` with one or more ampersand-separated + (``&``) key-value pairs for each tag and its corresponding value. + +Behavior +-------- + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility diff --git a/source/reference/minio-mc/mc-template.rst b/source/reference/minio-mc/mc-template.rst new file mode 100644 index 00000000..8646e70f --- /dev/null +++ b/source/reference/minio-mc/mc-template.rst @@ -0,0 +1,78 @@ +.. + + Use this file as a template for adding new MinIO `mc` commands and + subcommands. + +.. _minio-mc-COMMAND: + +============================ +``mc COMMAND`` +============================ + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc COMMAND + +Syntax +------ + +.. start-mc-COMMAND-desc + +The :mc:`mc COMMAND` command DESCRIPTION + +.. end-mc-COMMAND-desc + +.. code-block:: shell + + mc [GLOBALFLAGS] COMMAND FLAGS [FLAGS] ARGUMENTS [ARGUMENTS] + +Parameters +~~~~~~~~~~ + +.. + + Document all arguments here: + +.. mc-cmd:: ARGUMENT + + *Required|Optional* Describe the argument here + + +.. + + Document all flags here + +.. mc-cmd:: FLAG + + *Required|Optional* Describe the flag here + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +.. + + Document all examples here + + Use action-based titles: + + Enable | Configure | Modify | Deploy | Set + +Behavior +-------- + +.. + + Document all behaviors here + + Be descriptive to improve searchability / SEO diff --git a/source/reference/minio-mc/mc-tree.rst b/source/reference/minio-mc/mc-tree.rst new file mode 100644 index 00000000..60253500 --- /dev/null +++ b/source/reference/minio-mc/mc-tree.rst @@ -0,0 +1,128 @@ +=========== +``mc tree`` +=========== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc tree + +.. |command| replace:: :mc-cmd:`mc tree` +.. |rewind| replace:: :mc-cmd-option:`~mc tree rewind` +.. |alias| replace:: :mc-cmd-option:`~mc tree ALIAS` + +Syntax +------ + +.. start-mc-tree-desc + +The :mc:`mc tree` command lists all prefixes inside a MinIO bucket in a tree +format. The command optionally supports listing all objects inside of bucket +at each prefix, including the bucket root. + +.. end-mc-tree-desc + +You can also use :mc:`mc tree` against a local filesystem directory to +produce similar results to the ``tree`` commandline tool. + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command prints a complete tree of all objects at any + depth in the ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc tree --files myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] tree \ + [--depth int] \ + [--files] \ + [--rewind "string"] \ + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: ALIAS + + *Required* The :ref:`alias ` of a MinIO deployment and the + full path to the bucket to list the tree hierarchy. For example: + + .. code-block:: shell + + mc tree myminio/mybucket + + You can specify multiple targets to The command command. For + example: + + .. code-block:: shell + + mc tree myminio/mybucket myminio/myotherbucket + + For retrieving the tree heirarchy of a local filesystem directory, + specify the full path to that directory. For example: + + .. code-block:: shell + + mc tree ~/minio/mydata/ + +.. mc-cmd:: depth, d + :option: + + *Optional* Limit the tree depth to the specified integer value. + + Defaults to ``-1`` or unlimited depth. + +.. mc-cmd:: files, f + :option: + + *Optional* 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 +-------- + +.. code-block:: shell + :class: copyable + + mc tree ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the :ref:`alias ` + of the MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the path to the bucket 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 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-update.rst b/source/reference/minio-mc/mc-update.rst new file mode 100644 index 00000000..b5582b78 --- /dev/null +++ b/source/reference/minio-mc/mc-update.rst @@ -0,0 +1,59 @@ +============= +``mc update`` +============= + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 1 + +.. mc:: mc update + +Syntax +------ + +.. start-mc-update-desc + +The :mc:`mc update` command automatically updates the :program:`mc` binary to +the latest stable version. + +.. end-mc-update-desc + +Running this command is equivalent to manually downloading the latest +stable binary and using it to replace the existing ``mc`` installation on the +host machine. + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command updates the :program:`mc` binary on the local host: + + .. code-block:: shell + :class: copyable + + mc update + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] update + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + +Use :mc:`mc update` after updating the :program:`minio` server binary to +ensure consistent behavior and compatibility. + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-json-globals + :end-before: end-minio-mc-json-globals diff --git a/source/reference/minio-mc/mc-version.rst b/source/reference/minio-mc/mc-version.rst new file mode 100644 index 00000000..1cf4e853 --- /dev/null +++ b/source/reference/minio-mc/mc-version.rst @@ -0,0 +1,186 @@ +============== +``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, suspends, and retrieves the +:ref:`versioning ` configuration for a MinIO bucket. + +.. end-mc-version-desc + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command enables, suspends, and retrieves versioning + for the ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc version enable myminio/mydata + mc version info myminio/mydata + mc version suspend myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] version \ + [enable | suspend | info] \ + ALIAS + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: enable + + Enables versioning on the MinIO bucket specified to + :mc-cmd:`ALIAS `. + + Mutually exclusive with :mc-cmd:`~mc version suspend` and + :mc-cmd:`~mc version info` + +.. mc-cmd:: suspend + + Disables versioning on the MinIO bucket specified to + :mc-cmd:`ALIAS `. + + Mutually exclusive with :mc-cmd:`~mc version suspend` and + :mc-cmd:`~mc version info` + +.. mc-cmd:: info + + Returns the versioning configuration for the MinIO bucket specified to + :mc-cmd:`ALIAS `. + + Mutually exclusive with :mc-cmd:`~mc version suspend` and + :mc-cmd:`~mc version info` + +.. mc-cmd:: ALIAS + + *Required* The :ref:`alias ` of a MinIO deployment and the full path + to the bucket for which to set the versioning configuration. For example: + + .. code-block:: shell + + mc version enable myminio/mybucket + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-json-globals + :end-before: end-minio-mc-json-globals + +Examples +-------- + +Enable Bucket Versioning +~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc version suspend` to enable versioning on a bucket: + +.. code-block:: shell + :class: copyable + + mc version ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of a configured MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the bucket on which + to enable versioning. + +Disable Bucket Versioning +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc version suspend` to suspend versioning on a bucket: + +.. code-block:: shell + :class: copyable + + mc version ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of a configured MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the bucket on which + to suspend versioning. + +Get Bucket Versioning Status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc version info` to enable versioning on a bucket: + +.. code-block:: shell + :class: copyable + + mc version ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the + :mc:`alias ` of a configured MinIO deployment. + +- Replace :mc-cmd:`PATH ` with the bucket on which + to retrieve the versioning status. + +Behavior +-------- + +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 retention` for more information on configuring object locking. + +Bucket Versioning Requires Distributed MinIO +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MinIO bucket versioning is available only on +:ref:`distributed MinIO deployments `. Specifically, +Bucket versioning requires that the MinIO deployment supports +:ref:`erasure coding ` (4+ drives). Standalone +MinIO deployments (1 drive) cannot support bucket versioning. + +See the linked :ref:`comparison table ` for +a complete list of features available only with distributed MinIO deployments. + +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 ` to delete an +object *and* all its versions. + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility \ No newline at end of file diff --git a/source/reference/minio-mc/mc-watch.rst b/source/reference/minio-mc/mc-watch.rst new file mode 100644 index 00000000..2e5c8fc7 --- /dev/null +++ b/source/reference/minio-mc/mc-watch.rst @@ -0,0 +1,138 @@ +============ +``mc watch`` +============ + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc watch + +Syntax +------ + +.. start-mc-watch-desc + +The :mc:`mc watch` command watches for events on the specified MinIO bucket or +local filesystem path. For S3 services, use :mc:`mc event add` to configure +bucket event notifications on S3-compatible services. + +.. end-mc-watch-desc + +You can also use :mc:`mc watch` against a local filesystem directory to +produce similar results to running +the ``inotify -e modify,create,delete,move`` command. + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command watches for + :ref:`events ` on any object or prefix in the + ``mydata`` bucket on the ``myminio`` MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc watch --recursive myminio/mydata + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] watch \ + [--event "string"] \ + [--prefix "string"] \ + [--recursive] \ + [--suffix "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 ` of a MinIO deployment and the + full path to the bucket to watch for configured events. For example: + + .. code-block:: shell + + mc tree myminio/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 ALIAS` of ``play/mybucket`` and a + :mc-cmd-option:`~mc watch prefix` of ``photos``, only events in + ``play/mybucket/photos`` trigger bucket notifications. + +.. mc-cmd:: recursive, r + :option: + + Recursively watch for events in the specified + :mc-cmd:`~mc watch ALIAS` bucket path or local directory. + +.. 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 ALIAS` of ``play/mybucket`` and a + :mc-cmd-option:`~mc watch suffix` of ``.jpg``, only events in + ``play/mybucket/*.jpg`` trigger bucket notifications. + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-json-globals + :end-before: end-minio-mc-json-globals + +Examples +-------- + +Watch for Events in a Bucket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: shell + :class: copyable + + mc watch --recursive ALIAS/PATH + +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` + of the S3-compatible host. + +- Replace :mc-cmd:`PATH ` with the path to the bucket. + + +Behavior +-------- + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility + diff --git a/source/reference/minio-server/minio-server.rst b/source/reference/minio-server/minio-server.rst index e25f080f..dbcc8642 100644 --- a/source/reference/minio-server/minio-server.rst +++ b/source/reference/minio-server/minio-server.rst @@ -26,6 +26,17 @@ see :ref:`minio-installation`. For examples of deploying :mc:`minio server` on a Kubernetes environment, see :docs-k8s:`Kubernetes documentation <>`. +.. admonition:: AGPLv3 + :class: note + + :program:`minio server` is :minio-git:`AGPLv3 ` + licensed Free and Open Source (FOSS) software. + + Applications integrating :program:`mc` may trigger AGPLv3 compliance + requirements. `MinIO Commericla Licensing `__ + is the best option for applications which trigger AGPLv3 obligations where + open-sourcing the application is not an option. + Configuration Settings ~~~~~~~~~~~~~~~~~~~~~~ @@ -347,41 +358,6 @@ MinIO Console: Key Management Service and Encryption ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. envvar:: MINIO_KMS_SECRET_KEY - - .. versionadded:: RELEASE.2021-04-22T15-44-28Z - - The client-provided encryption 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. - - Do not use this setting in production environments. Use the MinIO - :minio-git:`Key Encryption Service (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 - ` for more information. - - Specify a 32-bit base-64 encrypted string in the following format: - - ``:`` - - - Replace the ```` with any string. You must use this - key name if you later migrate to using a dedicated KMS for - managing encryption keys. - - - Replace ```` with a 32-bit base64 encoded value. - For example: - - .. code-block:: shell - :class: copyable - - cat /dev/urandom | head -c 32 | base64 - - - Prior to :minio-release:`RELEASE.2021-04-22T15-44-28Z`, MinIO used the - :ref:`root ` user credentials for encrypting the backend. - .. envvar:: MINIO_KMS_KES_ENDPOINT The endpoint for the MinIO Key Encryption Service (KES) process to use diff --git a/source/replication/enable-server-side-multi-site-bucket-replication.rst b/source/replication/enable-server-side-multi-site-bucket-replication.rst index d8978ab6..6f42e352 100644 --- a/source/replication/enable-server-side-multi-site-bucket-replication.rst +++ b/source/replication/enable-server-side-multi-site-bucket-replication.rst @@ -78,19 +78,19 @@ Replication Requires Versioning MinIO relies on the immutability protections provided by versioning to synchronize objects as part of replication. -Use the :mc-cmd:`mc version enable` command to enable versioning for the bucket +Use the :mc-cmd:`mc version suspend` command to enable versioning for the bucket across *all* MinIO deployments participating in the multi-site replication configuration. .. code-block:: shell :class: copyable - mc version enable ALIAS/PATH + mc version ALIAS/PATH -- Replace :mc-cmd:`ALIAS ` with the +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the MinIO deployment. -- Replace :mc-cmd:`PATH ` with the bucket on which +- Replace :mc-cmd:`PATH ` with the bucket on which to enable versioning. Install and Configure ``mc`` with Access to Both Clusters. diff --git a/source/replication/enable-server-side-one-way-bucket-replication.rst b/source/replication/enable-server-side-one-way-bucket-replication.rst index c7652f8e..fa281664 100644 --- a/source/replication/enable-server-side-one-way-bucket-replication.rst +++ b/source/replication/enable-server-side-one-way-bucket-replication.rst @@ -60,18 +60,18 @@ 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 +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 enable ALIAS/PATH + mc version ALIAS/PATH -- Replace :mc-cmd:`ALIAS ` with the +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the MinIO cluster. -- Replace :mc-cmd:`PATH ` with the bucket on which +- Replace :mc-cmd:`PATH ` with the bucket on which to enable versioning. Install and Configure ``mc`` with Access to Both Clusters. @@ -359,22 +359,17 @@ replication rule to the source MinIO cluster. :class: copyable mc replicate add AlphaReplication/SOURCEBUCKET \ - --remote-bucket DESTINATIONBUCKET \ - --arn 'arn:minio:replication:::DESTINATIONBUCKET' \ + --remote-bucket 'arn:minio:replication:::DESTINATIONBUCKET' \ --replicate "delete,delete-marker,existing-objects" - Replace ``SOURCEBUCKET`` with the name of the bucket from which Alpha replicates data. The name *must* match the bucket specified when creating the remote target in the previous step. -- Replace the ``DESTINATIONBUCKET`` with the name of the ``Baker`` bucket to - which Alpha replicates data. The name *must* match the bucket specified - when creating the remote target in the previous step. - -- Replace the ``--arn`` value with the ARN returned in the previous step. - Ensure you specify the ARN created on the ``Alpha`` cluster. You can use - :mc-cmd:`mc admin bucket remote ls` to list all remote ARNs configured - on the cluster. +- Replace the ``--remote-bucket`` value with the ARN returned in the previous + step. Ensure you specify the ARN created on the ``Alpha`` cluster. You can use + :mc-cmd:`mc admin bucket remote ls` to list all remote ARNs configured on the + cluster. - The ``--replicate "delete,delete-marker,existing-objects"`` flag enables the following replication features: diff --git a/source/replication/enable-server-side-two-way-bucket-replication.rst b/source/replication/enable-server-side-two-way-bucket-replication.rst index 3b336f0c..a45823c7 100644 --- a/source/replication/enable-server-side-two-way-bucket-replication.rst +++ b/source/replication/enable-server-side-two-way-bucket-replication.rst @@ -65,18 +65,18 @@ Replication Requires Versioning 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 +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 enable ALIAS/PATH + mc version ALIAS/PATH -- Replace :mc-cmd:`ALIAS ` with the +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the MinIO cluster. -- Replace :mc-cmd:`PATH ` with the bucket on which +- Replace :mc-cmd:`PATH ` with the bucket on which to enable versioning. Install and Configure ``mc`` with Access to Both Clusters. @@ -438,20 +438,15 @@ A\) Create Replication Rule on Alpha :class: copyable mc replicate add AlphaReplication/SOURCEBUCKET \ - --remote-bucket DESTINATIONBUCKET \ - --arn 'arn:minio:replication:::DESTINATIONBUCKET' \ + --remote-bucket 'arn:minio:replication:::DESTINATIONBUCKET' \ --replicate "delete,delete-marker,existing-objects" - Replace ``SOURCEBUCKET`` with the name of the bucket from which Alpha replicates data. The name *must* match the bucket specified when creating the remote target in the previous step. - - Replace the ``DESTINATIONBUCKET`` with the name of the ``Baker`` bucket to - which Alpha replicates data. The name *must* match the bucket specified - when creating the remote target in the previous step. - - - Replace the ``--arn`` value with the ARN returned in the previous step. - Ensure you specify the ARN created on the ``Alpha`` cluster. You can use + - Replace the ``--remote-bucket`` value ARN returned in the previous step. + Ensure you specify the ARN created for the ``Baker`` cluster. You can use :mc-cmd:`mc admin bucket remote ls` to list all remote ARNs configured on the cluster. @@ -478,22 +473,17 @@ B\) Create Replication Rule on Baker :class: copyable mc replicate add BakerReplication/SOURCEBUCKET \ - --remote-bucket DESTINATIONBUCKET \ - --arn 'arn:minio:replication:::DESTINATIONBUCKET' \ + --remote-bucket 'arn:minio:replication:::DESTINATIONBUCKET' \ --replicate "delete,delete-marker,existing-objects" - Replace ``SOURCEBUCKET`` with the name of the bucket from which Baker replicates data. The name *must* match the bucket specified when creating the remote target in the previous step. - - Replace the ``DESTINATIONBUCKET`` with the name of the ``Alpha`` bucket to - which Baker replicates data. The name *must* match the bucket specified - when creating the remote target in the previous step. - - - Replace the ``--arn`` value with the ARN returned in the previous step. - Ensure you specify the ARN created on the ``Alpha`` cluster. You can use - :mc-cmd:`mc admin bucket remote ls` to list all remote ARNs configured - on the cluster. + - Replace the ``--remote-bucket`` with the value with the ARN returned in the + previous step. Ensure you specify the ARN created for the ``Alpha`` + cluster. You can use :mc-cmd:`mc admin bucket remote ls` to list all remote + ARNs configured on the cluster. - The ``--replicate "delete,delete-marker,existing-objects"`` flag enables the following replication features: @@ -508,9 +498,6 @@ B\) Create Replication Rule on Baker Specify any other supported optional arguments for :mc-cmd:`mc replicate add`. - Specify any other supported optional arguments for - :mc-cmd:`mc replicate add`. - 5) Validate the Replication Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/replication/replication-overview.rst b/source/replication/replication-overview.rst index daf80189..43b2ceed 100644 --- a/source/replication/replication-overview.rst +++ b/source/replication/replication-overview.rst @@ -24,7 +24,7 @@ and destination buckets. remote replication target. :ref:`Client-side Bucket Replication ` - Use the :mc-cmd:`mc mirror` process to synchronize objects between buckets + Use The command process to synchronize objects between buckets within the same S3-compatible cluster *or* between two independent S3-compatible clusters. Client-side replication using :mc-cmd:`mc mirror` supports MinIO-to-S3 and similar replication configurations. @@ -105,10 +105,16 @@ Replication of Delete Operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ MinIO supports replicating delete operations, where MinIO synchronizes -deleting specific object versions *and* new :s3-docs:`delete markers -`. Delete operation replication uses -the same :ref:`replication process ` as all other -replication operations. +deleting specific object versions *and* new +:s3-docs:`delete markers `. Delete operation +replication uses the same :ref:`replication process ` +as all other replication operations. + +MinIO requires explicitly enabling versioned deletes and delete marker +replication . Use the :mc-cmd-option:`mc replicate add replicate` field to +specify both or either ``delete`` and ``delete-marker`` to enable versioned +deletes and delete marker replication respectively. To enable both, specify both +strings using a comma separator ``delete,delete-marker``. For delete marker replication, MinIO begins the replication process after a delete operation creates the delete marker. MinIO uses the @@ -127,12 +133,6 @@ in listing operations returning the object version after the initial delete operation. MinIO uses the ``X-Minio-Replication-Delete-Status`` for tracking delete version replication status. -MinIO requires explicitly enabling versioned deletes and delete marker -replication . Use the :mc-cmd-option:`mc replicate add replicate` field to -specify both or either ``delete`` and ``delete-marker`` to enable versioned -deletes and delete marker replication respectively. To enable both, specify both -strings using a comma separator ``delete,delete-marker``. - MinIO only replicates explicit client-driven delete operations. MinIO does *not* replicate objects deleted from the application of :ref:`lifecycle management expiration rules @@ -211,7 +211,7 @@ overall cluster load, and the size of the namespace (all objects in the bucket). MinIO does not synchronize existing unversioned objects. Specifically, the bucket *must* have :ref:`versioning ` enabled when the -object was created. You can use the :mc-cmd:`mc cp` command to create a +object was created. You can use The command command to create a "versioned" copy of that object. Once that object replicates successfully, you can delete the unversioned object (versionid = ``null``). diff --git a/source/security/server-side-encryption/server-side-encryption-sse-c.rst b/source/security/server-side-encryption/server-side-encryption-sse-c.rst index 6e9fa8f6..ccc3ec5d 100644 --- a/source/security/server-side-encryption/server-side-encryption-sse-c.rst +++ b/source/security/server-side-encryption/server-side-encryption-sse-c.rst @@ -128,11 +128,11 @@ arguments for enabling SSE-S3 encryption: mc cp ~/data/mydata.json ALIAS/BUCKET/mydata.json \ --encrypt-key "ALIAS/BUCKET/=c2VjcmV0ZW5jcnlwdGlvbmtleWNoYW5nZW1lMTIzNAo=" -- Replace :mc-cmd:`ALIAS ` with the +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the MinIO deployment on which you want to write the SSE-C encrypted object. -- Replace :mc-cmd:`BUCKET ` with the full path to the +- Replace :mc-cmd:`BUCKET ` with the full path to the bucket or bucket prefix to which you want to write the SSE-C encrypted object. 3) Copy an SSE-C Encrypted Object @@ -161,13 +161,13 @@ arguments for enabling SSE-S3 encryption: --encrypt-key "SOURCE/BUCKET/=c2VjcmV0ZW5jcnlwdGlvbmtleWNoYW5nZW1lMTIzNAo=" \ --encrypt-key "TARGET/BUCKET/=c2VjcmV0ZW5jcnlwdGlvbmtleWNoYW5nZW1lMTIzNAo=" -- Replace :mc-cmd:`SOURCE/BUCKET ` with the +- Replace :mc-cmd:`SOURCE/BUCKET ` with the :mc:`alias ` of the MinIO deployment from which you are reading the encrypted object and the full path to the bucket or bucket prefix from which you want to read the SSE-C encrypted object. -- Replace :mc-cmd:`TARGET/BUCKET ` with the +- Replace :mc-cmd:`TARGET/BUCKET ` with the :mc:`alias ` of the MinIO deployment from which you are writing the encrypted object and the full path to the bucket or bucket prefix to which you want to write the SSE-C encrypted diff --git a/source/security/server-side-encryption/server-side-encryption-sse-kms.rst b/source/security/server-side-encryption/server-side-encryption-sse-kms.rst index 9c9d69fe..bf707585 100644 --- a/source/security/server-side-encryption/server-side-encryption-sse-kms.rst +++ b/source/security/server-side-encryption/server-side-encryption-sse-kms.rst @@ -227,10 +227,10 @@ of all objects written to a specific bucket. mc encrypt set sse-kms my-minio-sse-kms-key ALIAS/BUCKET -- Replace :mc-cmd:`ALIAS ` with the +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the MinIO deployment on which you enabled SSE-KMS. -- Replace :mc-cmd:`BUCKET ` with the full path to the +- Replace :mc-cmd:`BUCKET ` with the full path to the bucket or bucket prefix on which you want to enable automatic SSE-KMS. Objects written to the specified bucket are automatically encrypted using diff --git a/source/security/server-side-encryption/server-side-encryption-sse-s3.rst b/source/security/server-side-encryption/server-side-encryption-sse-s3.rst index ab56cd40..a04c8dcf 100644 --- a/source/security/server-side-encryption/server-side-encryption-sse-s3.rst +++ b/source/security/server-side-encryption/server-side-encryption-sse-s3.rst @@ -227,10 +227,10 @@ of all objects written to a specific bucket. mc encrypt set sse-s3 ALIAS/BUCKET -- Replace :mc-cmd:`ALIAS ` with the +- Replace :mc-cmd:`ALIAS ` with the :mc:`alias ` of the MinIO deployment on which you enabled SSE-S3. -- Replace :mc-cmd:`BUCKET ` with the full path to the +- Replace :mc-cmd:`BUCKET ` with the full path to the bucket or bucket prefix on which you want to enable automatic SSE-S3. .. _minio-encryption-sse-s3-erasure-locking: