minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-28 19:42:10 +03:00
Code Activity

Trying new page structure. See mc-admin-policy

Browse Source
This commit is contained in:
ravindk89
2020-08-14 19:33:44 -04:00
parent aa832e1d2f
commit 1c7ce6a9e2
28 changed files with 2129 additions and 294 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
CONTRIBUTIONS.md Normal file
View File

@ -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

23
source/_static/css-style.css
View File

@ -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 50ms ease-in-out;
transition: all 10ms 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;

15
source/_static/js/main.js
View File

@ -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);

1
source/conf.py
View File

@ -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.

2
source/images/Kubernetes-Minio.svg
View File

@ -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">

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 53 KiB

After

Width:  |  Height:  |  Size: 53 KiB

7
source/includes/facts-mc-admin.rst Normal file
View File

@ -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

24
source/includes/minio-mc-installation.rst
View File

@ -82,12 +82,12 @@
.. tab:: Source
Source installation is intended for developers and advanced users. The
:mc-cmd:`mc admin update` command does not support updating source-based
installations.
Installation from source is intended for developers and advanced users
and requires a working Golang environment. See
`How to install Golang <https://golang.org/doc/install>`__.
Source installation requires a working Golang environment.
See `How to install Golang <https://golang.org/doc/install>`__
Run the following commands in a terminal environment to install ``mc``
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
and development under the ``play`` alias. If the host machine has access to
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``:
To update a source-based installation, use ``go get -u``.
:mc-cmd:`mc update` does not support source-based installations.
.. 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.

6
source/minio-cli/minio-mc-admin.rst
View File

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

146
source/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst Normal file
View File

@ -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.

217
source/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst Normal file
View File

@ -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.

66
source/minio-cli/minio-mc-admin/mc-admin-console.rst Normal file
View File

@ -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)

250
source/minio-cli/minio-mc-admin/mc-admin-groups.rst Normal file
View File

@ -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.

94
source/minio-cli/minio-mc-admin/mc-admin-heal.rst Normal file
View File

@ -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.

27
source/minio-cli/minio-mc-admin/mc-admin-info.rst
View File

@ -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

51
source/minio-cli/minio-mc-admin/mc-admin-kms.rst Normal file
View File

@ -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.

58
source/minio-cli/minio-mc-admin/mc-admin-obd.rst Normal file
View File

@ -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``.

203
source/minio-cli/minio-mc-admin/mc-admin-policy.rst
View File

@ -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
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.
Quick Reference
---------------
MinIO strongly recommends using :mc-cmd:`mc admin policy` to configure PBAC
such that applications have the minimal set of privileges required for
completing their workloads. MinIO provides :ref:`minio-security-pbac-built-in`
policies as a baseline for configuring PBAC:
- :userpolicy:`readonly`
- :userpolicy:`readwrite`
- :userpolicy:`diagnostics`
- :userpolicy:`writeonly`
To apply a built-in policy to a user or group, use the
:mc-cmd:`mc admin policy set` command:
:mc-cmd:`mc admin policy add TARGET POLICYNAME POLICYFILE <mc admin policy add>`
Creates a new policy on the target MinIO deployment.
.. code-block:: shell
:class: copyable
mc admin policy set myminio myReadOnlyPolicy readOnlyUser
mc admin policy add play myNewPolicy /path/to/policy.json
mc admin policy set myminio myReadWritePolicy readWriteGroup
:mc-cmd:`mc admin policy list TARGET <mc admin policy list>`
Lists the available policies on the target MinIO deployment.
For more information on creating users and groups, see
:mc-cmd:`mc admin users` and :mc-cmd:`mc admin groups` respectively.
.. code-block:: shell
:class: copyable
mc admin policy list play
:mc-cmd:`mc admin policy info TARGET POLICYNAME <mc admin policy info>`
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
:end-before: end-play-alias-only
:start-after: myminio-alias
: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
:end-before: end-play-alias-only
:start-after: myminio-alias
: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
:end-before: end-play-alias-only
:start-after: myminio-alias
: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
target MinIO deployment. The command has the following syntax:
Applies an existing policy to a user or group on the
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

122
source/minio-cli/minio-mc-admin/mc-admin-profile.rst Normal file
View File

@ -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.

51
source/minio-cli/minio-mc-admin/mc-admin-prometheus.rst Normal file
View File

@ -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.

94
source/minio-cli/minio-mc-admin/mc-admin-service.rst
View File

@ -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

54
source/minio-cli/minio-mc-admin/mc-admin-top.rst Normal file
View File

@ -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.

62
source/minio-cli/minio-mc-admin/mc-admin-trace.rst Normal file
View File

@ -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.

45
source/minio-cli/minio-mc-admin/mc-admin-update.rst
View File

@ -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

281
source/minio-cli/minio-mc-admin/mc-admin-user.rst Normal file
View File

@ -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.

186
source/minio-cli/minio-mc.rst
View File

@ -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
``--config-dir`` flag to specify a path to a ``JSON`` formatted configuration file.
:mc-cmd:`mc` uses a ``JSON`` formatted configuration file used for storing
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
----------
Ensure that the host machine has :mc-cmd:`mc`
: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>`.
: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
example, the following lists all buckets on ``https://play.min.io``:
.. code-block:: shell
:class: copyable
bash +o history
mc alias add ALIAS ENDPOINT ACCESS_KEY SECRET_KEY --api [S3v2|S3v4]
bash -o history
mc ls play
- 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 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
The ``play`` MinIO deployment provides a simple sandbox for testing core S3
functionality. Any S3-compatible tool can view and interact with data on
``play``. Any data stored on ``play`` is public-facing and modifyable.
.. _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

245
source/security/minio-security-policy-based-access-control.rst → source/security/minio-authentication-authorization.rst
View File

@ -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
from an access key and secret key specified during server startup. While
these credentials are adequate for local development and evaluation, MinIO
strongly recommends using MinIO Policy Based Access Control (PBAC) to
restrict user access to only the minimum set of actions and resources required
to complete their workloads.
*Authentication* is the process of verifying the identity of a connecting
client. MinIO authentication requires providing user credentials in the form of
an access key (username) and corresponding secret key (password). The MinIO
deployment only grants access *if*:
MinIO PBAC uses IAM-compatible policy JSON documents to define rules for
accessing resources on the MinIO server. You can add policies to users or groups
on the MinIO server. Adding a user to a group also adds all of the group's
policies to the user.
- The access key corresponds to a user on the deployment, *and*
- The secret key corresponds to the specified access key.
.. _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
------------------------------------

2
source/security/minio-security.rst
View File

@ -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

5
sphinxext/minio.py
View File

@ -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)