diff --git a/CONTRIBUTIONS.md b/CONTRIBUTIONS.md new file mode 100644 index 00000000..1956e9a9 --- /dev/null +++ b/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 + diff --git a/source/_static/css-style.css b/source/_static/css-style.css index d8b547ed..e09bf84a 100644 --- a/source/_static/css-style.css +++ b/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 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; diff --git a/source/_static/js/main.js b/source/_static/js/main.js index e1d31c34..17c11325 100644 --- a/source/_static/js/main.js +++ b/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); diff --git a/source/conf.py b/source/conf.py index a21b08ac..a97ac0da 100644 --- a/source/conf.py +++ b/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. diff --git a/source/images/Kubernetes-Minio.svg b/source/images/Kubernetes-Minio.svg index 21803cea..1f4c037f 100644 --- a/source/images/Kubernetes-Minio.svg +++ b/source/images/Kubernetes-Minio.svg @@ -698,7 +698,7 @@ MinIo Console Server + style="shape-inside:url(#rect1738-25-1)">MinIO Console Server diff --git a/source/includes/facts-mc-admin.rst b/source/includes/facts-mc-admin.rst new file mode 100644 index 00000000..253e2ea0 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/source/includes/minio-mc-installation.rst b/source/includes/minio-mc-installation.rst index e12e4144..57911954 100644 --- a/source/includes/minio-mc-installation.rst +++ b/source/includes/minio-mc-installation.rst @@ -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 `__. - Source installation requires a working Golang environment. - See `How to install Golang `__ + 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. diff --git a/source/minio-cli/minio-mc-admin.rst b/source/minio-cli/minio-mc-admin.rst index 668e7024..b750aefa 100644 --- a/source/minio-cli/minio-mc-admin.rst +++ b/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` - - 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: diff --git a/source/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst b/source/minio-cli/minio-mc-admin/mc-admin-bucket-quota.rst new file mode 100644 index 00000000..39f03009 --- /dev/null +++ b/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 ` + Adds a hard quota of ``10GB`` to the ``mybucket`` bucket on the + MinIO deployment with the ``play`` :mc-cmd:`alias `. MinIO + rejects any ``PUT`` request that would result in the bucket exceeding + the configured quota. + +:mc-cmd:`mc admin bucket quota play/mybucket --fifo 10GB ` + Adds a hard quota of ``10GB`` to the ``mybucket`` bucket on the + MinIO deployment with the ``play`` :mc-cmd:`alias `. MinIO + removes the oldest objects on the bucket until it can satisfy the size + of an incoming ``PUT`` request. + +:mc-cmd:`mc admin bucket quota play/mybucket --clear ` + Removes all quotas from the ``mybucket`` bucket on the MinIO deployment + with the ``play`` :mc-cmd:`alias `. + +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 ` 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. + + + diff --git a/source/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst b/source/minio-cli/minio-mc-admin/mc-admin-bucket-remote.rst new file mode 100644 index 00000000..ef378f7d --- /dev/null +++ b/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 ` + Adds a new remote target ``target/mybucket`` to ``play/mybucket``, + where ``target`` and ``play`` are :mc-cmd:`aliases ` for + configured MinIO deployments. + + The command returns an ``ARN`` associated to the configured target. + :mc-cmd:`mc replicate` requires the ``ARN`` to enable replication + from a source bucket to a destination deployment and bucket. + +:mc-cmd:`mc admin bucket remote ls play/mybucket ` + Lists all remote targets for ``play/mybucket``, where + ``play`` is a :mc-cmd:`alias ` for a configured MinIO deployment. + + The command returns an ``ARN`` associated to each configured remote target. + :mc-cmd:`mc replicate` requires the ``ARN`` to enable replication + from a source bucket to a destination deployment and bucket. + +:mc-cmd:`mc admin bucket remote rm play/mybucket target/mybucket ` + Removes the remote target ``target/mybucket`` from ``play/mybucket``, + where ``target`` and ``play`` are :mc-cmd:`aliases ` for + configured MinIO deployments. + + Removing a remote target halts any in-progress bucket replication + relying on that remote target's ARN. + +Syntax +------ + +:mc-cmd:`mc admin bucket remote` has the following syntax: + +.. 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 ` 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 ` 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 + + / + + .. 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 ` 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 . Specify the + :mc-cmd:`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. + diff --git a/source/minio-cli/minio-mc-admin/mc-admin-console.rst b/source/minio-cli/minio-mc-admin/mc-admin-console.rst new file mode 100644 index 00000000..dc993594 --- /dev/null +++ b/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 ` 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) + diff --git a/source/minio-cli/minio-mc-admin/mc-admin-groups.rst b/source/minio-cli/minio-mc-admin/mc-admin-groups.rst new file mode 100644 index 00000000..cfdb7133 --- /dev/null +++ b/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 ` is a collection of :ref:`users +`. Each group can have one or more assigned +:ref:`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 +` 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 + `. + +Quick Reference +--------------- + +:mc-cmd:`mc admin group add TARGET GROUPNAME MEMBERS ` + 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 ` + Returns detailed information for a group on the MinIO deployment. + +:mc-cmd:`mc admin group list TARGET ` + Returns a list of all groups on the MinIO deployment. + +:mc-cmd:`mc admin group remove TARGET GROUPNAME ` + Removes a group on the MinIO deployment. + +:mc-cmd:`mc admin group enable TARGET GROUPNAME ` + Enables a group on the MinIO deployment. Users can only inherit + :ref:`policies ` assigned to an enabled group. + +:mc-cmd:`mc admin group disable TARGET GROUPNAME ` + Disables a group on the MinIO deployment. Users cannot inherit :ref:`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 ` 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 ` with membership in the group and the + assigned :ref:`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 ` 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 ` 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 ` 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 ` 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 ` 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 ` 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 ` of a configured MinIO deployment on which + to disable the group. + + .. mc-cmd:: GROUPNAME + + The name of the group to disable. + diff --git a/source/minio-cli/minio-mc-admin/mc-admin-heal.rst b/source/minio-cli/minio-mc-admin/mc-admin-heal.rst new file mode 100644 index 00000000..d1d76059 --- /dev/null +++ b/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 ` 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. diff --git a/source/minio-cli/minio-mc-admin/mc-admin-info.rst b/source/minio-cli/minio-mc-admin/mc-admin-info.rst index 22f97a1d..38189b13 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-info.rst +++ b/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 ------ @@ -33,19 +45,4 @@ Syntax Specify the :mc-cmd:`alias ` of a configured MinIO deployment as the ``TARGET``. :mc-cmd:`~mc admin service restart` restarts *all* MinIO servers in -the deployment. - -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 \ No newline at end of file +the deployment. \ No newline at end of file diff --git a/source/minio-cli/minio-mc-admin/mc-admin-kms.rst b/source/minio-cli/minio-mc-admin/mc-admin-kms.rst new file mode 100644 index 00000000..230f4b27 --- /dev/null +++ b/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 ` of a configured MinIO server from which + the command returns the KMS status. + +.. mc-cmd:: KEYNAME + + The name of the speciific key to return. + diff --git a/source/minio-cli/minio-mc-admin/mc-admin-obd.rst b/source/minio-cli/minio-mc-admin/mc-admin-obd.rst new file mode 100644 index 00000000..98785701 --- /dev/null +++ b/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 ` 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``. + diff --git a/source/minio-cli/minio-mc-admin/mc-admin-policy.rst b/source/minio-cli/minio-mc-admin/mc-admin-policy.rst index 523c1400..8bed1db0 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-policy.rst +++ b/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 -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: +:mc-cmd:`mc admin policy add TARGET POLICYNAME POLICYFILE ` + Creates a new policy on the target MinIO deployment. -- :userpolicy:`readonly` -- :userpolicy:`readwrite` -- :userpolicy:`diagnostics` -- :userpolicy:`writeonly` + .. code-block:: shell + :class: copyable -To apply a built-in policy to a user or group, use the -:mc-cmd:`mc admin policy set` command: + mc admin policy add play myNewPolicy /path/to/policy.json -.. code-block:: shell - :class: copyable +:mc-cmd:`mc admin policy list TARGET ` + Lists the available policies on the target MinIO deployment. - mc admin policy set myminio myReadOnlyPolicy readOnlyUser + .. code-block:: shell + :class: copyable + + mc admin policy list play - mc admin policy set myminio myReadWritePolicy readWriteGroup +:mc-cmd:`mc admin policy info TARGET POLICYNAME ` + Returns the policy in JSON format from 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 info play myNewPolicy + +:mc-cmd:`mc admin policy set TARGET POLICYNAME user=|group= ` + 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 ` + 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 ```` with the name of a user that exists on the deployment. .. code-block:: shell :class: copyable + mc admin policy set myminio listbucketsonly user= + +The following :mc-cmd:`mc admin policy set` command associates the +``listbucketsonly`` policy to a group on the ``myminio`` MinIO deployment. +Replace the ```` with the name of a user that exists on the deployment. + +.. code-block:: shell + :class: copyable + + mc admin policy set myminio listbucketsonly 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,12 +316,21 @@ 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 + ` policies by default: + + - :userpolicy:`readonly` + - :userpolicy:`readwrite` + - :userpolicy:`diagnostics` + - :userpolicy:`writeonly` .. mc-cmd:: user The name of the user to which the command associates the - :mc-cmd:`~mc admin policy set POLICYNAME`. + :mc-cmd:`~mc admin policy set POLICYNAME`. Mutually exclusive with :mc-cmd:`~mc admin policy set GROUP` @@ -299,7 +358,7 @@ Syntax .. mc-cmd:: TARGET The :mc-cmd:`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 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-profile.rst b/source/minio-cli/minio-mc-admin/mc-admin-profile.rst new file mode 100644 index 00000000..76aa1b15 --- /dev/null +++ b/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 `__ ``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/ ` + Starts profiling data related to ``cpu`` statistics + on the ``myminio`` :mc-cmd:`alias `. + +:mc-cmd:`mc admin profile start --type "cpu,mem,block" myminio/ ` + Starts profiling data related to ``cpu``, ``mem``, and ``block`` statistics + on the ``myminio`` :mc-cmd:`alias `. + +:mc-cmd:`mc admin profile stop myminio/ ` + Stops profiling data on the ``myminio`` :mc-cmd:`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 ` 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 `__ 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 ` of a configured MinIO deployment from + which the command returns available profiling data. + + + diff --git a/source/minio-cli/minio-mc-admin/mc-admin-prometheus.rst b/source/minio-cli/minio-mc-admin/mc-admin-prometheus.rst new file mode 100644 index 00000000..2f599bd2 --- /dev/null +++ b/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 `__. + +.. 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 +` + +.. 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 ` of a configured MinIO deployment for which + the command generates a Prometheus-compatible configuration file. + diff --git a/source/minio-cli/minio-mc-admin/mc-admin-service.rst b/source/minio-cli/minio-mc-admin/mc-admin-service.rst index ed9a41c4..7ae9fe72 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-service.rst +++ b/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 \ No newline at end of file diff --git a/source/minio-cli/minio-mc-admin/mc-admin-top.rst b/source/minio-cli/minio-mc-admin/mc-admin-top.rst new file mode 100644 index 00000000..7f5d3640 --- /dev/null +++ b/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 ` of a configured MinIO deployment from which + the command retrieves statistics. + + The alias *must* correspond to a distributed (multi-node) MinIO deployment. + The command returns an error for standalone MinIO deployments or MinIO + Gateway deployments. + + diff --git a/source/minio-cli/minio-mc-admin/mc-admin-trace.rst b/source/minio-cli/minio-mc-admin/mc-admin-trace.rst new file mode 100644 index 00000000..83a13cfa --- /dev/null +++ b/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 `__ +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 ` 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. diff --git a/source/minio-cli/minio-mc-admin/mc-admin-update.rst b/source/minio-cli/minio-mc-admin/mc-admin-update.rst index 40d59b05..3b23861e 100644 --- a/source/minio-cli/minio-mc-admin/mc-admin-update.rst +++ b/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 diff --git a/source/minio-cli/minio-mc-admin/mc-admin-user.rst b/source/minio-cli/minio-mc-admin/mc-admin-user.rst new file mode 100644 index 00000000..769cebb9 --- /dev/null +++ b/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 +` 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 + `. + +Quick Reference +--------------- + +:mc-cmd:`mc admin user add TARGET ACCESSKEY SECRETKEY ` + 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 ` + Lists all users on a MinIO deployment. + + .. code-block:: shell + :class: copyable + + mc admin user list play + +:mc-cmd:`mc admin user info TARGET USERNAME ` + Returns detailed information for a user on a MinIO deployment. + + .. code-block:: shell + :class: copyable + + mc admin user info play myNewUser + +:mc-cmd:`mc admin user remove TARGET USERNAME ` + Removes a user from a MinIO deployment. + + .. code-block:: shell + :class: copyable + + mc admin user remove play myNewUser + +:mc-cmd:`mc admin user enable TARGET USERNAME ` + Enables a user on a MinIO deployment. + + .. code-block:: shell + :class: copyable + + mc admin user enable play myNewUser + +:mc-cmd:`mc admin user disable TARGET USERNAME ` + Disables a user on a MinIO deployment. + + .. code-block:: shell + :class: copyable + + mc admin user disable play myNewUser + +Syntax +------ + +:mc-cmd:`mc admin user` has the following syntax: + +.. 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 ` 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 ` 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 ` of a configured MinIO deployment from + which the command retrieves the specified user information. + + .. mc-cmd:: USERNAME + + The username (:mc-cmd:`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 ` of a configured MinIO deployment on which + the command removes the specified user. + + .. mc-cmd:: USERNAME + + The username (:mc-cmd:`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 ` of a configured MinIO deployment on which + the command disables the specified user. + + .. mc-cmd:: USERNAME + + The username (:mc-cmd:`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 ` of a configured MinIO deployment on which + the command enables the specified user. + + .. mc-cmd:: USERNAME + + The username (:mc-cmd:`ACCESSKEY `) for + the user to enable. diff --git a/source/minio-cli/minio-mc.rst b/source/minio-cli/minio-mc.rst index 4b0ce53f..1930d885 100644 --- a/source/minio-cli/minio-mc.rst +++ b/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 ` 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 `. + +.. 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 ` 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 ` 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:`mc` includes a default :mc-cmd:`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 `_ formatted output to the diff --git a/source/security/minio-security-policy-based-access-control.rst b/source/security/minio-authentication-authorization.rst similarity index 65% rename from source/security/minio-security-policy-based-access-control.rst rename to source/security/minio-authentication-authorization.rst index e7aa287b..37228775 100644 --- a/source/security/minio-security-policy-based-access-control.rst +++ b/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 -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 +` 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 +` 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 ` or +a supported :ref:`action `. 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 +`. 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 + `. + +``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 `. Each group +can have one or more assigned :ref:`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 ` or supported +:ref:`policy action `. 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 + `. + +.. _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 ` 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 ` 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 deployments + :ref:`supported S3 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 + :ref:`supported 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 `. @@ -376,7 +554,7 @@ The following table lists the MinIO-supported policy action keys. ` 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 `. @@ -546,7 +728,7 @@ information on any listed condition key, see the ` MinIO supports the following condition keys for all supported -:ref:`actions `: +:ref:`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 `. +:mc-cmd:`mc admin` :ref:`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 ` 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 ------------------------------------- \ No newline at end of file diff --git a/source/security/minio-security.rst b/source/security/minio-security.rst index 56224a2f..c2ed00b5 100644 --- a/source/security/minio-security.rst +++ b/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 diff --git a/sphinxext/minio.py b/sphinxext/minio.py index ec0d2d8c..bbfbee6d 100644 --- a/sphinxext/minio.py +++ b/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)