diff --git a/source/reference/minio-mc.rst b/source/reference/minio-mc.rst index fc4a919e..60ae846b 100644 --- a/source/reference/minio-mc.rst +++ b/source/reference/minio-mc.rst @@ -262,6 +262,11 @@ The following table lists :mc-cmd:`mc` commands: :start-after: start-mc-mv-desc :end-before: end-mc-mv-desc + * - :mc:`mc od` + - .. include:: /reference/minio-mc/mc-od.rst + :start-after: start-mc-od-desc + :end-before: end-mc-od-desc + * - :mc:`mc pipe` - .. include:: /reference/minio-mc/mc-pipe.rst :start-after: start-mc-pipe-desc @@ -494,6 +499,7 @@ All :ref:`commands ` support the following global options: /reference/minio-mc/mc-mb /reference/minio-mc/mc-mirror /reference/minio-mc/mc-mv + /reference/minio-mc/mc-od /reference/minio-mc/mc-pipe /reference/minio-mc/mc-rb /reference/minio-mc/mc-replicate-add diff --git a/source/reference/minio-mc/mc-ilm-add.rst b/source/reference/minio-mc/mc-ilm-add.rst index 523a5215..ff229d5d 100644 --- a/source/reference/minio-mc/mc-ilm-add.rst +++ b/source/reference/minio-mc/mc-ilm-add.rst @@ -17,22 +17,17 @@ Syntax .. start-mc-ilm-add-desc -The :mc:`mc ilm add` command adds an object lifecycle management rule to a -bucket. +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. +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: + The following command adds new lifecycle management rules to the ``mydata`` bucket on the ``myminio`` deployment: .. code-block:: shell :class: copyable @@ -41,20 +36,17 @@ rules. mc ilm add --expired-object-delete-marker mydata/myminio - mc ilm add --transition-days 30 --storage-class "COLDTIER" mydata/myminio + mc ilm add --transition-days 30 --tier "COLDTIER" mydata/myminio - mc ilm add --noncurrentversion-transition-days 7 --noncurrent-version-transition-storage-class "COLDTIER" + mc ilm add --noncurrentversion-transition-days 7 --noncurrent-version-transition-tier "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. + - 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 @@ -63,12 +55,18 @@ rules. .. 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] \ + mc [GLOBALFLAGS] ilm add \ + --expiry-days "integer" \ + [--prefix string] \ + [--tags string] \ + [--transition-days "string"] \ + [--tier "string"] \ + [--expired-object-delete-marker] \ + [--noncurrentversion-expiration-days "integer"] \ + [--noncurrentversion-transition-days "integer"] \ + [--noncurrentversion-tier "string"] \ + [--newer-noncurrentversions-expiration "integer"] \ + [--newer-noncurrentversions-transition "integer"] \ ALIAS .. include:: /includes/common-minio-mc.rst @@ -79,153 +77,212 @@ Parameters ~~~~~~~~~~ .. mc-cmd:: ALIAS + :required: - *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: + The :ref:`alias ` and 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: +.. mc-cmd:: --prefix + :optional: + + Restrict the management rule to a specific bucket prefix. + + For example: .. code-block:: none - mc ilm add myminio/mydata/someprefix + mc ilm add --prefix "meetingnotes/" myminio/mydata/ --expiry-days "90" + + The command creates a rule that expires objects in the ``mydata`` bucket of the ``myminio`` ALIAS after 90 days for any object with the ``meetingnotes/`` prefix. .. mc-cmd:: --expiry-days - + :required: - *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. + 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:`~mc ilm add --noncurrentversion-expiration-days` option - to apply expiration behavior to noncurrent object versions. + For versioned buckets, the expiry rule applies only to the *current* object version. + Use the :mc-cmd:`~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. + 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:`~mc ilm add --expired-object-delete-marker` - For more complete documentation on object expiration, see - :ref:`minio-lifecycle-management-expiration`. + For more complete documentation on object expiration, see :ref:`minio-lifecycle-management-expiration`. .. mc-cmd:: --expired-object-delete-marker - + :optional: - *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. + 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:`~mc ilm add --tags` - :mc-cmd:`~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. + 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 + :optional: + The number of calendar days from object creation after which MinIO marks an object as eligible for transition. + MinIO transitions the object to the configured remote tier specified to the :mc-cmd:`~mc ilm add --tier`. + Specify the number of days as an integer, e.g. ``30`` for 30 days. - *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:`~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:`~mc ilm add --noncurrentversion-transition-days` option to apply transition behavior to noncurrent object versions. - For versioned buckets, the transition rule applies only to the *current* - object version. Use the - :mc-cmd:`~mc ilm add --noncurrentversion-transition-days` option - to apply transition behavior to noncurrent object versions. + Requires specifying :mc-cmd:`~mc ilm add --tier`. - Requires specifying :mc-cmd:`~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. - 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`. - For more complete documentation on object transition, see - :ref:`minio-lifecycle-management-tiering`. +.. mc-cmd:: --tier + :optional: -.. mc-cmd:: --storage-class - - - *Required* The remote storage tier to which MinIO - :ref:`transition objects `. - Specify a remote storage tier created by :mc:`mc admin tier`. + The remote tier to which MinIO :ref:`transition objects `. + Specify an existing remote tier created by :mc:`mc admin tier`. Required if specifying :mc-cmd:`~mc ilm add --transition-days`. .. mc-cmd:: --tags - + :optional: - *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. + 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:`~mc ilm add --expired-object-delete-marker` .. mc-cmd:: --noncurrentversion-expiration-days - + :optional: - *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. + 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. + 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. + 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 + :optional: + + The number of days an object has been non-current (i.e. replaced by a newer version of that same object) after which MinIO marks the object version as eligible for transition. + MinIO transitions the object to the configured remote tier specified to the :mc-cmd:`~mc ilm add --tier` once the system host datetime passes that calendar date. + + This option has no effect on non-versioned buckets. + Requires specifying :mc-cmd:`~mc ilm add --noncurrentversion-tier`. + + This option has the same behavior as the S3 ``NoncurrentVersionTransition`` action. + + MinIO uses a scanner process to check objects against all configured lifecycle management rules. + Slow scanning due to high IO workloads or limited system resources may delay application of lifecycle management rules. + See :ref:`minio-lifecycle-management-scanner` for more information. + +.. mc-cmd:: --noncurrentversion-tier + :optional: + + The remote tier to which MinIO :ref:`transitions noncurrent objects versions `. + Specify a remote tier created by :mc:`mc admin tier`. + +.. mc-cmd:: --newer-noncurrentversions-expiration + :optional: + + The maximum number of non-current object versions to retain, ordered from newest to oldest. - - *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:`~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:`~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 + Use this flag to retain a certain number of past versions of a file in a first in, first out fashion. + After retaining the maximum number of non-current versions, MinIO marks any remaining older non-current object versions as eligible for expiration. + The following table lists a number of object versions and their expiration eligibility based on ``--newer-noncurrentversions-expiration 3``: - *Optional* The remote storage tier to which MinIO - :ref:`transitions noncurrent objects versions - `. Specify a remote storage tier created - by :mc:`mc admin tier`. + .. list-table:: + :widths: 50 50 + :width: 100% + + * - v5 (current version) + - Current version not affected by ILM rules. + * - v4 + - retained + * - v3 + - retained + * - v2 + - retained + * - v1 + - marked for expiry + + MinIO retains the current version, v5. + MinIO also retains the next ``3`` non-current versions, starting with the newest. + This means MinIO marks ``v4``, ``v3``, and ``v2`` for the three non-current version to retain. + + ``v1`` would be a fourth non-current version, which falls outside the limit of non-current versions to retain, so MinIO marks ``v1`` for expiration. + + Updating the number for this flag only impacts the unmarked versions of objects. + Any versions already marked for expiration do not change if you increase the number to retain. + + MinIO uses a scanner process to check objects against all configured lifecycle management rules. + Slow scanning due to high IO workloads or limited system resources may delay application of lifecycle management rules. + See :ref:`minio-lifecycle-management-scanner` for more information. + +.. mc-cmd:: --newer-noncurrentversions-transition + :optional: + + The maximum number of non-current object versions to retain on the current tier. + Older object versions beyond the number to retain transition to a different, specified tier. + + Use this flag to keep a certain number of non-current versions of an object accessible on the tier in a first in, first out order. + + If not specified, all non-current object versions transition to the different tier. + + The following table lists a number of object versions and their transition eligibility based on ``--newer-noncurrentversions-transition 3``: + + .. list-table:: + :widths: 50 50 + :width: 100% + + * - v5 (current version) + - Current version not affected by ILM rules. + * - v4 + - kept on current tier + * - v3 + - kept on current tier + * - v2 + - kept on current tier + * - v1 + - marked for transition to other tier + + MinIO retains the current version, v5, on the tier. + MinIO also retains the next ``3`` non-current versions on the tier, starting with the newest. + This means MinIO leaves ``v4``, ``v3``, and ``v2`` for the three non-current version to keep on the current tier. + + ``v1`` would be a fourth non-current version, which falls outside the limit of non-current versions to retain, so MinIO marks ``v1`` for transition. + + Updating the number for this flag only impacts the unmarked versions of objects. + Any versions already marked for transition do not change if you increase the number, and any object versions already transitioned do not transition back to the tier. + + MinIO uses a scanner process to check objects against all configured lifecycle management rules. + Slow scanning due to high IO workloads or limited system resources may delay application of lifecycle management rules. + See :ref:`minio-lifecycle-management-scanner` for more information. Global Flags @@ -238,26 +295,55 @@ Global Flags Examples -------- -Expire Bucket Contents After Number of Days -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Expire All Bucket Contents After Number of Days +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use :mc:`mc ilm add` with :mc-cmd:`~mc ilm add --expiry-days` to -expire bucket contents a number of days after object creation: +Use :mc:`mc ilm add` with :mc-cmd:`~mc ilm add --expiry-days` to mark bucket contents for expiration after a number of days pass from the object's 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:`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:`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. +- 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. + +Transition Non-Current Object Versions at a Prefix to a Different Tier +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the :mc:`mc ilm add` with :mc-cmd:`~mc ilm add --prefix` and :mc-cmd:`~mc ilm add --tier` to transition older non-current versions of an object to a different storage tier. + +.. code-block:: shell + :class: copyable + + mc ilm add --prefix "doc/" --transition-days "90" --tier "MINIOTIER-1" \ + --noncurrentversion-transition-days "45" --noncurrentversion-tier "MINIOTIER-2" \ + myminio/mybucket/ + +This command looks at the contents with the ``doc/`` prefix in the ``mybucket`` bucket on the ``myminio`` deployment. + +- Current objects in the prefix older than 90 days move to the ``MINIOTIER-1`` storage tier. +- Non-current objects in the prefix older than 45 days move to the ``MINIOTIER-2`` storage tier. +- Both ``MINIOTIER-1`` and ``MINIOTIER-2`` have already been created with :mc:`mc admin tier add`. + +Expire All Objects at a Prefix, Retain Current Object Versions Longer Than Non-Current Object Versions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the :mc:`mc ilm add` command with :mc-cmd:`~mc ilm add --prefix`, :mc-cmd:`~mc ilm add --expiry-days`, and :mc-cmd:`~mc ilm add --noncurrentversion-expiration-days` to expire current and non-current versions of an object at different times. + +.. code-block:: shell + :class: copyable + + mc ilm add --prefix "doc/" --expiry-days "300" --noncurrentversion-expiration-days "100" myminio/mybucket/ + +This command looks at the contents with the ``doc/`` prefix in the ``mybucket`` bucket on the ``myminio`` deployment. + +- Current objects expire after 300 days. +- Non-current objects expire after 100 days. Behavior -------- diff --git a/source/reference/minio-mc/mc-ilm-edit.rst b/source/reference/minio-mc/mc-ilm-edit.rst index 09d1660d..c7af68e1 100644 --- a/source/reference/minio-mc/mc-ilm-edit.rst +++ b/source/reference/minio-mc/mc-ilm-edit.rst @@ -36,7 +36,7 @@ rule on a MinIO bucket. mc ilm edit --id "c79nu2p4b0t6qko19rgg" --expired-object-delete-marker mydata/myminio - mc ilm edit --id "c79n19dn10dnab109fg1" --transition-days 30 --storage-class "COLDTIER" + mc ilm edit --id "c79n19dn10dnab109fg1" --transition-days 30 --tier "COLDTIER" The command modifies the specified rules as follows: @@ -55,10 +55,13 @@ rule on a MinIO bucket. mc [GLOBALFLAGS] ilm edit \ --id "string" \ + [--prefix "string"] \ + [--enable] \ + [--disable] \ [--expiry-days "string" | --expired-object-delete-marker] \ - [--transition-days "string"] --storage-class "string" \ + [--transition-days "string"] --tier "string" \ [--noncurrentversion-expiration-days "string"] \ - [--noncurrentversion-transition-days "string" --noncurrentversion-transition-storage-class "string"] \ + [--noncurrentversion-transition-days "string" --noncurrentversion-tier "string"] \ [--tags] \ ALIAS @@ -70,8 +73,9 @@ Parameters ~~~~~~~~~~ .. mc-cmd:: ALIAS - - *Required* The :ref:`alias ` and full path to the bucket on the MinIO + :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: @@ -80,15 +84,39 @@ Parameters mc ilm edit myminio/mydata .. mc-cmd:: --id - + :required: - *Required* The unique ID of the rule. Use :mc:`mc ilm ls` to list bucket + The unique ID of the rule. Use :mc:`mc ilm ls` to list bucket rules and retrieve the ``id`` for the rule you want to modify. -.. mc-cmd:: --expiry-days - +.. mc-cmd:: --disable + :optional: - *Optional* The number of days to retain an object after being created. MinIO + Stop using the rule, but retain the rule for future use. + Objects do not transition or expire when a rule is disabled. + +.. mc-cmd:: --enable + :optional: + + Use a rule to transition or expire objects. + +.. mc-cmd:: --prefix + :optional: + + Restrict the management rule to a specific bucket prefix. + + For example: + + .. code-block:: none + + mc ilm edit --prefix "meetingnotes/" myminio/mydata/ --expiry-days "90" + + The command modifies a rule that expires objects in the ``mydata`` bucket of the ``myminio`` ALIAS after 90 days for any object with the ``meetingnotes/`` prefix. + +.. mc-cmd:: --expiry-days + :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 @@ -114,9 +142,9 @@ Parameters - :mc-cmd:`~mc ilm edit --expired-object-delete-marker` .. mc-cmd:: --expired-object-delete-marker - + :optional: - *Optional* Specify this option to direct MinIO to remove delete markers for + 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. @@ -131,9 +159,9 @@ Parameters rules. See :ref:`minio-lifecycle-management-scanner` for more information. .. mc-cmd:: --noncurrentversion-expiration-days - + :optional: - *Optional* The number of days to retain an object version after becoming + 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. @@ -147,17 +175,17 @@ Parameters rules. See :ref:`minio-lifecycle-management-scanner` for more information. .. mc-cmd:: --noncurrentversion-transition-days - + :optional: - *Optional* The number of days an object has been non-current (i.e. replaced + 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:`~mc ilm edit --storage-class` once the system host datetime + :mc-cmd:`~mc ilm edit --tier` once the system host datetime passes that calendar date. This option has no effect on non-versioned buckets. Requires specifying - :mc-cmd:`~mc ilm edit --noncurrentversion-transition-storage-class`. + :mc-cmd:`~mc ilm edit --noncurrentversion-tier`. This option has the same behavior as the S3 ``NoncurrentVersionTransition`` action. @@ -167,10 +195,10 @@ Parameters 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 - +.. mc-cmd:: --noncurrentversion-tier + :optional: - *Optional* The remote storage tier to which MinIO + The remote storage tier to which MinIO :ref:`transitions noncurrent objects versions `. Specify a remote storage tier created by :mc:`mc admin tier`. @@ -179,10 +207,26 @@ Parameters specified remote tier to the new remote tier. MinIO continues to route requests for objects stored on the old remote tier. -.. mc-cmd:: --tags - +.. mc-cmd:: --newer-noncurrentversions-expiration + :optional: - *Optional* One or more ampersand ``&``-delimited key-value pairs describing + The number of non-current versions of an object to retain before applying expiration. + Older non-current versions beyond the specified number expire. + + By default, MinIO does not retain any non-current versions when an expiration rule applies. + +.. mc-cmd:: --newer-noncurrentversions-transition + :optional: + + The number of non-current versions of an object to keep on the current storage tier. + Older non-current versions beyond the specified number transition to the specified tier. + + By default, MinIO transitions all non-current versions when a transition rule applies. + +.. mc-cmd:: --tags + :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: @@ -190,29 +234,29 @@ Parameters - :mc-cmd:`~mc ilm edit --expired-object-delete-marker` .. mc-cmd:: --transition-days + :optional: - - *Optional* The number of calendar days from object creation after which MinIO + 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:`~mc ilm edit --storage-class`. + :mc-cmd:`~mc ilm edit --tier`. For versioned buckets, the transition rule applies only to the *current* object version. Use the :mc-cmd:`~mc ilm edit --noncurrentversion-transition-days` option to apply transition behavior to noncurrent object versions. - Requires specifying :mc-cmd:`~mc ilm edit --storage-class`. + Requires specifying :mc-cmd:`~mc ilm edit --tier`. MinIO uses a scanner process to check objects against all configured lifecycle management rules. Slow scanning due to high IO workloads or limited system resources may delay application of lifecycle management rules. See :ref:`minio-lifecycle-management-scanner` for more information. -.. mc-cmd:: --storage-class - +.. mc-cmd:: --tier + :optional: - *Optional* The remote storage tier to which MinIO + The remote storage tier to which MinIO :ref:`transition objects `. Specify a remote storage tier created by :mc:`mc admin tier`. @@ -251,12 +295,28 @@ an existing object expiration rule: - Replace ``RULEID`` with the unique ID of the object lifecycle management rule. + Use :mc:`mc ilm ls` to find the ``RULEID``. - 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. +Disable a Lifecycle Management Rule +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc:`mc ilm edit` with :mc-cmd:`~mc ilm edit --disable` to stop using an existing management rule. + +.. code-block:: shell + :class: copyable + + mc ilm edit --id "RULEID" --disable myminio/mybucket + +- Replace ``RULEID`` with the unique ID of the object lifecycle management rule. + Use :mc:`mc ilm ls` to find the ``RULEID``. +- Replace ``myminio`` with the ALIAS of the deployment where the rule exists. +- Replace ``mybucket`` with the bucket for the rule. + Behavior -------- diff --git a/source/reference/minio-mc/mc-license-info.rst b/source/reference/minio-mc/mc-license-info.rst index f865a517..a7740e49 100644 --- a/source/reference/minio-mc/mc-license-info.rst +++ b/source/reference/minio-mc/mc-license-info.rst @@ -67,7 +67,9 @@ Parameters .. mc-cmd:: --airgap :optional: - Use in environments without network access to SUBNET (for example, airgapped, firewalled, or similar configuration) to display instructions for how to register the deployment with SUBNET. + Use in environments where the client machine running the :ref:`minio client ` does not have network access to SUBNET (for example, airgapped, firewalled, or similar configuration) to display instructions for how to register the deployment with SUBNET. + + If the deployment is airgapped, but the local device has network access, you do not need to use the ``--airgap`` flag. Global Flags ~~~~~~~~~~~~ diff --git a/source/reference/minio-mc/mc-license-register.rst b/source/reference/minio-mc/mc-license-register.rst index 5cc967b9..dcefc2c5 100644 --- a/source/reference/minio-mc/mc-license-register.rst +++ b/source/reference/minio-mc/mc-license-register.rst @@ -107,6 +107,9 @@ Parameters For instructions, see the :ref:`airgap example `. + If the deployment is airgapped, but the local device where you are using the :ref:`minio client ` has network access, you do not need to use the ``--airgap`` flag. + + Global Flags ~~~~~~~~~~~~ diff --git a/source/reference/minio-mc/mc-license-update.rst b/source/reference/minio-mc/mc-license-update.rst index e35152bb..23459aae 100644 --- a/source/reference/minio-mc/mc-license-update.rst +++ b/source/reference/minio-mc/mc-license-update.rst @@ -56,6 +56,7 @@ Parameters Use in environments without network access to SUBNET (for example, airgapped, firewalled, or similar configuration). + If the deployment is airgapped, but the local device where you are using the :ref:`minio client ` has network access, you do not need to use the ``--airgap`` flag. Global Flags ~~~~~~~~~~~~ diff --git a/source/reference/minio-mc/mc-mb.rst b/source/reference/minio-mc/mc-mb.rst index b48b286a..512b2184 100644 --- a/source/reference/minio-mc/mc-mb.rst +++ b/source/reference/minio-mc/mc-mb.rst @@ -47,6 +47,7 @@ similar results to the ``mkdir -p`` commandline tool. [--ignore-existing] \ [--region "string"] \ [--with-lock] \ + [--with-versioning] \ ALIAS .. include:: /includes/common-minio-mc.rst @@ -58,9 +59,9 @@ Parameters ~~~~~~~~~~ .. mc-cmd:: ALIAS + :required: - *Required* The MinIO or other S3-compatible service on which to create the - new bucket. + The MinIO or other S3-compatible service on which to create the new bucket. For creating a bucket on MinIO, specify the :ref:`alias ` and the name of the bucket. For example: @@ -77,22 +78,23 @@ Parameters mc mb ~/mydata/mydir .. mc-cmd:: --ignore-existing, p - + :optional: - Directs :mc:`mc mb` to do nothing if the bucket or directory already - exists. + Directs :mc:`mc mb` to do nothing if the bucket or directory already exists. .. mc-cmd:: --region - + :optional: - The region in which to create the specified bucket. Has no effect if the - specified :mc-cmd:`~mc mb ALIAS` is a filesystem directory. + The region in which to create the specified bucket. + Has no effect if the specified :mc-cmd:`~mc mb ALIAS` is a filesystem directory. + + If not specified, default value is ``us-east-1``. .. mc-cmd:: --with-lock, l - + :optional: - Enables :ref:`object locking ` on the specified - bucket. + Enables :ref:`object locking ` on the specified bucket. + Object locking requires, and therefore implies, enabling object versioning. .. important:: @@ -101,6 +103,14 @@ Parameters :ref:`Bucket Lifecycle Management ` or :ref:`Bucket Object Locking ` functionality. +.. mc-cmd:: --with-versioning + :optional: + + Enables :ref:`object versioning ` on the new bucket. + + Versioning is required for :ref:`bucket replication ` or :ref:`site replication `. + Versioning does not imply or require object locking. + Global Flags ~~~~~~~~~~~~ @@ -111,23 +121,45 @@ Global Flags Examples -------- -Create Bucket -~~~~~~~~~~~~~ +Create Bucket with Object Locking +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use :mc:`mc mb` to create a bucket on an S3-compatible host. The -:mc-cmd:`~mc mb --with-lock` option creates the bucket with locking -enabled: +Use :mc:`mc mb` to create a bucket on an S3-compatible host. +The :mc-cmd:`~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:`ALIAS ` with the :mc:`alias ` of the S3-compatible host. - Replace :mc-cmd:`BUCKET ` with the bucket to create. +Create a New Bucket in a Specific Region +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc:`mc mb` to create a bucket on an S3-compatible host. +The :mc-cmd:`~mc mb --region` option creates the bucket in a desired region. + +.. code-block:: shell + :class: copyable + + mc mb --region --region=us-west-2 myminio/mynewbucket + +The above command creates a new bucket, ``mynewbucket`` on the ``myminio`` bucket within the ``us-west-2`` region. + +Create a New Bucket with Versioning Enabled +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: shell + :class: copyable + + mc mb --with-versioning myminio/myversionedbucket + +The above command creates a new bucket, ``myversionedbucket``, on the ``myminio`` alias. +The new bucket enables :ref:`object versioning ` for all objects in the bucket. + Behavior -------- diff --git a/source/reference/minio-mc/mc-od.rst b/source/reference/minio-mc/mc-od.rst new file mode 100644 index 00000000..c9c28780 --- /dev/null +++ b/source/reference/minio-mc/mc-od.rst @@ -0,0 +1,171 @@ +========= +``mc od`` +========= + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc od + +Syntax +------ + +.. start-mc-od-desc + +The :mc:`mc od` command copies a local file to a remote location in a specified number of parts and part sizes. +The command outputs the time it took to upload the file. + +.. end-mc-od-desc + +Use the :mc:`mc od` to mimic the functionality of the Linux ``dd`` command. + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following command Upload 200MiB of a file to a bucket in 5 parts of size 40MiB. + The output shows the results of the upload, including the length of time it took for the upload to complete. + + .. code-block:: shell + :class: copyable + + mc od if=file.zip of=myminio/mybucket/file.zip size=40MiB parts=5 + + If passing the ``--json`` :ref:`global flag `, the output of the command resembles the following: + + .. code-block:: json + + { + "source": "home/user/file.zip" + "target": "myminio/mybucket/file.zip" + "partSize": 41943040 + "totalSize": 209715200 + "parts": 5 + "elapsed": "314ms" + } + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] od \ + if= \ + of= \ + [size=] \ + [parts=] \ + [skip=] + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: if + :required: + + The path of the source object to use for the upload. + Use the full path relative to your current location. + + .. code-block:: none + + mc od if=file.zip of=myminio/mybucket/file.zip + +.. mc-cmd:: of + :required: + + The full target path to upload the object to. + +.. mc-cmd:: size + :optional: + + The size for each part of the file to upload. + If not specified, MinIO determines the size for parts from the source stream. + +.. mc-cmd:: parts + :optional: + + The number of parts to divide the object into for uploading. + If not specified, MinIO determines the number of parts based on the size of the source stream. + +.. mc-cmd:: skip + :optional: + + The number of parts of the file to skip during the upload. + For example, use this option to test the upload speed for a large file of many parts on only a portion of the object's parts. + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + +Examples +-------- + +Upload a Full File with 40MiB Parts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc:`mc od` to upload a file to MinIO in a set of parts of specified size. +The :mc-cmd:`~mc od size` option allows you to specify the desired part size. + +.. code-block:: shell + :class: copyable + + mc od if=file.zip of=myminio/mybucket/file.zip size=40MiB + +- Replace ``myminio/mybucket/file.zip`` with the path of the object or file stream to upload. + +- Replace :mc-cmd:`size ` with the desired size of the object parts. + +MinIO examines the source file and divides it into the necessary number of parts so that no part is larger than the specified 40MiB part size. + +Upload a First Five 40 MiB Parts of a File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc:`mc od` to upload parts of a file to MinIO of specified part size. +The :mc-cmd:`~mc od size` option allows you to specify the desired part size. +The :mc-cmd:`~mc od parts` option allows you to specify the total number of parts to use for the object. + +.. code-block:: shell + :class: copyable + + mc od if=file.zip of=myminio/mybucket/file.zip size=40MiB parts=5 + +- Replace ``myminio/mybucket/file.zip`` with the path of the object or file stream to upload. +- Replace :mc-cmd:`size ` with the desired size of the object parts. +- Replace :mc-cmd:`parts ` with the number of desired parts to use for the object. + +In this command example, if the source object stream is larger than 200MiB (40MiB × 5 parts), only the first 200MiB of the file upload. + +.. important:: + + Using the command this way may not upload the entirety of an object. + +Upload a Full File in 5 Parts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Take a source file, divide the file into a specified number of parts, then upload all parts of the file to a MinIO target. + +.. code-block:: shell + :class: copyable + + mc od if=file.zip of=myminio/mybucket/file.zip parts=5 + +The above command divides the source file into five equal parts, then uploads those parts. + +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-support-diag.rst b/source/reference/minio-mc/mc-support-diag.rst index 37e2e699..1cd894d8 100644 --- a/source/reference/minio-mc/mc-support-diag.rst +++ b/source/reference/minio-mc/mc-support-diag.rst @@ -101,9 +101,10 @@ The command has the following syntax: .. code-block:: shell - mc [GLOBALFLAGS] support diag \ - ALIAS \ - [--airgap] + mc [GLOBALFLAGS] support diag \ + ALIAS \ + [--airgap] \ + [--api-key string] Parameters @@ -124,6 +125,16 @@ Parameters For instructions, see the :ref:`airgap example `. + If the deployment is airgapped, but the local device where you are using the :ref:`minio client ` has network access, you do not need to use the ``--airgap`` flag. + + +.. mc-cmd:: --api-key + :optional: + + Takes the account's API key value from SUBNET. + + This value is only required for airgapped environments where MinIO has not already stored the API key for the deployment. + Global Flags ~~~~~~~~~~~~