From 5c574ab4b18d6a42717811527a81d63feffe94e0 Mon Sep 17 00:00:00 2001 From: ravindk89 Date: Mon, 19 Oct 2020 18:06:55 -0400 Subject: [PATCH] Cleaning up mc admin commands --- source/_static/css-style.css | 4 + source/minio-cli/minio-mc-admin.rst | 220 ++++++------------ .../minio-mc-admin/mc-admin-bucket-quota.rst | 101 ++++++-- .../minio-mc-admin/mc-admin-bucket-remote.rst | 177 ++++++++------ ...mc-admin-groups.rst => mc-admin-group.rst} | 115 ++++++++- .../minio-mc-admin/mc-admin-heal.rst | 14 +- .../minio-mc-admin/mc-admin-info.rst | 5 +- .../minio-mc-admin/mc-admin-kms-key.rst | 90 +++++++ .../minio-cli/minio-mc-admin/mc-admin-kms.rst | 51 ---- .../minio-cli/minio-mc-admin/mc-admin-obd.rst | 17 +- .../minio-mc-admin/mc-admin-profile.rst | 79 +++++-- .../minio-cli/minio-mc-admin/mc-admin-top.rst | 27 ++- .../minio-mc-admin/mc-admin-trace.rst | 14 ++ .../minio-mc-admin/mc-admin-update.rst | 10 +- .../minio-mc-admin/mc-admin-user.rst | 177 +++++++++----- 15 files changed, 698 insertions(+), 403 deletions(-) rename source/minio-cli/minio-mc-admin/{mc-admin-groups.rst => mc-admin-group.rst} (71%) create mode 100644 source/minio-cli/minio-mc-admin/mc-admin-kms-key.rst delete mode 100644 source/minio-cli/minio-mc-admin/mc-admin-kms.rst diff --git a/source/_static/css-style.css b/source/_static/css-style.css index aee39b71..5b2ff0a5 100644 --- a/source/_static/css-style.css +++ b/source/_static/css-style.css @@ -232,6 +232,10 @@ body div.center dl dd { margin-left: 15px; } +body div.center table.docutils td { + padding: 20px 10px; +} + body div.center div.footer { text-align: center; width: auto; diff --git a/source/minio-cli/minio-mc-admin.rst b/source/minio-cli/minio-mc-admin.rst index 931770fd..c36ce8db 100644 --- a/source/minio-cli/minio-mc-admin.rst +++ b/source/minio-cli/minio-mc-admin.rst @@ -29,17 +29,86 @@ The following table lists :mc-cmd:`mc admin` commands: .. list-table:: :header-rows: 1 - :widths: 25 75 + :widths: 40 60 :width: 100% * - Command - Description + * - :mc:`mc admin bucket remote` + - .. include:: /minio-cli/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:: /minio-cli/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:: /minio-cli/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:: /minio-cli/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:: /minio-cli/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:: /minio-cli/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:: /minio-cli/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:: /minio-cli/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:: /minio-cli/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:: /minio-cli/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:: /minio-cli/minio-mc-admin/mc-admin-service.rst :start-after: start-mc-admin-service-desc :end-before: end-mc-admin-service-desc + * - :mc:`mc admin top` + - .. include:: /minio-cli/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:: /minio-cli/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:: /minio-cli/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:: /minio-cli/minio-mc-admin/mc-admin-user.rst + :start-after: start-mc-admin-user-desc + :end-before: end-mc-admin-user-desc .. _mc-admin-install: @@ -76,7 +145,7 @@ Replace each argument with the required values. Specifying only the ``mc config host add`` command starts an input prompt for entering the required values. -Use the :ref:`mc admin info ` command to test the connection to +Use the :mc-cmd:`mc admin info` command to test the connection to the newly added MinIO deployment: .. code-block:: shell @@ -90,153 +159,6 @@ Global Options :mc-cmd:`mc admin` supports the same global options as :mc-cmd:`mc`. See :ref:`minio-mc-global-options`. - - -.. _mc-admin-info: - -``mc admin info`` -~~~~~~~~~~~~~~~~~ - -The ``mc admin info`` command returns diagnostic information of a MinIO server. - -The command has the following syntax: - -.. code-block:: none - - NAME: - mc admin info COMMAND - - FLAGS - --debug Returns verbose information for debugging - -If the specified ```` corresponds to a distributed MinIO deployment, the -command returns information for each MinIO server in the deployment. Use -:subcommand:`mc alias set` to list the currently configured aliases and their -corresponding endpoints. - -*Display MinIO Server Information* - -.. code-block:: shell - :class: copyable - - mc admin info myminio - -.. _mc-admin-policy: - -``mc admin policy`` -~~~~~~~~~~~~~~~~~~~ - -The ``mc admin policy`` command can add, remove, list, get info, and set -policies for a user on the MinIO server. MinIO policies are fully compatible -with AWS IAM S3 policies. See -:aws-docs:`AWS Policies and Permissions in Amazon S3 -`. - -The command has the following syntax: - -.. code-block:: none - - NAME: - mc admin policy COMMAND - - COMMANDS: - add add new policy - remove remove policy - list list all policies - info show info on a policy - set set IAM policy on a user or group - -If the specified ```` corresponds to a distributed MinIO deployment, the -command adds the policy to each MinIO server in the deployment. Use -:subcommand:`mc alias set` to list the currently configured aliases and their -corresponding endpoints. - -MinIO servers include the following canned policies: - -.. code-block:: none - - diagnostics - readonly - readwrite - writeonly - -Example: Add a new policy to a MinIO server -``````````````````````````````````````````` - -Applying the following example policy ``listbucketsonly.json`` to a user -restricts that user to only listing the top layer buckets in the MinIO server. -The user cannot list any other resources, including any objects in the top layer -buckets. - -The following operation creates the policy on the ``/tmp`` folder - -.. code-block:: shell - - cat <> /tmp/listbucketsonly.json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "s3:ListAllMyBuckets" - ], - "Resource": [ - "arn:aws:s3:::*" - ] - } - ] - } - EOF - -Use the ``mc admin policy add`` command to add the policy to the MinIO server. -Replace ```` with the alias for the desired MinIO deployment. - -.. code-block:: shell - - mc admin policy add listbucketsonly /tmp/listbucketsonly.json - -Example: Remove a policy from a MinIO Server -```````````````````````````````````````````` - -Use the ``mc admin policy remove`` command to remove a policy from the -MinIO server. - -.. todo : what happens to current users who have that policy? - -.. code-block:: shell - - mc admin policy remove listbucketsonly - -Example: Display an existing policy -``````````````````````````````````` - -Use the ``mc admin policy info`` command to retrieve policy's JSON -structure. Replace ```` with the alias for the desired MinIO deployment. - -.. code-block:: shell - - mc admin policy info writeonly - -Example: Associate a policy to a user or group -`````````````````````````````````````````````` - -Use the ``mc admin policy set`` command to set a policy to a user or -group: - -**Set policy for a user** - -.. code-block:: shell - - mc admin policy set user= - -**Set policy for a group** - -.. code-block:: shell - - mc admin policy set group= - - .. toctree:: :titlesonly: :hidden: diff --git a/source/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst b/source/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst index 8795ce23..437f5233 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst @@ -1,6 +1,6 @@ -================================== +========================= ``mc admin bucket quota`` -================================== +========================= .. default-domain:: minio @@ -71,25 +71,82 @@ specified size value: Omitting the suffix defaults to ``bytes``. +Examples +-------- -Quick Reference ---------------- +Configure a Hard Quota on a Bucket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:mc-cmd:`mc admin bucket quota play/mybucket --hard 10GB ` - Adds a hard quota of ``10GB`` to the ``mybucket`` bucket on the - MinIO deployment with the ``play`` :mc-cmd:`alias `. MinIO - rejects any ``PUT`` request that would result in the bucket exceeding - the configured quota. +Use :mc:`mc admin bucket quota` with the +:mc-cmd-option:`~mc admin bucket quota hard` flag to specify a hard quota +on a bucket. Hard quotas prevent the bucket size from growing past the specified +limit. -:mc-cmd:`mc admin bucket quota play/mybucket --fifo 10GB ` - Adds a hard quota of ``10GB`` to the ``mybucket`` bucket on the - MinIO deployment with the ``play`` :mc-cmd:`alias `. MinIO - removes the oldest objects on the bucket until it can satisfy the size - of an incoming ``PUT`` request. +.. code-block:: shell + :class: copyable -:mc-cmd:`mc admin bucket quota play/mybucket --clear ` - Removes all quotas from the ``mybucket`` bucket on the MinIO deployment - with the ``play`` :mc-cmd:`alias `. + mc admin bucket quota TARGET/BUCKET --hard LIMIT + +- Replace ``TARGET`` with the :mc-cmd:`alias ` of a configured + MinIO deployment. Replace ``BUCKET`` with the name of the bucket on which to + set the hard quota. + +- Replace ``LIMIT`` with the maximum size to which the bucket can grow. + For example, to set a hard limit of 10 Terrabytes, specify ``10t``. + See :ref:`mc-admin-bucket-quota-units` for supported units. + +Configure a First-In First-Out (FIFO) Quota on a Bucket +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc:`mc admin bucket quota` with the +:mc-cmd-option:`~mc admin bucket quota fifo` flag to specify a quota with +First-In First-Out deletion of content. FIFO quotas prevent the bucket size +from growing past the specified limit by deleting the oldest content on the +bucket to make room for newer content. + +.. code-block:: shell + :class: copyable + + mc admin bucket quota TARGET/BUCKET --fifo LIMIT + +- Replace ``TARGET`` with the :mc-cmd:`alias ` of a configured + MinIO deployment. Replace ``BUCKET`` with the name of the bucket on which to + set the quota. + +- Replace ``LIMIT`` with the maximum size to which the bucket can grow. + For example, to set a limit of 10 Terrabytes, specify ``10t``. + See :ref:`mc-admin-bucket-quota-units` for supported units. + +Retrieve Bucket Quota Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc:`mc admin bucket quota` to retrieve the current quota configuration +for a bucket: + +.. code-block:: shell + :class: copyable + + mc admin bucket quota TARGET/BUCKET + +Replace ``TARGET`` with the :mc-cmd:`alias ` of a configured +MinIO deployment. Replace ``BUCKET`` with the name of the bucket on which to +retreive the quota. + +Clear Configured Bucket Quota +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc:`mc admin bucket quota` with the +:mc-cmd-option:`~mc admin bucket quota clear` flag to clear all quotas from +a bucket. + +.. code-block:: shell + :class: copyable + + mc admin bucket quota TARGET/BUCKET --clear + +- Replace ``TARGET`` with the :mc-cmd:`alias ` of a configured + MinIO deployment. Replace ``BUCKET`` with the name of the bucket on which to + clear the quota. Syntax ------ @@ -99,7 +156,7 @@ Syntax .. code-block:: shell :class: copyable - mc admin bucket quota TARGET [FLAGS] [ARGUMENTS] + mc admin bucket quota TARGET [ARGUMENTS] :mc-cmd:`mc admin bucket quota` supports the following arguments: @@ -114,6 +171,9 @@ Syntax mc admin bucket quota play/mybucket + Omit all other arguments to return the current quota settings for the + specified bucket. + .. mc-cmd:: hard :option: @@ -129,8 +189,9 @@ Syntax .. mc-cmd:: fifo :option: - Sets a limit to the bucket storage size after which MinIO removes the oldest - objects in the bucket until the bucket size drops below the specified limit. + Sets a maximum limit to the bucket storage size. The MinIO server removes + the oldest objects in the bucket to make space for newer objects such that + the bucket size remains below the specified limit. For example, a ``fifo`` limit of ``10GB`` would result in removal of the oldest objects in the bucket once it reaches ``10GB`` in size. diff --git a/source/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst b/source/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst index 07d3d4f9..cc0e7f3d 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst @@ -13,15 +13,12 @@ Description ----------- -.. start-mc-admin-bucket remote-desc +.. start-mc-admin-bucket-remote-desc -The :mc-cmd:`mc admin bucket remote` command manages remote targets for -supporting bucket replication. +The :mc-cmd:`mc admin bucket remote` command manages the ``ARN`` resources +for use with :mc-cmd:`bucket replication `. -.. end-mc-admin-bucket remote-desc - -:mc-cmd:`mc admin bucket remote` creates the required ``ARN`` resource for -use with :mc-cmd:`mc replicate`. +.. end-mc-admin-bucket-remote-desc .. admonition:: Use ``mc admin`` on MinIO Deployments Only :class: note @@ -30,68 +27,88 @@ use with :mc-cmd:`mc replicate`. :start-after: start-minio-only :end-before: end-minio-only -MinIO Deployments Only -~~~~~~~~~~~~~~~~~~~~~~ +Examples +-------- -:mc-cmd:`mc admin bucket remote` only supports MinIO deployments for the source -and target. MinIO provides no support or guarantees for other S3-compatible -services. +Add a New Replication Target +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Quick Reference ---------------- - -:mc-cmd:`mc admin bucket remote add play/mybucket target/mybucket ` - Adds a new remote target ``target/mybucket`` to ``play/mybucket``, - where ``target`` and ``play`` are :mc-cmd:`aliases ` for - configured MinIO deployments. - - The command returns an ``ARN`` associated to the configured target. - :mc-cmd:`mc replicate` requires the ``ARN`` to enable replication - from a source bucket to a destination deployment and bucket. - -:mc-cmd:`mc admin bucket remote ls play/mybucket ` - Lists all remote targets for ``play/mybucket``, where - ``play`` is a :mc-cmd:`alias ` for a configured MinIO deployment. - - The command returns an ``ARN`` associated to each configured remote target. - :mc-cmd:`mc replicate` requires the ``ARN`` to enable replication - from a source bucket to a destination deployment and bucket. - -:mc-cmd:`mc admin bucket remote rm play/mybucket target/mybucket ` - Removes the remote target ``target/mybucket`` from ``play/mybucket``, - where ``target`` and ``play`` are :mc-cmd:`aliases ` for - configured MinIO deployments. - - Removing a remote target halts any in-progress bucket replication - relying on that remote target's ARN. - -Syntax ------- - -:mc-cmd:`mc admin bucket remote` has the following syntax: +Use :mc-cmd:`mc admin bucket remote add` to create a new replication target +ARN for use with :mc-cmd:`mc replicate`: .. code-block:: shell :class: copyable - mc admin bucket remote SUBCOMMAND [ARGUMENTS] + mc admin bucket remote add TARGET/BUCKET SOURCE/BUCKET -:mc-cmd:`mc admin bucket remote` supports the following subcommands: +- Replace :mc-cmd:`TARGET ` with the + :mc-cmd:`alias ` of the MinIO deployment to use as the replication + target. Replace ``BUCKET`` with the full path of the bucket into which MinIO + replicates objects from the ``SOURCE``. + +- Replace :mc-cmd:`SOURCE ` with the + :mc-cmd:`alias ` of the MinIO deployment to use as the + replication source. Replace ``BUCKET`` with the full path of the bucket from + which MinIO replicates objects into the ``TARGET``. + +Remove an Existing Replication Target +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin bucket remote rm` to remove a replication target from a +bucket: + +.. code-block:: shell + :class: copyable + + mc admin bucket remote rm SOURCE/BUCKET --arn ARN + +- Replace :mc-cmd:`SOURCE ` with the + :mc-cmd:`alias ` of the MinIO deployment being used as the + replication source. Replace ``BUCKET`` with the full path of the bucket from + which MinIO replicates objects. + +- Replace :mc-cmd:`ARN ` with the + ARN of the remote target. + +Removing the target halts all in-progress +:mc-cmd:`bucket replication ` to the target. + +Retrieve Configured Replication Targets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin bucket remote ls` to list a bucket's configured +replication targets: + +.. code-block:: shell + :class: copyable + + mc admin bucket remote ls SOURCE/BUCKET + +- Replace :mc-cmd:`SOURCE ` with the + :mc-cmd:`alias ` of the MinIO deployment being used as the + replication source. Replace ``BUCKET`` with the full path of the bucket from + which MinIO replicates objects. + +Syntax +------ .. mc-cmd:: add :fullpath: - Adds a remote target to a bucket on the MinIO deployment. The + Adds a remote target to a bucket on a MinIO deployment. The command has the following syntax: .. code-block:: shell :class: copyable - mc admin bucket add TARGET DESTINATION --service "replication" [ARGUMENTS] + mc admin bucket add TARGET DESTINATION --service "replication" [FLAGS] The command accepts the following arguments: .. mc-cmd:: TARGET + *Required* + The full path to the bucket to which the command adds the remote target. Specify the :mc-cmd:`alias ` of a configured MinIO deployment as the prefix to the bucket path. For example: @@ -103,52 +120,46 @@ Syntax .. mc-cmd:: DESTINATION - The target MinIO deployment and bucket. Specify one of the two - following formats: + *Required* - .. tabs:: + The target MinIO deployment and bucket. - .. tab:: ``alias/bucket`` + Specify the full URL to the destination MinIO deployment and bucket + using the following format: - Specify the :mc-cmd:`alias ` of a configured MinIO - deployment as the prefix and destination bucket name as the suffix - using a forward slash ``/`` as a delimiter: + .. code-block:: shell + :class: copyable - .. code-block:: shell - :class: copyable + http(s)://ACCESSKEY:SECRETKEY@DESTHOSTNAME/DESTBUCKET - / + - Replace ``ACCESSKEY`` with the access key for a user on the + destination MinIO deployment. - .. tab:: URL + - Replace ``SECRETKEY`` with the secret key for a user on the + destination MinIO deployment. - Specify the full URL to the destination MinIO deployment and bucket - using the following format: + - Replace ``DESTHOSTNAME`` with the hostname and port of the MinIO + deployment (i.e. ``minio-server.example.net:9000``). - .. code-block:: shell - :class: copyable + - Replace ``DESTBUCKET`` with the bucket on the + destination. - http(s)://ACCESSKEY:SECRETKEY@DESTHOSTNAME/DESTBUCKET + .. mc-cmd:: service + :option: - - Replace ``ACCESSKEY`` with the access key for a user on the - destination MinIO deployment. + *Required* - - Replace ``SECRETKEY`` with the secret key for a user on the - destination MinIO deployment. - - - Replace ``DESTHOSTNAME`` with the hostname and port of the MinIO - deployment (i.e. ``minio-server.example.net:9000``). - - - Replace ``DESTBUCKET`` with the bucket on the - destination. + Specify ``"replication"``. .. mc-cmd:: region :option: The region of the :mc-cmd:`~mc admin bucket remote DESTINATION`. - Mutually exclusive with :mc-cmd-option:`~mc admin bucket remote path` + Mutually exclusive with :mc-cmd-option:`~mc admin bucket remote add path` .. mc-cmd:: path + :option: The bucket path lookup supported by the destination server. Specify one of the following: @@ -157,7 +168,8 @@ Syntax - ``off`` - ``auto`` (Default) - Mutually exclusive with :mc-cmd-option:`~mc admin bucket remote region` + Mutually exclusive with + :mc-cmd-option:`~mc admin bucket remote add region` .. mc-cmd:: ls :fullpath: @@ -183,6 +195,13 @@ Syntax mc admin bucket ls play/mybucket + .. mc-cmd:: service + :option: + + *Required* + + Specify ``"replication"``. + .. mc-cmd:: rm :fullpath: @@ -193,12 +212,14 @@ Syntax .. code-block:: shell :class: copyable - mc admin bucket rm TARGET --arn + mc admin bucket rm TARGET --arn ARN The command accepts the following arguments: .. mc-cmd:: TARGET + *Required* + The full path to the bucket for which the command . Specify the :mc-cmd:`alias ` of a configured MinIO deployment as the prefix to the bucket path. For example: @@ -211,6 +232,8 @@ Syntax .. mc-cmd:: ARN :option: + *Required* + The ``ARN`` of the remote target for which the command removes from the target bucket. Use :mc-cmd:`mc admin bucket ls` to list all remote targets and their associated ARNs for a specific bucket. diff --git a/source/minio-cli/minio-mc-admin/mc-admin-groups.rst b/source/minio-cli/minio-mc-admin/mc-admin-group.rst similarity index 71% rename from source/minio-cli/minio-mc-admin/mc-admin-groups.rst rename to source/minio-cli/minio-mc-admin/mc-admin-group.rst index 6f1d9742..d5b7c02b 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-groups.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-group.rst @@ -13,11 +13,11 @@ Description ----------- -.. start-mc-admin-groups-desc +.. start-mc-admin-group-desc The :mc-cmd:`mc admin group` command manages groups on a MinIO deployment. -.. end-mc-admin-groups-desc +.. end-mc-admin-group-desc A :ref:`group ` is a collection of :ref:`users `. Each group can have one or more assigned @@ -66,6 +66,113 @@ more information on MinIO policies, see :ref:`minio-policy`. :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account `. +Examples +-------- + +Create a New Group +~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin group add` to create a new group to an S3-compatible host: + +.. code-block:: shell + :class: copyable + + mc admin group add ALIAS GROUPNAME MEMBER [MEMBER...] + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`GROUPNAME ` with the name + of the group to create. + +- Replace :mc-cmd:`MEMBER ` with *at least* one + :mc-cmd:`user ` on the S3 host. Specify multiple members + as a list: ``MEMBER1 MEMBER2 MEMBER3`` + +List Available Groups +~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin group list` to list list all groups on an S3-compatible +host: + +.. code-block:: shell + :class: copyable + + mc admin group list ALIAS + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the S3-compatible host. + + +View Group Details +~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin group info` to view detailed group information on an +S3-compatible host: + +.. code-block:: shell + :class: copyable + + mc admin group info ALIAS GROUPNAME + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`GROUPNAME ` with the name of + the group. + +Remove a Group +~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin group remove` to remove a group from an S3-compatible +host: + +.. code-block:: shell + :class: copyable + + mc admin group remove ALIAS GROUPNAME + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`GROUPNAME ` with the + name of the group. + +Disable a Group +~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin group disable` to disable a group on an S3-compatible +host: + +.. code-block:: shell + :class: copyable + + mc admin group disable ALIAS GROUPNAME + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`GROUPNAME ` with the name + of the group. + +Enable a Group +~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin group enable` to enable a group on an S3-compatible +host: + +.. code-block:: shell + :class: copyable + + mc admin group enable ALIAS GROUPNAME + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`GROUPNAME ` with the name + of the group. + + Quick Reference --------------- @@ -192,7 +299,7 @@ Syntax The name of the group to remove. -.. mc-cmd:: mc admin group enable +.. mc-cmd:: enable :fullpath: Enables the group on the target MinIO deployment. Users can only inherit @@ -216,7 +323,7 @@ Syntax The name of the group to enable. -.. mc-cmd:: mc admin group disable +.. mc-cmd:: disable :fullpath: Disables the group on the target MinIO deployment. Users cannot inherit diff --git a/source/minio-cli/minio-mc-admin/mc-admin-heal.rst b/source/minio-cli/minio-mc-admin/mc-admin-heal.rst index 84f9af8d..abd2056e 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-heal.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-heal.rst @@ -15,16 +15,16 @@ Description .. start-mc-admin-heal-desc -The :mc-cmd:`mc admin heal` command scans for objects that are damaged or +The :mc:`mc admin heal` command scans for objects that are damaged or corrupted and heals those objects. -:mc-cmd:`mc admin heal` is resource intensive and typically not required even +.. end-mc-admin-heal-desc + +:mc:`mc admin heal` is resource intensive and typically not required even after disk failures or corruption events. Instead, MinIO automatically heals objects damaged by silent bitrot corruption, disk failure, or other issues on POST/GET. MinIO also performs periodic background object healing. -.. end-mc-admin-heal-desc - .. admonition:: Use ``mc admin`` on MinIO Deployments Only :class: note @@ -35,17 +35,19 @@ POST/GET. MinIO also performs periodic background object healing. Syntax ------ -:mc-cmd:`mc admin heal` has the following syntax: +:mc:`mc admin heal` has the following syntax: .. code-block:: shell :class: copyable mc admin heal [FLAGS] TARGET -:mc-cmd:`mc admin heal` supports the following arguments: +:mc:`mc admin heal` supports the following arguments: .. mc-cmd:: TARGET + *Required* + The full path to the bucket or bucket prefix on which the command should perform object healing. Specify the :mc-cmd:`alias ` of a configured MinIO deployment as the prefix for the path. For example: diff --git a/source/minio-cli/minio-mc-admin/mc-admin-info.rst b/source/minio-cli/minio-mc-admin/mc-admin-info.rst index 3fac1686..0f883bfd 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-info.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-info.rst @@ -15,7 +15,7 @@ Description .. start-mc-admin-info-desc -The :mc-cmd:`mc admin info` command displays information on a MinIO server. +The :mc:`mc admin info` command displays information on a MinIO server. For distributed MinIO deployments, :mc:`mc admin info` displays information for each MinIO server in the deployment. @@ -44,5 +44,4 @@ Syntax mc admin info TARGET Specify the :mc-cmd:`alias ` of a configured MinIO deployment as the -``TARGET``. :mc-cmd:`~mc admin service restart` restarts *all* MinIO servers in -the deployment. \ No newline at end of file +``TARGET``. \ No newline at end of file diff --git a/source/minio-cli/minio-mc-admin/mc-admin-kms-key.rst b/source/minio-cli/minio-mc-admin/mc-admin-kms-key.rst new file mode 100644 index 00000000..cce2e011 --- /dev/null +++ b/source/minio-cli/minio-mc-admin/mc-admin-kms-key.rst @@ -0,0 +1,90 @@ +==================== +``mc admin kms key`` +==================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +.. mc:: mc admin kms key + +Description +----------- + +.. start-mc-admin-kms-key-desc + +The :mc-cmd:`mc admin kms key` command performs cryptographic key management +operations through the MinIO Key Encryption Service (KES). + +.. end-mc-admin-kms-key-desc + +.. admonition:: Use ``mc admin`` on MinIO Deployments Only + :class: note + + .. include:: /includes/facts-mc-admin.rst + :start-after: start-minio-only + :end-before: end-minio-only + +.. TODO + + Return to this section as part of the KES documentation. There's a lot here + that only makes sense once we can link to KES overview + config. + +Syntax +------ + +.. mc-cmd:: create + :fullpath: + + + Creates a new master key on a Key Management System (KMS). + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc admin kms key create TARGET [KEY_NAME] + + The command accepts the following arguments: + + .. mc-cmd:: TARGET + + Specify the :mc-cmd:`alias ` of a configured MinIO deployment. + + The ``TARGET`` deployment **must** include a configured + MinIO Key Encryption Service (KES) server. + + .. mc-cmd:: KEY_NAME + + Specify the name of the new master key. + +.. mc-cmd:: status + :fullpath: + + Requests information on a Key Management System (KMS) master key. + + The command has the following syntax: + + .. code-block:: shell + :class: copyable + + mc admin kms key status TARGET [KEY_NAME] + + The command accepts the following arguments: + + .. mc-cmd:: TARGET + + Specify the :mc-cmd:`alias ` of a configured MinIO deployment. + + The ``TARGET`` deployment **must** include a configured MinIO Key + Encryption Service (KES) server. + + .. mc-cmd:: KEY_NAME + + Specify the name of a master key on the KMS. + + Omit this argument to return the default master key on the + :mc-cmd:`~mc admin kms key status TARGET` deployment. \ No newline at end of file diff --git a/source/minio-cli/minio-mc-admin/mc-admin-kms.rst b/source/minio-cli/minio-mc-admin/mc-admin-kms.rst deleted file mode 100644 index 3df451a6..00000000 --- a/source/minio-cli/minio-mc-admin/mc-admin-kms.rst +++ /dev/null @@ -1,51 +0,0 @@ -================ -``mc admin kms`` -================ - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. mc:: mc admin kms - -Description ------------ - -.. start-mc-admin-kms-desc - -The :mc-cmd:`mc admin kms` command performs management operations on -a supported Key Management Service (KMS). - -.. end-mc-admin-kms-desc - -.. admonition:: Use ``mc admin`` on MinIO Deployments Only - :class: note - - .. include:: /includes/facts-mc-admin.rst - :start-after: start-minio-only - :end-before: end-minio-only - - -Syntax ------- - -:mc-cmd:`mc admin kms` has the following syntax: - -.. code-block:: shell - :class: copyable - - mc admin kms key status TARGET KEYNAME - -:mc-cmd:`mc admin kms` supports the following: - -.. mc-cmd:: TARGET - - The :mc-cmd:`alias ` of a configured MinIO server from which - the command returns the KMS status. - -.. mc-cmd:: KEYNAME - - The name of the speciific key to return. - diff --git a/source/minio-cli/minio-mc-admin/mc-admin-obd.rst b/source/minio-cli/minio-mc-admin/mc-admin-obd.rst index 9cec6039..9c920b70 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-obd.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-obd.rst @@ -15,14 +15,23 @@ Description .. start-mc-admin-obd-desc -The :mc-cmd:`mc admin obd` command generates detailed diagnostics for the +The :mc:`mc admin obd` command generates detailed diagnostics for the target MinIO deployment as a ``GZIP`` compressed ``JSON`` file. MinIO Support -may request the output of :mc-cmd:`mc admin obd` as part of troubleshooting +may request the output of :mc:`mc admin obd` as part of troubleshooting and diagnostics. .. end-mc-admin-obd-desc -The :mc-cmd:`mc admin odb` output may contain sensitive information about your +:mc:`mc admin odb` names the file using the following pattern: + +.. code-block:: none + + alias-health_YYYYMMDDHHMMSS.json.gzip + +The ``alias`` is the :mc-cmd:`~mc admin obd TARGET` MinIO deployment from which +:mc:`mc admin odb` returned the diagnostics. + +The :mc:`mc admin odb` output may contain sensitive information about your environment. Exercise all possible precautions, such as redacting sensitive fields, prior to sharing the data on any public forum. @@ -47,6 +56,8 @@ Syntax .. mc-cmd:: TARGET + *Required* + The :mc-cmd:`alias ` of a configured MinIO deployment from which the command retrieves the diagnostic data. diff --git a/source/minio-cli/minio-mc-admin/mc-admin-profile.rst b/source/minio-cli/minio-mc-admin/mc-admin-profile.rst index a3859b28..504120fa 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-profile.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-profile.rst @@ -20,11 +20,6 @@ purposes. .. end-mc-admin-profile-desc -:mc-cmd:`mc admin profile` produces a ``ZIP`` archive ``profile.zip`` that -contains one or more ``.pprof`` files. Use the -`pprof `__ ``go`` utility to read the -profile data. - .. admonition:: Use ``mc admin`` on MinIO Deployments Only :class: note @@ -32,20 +27,72 @@ profile data. :start-after: start-minio-only :end-before: end-minio-only -Quick Reference ---------------- +Profile Data Format +~~~~~~~~~~~~~~~~~~~ -:mc-cmd:`mc admin profile start --type cpu myminio/ ` - Starts profiling data related to ``cpu`` statistics - on the ``myminio`` :mc-cmd:`alias `. +:mc-cmd:`mc admin profile` produces a ``ZIP`` archive ``profile.zip`` that +contains one or more ``.pprof`` files. Use the +`pprof `__ ``go`` utility to read the +profile data. -:mc-cmd:`mc admin profile start --type "cpu,mem,block" myminio/ ` - Starts profiling data related to ``cpu``, ``mem``, and ``block`` statistics - on the ``myminio`` :mc-cmd:`alias `. +Examples +-------- -:mc-cmd:`mc admin profile stop myminio/ ` - Stops profiling data on the ``myminio`` :mc-cmd:`alias ` and - dumps the recorded data to ``profile.zip``. +Profile Data for Single Resource +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin profile start` with the +:mc-cmd-option:`~mc admin profile start type` flag to start profiling the +resource: + +.. code-block:: shell + :class: copyable + + mc admin profile start --type "TYPE" ALIAS + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the MinIO host. + +- Replace :mc-cmd:`TYPE ` with the resource to + profile. + +Use :mc-cmd:`mc admin profile stop` to stop profiling data from the specified +resource and output the results: + +.. code-block:: shell + :class: copyable + + mc admin profile stop + +The command outputs the profiled data as ``profile.zip``. + +Profile Data for Multiple Resources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin profile start` with the +:mc-cmd-option:`~mc admin profile start type` flag to start profiling the +resources: + +.. code-block:: shell + :class: copyable + + mc admin profile start --type "TYPE,[TYPE...]" ALIAS + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the MinIO host. + +- Replace :mc-cmd:`TYPE ` with the resources to + profile. Specify multiple resources as a comma-separated list. + +Use :mc-cmd:`mc admin profile stop` to stop profiling data from the specified +resources and output the results: + +.. code-block:: shell + :class: copyable + + mc admin profile stop + +The command outputs the profiled data as ``profile.zip``. Syntax ------ diff --git a/source/minio-cli/minio-mc-admin/mc-admin-top.rst b/source/minio-cli/minio-mc-admin/mc-admin-top.rst index 0c59662b..682a2088 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-top.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-top.rst @@ -33,22 +33,27 @@ or MinIO Gateway deployments. Syntax ------ -:mc-cmd:`mc admin top` has the following syntax: +.. mc-cmd:: locks + :fullpath: -.. code-block:: shell - :class: copyable + Returns the 10 oldest locks on the MinIO deployment. - mc admin top lock TARGET + The command has the following syntax: -The command supports the following arguments: + .. code-block:: shell + :class: copyable -.. mc-cmd:: TARGET + mc admin top locks TARGET - The :mc-cmd:`alias ` of a configured MinIO deployment from which - the command retrieves statistics. + The command supports the following arguments: - The alias *must* correspond to a distributed (multi-node) MinIO deployment. - The command returns an error for standalone MinIO deployments or MinIO - Gateway deployments. + .. mc-cmd:: TARGET + + The :mc-cmd:`alias ` of a configured MinIO deployment from which + the command retrieves statistics. + + The alias *must* correspond to a distributed (multi-node) MinIO deployment. + The command returns an error for standalone MinIO deployments or MinIO + Gateway deployments. diff --git a/source/minio-cli/minio-mc-admin/mc-admin-trace.rst b/source/minio-cli/minio-mc-admin/mc-admin-trace.rst index 84ac0156..5f785f81 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-trace.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-trace.rst @@ -28,6 +28,20 @@ request against each MinIO server in a deployment. :start-after: start-minio-only :end-before: end-minio-only +Example +------- + +Use :mc:`mc admin trace` to perform an HTTP trace of each MinIO server in +the deployment: + +.. code-block:: shell + :class: copyable + + mc admin trace ALIAS + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the MinIO deployment. + Syntax ------ diff --git a/source/minio-cli/minio-mc-admin/mc-admin-update.rst b/source/minio-cli/minio-mc-admin/mc-admin-update.rst index f45e130c..632a45c7 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-update.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-update.rst @@ -36,14 +36,16 @@ production environments. Examples -------- -.. include:: /includes/play-alias-available.rst - :start-after: myminio-alias - :end-before: end-myminio-alias +Use :mc:`mc admin update` to update each :mc:`minio` server process in the +MinIO deployment: .. code-block:: shell :class: copyable - mc admin update myminio + mc admin update ALIAS + +Replace :mc-cmd:`ALIAS ` with the +:mc-cmd:`alias ` of the MinIO deployment. Syntax ------ diff --git a/source/minio-cli/minio-mc-admin/mc-admin-user.rst b/source/minio-cli/minio-mc-admin/mc-admin-user.rst index 7e8ccb69..53a53116 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-user.rst +++ b/source/minio-cli/minio-mc-admin/mc-admin-user.rst @@ -15,13 +15,13 @@ Description .. start-mc-admin-user-desc -The :mc-cmd:`mc admin user` command manages users on a MinIO deployment. +The :mc-cmd:`mc admin user` command manages users on a MinIO deployment. Clients +*must* authenticate to the MinIO deployment with the access key and secret key +associated to a user on the deployment. MinIO users constitue a key component in +MinIO Identity and Access Management. .. end-mc-admin-user-desc -Clients authenticate to the MinIO deployment with the access key and secret key -associated to a user on the deployment. - .. admonition:: Use ``mc admin`` on MinIO Deployments Only :class: note @@ -72,68 +72,124 @@ more information on MinIO policies, see :ref:`minio-policy`. :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account `. -Quick Reference ---------------- +Examples +-------- -:mc-cmd:`mc admin user add TARGET ACCESSKEY SECRETKEY ` - Adds a new user to a MinIO deployment. +Create a New User +~~~~~~~~~~~~~~~~~ - .. code-block:: shell - :class: copyable - - mc admin user add play myNewUser myNewUserSecretKey - -:mc-cmd:`mc admin user list TARGET ` - Lists all users on a MinIO deployment. - - .. code-block:: shell - :class: copyable - - mc admin user list play - -:mc-cmd:`mc admin user info TARGET USERNAME ` - Returns detailed information for a user on a MinIO deployment. - - .. code-block:: shell - :class: copyable - - mc admin user info play myNewUser - -:mc-cmd:`mc admin user remove TARGET USERNAME ` - Removes a user from a MinIO deployment. - - .. code-block:: shell - :class: copyable - - mc admin user remove play myNewUser - -:mc-cmd:`mc admin user enable TARGET USERNAME ` - Enables a user on a MinIO deployment. - - .. code-block:: shell - :class: copyable - - mc admin user enable play myNewUser - -:mc-cmd:`mc admin user disable TARGET USERNAME ` - Disables a user on a MinIO deployment. - - .. code-block:: shell - :class: copyable - - mc admin user disable play myNewUser - -Syntax ------- - -:mc-cmd:`mc admin user` has the following syntax: +Use :mc-cmd:`mc admin user add` to create a user on an S3-compatible host: .. code-block:: shell :class: copyable - mc admin user SUBCOMMAND + mc admin user add ALIAS ACCESSKEY SECRETKEY -:mc-cmd:`mc admin user` supports the following subcommands: +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`ACCESSKEY ` with the + access key for the user. MinIO allows retrieving the access key after + user creation through the :mc-cmd:`mc admin user info` command. + +- Replace :mc-cmd:`SECRETKEY ` with the + secret key for the user. MinIO *does not* provide any method for retrieving + the secret key once set. + +Specify a unique, random, and long string for both the ``ACCESSKEY`` and +``SECRETKEY``. Your organization may have specific internal or regulatory +requirements around generating values for use with access or secret keys. + +List Available Users +~~~~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin user list` to list all users on an S3-compatible host: + +.. code-block:: shell + :class: copyable + + mc admin user list ALIAS + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the S3-compatible host. + +:mc-cmd:`mc admin user list` does *not* return the access key or secret key +associated to a user. Use :mc-cmd:`mc admin user info` to retrieve detailed +user information, including the user access key. + +View User Details +~~~~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin user info` to view detailed user information on an +S3-compatible host: + +.. code-block:: shell + :class: copyable + + mc admin user info ALIAS USERNAME + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`USERNAME ` with the name of + the user. + +Remove a User +~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin user remove` to remove a user from an S3-compatible host: + +.. code-block:: shell + :class: copyable + + mc admin user remove ALIAS USERNAME + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`USERNAME ` with the name of + the user to remove. + +Disable a User +~~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin user disable` to disable a user on an S3-compatible host. +Disabling a user prevents clients from authenticating to the S3 host with that +user's credentials, but does *not* remove that user from the S3 host. + +Use :mc-cmd:`mc admin user enable` to enable a disabled user on an S3-compatible +host. + +.. code-block:: shell + :class: copyable + + mc admin user disable ALIAS USERNAME + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`USERNAME ` with the name of + the user to disable. + +Enable a User +~~~~~~~~~~~~~ + +Use :mc-cmd:`mc admin user enable` to enable a user on an S3-compatible +host. + +.. code-block:: shell + :class: copyable + + mc admin user enable ALIAS USERNAME + +- Replace :mc-cmd:`ALIAS ` with the + :mc-cmd:`alias ` of the S3-compatible host. + +- Replace :mc-cmd:`USERNAME ` with the name of + the user to enable. + +Syntax +------ .. mc-cmd:: add :fullpath: @@ -187,6 +243,7 @@ Syntax the command lists users. .. mc-cmd:: info + :fullpath: Returns detailed information of a user on the target MinIO deployment. The command has the following syntax: @@ -231,6 +288,7 @@ Syntax the user to remove. .. mc-cmd:: disable + :fullpath: Disables a user on the target MinIO deployment. Clients cannot use the user credentials to authenticate to the MinIO deployment. Disabling @@ -256,6 +314,7 @@ Syntax the user to disable. .. mc-cmd:: enable + :fullpath: Enables a user on the target deployment. Clients can only use enabled users to authenticate to the MinIO deployment. Users created using