From 76e5e35ab3d55a759e6c5b2668757f58c9d3ceab Mon Sep 17 00:00:00 2001 From: Ravind Kumar Date: Mon, 26 Aug 2024 11:54:49 -0400 Subject: [PATCH] DOCS-1191: Updating SSE params, general fixups (#1295) Closes #1191 # Summary Finally getting around to this mc release - Added docs for enc-c, enc-s3, enc-kms - Some docs are making assumptions around behavior that needs to be fixed _first_ - Drive-by linker fixes Staged: http://192.241.195.202:9000/staging/DOCS-1191/linux/index.html --------- Co-authored-by: Andrea Longo Co-authored-by: Daryl White <53910321+djwfyi@users.noreply.github.com> --- source/includes/common-minio-sse.rst | 113 +++++++++- source/operations/monitoring.rst | 5 +- .../mc-admin-bucket-remote.rst | 0 source/reference/minio-mc-admin.rst | 6 - source/reference/minio-mc-deprecated.rst | 5 + source/reference/minio-mc.rst | 2 + source/reference/minio-mc/mc-cat.rst | 44 ++-- source/reference/minio-mc/mc-cp.rst | 47 +--- source/reference/minio-mc/mc-du.rst | 23 +- source/reference/minio-mc/mc-get.rst | 12 +- source/reference/minio-mc/mc-head.rst | 21 +- ...c-idp-ldap-accesskey-create-with-login.rst | 200 ++++++++++++++++++ .../minio-mc/mc-idp-ldap-accesskey-create.rst | 8 +- source/reference/minio-mc/mc-ilm-restore.rst | 31 ++- source/reference/minio-mc/mc-mirror.rst | 21 +- source/reference/minio-mc/mc-mv.rst | 52 +---- source/reference/minio-mc/mc-pipe.rst | 32 +-- source/reference/minio-mc/mc-put.rst | 27 +-- source/reference/minio-mc/mc-rm.rst | 21 -- source/reference/minio-mc/mc-sql.rst | 18 +- source/reference/minio-mc/mc-stat.rst | 12 +- .../minio-mc/minio-client-settings.rst | 22 +- 22 files changed, 435 insertions(+), 287 deletions(-) rename source/reference/{minio-mc-admin => deprecated}/mc-admin-bucket-remote.rst (100%) create mode 100644 source/reference/minio-mc/mc-idp-ldap-accesskey-create-with-login.rst diff --git a/source/includes/common-minio-sse.rst b/source/includes/common-minio-sse.rst index 7275d475..5af0e8b7 100644 --- a/source/includes/common-minio-sse.rst +++ b/source/includes/common-minio-sse.rst @@ -23,4 +23,115 @@ MinIO generates a random 256-bit unique Object Encryption Key (OEK) and uses tha MinIO never stores the plaintext representation of the OEK on a drive. The plaintext OEK resides in RAM during cryptographic operations. -.. end-sse-oek \ No newline at end of file +.. end-sse-oek + +.. start-minio-mc-sse-options + +.. mc-cmd:: --enc-kms + + Encrypt or decrypt objects using server-side :ref:`SSE-KMS encryption ` with client-managed keys. + + The parameter accepts a key-value pair formatted as ``KEY=VALUE`` + + .. list-table:: + :stub-columns: 1 + :widths: 30 70 + :width: 100% + + * - ``KEY`` + - The full path to the object as ``alias/bucket/path/object.ext``. + + You can specify only the top-level path to use a single encryption key for all operations in that path. + + * - ``VALUE`` + - Specify an existing data key on the external KMS. + + See the :mc-cmd:`mc admin kms key create` reference for creating data keys. + + For example: + + .. code-block:: shell + + --enc-kms "myminio/mybucket/prefix/object.obj=mybucketencryptionkey" + + You can specify multiple encryption keys by repeating the parameter. + + Specify the path to a prefix to apply encryption to all matching objects at that path: + + .. code-block:: shell + + --enc-kms "myminio/mybucket/prefix/=mybucketencryptionkey" + +.. mc-cmd:: --enc-s3 + :optional: + + Encrypt or decrypt objects using server-side :ref:`SSE-S3 encryption ` with KMS-managed keys. + Specify the full path to the object as ``alias/bucket/prefix/object``. + + For example: + + .. code-block:: shell + + --enc-s3 "myminio/mybucket/prefix/object.obj" + + You can specify the parameter multiple times to denote different object(s) to encrypt: + + .. code-block:: shell + + --enc-s3 "myminio/mybucket/foo/fooobject.obj" --enc-s3 "myminio/mybucket/bar/barobject.obj" + + Specify the path to a prefix to apply encryption to all matching objects at that path: + + .. code-block:: shell + + --enc-s3 "myminio/mybucket/foo" + +.. start-minio-mc-sse-c-only + +.. mc-cmd:: --enc-c + :optional: + + Encrypt or decrypt objects using server-side :ref:`SSE-C encryption ` with client-managed keys. + + The parameter accepts a key-value pair formatted as ``KEY=VALUE`` + + .. list-table:: + :stub-columns: 1 + :widths: 30 70 + :width: 100% + + * - ``KEY`` + - The full path to the object as ``alias/bucket/path/object.ext``. + + You can specify only the top-level path to use a single encryption key for all operations in that path. + + * - ``VALUE`` + - Specify either a 32-byte RawBase64-encoded key *or* a 64-byte hex-encoded key for use with SSE-C encryption. + + Raw Base64 encoding **rejects** ``=``-padded keys. + Omit the padding or use a Base64 encoder that supports RAW formatting. + + - ``KEY`` - the full path to the object as ``alias/bucket/path/object``. + - ``VALUE`` - the 32-byte RAW Base64-encoded data key to use for encrypting object(s). + + For example: + + .. code-block:: shell + + # RawBase64-Encoded string "mybucket32byteencryptionkeyssec" + --enc-c "myminio/mybucket/prefix/object.obj=bXlidWNrZXQzMmJ5dGVlbmNyeXB0aW9ua2V5c3NlYwo" + + You can specify multiple encryption keys by repeating the parameter. + + Specify the path to a prefix to apply encryption to all matching objects at that path: + + .. code-block:: shell + + --enc-c "myminio/mybucket/prefix/=bXlidWNrZXQzMmJ5dGVlbmNyeXB0aW9ua2V5c3NlYwo" + + .. note:: + + MinIO strongly recommends against using SSE-C encryption in production workloads. + Use SSE-KMS via the ``--enc-kms`` or SSE-S3 via ``--enc-s3`` parameters instead. + +.. end-minio-mc-sse-options \ No newline at end of file diff --git a/source/operations/monitoring.rst b/source/operations/monitoring.rst index a0f6b371..1575a93c 100644 --- a/source/operations/monitoring.rst +++ b/source/operations/monitoring.rst @@ -16,9 +16,8 @@ Monitoring and Alerts Metrics and Alerts ------------------ -MinIO publishes metrics endpoints for scraping data on cluster status and operations. -For historical metrics and analytics, MinIO publishes cluster and node metrics using the :prometheus-docs:`Prometheus Data Model `. -You can use any scraping tool which supports that data model to pull metrics data from MinIO for further analysis and alerting. +MinIO publishes point-in-time metrics using the :prometheus-docs:`Prometheus Data Model `. +You can use any scraping tool which supports that data model to pull those metrics into a database for populating historical views, performing query/analysis of metrics data, or creating alerts on preferred data points. The following table lists tutorials for integrating MinIO metrics with select third-party monitoring software. diff --git a/source/reference/minio-mc-admin/mc-admin-bucket-remote.rst b/source/reference/deprecated/mc-admin-bucket-remote.rst similarity index 100% rename from source/reference/minio-mc-admin/mc-admin-bucket-remote.rst rename to source/reference/deprecated/mc-admin-bucket-remote.rst diff --git a/source/reference/minio-mc-admin.rst b/source/reference/minio-mc-admin.rst index 31f46650..6e92cd36 100644 --- a/source/reference/minio-mc-admin.rst +++ b/source/reference/minio-mc-admin.rst @@ -35,11 +35,6 @@ The following table lists :mc:`mc admin` commands: * - Command - Description - * - :mc-cmd:`mc admin bucket remote` - - .. 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 cluster bucket` - .. include:: /reference/minio-mc-admin/mc-admin-cluster-bucket.rst :start-after: start-mc-admin-cluster-bucket-desc @@ -174,7 +169,6 @@ See :ref:`minio-mc-global-options`. :hidden: :glob: - /reference/minio-mc-admin/mc-admin-bucket-remote /reference/minio-mc-admin/mc-admin-cluster-bucket /reference/minio-mc-admin/mc-admin-cluster-iam /reference/minio-mc-admin/mc-admin-config diff --git a/source/reference/minio-mc-deprecated.rst b/source/reference/minio-mc-deprecated.rst index ae156c7b..bbf268b2 100644 --- a/source/reference/minio-mc-deprecated.rst +++ b/source/reference/minio-mc-deprecated.rst @@ -88,6 +88,10 @@ Table of Deprecated Admin Commands - Replacement Command - Version of Change + * - ``mc admin bucket remote`` + - :mc-cmd:`mc replicate` + - mc RELEASE.2022-12-24T15-21-38Z + * - ``mc admin bucket remote add`` - :mc-cmd:`mc replicate add` - mc RELEASE.2022-12-24T15-21-38Z @@ -236,6 +240,7 @@ Table of Deprecated Admin Commands /reference/deprecated/mc-quota-info /reference/deprecated/mc-quota-set /reference/deprecated/mc-admin-bucket-quota + /reference/deprecated/mc-admin-bucket-remote /reference/deprecated/mc-admin-console /reference/deprecated/mc-admin-idp-ldap /reference/deprecated/mc-admin-idp-ldap-policy diff --git a/source/reference/minio-mc.rst b/source/reference/minio-mc.rst index 466a7692..c9ec01ce 100644 --- a/source/reference/minio-mc.rst +++ b/source/reference/minio-mc.rst @@ -243,6 +243,7 @@ The following table lists :mc-cmd:`mc` commands: :end-before: end-mc-head-desc * - | :mc:`mc idp ldap accesskey` + | :mc:`mc idp ldap accesskey create-with-login` | :mc:`mc idp ldap add` | :mc:`mc idp ldap disable` | :mc:`mc idp ldap enable` @@ -674,6 +675,7 @@ You can also define some of these options using :ref:`Environment Variables ` 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:`~mc cp --encrypt` in double-quotes ``"``. - - :mc-cmd:`~mc cp --encrypt` can use the :envvar:`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 - :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:`~mc cp --encrypt-key` in double quotes ``"``. - - :mc-cmd:`~mc cp --encrypt-key` can use the :envvar:`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-sse.rst + :start-after: start-minio-mc-sse-options + :end-before: end-minio-mc-sse-options .. mc-cmd:: --legal-hold :optional: @@ -485,10 +456,6 @@ Behavior :mc:`mc cp` verifies all copy operations to object storage using MD5SUM checksums. -Interrupted or failed copy operations can resume from the point of failure -by issuing the :mc:`mc cp` operation again with the -:mc-cmd:`~mc cp --continue` argument. - S3 Compatibility ~~~~~~~~~~~~~~~~ diff --git a/source/reference/minio-mc/mc-du.rst b/source/reference/minio-mc/mc-du.rst index 9e6d7ade..4144cdb3 100644 --- a/source/reference/minio-mc/mc-du.rst +++ b/source/reference/minio-mc/mc-du.rst @@ -53,12 +53,11 @@ You can also use :mc:`~mc du` against the local filesystem to produce similar re .. code-block:: shell :class: copyable - mc [GLOBALFLAGS] du \ - [--depth] \ - [--encrypt-key] \ - [--recursive] \ - [--rewind] \ - [--versions] \ + mc [GLOBALFLAGS] du \ + [--depth] \ + [--recursive] \ + [--rewind] \ + [--versions] \ ALIAS [ALIAS ...] .. include:: /includes/common-minio-mc.rst @@ -97,18 +96,6 @@ Parameters Print the total for all folders N or fewer levels below the path specified in the command. Default is 0, for the specified path only. -.. mc-cmd:: --encrypt-key - :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:`~mc du --encrypt-key` in double quotes ``"``. - - :mc-cmd:`~mc du --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 :optional: diff --git a/source/reference/minio-mc/mc-get.rst b/source/reference/minio-mc/mc-get.rst index 7cc125d5..0686d929 100644 --- a/source/reference/minio-mc/mc-get.rst +++ b/source/reference/minio-mc/mc-get.rst @@ -46,7 +46,7 @@ The :mc:`mc get` command downloads an object from a target S3 deployment to the mc [GLOBALFLAGS] get \ SOURCE \ TARGET \ - [--enc-c value] + [--enc-c string] \ [--version-id, --vid value] .. include:: /includes/common-minio-mc.rst @@ -66,13 +66,11 @@ Parameters The destination path on the local file system where the command should place the downloaded file. -.. mc-cmd:: --enc-c - :optional: +.. block include of enc-c - Encrypt or decrypt objects using client provided keys. - Repeat the flag to pass multiple keys. - - Keys must be in either Raw Base64 or Hex format. +.. include:: /includes/common-minio-sse.rst + :start-after: start-minio-mc-sse-c-only + :end-before: end-minio-mc-sse-options .. mc-cmd:: --version-id, --vid :optional: diff --git a/source/reference/minio-mc/mc-head.rst b/source/reference/minio-mc/mc-head.rst index 21a0838f..b68f7be4 100644 --- a/source/reference/minio-mc/mc-head.rst +++ b/source/reference/minio-mc/mc-head.rst @@ -56,7 +56,7 @@ tool. [--lines int] \ [--rewind "string"] \ [--version-id "string"] \ - [--encrypt-key "string"] \ + [--enc-c "string"] \ ALIAS [ALIAS ...] .. include:: /includes/common-minio-mc.rst @@ -99,22 +99,11 @@ Parameters Defaults to ``10``. -.. mc-cmd:: --encrypt-key - :optional: +.. block include of enc-c - 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:`~mc head --encrypt-key` in double quotes ``"``. - - :mc-cmd:`~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-sse.rst + :start-after: start-minio-mc-sse-c-only + :end-before: end-minio-mc-sse-options .. mc-cmd:: --rewind :optional: diff --git a/source/reference/minio-mc/mc-idp-ldap-accesskey-create-with-login.rst b/source/reference/minio-mc/mc-idp-ldap-accesskey-create-with-login.rst new file mode 100644 index 00000000..c0a40f1b --- /dev/null +++ b/source/reference/minio-mc/mc-idp-ldap-accesskey-create-with-login.rst @@ -0,0 +1,200 @@ +.. _minio-mc-idp-ldap-accesskey-create-with-login: + +=========================================== +``mc idp ldap accesskey create-with-login`` +=========================================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + + +.. mc:: mc idp ldap accesskey create-with-login + +.. versionadded:: mc RELEASE.2024-04-18T16-45-29Z + +Description +----------- + +.. start-mc-idp-ldap-accesskey-create-with-login-desc + +The :mc:`mc idp ldap accesskey create-with-login` uses interactive terminal-based prompt to authenticate with the external AD/LDAP server and generate access keys for use with MinIO. + +.. end-mc-idp-ldap-accesskey-create-with-login-desc + +.. tab-set:: + + .. tab-item:: EXAMPLE + + The following example prompts the user to provide their AD/LDAP credentials. + It then generates a new access key pair using the policy or policies associated with that AD/LDAP user. + + .. code-block:: shell + :class: copyable + + mc idp ldap accesskey create-with-login https://minio.example.net/ + + .. tab-item:: SYNTAX + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc [GLOBALFLAGS] idp ldap accesskey create-with-login \ + URL \ + [--access-key ] \ + [--secret-key ] \ + [--policy ] \ + [--name ] \ + [--description ] \ + [--expiry ] \ + [--expiry-duration ] + + - Replace ``URL`` with the :abbr:`FQDN (Fully Qualified Domain Name)` of a MinIO deployment configured for AD/LDAP integration. + + .. include:: /includes/common-minio-mc.rst + :start-after: start-minio-syntax + :end-before: end-minio-syntax + + +Parameters +~~~~~~~~~~ + +.. mc-cmd:: URL + :required: + + The :abbr:`FQDN (Fully Qualified Domain Name)` of a MinIO deployment configured for AD/LDAP integration. + + For example: + + .. code-block:: none + + mc idp ldap accesskey create-with-login https://minio.example.net + +.. mc-cmd:: --access-key + :optional: + + The access key to use once successfully authenticated. + Omit to let MinIO randomly generate a value. + + The access key cannot contain the characters ``=`` (equal sign) or ``,`` (comma). + + Requires :mc-cmd:`~mc idp ldap accesskey create-with-login --secret-key` + +.. mc-cmd:: --secret-key + :optional: + + A secret key to use once successfully authenticated. + Omit to let MinIO randomly generate a value. + + Requires :mc-cmd:`~mc idp ldap accesskey create-with-login --access-key` + +.. mc-cmd:: --policy + :optional: + + File path to the JSON-formatted :ref:`policy ` to use for the account. + This policy _cannot_ grant additional privileges beyond the privileges associated with the authenticated AD/LDAP user. + + Omit to use the AD/LDAP user policies. + +.. mc-cmd:: --name + :optional: + + A human-readable name to use for the created access key. + +.. mc-cmd:: --description + :optional: + + Create a description for the service account. + For example, you might specify the reason the access key exists. + +.. mc-cmd:: --expiry-duration + :optional: + + Length of time the access key pair should remain valid for use in ``#d#h#s`` format. + + For example, ``7d``, ``24h``, ``5d12h30s`` are valid strings. + + Mutually exclusive with :mc-cmd:`~mc idp ldap accesskey create-with-login --expiry`. + +.. mc-cmd:: --expiry + :optional: + + The date after which the access key expires. + Enter the date in ``YYYY-MM-DD`` format. + + For example, to expire the credentials after December 31, 2024, enter ``2024-12-31``. + + Mutually exclusive with :mc-cmd:`~mc idp ldap accesskey create-with-login --expiry-duration`. + + +Global Flags +~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-globals + :end-before: end-minio-mc-globals + + +Behavior +-------- + +S3 Compatibility +~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-minio-mc.rst + :start-after: start-minio-mc-s3-compatibility + :end-before: end-minio-mc-s3-compatibility + +Examples +-------- + +Create a new access-key pair for the authenticated user +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command creates a new access key pair to use with the currently authenticated user on the ``minio`` alias. +The command outputs a randomly generated access key and secret key. + +.. code-block:: shell + :class: copyable + + mc idp ldap accesskey create-with-login https://minio.example.net + +Create a new access-key pair with a custom access key and secret key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command creates a new access key pair with both an access key and secret key that you specify for the user currently authenticated on the ``minio`` alias. + +.. code-block:: shell + :class: copyable + + mc idp ldap accesskey create-with-login https://minio.example.net/ --access-key my-access-key-change-me --secret-key my-secret-key-change-me + +Create a new access-key pair that expires after 24 hours +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command creates a new access key pair to use with the currently authenticated user on the ``minio`` alias. +The credentials expire after 24 hours. + +The command outputs a randomly generated access key and secret key. + +.. code-block:: shell + :class: copyable + + mc idp ldap accesskey create-with-login https://minio.example.net --expiry-duration 24h + +Create a new access-key pair that expires after a date +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following command creates a new access key pair to use with the currently authenticated user on the ``minio`` alias. +The credentials expire after February 28, 2025. + +The command outputs a randomly generated access key and secret key. + +.. code-block:: shell + :class: copyable + + mc idp ldap accesskey create-with-login https://minio.example.net --expiry 2025-02-28 \ No newline at end of file diff --git a/source/reference/minio-mc/mc-idp-ldap-accesskey-create.rst b/source/reference/minio-mc/mc-idp-ldap-accesskey-create.rst index e65fd094..10028d2f 100644 --- a/source/reference/minio-mc/mc-idp-ldap-accesskey-create.rst +++ b/source/reference/minio-mc/mc-idp-ldap-accesskey-create.rst @@ -49,8 +49,8 @@ The :mc:`mc idp ldap accesskey create` allows you to add LDAP access key pairs. [--policy ] \ [--name ] \ [--description ] \ - [--expiry-duration ] \ - [--login ] + [--expiry ] \ + [--expiry-duration ] - Replace ``ALIAS`` with the :ref:`alias ` of a MinIO deployment configured for AD/LDAP integration. @@ -128,6 +128,10 @@ Parameters .. mc-cmd:: --login :optional: + .. deprecated:: RELEASE.2024-04-18T16-45-29Z + + Use :mc-cmd:`mc idp ldap accesskey create-with-login` to access the functionality previously provided by this parameter. + Prompts the user to log in using the LDAP credentials to use to generate the access key. Specify the URL of the LDAP-configured MinIO Server to use for the login prompt. diff --git a/source/reference/minio-mc/mc-ilm-restore.rst b/source/reference/minio-mc/mc-ilm-restore.rst index e5fffcf8..c45c5e6b 100644 --- a/source/reference/minio-mc/mc-ilm-restore.rst +++ b/source/reference/minio-mc/mc-ilm-restore.rst @@ -50,12 +50,12 @@ tier, while the temporary copy becomes ``HEAD`` for that object. .. code-block:: shell :class: copyable - mc [GLOBALFLAGS] ilm restore \ - [--days "int" ] \ - [--recursive] \ - [--vid "string"] \ - [--versions] \ - [--encrypt-key] \ + mc [GLOBALFLAGS] ilm restore \ + [--days "int" ] \ + [--recursive] \ + [--vid "string"] \ + [--versions] \ + [--enc-c "string"] \ ALIAS .. include:: /includes/common-minio-mc.rst @@ -80,6 +80,12 @@ Parameters The number of days after which MinIO expires the restored copy of the archived object. +.. block include of enc-c + +.. include:: /includes/common-minio-sse.rst + :start-after: start-minio-mc-sse-c-only + :end-before: end-minio-mc-sse-options + .. mc-cmd:: --recursive, r :optional: @@ -95,19 +101,6 @@ Parameters Restores the specified version of the object on the remote tier. -.. mc-cmd:: --encrypt-key - :optional: - - .. versionadded:: RELEASE.2023-01-28T20-29-38Z - - 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:`~mc ilm restore --encrypt-key` in double quotes ``"``. - Global Flags ~~~~~~~~~~~~ diff --git a/source/reference/minio-mc/mc-mirror.rst b/source/reference/minio-mc/mc-mirror.rst index e9249645..a18a9465 100644 --- a/source/reference/minio-mc/mc-mirror.rst +++ b/source/reference/minio-mc/mc-mirror.rst @@ -54,7 +54,9 @@ The :mc:`mc mirror` command synchronizes content to MinIO deployment, similar to [--attr "string"] \ [--disable-multipart] \ [--dry-run] \ - [--encrypt-key "string"] \ + [--enc-kms "string"] \ + [--enc-s3 "string"] \ + [--enc-c "string"] \ [--exclude "string"] \ [--exclude-bucket "string"] \ [--exclude-storageclass "string"] \ @@ -160,20 +162,11 @@ Parameters Perform a mock mirror operation. Use this operation to test that the :mc:`mc mirror` operation will only mirror the desired objects or buckets. -.. mc-cmd:: --encrypt-key - :optional: +.. block include of enc-c , enc-s3, and enc-kms - 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:``~mc mirror --encrypt-key`` in double quotes ``"``. - - :mc-cmd:`~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:`~mc mirror --encrypt-key` secret key. +.. include:: /includes/common-minio-sse.rst + :start-after: start-minio-mc-sse-options + :end-before: end-minio-mc-sse-options .. mc-cmd:: --exclude :optional: diff --git a/source/reference/minio-mc/mc-mv.rst b/source/reference/minio-mc/mc-mv.rst index f678a1bb..009ed161 100644 --- a/source/reference/minio-mc/mc-mv.rst +++ b/source/reference/minio-mc/mc-mv.rst @@ -45,10 +45,10 @@ similar results to the ``mv`` commandline tool. mc [GLOBALFLAGS] mv \ [--attr "string"] \ - [--continue] \ [--disable-multipart] \ - [--encrypt "string"] \ - [--encrypt-key "string"] \ + [--enc-kms "string"] \ + [--enc-s3 "string"] \ + [--enc-c "string"] \ [--limit-download string] \ [--limit-upload string] \ [--newer-than "string"] \ @@ -136,11 +136,6 @@ Parameters 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 - :optional: - - Create or resume a move session. - .. mc-cmd:: --disable-multipart :optional: @@ -154,39 +149,12 @@ Parameters MinIO recommends using multipart upload for any object larger than 100 MB. For more information on multipart upload, refer to the :s3-docs:`Amazon S3 documentation ` -.. mc-cmd:: --encrypt - :optional: +.. block include of enc-c , enc-s3, and enc-kms - 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). +.. include:: /includes/common-minio-sse.rst + :start-after: start-minio-mc-sse-options + :end-before: end-minio-mc-sse-options - Enclose the entire list of key-value pairs passed to - :mc-cmd:`~mc mv --encrypt` in double-quotes ``"``. - - :mc-cmd:`~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 - :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:`~mc mv --encrypt-key` in double quotes ``"``. - - :mc-cmd:`~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/linux/minio-client.rst :start-after: start-mc-limit-flags-desc @@ -367,12 +335,6 @@ Checksum Verification :mc:`mc mv` verifies all move operations to object storage using MD5SUM checksums. -Resume Move Operations -~~~~~~~~~~~~~~~~~~~~~~ - -Use :mc-cmd:`mc mv --continue` to resume an interrupted or failed -move operation from the point of failure. - MinIO Trims Empty Prefixes on Object Removal ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/minio-mc/mc-pipe.rst b/source/reference/minio-mc/mc-pipe.rst index 388039d6..bb70c0e7 100644 --- a/source/reference/minio-mc/mc-pipe.rst +++ b/source/reference/minio-mc/mc-pipe.rst @@ -39,11 +39,12 @@ The :mc:`mc pipe` command streams content from `STDIN ` 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). +.. block include of enc-c , enc-s3, and enc-kms - Enclose the entire list of key-value pairs passed to :mc-cmd:`~mc pipe --encrypt` in double-quotes ``"``. +.. include:: /includes/common-minio-sse.rst + :start-after: start-minio-mc-sse-options + :end-before: end-minio-mc-sse-options - :mc-cmd:`~mc pipe --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 - :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:`~mc pipe --encrypt-key` in double quotes ``"``. - - :mc-cmd:`~mc pipe --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:: --storage-class, --sc :optional: diff --git a/source/reference/minio-mc/mc-put.rst b/source/reference/minio-mc/mc-put.rst index 3518f550..d175a9c2 100644 --- a/source/reference/minio-mc/mc-put.rst +++ b/source/reference/minio-mc/mc-put.rst @@ -46,9 +46,9 @@ The :mc:`mc put` uploads an object from the local file system to a bucket on a t mc [GLOBALFLAGS] put \ TARGET \ - [--enc-c value] \ [--enc-kms value] \ [--enc-s3 value] \ + [--enc-c value] \ [--if-not-exists] \ [--parallel, -P integer] \ [--part-size, -s string] @@ -76,29 +76,12 @@ Parameters - ``ALIAS/BUCKET/OBJECT-NAME`` - ``ALIAS/BUCKET/PREFIX/OBJECT-NAME`` -.. mc-cmd:: --enc-c - :optional: +.. block include of enc-c , enc-s3, and enc-kms - Encrypt or decrypt objects using client provided keys. - Repeat the flag to pass multiple keys. +.. include:: /includes/common-minio-sse.rst + :start-after: start-minio-mc-sse-options + :end-before: end-minio-mc-sse-options - Keys must be in either Raw Base64 or Hex format. - -.. mc-cmd:: --enc-kms - :optional: - - Encrypt or decrypt objects using specific server-side keys. - Repeat the flag to pass multiple keys. - - Defaults to the value in the ``MC_ENC_KMS`` environment variable. - -.. mc-cmd:: --enc-s3 - :optional: - - Encrypt or decrypt objects using default server-side keys and configurations. - Repeat the flag to pass multiple keys. - - Defaults to the value in the ``MC_ENC_S3`` environment variable. .. mc-cmd:: --parallel, --P :optional: diff --git a/source/reference/minio-mc/mc-rm.rst b/source/reference/minio-mc/mc-rm.rst index 041cc8a6..3ac253a7 100644 --- a/source/reference/minio-mc/mc-rm.rst +++ b/source/reference/minio-mc/mc-rm.rst @@ -153,25 +153,6 @@ Parameters Outputs the results of a command without actually removing any files. Use this flag to test that your command configuration removes only the objects you wish to remove. -.. mc-cmd:: --encrypt-key - :optional: - - The encryption key to use for performing Server-Side Encryption - with Client Keys (SSE-C). Specify comma separated 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:`~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:: --force :optional: @@ -331,8 +312,6 @@ incomplete upload files for an object. - Replace :mc-cmd:`PATH ` with the path to the object. -Removing incomplete upload files prevents resuming the upload using the -:mc-cmd:`mc mv --continue` or :mc-cmd:`mc cp --continue` commands. Roll Object Back To Previous Version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/minio-mc/mc-sql.rst b/source/reference/minio-mc/mc-sql.rst index 643fcdc8..8abac6b7 100644 --- a/source/reference/minio-mc/mc-sql.rst +++ b/source/reference/minio-mc/mc-sql.rst @@ -45,7 +45,7 @@ See :s3-docs:`Selecting content from objects ` f [--compression "string"] \ [--csv-output "string"] \ [--csv-output-header "string"] \ - [--encrypt-key "string"] \ + [--enc-c "string"] \ [--json-input "string"] \ [--json-output "string"] \ [--recursive] \ @@ -118,19 +118,11 @@ Parameters Omit to output a ``.csv`` with no header row. -.. mc-cmd:: --encrypt-key - :optional: +.. block include of enc-c - 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:`~mc sql --encrypt-key` can use the :envvar:`MC_ENCRYPT_KEY` environment variable for populating the list of encryption key-value pairs as an alternative to specifying them on the command line. +.. include:: /includes/common-minio-sse.rst + :start-after: start-minio-mc-sse-c-only + :end-before: end-minio-mc-sse-options .. mc-cmd:: --json-input :optional: diff --git a/source/reference/minio-mc/mc-stat.rst b/source/reference/minio-mc/mc-stat.rst index cc0c2cc4..19cdd580 100644 --- a/source/reference/minio-mc/mc-stat.rst +++ b/source/reference/minio-mc/mc-stat.rst @@ -92,18 +92,16 @@ Parameters mc stat ~/data/myobject.txt -.. mc-cmd:: --enc-c - :optional: +.. block include of enc-c - Encrypt or decrypt objects using client provided keys. - Repeat the flag to pass multiple keys. - - Keys must be in either Raw Base64 or Hex format. +.. include:: /includes/common-minio-sse.rst + :start-after: start-minio-mc-sse-c-only + :end-before: end-minio-mc-sse-options .. mc-cmd:: --no-list :optional: - Disable all ``LIST`` operations if the target does not exist. + Disable all ``LIST`` operations if the target does not exist. .. mc-cmd:: --recursive, r :optional: diff --git a/source/reference/minio-mc/minio-client-settings.rst b/source/reference/minio-mc/minio-client-settings.rst index a0ad590e..dcd131ed 100644 --- a/source/reference/minio-mc/minio-client-settings.rst +++ b/source/reference/minio-mc/minio-client-settings.rst @@ -345,19 +345,19 @@ For example, to limit upload rates to no more than 1 GiB/s, use the following on Refer to your operating system instructions for equivalent commands on non-Linux systems. -Encrypt -~~~~~~~ +SSE-KMS Encryption +~~~~~~~~~~~~~~~~~~ -Encrypt and decrypt options using :ref:`server-side encryption ` with server managed keys. +Encrypt and decrypt options using :ref:`SSE-KMS ` with server managed keys. .. tab-set:: .. tab-item:: Environment Variable :selected: - .. envvar:: MC_ENCRYPT + .. envvar:: MC_ENC_KMS - Specify the key with the :envvar:`MC_ENCRYPT_KEY` environment variable. + Specify the key with the :envvar:`MC_ENC_KMS` environment variable. .. tab-item:: Configuration Setting @@ -365,18 +365,20 @@ Encrypt and decrypt options using :ref:`server-side encryption ` with server managed keys. .. tab-set:: .. tab-item:: Environment Variable :selected: - .. envvar:: MC_ENCRYPT_KEY + .. envvar:: MC_ENC_S3 + + Specify the key to use for performing SSE-S3 encryption. + The specified value must match the encryption key set in :envvar:`MINIO_KMS_KES_KEY_NAME`. .. tab-item:: Configuration Setting