Trying new page structure. See mc-admin-policy

CONTRIBUTIONS.md

@@ -0,0 +1,82 @@
+
+# Contributors License Agreement
+
+
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when
+an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official
+project e-mail address, posting via an official social media account, or acting
+as an appointed representative at an online or offline event. Representation of
+a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at docs@min.io. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see
+https://www.contributor-covenant.org/faq
+

source/_static/css-style.css

@@ -78,6 +78,10 @@ div.document {
     top: 75px;
 }
 
+div.section code {
+   color: #c72e49;
+}
+
 div.topic {
     background-color: #edf7f71A;
 }
@@ -98,19 +102,30 @@ div.localtoc ul {
 }
 
 div.localtoc ul li {
-   padding: 2px 0px;
+   transition: all 10ms ease-in-out;
-   transition: all 50ms ease-in-out;
 }
 
-div.localtoc ul li.active {
+/* div.localtoc ul li.active {
    color: #c72e49;
+   list-style: square;
+   position: relative;
+   border-left: 5px solid #c72e49;
+   padding-left: 5px;
+   margin-left: -10px;
+} */
+
+div.localtoc ul li p {
+   padding-top: 3px;
+   padding-bottom: 3px;
+}
+
+div.localtoc ul li p.active-p {
    position: relative;
    border-left: 5px solid #c72e49;
    padding-left: 5px;
    margin-left: -10px;
 }
 
-
 div.body a {
     color: #c72e49;
     text-decoration: none;

source/_static/js/main.js

@@ -11,9 +11,15 @@ window.addEventListener('DOMContentLoaded', (event) => {
       console.log("moving local toc");
    }
 
+
+   // There's probably a better way to refine what sections are shown on screen.
+   // Experimenting with setting the `intersectionRatio` and such tends to stop
+   // this from working, especially if the 'section' is really long. Not sure
+   // how to resolve that.
+
    let options = {
       root: document.querySelector('#scrollArea'),
-      rootMargin: '-100px 0px 0px 0px'
+      rootMargin: '-150px 0px -300px 0px'
    }
 
    const observer = new IntersectionObserver(entries => {
@@ -26,20 +32,25 @@ window.addEventListener('DOMContentLoaded', (event) => {
             return 0
           if (entry.intersectionRatio > 0) {
               
+
+              pElement = document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement;
               liElement = document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement.parentElement;
               
               liElement.classList.add('active');
+              pElement.classList.add('active-p');
 
               liElementParent = liElement.parentElement.parentElement
 
               if (liElementParent.tagName == "LI") {
-                 liElementParent.classList.remove("active")
+                 //liElementParent.classList.remove("active")
+                 // Need to re-visit this logic
               }
 
               
 
           } else {
               document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement.parentElement.classList.remove('active');
+              document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement.classList.remove('active-p');
           }
       });
   },options);

source/conf.py

@@ -59,6 +59,7 @@ extlinks = {
     's3-api'    : ('https://docs.aws.amazon.com/AmazonS3/latest/API/%s',''),
     'iam-docs'  : ('https://docs.aws.amazon.com/IAM/latest/UserGuide/%s',''),
     'release'   : ('https://github.com/minio/mc/releases/tag/%s',''),
+    'legacy'    : ('https://docs.min.io/docs/%s',''),
 }
 
 # Add any paths that contain templates here, relative to this directory.

source/images/Kubernetes-Minio.svg

@@ -698,7 +698,7 @@
 </tspan></tspan><tspan
              x="99.629028"
              y="347.77352"><tspan
-               style="shape-inside:url(#rect1738-25-1)">MinIo Console Server</tspan></tspan></text>
+               style="shape-inside:url(#rect1738-25-1)">MinIO Console Server</tspan></tspan></text>
       </g>
       <g
          id="g1477">

source/includes/facts-mc-admin.rst

@@ -0,0 +1,7 @@
+start-minio-only
+
+MinIO does not support using :mc-cmd:`mc admin` commands with other
+S3-compatible services, regardless of their claimed compatibility with MinIO
+deployments.
+
+end-minio-only

source/includes/minio-mc-installation.rst

@@ -82,12 +82,12 @@
 
    .. tab:: Source
 
-      Source installation is intended for developers and advanced users. The
+      Installation from source is intended for developers and advanced users
-      :mc-cmd:`mc admin update` command does not support updating source-based
+      and requires a working Golang environment. See 
-      installations.
+      `How to install Golang <https://golang.org/doc/install>`__.
 
-      Source installation requires a working Golang environment. 
+      Run the following commands in a terminal environment to install ``mc``
-      See `How to install Golang <https://golang.org/doc/install>`__
+      from source:
 
       .. code-block:: shell
          :class: copyable
@@ -96,17 +96,7 @@
          cd ${GOPATH}/src/github.com/minio/mc
          make
 
-:command:`mc` includes the https://play.min.io MinIO server for testing
+      To update a source-based installation, use ``go get -u``. 
-and development under the ``play`` alias. If the host machine has access to
+      :mc-cmd:`mc update` does not support source-based installations.
-the public internet, you can use the ``play`` alias for testing and development
-purposes. For example, the following lists all buckets on 
-``https://play.min.io``:
 
-.. code-block:: shell
-   :class: copyable
 
-   mc ls play
-
-The ``play`` alias is strictly for testing and development. Any S3-compatible
-tool can view and interact with data on ``play``. You should only store data on
-``play`` that is safe for public interaction. 

source/minio-cli/minio-mc-admin.rst

@@ -35,8 +35,10 @@ The following table lists :mc-cmd:`mc admin` commands:
    * - Command
      - Description
 
-   * - :mc:`mc service`
+   * - :mc:`mc admin service`
-     - Restart or stop MinIO servers. 
+     - .. 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-admin-install:

source/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst

@@ -0,0 +1,146 @@
+==================================
+``mc admin bucket quota``
+==================================
+
+.. default-domain:: minio
+
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
+.. mc:: mc admin bucket quota
+
+Description
+-----------
+
+.. start-mc-admin-bucket-quota-desc
+
+The :mc-cmd:`mc admin bucket quota` command manages per-bucket
+storage quotas.
+
+.. end-mc-admin-bucket-quota-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
+
+.. _mc-admin-bucket-quota-units:
+
+Units of Measurement
+~~~~~~~~~~~~~~~~~~~~
+
+The :mc-cmd-option:`mc admin bucket quota hard` and 
+:mc-cmd-option:`mc admin bucket quota fifo` flags
+accept the following case-insensitive suffixes to represent the unit of the
+specified size value:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+   :width: 100%
+
+   * - Suffix
+     - Unit Size
+
+   * - ``k``
+     - KB (Kilobyte, 1000 Bytes)
+
+   * - ``m``
+     - MB (Megabyte, 1000 Kilobytes)
+
+   * - ``g``
+     - GB (Gigabyte, 1000 Megabytes)
+
+   * - ``t``
+     - TB (Terrabyte, 1000 Gigabytes)
+
+   * - ``ki``
+     - KiB (Kibibyte, 1024 Bites)
+
+   * - ``mi``
+     - MiB (Mebibyte, 1024 Kibibytes)
+
+   * - ``gi``
+     - GiB (Gibibyte, 1024 Mebibytes)
+
+   * - ``ti``
+     - TiB (Tebibyte, 1024 Gibibytes)
+
+Omitting the suffix defaults to ``bytes``.
+
+
+Quick Reference
+---------------
+
+:mc-cmd:`mc admin bucket quota play/mybucket --hard 10GB <mc admin bucket quota hard>`
+   Adds a hard quota of ``10GB`` to the ``mybucket`` bucket on the
+   MinIO deployment with the ``play`` :mc-cmd:`alias <mc alias>`. MinIO
+   rejects any ``PUT`` request that would result in the bucket exceeding
+   the configured quota.
+
+:mc-cmd:`mc admin bucket quota play/mybucket --fifo 10GB <mc admin bucket quota fifo>`
+   Adds a hard quota of ``10GB`` to the ``mybucket`` bucket on the
+   MinIO deployment with the ``play`` :mc-cmd:`alias <mc alias>`. MinIO
+   removes the oldest objects on the bucket until it can satisfy the size
+   of an incoming ``PUT`` request.
+
+:mc-cmd:`mc admin bucket quota play/mybucket --clear <mc admin bucket quota clear>`
+   Removes all quotas from the ``mybucket`` bucket on the MinIO deployment
+   with the ``play`` :mc-cmd:`alias <mc alias>`.
+
+Syntax
+------
+
+:mc-cmd:`mc admin bucket quota` has the following syntax:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin bucket quota TARGET [FLAGS] [ARGUMENTS]
+
+:mc-cmd:`mc admin bucket quota` supports the following arguments:
+
+.. mc-cmd:: TARGET
+
+   The full path to the bucket for which the command creates the quota. 
+   Specify the :mc-cmd:`alias <mc alias>` of the MinIO deployment as a 
+   prefix to the path. For example:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin bucket quota play/mybucket
+
+.. mc-cmd:: hard
+   :option:
+
+   Sets a maximum limit to the bucket storage size. The MinIO server rejects any
+   incoming ``PUT`` request whose contents would exceed the bucket's configured
+   quota.
+
+   For example, a hard limit of ``10GB`` would prevent adding any additional
+   objects if the bucket reaches ``10GB`` of size.
+
+   See :ref:`mc-admin-bucket-quota-units` for supported unit sizes.
+
+.. 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.
+
+   For example, a ``fifo`` limit of ``10GB`` would result in removal of the
+   oldest objects in the bucket once it reaches ``10GB`` in size. 
+
+   See :ref:`mc-admin-bucket-quota-units` for supported unit sizes.
+
+.. mc-cmd:: clear
+   :option:
+
+   Clears all quotas configured for the bucket. 
+
+   
+

source/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst

@@ -0,0 +1,217 @@
+==========================
+``mc admin bucket remote``
+==========================
+
+.. default-domain:: minio
+
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
+.. mc:: mc admin bucket remote
+
+Description
+-----------
+
+.. start-mc-admin-bucket remote-desc
+
+The :mc-cmd:`mc admin bucket remote` command manages remote targets for 
+supporting 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`.
+
+.. 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
+
+MinIO Deployments Only
+~~~~~~~~~~~~~~~~~~~~~~
+
+: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.
+
+Quick Reference
+---------------
+
+:mc-cmd:`mc admin bucket remote add play/mybucket target/mybucket <mc admin bucket remote add>`
+   Adds a new remote target ``target/mybucket`` to ``play/mybucket``,
+   where ``target`` and ``play`` are :mc-cmd:`aliases <mc alias>` 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  <mc admin bucket remote ls>`
+   Lists all remote targets for ``play/mybucket``, where
+   ``play`` is a :mc-cmd:`alias <mc 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 <mc admin bucket remote rm>`
+   Removes the remote target ``target/mybucket`` from ``play/mybucket``,
+   where ``target`` and ``play`` are :mc-cmd:`aliases <mc alias>` 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:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin bucket remote SUBCOMMAND [ARGUMENTS]
+
+:mc-cmd:`mc admin bucket remote` supports the following subcommands:
+
+.. mc-cmd:: add
+   :fullpath:
+
+   Adds a remote target to a bucket on the MinIO deployment. The
+   command has the following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin bucket add TARGET DESTINATION --service "replication" [ARGUMENTS]
+
+   The command accepts the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The full path to the bucket to which the command adds the remote target.
+      Specify the :mc-cmd:`alias <mc alias>` of a configured MinIO deployment as
+      the prefix to the bucket path. For example:
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc admin bucket add play/mybucket
+
+   .. mc-cmd:: DESTINATION
+
+      The target MinIO deployment and bucket. Specify one of the two
+      following formats:
+
+      .. tabs::
+
+         .. tab:: ``alias/bucket``
+
+            Specify the :mc-cmd:`alias <mc 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
+
+               <alias>/<bucket>
+
+         .. tab:: URL
+
+            Specify the full URL to the destination MinIO deployment and bucket
+            using the following format:
+
+            .. 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.
+
+            - 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 name of the bucket on the
+              destination.
+
+   .. 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`
+
+   .. mc-cmd:: path
+
+      The bucket path lookup supported by the destination server. Specify
+      one of the following:
+
+      - ``on``
+      - ``off``
+      - ``auto`` (Default)
+
+      Mutually exclusive with :mc-cmd-option:`~mc admin bucket remote region`
+
+.. mc-cmd:: ls
+   :fullpath:
+
+   Lists all remote targets associated to a bucket on the MinIO deployment. The
+   command has the following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin bucket ls TARGET --service "replication"
+
+   The command accepts the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The full path to the bucket for which the command returns the configured
+      remote targets. Specify the :mc-cmd:`alias <mc alias>` of a configured
+      MinIO deployment as the prefix to the bucket path. For example:
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc admin bucket ls play/mybucket
+
+
+.. mc-cmd:: rm
+   :fullpath:
+
+   Removes a remote target for a bucket on the MinIO deployment. The
+   command has the following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin bucket rm TARGET --arn
+
+   The command accepts the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The full path to the bucket for which the command <ACTION>. Specify the
+      :mc-cmd:`alias <mc alias>` of a configured MinIO deployment as the
+      prefix to the bucket path. For example:
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc admin bucket remove play/mybucket
+
+   .. mc-cmd:: ARN
+      :option:
+
+      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.
+

source/minio-cli/minio-mc-admin/mc-admin-console.rst

@@ -0,0 +1,66 @@
+====================
+``mc admin console``
+====================
+
+.. default-domain:: minio
+
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
+.. mc:: mc admin console
+
+Description
+-----------
+
+.. start-mc-admin-console-desc
+
+The :mc-cmd:`mc admin console` command returns server log entries for each
+MinIO server in the deployment.
+
+.. end-mc-admin-console-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 console` has the following syntax:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin console [FLAGS] TARGET NODENAME
+
+:mc-cmd:`mc admin console` supports the following:
+
+.. mc-cmd:: TARGET
+
+   The :mc-cmd:`alias <mc-alias>` of a configured MinIO deployment from which
+   the command retrieves server logs.
+
+.. mc-cmd:: NODENAME
+
+   The specific MinIO server node from which the command retrieves server logs.
+
+.. mc-cmd:: limit, l
+   :option:
+
+   The number of most recent log entries to show. Defaults to ``10``.
+
+.. mc-cmd:: type, t
+   :option:
+
+   The type of errog logs to return. Specify one or more of the following
+   options as a comma-seperated ``,`` list:
+
+   - ``minio``
+   - ``application``
+   - ``all`` (Default)
+

source/minio-cli/minio-mc-admin/mc-admin-groups.rst

@@ -0,0 +1,250 @@
+===================
+``mc admin group``
+===================
+
+.. default-domain:: minio
+
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
+.. mc:: mc admin group
+
+Description
+-----------
+
+.. start-mc-admin-groups-desc
+
+The :mc-cmd:`mc admin group` command manages groups on a MinIO deployment.
+
+.. end-mc-admin-groups-desc
+
+A :ref:`group <minio-auth-authz-groups>` is a collection of :ref:`users
+<minio-auth-authz-users>`. Each group can have one or more assigned
+:ref:`policies <minio-auth-authz-pbac-policies>` that explicitly list the
+actions and resources to which group members are allowed or denied access.
+Groups provide a simplified method for managing shared permissions among users
+with common access patterns and workloads. 
+
+.. 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
+
+Groups and Policy-Based Access Control
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MinIO uses Policy-Based Access Control (PBAC) to support *authorization* of
+users who have successfully *authenticated* to the deployment. Each policy
+includes rules that dictate the allowed or denied actions/resources on the
+deployment. You can assign one or more :ref:`policies
+<minio-auth-authz-pbac-policies>` to a group. Users with membership in the
+group inherit the group's assigned policies. A user's total set of permissions
+includes their explicitly assigned policies *and* any policies inherited
+via group membership.
+
+Newly created groups have *no* policies by default. To configure a group's
+assigned policies, use the :mc-cmd:`mc admin policy set` command.
+
+For more information on MinIO users and groups, see
+:ref:`minio-auth-authz-users` and :ref:`minio-auth-authz-groups`. For 
+more information on MinIO policies, see :ref:`minio-auth-authz-pbac-policies`.
+
+.. admonition:: ``Deny`` overrides ``Allow``
+   :class: note
+
+   MinIO follows the IAM standard where a ``Deny`` rule overrides ``Allow`` rule
+   on the same action or resource. For example, if a user has an explicitly
+   assigned policy with an ``Allow`` rule for an action/resource while one of
+   its groups has an assigned policy with a ``Deny`` rule for that
+   action/resource, MinIO would apply only the ``Deny`` rule. 
+
+   For more information on IAM policy evaluation logic, see the IAM
+   documentation on 
+   :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account 
+   <reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
+
+Quick Reference
+---------------
+
+:mc-cmd:`mc admin group add TARGET GROUPNAME MEMBERS <mc admin group add>`
+   Adds a user to a group on the MinIO deployment. Creates the group if it
+   does not exist.
+
+:mc-cmd:`mc admin group info TARGET GROUPNAME <mc admin group info>`
+   Returns detailed information for a group on the MinIO deployment.
+
+:mc-cmd:`mc admin group list TARGET <mc admin group list>`
+   Returns a list of all groups on the MinIO deployment.
+
+:mc-cmd:`mc admin group remove TARGET GROUPNAME <mc admin group remove>`
+   Removes a group on the MinIO deployment.
+
+:mc-cmd:`mc admin group enable TARGET GROUPNAME <mc admin group enable>`
+   Enables a group on the MinIO deployment. Users can only inherit
+   :ref:`policies <minio-auth-authz-pbac-policies>` assigned to an enabled group.
+
+:mc-cmd:`mc admin group disable TARGET GROUPNAME <mc admin group disable>`
+   Disables a group on the MinIO deployment. Users cannot inherit :ref:`policies
+   <minio-auth-authz-pbac-policies>` assigned to a disabled group.
+
+Syntax
+------
+
+:mc-cmd:`mc admin group` has the following syntax:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin group [SUBCOMMAND] [ARGUMENTS]
+
+:mc-cmd:`mc admin group` supports the following subcommands:
+
+.. mc-cmd:: mc admin group add
+   :fullpath:
+
+   Adds an existing user to the group. The command creates the group if it
+   does not exist. The command has the following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin group add TARGET GROUPNAME MEMBERS
+
+   The command accepts the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment on which
+      the command adds users to the new or existing group
+
+   .. mc-cmd:: GROUPNAME
+
+      The name of the group. The command creates the group if it does not 
+      already exist. Use :mc-cmd:`mc admin group list` to review the existing
+      groups on a deployment.
+
+   .. mc-cmd:: MEMBERS
+
+      The name of the user to add to the group.
+      
+      The user *must* exist on the :mc-cmd:`~mc admin group add TARGET` MinIO
+      deployment. Use :mc-cmd:`mc admin user list` to review the available
+      users on the deployment. 
+
+.. mc-cmd:: mc admin group info
+   :fullpath:
+
+   Returns details for the group on the target deployment, such as all
+   :ref:`users <minio-auth-authz-users>` with membership in the group and the
+   assigned :ref:`policies <minio-auth-authz-pbac-policies>`. The command has
+   the following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin group info TARGET GROUPNAME
+
+   The command accepts the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment from which
+      to retrieve the group information.
+
+   .. mc-cmd:: GROUPNAME
+
+      The name of the group.
+
+.. mc-cmd:: mc admin group list
+   :fullpath:
+
+   List all groups on the target MinIO deployment. The command has the
+   following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin group list TARGET
+
+   The command accepts the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment from
+      which to retrieve groups.
+
+.. mc-cmd:: mc admin group remove
+   :fullpath:
+
+   Removes a group on the target MinIO deployment. Removing a group does *not*
+   remove any users with membership in the group. Use :mc-cmd:`mc admin user
+   remove` to remove users from a group. 
+   
+   The command has the following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin group remove TARGET GROUPNAME
+
+   The command accepts the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment on which
+      to remove the group.
+
+   .. mc-cmd:: GROUPNAME
+
+      The name of the group to remove.
+
+.. mc-cmd:: mc admin group enable
+   :fullpath:
+
+   Enables the group on the target MinIO deployment. Users can only inherit
+   :ref:`policies <minio-auth-authz-pbac-policies>` from an enabled group.
+   Groups are enabled on creation by default. The command has the following
+   syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin group enable TARGET GROUPNAME
+
+   The command accepts the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment on
+      which to enable the group.
+
+   .. mc-cmd:: GROUPNAME
+
+      The name of the group to enable. 
+
+.. mc-cmd:: mc admin group disable
+   :fullpath:
+
+   Disables the group on the target MinIO deployment. Users cannot inherit
+   :ref:`policies <minio-auth-authz-pbac-policies>` from a disabled group. The
+   command has the following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin group disable TARGET GROUPNAME
+
+   The command accepts the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment on which
+      to disable the group.
+
+   .. mc-cmd:: GROUPNAME
+
+      The name of the group to disable.
+

source/minio-cli/minio-mc-admin/mc-admin-heal.rst

@@ -0,0 +1,94 @@
+=================
+``mc admin heal``
+=================
+
+.. default-domain:: minio
+
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
+.. mc:: mc admin heal
+
+Description
+-----------
+
+.. start-mc-admin-heal-desc
+
+The :mc-cmd:`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
+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
+
+   .. include:: /includes/facts-mc-admin.rst
+      :start-after: start-minio-only
+      :end-before: end-minio-only
+
+Syntax
+------
+
+:mc-cmd:`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-cmd:: TARGET
+
+   The full path to the bucket or bucket prefix on which the command should
+   perform object healing. Specify the :mc-cmd:`alias <mc alias>` of a
+   configured MinIO deployment as the prefix for the path. For example:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin heal play/mybucket/myprefix
+
+   If the ``TARGET`` bucket or bucket prefix has an active healing scan,
+   the command returns the status of that scan.
+
+.. mc-cmd:: scan
+   :option:
+
+   The type of scan to perform. Specify one of the following supported scan
+   modes:
+
+   - ``normal`` (default)
+   - ``deep``
+
+.. mc-cmd:: recursive, r
+   :option:
+
+   Recursively scans for objects in the specified bucket or bucket prefix.
+
+.. mc-cmd:: dry-run
+   :option:
+
+   Inspects the :mc-cmd:`~mc admin heal TARGET` bucket or bucket prefix, 
+   but does *not* perform any object healing.
+
+.. mc-cmd:: force-start, f
+   :option:
+
+   Force starts the healing process.
+
+.. mc-cmd:: force-stop, s
+   :option:
+
+   Force stops the healing sequence.
+
+.. mc-cmd:: remove
+   :option:
+
+   Removes dangling objects in the healing process. 

source/minio-cli/minio-mc-admin/mc-admin-info.rst

@@ -21,6 +21,18 @@ for each MinIO server in the deployment.
 
 .. end-mc-admin-info-desc
 
+Examples
+--------
+
+.. include:: /includes/play-alias-available.rst
+   :start-after: play-alias-only
+   :end-before: end-play-alias-only
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin info play
+
 Syntax
 ------
 
@@ -34,18 +46,3 @@ Syntax
 Specify the :mc-cmd:`alias <mc alias>` of a configured MinIO deployment as the
 ``TARGET``. :mc-cmd:`~mc admin service restart` restarts *all* MinIO servers in
 the deployment.
-
-Behavior
---------
-
-Examples
---------
-
-.. include:: /includes/play-alias-available.rst
-   :start-after: play-alias-only
-   :end-before: end-play-alias-only
-
-.. code-block:: shell
-   :class: copyable
-
-   mc admin info play

source/minio-cli/minio-mc-admin/mc-admin-kms.rst

@@ -0,0 +1,51 @@
+================
+``mc admin kms``
+================
+
+.. default-domain:: minio
+
+.. contents:: On This Page
+   :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 <mc 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.
+

source/minio-cli/minio-mc-admin/mc-admin-obd.rst

@@ -0,0 +1,58 @@
+================
+``mc admin obd``
+================
+
+.. default-domain:: minio
+
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
+.. mc:: mc admin obd
+
+Description
+-----------
+
+.. start-mc-admin-obd-desc
+
+The :mc-cmd:`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
+and diagnostics.
+
+.. end-mc-admin-obd-desc
+
+The :mc-cmd:`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. 
+
+.. 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 obd` has the following syntax:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin obd [FLAGS] TARGET
+
+:mc-cmd:`mc admin obd` supports the following arguments:
+
+.. mc-cmd:: TARGET
+
+   The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment from which
+   the command retrieves the diagnostic data.
+
+.. mc-cmd:: deadline
+   :option:
+
+   The maximum duration the command can run. Specify a string as 
+   ``##h##m##s``. Defaults to ``1h0m0s``. 
+

source/minio-cli/minio-mc-admin/mc-admin-policy.rst

@@ -23,35 +23,52 @@ documents to define rules for accessing resources on a MinIO server.
 
 For complete documentation on MinIO PBAC, including policy document JSON
 structure and syntax, see
-:doc:`/security/minio-security-policy-based-access-control`.
+:doc:`/security/minio-authentication-authorization`.
 
-By default, MinIO deployments use the access key and secret key
+Quick Reference
-specified when starting the MinIO server or servers as the root credentials.
+---------------
-These credentials provide complete control over the MinIO deployment and are
-not intended for use outside of administrative operations.
 
-MinIO strongly recommends using :mc-cmd:`mc admin policy` to configure PBAC
+:mc-cmd:`mc admin policy add TARGET POLICYNAME POLICYFILE <mc admin policy add>`
-such that applications have the minimal set of privileges required for
+   Creates a new policy on the target MinIO deployment. 
-completing their workloads. MinIO provides :ref:`minio-security-pbac-built-in`
-policies as a baseline for configuring PBAC:
 
-- :userpolicy:`readonly`
+   .. code-block:: shell
-- :userpolicy:`readwrite`
+      :class: copyable
-- :userpolicy:`diagnostics`
-- :userpolicy:`writeonly`
 
-To apply a built-in policy to a user or group, use the 
+      mc admin policy add play myNewPolicy /path/to/policy.json
-:mc-cmd:`mc admin policy set` command:
 
-.. code-block:: shell
+:mc-cmd:`mc admin policy list TARGET <mc admin policy list>`
-   :class: copyable
+   Lists the available policies on the target MinIO deployment.
 
-   mc admin policy set myminio myReadOnlyPolicy readOnlyUser
+   .. code-block:: shell
+      :class: copyable
       
-   mc admin policy set myminio myReadWritePolicy readWriteGroup
+      mc admin policy list play
 
-For more information on creating users and groups, see 
+:mc-cmd:`mc admin policy info TARGET POLICYNAME <mc admin policy info>`
-:mc-cmd:`mc admin users` and :mc-cmd:`mc admin groups` respectively.
+   Returns the policy in JSON format from the target MinIO deployment.
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin policy info play myNewPolicy
+
+:mc-cmd:`mc admin policy set TARGET POLICYNAME user=|group= <mc admin policy set>`
+   Associates a policy to a user or group on the target MinIO deployment.
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin policy set play myNewPolicy user=myMinioUser
+
+      mc admin policy set play myNewGroupPolicy group=myMinioGroup
+
+:mc-cmd:`mc admin policy remove TARGET POLICYNAME <mc admin policy remove>`
+   Removes a policy from the target MinIO deployment.
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin policy remove play myNewPolicy
 
 Examples
 --------
@@ -61,9 +78,9 @@ Create a Policy
 
 .. include:: /includes/play-alias-available.rst
    :start-after: myminio-alias
-   :end-before: myminio-alias
+   :end-before: end-myminio-alias
 
-For example, consider the following JSON policy document:
+Consider the following JSON policy document:
 
 .. code-block:: javascript
    :class: copyable
@@ -83,7 +100,6 @@ For example, consider the following JSON policy document:
       ]
    }
 
-
 The following :mc-cmd:`mc admin policy add` command creates a new policy
 ``listbucketsonly`` on the ``myminio`` MinIO deployment using the
 example JSON policy document:
@@ -100,74 +116,105 @@ List Available Policies
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 .. include:: /includes/play-alias-available.rst
-   :start-after: play-alias-only
+   :start-after: myminio-alias
-   :end-before: end-play-alias-only
+   :end-before: end-myminio-alias
 
 The following :mc-cmd:`mc admin policy list` command lists the available
-policies on the ``play`` MinIO deployment:
+policies on the ``myminio`` MinIO deployment:
 
 .. code-block:: shell
    :class: copyable
 
+   mc admin policy list myminio
+
+The command returns output that resembles the following:
+
+.. code-block:: shell
+
+   readwrite
+   writeonly
+
+To retrieve information on a specific policy, use the 
+:mc-cmd:`mc admin policy info` command:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin policy info myminio writeonly
+
+The command returns output that resembles the following:
+
+.. code-block:: javascript
+
+   {
+      "Version": "2012-10-17",
+      "Statement": [
+         {
+            "Effect": "Allow",
+            "Action": [
+               "s3:PutObject"
+            ],
+            "Resource": [
+               "arn:aws:s3:::*"
+            ]
+         }
+      ]
+   }
+
 Remove a Policy
 ~~~~~~~~~~~~~~~
 
 .. include:: /includes/play-alias-available.rst
-   :start-after: play-alias-only
+   :start-after: myminio-alias
-   :end-before: end-play-alias-only
+   :end-before: end-myminio-alias
+
+The following :mc-cmd:`mc admin policy remove` command removes a policy
+on the ``myminio`` MinIO deployment:
 
 .. code-block:: shell
    :class: copyable
 
+   mc admin policy remove myminio listbucketsonly
+
+
 Apply a Policy to a User or Group
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. include:: /includes/play-alias-available.rst
-   :start-after: play-alias-only
+   :start-after: myminio-alias
-   :end-before: end-play-alias-only
+   :end-before: end-myminio-alias
+
+- Use the :mc-cmd:`mc admin user list` command to return a list of
+  users on the target MinIO deployment. 
+
+- Use the :mc-cmd:`mc admin group list` command to return a list of
+  users on the target MinIO deployment.
+
+The following :mc-cmd:`mc admin policy set` command associates the 
+``listbucketsonly`` policy to a user on the ``myminio`` MinIO deployment. 
+Replace the ``<USER>`` with the name of a user that exists on the deployment.
 
 .. code-block:: shell
    :class: copyable
 
+   mc admin policy set myminio listbucketsonly user=<USER>
+
+The following :mc-cmd:`mc admin policy set` command associates the 
+``listbucketsonly`` policy to a group on the ``myminio`` MinIO deployment. 
+Replace the ``<GROUP>`` with the name of a user that exists on the deployment.
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin policy set myminio listbucketsonly group=<GROUP>
+
 Syntax
 ------
 
-:mc-cmd:`mc admin policy` has the following syntax:
-
-.. code-block:: shell
-   :class: copyable
-
-   mc admin policy SUBCOMMAND [ARGUMENTS]
-
-:mc-cmd:`mc admin policy` supports the following subcommands:
-
-.. list-table::
-   :header-rows: 1
-   :widths: 40 60
-   :width: 100%
-
-   * - Subcommand
-     - Description
-
-   * - :mc-cmd:`mc admin policy add`
-     - Creates a new policy on the target MinIO deployment.
-
-   * - :mc-cmd:`mc admin policy list`
-     - Lists the available policies on the target MinIO deployment.
-
-   * - :mc-cmd:`mc admin policy info`
-     - Returns the policy in JSON format from the target MinIO deployment.
-
-   * - :mc-cmd:`mc admin policy set`
-     - Associates a policy to a user or group on the target MinIO deployment.
-
-   * - :mc-cmd:`mc admin policy remove`
-     - Removes a policy from the target MinIO deployment.
-
 .. mc-cmd:: add
    :fullpath:
 
-   :mc-cmd:`mc admin policy add` creates a new policy on the target MinIO
+   Creates a new policy on the target MinIO
    deployment. The command has the following syntax:
 
    .. code-block:: shell
@@ -197,7 +244,7 @@ Syntax
 .. mc-cmd:: list
    :fullpath:
 
-   This command lists all policies on the target MinIO deployment. The command
+   Lists all policies on the target MinIO deployment. The command
    has the following syntax:
 
    .. code-block:: shell
@@ -206,7 +253,7 @@ Syntax
       mc admin policy list TARGET
 
    For example, the following command lists all policies on the 
-   ``play`` MinIO deployment:
+   ``myminio`` MinIO deployment:
 
    .. code-block:: shell
       :class: copyable
@@ -223,7 +270,7 @@ Syntax
 .. mc-cmd:: info
    :fullpath:
 
-   This command returns the specified policy in JSON format if it exists 
+   Returns the specified policy in JSON format if it exists 
    on the target MinIO deployment. The command has the following syntax:
 
    .. code-block:: shell
@@ -245,13 +292,16 @@ Syntax
 .. mc-cmd:: set
    :fullpath:
 
-   This command applies an existing policy to a user or group on the 
+   Applies an existing policy to a user or group on the 
-   target MinIO deployment. The command has the following syntax:
+   target MinIO deployment. :mc-cmd:`mc admin policy set` overwrites the
+   existing policy associated to the user or group.
+   
+   The command has the following syntax:
 
    .. code-block:: shell
       :class: copyable
 
-      mc admin policy set TARGET POLICYNAME [ user=USERNAME | group=GROUPNAME ]
+      mc admin policy set TARGET POLICYNAME[,POLICYNAME,...] [ user=USERNAME | group=GROUPNAME ]
 
    The command accepts the following arguments:
 
@@ -266,7 +316,16 @@ Syntax
 
       The name of the policy which the command associates to the specified
       :mc-cmd:`~mc admin policy set user` or 
-      :mc-cmd:`~mc admin policy set group`.
+      :mc-cmd:`~mc admin policy set group`. Specify multiple policies
+      as a comma-separated list.
+
+      MinIO deployments include the following :ref:`built-in policies
+      <minio-auth-authz-pbac-built-in>` policies by default:
+
+      - :userpolicy:`readonly` 
+      - :userpolicy:`readwrite`
+      - :userpolicy:`diagnostics`
+      - :userpolicy:`writeonly`
 
    .. mc-cmd:: user
 
@@ -299,7 +358,7 @@ Syntax
    .. mc-cmd:: TARGET
 
       The :mc-cmd:`alias <mc-alias>` of a configured MinIO deployment on which
-      the command removes the :mc-cmd:`~mc admin policy set POLICYNAME`.
+      the command removes the :mc-cmd:`~mc admin policy remove POLICYNAME`.
 
    .. mc-cmd:: POLICYNAME
 

source/minio-cli/minio-mc-admin/mc-admin-profile.rst

@@ -0,0 +1,122 @@
+====================
+``mc admin profile``
+====================
+
+.. default-domain:: minio
+
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
+.. mc:: mc admin profile
+
+Description
+-----------
+
+.. start-mc-admin-profile-desc
+
+The :mc-cmd:`mc admin profile` command generates profiling data for debugging
+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 <https://github.com/google/pprof>`__ ``go`` utility to read the
+profile data.
+
+.. 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
+
+Quick Reference
+---------------
+
+:mc-cmd:`mc admin profile start --type cpu myminio/ <mc admin profile start>`
+   Starts profiling data related to ``cpu`` statistics
+   on the ``myminio`` :mc-cmd:`alias <mc alias>`.
+
+:mc-cmd:`mc admin profile start --type "cpu,mem,block" myminio/ <mc admin profile start>`
+   Starts profiling data related to ``cpu``, ``mem``, and ``block`` statistics
+   on the ``myminio`` :mc-cmd:`alias <mc alias>`.
+
+:mc-cmd:`mc admin profile stop myminio/ <mc admin profile stop>`
+   Stops profiling data on the ``myminio`` :mc-cmd:`alias <mc alias>` and
+   dumps the recorded data to ``profile.zip``.
+
+Syntax
+------
+
+:mc-cmd:`mc admin profile` has the following syntax:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin profile SUBCOMMAND
+
+:mc-cmd:`mc admin profile` supports the following subcommands:
+
+.. mc-cmd:: start
+   :fullpath:
+
+   Starts collecting profiling data on the target MinIO deployment. The
+   command has the following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin profile start [FLAGS] TARGET
+
+   :mc-cmd:`mc admin profile start` supports the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment from
+      which the command collects profiling data.
+
+   .. mc-cmd:: type
+      :option:
+
+      The type(s) of profiling data to collect from the 
+      :mc-cmd:`~mc admin profile start TARGET` MinIO deployment.
+
+      Specify one or more of the following supported types as a comma-separated
+      list:
+
+      - ``cpu``
+      - ``mem``
+      - ``block``
+      - ``mutex``
+      - ``trace``
+      - ``threads``
+      - ``goroutines``
+
+      Defaults to ``cpu,mem,block`` if omitted. 
+
+.. mc-cmd:: stop
+   :fullpath:
+
+   Stops the profiling process and returns the collected data as 
+   ``profile.zip``. The ``zip`` file contains one or more 
+   ``.pprof`` files which are readable with programs like the ``go``
+   `pprof <https://github.com/google/pprof>`__ utility.
+
+   The command has the following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin profile stop TARGET
+
+   The command supports the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment from
+      which the command returns available profiling data. 
+
+
+

source/minio-cli/minio-mc-admin/mc-admin-prometheus.rst

@@ -0,0 +1,51 @@
+=======================
+``mc admin prometheus``
+=======================
+
+.. default-domain:: minio
+
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
+.. mc:: mc admin prometheus
+
+Description
+-----------
+
+.. start-mc-admin-prometheus-desc
+
+The :mc-cmd:`mc admin prometheus` command generates a configuration file for
+use with `Prometheus <https://prometheus.io/>`__.
+
+.. end-mc-admin-prometheus-desc
+
+For more complete documentation on using MinIO with Prometheus, see our
+legacy documentation site 
+:legacy:`How to monitor MinIO server with Prometheus 
+<how-to-monitor-minio-using-prometheus.html>`
+
+.. 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 prometheus` has the following syntax:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin prometheus generate TARGET
+
+:mc-cmd:`mc admin prometheus` supports the following:
+
+.. mc-cmd:: TARGET
+
+   The :mc-cmd:`alias <mc-alias>` of a configured MinIO deployment for which
+   the command generates a Prometheus-compatible configuration file.
+

source/minio-cli/minio-mc-admin/mc-admin-service.rst

@@ -6,7 +6,7 @@
 
 .. contents:: On This Page
    :local:
-   :depth: 1
+   :depth: 2
 
 .. mc:: mc admin service
 
@@ -19,6 +19,46 @@ The :mc-cmd:`mc admin service` command can restart or stop MinIO servers.
 
 .. end-mc-admin-service-desc
 
+:mc-cmd:`mc admin service` affects *all* MinIO servers in the target deployment
+at the same time. The command interrupts in-progress API operations on
+the MinIO deployment. Exercise caution before issuing an update command on
+production environments.
+
+
+.. 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
+
+Examples
+--------
+
+Restart MinIO Servers in Target Deployment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/play-alias-available.rst
+   :start-after: myminio-alias
+   :end-before: end-myminio-alias
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin service restart myminio
+
+Stop MinIO Servers in Target Deployment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/play-alias-available.rst
+   :start-after: myminio-alias
+   :end-before: end-myminio-alias
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin service stop myminio
+
 Syntax
 ------
 
@@ -61,55 +101,3 @@ Syntax
    :mc-cmd:`~mc admin service stop` stops *all* MinIO servers in the
    deployment.
 
-Behavior
---------
-
-Simultaneous Restart or Stop
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-:mc-cmd:`mc admin service restart` and :mc-cmd:`mc admin service stop`
-affect *all* MinIO servers in the target deployment at the same time.
-The commands do not perform a rolling restart or similar zero or near-zero
-downtime restart procedure. Use :mc-cmd:`mc alias list` to review the currently
-configured aliases and their corresponding endpoints.
-
-.. important::
-   
-   ``mc admin service restart`` and ``mc admin service stop`` interrupts
-   in-progress API operations on the MinIO deployment. Exercise caution before
-   issuing either command in production environments.
-
-
-MinIO Deployments Only
-~~~~~~~~~~~~~~~~~~~~~~
-
-:mc-cmd:`mc admin service` is intended for use with MinIO servers only. MinIO
-provides no guarantees or support for using :mc-cmd:`mc admin service` 
-with other S3-compatible services.
-
-Examples
---------
-
-Restart MinIO Servers in Target Deployment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. include:: /includes/play-alias-available.rst
-   :start-after: myminio-alias
-   :end-before: end-myminio-alias
-
-.. code-block:: shell
-   :class: copyable
-
-   mc admin service restart myminio
-
-Stop MinIO Servers in Target Deployment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. include:: /includes/play-alias-available.rst
-   :start-after: myminio-alias
-   :end-before: end-myminio-alias
-
-.. code-block:: shell
-   :class: copyable
-
-   mc admin service stop myminio

source/minio-cli/minio-mc-admin/mc-admin-top.rst

@@ -0,0 +1,54 @@
+================
+``mc admin top``
+================
+
+.. default-domain:: minio
+
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
+.. mc:: mc admin top
+
+Description
+-----------
+
+.. start-mc-admin-top-desc
+
+The :mc-cmd:`mc admin top` command returns statistics for distributed
+MinIO deployments, similar to the output of the ``top`` command. 
+
+:mc-cmd:`mc admin top` is not supported on standalone MinIO deployments
+or MinIO Gateway deployments.
+
+.. end-mc-admin-top-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 top` has the following syntax:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin top lock TARGET
+
+The command supports the following arguments:
+
+.. mc-cmd:: TARGET
+
+   The :mc-cmd:`alias <mc 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.
+
+

source/minio-cli/minio-mc-admin/mc-admin-trace.rst

@@ -0,0 +1,62 @@
+==================
+``mc admin trace``
+==================
+
+.. default-domain:: minio
+
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
+.. mc:: mc admin trace
+
+Description
+-----------
+
+.. start-mc-admin-trace-desc
+
+The :mc-cmd:`mc admin trace` command displays the results of an
+`HTTP TRACE <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/TRACE>`__
+request against each MinIO server in a deployment.
+
+.. end-mc-admin-trace-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 trace` has the following syntax:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin trace [FLAGS] TARGET
+
+:mc-cmd:`mc admin trace` supports the following argument:
+
+.. mc-cmd:: TARGET
+
+   Specify the :mc-cmd:`alias <mc-alias>` of a configured MinIO deployment
+   against which the command issues ``HTTP TRACE`` requests.
+
+.. mc-cmd:: all, a
+   :option:
+
+   Returns all traffic on the MinIO deployment, including internode traffic
+   between MinIO servers.
+
+.. mc-cmd:: verbose
+   :option:
+
+   Returns verbose ``HTTP TRACE`` output.
+
+.. mc-cmd:: errors, e
+   :option:
+
+   Returns failed ``HTTP TRACE`` requests only.

source/minio-cli/minio-mc-admin/mc-admin-update.rst

@@ -21,6 +21,30 @@ environments where the deployment does not have public internet access.
 
 .. end-mc-admin-update-desc
 
+:mc-cmd:`mc admin update` affects *all* MinIO servers in the target deployment
+at the same time. The update procedure interrupts in-progress API operations on
+the MinIO deployment. Exercise caution before issuing an update command on
+production environments.
+
+.. 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
+
+Examples
+--------
+
+.. include:: /includes/play-alias-available.rst
+   :start-after: myminio-alias
+   :end-before: end-myminio-alias
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin update myminio
+
 Syntax
 ------
 
@@ -50,24 +74,3 @@ Syntax
    The mirror URL of the ``minio`` server binary to use for updating MinIO
    servers in the :mc-cmd:`~mc admin update ALIAS` deployment.
 
-Behavior
---------
-
-Update Requires Downtime
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-:mc-cmd:`mc admin update` interrupts in-progress API operations on the MinIO
-deployment. Exercise caution before issuing an update command on production
-environments.
-
-Examples
---------
-
-.. include:: /includes/play-alias-available.rst
-   :start-after: myminio-alias
-   :end-before: end-myminio-alias
-
-.. code-block:: shell
-   :class: copyable
-
-   mc admin update myminio

source/minio-cli/minio-mc-admin/mc-admin-user.rst

@@ -0,0 +1,281 @@
+=================
+``mc admin user``
+=================
+
+.. default-domain:: minio
+
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
+.. mc:: mc admin user
+
+Description
+-----------
+
+.. start-mc-admin-user-desc
+
+The :mc-cmd:`mc admin user` command manages users on a MinIO deployment.
+
+.. 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
+
+   .. include:: /includes/facts-mc-admin.rst
+      :start-after: start-minio-only
+      :end-before: end-minio-only
+
+Users and Policy-Based Access Control
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MinIO uses Policy-Based Access Control (PBAC) to support *authorization* of
+users who have successfully *authenticated* to the deployment. Each policy
+includes rules that dictate the allowed or denied actions/resources on the
+deployment. You can assign one or more :ref:`policies
+<minio-auth-authz-pbac-policies>` to a User. Users *also* inherit the policies
+of any groups of which they are members. A user's total set of permissions
+includes their explicitly assigned policies *and* any policies inherited via
+group membership.
+
+Newly created users have *no* policies by default and therefore cannot perform
+any operations on the MinIO deployment. To configure a user's assigned policies,
+you can do either or both of the following:
+
+- Use :mc-cmd:`mc admin policy set` to associate one or more policies to
+  the user.
+
+- Use :mc-cmd:`mc admin group add` to associate the user to the group. Users
+  inherit any policies assigned to the group.
+
+Each user's total set of permissions consists of their explicitly assigned
+permission *and* the inherited permissions from each of their assigned groups.
+
+For more information on MinIO users and groups, see
+:ref:`minio-auth-authz-users` and :ref:`minio-auth-authz-groups`. For 
+more information on MinIO policies, see :ref:`minio-auth-authz-pbac-policies`.
+
+.. admonition:: ``Deny`` overrides ``Allow``
+   :class: note
+
+   MinIO follows the IAM standard where a ``Deny`` rule overrides ``Allow`` rule
+   on the same action or resource. For example, if a user has an explicitly
+   assigned policy with an ``Allow`` rule for an action/resource while one of
+   its groups has an assigned policy with a ``Deny`` rule for that
+   action/resource, MinIO would apply only the ``Deny`` rule. 
+
+   For more information on IAM policy evaluation logic, see the IAM
+   documentation on 
+   :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account 
+   <reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
+
+Quick Reference
+---------------
+
+:mc-cmd:`mc admin user add TARGET ACCESSKEY SECRETKEY <mc admin user add>`
+   Adds a new user to a MinIO deployment.
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin user add play myNewUser myNewUserSecretKey
+
+:mc-cmd:`mc admin user list TARGET <mc admin user list>`
+   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 <mc admin user info>`
+   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 <mc admin user remove>`
+   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 <mc admin user enable>`
+   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 <mc admin user disable>`
+   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:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc admin user SUBCOMMAND
+
+:mc-cmd:`mc admin user` supports the following subcommands:
+
+.. mc-cmd:: add
+   :fullpath:
+
+   Adds new user to the target MinIO deployment. The command has the following
+   syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin user add TARGET ACCESSKEY SECRETKEY
+
+   The command accepts the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment on which
+      the command creates the new user. 
+
+   .. mc-cmd:: ACCESSKEY
+
+      The access key that uniquely identifies the new user, similar to a
+      username.
+
+   .. mc-cmd:: SECRETKEY
+
+      The secret key for the new user. Consider the following guidance
+      when creating a secret key:
+
+      - The key should be *unique*
+      - The key should be *long* (Greater than 12 characters)
+      - The key should be *complex* (A mixture of characters, numerals, and symbols)
+
+
+.. mc-cmd:: list
+   :fullpath:
+
+   Lists all users on the target MinIO deployment. The command has the
+   following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin user list TARGET
+
+   The command accepts the following argument:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment from which
+      the command lists users.
+
+.. mc-cmd:: info
+
+   Returns detailed information of a user on the target MinIO deployment. The
+   command has the following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin user info TARGET USERNAME
+
+   The command accepts the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment from
+      which the command retrieves the specified user information.
+
+   .. mc-cmd:: USERNAME
+
+      The username (:mc-cmd:`ACCESSKEY <mc admin user set ACCESSKEY>`) for the
+      user whose information the command retrieves. 
+
+.. mc-cmd:: remove
+
+   Removes a user from the target MinIO deployment. The command has the
+   following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin user remove TARGET USERNAME
+
+   The command supports the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc-alias>` of a configured MinIO deployment on which
+      the command removes the specified user.
+
+   .. mc-cmd:: USERNAME
+
+      The username (:mc-cmd:`ACCESSKEY <mc admin user set ACCESSKEY>`) for
+      the user to remove. 
+
+.. mc-cmd:: disable
+
+   Disables a user on the target MinIO deployment. Clients cannot use the
+   user credentials to authenticate to the MinIO deployment. Disabling
+   a user does *not* remove that user from the deployment.
+
+   The command has the following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin user disable TARGET USERNAME
+
+   The command supports the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc-alias>` of a configured MinIO deployment on which
+      the command disables the specified user.
+
+   .. mc-cmd:: USERNAME
+
+      The username (:mc-cmd:`ACCESSKEY <mc admin user set ACCESSKEY>`) for
+      the user to disable. 
+
+.. mc-cmd:: enable
+
+   Enables a user on the target deployment. Clients can only use enabled
+   users to authenticate to the MinIO deployment. Users created using
+   :mc-cmd:`mc admin user add` are enabled by default.
+
+   The command has the following syntax:
+
+   .. code-block:: shell
+      :class: copyable
+
+      mc admin user enable TARGET USERNAME
+
+   The command supports the following arguments:
+
+   .. mc-cmd:: TARGET
+
+      The :mc-cmd:`alias <mc-alias>` of a configured MinIO deployment on which
+      the command enables the specified user.
+
+   .. mc-cmd:: USERNAME
+
+      The username (:mc-cmd:`ACCESSKEY <mc admin user set ACCESSKEY>`) for
+      the user to enable. 

source/minio-cli/minio-mc.rst

@@ -21,6 +21,103 @@ support for both filesystems and Amazon S3-compatible cloud storage services
 
    mc [FLAGS] COMMAND [COMMAND FLAGS | -h] [ARGUMENTS...] ALIAS
 
+Quickstart
+----------
+
+1) Install ``mc``
+~~~~~~~~~~~~~~~~~
+
+Ensure that the host machine has :mc-cmd:`mc`
+:ref:`installed <mc-install>` prior to starting this procedure:
+
+.. include:: /includes/minio-mc-installation.rst
+
+2) Add an S3-Compatible Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. important::
+
+   The following example temporarily disables the bash history to mitigate the
+   risk of authentication credentials leaking in plain text. This is a basic
+   security measure and does not mitigate all possible attack vectors. Defer to
+   security best practices for your operating system for inputting sensitive
+   information on the command line.
+
+Use the :mc-cmd:`mc alias add` command to add an Amazon S3-compatible host
+to the :mc-cmd:`mc` :ref:`configuration <mc-configuration>`.
+
+.. code-block:: shell
+   :class: copyable
+
+   bash +o history
+   mc alias add ALIAS ENDPOINT ACCESS_KEY SECRET_KEY --api [S3v2|S3v4]
+   bash -o history
+
+- Replace ``ALIAS`` with a name to associate to the S3 service. 
+  :mc-cmd:`mc` commands typically require ``ALIAS`` as an argument for
+  identifying which S3 service to execute against.
+
+- Replace ``ENDPOINT`` with the URL endpoint of the S3 service.
+
+- Replace ``ACCESS_KEY`` and ``SECRET_KEY`` with the access and secret 
+  keys for a user on the S3 service. 
+
+- The ``--api`` flag is optional and defaults to ``S3v4`` if ommitted.
+
+Replace each argument with the required values. Specifying only the 
+``mc config host add`` command starts an input prompt for entering the
+required values.
+
+Each of the following tabs contains a provider-specific example:
+
+.. tabs::
+
+   .. tab:: MinIO Server
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc alias add myminio https://minioserver.example.net ACCESS_KEY SECRET KEY
+
+   .. tab:: AWS S3 Storage
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc alias add myS3 https://s3.amazon.com/endpoint ACCESS_KEY SECRET KEY
+
+   .. tab:: Google Cloud Storage
+
+      .. code-block:: shell
+         :class: copyable
+
+         mc alias add myGCS https://storage.googleapis.com/endpoint ACCESS_KEY SECRET KEY
+
+3) Test the Connection
+~~~~~~~~~~~~~~~~~~~~~~
+
+Use the :mc-cmd:`mc info` command to test the connection to
+the newly added MinIO deployment:
+
+.. code-block:: shell
+   :class: copyable
+
+   mc info myminio
+
+The command returns information on the S3 service if successful. If
+unsuccessful, check each of the following:
+
+- The host machine has connectivity to the S3 service URL (i.e. using ``ping``
+  or ``traceroute``).
+
+- The specified ``ACCESSKEY`` and ``SECRETKEY`` correspond to a user on the
+  S3 service. The user must have permission to perform actions on the
+  service. 
+  
+  For MinIO deployments, see :doc:`/security/minio-authentication-authorization`
+  for more information on user access permissions. For other S3-compatible
+  services, defer to the documentation for that service.
+
 Command Quick Reference
 -----------------------
 
@@ -161,15 +258,16 @@ The following table lists :mc-cmd:`mc` commands:
      
 
 :mc-cmd:`mc` also includes an administration extension for managing MinIO
-deployments. See :program:`mc admin` for more complete documentation.
+deployments. See :mc-cmd:`mc admin` for more complete documentation.
 
 .. _mc-configuration:
 
 Configuration File
 ------------------
 
-:mc-cmd:`mc` stores data in a configuration file. Use the
+:mc-cmd:`mc` uses a ``JSON`` formatted configuration file used for storing
-``--config-dir`` flag to specify a path to a ``JSON`` formatted configuration file.
+certain kinds of information, such as the :mc-cmd:`aliases <mc alias>` for 
+each configured S3-compatible service.
 
 For Linux and OSX, the default configuration file location is 
 ``~/.mc/config.json``.
@@ -184,6 +282,8 @@ The following list describes each possible file path location in the order
 #. ``USERPROFILE\.mc\config.json``
 #. ``HOMEDRIVE+HOMEPATH\.mc\config.json``
 
+You can use the ``--config-dir``
+
 .. _mc-install:
 
 Installation
@@ -191,77 +291,19 @@ Installation
 
 .. include:: /includes/minio-mc-installation.rst
 
-Quickstart
+:mc:`mc` includes a default :mc-cmd:`alias <mc alias>` for the
-----------
+https://play.min.io MinIO deployment. If the host machine has internet access,
-
+you can use the ``play`` alias for testing and development purposes. For
-Ensure that the host machine has :mc-cmd:`mc`
+example, the following lists all buckets on ``https://play.min.io``:
-:ref:`installed <mc-install>` prior to starting this procedure.
-
-.. important::
-
-   The following example temporarily disables the bash history to mitigate the
-   risk of authentication credentials leaking in plain text. This is a basic
-   security measure and does not mitigate all possible attack vectors. Defer to
-   security best practices for your operating system for inputting sensitive
-   information on the command line.
-
-Use the :subcommand:`mc alias add` command to add an Amazon S3-compatible host
-to the :mc-cmd:`mc` :ref:`configuration <mc-configuration>`.
 
 .. code-block:: shell
    :class: copyable
 
-   bash +o history
+   mc ls play
-   mc alias add ALIAS ENDPOINT ACCESS_KEY SECRET_KEY --api [S3v2|S3v4]
-   bash -o history
 
-- Replace ``ALIAS`` with a name to associate to the S3 service. 
+The ``play`` MinIO deployment provides a simple sandbox for testing core S3
-  :mc-cmd:`mc` commands typically require ``ALIAS`` as an argument for
+functionality. Any S3-compatible tool can view and interact with data on
-  identifying which S3 service to execute against.
+``play``. Any data stored on ``play`` is public-facing and modifyable.
-
-- Replace ``ENDPOINT`` with the URL endpoint of the S3 service.
-
-- Replace ``ACCESS_KEY`` and ``SECRET_KEY`` with the access and secret 
-  keys for the S3 service. 
-
-- The ``--api`` flag is optional and defaults to ``S3v4`` if ommitted.
-
-Replace each argument with the required values. Specifying only the 
-``mc config host add`` command starts an input prompt for entering the
-required values.
-
-Each of the following tabs contains a provider-specific example:
-
-.. tabs::
-
-   .. tab:: MinIO Server
-
-      .. code-block:: shell
-         :class: copyable
-
-         mc alias add myminio https://minioserver.example.net ACCESS_KEY SECRET KEY
-
-   .. tab:: AWS S3 Storage
-
-      .. code-block:: shell
-         :class: copyable
-
-         mc alias add myS3 https://s3.amazon.com/endpoint ACCESS_KEY SECRET KEY
-
-   .. tab:: Google Cloud Storage
-
-      .. code-block:: shell
-         :class: copyable
-
-         mc alias add myGCS https://storage.googleapis.com/endpoint ACCESS_KEY SECRET KEY
-
-Use the :command:`mc info` command to test the connection to
-the newly added MinIO deployment:
-
-.. code-block:: shell
-   :class: copyable
-
-   mc info ALIAS
 
 .. _minio-mc-global-options:
 
@@ -282,6 +324,12 @@ Global Options
 
       mc --debug ls play
 
+.. option:: --config-dir
+
+   The path to a ``JSON`` formatted configuration file that
+   :program:`mc` uses for storing data. See :ref:`mc-configuration` for
+   more information on how :program:`mc` uses the configuration file.
+
 .. option:: --JSON
 
    Enables `JSON lines <http://jsonlines.org/>`_ formatted output to the

source/security/minio-authentication-authorization.rst

@@ -1,32 +1,210 @@
-===========================
+================================
-Policy Based Access Control
+Authentication and Authorization
-===========================
+================================
 
 .. default-domain:: minio
 
 .. contents:: On This Page
    :local:
-   :depth: 1
+   :depth: 2
 
 Overview
 --------
 
-By default, MinIO servers have a single root user which derives its credentials
+*Authentication* is the process of verifying the identity of a connecting
-from an access key and secret key specified during server startup. While
+client. MinIO authentication requires providing user credentials in the form of
-these credentials are adequate for local development and evaluation, MinIO
+an access key (username) and corresponding secret key (password). The MinIO
-strongly recommends using MinIO Policy Based Access Control (PBAC) to
+deployment only grants access *if*:
-restrict user access to only the minimum set of actions and resources required
-to complete their workloads.
 
-MinIO PBAC uses IAM-compatible policy JSON documents to define rules for
+- The access key corresponds to a user on the deployment, *and*
-accessing resources on the MinIO server. You can add policies to users or groups
+- The secret key corresponds to the specified access key.
-on the MinIO server. Adding a user to a group also adds all of the group's
-policies to the user.
 
-.. _minio-security-pbac-built-in:
+*Authorization* is the process of restricting the actions and resources the
+authenticated client can perform on the deployment. MinIO uses Policy-Based
+Access Control (PBAC), where each policy describes one or more rules that
+outline the permissions of a user or group of users. MinIO supports a subset of
+:iam-docs:`IAM actions and conditions
+<reference_policies_actions-resources-contextkeys.html>` when creating policies.
+By default, MinIO *denies* access to actions or resources not explicitly
+referenced in a user's assigned or inherited policies.
+
+- For more information on MinIO user management, see 
+  :ref:`minio-auth-authz-users`.
+
+- For more information on MinIO group management, see
+  :ref:`minio-auth-authz-groups`.
+
+- For more information on MinIO policy creation, see
+  :ref:`minio-auth-authz-pbac-policies`.
+
+.. _minio-auth-authz-users:
+
+Users
+-----
+
+A *user* is an identity with associated privileges on a MinIO deployment. Each
+user consists of a unique access key (username) and corresponding secret key
+(password).  The access key and secret key support *authentication* on the MinIO
+deployment, similar to a username and password. Clients must specify both a
+valid access key (username) and the corresponding secret key (password) to
+access the MinIO deployment. 
+
+Each user can have one or more assigned :ref:`policies
+<minio-auth-authz-pbac-policies>` that explicitly list the actions and resources
+to which the user is allowed or denied access. Policies support *authorization*
+of operations on the MinIO deployment, such that clients can only perform
+an operation if the user's assigned policies allow access to both the operation
+*action* and the target *resources*.
+
+For example, consider the following table of users. Each user is assigned
+a :ref:`built-in policy <minio-auth-authz-pbac-built-in>` or
+a supported :ref:`action <minio-auth-authz-pbac-actions>`. The table
+describes a subset of operations a client could perform if authenticated
+as that user:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+   :width: 100%
+
+   * - User
+     - Policy
+     - Operations
+
+   * - ``Operations``
+     - | :userpolicy:`readwrite` on ``finance`` bucket
+       | :userpolicy:`readonly` on ``audit`` bucket
+     
+     - | ``PUT`` and ``GET`` on ``finance`` bucket.
+       | ``PUT`` on ``audit`` bucket
+
+   * - ``Auditing``
+     - | :userpolicy:`readonly` on ``audit`` bucket
+     - ``GET`` on ``audit`` bucket
+
+   * - ``Admin``
+     - :policy-action:`admin:*`
+     - All :mc-cmd:`mc admin` commands.
+
+Users also inherit permissions from their assigned :ref:`groups
+<minio-auth-authz-groups>`. A user's total set of permissions consists of their
+explicitly assigned permissions *and* the inherited permissions from each of
+their assigned groups.
+
+.. admonition:: ``Deny`` overrides ``Allow``
+   :class: note
+
+   MinIO follows the IAM policy evaluation rules where a ``Deny`` rule overrides
+   ``Allow`` rule on the same action/resource. For example, if a user has an
+   explicitly assigned policy with an ``Allow`` rule for an action/resource
+   while one of its groups has an assigned policy with a ``Deny`` rule for that
+   action/resource, MinIO would apply only the ``Deny`` rule. 
+
+   For more information on IAM policy evaluation logic, see the IAM
+   documentation on 
+   :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account 
+   <reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
+
+``root`` User
+~~~~~~~~~~~~~
+
+By default, MinIO deployments provide ``root`` user with access to all actions
+and resources on the deployment. The ``root`` user credentials are set when
+starting the ``minio`` server. When specifying the ``root`` access key and
+secret key, consider using *long, unique, and random* strings. Exercise all
+possible precautions in storing the access key and secret key, such that only
+known and trusted individuals who *require* superuser access to the deployment
+can retrieve the ``root`` credentials.
+
+- MinIO *strongly discourages* using the ``root`` user for regular client access
+  regardless of the environment (development, staging, or production).
+
+- MinIO *strongly recommends* creating users such that each client has access to
+  the minimal set of actions and resources required to perform their assigned
+  workloads. 
+
+.. _minio-auth-authz-groups:
+
+Groups
+------
+
+A *group* is a collection of :ref:`users <minio-auth-authz-users>`. Each group
+can have one or more assigned :ref:`policies <minio-auth-authz-pbac-policies>`
+that explicitly list the actions and resources to which group members are
+allowed or denied access.
+
+For example, consider the following groups. Each group is assigned a
+:ref:`built-in policy <minio-auth-authz-pbac-built-in>` or supported
+:ref:`policy action <minio-auth-authz-pbac-actions>`. Each group also has one or
+more assigned users. Each user's total set of permissions consists of their
+explicitly assigned permission *and* the inherited permissions from each of
+their assigned groups.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 40 40
+   :width: 100%
+
+   * - Group
+     - Policy
+     - Members
+
+   * - ``Operations``
+     - | :userpolicy:`readwrite` on ``finance`` bucket
+       | :userpolicy:`readonly` on ``audit`` bucket
+     
+     - ``john.doe``, ``jane.doe``
+
+   * - ``Auditing``
+     - | :userpolicy:`readonly` on ``audit`` bucket
+     - ``jen.doe``, ``joe.doe``
+
+   * - ``Admin``
+     - :policy-action:`admin:*`
+     - ``greg.doe``, ``jen.doe``
+
+Groups provide a simplified method for managing shared permissions among
+users with common access patterns and workloads. Client's *cannot* authenticate
+to a MinIO deployment using a group as an identity.
+
+.. admonition:: ``Deny`` overrides ``Allow``
+   :class: note
+
+   MinIO follows the IAM standard where a ``Deny`` rule overrides ``Allow`` rule
+   on the same action or resource. For example, if a user has an explicitly
+   assigned policy with an ``Allow`` rule for an action/resource while one of
+   its groups has an assigned policy with a ``Deny`` rule for that
+   action/resource, MinIO would apply only the ``Deny`` rule. 
+
+   For more information on IAM policy evaluation logic, see the IAM
+   documentation on 
+   :iam-docs:`Determining Whether a Request is Allowed or Denied Within an Account 
+   <reference_policies_evaluation-logic.html#policy-eval-denyallow>`.
+
+.. _minio-auth-authz-pbac-policies:
+
+Policies
+--------
+
+MinIO uses Policy-Based Access Control (PBAC) for supporting *authorization* of
+users who have successfully *authenticated* to the deployment. Each policy
+describes one or more rules that outline the permissions of a user or group of
+users. MinIO PBAC follows the guidelines and standards set by AWS Identity and
+Access Management (IAM). MinIO supports a subset of :iam-docs:`IAM actions and
+conditions <reference_policies_actions-resources-contextkeys.html>` when
+creating policies. By default, MinIO *denies* access to actions or resources not
+explicitly referenced in a user's assigned or inherited policies.
+
+This section focuses on MinIO's implementation and extensions of IAM policies
+and access management. A complete description of IAM or IAM policies is out
+of scope of this documentation. Consider deferring to the
+:iam-docs:`IAM documentation <>` for more complete documentation on the
+IAM service.
+
+.. _minio-auth-authz-pbac-built-in:
 
 Built-In Policies
------------------
+~~~~~~~~~~~~~~~~~
 
 MinIO provides the following built-in policies for assigning to users
 and groups:
@@ -49,10 +227,10 @@ and groups:
    Grants write-only permissions for all buckets and objects on the MinIO 
    server.
 
-.. _minio-security-pbac-document:
+.. _minio-auth-authz-pbac-document:
 
 Policy Document Structure
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 MinIO policy documents use the same schema as 
 :aws-docs:`AWS IAM Policy <IAM/latest/UserGuide/access.html>` documents.
@@ -84,7 +262,7 @@ policy elements, see the :aws-docs:`IAM JSON Policy Elements Reference
    }
 
 - For the ``Statement.Action`` array, specify one or more 
-  :ref:`supported S3 actions <minio-security-pbac-actions>`. MinIO deployments
+  :ref:`supported S3 actions <minio-auth-authz-pbac-actions>`. MinIO deployments
   supports a subset of AWS S3 actions.
 
 - For the ``Statement.Resource`` key, you can replace the ``*`` with 
@@ -92,13 +270,13 @@ policy elements, see the :aws-docs:`IAM JSON Policy Elements Reference
   Using ``*`` applies the statement to all resources on the MinIO deployment.
 
 - For the ``Statement.Condition`` key, you can specify one or more 
-  :ref:`supported Conditions <minio-security-pbac-conditions>`. MinIO
+  :ref:`supported Conditions <minio-auth-authz-pbac-conditions>`. MinIO
   deployments supports a subset of AWS S3 conditions.
 
-.. _minio-security-pbac-actions:
+.. _minio-auth-authz-pbac-actions:
 
 Supported Policy Actions
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 MinIO policy documents support a subset of IAM 
 :iam-docs:`S3 Action keys <list_amazons3.html#amazons3-actions-as-permissions>`. 
@@ -376,7 +554,7 @@ The following table lists the MinIO-supported policy action keys.
    <API_GetObjectVersionForReplication.html>` IAM action.
 
 
-.. _minio-security-pbac-mc-admin-actions:
+.. _minio-auth-authz-pbac-mc-admin-actions:
 
 ``mc admin`` Policy Action Keys
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -386,6 +564,10 @@ for :mc-cmd:`mc admin` operations. These actions are *only* valid for
 MinIO deployments and are *not* intended for use with other S3-compatible
 services:
 
+.. policy-action:: admin:*
+
+   Selector for all admin action keys.
+
 .. policy-action:: admin:Heal
 
    Allows heal command
@@ -530,10 +712,10 @@ services:
 
    Allows getting bucket targets
 
-.. _minio-security-pbac-conditions:
+.. _minio-auth-authz-pbac-conditions:
 
 Supported Policy Condition Keys
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 MinIO policy documents support IAM 
 :iam-docs:`conditional statements <reference_policies_elements_condition.html>`. 
@@ -546,7 +728,7 @@ information on any listed condition key, see the
 <reference_policies_elements_condition.html>`
 
 MinIO supports the following condition keys for all supported 
-:ref:`actions <minio-security-pbac-actions>`:
+:ref:`actions <minio-auth-authz-pbac-actions>`:
 
 - ``aws:Referer``
 - ``aws:SourceIp``
@@ -616,10 +798,10 @@ actions:
      - ``s3:versionid``
 
 ``mc admin`` Policy Condition Keys
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``````````````````````````````````
 
 MinIO supports the following conditions for use with defining policies for
-:mc-cmd:`mc admin` :ref:`actions <minio-security-pbac-mc-admin-actions>`.
+:mc-cmd:`mc admin` :ref:`actions <minio-auth-authz-pbac-mc-admin-actions>`.
 
 - ``aws:Referer``
 - ``aws:SourceIp``
@@ -632,7 +814,7 @@ For complete information on any listed condition key, see the :iam-docs:`IAM
 Condition Element Documentation <reference_policies_elements_condition.html>`
 
 Creating Custom Policies
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 Use the ``mc admin policy`` command to add a policy to the MinIO
 server. The policy *must* be a valid JSON document formatted according to
@@ -652,8 +834,3 @@ To add this policy to a user or group, use the ``mc admin policy set`` command:
 
    mc admin policy set myminio/ new_policy group=group_name
 
-Add Policies to a User or Group
--------------------------------
-
-Remove Policies from a User or Group
-------------------------------------

source/security/minio-security.rst

@@ -41,7 +41,7 @@ MinIO provides support for the following security features:
    :titlesonly:
    :hidden:
 
-   /security/minio-security-policy-based-access-control
+   /security/minio-authentication-authorization
    /security/minio-security-TLS-encryption
    /security/minio-security-server-side-encryption
    /security/minio-security-security-token-service 

sphinxext/minio.py

@@ -47,7 +47,7 @@ logger = logging.getLogger(__name__)
 class MinioMCCommand(SphinxDirective):
    """
    Description of a MinIO MC Command. Use this class when describing a top level
-   ``mc`` or ``mc admin`` command. ``MinioSubcommand`` objects use this
+   ``mc`` or ``mc admin`` command. ``MinioMCObjects`` objects use this
    as a prefix for linking purposes. 
    """
 
@@ -102,6 +102,7 @@ class MinioMCObject(ObjectDescription):
        'noindexentry': directives.flag,
        'fullpath': directives.flag,
        'option': directives.flag,
+       'notext': directives.flag,
     }
 
     def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str]:
@@ -153,6 +154,8 @@ class MinioMCObject(ObjectDescription):
         
         if (alias != None):
            signode += addnodes.desc_name(name + ', ' + alias, format_name + ', ' + format_alias)
+        elif 'notext' in self.options:
+           signode += addnodes.desc_name(name, '')
         else:
            signode += addnodes.desc_name(name, format_name)