mirror of
https://github.com/minio/docs.git
synced 2025-07-28 19:42:10 +03:00
Initial Commit (not yet MVP 1.0)
This commit is contained in:
ravindk89
13
.gitignore
vendored
Normal file
13
.gitignore
vendored
Normal file
@ -0,0 +1,13 @@
|
|||||||
|
# Ignore build directory
|
||||||
|
build
|
||||||
|
|
||||||
|
# Ignore venv
|
||||||
|
venv
|
||||||
|
|
||||||
|
# Ignore vscode
|
||||||
|
|
||||||
|
.vscode
|
||||||
|
|
||||||
|
# ignore pycache
|
||||||
|
|
||||||
|
__pycache__
|
||||||
202
LICENSE
Normal file
202
LICENSE
Normal file
@ -0,0 +1,202 @@
|
|||||||
|
|
||||||
|
Apache License
|
||||||
|
Version 2.0, January 2004
|
||||||
|
http://www.apache.org/licenses/
|
||||||
|
|
||||||
|
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||||
|
|
||||||
|
1. Definitions.
|
||||||
|
|
||||||
|
"License" shall mean the terms and conditions for use, reproduction,
|
||||||
|
and distribution as defined by Sections 1 through 9 of this document.
|
||||||
|
|
||||||
|
"Licensor" shall mean the copyright owner or entity authorized by
|
||||||
|
the copyright owner that is granting the License.
|
||||||
|
|
||||||
|
"Legal Entity" shall mean the union of the acting entity and all
|
||||||
|
other entities that control, are controlled by, or are under common
|
||||||
|
control with that entity. For the purposes of this definition,
|
||||||
|
"control" means (i) the power, direct or indirect, to cause the
|
||||||
|
direction or management of such entity, whether by contract or
|
||||||
|
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||||
|
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||||
|
|
||||||
|
"You" (or "Your") shall mean an individual or Legal Entity
|
||||||
|
exercising permissions granted by this License.
|
||||||
|
|
||||||
|
"Source" form shall mean the preferred form for making modifications,
|
||||||
|
including but not limited to software source code, documentation
|
||||||
|
source, and configuration files.
|
||||||
|
|
||||||
|
"Object" form shall mean any form resulting from mechanical
|
||||||
|
transformation or translation of a Source form, including but
|
||||||
|
not limited to compiled object code, generated documentation,
|
||||||
|
and conversions to other media types.
|
||||||
|
|
||||||
|
"Work" shall mean the work of authorship, whether in Source or
|
||||||
|
Object form, made available under the License, as indicated by a
|
||||||
|
copyright notice that is included in or attached to the work
|
||||||
|
(an example is provided in the Appendix below).
|
||||||
|
|
||||||
|
"Derivative Works" shall mean any work, whether in Source or Object
|
||||||
|
form, that is based on (or derived from) the Work and for which the
|
||||||
|
editorial revisions, annotations, elaborations, or other modifications
|
||||||
|
represent, as a whole, an original work of authorship. For the purposes
|
||||||
|
of this License, Derivative Works shall not include works that remain
|
||||||
|
separable from, or merely link (or bind by name) to the interfaces of,
|
||||||
|
the Work and Derivative Works thereof.
|
||||||
|
|
||||||
|
"Contribution" shall mean any work of authorship, including
|
||||||
|
the original version of the Work and any modifications or additions
|
||||||
|
to that Work or Derivative Works thereof, that is intentionally
|
||||||
|
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||||
|
or by an individual or Legal Entity authorized to submit on behalf of
|
||||||
|
the copyright owner. For the purposes of this definition, "submitted"
|
||||||
|
means any form of electronic, verbal, or written communication sent
|
||||||
|
to the Licensor or its representatives, including but not limited to
|
||||||
|
communication on electronic mailing lists, source code control systems,
|
||||||
|
and issue tracking systems that are managed by, or on behalf of, the
|
||||||
|
Licensor for the purpose of discussing and improving the Work, but
|
||||||
|
excluding communication that is conspicuously marked or otherwise
|
||||||
|
designated in writing by the copyright owner as "Not a Contribution."
|
||||||
|
|
||||||
|
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||||
|
on behalf of whom a Contribution has been received by Licensor and
|
||||||
|
subsequently incorporated within the Work.
|
||||||
|
|
||||||
|
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
copyright license to reproduce, prepare Derivative Works of,
|
||||||
|
publicly display, publicly perform, sublicense, and distribute the
|
||||||
|
Work and such Derivative Works in Source or Object form.
|
||||||
|
|
||||||
|
3. Grant of Patent License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
(except as stated in this section) patent license to make, have made,
|
||||||
|
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||||
|
where such license applies only to those patent claims licensable
|
||||||
|
by such Contributor that are necessarily infringed by their
|
||||||
|
Contribution(s) alone or by combination of their Contribution(s)
|
||||||
|
with the Work to which such Contribution(s) was submitted. If You
|
||||||
|
institute patent litigation against any entity (including a
|
||||||
|
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||||
|
or a Contribution incorporated within the Work constitutes direct
|
||||||
|
or contributory patent infringement, then any patent licenses
|
||||||
|
granted to You under this License for that Work shall terminate
|
||||||
|
as of the date such litigation is filed.
|
||||||
|
|
||||||
|
4. Redistribution. You may reproduce and distribute copies of the
|
||||||
|
Work or Derivative Works thereof in any medium, with or without
|
||||||
|
modifications, and in Source or Object form, provided that You
|
||||||
|
meet the following conditions:
|
||||||
|
|
||||||
|
(a) You must give any other recipients of the Work or
|
||||||
|
Derivative Works a copy of this License; and
|
||||||
|
|
||||||
|
(b) You must cause any modified files to carry prominent notices
|
||||||
|
stating that You changed the files; and
|
||||||
|
|
||||||
|
(c) You must retain, in the Source form of any Derivative Works
|
||||||
|
that You distribute, all copyright, patent, trademark, and
|
||||||
|
attribution notices from the Source form of the Work,
|
||||||
|
excluding those notices that do not pertain to any part of
|
||||||
|
the Derivative Works; and
|
||||||
|
|
||||||
|
(d) If the Work includes a "NOTICE" text file as part of its
|
||||||
|
distribution, then any Derivative Works that You distribute must
|
||||||
|
include a readable copy of the attribution notices contained
|
||||||
|
within such NOTICE file, excluding those notices that do not
|
||||||
|
pertain to any part of the Derivative Works, in at least one
|
||||||
|
of the following places: within a NOTICE text file distributed
|
||||||
|
as part of the Derivative Works; within the Source form or
|
||||||
|
documentation, if provided along with the Derivative Works; or,
|
||||||
|
within a display generated by the Derivative Works, if and
|
||||||
|
wherever such third-party notices normally appear. The contents
|
||||||
|
of the NOTICE file are for informational purposes only and
|
||||||
|
do not modify the License. You may add Your own attribution
|
||||||
|
notices within Derivative Works that You distribute, alongside
|
||||||
|
or as an addendum to the NOTICE text from the Work, provided
|
||||||
|
that such additional attribution notices cannot be construed
|
||||||
|
as modifying the License.
|
||||||
|
|
||||||
|
You may add Your own copyright statement to Your modifications and
|
||||||
|
may provide additional or different license terms and conditions
|
||||||
|
for use, reproduction, or distribution of Your modifications, or
|
||||||
|
for any such Derivative Works as a whole, provided Your use,
|
||||||
|
reproduction, and distribution of the Work otherwise complies with
|
||||||
|
the conditions stated in this License.
|
||||||
|
|
||||||
|
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||||
|
any Contribution intentionally submitted for inclusion in the Work
|
||||||
|
by You to the Licensor shall be under the terms and conditions of
|
||||||
|
this License, without any additional terms or conditions.
|
||||||
|
Notwithstanding the above, nothing herein shall supersede or modify
|
||||||
|
the terms of any separate license agreement you may have executed
|
||||||
|
with Licensor regarding such Contributions.
|
||||||
|
|
||||||
|
6. Trademarks. This License does not grant permission to use the trade
|
||||||
|
names, trademarks, service marks, or product names of the Licensor,
|
||||||
|
except as required for reasonable and customary use in describing the
|
||||||
|
origin of the Work and reproducing the content of the NOTICE file.
|
||||||
|
|
||||||
|
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||||
|
agreed to in writing, Licensor provides the Work (and each
|
||||||
|
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||||
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||||
|
implied, including, without limitation, any warranties or conditions
|
||||||
|
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||||
|
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||||
|
appropriateness of using or redistributing the Work and assume any
|
||||||
|
risks associated with Your exercise of permissions under this License.
|
||||||
|
|
||||||
|
8. Limitation of Liability. In no event and under no legal theory,
|
||||||
|
whether in tort (including negligence), contract, or otherwise,
|
||||||
|
unless required by applicable law (such as deliberate and grossly
|
||||||
|
negligent acts) or agreed to in writing, shall any Contributor be
|
||||||
|
liable to You for damages, including any direct, indirect, special,
|
||||||
|
incidental, or consequential damages of any character arising as a
|
||||||
|
result of this License or out of the use or inability to use the
|
||||||
|
Work (including but not limited to damages for loss of goodwill,
|
||||||
|
work stoppage, computer failure or malfunction, or any and all
|
||||||
|
other commercial damages or losses), even if such Contributor
|
||||||
|
has been advised of the possibility of such damages.
|
||||||
|
|
||||||
|
9. Accepting Warranty or Additional Liability. While redistributing
|
||||||
|
the Work or Derivative Works thereof, You may choose to offer,
|
||||||
|
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||||
|
or other liability obligations and/or rights consistent with this
|
||||||
|
License. However, in accepting such obligations, You may act only
|
||||||
|
on Your own behalf and on Your sole responsibility, not on behalf
|
||||||
|
of any other Contributor, and only if You agree to indemnify,
|
||||||
|
defend, and hold each Contributor harmless for any liability
|
||||||
|
incurred by, or claims asserted against, such Contributor by reason
|
||||||
|
of your accepting any such warranty or additional liability.
|
||||||
|
|
||||||
|
END OF TERMS AND CONDITIONS
|
||||||
|
|
||||||
|
APPENDIX: How to apply the Apache License to your work.
|
||||||
|
|
||||||
|
To apply the Apache License to your work, attach the following
|
||||||
|
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||||
|
replaced with your own identifying information. (Don't include
|
||||||
|
the brackets!) The text should be enclosed in the appropriate
|
||||||
|
comment syntax for the file format. We also recommend that a
|
||||||
|
file or class name and description of purpose be included on the
|
||||||
|
same "printed page" as the copyright notice for easier
|
||||||
|
identification within third-party archives.
|
||||||
|
|
||||||
|
Copyright [yyyy] [name of copyright owner]
|
||||||
|
|
||||||
|
Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
you may not use this file except in compliance with the License.
|
||||||
|
You may obtain a copy of the License at
|
||||||
|
|
||||||
|
http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
|
||||||
|
Unless required by applicable law or agreed to in writing, software
|
||||||
|
distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
See the License for the specific language governing permissions and
|
||||||
|
limitations under the License.
|
||||||
20
Makefile
Normal file
20
Makefile
Normal file
@ -0,0 +1,20 @@
|
|||||||
|
# Minimal makefile for Sphinx documentation
|
||||||
|
#
|
||||||
|
|
||||||
|
# You can set these variables from the command line, and also
|
||||||
|
# from the environment for the first two.
|
||||||
|
SPHINXOPTS ?=
|
||||||
|
SPHINXBUILD ?= sphinx-build
|
||||||
|
SOURCEDIR = source
|
||||||
|
BUILDDIR = build
|
||||||
|
|
||||||
|
# Put it first so that "make" without argument is like "make help".
|
||||||
|
help:
|
||||||
|
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||||
|
|
||||||
|
.PHONY: help Makefile
|
||||||
|
|
||||||
|
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||||
|
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||||
|
%: Makefile
|
||||||
|
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||||
52
README.md
Normal file
52
README.md
Normal file
@ -0,0 +1,52 @@
|
|||||||
|
#Requirements
|
||||||
|
|
||||||
|
Python3 (any version should be fine, latest is ideal)
|
||||||
|
|
||||||
|
Suggest creating a virtual environment to keep things clean and simple:
|
||||||
|
|
||||||
|
Start by cloning the repository. `cd` into the cloned repo and `git checkout dev`. You might need to `git fetch` to refresh the repo.
|
||||||
|
|
||||||
|
Once in the repository root, run the following.
|
||||||
|
|
||||||
|
```shell
|
||||||
|
|
||||||
|
python3 -m venv venv
|
||||||
|
|
||||||
|
source venv/bin/activate
|
||||||
|
|
||||||
|
pip3 install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
To make the build, do:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
make html
|
||||||
|
```
|
||||||
|
|
||||||
|
Artifacts output to the `build/` directory as HTML. Just open `index.html` to get started poking around.
|
||||||
|
|
||||||
|
If you modify things, I suggest doing clean builds to make sure all artifacts are fresh:
|
||||||
|
|
||||||
|
```shell
|
||||||
|
rm -rf build/ && make html
|
||||||
|
```
|
||||||
|
|
||||||
|
Still need to work out deployment steps, but this should work for testing locally.
|
||||||
|
|
||||||
|
The `source` directory contains all of the source files, including css and js.
|
||||||
|
|
||||||
|
The `sphinxext` directory contains some python stuff related to the custom directive/roles, and its a rats nest right now.
|
||||||
|
|
||||||
|
#TODO
|
||||||
|
|
||||||
|
- Finish the remainder of the `mc`, `mc admin`, and `minio` reference material
|
||||||
|
- Refine structure of reference pages
|
||||||
|
- Transition all MinIO Features from legacy documentation and format for RST
|
||||||
|
- Flesh out Kubernetes section (pending operator/plugin work completion)
|
||||||
|
- Flesh out introduction / concepts section
|
||||||
|
- Re-write security docs
|
||||||
|
- Create references for KES, Sidekick, MCS, Gateway
|
||||||
|
- Transition cookbook material as needed
|
||||||
|
- Flesh out Baremetal deployment section
|
||||||
|
- Scan for any remaining legacy material that needs migration
|
||||||
|
|
||||||
35
make.bat
Normal file
35
make.bat
Normal file
@ -0,0 +1,35 @@
|
|||||||
|
@ECHO OFF
|
||||||
|
|
||||||
|
pushd %~dp0
|
||||||
|
|
||||||
|
REM Command file for Sphinx documentation
|
||||||
|
|
||||||
|
if "%SPHINXBUILD%" == "" (
|
||||||
|
set SPHINXBUILD=sphinx-build
|
||||||
|
)
|
||||||
|
set SOURCEDIR=source
|
||||||
|
set BUILDDIR=build
|
||||||
|
|
||||||
|
if "%1" == "" goto help
|
||||||
|
|
||||||
|
%SPHINXBUILD% >NUL 2>NUL
|
||||||
|
if errorlevel 9009 (
|
||||||
|
echo.
|
||||||
|
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
|
||||||
|
echo.installed, then set the SPHINXBUILD environment variable to point
|
||||||
|
echo.to the full path of the 'sphinx-build' executable. Alternatively you
|
||||||
|
echo.may add the Sphinx directory to PATH.
|
||||||
|
echo.
|
||||||
|
echo.If you don't have Sphinx installed, grab it from
|
||||||
|
echo.http://sphinx-doc.org/
|
||||||
|
exit /b 1
|
||||||
|
)
|
||||||
|
|
||||||
|
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||||
|
goto end
|
||||||
|
|
||||||
|
:help
|
||||||
|
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
|
||||||
|
|
||||||
|
:end
|
||||||
|
popd
|
||||||
5
requirements.txt
Normal file
5
requirements.txt
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
sphinx == 3.1.2
|
||||||
|
sphinx-copybutton == 0.2.12
|
||||||
|
git+https://github.com/ravindk89/sphinx-tabs
|
||||||
|
recommonmark == 0.6.0
|
||||||
|
sphinx-markdown-tables == 0.0.15
|
||||||
231
source/_static/css-style.css
Normal file
231
source/_static/css-style.css
Normal file
@ -0,0 +1,231 @@
|
|||||||
|
@font-face {
|
||||||
|
font-family: "Mark";
|
||||||
|
src: url("fonts/Mark-Regular.woff2") format("woff2"),
|
||||||
|
url("fonts/Mark-Regular.woff") format("woff");
|
||||||
|
font-weight: normal;
|
||||||
|
font-style: normal;
|
||||||
|
}
|
||||||
|
|
||||||
|
:root {
|
||||||
|
--table-border-color: #e6e6e6;
|
||||||
|
}
|
||||||
|
|
||||||
|
body {
|
||||||
|
font-family: Mark, Helvetica, sans-serif;
|
||||||
|
font-size: 100%;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.body {
|
||||||
|
min-width: 500px;
|
||||||
|
max-width: 600px;
|
||||||
|
margin: 0 0 0 300px;
|
||||||
|
position: relative;
|
||||||
|
z-index: 0;
|
||||||
|
padding-top: 10px;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.body p {
|
||||||
|
font-size: 90%;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.admonition {
|
||||||
|
font-family: Mark, Helvetica, sans-serif;
|
||||||
|
border-left: 5px solid #c72e49;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.admonition p.admonition-title {
|
||||||
|
font-family: Mark, Helvetica, sans-serif;
|
||||||
|
text-transform: uppercase;
|
||||||
|
font-size: 100%;
|
||||||
|
font-weight: bold;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.body h1,
|
||||||
|
div.body h2,
|
||||||
|
div.body h3,
|
||||||
|
div.body h4,
|
||||||
|
div.body h5,
|
||||||
|
div.body h6 {
|
||||||
|
font-family: Mark, sans-serif;
|
||||||
|
font-weight: normal;
|
||||||
|
margin: 30px 0px 10px 0px;
|
||||||
|
padding: 0;
|
||||||
|
color: #c72e49;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.sphinxsidebar {
|
||||||
|
width: 300px;
|
||||||
|
font-size: 80%;
|
||||||
|
line-height: 1.5;
|
||||||
|
box-shadow: 5px 5px 5px #e6e6e6;
|
||||||
|
height: 100%;
|
||||||
|
z-index: 1
|
||||||
|
}
|
||||||
|
|
||||||
|
div.sphinxsidebar h3,
|
||||||
|
div.sphinxsidebar h4 {
|
||||||
|
font-family: Mark, sans-serif;
|
||||||
|
font-size: 24px;
|
||||||
|
font-weight: normal;
|
||||||
|
margin: 0 0 5px 0;
|
||||||
|
padding: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.document {
|
||||||
|
margin: 0 0 0 0;
|
||||||
|
width: 100%;
|
||||||
|
position: relative;
|
||||||
|
top: 75px;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.topic {
|
||||||
|
background-color: #edf7f71A;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.localtoc {
|
||||||
|
position: fixed;
|
||||||
|
top: 75px;
|
||||||
|
right: 0px;
|
||||||
|
margin-right: 18px;
|
||||||
|
min-width: 200px;
|
||||||
|
max-width: 250px;
|
||||||
|
font-size: 90%;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.localtoc ul {
|
||||||
|
list-style: none;
|
||||||
|
margin: 0px 10px;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.localtoc ul li {
|
||||||
|
padding: 2px 0px;
|
||||||
|
transition: all 50ms ease-in-out;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.localtoc ul li.active {
|
||||||
|
color: #c72e49;
|
||||||
|
position: relative;
|
||||||
|
border-left: 5px solid #c72e49;
|
||||||
|
padding-left: 5px;
|
||||||
|
margin-left: -10px;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
div.body a {
|
||||||
|
color: #c72e49;
|
||||||
|
text-decoration: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.body :target {
|
||||||
|
scroll-margin-top: 75px;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.body a.reference.internal code {
|
||||||
|
color: #c72e49;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.sphinxsidebar a.current.reference.internal {
|
||||||
|
color: #c72e49;
|
||||||
|
font-weight: bold;
|
||||||
|
position: relative;
|
||||||
|
border-left: 5px solid #c72e49;
|
||||||
|
padding-left: 5px;
|
||||||
|
margin-left: -10px;
|
||||||
|
|
||||||
|
}
|
||||||
|
|
||||||
|
div.contents.local.topic a{
|
||||||
|
border-bottom: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.sphinxsidebar a.reference.internal {
|
||||||
|
margin: 10px 0px 10px 0px;
|
||||||
|
display: block;
|
||||||
|
border-bottom: 0px;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.sphinxsidebar a:hover {
|
||||||
|
text-decoration: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
img.logo {
|
||||||
|
height: 120px;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.sphinxsidebar ul ul {
|
||||||
|
list-style: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
dt {
|
||||||
|
font-weight: bold;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.body table.docutils {
|
||||||
|
border-color: var(--table-border-color);
|
||||||
|
}
|
||||||
|
|
||||||
|
div.body div.alert-info {
|
||||||
|
|
||||||
|
background-color:#c72e491a;
|
||||||
|
padding-left: 5px;
|
||||||
|
padding-right: 5px;
|
||||||
|
border: 2px #c72e49 solid;
|
||||||
|
border-radius: 10px;
|
||||||
|
|
||||||
|
}
|
||||||
|
|
||||||
|
div.body div.alert-info p {
|
||||||
|
text-align: center;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.body table.docutils th {
|
||||||
|
border-top: 1px solid var(--table-border-color);
|
||||||
|
border-bottom: 1px solid var(--table-border-color);
|
||||||
|
border-left: none;
|
||||||
|
border-right: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.body table.docutils td {
|
||||||
|
border-top: 1px solid var(--table-border-color);
|
||||||
|
border-bottom: 1px solid var(--table-border-color);
|
||||||
|
border-left: none;
|
||||||
|
border-right: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.header {
|
||||||
|
background-color: #01262e;
|
||||||
|
height: 75px;
|
||||||
|
width: 100%;
|
||||||
|
position: fixed;
|
||||||
|
z-index: 2;
|
||||||
|
top: 0px;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.header img.logo {
|
||||||
|
height: 100%;
|
||||||
|
padding-top: 28.5px;
|
||||||
|
padding-left: 10px;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.header div.navbar {
|
||||||
|
float: right;
|
||||||
|
text-align: center;
|
||||||
|
padding-right: 10px;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.header img.logo {
|
||||||
|
height: 18px;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.footer {
|
||||||
|
width: 100%;
|
||||||
|
text-align: center;
|
||||||
|
}
|
||||||
|
|
||||||
|
dl.minio {
|
||||||
|
border-bottom: 1px solid #01262e2a;
|
||||||
|
border-top: 1px solid #01262e2a;
|
||||||
|
padding-top: 10px;
|
||||||
|
padding-bottom: 10px;
|
||||||
|
}
|
||||||
|
|
||||||
227
source/_static/docs-logo.svg
Normal file
227
source/_static/docs-logo.svg
Normal file
@ -0,0 +1,227 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||||
|
<svg
|
||||||
|
xmlns:osb="http://www.openswatchbook.org/uri/2009/osb"
|
||||||
|
xmlns:dc="http://purl.org/dc/elements/1.1/"
|
||||||
|
xmlns:cc="http://creativecommons.org/ns#"
|
||||||
|
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
|
||||||
|
xmlns:svg="http://www.w3.org/2000/svg"
|
||||||
|
xmlns="http://www.w3.org/2000/svg"
|
||||||
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||||
|
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
|
||||||
|
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
|
||||||
|
sodipodi:docname="docs-logo.svg"
|
||||||
|
inkscape:version="1.0 (4035a4fb49, 2020-05-01)"
|
||||||
|
id="svg8"
|
||||||
|
version="1.1"
|
||||||
|
viewBox="0 0 600 80"
|
||||||
|
height="80"
|
||||||
|
width="600">
|
||||||
|
<defs
|
||||||
|
id="defs2">
|
||||||
|
<linearGradient
|
||||||
|
id="Glacier"
|
||||||
|
osb:paint="solid">
|
||||||
|
<stop
|
||||||
|
style="stop-color:#edf7f7;stop-opacity:1;"
|
||||||
|
offset="0"
|
||||||
|
id="stop924" />
|
||||||
|
</linearGradient>
|
||||||
|
<linearGradient
|
||||||
|
id="Meridian"
|
||||||
|
osb:paint="solid">
|
||||||
|
<stop
|
||||||
|
style="stop-color:#132742;stop-opacity:1;"
|
||||||
|
offset="0"
|
||||||
|
id="stop918" />
|
||||||
|
</linearGradient>
|
||||||
|
<linearGradient
|
||||||
|
id="Nautical"
|
||||||
|
osb:paint="solid">
|
||||||
|
<stop
|
||||||
|
style="stop-color:#00303f;stop-opacity:1;"
|
||||||
|
offset="0"
|
||||||
|
id="stop912" />
|
||||||
|
</linearGradient>
|
||||||
|
<linearGradient
|
||||||
|
id="French_Raspberry"
|
||||||
|
osb:paint="solid">
|
||||||
|
<stop
|
||||||
|
style="stop-color:#c72c48;stop-opacity:1;"
|
||||||
|
offset="0"
|
||||||
|
id="stop847" />
|
||||||
|
</linearGradient>
|
||||||
|
<linearGradient
|
||||||
|
id="Midnight"
|
||||||
|
osb:paint="solid">
|
||||||
|
<stop
|
||||||
|
style="stop-color:#081c3a;stop-opacity:1;"
|
||||||
|
offset="0"
|
||||||
|
id="stop841" />
|
||||||
|
</linearGradient>
|
||||||
|
<rect
|
||||||
|
x="200"
|
||||||
|
y="650"
|
||||||
|
width="150"
|
||||||
|
height="50"
|
||||||
|
id="rect837" />
|
||||||
|
<linearGradient
|
||||||
|
inkscape:collect="always"
|
||||||
|
xlink:href="#Midnight"
|
||||||
|
id="linearGradient851"
|
||||||
|
x1="100"
|
||||||
|
y1="675"
|
||||||
|
x2="150"
|
||||||
|
y2="675"
|
||||||
|
gradientUnits="userSpaceOnUse"
|
||||||
|
gradientTransform="translate(-50)" />
|
||||||
|
<linearGradient
|
||||||
|
inkscape:collect="always"
|
||||||
|
xlink:href="#Nautical"
|
||||||
|
id="linearGradient916"
|
||||||
|
x1="100"
|
||||||
|
y1="675"
|
||||||
|
x2="150"
|
||||||
|
y2="675"
|
||||||
|
gradientUnits="userSpaceOnUse" />
|
||||||
|
<linearGradient
|
||||||
|
inkscape:collect="always"
|
||||||
|
xlink:href="#Meridian"
|
||||||
|
id="linearGradient922"
|
||||||
|
x1="150"
|
||||||
|
y1="675"
|
||||||
|
x2="200"
|
||||||
|
y2="675"
|
||||||
|
gradientUnits="userSpaceOnUse" />
|
||||||
|
<linearGradient
|
||||||
|
inkscape:collect="always"
|
||||||
|
xlink:href="#Glacier"
|
||||||
|
id="linearGradient928"
|
||||||
|
x1="200"
|
||||||
|
y1="675"
|
||||||
|
x2="250"
|
||||||
|
y2="675"
|
||||||
|
gradientUnits="userSpaceOnUse" />
|
||||||
|
<style
|
||||||
|
id="style1106">.cls-1{fill:#c72c48;}</style>
|
||||||
|
</defs>
|
||||||
|
<sodipodi:namedview
|
||||||
|
inkscape:window-maximized="0"
|
||||||
|
inkscape:window-y="0"
|
||||||
|
inkscape:window-x="5760"
|
||||||
|
inkscape:window-height="2119"
|
||||||
|
inkscape:window-width="1920"
|
||||||
|
units="px"
|
||||||
|
showgrid="true"
|
||||||
|
inkscape:document-rotation="0"
|
||||||
|
inkscape:current-layer="g1133"
|
||||||
|
inkscape:document-units="px"
|
||||||
|
inkscape:cy="-116.65714"
|
||||||
|
inkscape:cx="263.68744"
|
||||||
|
inkscape:zoom="1.979899"
|
||||||
|
inkscape:pageshadow="2"
|
||||||
|
inkscape:pageopacity="0.0"
|
||||||
|
borderopacity="1.0"
|
||||||
|
bordercolor="#666666"
|
||||||
|
pagecolor="#ffffff"
|
||||||
|
id="base">
|
||||||
|
<inkscape:grid
|
||||||
|
spacingy="10"
|
||||||
|
spacingx="10"
|
||||||
|
id="grid10"
|
||||||
|
type="xygrid" />
|
||||||
|
</sodipodi:namedview>
|
||||||
|
<metadata
|
||||||
|
id="metadata5">
|
||||||
|
<rdf:RDF>
|
||||||
|
<cc:Work
|
||||||
|
rdf:about="">
|
||||||
|
<dc:format>image/svg+xml</dc:format>
|
||||||
|
<dc:type
|
||||||
|
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
|
||||||
|
<dc:title></dc:title>
|
||||||
|
</cc:Work>
|
||||||
|
</rdf:RDF>
|
||||||
|
</metadata>
|
||||||
|
<g
|
||||||
|
id="layer1"
|
||||||
|
inkscape:groupmode="layer"
|
||||||
|
inkscape:label="Layer 1">
|
||||||
|
<rect
|
||||||
|
style="fill:url(#French_Raspberry);fill-opacity:1"
|
||||||
|
id="rect831"
|
||||||
|
width="50"
|
||||||
|
height="50"
|
||||||
|
x="0"
|
||||||
|
y="650" />
|
||||||
|
<rect
|
||||||
|
style="fill:url(#linearGradient851);fill-opacity:1"
|
||||||
|
id="rect833"
|
||||||
|
width="50"
|
||||||
|
height="50"
|
||||||
|
x="50"
|
||||||
|
y="650" />
|
||||||
|
<rect
|
||||||
|
y="650"
|
||||||
|
x="100"
|
||||||
|
height="50"
|
||||||
|
width="50"
|
||||||
|
id="rect833-1"
|
||||||
|
style="fill:url(#linearGradient916);fill-opacity:1" />
|
||||||
|
<rect
|
||||||
|
y="650"
|
||||||
|
x="150"
|
||||||
|
height="50"
|
||||||
|
width="50"
|
||||||
|
id="rect833-9"
|
||||||
|
style="fill:url(#linearGradient922);fill-opacity:1" />
|
||||||
|
<rect
|
||||||
|
style="fill:url(#linearGradient928);fill-opacity:1"
|
||||||
|
id="rect833-9-9"
|
||||||
|
width="50"
|
||||||
|
height="50"
|
||||||
|
x="200"
|
||||||
|
y="650" />
|
||||||
|
<g
|
||||||
|
transform="translate(-0.6,4.9)"
|
||||||
|
id="g920">
|
||||||
|
<path
|
||||||
|
style="stroke-width:0.423287"
|
||||||
|
class="st1"
|
||||||
|
d="M 40.257704,15.543585 C 38.268257,12.24195 36.27881,8.9403151 34.247035,5.6810088 33.188819,3.9878627 32.130602,2.2947166 31.072386,0.60157047 30.9454,0.3899272 30.776085,0.22061259 30.649099,0.00896932 28.74431,-2.9117077 24.97706,-4.8588258 21.252138,-2.9963651 c -3.259306,1.5661602 -4.656152,5.502725 -3.089991,8.8043599 0,0.042329 0.04233,0.042329 0.04233,0.084657 0.63493,1.227531 1.693146,2.2857473 2.666705,3.3439636 3.005335,3.2169776 6.137655,6.3069696 9.100661,9.5239476 3.555607,3.809578 3.343963,9.777919 -0.465615,13.291197 -0.804245,0.761916 -1.777804,1.396845 -2.83602,1.820132 -0.08466,0 -0.126986,0 -0.211643,0 V 18.972206 C 21.167481,21.723568 16.384343,25.406161 12.40545,29.85067 6.1831378,36.792569 2.500545,45.469943 1.4,51.776912 l 10.116548,-5.164096 c 3.386292,-1.693146 6.730256,-3.386292 10.243534,-5.164095 v 28.91047 L 26.416234,75.1 V 38.909002 c 0,0 0.08466,-0.04233 0.465615,-0.253972 1.396846,-0.677259 2.793691,-1.439175 4.10588,-2.285748 6.26464,-4.40218 7.788472,-12.994896 3.386292,-19.259537 -0.423287,-0.592601 -0.846573,-1.142873 -1.354517,-1.650817 -3.47095,-3.640264 -6.984228,-7.2382 -10.412849,-10.8784641 -1.015887,-1.0582164 -0.973559,-2.4127333 0,-3.3439636 0.973559,-0.93123041 2.328076,-0.8465731 3.343964,0.2116432 l 1.439174,1.4815029 c 1.142874,1.2275309 2.285747,2.4550619 3.47095,3.6825928 2.920677,3.0899917 5.883682,6.1376548 8.804359,9.1853178 0.126986,0.169315 0.33863,0.296301 0.507944,0.423286 l 0.169315,-0.126985 c 0.08466,-0.169315 0,-0.380958 -0.08466,-0.550273 z M 21.887068,35.988324 c -0.04233,0.253972 -0.211643,0.465616 -0.423286,0.550273 -1.862461,0.973559 -3.724922,1.947118 -5.587383,2.920677 L 9.0614862,42.972552 C 12.024492,36.75024 16.426672,31.332173 21.844739,27.141636 c 0.04233,0.08466 0.08466,0.126986 0.08466,0.169315 0,2.878348 0,5.799025 -0.04233,8.677373 z"
|
||||||
|
id="path908" />
|
||||||
|
<g
|
||||||
|
transform="matrix(3.2860646,0,0,3.2860646,66.04,-5.31)"
|
||||||
|
id="g1133">
|
||||||
|
<rect
|
||||||
|
class="cls-1"
|
||||||
|
x="52.75"
|
||||||
|
y="0.41"
|
||||||
|
width="9.1099997"
|
||||||
|
height="23.629999"
|
||||||
|
id="rect1112" />
|
||||||
|
<path
|
||||||
|
class="cls-1"
|
||||||
|
d="m 41.71,0.74 -18.49,9.92 a 0.91,0.91 0 0 1 -0.85,0 L 3.88,0.74 A 2.78,2.78 0 0 0 2.56,0.41 v 0 A 2.41,2.41 0 0 0 0,2.64 V 24 H 9.1 V 13.84 a 0.93,0.93 0 0 1 1,-0.81 1,1 0 0 1 0.37,0.13 l 10.36,5.57 a 3.63,3.63 0 0 0 3.33,0 L 35.1,13.09 a 0.92,0.92 0 0 1 1.25,0.34 1,1 0 0 1 0.12,0.35 V 24 h 9.1 V 2.64 A 2.41,2.41 0 0 0 43.06,0.41 v 0 a 2.78,2.78 0 0 0 -1.35,0.33 z"
|
||||||
|
id="path1114" />
|
||||||
|
<path
|
||||||
|
class="cls-1"
|
||||||
|
d="M 107.28,0.41 H 98 V 11.17 A 0.93,0.93 0 0 1 97,12 1.26,1.26 0 0 1 96.67,11.9 L 72.76,0.68 A 2.73,2.73 0 0 0 71.57,0.41 v 0 A 2.41,2.41 0 0 0 69,2.64 V 24 h 9.16 V 13.27 a 0.91,0.91 0 0 1 1,-0.8 0.75,0.75 0 0 1 0.33,0.1 l 24,11.2 a 2.86,2.86 0 0 0 1.19,0.26 v 0 a 2.41,2.41 0 0 0 2.54,-2.23 z"
|
||||||
|
id="path1116" />
|
||||||
|
<path
|
||||||
|
class="cls-1"
|
||||||
|
d="M 114.44,24 V 0.41 h 4.19 V 24 Z"
|
||||||
|
id="path1118" />
|
||||||
|
<path
|
||||||
|
class="cls-1"
|
||||||
|
d="M 143.29,24.47 C 132,24.47 124,19.76 124,12.23 124,4.7 132.07,0 143.29,0 c 11.22,0 19.32,4.7 19.32,12.23 0,7.53 -7.9,12.24 -19.32,12.24 z m 0,-21.34 c -8.38,0 -14.84,3.22 -14.84,9.1 0,5.88 6.46,9.1 14.84,9.1 8.38,0 14.89,-3.17 14.89,-9.1 0,-5.93 -6.5,-9.1 -14.89,-9.1 z"
|
||||||
|
id="path1120" />
|
||||||
|
</g>
|
||||||
|
</g>
|
||||||
|
</g>
|
||||||
|
<style
|
||||||
|
type="text/css"
|
||||||
|
id="style902">
|
||||||
|
.st0{fill:none;stroke:#CCCCCC;stroke-miterlimit:10;}
|
||||||
|
.st1{fill:#C72C48;}
|
||||||
|
</style>
|
||||||
|
</svg>
|
||||||
|
After Width: | Height: | Size: 8.2 KiB |
BIN
source/_static/favicon.png
Normal file
BIN
source/_static/favicon.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 16 KiB |
BIN
source/_static/fonts/Mark-Bold.dvi
Normal file
BIN
source/_static/fonts/Mark-Bold.dvi
Normal file
Binary file not shown.
BIN
source/_static/fonts/Mark-Bold.woff
Normal file
BIN
source/_static/fonts/Mark-Bold.woff
Normal file
Binary file not shown.
BIN
source/_static/fonts/Mark-Bold.woff2
Normal file
BIN
source/_static/fonts/Mark-Bold.woff2
Normal file
Binary file not shown.
BIN
source/_static/fonts/Mark-Medium.woff
Executable file
BIN
source/_static/fonts/Mark-Medium.woff
Executable file
Binary file not shown.
BIN
source/_static/fonts/Mark-Medium.woff2
Executable file
BIN
source/_static/fonts/Mark-Medium.woff2
Executable file
Binary file not shown.
BIN
source/_static/fonts/Mark-Regular.woff
Normal file
BIN
source/_static/fonts/Mark-Regular.woff
Normal file
Binary file not shown.
BIN
source/_static/fonts/Mark-Regular.woff2
Normal file
BIN
source/_static/fonts/Mark-Regular.woff2
Normal file
Binary file not shown.
54
source/_static/js/main.js
Normal file
54
source/_static/js/main.js
Normal file
@ -0,0 +1,54 @@
|
|||||||
|
window.addEventListener('DOMContentLoaded', (event) => {
|
||||||
|
console.log('DOM fully loaded and parsed');
|
||||||
|
|
||||||
|
var topic = document.getElementById('on-this-page');
|
||||||
|
|
||||||
|
if (topic != null) {
|
||||||
|
document.getElementById('localtoc').appendChild(
|
||||||
|
document.getElementById('on-this-page')
|
||||||
|
);
|
||||||
|
|
||||||
|
console.log("moving local toc");
|
||||||
|
}
|
||||||
|
|
||||||
|
let options = {
|
||||||
|
root: document.querySelector('#scrollArea'),
|
||||||
|
rootMargin: '-100px 0px 0px 0px'
|
||||||
|
}
|
||||||
|
|
||||||
|
const observer = new IntersectionObserver(entries => {
|
||||||
|
entries.forEach(entry => {
|
||||||
|
const id = entry.target.getAttribute('id');
|
||||||
|
console.log("entry is " + id + " Ratio is " + entry.intersectionRatio)
|
||||||
|
console.log(entry.rootBounds)
|
||||||
|
|
||||||
|
if (id == document.querySelector('.section[id]').getAttribute('id'))
|
||||||
|
return 0
|
||||||
|
if (entry.intersectionRatio > 0) {
|
||||||
|
|
||||||
|
liElement = document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement.parentElement;
|
||||||
|
|
||||||
|
liElement.classList.add('active');
|
||||||
|
|
||||||
|
liElementParent = liElement.parentElement.parentElement
|
||||||
|
|
||||||
|
if (liElementParent.tagName == "LI") {
|
||||||
|
liElementParent.classList.remove("active")
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
} else {
|
||||||
|
document.querySelector(`#on-this-page li a[href="#${id}"]`).parentElement.parentElement.classList.remove('active');
|
||||||
|
}
|
||||||
|
});
|
||||||
|
},options);
|
||||||
|
|
||||||
|
// Track all sections that have an `id` applied
|
||||||
|
document.querySelectorAll('.section[id]').forEach((section) => {
|
||||||
|
observer.observe(section);
|
||||||
|
});
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
});
|
||||||
19
source/_static/logo.svg
Normal file
19
source/_static/logo.svg
Normal file
@ -0,0 +1,19 @@
|
|||||||
|
<?xml version="1.0" encoding="utf-8"?>
|
||||||
|
<!-- Generator: Adobe Illustrator 22.1.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
|
||||||
|
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
|
||||||
|
viewBox="0 0 297 348.5" style="enable-background:new 0 0 297 348.5;" xml:space="preserve">
|
||||||
|
<style type="text/css">
|
||||||
|
.st0{fill:none;stroke:#CCCCCC;stroke-miterlimit:10;}
|
||||||
|
.st1{fill:#C72C48;}
|
||||||
|
</style>
|
||||||
|
<title>Bird</title>
|
||||||
|
<polygon class="st0" points="0.6,0.5 296.5,0.5 296.5,348 0.5,348 "/>
|
||||||
|
<path class="st1" d="M194,126.8c-4.7-7.8-9.4-15.6-14.2-23.3c-2.5-4-5-8-7.5-12c-0.3-0.5-0.7-0.9-1-1.4c-4.5-6.9-13.4-11.5-22.2-7.1
|
||||||
|
c-7.7,3.7-11,13-7.3,20.8c0,0.1,0.1,0.1,0.1,0.2c1.5,2.9,4,5.4,6.3,7.9c7.1,7.6,14.5,14.9,21.5,22.5c8.4,9,7.9,23.1-1.1,31.4
|
||||||
|
c-1.9,1.8-4.2,3.3-6.7,4.3c-0.2,0-0.3,0-0.5,0v-35.2c-12.5,6.5-23.8,15.2-33.2,25.7c-14.7,16.4-23.4,36.9-26,51.8l23.9-12.2
|
||||||
|
c8-4,15.9-8,24.2-12.2v68.3l11,11.2V182c0,0,0.2-0.1,1.1-0.6c3.3-1.6,6.6-3.4,9.7-5.4c14.8-10.4,18.4-30.7,8-45.5
|
||||||
|
c-1-1.4-2-2.7-3.2-3.9c-8.2-8.6-16.5-17.1-24.6-25.7c-2.4-2.5-2.3-5.7,0-7.9s5.5-2,7.9,0.5l3.4,3.5c2.7,2.9,5.4,5.8,8.2,8.7
|
||||||
|
c6.9,7.3,13.9,14.5,20.8,21.7c0.3,0.4,0.8,0.7,1.2,1l0.4-0.3C194.4,127.7,194.2,127.2,194,126.8z M150.6,175.1
|
||||||
|
c-0.1,0.6-0.5,1.1-1,1.3c-4.4,2.3-8.8,4.6-13.2,6.9l-16.1,8.3c7-14.7,17.4-27.5,30.2-37.4c0.1,0.2,0.2,0.3,0.2,0.4
|
||||||
|
C150.7,161.4,150.7,168.3,150.6,175.1L150.6,175.1z"/>
|
||||||
|
</svg>
|
||||||
|
After Width: | Height: | Size: 1.4 KiB |
44
source/_templates/layout.html
Normal file
44
source/_templates/layout.html
Normal file
@ -0,0 +1,44 @@
|
|||||||
|
{# Import the theme's layout. #}
|
||||||
|
{% extends "!layout.html" %}
|
||||||
|
|
||||||
|
{# Custom CSS overrides #}
|
||||||
|
|
||||||
|
{# Override content block #}
|
||||||
|
|
||||||
|
{%- block header %}
|
||||||
|
<div class="header">
|
||||||
|
<a href="https://min.io">
|
||||||
|
<img class="logo" src="{{ pathto('_static/docs-logo.svg',1) }}" alt="Logo"/>
|
||||||
|
</a>
|
||||||
|
<div class="navbar">
|
||||||
|
<p style="color: white">This will someday contain a header</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
{%- endblock %}
|
||||||
|
|
||||||
|
{%- block content %}
|
||||||
|
<div class="document">
|
||||||
|
{{ sidebar() }}
|
||||||
|
<div class=body>
|
||||||
|
{% block alertbar -%}
|
||||||
|
<div class="alert alert-info">
|
||||||
|
<span class="alert-message">
|
||||||
|
<p>We're building a new version of the MinIO Documentation!
|
||||||
|
If you can't find what you're looking for, check our
|
||||||
|
<a href="https://docs.min.io"> legacy documentation</a>.
|
||||||
|
Thank you for your patience.
|
||||||
|
</p>
|
||||||
|
</span>
|
||||||
|
</div>
|
||||||
|
{% endblock %}
|
||||||
|
{% block body %} {% endblock %}
|
||||||
|
<div class="footer">
|
||||||
|
©{{ copyright }}
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div id=localtoc class=localtoc>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
{%- endblock %}
|
||||||
|
|
||||||
|
{%- block footer %}{%- endblock %}
|
||||||
104
source/conf.py
Normal file
104
source/conf.py
Normal file
@ -0,0 +1,104 @@
|
|||||||
|
# Configuration file for the Sphinx documentation builder.
|
||||||
|
#
|
||||||
|
# This file only contains a selection of the most common options. For a full
|
||||||
|
# list see the documentation:
|
||||||
|
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||||
|
|
||||||
|
# -- Path setup --------------------------------------------------------------
|
||||||
|
|
||||||
|
# If extensions (or modules to document with autodoc) are in another directory,
|
||||||
|
# add these directories to sys.path here. If the directory is relative to the
|
||||||
|
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||||
|
#
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
|
||||||
|
# The current working dir seems to be /source, so we have to pop up a level
|
||||||
|
sys.path.append(os.path.abspath('../sphinxext'))
|
||||||
|
|
||||||
|
|
||||||
|
# sys.path.insert(0, os.path.abspath('.'))
|
||||||
|
|
||||||
|
|
||||||
|
# -- Project information -----------------------------------------------------
|
||||||
|
|
||||||
|
project = 'DOCS@MinIO'
|
||||||
|
copyright = '2020, MinIO'
|
||||||
|
author = 'Ravind Kumar'
|
||||||
|
|
||||||
|
# The full version, including alpha/beta/rc tags
|
||||||
|
release = '0.1'
|
||||||
|
|
||||||
|
|
||||||
|
# -- General configuration ---------------------------------------------------
|
||||||
|
|
||||||
|
# Add any Sphinx extension module names here, as strings. They can be
|
||||||
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||||
|
# ones.
|
||||||
|
extensions = [
|
||||||
|
'sphinx.ext.extlinks',
|
||||||
|
'minio',
|
||||||
|
'sphinx_copybutton',
|
||||||
|
'sphinx_tabs.tabs',
|
||||||
|
'recommonmark',
|
||||||
|
'sphinx_markdown_tables',
|
||||||
|
]
|
||||||
|
|
||||||
|
# -- External Links
|
||||||
|
|
||||||
|
# Add roots for short external link references in the documentation.
|
||||||
|
# Helpful for sites we tend to make lots of references to.
|
||||||
|
|
||||||
|
extlinks = {
|
||||||
|
'kube-docs' : ('https://kubernetes.io/docs/%s', ''),
|
||||||
|
'minio-git' : ('https://github.com/minio/%s',''),
|
||||||
|
'github' : ('https://github.com/%s',''),
|
||||||
|
'kube-api' : ('https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/%s',''),
|
||||||
|
'aws-docs' : ('https://docs.aws.amazon.com/%s',''),
|
||||||
|
's3-docs' : ('https://docs.aws.amazon.com/AmazonS3/latest/dev/%s',''),
|
||||||
|
'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',''),
|
||||||
|
}
|
||||||
|
|
||||||
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
|
templates_path = ['_templates']
|
||||||
|
|
||||||
|
# List of patterns, relative to source directory, that match files and
|
||||||
|
# directories to ignore when looking for source files.
|
||||||
|
# This pattern also affects html_static_path and html_extra_path.
|
||||||
|
exclude_patterns = ['includes/*.rst']
|
||||||
|
|
||||||
|
# Copy-Button Customization
|
||||||
|
|
||||||
|
copybutton_selector = "div.copyable pre"
|
||||||
|
|
||||||
|
# -- Options for HTML output -------------------------------------------------
|
||||||
|
|
||||||
|
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||||
|
# a list of builtin themes.
|
||||||
|
#
|
||||||
|
html_theme = 'alabaster'
|
||||||
|
|
||||||
|
html_favicon = '_static/favicon.png'
|
||||||
|
|
||||||
|
html_sidebars = {
|
||||||
|
'**' : [
|
||||||
|
'about.html',
|
||||||
|
'navigation.html',
|
||||||
|
'searchbox.html',
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
html_theme_options = {
|
||||||
|
'fixed_sidebar' : 'true',
|
||||||
|
}
|
||||||
|
|
||||||
|
# Add any paths that contain custom static files (such as style sheets) here,
|
||||||
|
# relative to this directory. They are copied after the builtin static files,
|
||||||
|
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||||
|
html_static_path = ['_static']
|
||||||
|
|
||||||
|
html_css_files = ['css-style.css']
|
||||||
|
|
||||||
|
html_js_files = ['js/main.js']
|
||||||
BIN
source/images/Kubernetes-Minio.png
Normal file
BIN
source/images/Kubernetes-Minio.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
771
source/images/Kubernetes-Minio.svg
Normal file
771
source/images/Kubernetes-Minio.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 53 KiB |
21
source/includes/minio-kubernetes-operator.rst
Normal file
21
source/includes/minio-kubernetes-operator.rst
Normal file
@ -0,0 +1,21 @@
|
|||||||
|
.. tabs::
|
||||||
|
|
||||||
|
.. tab:: SSH
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mkdir -p ~/minio-kubernetes/git
|
||||||
|
cd ~/minio-examples/git
|
||||||
|
|
||||||
|
git clone git@github.com:minio/minio-operator.git
|
||||||
|
|
||||||
|
.. tab:: HTTPS
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mkdir -p ~/minio-kubernetes/git
|
||||||
|
cd ~/minio-examples/git
|
||||||
|
|
||||||
|
git clone https://github.com/minio/minio-operator.git
|
||||||
112
source/includes/minio-mc-installation.rst
Normal file
112
source/includes/minio-mc-installation.rst
Normal file
@ -0,0 +1,112 @@
|
|||||||
|
.. tabs::
|
||||||
|
|
||||||
|
.. tab:: Docker
|
||||||
|
|
||||||
|
**Stable**
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
docker pull minio/mc
|
||||||
|
docker run minio/mc admin info play
|
||||||
|
|
||||||
|
**Edge**
|
||||||
|
|
||||||
|
*Do not use bleeding-edge deployments of MinIO in production environments*
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
docker pull minio/mc:edge
|
||||||
|
docker run minio/mc:edge admin info server play
|
||||||
|
|
||||||
|
|
||||||
|
.. tab:: Linux
|
||||||
|
|
||||||
|
The following commands add a *temporary* extension to your system
|
||||||
|
PATH for running the ``mc`` utility. Defer to your operating system
|
||||||
|
instructions for making permanent modifications to your system PATH.
|
||||||
|
|
||||||
|
Alternatively, execute ``mc`` by navigating to the parent folder and
|
||||||
|
running ``./mc --help``
|
||||||
|
|
||||||
|
**64-bit Intel**
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
curl https://dl.min.io/client/mc/release/linux-amd64/mc \
|
||||||
|
--create-dirs \
|
||||||
|
-o $HOME/minio-binaries/mc
|
||||||
|
|
||||||
|
chmod +x $HOME/minio-binaries/mc
|
||||||
|
export PATH=$PATH:$HOME/minio-binaries/
|
||||||
|
|
||||||
|
mc --help
|
||||||
|
|
||||||
|
**64-bit PPC**
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
curl https://dl.min.io/client/mc/release/linux-ppc64le/mc \
|
||||||
|
--create-dirs \
|
||||||
|
-o ~/minio-binaries/mc
|
||||||
|
|
||||||
|
chmod +x $HOME/minio-binaries/mc
|
||||||
|
export PATH=$PATH:$HOME/minio-binaries/
|
||||||
|
|
||||||
|
mc --help
|
||||||
|
|
||||||
|
.. tab:: macOS
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
brew install minio/stable/mc
|
||||||
|
mc --help
|
||||||
|
|
||||||
|
|
||||||
|
.. tab:: Windows
|
||||||
|
|
||||||
|
Open the following file in a browser:
|
||||||
|
|
||||||
|
https://dl.min.io/client/mc/release/windows-amd64/mc.exe
|
||||||
|
|
||||||
|
Execute the file by double clicking on it, *or* by running the
|
||||||
|
following in the command prompt or powershell:
|
||||||
|
|
||||||
|
.. code-block:: powershell
|
||||||
|
|
||||||
|
\path\to\mc.exe --help
|
||||||
|
|
||||||
|
.. 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.
|
||||||
|
|
||||||
|
Source installation requires a working Golang environment.
|
||||||
|
See `How to install Golang <https://golang.org/doc/install>`__
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
go get -d github.com/minio/mc
|
||||||
|
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``:
|
||||||
|
|
||||||
|
.. 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.
|
||||||
32
source/includes/play-alias-available.rst
Normal file
32
source/includes/play-alias-available.rst
Normal file
@ -0,0 +1,32 @@
|
|||||||
|
play-alias-only
|
||||||
|
|
||||||
|
The following example assumes that the ``play`` alias exists in the
|
||||||
|
:mc-cmd:`mc` :ref:`configuration file <mc-configuration>`. You can
|
||||||
|
replace ``play`` with the alias for your preferred S3-compatible deployment.
|
||||||
|
|
||||||
|
See :mc-cmd:`mc alias` for more information on aliases.
|
||||||
|
|
||||||
|
end-play-alias-only
|
||||||
|
|
||||||
|
|
||||||
|
play-s3-alias
|
||||||
|
|
||||||
|
The following example assumes that the ``play`` and ``s3`` aliases exist in the
|
||||||
|
:mc-cmd:`mc` :ref:`configuration file <mc-configuration>`. You can replace
|
||||||
|
``play`` and ``s3`` with the aliases for your preferred S3-compatible
|
||||||
|
deployments.
|
||||||
|
|
||||||
|
See :mc-cmd:`mc alias` for more information on aliases.
|
||||||
|
|
||||||
|
end-play-s3-alias
|
||||||
|
|
||||||
|
myminio-alias
|
||||||
|
|
||||||
|
The following example uses the default ``myminio`` alias. The ``myminio``
|
||||||
|
alias points to a local ``minio`` server running on port ``9000``. See
|
||||||
|
<installation instructions> for more information on installing and running
|
||||||
|
a local ``minio`` server instance.
|
||||||
|
|
||||||
|
See :mc-cmd:`mc alias` for more information on aliases.
|
||||||
|
|
||||||
|
end-myminio-alias
|
||||||
26
source/index.rst
Normal file
26
source/index.rst
Normal file
@ -0,0 +1,26 @@
|
|||||||
|
=====================================
|
||||||
|
MinIO High Performance Object Storage
|
||||||
|
=====================================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
Welcome to the MinIO Documentation! MinIO is a high performance object storage
|
||||||
|
solution with native support for Kubernetes deployments. MinIO provides an
|
||||||
|
Amazon Web Services S3-compatible API and supports all core S3 features.
|
||||||
|
|
||||||
|
First-time users of MinIO *or* object storage services should start with
|
||||||
|
our :doc:`Introduction </introduction/minio-overview>`.
|
||||||
|
|
||||||
|
Users deploying onto a Kubernetes cluster should start with our
|
||||||
|
:doc:`Kubernetes-specific documentation </kubernetes/minio-kubernetes>`.
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:titlesonly:
|
||||||
|
:hidden:
|
||||||
|
|
||||||
|
/introduction/minio-overview
|
||||||
|
/minio-features/overview.rst
|
||||||
|
/kubernetes/minio-kubernetes
|
||||||
|
/security/minio-security
|
||||||
|
/minio-cli/minio-mc
|
||||||
|
/minio-cli/minio-mc-admin
|
||||||
18
source/introduction/bitrot-protection.rst
Normal file
18
source/introduction/bitrot-protection.rst
Normal file
@ -0,0 +1,18 @@
|
|||||||
|
.. _minio-bitrot-protection:
|
||||||
|
|
||||||
|
=================
|
||||||
|
Bitrot Protection
|
||||||
|
=================
|
||||||
|
|
||||||
|
Silent data corruption or bitrot is a serious problem faced by disk drives
|
||||||
|
resulting in data getting corrupted without the user’s knowledge. The reasons
|
||||||
|
are manifold (ageing drives, current spikes, bugs in disk firmware, phantom
|
||||||
|
writes, misdirected reads/writes, driver errors, accidental overwrites) but the
|
||||||
|
result is the same - compromised data.
|
||||||
|
|
||||||
|
MinIO’s optimized implementation of the HighwayHash algorithm ensures that it
|
||||||
|
will never read corrupted data - it captures and heals corrupted objects on the
|
||||||
|
fly. Integrity is ensured from end to end by computing a hash on READ and
|
||||||
|
verifying it on WRITE from the application, across the network and to the
|
||||||
|
memory/drive. The implementation is designed for speed and can achieve hashing
|
||||||
|
speeds over 10 GB/sec on a single core on Intel CPUs.
|
||||||
75
source/introduction/buckets.rst
Normal file
75
source/introduction/buckets.rst
Normal file
@ -0,0 +1,75 @@
|
|||||||
|
.. _minio-bucket:
|
||||||
|
|
||||||
|
=======
|
||||||
|
Buckets
|
||||||
|
=======
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 2
|
||||||
|
|
||||||
|
|
||||||
|
A :ref:`bucket <minio-bucket>` is a folder or storage container that can hold an
|
||||||
|
arbitrary number of :ref:`objects <minio-object>`. Minio buckets provide the
|
||||||
|
same functionality as an Amazon Web Services (AWS) S3 Bucket. The MinIO API is
|
||||||
|
fully compatible with the Amazon S3 API, where applications can seamlessly
|
||||||
|
transition to using the MinIO deployment with minimal code changes.
|
||||||
|
|
||||||
|
Bucket Notifications
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
MinIO Bucket Notifications allow you to automatically publish notifications
|
||||||
|
to one or more configured endpoints when specific events occur in a bucket.
|
||||||
|
|
||||||
|
See :doc:`/minio-features/bucket-notifications` for more information.
|
||||||
|
|
||||||
|
Push Notifications
|
||||||
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
MinIO supports pushing events to the following targets:
|
||||||
|
|
||||||
|
- AMQP
|
||||||
|
- MQTT
|
||||||
|
- Elasticsearch
|
||||||
|
- NSQ
|
||||||
|
- Redis
|
||||||
|
- NATS
|
||||||
|
- PostgreSQL
|
||||||
|
- MySQL
|
||||||
|
- Apache Kafka
|
||||||
|
- Webhooks
|
||||||
|
|
||||||
|
Use the ``mc admin`` utility to configure the MinIO deployment to actively
|
||||||
|
push notifications to each configured target. For more complete documentation,
|
||||||
|
see <logging tbd>
|
||||||
|
|
||||||
|
Listener API
|
||||||
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
|
MinIO provides two routes to listen for events for a given bucket:
|
||||||
|
|
||||||
|
- The ``mc event`` command.
|
||||||
|
- The ``BucketNotification`` API.
|
||||||
|
|
||||||
|
.. todo: Add more information here as its available.
|
||||||
|
|
||||||
|
Write Once Read Many (WORM)
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
MinIO supports enabling Write-Once Read-Many (WORM) for specific objects
|
||||||
|
in a bucket *or* for all objects in the bucket. Objects with WORM applied
|
||||||
|
are immutable, and can only be deleted if the WORM configuration includes an
|
||||||
|
expiry.
|
||||||
|
|
||||||
|
Configure WORM for Bucket
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
ToDo: Enable, Disable WORM
|
||||||
|
|
||||||
|
Configure WORM for Specific Objects
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
ToDo: Enable, Disable WORM per object
|
||||||
|
|
||||||
63
source/introduction/deployment-topologies.rst
Normal file
63
source/introduction/deployment-topologies.rst
Normal file
@ -0,0 +1,63 @@
|
|||||||
|
=====================
|
||||||
|
Deployment Topologies
|
||||||
|
=====================
|
||||||
|
|
||||||
|
MinIO supports three deployment topologies:
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:widths: 30 70
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - Deployment Type
|
||||||
|
- Description
|
||||||
|
|
||||||
|
* - :ref:`Standalone <minio-deployment-standalone>`
|
||||||
|
- A single MinIO server.
|
||||||
|
|
||||||
|
Standalone deployments are ideal for local development and evaluation.
|
||||||
|
|
||||||
|
* - :ref:`Distributed <minio-deployment-distributed>`
|
||||||
|
- Multiple MinIO servers allow for horizontal scaling of storage while
|
||||||
|
allowing applications to treat the deployment as a single MinIO
|
||||||
|
instance.
|
||||||
|
|
||||||
|
Distributed deployments are ideal for production environments.
|
||||||
|
|
||||||
|
* - :ref:`Active-Active <minio-deployment-active-active>`
|
||||||
|
- Multiple distributed deployments with intra-deployment
|
||||||
|
replication to synchronize :ref:`objects <minio-object>` across
|
||||||
|
deployments.
|
||||||
|
|
||||||
|
Active-Active Distributed deployments are ideal for production
|
||||||
|
environments with globally distributed applications, where applications
|
||||||
|
prefer routing to the geographically-nearest MinIO instance.
|
||||||
|
|
||||||
|
.. _minio-deployment-standalone:
|
||||||
|
|
||||||
|
Standalone Deployment
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
TBD:
|
||||||
|
- Add a diagram of a standalone deployment
|
||||||
|
- List the drawbacks (if any)
|
||||||
|
- Link to deployment tutorials (kubernetes, bare-metal)
|
||||||
|
|
||||||
|
.. _minio-deployment-distributed:
|
||||||
|
|
||||||
|
Distributed Deployment
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
TBD:
|
||||||
|
- Add a diagram of a distributed deployment
|
||||||
|
- List the drawbacks (if any)
|
||||||
|
- Link to deployment tutorials (kubernetes, bare-metal)
|
||||||
|
|
||||||
|
.. _minio-deployment-active-active:
|
||||||
|
|
||||||
|
Active-Active
|
||||||
|
-------------
|
||||||
|
|
||||||
|
TBD:
|
||||||
|
- Add a diagram of a distributed deployment
|
||||||
|
- List the drawbacks (if any)
|
||||||
|
- Link to deployment tutorials (kubernetes, bare-metal)
|
||||||
17
source/introduction/erasure-coding.rst
Normal file
17
source/introduction/erasure-coding.rst
Normal file
@ -0,0 +1,17 @@
|
|||||||
|
.. _minio-erasure-coding:
|
||||||
|
|
||||||
|
==============
|
||||||
|
Erasure Coding
|
||||||
|
==============
|
||||||
|
|
||||||
|
MinIO protects data with per-object, inline erasure coding, which is written in
|
||||||
|
assembly code to deliver the highest performance possible. MinIO uses
|
||||||
|
Reed-Solomon code to stripe objects into `n/2` data and ``n/2`` parity blocks -
|
||||||
|
although these can be configured to any desired redundancy level.
|
||||||
|
|
||||||
|
This means that in a 12 drive setup, an object is sharded across as 6 data and 6
|
||||||
|
parity blocks. Even if you lose as many as 5 ((n/2)–1) drives, be it parity or
|
||||||
|
data, you can still reconstruct the data reliably from the remaining drives.
|
||||||
|
MinIO's implementation ensures that objects can be read or new objects are
|
||||||
|
written even if multiple devices are lost or unavailable. Finally, MinIO's
|
||||||
|
erasure code is at the object level and can heal one object at a time.
|
||||||
59
source/introduction/minio-overview.rst
Normal file
59
source/introduction/minio-overview.rst
Normal file
@ -0,0 +1,59 @@
|
|||||||
|
============
|
||||||
|
Introduction
|
||||||
|
============
|
||||||
|
|
||||||
|
MinIO is a High Performance Object Storage released under Apache License v2.0.
|
||||||
|
It is API compatible with Amazon S3 cloud storage service. Use MinIO to build
|
||||||
|
high performance infrastructure for machine learning, analytics and application
|
||||||
|
data workloads.
|
||||||
|
|
||||||
|
What Is Object Storage?
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
Applications create, update, retrieve, and delete data as part of normal
|
||||||
|
operations. MinIO provides a complete solution for managing the storage
|
||||||
|
and access of that data as :ref:`objects <minio-object>`. Applications group
|
||||||
|
objects into one or more :ref:`buckets <minio-bucket>`.
|
||||||
|
|
||||||
|
MinIO is fully compatible with the Amazon Web Services Simple Storage Service
|
||||||
|
(AWS S3) API. Applications using the AWS S3 API can seamlessly transition to
|
||||||
|
using a MinIO deployment for managing their application's object storage with
|
||||||
|
minimal code changes.
|
||||||
|
|
||||||
|
Erasure Coding
|
||||||
|
--------------
|
||||||
|
|
||||||
|
MinIO Erasure Coding guarantees object retrieval as long as the deployment
|
||||||
|
has at least half of its drives operational. Specifically, the deployment
|
||||||
|
can lose `(n/2)-1` drives and still service create, retrieval, update, and
|
||||||
|
delete operations.
|
||||||
|
|
||||||
|
For example, consider a deployment with 12 data drives. MinIO splits the
|
||||||
|
12 drive set into 6 data drives and 6 parity drives. As long as *at least* 7
|
||||||
|
drives are online, the MinIO server can guarantee retrieval of any stored
|
||||||
|
object.
|
||||||
|
|
||||||
|
For more information on MinIO Erasure Coding, see
|
||||||
|
:ref:`minio-erasure-coding`.
|
||||||
|
|
||||||
|
Bitrot Protection
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
MinIO Bitrot Protection heals objects that have degraded due to
|
||||||
|
disk corruption. When applications request a specific object, MinIO
|
||||||
|
automatically checks for corruption and applies a healing algorithm to
|
||||||
|
reconstruct the object.
|
||||||
|
|
||||||
|
For more information on MinIO Bitrot Protection, see
|
||||||
|
:ref:`minio-bitrot-protection`.
|
||||||
|
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:hidden:
|
||||||
|
:titlesonly:
|
||||||
|
|
||||||
|
/introduction/buckets.rst
|
||||||
|
/introduction/objects.rst
|
||||||
|
/introduction/deployment-topologies.rst
|
||||||
|
/introduction/erasure-coding.rst
|
||||||
|
/introduction/bitrot-protection.rst
|
||||||
15
source/introduction/objects.rst
Normal file
15
source/introduction/objects.rst
Normal file
@ -0,0 +1,15 @@
|
|||||||
|
.. _minio-object:
|
||||||
|
|
||||||
|
=======
|
||||||
|
Objects
|
||||||
|
=======
|
||||||
|
|
||||||
|
An :ref:`object <minio-object>` is any kind of data with no limit to its
|
||||||
|
size, format, or type. Examples of objects include digital images,
|
||||||
|
text documents, or video files. Applications can store, retrieve, and
|
||||||
|
delete objects from a MinIO deployment.
|
||||||
|
|
||||||
|
MinIO objects provide the same core functionality as an Amazon Web Services (AWS)
|
||||||
|
S3 Object. The MinIO API is fully compatible with the Amazon S3 API,
|
||||||
|
where applications can seamlessly transition to using the MinIO deployment
|
||||||
|
with minimal code changes.
|
||||||
87
source/kubernetes/deploy-on-kubernetes.rst
Normal file
87
source/kubernetes/deploy-on-kubernetes.rst
Normal file
@ -0,0 +1,87 @@
|
|||||||
|
====================================
|
||||||
|
Deploy MinIO on a Kubernetes Cluster
|
||||||
|
====================================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 2
|
||||||
|
|
||||||
|
Overview
|
||||||
|
--------
|
||||||
|
|
||||||
|
This tutorial uses the MinIO Kubernetes Operator to deploy MinIO to your
|
||||||
|
Kubernetes cluster in a distributed configuration. Distributed MinIO deployments
|
||||||
|
are suitable for development, staging, and production environments. For
|
||||||
|
a tutorial on creating a more simple MinIO deployment for local development
|
||||||
|
and evaluation, see :doc:`/kubernetes/quickstart`.
|
||||||
|
|
||||||
|
By default, this tutorial creates a distributed MinIO deployment with the
|
||||||
|
following components:
|
||||||
|
|
||||||
|
- 4 MinIO server instances with TLS enabled.
|
||||||
|
- 4 x 1TB storage volumes per MinIO server instance.
|
||||||
|
- 1 MinIO KES key management instance.
|
||||||
|
- 1 MinIO Minio Console Service instance.
|
||||||
|
- 1 MinIO Operator instance.
|
||||||
|
|
||||||
|
This tutorial includes instructions for modifying the deployment configuration
|
||||||
|
for your specific requirements.
|
||||||
|
|
||||||
|
You should have basic familiarity with Kubernetes, its associated terminology,
|
||||||
|
and its command line tools prior to starting this tutorial. While the MinIO
|
||||||
|
documentation makes a best-effort to address Kubernetes-specific information,
|
||||||
|
you should review the official Kubernetes :kube-docs:`documentation <>` for more
|
||||||
|
complete coverage.
|
||||||
|
|
||||||
|
.. _minio-kubernetes-deploy-minio-prerequisites:
|
||||||
|
|
||||||
|
Prerequisites
|
||||||
|
-------------
|
||||||
|
|
||||||
|
This tutorial requires the following resources:
|
||||||
|
|
||||||
|
- The :minio-git:`minio-operator <minio-operator>` github repository.
|
||||||
|
|
||||||
|
- A Kubernetes cluster with *at least* **four**
|
||||||
|
:kube-docs:`node` per MinIO server instance. Each node must have *at least*
|
||||||
|
**four** persistent volumes.
|
||||||
|
|
||||||
|
- A host machine with ``kubectl`` installed. See
|
||||||
|
:kube-docs:`Install and Set Up kubectl <tasks/tools/install-kubectl/>`
|
||||||
|
|
||||||
|
The host machine should be configured such that ``kubectl`` can access the
|
||||||
|
Kubernetes cluster. See :kube-docs:`Access Applications in a Cluster
|
||||||
|
<tasks/access-application-cluster>` for more information.
|
||||||
|
|
||||||
|
Considerations
|
||||||
|
--------------
|
||||||
|
|
||||||
|
.. ToDo:
|
||||||
|
|
||||||
|
- Document recommended resource allocation (CPU, RAM, etc.)
|
||||||
|
- Document recommended number of MinIO pods to Nodes
|
||||||
|
- Document recommended ratio of PV to Physical Disk
|
||||||
|
|
||||||
|
Procedure
|
||||||
|
---------
|
||||||
|
|
||||||
|
1) First Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
|
|
||||||
|
2) Second Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
|
|
||||||
113
source/kubernetes/enforce-security.rst
Normal file
113
source/kubernetes/enforce-security.rst
Normal file
@ -0,0 +1,113 @@
|
|||||||
|
========================================
|
||||||
|
Enforce Security for MinIO in Kubernetes
|
||||||
|
========================================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 2
|
||||||
|
|
||||||
|
Overview
|
||||||
|
--------
|
||||||
|
|
||||||
|
This page covers multiple procedures for configuring MinIO security features
|
||||||
|
using the MinIO Kubernetes Operator.
|
||||||
|
|
||||||
|
You should have basic familiarity with Kubernetes, its associated terminology,
|
||||||
|
and its command line tools prior to starting any of the documented procedures.
|
||||||
|
While the MinIO documentation makes a best-effort to address Kubernetes-specific
|
||||||
|
information, you should review the official Kubernetes :kube-docs:`documentation
|
||||||
|
<>` for more complete coverage.
|
||||||
|
|
||||||
|
.. _minio-kubernetes-enforce-security-prerequisites:
|
||||||
|
|
||||||
|
Prerequisites
|
||||||
|
-------------
|
||||||
|
|
||||||
|
This tutorial requires the following resources:
|
||||||
|
|
||||||
|
- The :minio-git:`minio-operator <minio-operator>` github repository.
|
||||||
|
|
||||||
|
- A Kubernetes cluster with *at least* **four**
|
||||||
|
:kube-docs:`node` per MinIO server instance. Each node must have *at least*
|
||||||
|
**four** persistent volumes.
|
||||||
|
|
||||||
|
- A host machine with ``kubectl`` installed. See
|
||||||
|
:kube-docs:`Install and Set Up kubectl <tasks/tools/install-kubectl/>`
|
||||||
|
|
||||||
|
The host machine should be configured such that ``kubectl`` can access the
|
||||||
|
Kubernetes cluster. See :kube-docs:`Access Applications in a Cluster
|
||||||
|
<tasks/access-application-cluster>` for more information.
|
||||||
|
|
||||||
|
Considerations
|
||||||
|
--------------
|
||||||
|
|
||||||
|
.. ToDo:
|
||||||
|
|
||||||
|
- Document recommended resource allocation (CPU, RAM, etc.)
|
||||||
|
- Document recommended number of MinIO pods to Nodes
|
||||||
|
- Document recommended ratio of PV to Physical Disk
|
||||||
|
|
||||||
|
Enable TLS
|
||||||
|
----------
|
||||||
|
|
||||||
|
1) First Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
|
|
||||||
|
2) Second Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
|
|
||||||
|
Configure Root Access to MinIO Servers
|
||||||
|
--------------------------------------
|
||||||
|
|
||||||
|
1) First Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
|
|
||||||
|
2) Second Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
|
|
||||||
|
Another Deployment-Level Security Feature
|
||||||
|
-----------------------------------------
|
||||||
|
|
||||||
|
1) First Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
|
|
||||||
|
2) Second Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
77
source/kubernetes/manage-on-kubernetes.rst
Normal file
77
source/kubernetes/manage-on-kubernetes.rst
Normal file
@ -0,0 +1,77 @@
|
|||||||
|
====================================
|
||||||
|
Expand MinIO in a Kubernetes Cluster
|
||||||
|
====================================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 2
|
||||||
|
|
||||||
|
Overview
|
||||||
|
--------
|
||||||
|
|
||||||
|
This tutorial uses the MinIO Kubernetes Operator to expand an existing
|
||||||
|
distributed MinIO deployment in your Kubernetes cluster. Specifically,
|
||||||
|
this tutorial covers:
|
||||||
|
|
||||||
|
- Adding additional MinIO server instances to the deployment, *and*
|
||||||
|
- Adding additional drives to a MinIO server instance.
|
||||||
|
|
||||||
|
This tutorial includes instructions for modifying the deployment configuration
|
||||||
|
for your specific requirements.
|
||||||
|
|
||||||
|
You should have basic familiarity with Kubernetes, its associated terminology,
|
||||||
|
and its command line tools prior to starting this tutorial. While the MinIO
|
||||||
|
documentation makes a best-effort to address Kubernetes-specific information,
|
||||||
|
you should review the official Kubernetes :kube-docs:`documentation <>` for more
|
||||||
|
complete coverage.
|
||||||
|
|
||||||
|
.. _minio-kubernetes-expand-minio-prerequisites:
|
||||||
|
|
||||||
|
Prerequisites
|
||||||
|
-------------
|
||||||
|
|
||||||
|
This tutorial requires the following resources:
|
||||||
|
|
||||||
|
- The :minio-git:`minio-operator <minio-operator>` github repository.
|
||||||
|
|
||||||
|
- An existing Kubernetes cluster with a distributed MinIO deployment.
|
||||||
|
|
||||||
|
- A host machine with ``kubectl`` installed. See
|
||||||
|
:kube-docs:`Install and Set Up kubectl <tasks/tools/install-kubectl/>`
|
||||||
|
|
||||||
|
The host machine should be configured such that ``kubectl`` can access the
|
||||||
|
Kubernetes cluster. See :kube-docs:`Access Applications in a Cluster
|
||||||
|
<tasks/access-application-cluster>` for more information.
|
||||||
|
|
||||||
|
Considerations
|
||||||
|
--------------
|
||||||
|
|
||||||
|
.. ToDo:
|
||||||
|
|
||||||
|
- Document recommended resource allocation (CPU, RAM, etc.)
|
||||||
|
- Document recommended number of MinIO pods to Nodes
|
||||||
|
- Document recommended ratio of PV to Physical Disk
|
||||||
|
|
||||||
|
Procedure
|
||||||
|
---------
|
||||||
|
|
||||||
|
1) First Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
|
|
||||||
|
2) Second Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
|
|
||||||
41
source/kubernetes/minio-kubernetes.rst
Normal file
41
source/kubernetes/minio-kubernetes.rst
Normal file
@ -0,0 +1,41 @@
|
|||||||
|
=====================
|
||||||
|
MinIO for Kuberenetes
|
||||||
|
=====================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 2
|
||||||
|
|
||||||
|
MinIO is a high performance distributed object storage server, designed for
|
||||||
|
large-scale private cloud infrastructure. MinIO is designed in a cloud-native
|
||||||
|
manner to scale sustainably in multi-tenant environments. Orchestration
|
||||||
|
platforms like Kubernetes provide perfect cloud-native environment to deploy and
|
||||||
|
scale MinIO. The :minio-git:`MinIO Kubernetes Operator </minio-operator>` brings
|
||||||
|
native MinIO support to Kubernetes.
|
||||||
|
|
||||||
|
.. image:: /images/Kubernetes-Minio.svg
|
||||||
|
:align: center
|
||||||
|
:width: 90%
|
||||||
|
:class: no-scaled-link
|
||||||
|
:alt: Kubernetes Orchestration with the MinIO Operator facilitates automated deployment of MinIO clusters.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. versionchanged:: VERSION.VERSION
|
||||||
|
|
||||||
|
This feature was added in VERSION, upgrade to VERSION
|
||||||
|
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:titlesonly:
|
||||||
|
:hidden:
|
||||||
|
|
||||||
|
/kubernetes/quickstart
|
||||||
|
/kubernetes/deploy-on-kubernetes
|
||||||
|
/kubernetes/manage-on-kubernetes
|
||||||
|
/kubernetes/enforce-security
|
||||||
|
/kubernetes/operator-kes
|
||||||
|
/kubernetes/operator-mcs
|
||||||
|
/kubernetes/operator-reference
|
||||||
79
source/kubernetes/operator-kes.rst
Normal file
79
source/kubernetes/operator-kes.rst
Normal file
@ -0,0 +1,79 @@
|
|||||||
|
========================================
|
||||||
|
Deploy MinIO KES on a Kubernetes Cluster
|
||||||
|
========================================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 2
|
||||||
|
|
||||||
|
MinIO KES is a stateless and distributed key-management system for
|
||||||
|
high-performance applications. KES provides a bridge between applications
|
||||||
|
running in containerized deployments, like Kubernetes, and centralized Key
|
||||||
|
Mannagement Systems (KMS) like Hashicorp Vault or Amazon Web Services (AWS) KMS. This
|
||||||
|
tutorial covers the information necessary for using the MinIO Kubernetes
|
||||||
|
Operator (``minio-operator``) to deploy MinIO KES instances on a Kubernetes
|
||||||
|
Cluster.
|
||||||
|
|
||||||
|
You should have basic familiarity with the Kubernetes ecosystem and your
|
||||||
|
preferred KMS backend prior to starting this tutorial. Defer to the official
|
||||||
|
documentation for :kube-docs:`Kubernetes` and your preferred KMS backend for
|
||||||
|
more complete learning resource. While the MinIO docs make a best-effort
|
||||||
|
to cover third-party concepts and configurations, you should not depend on
|
||||||
|
this tutorial as the only source of information on third-party products.
|
||||||
|
|
||||||
|
For more complete documentation on MinIO KES, see <future page>.
|
||||||
|
|
||||||
|
Prerequisites
|
||||||
|
-------------
|
||||||
|
|
||||||
|
This tutorial requires the following resources:
|
||||||
|
|
||||||
|
Kubernetes Cluster
|
||||||
|
You should have access to a running Kubernetes cluster.
|
||||||
|
|
||||||
|
The Kubernetes cluster
|
||||||
|
|
||||||
|
- The Kubernetes cluster must have at least one running
|
||||||
|
:minio-git:`minio-operator <minio-operator>` instance. See
|
||||||
|
<future minio-operator deployment proc> for installation instructions.
|
||||||
|
|
||||||
|
The Kubernetes cluster should have *at least* **one** node with enough
|
||||||
|
resources to launch additional pods.
|
||||||
|
|
||||||
|
- The ``minio-operator`` has TLS configured and enabled. See
|
||||||
|
<future minio-operator security config docs> for configuration instructions.
|
||||||
|
|
||||||
|
- An x.509 Certificate and corresponding private key for MinIO KES to use
|
||||||
|
for mTLS authentication and authorization.
|
||||||
|
|
||||||
|
- A supported Key Management System backend. MinIO KES supports the following KMS providers:
|
||||||
|
|
||||||
|
- `Hashicorp Vault <https://www.vaultproject.io/?ref=minio>`__
|
||||||
|
- `Amazon Web Services KMS <https://aws.amazon.com/kms/?ref=minio>`__
|
||||||
|
- `Gemalto SafeNet KeySecure <https://www.netapp.com/us/products/storage-security-systems/key-management/keysecure-k460.aspx?ref=minio>`__
|
||||||
|
|
||||||
|
Procedure
|
||||||
|
---------
|
||||||
|
|
||||||
|
Procedure
|
||||||
|
---------
|
||||||
|
|
||||||
|
1) First Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
|
|
||||||
|
2) Second Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
74
source/kubernetes/operator-mcs.rst
Normal file
74
source/kubernetes/operator-mcs.rst
Normal file
@ -0,0 +1,74 @@
|
|||||||
|
===================================================
|
||||||
|
Deploy MinIO Console Server on a Kubernetes Cluster
|
||||||
|
===================================================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 2
|
||||||
|
|
||||||
|
MinIO Console Server (MCS) is a graphical user interface for administrating
|
||||||
|
MinIO servers. This tutorial covers the information necessary for using the
|
||||||
|
MinIO Kubernetes Operator (``minio-operator``) to deploy MinIO MCS instances on
|
||||||
|
a Kubernetes Cluster.
|
||||||
|
|
||||||
|
You should have basic familiarity with the Kubernetes ecosystem prior to
|
||||||
|
starting this tutorial. Defer to the official documentation for
|
||||||
|
:kube-docs:`Kubernetes` for more complete learning resources. While the MinIO
|
||||||
|
docs make a best-effort to cover third-party concepts and configurations, you
|
||||||
|
should not depend on this tutorial as the only source of information on
|
||||||
|
third-party products.
|
||||||
|
|
||||||
|
For more complete documentation on MinIO MCS, see <future page>.
|
||||||
|
|
||||||
|
Prerequisites
|
||||||
|
-------------
|
||||||
|
|
||||||
|
This tutorial requires the following resources:
|
||||||
|
|
||||||
|
Kubernetes Cluster
|
||||||
|
You should have access to a running Kubernetes cluster.
|
||||||
|
|
||||||
|
The Kubernetes cluster should have *at least* **one** node with enough
|
||||||
|
resources to launch additional pods.
|
||||||
|
|
||||||
|
MinIO Kubernetes Operator
|
||||||
|
The Kubernetes cluster must have at least one running
|
||||||
|
:minio-git:`minio-operator <minio-operator>` instance. See <future
|
||||||
|
minio-operator deployment proc> for installation instructions.
|
||||||
|
|
||||||
|
The MinIO operator *must* have TLS configured and enabled. See <future
|
||||||
|
security config docs> for configuration instructions.
|
||||||
|
|
||||||
|
MinIO Deployment
|
||||||
|
For a tutorial on deploying MinIO on Kubernetes, see
|
||||||
|
:doc:`/kubernetes/deploy-on-kubernetes`.
|
||||||
|
|
||||||
|
For a shorter tutorial for local development only, see
|
||||||
|
:doc:`/kubernetes/quickstart`.
|
||||||
|
|
||||||
|
The MinIO deployment must have at least one MinIO user with administrative
|
||||||
|
privileges for the MCS instance to use for authentication and authorization.
|
||||||
|
See <future security docs> for more information on configuring MinIO users.
|
||||||
|
|
||||||
|
Procedure
|
||||||
|
---------
|
||||||
|
|
||||||
|
1) First Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
|
|
||||||
|
2) Second Step Header
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a) First Substep
|
||||||
|
````````````````
|
||||||
|
|
||||||
|
b) Second Substep
|
||||||
|
`````````````````
|
||||||
133
source/kubernetes/operator-reference.rst
Normal file
133
source/kubernetes/operator-reference.rst
Normal file
@ -0,0 +1,133 @@
|
|||||||
|
========================
|
||||||
|
MinIO Operator Reference
|
||||||
|
========================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 2
|
||||||
|
|
||||||
|
This document explains the various fields supported by MinIO Operator and its
|
||||||
|
CRD's and how to use these fields to deploy and access MinIO server clusters.
|
||||||
|
|
||||||
|
MinIO Operator creates native Kubernetes resources within the cluster. The
|
||||||
|
operator uses the name of the created MinIO Instance as a prefix for
|
||||||
|
all resources created by the operator. For example, if deploying a
|
||||||
|
MinIO instance named ``minioinstance``, the operator creates the following
|
||||||
|
resources with their associated names:
|
||||||
|
|
||||||
|
- Headless Service: ``minioinstance-hl-svc``
|
||||||
|
- StatefulSet: ``minioinstance``
|
||||||
|
- Secret: ``minioinstance-tls`` (If :kubeconf:`spec.requestAutoCert` is enabled)
|
||||||
|
- CertificateSigningRequest: ``minioinstance-csr`` (If :kubeconf:`spec.requestAutoCert` is enabled)
|
||||||
|
|
||||||
|
The MinIO Kubernetes Operator is under active development. The contents of
|
||||||
|
this page may change at any time.
|
||||||
|
|
||||||
|
Configuration File Overview
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
The following example shows all possible MinIO Kubernetes Operator configuration
|
||||||
|
options.
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
apiVerison: operator.min.io/v1
|
||||||
|
kind: "MinIOInstance"
|
||||||
|
metadata: <object>
|
||||||
|
scheduler: <string>
|
||||||
|
spec:
|
||||||
|
metadata: <object>
|
||||||
|
image: <string>
|
||||||
|
zones: <int>
|
||||||
|
volumesPerServer: <int>
|
||||||
|
imagePullSecret: <string>
|
||||||
|
credsSecret: <string>
|
||||||
|
replicas: <int>
|
||||||
|
podManagementPolicy: <string>
|
||||||
|
mountPath: <string>
|
||||||
|
subPath: <string>
|
||||||
|
volumeClaimTemplate: <object>
|
||||||
|
env: <object>
|
||||||
|
requestAutoCert: <bool>
|
||||||
|
certConfig: <object>
|
||||||
|
externalCertSecret: <object>
|
||||||
|
resources: <object>
|
||||||
|
liveness: <object>
|
||||||
|
nodeSelector: <object>
|
||||||
|
tolerations: <object>
|
||||||
|
securityContext: <object>
|
||||||
|
serviceAccountName: <string>
|
||||||
|
mcs:
|
||||||
|
image: <string>
|
||||||
|
replicas: <int>
|
||||||
|
mcsSecret: <string>
|
||||||
|
metadata: <object>
|
||||||
|
kes:
|
||||||
|
replicas: <int>
|
||||||
|
image: <string>
|
||||||
|
configSecret: <string>
|
||||||
|
metadata: <object>
|
||||||
|
|
||||||
|
Configuration Options
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
.. kubeconf:: kind
|
||||||
|
|
||||||
|
*Type*: String
|
||||||
|
|
||||||
|
Specify ``MinIOInstance``.
|
||||||
|
|
||||||
|
.. kubeconf:: metadata
|
||||||
|
|
||||||
|
*Type*: Object
|
||||||
|
|
||||||
|
Metadata related to the ``MinIOInstance``. For example, the
|
||||||
|
following sets the ``label`` for the ``MinIOInstance`` object:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
metadata:
|
||||||
|
labels: minio
|
||||||
|
|
||||||
|
See :kube-api:`#objectmeta-v1-meta` for more complete documentation on
|
||||||
|
supported metadata options.
|
||||||
|
|
||||||
|
.. kubeconf:: spec
|
||||||
|
|
||||||
|
*Type*: Object
|
||||||
|
|
||||||
|
The specifications used by the MinIO Operator to deploy the MinIO
|
||||||
|
server cluster.
|
||||||
|
|
||||||
|
Options marked as **Required** must be included in the configuration
|
||||||
|
document.
|
||||||
|
|
||||||
|
.. kubeconf:: spec.metadata
|
||||||
|
|
||||||
|
*Type* : Object
|
||||||
|
|
||||||
|
Metadata related to all pods launched by the MinIO operator. For example, the
|
||||||
|
following sets the ``label`` for all pods launched by the MinIO instance
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
metadata:
|
||||||
|
labels: minio
|
||||||
|
|
||||||
|
See :kube-api:`metadata reference documentation <#objectmeta-v1-meta>` for
|
||||||
|
more complete documentation on supported metadata options.
|
||||||
|
|
||||||
|
.. kubeconf:: spec.requestAutoCert
|
||||||
|
|
||||||
|
*Type*: Boolean
|
||||||
|
|
||||||
|
*Defaults*: ``false``
|
||||||
|
|
||||||
|
Specify ``true`` to enable automatic TLS certificate generation for each
|
||||||
|
resource created by the MinIO Operator. The operator uses the root
|
||||||
|
Certificate Authority (CA) configured for the Kubernetes cluster to generate
|
||||||
|
the required Certificate Signing Requests (CSR).
|
||||||
|
|
||||||
229
source/kubernetes/quickstart.rst
Normal file
229
source/kubernetes/quickstart.rst
Normal file
@ -0,0 +1,229 @@
|
|||||||
|
============================================
|
||||||
|
Quickstart: Deploy a Standalone MinIO Server
|
||||||
|
============================================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
Overview
|
||||||
|
--------
|
||||||
|
|
||||||
|
This tutorial uses the MinIO Operator to create a standalone MinIO server on a
|
||||||
|
local Kubernetes cluster. Standalone MinIO deployments are best suited for local
|
||||||
|
development of applications using MinIO for object storage. For a tutorial on
|
||||||
|
creating a production-grade MinIO deployment on a Kubernetes cluster, see
|
||||||
|
:doc:`/kubernetes/deploy-on-kubernetes`.
|
||||||
|
|
||||||
|
By default, this tutorial creates a standalone MinIO deployment with the
|
||||||
|
following components:
|
||||||
|
|
||||||
|
- 1 MinIO server instance with TLS enabled.
|
||||||
|
- 4 x 100MB storage volumes
|
||||||
|
- 1 MinIO Minio Console Service instance.
|
||||||
|
- 1 MinIO Operator instance.
|
||||||
|
|
||||||
|
You should have basic familiarity with Kubernetes, its associated terminology,
|
||||||
|
and its command line tools prior to starting this tutorial. While the MinIO
|
||||||
|
documentation makes a best-effort to address Kubernetes-specific information,
|
||||||
|
you should review the official Kubernetes :kube-docs:`documentation <>` for more
|
||||||
|
complete coverage.
|
||||||
|
|
||||||
|
.. _minio-kubernetes-quickstart-prerequisites:
|
||||||
|
|
||||||
|
Prerequisites
|
||||||
|
-------------
|
||||||
|
|
||||||
|
This tutorial requires the following resources:
|
||||||
|
|
||||||
|
- The :minio-git:`minio-operator <minio-operator>` github repository.
|
||||||
|
|
||||||
|
- The `kind <https://kind.sigs.k8s.io/>`__ Kubernetes cluster deployment tool.
|
||||||
|
Defer to the ``kind``
|
||||||
|
`Quick Start <https://kind.sigs.k8s.io/docs/user/quick-start/>`__ for
|
||||||
|
installation instructions and related dependencies.
|
||||||
|
|
||||||
|
- A host machine where you have rights to install and run software. The
|
||||||
|
host machine **must** have *at least* the following available resources:
|
||||||
|
|
||||||
|
- 10GB of free storage space.
|
||||||
|
- 2GB of free system memory (RAM)
|
||||||
|
- 2 or more physical CPUs.
|
||||||
|
|
||||||
|
Procedure
|
||||||
|
---------
|
||||||
|
|
||||||
|
1) Download and Configure Prerequisites
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
a\) Clone the ``minio-operator`` github repository
|
||||||
|
Issue the following command in a terminal or shell on the host machine
|
||||||
|
to clone the :minio-git:`minio-operator <minio-operator>` github repository.
|
||||||
|
|
||||||
|
.. include:: /includes/minio-kubernetes-operator.rst
|
||||||
|
|
||||||
|
The github repository contains the MinIO Kubernetes Operator and the example
|
||||||
|
configuration files used as part of this tutorial.
|
||||||
|
|
||||||
|
b\) Install and configure ``kind``
|
||||||
|
Follow the instructions on the ``kind``
|
||||||
|
`Quick Start <https://kind.sigs.k8s.io/docs/user/quick-start/>`__ guide.
|
||||||
|
|
||||||
|
Once installed, use the following ``kind`` cluster configuration file to
|
||||||
|
create a Kubernetes cluster that can support a standalone MinIO server:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
kind: Cluster
|
||||||
|
apiVersion: kind.x-k8s.io/v1alpha4
|
||||||
|
nodes:
|
||||||
|
- role: control-plane
|
||||||
|
- role: worker
|
||||||
|
|
||||||
|
Issue the following command in a terminal or shell on the host machine to
|
||||||
|
create the local Kubernetes cluster:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
kind create cluster --name minio-local --config.yaml
|
||||||
|
|
||||||
|
To confirm the cluster is available, run the following command:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
kubectl --cluster-info --context kind-minio-local
|
||||||
|
|
||||||
|
Take note of the hostnames assigned to each component in the Kubernetes
|
||||||
|
cluster.
|
||||||
|
|
||||||
|
2) Start the MinIO Kubernetes Operator
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Issue the following command in a terminal or shell on the host machine to
|
||||||
|
start the MinIO Kubernetes Operator.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
kubectl apply -f ~/minio-kubernetes/git/minio-operator/minio-operator.yaml
|
||||||
|
|
||||||
|
The ``minio-operator.yaml`` configuration file creates a
|
||||||
|
``minio-operator`` deployment in the Kubernetes cluster.
|
||||||
|
|
||||||
|
3) Configure the Storage Layer
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The example MinIO server configuration used in this tutorial requires four
|
||||||
|
:kube-docs:`persistent volumes <storage/persistent-volumes/>` to start
|
||||||
|
successfully. This configuration enables features such as :ref:`erasure coding
|
||||||
|
<minio-erasure-coding>`.
|
||||||
|
|
||||||
|
Create four Kubernetes persistent volumes for use by the MinIO server instance.
|
||||||
|
MinIO recommends creating :kube-docs:`local <storage/volumes/#local>` persistent
|
||||||
|
volumes. The following template provides all required fields for creating the
|
||||||
|
required persistent volumes:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
apiVersion: v1
|
||||||
|
kind: PersistentVolume
|
||||||
|
metadata:
|
||||||
|
name: minioexample-pv1
|
||||||
|
spec:
|
||||||
|
capacity:
|
||||||
|
storage: 10Gi # specify the maximum size of the storage device
|
||||||
|
volumeMode: Filesystem
|
||||||
|
accessModes:
|
||||||
|
- ReadWriteOnce
|
||||||
|
persistentVolumeReclaimPolicy: Retain
|
||||||
|
storageClassName: local-storage-class
|
||||||
|
local:
|
||||||
|
path: /var/export1 # specify path to local volume on host
|
||||||
|
nodeAffinity:
|
||||||
|
required:
|
||||||
|
nodeSelectorTerms:
|
||||||
|
- matchExpressions:
|
||||||
|
- key: kubernetes.io/hostname
|
||||||
|
operator: In
|
||||||
|
values:
|
||||||
|
- minio-local-worker #specify hostname prefix of preferred node
|
||||||
|
|
||||||
|
Change the following configuration options as appropriate for the host
|
||||||
|
machine configuration:
|
||||||
|
|
||||||
|
- ``spec.capacity.storage`` ( :kube-docs:`reference <concepts/storage/persistent-volumes/#capacity>`)
|
||||||
|
- ``spec.local.path`` ( :kube-api:`reference <#localvolumesource-v1-core>`)
|
||||||
|
- ``spec.nodeAffinity.required.matchExpressions.key.values`` (:kube-api:`reference <#nodeselectorrequirement-v1-core>`)
|
||||||
|
|
||||||
|
Issue the following command against each persistent volume configuration file
|
||||||
|
to create the associated resources. Replace ``<pv-filename>`` with the name
|
||||||
|
of each persistent volume configuration file.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
kubectl apply -f ~/minio-kubernetes/<pv-filename>.yaml
|
||||||
|
|
||||||
|
Issue the following command to check the state of the persistent volumes:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
kubectl get pv
|
||||||
|
|
||||||
|
The output should include the four created persistent volumes.
|
||||||
|
|
||||||
|
4) Create the MinIO Server
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Issue the following command in a terminal or shell to create the MinIO
|
||||||
|
standalone instance using the MinIO Kubernetes Operator:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
kubectl apply -f ~/minio-kubernetes/minio-operator/examples/minioinstance-standalone.yaml
|
||||||
|
|
||||||
|
Issue the following command to check the state of the minio instance:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
kubectl get pods
|
||||||
|
|
||||||
|
The output should include a pod running the MinIO server.
|
||||||
|
|
||||||
|
5) Connect to the MinIO Server
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The ``minioinstance-standalone.yaml`` configuration file also creates a
|
||||||
|
Kubernetes Service to manage communications to and from pods running the MinIO
|
||||||
|
service. Issue the following command to get the IP address of the service:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
kubectl get services
|
||||||
|
|
||||||
|
The default access key is ``minio-admin`` and the default secret key is
|
||||||
|
``minio-admin``.
|
||||||
|
|
||||||
|
You must use the IP address of the ``minio-service`` to access the MinIO
|
||||||
|
server. For example, if the IP address is ``192.51.100.21``, enter the URL
|
||||||
|
``http://192.51.100.21:9000`` into your browser to access the MinIO server.
|
||||||
|
|
||||||
|
To connect using the ``mc`` client, issue the following command on in a
|
||||||
|
terminal or shell:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc config host add minio http://192.51.100.21 minio-admin minio-admin
|
||||||
|
|
||||||
|
Next Steps
|
||||||
|
~~~~~~~~~~
|
||||||
|
|
||||||
|
- Perform CRUD operations on a MinIO Server (ToDo)
|
||||||
|
-
|
||||||
|
|
||||||
243
source/minio-cli/minio-mc-admin.rst
Normal file
243
source/minio-cli/minio-mc-admin.rst
Normal file
@ -0,0 +1,243 @@
|
|||||||
|
==========================
|
||||||
|
MinIO Admin (``mc admin``)
|
||||||
|
==========================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc admin
|
||||||
|
|
||||||
|
The MinIO Client :mc-cmd:`mc` command line tool provides the :mc-cmd:`mc admin`
|
||||||
|
command for performing administrative tasks on your MinIO deployments.
|
||||||
|
|
||||||
|
While :mc-cmd:`mc` supports any S3-compatible service,
|
||||||
|
:mc-cmd:`mc admin` *only* supports MinIO deployments.
|
||||||
|
|
||||||
|
:mc-cmd:`mc admin` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc admin [FLAGS] COMMAND [ARGUMENTS]
|
||||||
|
|
||||||
|
Command Quick reference
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
The following table lists :mc-cmd:`mc admin` commands:
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
:widths: 25 75
|
||||||
|
:width: 100%
|
||||||
|
|
||||||
|
* - Command
|
||||||
|
- Description
|
||||||
|
|
||||||
|
* - :mc:`mc service`
|
||||||
|
- Restart or stop MinIO servers.
|
||||||
|
|
||||||
|
|
||||||
|
.. _mc-admin-install:
|
||||||
|
|
||||||
|
Installation
|
||||||
|
------------
|
||||||
|
|
||||||
|
.. include:: /includes/minio-mc-installation.rst
|
||||||
|
|
||||||
|
Quickstart
|
||||||
|
----------
|
||||||
|
|
||||||
|
Ensure that the host machine has :command:`mc`
|
||||||
|
:ref:`installed <mc-admin-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 the
|
||||||
|
deployment to the :command:`mc` configuration.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
bash +o history
|
||||||
|
mc config host add <ALIAS> <ENDPOINT> ACCESS_KEY SECRET_KEY
|
||||||
|
bash -o history
|
||||||
|
|
||||||
|
Replace each argument with the required values. Specifying only the
|
||||||
|
``mc config host add`` command starts an input prompt for entering the
|
||||||
|
required values.
|
||||||
|
|
||||||
|
Use the :ref:`mc admin info <mc-admin-info>` command to test the connection to
|
||||||
|
the newly added MinIO deployment:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin info <ALIAS>
|
||||||
|
|
||||||
|
Global Options
|
||||||
|
--------------
|
||||||
|
|
||||||
|
:mc-cmd:`mc admin` supports the same global options as
|
||||||
|
:mc-cmd:`mc`. See :ref:`minio-mc-global-options`.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. _mc-admin-info:
|
||||||
|
|
||||||
|
``mc admin info``
|
||||||
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The ``mc admin info`` command returns diagnostic information of a MinIO server.
|
||||||
|
|
||||||
|
The command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
NAME:
|
||||||
|
mc admin info COMMAND <ALIAS>
|
||||||
|
|
||||||
|
FLAGS
|
||||||
|
--debug Returns verbose information for debugging
|
||||||
|
|
||||||
|
If the specified ``<ALIAS>`` corresponds to a distributed MinIO deployment, the
|
||||||
|
command returns information for each MinIO server in the deployment. Use
|
||||||
|
:subcommand:`mc alias add` to list the currently configured aliases and their
|
||||||
|
corresponding endpoints.
|
||||||
|
|
||||||
|
*Display MinIO Server Information*
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin info myminio
|
||||||
|
|
||||||
|
.. _mc-admin-policy:
|
||||||
|
|
||||||
|
``mc admin policy``
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The ``mc admin policy`` command can add, remove, list, get info, and set
|
||||||
|
policies for a user on the MinIO server. MinIO policies are fully compatible
|
||||||
|
with AWS IAM S3 policies. See
|
||||||
|
:aws-docs:`AWS Policies and Permissions in Amazon S3
|
||||||
|
<AmazonS3/latest/dev/access-policy-language-overview.html>`.
|
||||||
|
|
||||||
|
The command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
NAME:
|
||||||
|
mc admin policy COMMAND <ALIAS>
|
||||||
|
|
||||||
|
COMMANDS:
|
||||||
|
add add new policy
|
||||||
|
remove remove policy
|
||||||
|
list list all policies
|
||||||
|
info show info on a policy
|
||||||
|
set set IAM policy on a user or group
|
||||||
|
|
||||||
|
If the specified ``<ALIAS>`` corresponds to a distributed MinIO deployment, the
|
||||||
|
command adds the policy to each MinIO server in the deployment. Use
|
||||||
|
:subcommand:`mc alias add` to list the currently configured aliases and their
|
||||||
|
corresponding endpoints.
|
||||||
|
|
||||||
|
MinIO servers include the following canned policies:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
diagnostics
|
||||||
|
readonly
|
||||||
|
readwrite
|
||||||
|
writeonly
|
||||||
|
|
||||||
|
Example: Add a new policy to a MinIO server
|
||||||
|
```````````````````````````````````````````
|
||||||
|
|
||||||
|
Applying the following example policy ``listbucketsonly.json`` to a user
|
||||||
|
restricts that user to only listing the top layer buckets in the MinIO server.
|
||||||
|
The user cannot list any other resources, including any objects in the top layer
|
||||||
|
buckets.
|
||||||
|
|
||||||
|
The following operation creates the policy on the ``/tmp`` folder
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
cat <<EOF >> /tmp/listbucketsonly.json
|
||||||
|
{
|
||||||
|
"Version": "2012-10-17",
|
||||||
|
"Statement": [
|
||||||
|
{
|
||||||
|
"Effect": "Allow",
|
||||||
|
"Action": [
|
||||||
|
"s3:ListAllMyBuckets"
|
||||||
|
],
|
||||||
|
"Resource": [
|
||||||
|
"arn:aws:s3:::*"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
EOF
|
||||||
|
|
||||||
|
Use the ``mc admin policy add`` command to add the policy to the MinIO server.
|
||||||
|
Replace ``<ALIAS>`` with the alias for the desired MinIO deployment.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc admin policy add <ALIAS> listbucketsonly /tmp/listbucketsonly.json
|
||||||
|
|
||||||
|
Example: Remove a policy from a MinIO Server
|
||||||
|
````````````````````````````````````````````
|
||||||
|
|
||||||
|
Use the ``mc admin policy <ALIAS> remove`` command to remove a policy from the
|
||||||
|
MinIO server.
|
||||||
|
|
||||||
|
.. todo : what happens to current users who have that policy?
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc admin policy remove <ALIAS> listbucketsonly
|
||||||
|
|
||||||
|
Example: Display an existing policy
|
||||||
|
```````````````````````````````````
|
||||||
|
|
||||||
|
Use the ``mc admin policy <ALIAS> info`` command to retrieve policy's JSON
|
||||||
|
structure. Replace ``<ALIAS>`` with the alias for the desired MinIO deployment.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc admin policy info <ALIAS> writeonly
|
||||||
|
|
||||||
|
Example: Associate a policy to a user or group
|
||||||
|
``````````````````````````````````````````````
|
||||||
|
|
||||||
|
Use the ``mc admin policy <ALIAS> set`` command to set a policy to a user or
|
||||||
|
group:
|
||||||
|
|
||||||
|
**Set policy for a user**
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc admin policy set <ALIAS> <POLICY> user=<USERNAME>
|
||||||
|
|
||||||
|
**Set policy for a group**
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc admin policy set <ALIAS> <POLICY> group=<GROUP>
|
||||||
|
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:titlesonly:
|
||||||
|
:hidden:
|
||||||
|
:glob:
|
||||||
|
|
||||||
|
/minio-cli/minio-mc-admin/*
|
||||||
51
source/minio-cli/minio-mc-admin/mc-admin-info.rst
Normal file
51
source/minio-cli/minio-mc-admin/mc-admin-info.rst
Normal file
@ -0,0 +1,51 @@
|
|||||||
|
=================
|
||||||
|
``mc admin info``
|
||||||
|
=================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc admin info
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-admin-info-desc
|
||||||
|
|
||||||
|
The :mc-cmd:`mc admin info` command displays information on a MinIO server.
|
||||||
|
For distributed MinIO deployments, :mc:`mc admin info` displays information
|
||||||
|
for each MinIO server in the deployment.
|
||||||
|
|
||||||
|
.. end-mc-admin-info-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc-cmd:`mc admin info` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin info TARGET
|
||||||
|
|
||||||
|
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
|
||||||
307
source/minio-cli/minio-mc-admin/mc-admin-policy.rst
Normal file
307
source/minio-cli/minio-mc-admin/mc-admin-policy.rst
Normal file
@ -0,0 +1,307 @@
|
|||||||
|
===================
|
||||||
|
``mc admin policy``
|
||||||
|
===================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 2
|
||||||
|
|
||||||
|
.. mc:: mc admin policy
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-admin-policy-desc
|
||||||
|
|
||||||
|
The :mc-cmd:`mc admin policy` command manages policies for use with MinIO
|
||||||
|
Policy-Based Access Control (PBAC). MinIO PBAC uses IAM-compatible policy JSON
|
||||||
|
documents to define rules for accessing resources on a MinIO server.
|
||||||
|
|
||||||
|
.. end-mc-admin-policy-desc
|
||||||
|
|
||||||
|
For complete documentation on MinIO PBAC, including policy document JSON
|
||||||
|
structure and syntax, see
|
||||||
|
:doc:`/security/minio-security-policy-based-access-control`.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin policy set myminio myReadOnlyPolicy readOnlyUser
|
||||||
|
|
||||||
|
mc admin policy set myminio myReadWritePolicy readWriteGroup
|
||||||
|
|
||||||
|
For more information on creating users and groups, see
|
||||||
|
:mc-cmd:`mc admin users` and :mc-cmd:`mc admin groups` respectively.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Create a Policy
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: myminio-alias
|
||||||
|
:end-before: myminio-alias
|
||||||
|
|
||||||
|
For example, consider the following JSON policy document:
|
||||||
|
|
||||||
|
.. code-block:: javascript
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
{
|
||||||
|
"Version": "2012-10-17",
|
||||||
|
"Statement": [
|
||||||
|
{
|
||||||
|
"Effect": "Allow",
|
||||||
|
"Action": [
|
||||||
|
"s3:ListAllMyBuckets"
|
||||||
|
],
|
||||||
|
"Resource": [
|
||||||
|
"arn:minio:s3:::*"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin policy add myminio listbucketsonly /path/to/listbucketsonly.json
|
||||||
|
|
||||||
|
You can associate the new ``listbucketsonly`` policy to users or groups on the
|
||||||
|
``myminio`` deployment using the :mc-cmd:`mc admin policy set` command.
|
||||||
|
|
||||||
|
List Available Policies
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
The following :mc-cmd:`mc admin policy list` command lists the available
|
||||||
|
policies on the ``play`` MinIO deployment:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
Remove a Policy
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
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
|
||||||
|
deployment. The command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin policy add TARGET POLICYNAME POLICYPATH
|
||||||
|
|
||||||
|
The :mc-cmd:`mc admin policy add` command accepts the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment on which
|
||||||
|
to add the new policy.
|
||||||
|
|
||||||
|
.. mc-cmd:: POLICYNAME
|
||||||
|
|
||||||
|
The name of the policy to add.
|
||||||
|
|
||||||
|
Specifying the name of an existing policy overwrites that policy on the
|
||||||
|
:mc-cmd:`~mc admin policy TARGET` MinIO deployment.
|
||||||
|
|
||||||
|
.. mc-cmd:: POLICYPATH
|
||||||
|
|
||||||
|
The file path to the policy to add. The file *must* be a JSON-formatted
|
||||||
|
file with :iam-docs:`IAM-compatible syntax <reference_policies.html>`.
|
||||||
|
|
||||||
|
.. mc-cmd:: list
|
||||||
|
:fullpath:
|
||||||
|
|
||||||
|
This command lists all policies on the target MinIO deployment. The command
|
||||||
|
has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin policy list TARGET
|
||||||
|
|
||||||
|
For example, the following command lists all policies on the
|
||||||
|
``play`` MinIO deployment:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin policy list play
|
||||||
|
|
||||||
|
The :mc-cmd:`mc admin policy add` command accepts the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment from which
|
||||||
|
the command lists the available policies.
|
||||||
|
|
||||||
|
.. mc-cmd:: info
|
||||||
|
:fullpath:
|
||||||
|
|
||||||
|
This command returns the specified policy in JSON format if it exists
|
||||||
|
on the target MinIO deployment. The command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin policy info TARGET POLICYNAME
|
||||||
|
|
||||||
|
:mc-cmd:`mc admin policy info` accepts the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
The :mc-cmd:`alias <mc alias>` of a configured MinIO deployment from
|
||||||
|
which the command returns information on the specified policy.
|
||||||
|
|
||||||
|
.. mc-cmd:: POLICYNAME
|
||||||
|
|
||||||
|
The name of the policy whose details the command returns.
|
||||||
|
|
||||||
|
.. 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:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin policy set TARGET POLICYNAME [ user=USERNAME | group=GROUPNAME ]
|
||||||
|
|
||||||
|
The command accepts the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
The :mc-cmd:`alias <mc-alias>` of a configured MinIO deployment on which
|
||||||
|
the command associates the :mc-cmd:`~mc admin policy set POLICYNAME`
|
||||||
|
to the :mc-cmd:`~mc admin policy set user` or
|
||||||
|
:mc-cmd:`~mc admin policy set group`.
|
||||||
|
|
||||||
|
.. mc-cmd:: POLICYNAME
|
||||||
|
|
||||||
|
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:: user
|
||||||
|
|
||||||
|
The name of the user to which the command associates the
|
||||||
|
:mc-cmd:`~mc admin policy set POLICYNAME`.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd:`~mc admin policy set GROUP`
|
||||||
|
|
||||||
|
.. mc-cmd:: group
|
||||||
|
|
||||||
|
The name of the group to which the command associates the
|
||||||
|
:mc-cmd:`~mc admin policy set POLICYNAME`. All users with membership in
|
||||||
|
the group inherit the policies associated to the group.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd:`~mc admin policy set USER`
|
||||||
|
|
||||||
|
.. mc-cmd:: remove
|
||||||
|
:fullpath:
|
||||||
|
|
||||||
|
This command removes an existing policy from the target MinIO deployment. The
|
||||||
|
command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin policy remove TARGET POLICYNAME
|
||||||
|
|
||||||
|
The command accepts the following arguments:
|
||||||
|
|
||||||
|
.. 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`.
|
||||||
|
|
||||||
|
.. mc-cmd:: POLICYNAME
|
||||||
|
|
||||||
|
The name of the policy which the command removes from the
|
||||||
|
:mc-cmd:`~mc admin policy remove TARGET` deployment.
|
||||||
115
source/minio-cli/minio-mc-admin/mc-admin-service.rst
Normal file
115
source/minio-cli/minio-mc-admin/mc-admin-service.rst
Normal file
@ -0,0 +1,115 @@
|
|||||||
|
====================
|
||||||
|
``mc admin service``
|
||||||
|
====================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc admin service
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-admin-service-desc
|
||||||
|
|
||||||
|
The :mc-cmd:`mc admin service` command can restart or stop MinIO servers.
|
||||||
|
|
||||||
|
.. end-mc-admin-service-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc-cmd:`mc admin service` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin service COMMAND [ARGUMENTS]
|
||||||
|
|
||||||
|
:mc-cmd:`mc admin service` supports the following commands:
|
||||||
|
|
||||||
|
.. mc-cmd:: restart
|
||||||
|
|
||||||
|
Restarts MinIO servers.
|
||||||
|
|
||||||
|
:mc-cmd:`mc admin service restart` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin service restart TARGET
|
||||||
|
|
||||||
|
Specify the :mc-cmd:`alias <mc alias>` of a configured MinIO deployment.
|
||||||
|
:mc-cmd:`~mc admin service restart` restarts *all* MinIO servers in the
|
||||||
|
deployment.
|
||||||
|
|
||||||
|
.. mc-cmd:: stop
|
||||||
|
|
||||||
|
Stops MinIO servers.
|
||||||
|
|
||||||
|
:mc-cmd:`mc admin service stop` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin service stop TARGET
|
||||||
|
|
||||||
|
Specify the :mc-cmd:`alias <mc alias>` of a configured MinIO deployment.
|
||||||
|
: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
|
||||||
73
source/minio-cli/minio-mc-admin/mc-admin-update.rst
Normal file
73
source/minio-cli/minio-mc-admin/mc-admin-update.rst
Normal file
@ -0,0 +1,73 @@
|
|||||||
|
===================
|
||||||
|
``mc admin update``
|
||||||
|
===================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc admin update
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-admin-update-desc
|
||||||
|
|
||||||
|
The :mc-cmd:`mc admin update` command updates all MinIO servers in the
|
||||||
|
deployment. The command also supports using a private mirror server for
|
||||||
|
environments where the deployment does not have public internet access.
|
||||||
|
|
||||||
|
.. end-mc-admin-update-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc-cmd:`mc admin update` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc admin update ALIAS [MIRROR_URL]
|
||||||
|
|
||||||
|
:mc-cmd:`mc admin update` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: ALIAS
|
||||||
|
|
||||||
|
The :mc-cmd:`alias <mc alias>` of the MinIO deployment to update.
|
||||||
|
|
||||||
|
If the specified ``ALIAS`` corresponds to a distributed MinIO
|
||||||
|
deployment, :mc-cmd:`mc admin update` updates *all* MinIO servers
|
||||||
|
in the deployment at the same time. The command does not perform a
|
||||||
|
rolling upgrade or similar zero or near-zero downtime upgrade procedure.
|
||||||
|
|
||||||
|
Use :mc-cmd:`mc alias list` to review the configured aliases and their
|
||||||
|
corresponding MinIO deployment endpoints.
|
||||||
|
|
||||||
|
.. mc-cmd:: MIRROR_URL
|
||||||
|
|
||||||
|
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
|
||||||
326
source/minio-cli/minio-mc.rst
Normal file
326
source/minio-cli/minio-mc.rst
Normal file
@ -0,0 +1,326 @@
|
|||||||
|
=================
|
||||||
|
MinIO Client (mc)
|
||||||
|
=================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc
|
||||||
|
|
||||||
|
The MinIO Client :mc-cmd:`mc` command line tool provides a modern alternative
|
||||||
|
to UNIX commands like ``ls``, ``cat``, ``cp``, ``mirror``, and ``diff`` with
|
||||||
|
support for both filesystems and Amazon S3-compatible cloud storage services
|
||||||
|
(AWS Signature v2 and v4).
|
||||||
|
|
||||||
|
:mc-cmd:`mc` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc [FLAGS] COMMAND [COMMAND FLAGS | -h] [ARGUMENTS...] ALIAS
|
||||||
|
|
||||||
|
Command Quick Reference
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
The following table lists :mc-cmd:`mc` commands:
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
:widths: 25 75
|
||||||
|
:width: 100%
|
||||||
|
|
||||||
|
* - Command
|
||||||
|
- Description
|
||||||
|
|
||||||
|
* - :mc:`mc alias`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-alias.rst
|
||||||
|
:start-after: start-mc-alias-desc
|
||||||
|
:end-before: end-mc-alias-desc
|
||||||
|
|
||||||
|
* - :mc:`mc cat`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-cat.rst
|
||||||
|
:start-after: start-mc-cat-desc
|
||||||
|
:end-before: end-mc-cat-desc
|
||||||
|
|
||||||
|
* - :mc:`mc cp`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-cp.rst
|
||||||
|
:start-after: start-mc-cp-desc
|
||||||
|
:end-before: end-mc-cp-desc
|
||||||
|
|
||||||
|
* - :mc:`mc diff`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-diff.rst
|
||||||
|
:start-after: start-mc-diff-desc
|
||||||
|
:end-before: end-mc-diff-desc
|
||||||
|
|
||||||
|
* - :mc:`mc encrypt`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-encrypt.rst
|
||||||
|
:start-after: start-mc-encrypt-desc
|
||||||
|
:end-before: end-mc-encrypt-desc
|
||||||
|
|
||||||
|
* - :mc:`mc event`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-event.rst
|
||||||
|
:start-after: start-mc-event-desc
|
||||||
|
:end-before: end-mc-event-desc
|
||||||
|
|
||||||
|
* - :mc:`mc find`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-find.rst
|
||||||
|
:start-after: start-mc-find-desc
|
||||||
|
:end-before: end-mc-find-desc
|
||||||
|
|
||||||
|
* - :mc:`mc head`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-head.rst
|
||||||
|
:start-after: start-mc-head-desc
|
||||||
|
:end-before: end-mc-head-desc
|
||||||
|
|
||||||
|
* - :mc:`mc ilm`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-ilm.rst
|
||||||
|
:start-after: start-mc-ilm-desc
|
||||||
|
:end-before: end-mc-ilm-desc
|
||||||
|
|
||||||
|
* - :mc:`mc legalhold`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-legalhold.rst
|
||||||
|
:start-after: start-mc-legalhold-desc
|
||||||
|
:end-before: end-mc-legalhold-desc
|
||||||
|
|
||||||
|
* - :mc:`mc lock`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-lock.rst
|
||||||
|
:start-after: start-mc-lock-desc
|
||||||
|
:end-before: end-mc-lock-desc
|
||||||
|
|
||||||
|
* - :mc:`mc mb`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-mb.rst
|
||||||
|
:start-after: start-mc-mb-desc
|
||||||
|
:end-before: end-mc-mb-desc
|
||||||
|
|
||||||
|
* - :mc:`mc mirror`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-mirror.rst
|
||||||
|
:start-after: start-mc-mirror-desc
|
||||||
|
:end-before: end-mc-mirror-desc
|
||||||
|
|
||||||
|
* - :mc:`mc mv`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-mv.rst
|
||||||
|
:start-after: start-mc-mv-desc
|
||||||
|
:end-before: end-mc-mv-desc
|
||||||
|
|
||||||
|
* - :mc:`mc policy`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-policy.rst
|
||||||
|
:start-after: start-mc-policy-desc
|
||||||
|
:end-before: end-mc-policy-desc
|
||||||
|
|
||||||
|
* - :mc:`mc rb`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-rb.rst
|
||||||
|
:start-after: start-mc-rb-desc
|
||||||
|
:end-before: end-mc-rb-desc
|
||||||
|
|
||||||
|
* - :mc:`mc retention`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-retention.rst
|
||||||
|
:start-after: start-mc-retention-desc
|
||||||
|
:end-before: end-mc-retention-desc
|
||||||
|
|
||||||
|
* - :mc:`mc rm`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-rm.rst
|
||||||
|
:start-after: start-mc-rm-desc
|
||||||
|
:end-before: end-mc-rm-desc
|
||||||
|
|
||||||
|
* - :mc:`mc share`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-share.rst
|
||||||
|
:start-after: start-mc-share-desc
|
||||||
|
:end-before: end-mc-share-desc
|
||||||
|
|
||||||
|
* - :mc:`mc sql`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-sql.rst
|
||||||
|
:start-after: start-mc-sql-desc
|
||||||
|
:end-before: end-mc-sql-desc
|
||||||
|
|
||||||
|
* - :mc:`mc stat`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-stat.rst
|
||||||
|
:start-after: start-mc-stat-desc
|
||||||
|
:end-before: end-mc-stat-desc
|
||||||
|
|
||||||
|
* - :mc:`mc tree`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-tree.rst
|
||||||
|
:start-after: start-mc-tree-desc
|
||||||
|
:end-before: end-mc-tree-desc
|
||||||
|
|
||||||
|
* - :mc:`mc update`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-update.rst
|
||||||
|
:start-after: start-mc-update-desc
|
||||||
|
:end-before: end-mc-update-desc
|
||||||
|
|
||||||
|
* - :mc:`mc version`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-version.rst
|
||||||
|
:start-after: start-mc-version-desc
|
||||||
|
:end-before: end-mc-version-desc
|
||||||
|
|
||||||
|
* - :mc:`mc watch`
|
||||||
|
- .. include:: /minio-cli/minio-mc/mc-watch.rst
|
||||||
|
:start-after: start-mc-watch-desc
|
||||||
|
:end-before: end-mc-watch-desc
|
||||||
|
|
||||||
|
|
||||||
|
:mc-cmd:`mc` also includes an administration extension for managing MinIO
|
||||||
|
deployments. See :program:`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.
|
||||||
|
|
||||||
|
For Linux and OSX, the default configuration file location is
|
||||||
|
``~/.mc/config.json``.
|
||||||
|
|
||||||
|
For Windows, :mc-cmd:`mc` attempts to construct a default file path by trying
|
||||||
|
specific environment variables. If a variable is unset, :mc-cmd:`mc` moves
|
||||||
|
to the next variable. If all attempts fail, :mc-cmd:`mc` returns an error.
|
||||||
|
The following list describes each possible file path location in the order
|
||||||
|
:mc-cmd:`mc` checks them:
|
||||||
|
|
||||||
|
#. ``HOME\.mc\config.json``
|
||||||
|
#. ``USERPROFILE\.mc\config.json``
|
||||||
|
#. ``HOMEDRIVE+HOMEPATH\.mc\config.json``
|
||||||
|
|
||||||
|
.. _mc-install:
|
||||||
|
|
||||||
|
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>`.
|
||||||
|
|
||||||
|
.. 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 the S3 service.
|
||||||
|
|
||||||
|
- The ``--api`` flag is optional and defaults to ``S3v4`` if ommitted.
|
||||||
|
|
||||||
|
Replace each argument with the required values. Specifying only the
|
||||||
|
``mc config host add`` command starts an input prompt for entering the
|
||||||
|
required values.
|
||||||
|
|
||||||
|
Each of the following tabs contains a provider-specific example:
|
||||||
|
|
||||||
|
.. tabs::
|
||||||
|
|
||||||
|
.. tab:: MinIO Server
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc alias add myminio https://minioserver.example.net ACCESS_KEY SECRET KEY
|
||||||
|
|
||||||
|
.. tab:: AWS S3 Storage
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc alias add myS3 https://s3.amazon.com/endpoint ACCESS_KEY SECRET KEY
|
||||||
|
|
||||||
|
.. tab:: Google Cloud Storage
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc alias add myGCS https://storage.googleapis.com/endpoint ACCESS_KEY SECRET KEY
|
||||||
|
|
||||||
|
Use the :command:`mc info` command to test the connection to
|
||||||
|
the newly added MinIO deployment:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc info ALIAS
|
||||||
|
|
||||||
|
.. _minio-mc-global-options:
|
||||||
|
|
||||||
|
Global Options
|
||||||
|
--------------
|
||||||
|
|
||||||
|
.. program:: mc
|
||||||
|
|
||||||
|
.. option:: --debug
|
||||||
|
|
||||||
|
Enables verbose output to the console.
|
||||||
|
|
||||||
|
For example, the following operation adds verbose output to the
|
||||||
|
:command:`mc ls` command:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc --debug ls play
|
||||||
|
|
||||||
|
.. option:: --JSON
|
||||||
|
|
||||||
|
Enables `JSON lines <http://jsonlines.org/>`_ formatted output to the
|
||||||
|
console.
|
||||||
|
|
||||||
|
For example, the following operation adds JSON Lines output to the
|
||||||
|
:command:`mc ls` command:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc --JSON ls play
|
||||||
|
|
||||||
|
.. option:: --no-color
|
||||||
|
|
||||||
|
Disables the built-in color theme for console output. Useful for dumb
|
||||||
|
terminals.
|
||||||
|
|
||||||
|
.. option:: --quiet
|
||||||
|
|
||||||
|
Suppresses console output.
|
||||||
|
|
||||||
|
.. option:: --insecure
|
||||||
|
|
||||||
|
Disables TLS/SSL certificate verification. Allows TLS connectivity to
|
||||||
|
servers with invalid certificates. Exercise caution when using this
|
||||||
|
option against untrusted S3 hosts.
|
||||||
|
|
||||||
|
.. option:: --version
|
||||||
|
|
||||||
|
Displays the current version of :mc-cmd:`mc`.
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:titlesonly:
|
||||||
|
:hidden:
|
||||||
|
:glob:
|
||||||
|
|
||||||
|
/minio-cli/minio-mc/*
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
134
source/minio-cli/minio-mc/mc-alias.rst
Normal file
134
source/minio-cli/minio-mc/mc-alias.rst
Normal file
@ -0,0 +1,134 @@
|
|||||||
|
============
|
||||||
|
``mc alias``
|
||||||
|
============
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc alias
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-alias-desc
|
||||||
|
|
||||||
|
The :mc-cmd:`mc alias` command provides a convenient interface for
|
||||||
|
managing the list of S3-compatible hosts that :mc-cmd:`mc` can
|
||||||
|
connect to and run operations against.
|
||||||
|
|
||||||
|
:mc-cmd:`mc` commands that operate on S3-compatible services *require*
|
||||||
|
specifying an alias for that service.
|
||||||
|
|
||||||
|
.. end-mc-alias-desc
|
||||||
|
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc-cmd:`~mc alias` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc alias COMMAND [COMMAND FLAGS | -h ] [ARGUMENTS]
|
||||||
|
|
||||||
|
:mc-cmd:`~mc alias` supports the following commands:
|
||||||
|
|
||||||
|
.. mc-cmd:: add, a
|
||||||
|
|
||||||
|
Adds a new S3-compatible host to the configuration file. The command
|
||||||
|
has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc alias add ALIAS HOSTNAME ACCESS_KEY SECRET_KEY --api [S3v2|S3v4]
|
||||||
|
|
||||||
|
:mc-cmd:`mc alias add` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: ALIAS
|
||||||
|
|
||||||
|
The name to associate to the S3-compatible service.
|
||||||
|
|
||||||
|
The specified string cannot match any existing host aliases. Use
|
||||||
|
:mc-cmd:`~mc alias list` to view the current host aliases before
|
||||||
|
adding a new host.
|
||||||
|
|
||||||
|
.. mc-cmd:: HOSTNAME
|
||||||
|
|
||||||
|
The URL for the S3-compatible service endpoint.
|
||||||
|
|
||||||
|
.. mc-cmd:: ACCESS_KEY
|
||||||
|
|
||||||
|
The access key for authenticating to the S3 service. The
|
||||||
|
``ACCESS_KEY`` must correspond to a user or role on the S3 service.
|
||||||
|
|
||||||
|
:mc-cmd:`mc` can only perform an operation on the S3 service if
|
||||||
|
the ``ACCESS_KEY`` user or role grants the required permissions.
|
||||||
|
|
||||||
|
.. mc-cmd:: SECRET_KEY
|
||||||
|
|
||||||
|
The corresponding secret for the specified ``ACCESS_KEY``.
|
||||||
|
|
||||||
|
.. mc-cmd:: api
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The Amazon S3 Signature version to use when connecting to the
|
||||||
|
S3 service. Supports the following values:
|
||||||
|
|
||||||
|
- ``S3v2``
|
||||||
|
- ``S3v4`` (Default)
|
||||||
|
|
||||||
|
|
||||||
|
.. mc-cmd:: remove, rm
|
||||||
|
|
||||||
|
Removes a host entry from the configuration file. The command has the
|
||||||
|
following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc alias remove ALIAS
|
||||||
|
|
||||||
|
.. mc-cmd:: list, ls
|
||||||
|
|
||||||
|
Lists all hosts in the configuration file. The command has the following
|
||||||
|
syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc alias list
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Add a New S3 Service Alias
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc alias add myminio https://myminio.example.net myminioaccesskey myminiosecretkey
|
||||||
|
|
||||||
|
Remove an Existing S3 Service Alias
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc alias remove myminio
|
||||||
|
|
||||||
|
|
||||||
|
List All Configured S3 Service Aliases
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc alias list
|
||||||
133
source/minio-cli/minio-mc/mc-cat.rst
Normal file
133
source/minio-cli/minio-mc/mc-cat.rst
Normal file
@ -0,0 +1,133 @@
|
|||||||
|
==========
|
||||||
|
``mc cat``
|
||||||
|
==========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc cat
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-cat-desc
|
||||||
|
|
||||||
|
The :mc:`mc cat` command concatenates the contents of a file or
|
||||||
|
object to another file or object. You can also use the command to
|
||||||
|
display the contents of the specified file or object to ``STDOUT``.
|
||||||
|
:mc:`~mc cat` has similar functionality to ``cat``.
|
||||||
|
|
||||||
|
.. end-mc-cat-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc cat` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc cat [FLAGS] SOURCE [SOURCE ...]
|
||||||
|
|
||||||
|
:mc:`~mc cat` supports requires following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: SOURCE
|
||||||
|
|
||||||
|
**REQUIRED**
|
||||||
|
|
||||||
|
The full path to the file or object to concatenate.
|
||||||
|
|
||||||
|
.. mc-cmd:: rewind
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Returns the contents of the object at a specified date or after the
|
||||||
|
specified duration. Enclose the specified date or duration in double
|
||||||
|
quotes ``"``.
|
||||||
|
|
||||||
|
:mc-cmd:`mc cat rewind` requires the specified :mc-cmd:`~mc cat SOURCE`
|
||||||
|
bucket to have Bucket Versioning enabled. See
|
||||||
|
:mc-cmd:`mc versioning`.
|
||||||
|
|
||||||
|
- For a date in time, specify an ISO8601-formatted timestamp. For example:
|
||||||
|
``--rewind "2020.03.24T10:00"``.
|
||||||
|
|
||||||
|
- For duration, specify a string in ``#d#hh#mm#ss`` format. For example:
|
||||||
|
``--rewind "1d2hh3mm4ss"``.
|
||||||
|
|
||||||
|
.. mc-cmd:: encrypt-key
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Encrypt or decrypt objects using server-side encryption with
|
||||||
|
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
|
||||||
|
|
||||||
|
- Each ``KEY`` represents a bucket or object.
|
||||||
|
- Each ``VALUE`` represents the data key to use for encrypting
|
||||||
|
object(s).
|
||||||
|
|
||||||
|
Enclose the entire list of key-value pairs passed to
|
||||||
|
:mc-cmd:`~mc cat --encrypt-key` in double quotes ``"``.
|
||||||
|
|
||||||
|
:mc-cmd:`~mc cat --encrypt-key` can use the ``MC_ENCRYPT_KEY``
|
||||||
|
environment variable for retrieving a list of encryption key-value pairs
|
||||||
|
as an alternative to specifying them on the command line.
|
||||||
|
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Display the Contents of an Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cat play/mybucket/object.txt
|
||||||
|
|
||||||
|
Display the Contents of a Server Encrypted Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cat --encrypt-key="play/mybucket=32ByteLongSecretKeyMustBeGiven1" play/mybucket/object.txt
|
||||||
|
|
||||||
|
If the secret key contains non-printable characters, specify a ``base64``
|
||||||
|
encoded string instead:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cat --encrypt-key="play/mybucket=MzJieXRlc2xvbmdzZWNyZWFiY2RlZmcJZ2l2ZW5uMjE=" play/mybucket/object.txt
|
||||||
|
|
||||||
|
Display the Past Contents of an Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
To retrieve the contents of an object a specific number of days in the past,
|
||||||
|
specify :mc-cmd:`mc cat --rewind` with a duration of ``##d``:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cat --rewind "10d" play/mybucket/object.txt
|
||||||
|
|
||||||
|
To retrieve the contents of an object at a specific date or time in the past,
|
||||||
|
specify :mc-cmd:`mc cat --rewind` with an ISO8601-formatted timestamp:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cat --rewind "2020.03.04T12:34" play/mybucket/object.txt
|
||||||
273
source/minio-cli/minio-mc/mc-cp.rst
Normal file
273
source/minio-cli/minio-mc/mc-cp.rst
Normal file
@ -0,0 +1,273 @@
|
|||||||
|
=========
|
||||||
|
``mc cp``
|
||||||
|
=========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc cp
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-cp-desc
|
||||||
|
|
||||||
|
The :mc:`mc cp` command copies data from one or more sources to a target
|
||||||
|
S3-compatible service.
|
||||||
|
|
||||||
|
.. end-mc-cp-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc cp` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc cp [FLAGS] SOURCE [SOURCE...] TARGET
|
||||||
|
|
||||||
|
:mc:`~mc cp` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: SOURCE
|
||||||
|
|
||||||
|
**REQUIRED**
|
||||||
|
|
||||||
|
The object or objects to copy. You can specify both local paths
|
||||||
|
and S3 paths using a configured S3 service :mc:`alias <mc alias>`.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
mc cp play/mybucket/object.txt ~/localfiles/mybucket/object.txt TARGET
|
||||||
|
|
||||||
|
If you specify a directory or bucket to :mc-cmd:`~mc cp SOURCE`, you must
|
||||||
|
also specify :mc-cmd-option:`~mc cp recursive` to recursively copy the
|
||||||
|
contents of that directory or bucket. If you omit the ``--recursive``
|
||||||
|
argument, :mc:`~mc cp` only copies objects in the top level of the specified
|
||||||
|
directory or bucket.
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
**REQUIRED**
|
||||||
|
|
||||||
|
The full path to the bucket to copy the specified
|
||||||
|
:mc-cmd:`~mc cp SOURCES` to. Specify the :mc:`alias <mc alias>`
|
||||||
|
of a configured S3 service as the prefix to the
|
||||||
|
:mc-cmd:`~mc cp TARGET` path.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc cp ~/localfiles/object.txt play/mybucket/
|
||||||
|
|
||||||
|
.. mc-cmd:: recursive, r
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Recursively copy the contents of each bucket or directory
|
||||||
|
:mc-cmd:`~mc cp SOURCE` to the :mc-cmd:`~mc cp TARGET`
|
||||||
|
bucket.
|
||||||
|
|
||||||
|
.. mc-cmd:: older-than
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Remove object(s) older than the specified time limit. Specify a string
|
||||||
|
in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``
|
||||||
|
|
||||||
|
Defaults to ``0`` (all objects).
|
||||||
|
|
||||||
|
.. mc-cmd:: newer-than
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Remove object(s) newer than the specified number of days. Specify a
|
||||||
|
string in ``#d#hh#mm#ss`` format. For example:
|
||||||
|
``--older-than 1d2hh3mm4ss``
|
||||||
|
|
||||||
|
Defaults to ``0`` (all objects).
|
||||||
|
|
||||||
|
.. mc-cmd:: storage-class, sc
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Set the storage class for the new object(s) on the
|
||||||
|
:mc-cmd:`~mc cp TARGET`.
|
||||||
|
|
||||||
|
See :aws-docs:`AmazonS3/latest/dev/storage-class-intro.html` for
|
||||||
|
more information on S3 storage classses.
|
||||||
|
|
||||||
|
.. mc-cmd:: preserve, a
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Preserve file system attributes and bucket policy rules of the
|
||||||
|
:mc-cmd:`~mc cp SOURCE` directories, buckets, and objects on the
|
||||||
|
:mc-cmd:`~mc cp TARGET` bucket(s).
|
||||||
|
|
||||||
|
.. mc-cmd:: attr
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Add custom metadata for the object. Specify key-value pairs as
|
||||||
|
``KEY=VALUE\;``. For example,
|
||||||
|
``--attr key1=value1\;key2=value2\;key3=value3``.
|
||||||
|
|
||||||
|
.. mc-cmd:: continue, c
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Create or resume a copy session.
|
||||||
|
|
||||||
|
.. mc-cmd:: encrypt
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Encrypt or decrypt objects using server-side encryption with
|
||||||
|
server-managed keys. Specify key-value pairs as ``KEY=VALUE``.
|
||||||
|
|
||||||
|
- Each ``KEY`` represents a bucket or object.
|
||||||
|
- Each ``VALUE`` represents the data key to use for encrypting
|
||||||
|
object(s).
|
||||||
|
|
||||||
|
Enclose the entire list of key-value pairs passed to
|
||||||
|
:mc-cmd-option:`~mc cp encrypt` in double-quotes ``"``.
|
||||||
|
|
||||||
|
:mc-cmd-option:`~mc cp encrypt` can use the ``MC_ENCRYPT`` environment
|
||||||
|
variable for retrieving a list of encryption key-value pairs as an
|
||||||
|
alternative to specifying them on the command line.
|
||||||
|
|
||||||
|
.. mc-cmd:: encrypt-key
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Encrypt or decrypt objects using server-side encryption with
|
||||||
|
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
|
||||||
|
|
||||||
|
- Each ``KEY`` represents a bucket or object.
|
||||||
|
- Each ``VALUE`` represents the data key to use for encrypting
|
||||||
|
object(s).
|
||||||
|
|
||||||
|
Enclose the entire list of key-value pairs passed to
|
||||||
|
:mc-cmd-option:`~mc cp encrypt-key` in double quotes ``"``.
|
||||||
|
|
||||||
|
:mc-cmd-option:`~mc cp encrypt-key` can use the ``MC_ENCRYPT_KEY``
|
||||||
|
environment variable for retrieving a list of encryption key-value pairs
|
||||||
|
as an alternative to specifying them on the command line.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
:mc:`mc cp` verifies all copy operations to object storage using MD5SUM
|
||||||
|
checksums.
|
||||||
|
|
||||||
|
Interrupted or failed copy operations can resume from the point of failure
|
||||||
|
by issuing the :mc:`mc cp` operation again with the
|
||||||
|
:mc-cmd-option:`~mc cp continue` argument.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Copy a text file to an object storage.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cp myobject.txt play/mybucket
|
||||||
|
|
||||||
|
Copy a text file to an object storage with specified metadata.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cp --attr key1=value1;key2=value2 myobject.txt play/mybucket
|
||||||
|
|
||||||
|
Copy a folder recursively from MinIO cloud storage to Amazon S3 cloud storage with specified metadata.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cp --attr Cache-Control=max-age=90000,min-fresh=9000\;key1=value1\;key2=value2 \
|
||||||
|
--recursive play/mybucket/bucketname/ s3/mybucket/
|
||||||
|
|
||||||
|
|
||||||
|
Copy a text file to an object storage and assign ``storage-class`` REDUCED_REDUNDANCY to the uploaded object.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cp --storage-class REDUCED_REDUNDANCY myobject.txt play/mybucket
|
||||||
|
|
||||||
|
Copy a server-side encrypted file to an object storage.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The following example assumes that the ``s3`` and ``myminio`` aliases
|
||||||
|
exists in the :mc:`mc` :ref:`configuration file <mc-configuration>`. See
|
||||||
|
:mc:`mc alias` for more information on aliases.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cp --recursive \
|
||||||
|
--encrypt-key "s3/documents/=32byteslongsecretkeymustbegiven1 , myminio/documents/=32byteslongsecretkeymustbegiven2" \
|
||||||
|
s3/documents/myobject.txt myminio/documents/
|
||||||
|
|
||||||
|
Perform key-rotation on a server-side encrypted object.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
:mc:`mc cp` key rotation requires creating an additional alias with the same
|
||||||
|
endpoing as the target S3 service alias. :mc:`mc cp` effectively decrypts
|
||||||
|
the object using the old secret key, encrypts the object using the new
|
||||||
|
secret key, and replaces the old object with the newly encrypted object.
|
||||||
|
|
||||||
|
The following example assumes that the ``myminio1`` and ``myminio2`` aliases
|
||||||
|
exists in the :mc:`mc` :ref:`configuration file <mc-configuration>`. See
|
||||||
|
:mc:`mc alias` for more information on aliases.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cp --encrypt-key 'myminio1/mybucket=32byteslongsecretkeymustgenerate , myminio2/mybucket/=32byteslongsecretkeymustgenerat1' \
|
||||||
|
myminio1/mybucket/encryptedobject myminio2/mybucket/encryptedobject
|
||||||
|
|
||||||
|
Copy a javascript file to object storage and assign ``Cache-Control`` header to the uploaded object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cp --attr Cache-Control=no-cache myscript.js play/mybucket
|
||||||
|
|
||||||
|
Copy a text file to an object storage and preserve the filesyatem attributes.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc cp -a myobject.txt play/mybucket
|
||||||
|
|
||||||
|
|
||||||
65
source/minio-cli/minio-mc/mc-diff.rst
Normal file
65
source/minio-cli/minio-mc/mc-diff.rst
Normal file
@ -0,0 +1,65 @@
|
|||||||
|
===========
|
||||||
|
``mc diff``
|
||||||
|
===========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc diff
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-diff-desc
|
||||||
|
|
||||||
|
The :mc:`mc diff` mc computes the differences between two filesystem directories
|
||||||
|
or S3-compatible buckets. :mc:`mc diff` lists only those objects which are
|
||||||
|
missing or which differ in size. :mc:`mc diff` does **not** compare the contents
|
||||||
|
of objects.
|
||||||
|
|
||||||
|
.. end-mc-diff-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc diff` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc diff FIRST SECOND
|
||||||
|
|
||||||
|
:mc:`~mc diff` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: FIRST
|
||||||
|
|
||||||
|
The path to a filesystem directory or S3-compatible bucket.
|
||||||
|
|
||||||
|
.. mc-cmd:: SECOND
|
||||||
|
|
||||||
|
The path to a filesystem directory or S3-compatible bucket.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
:mc:`mc diff` uses the following legend when formatting the diff output:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
FIRST < SECOND - object exists only in FIRST
|
||||||
|
FIRST > SECOND - object exists only in SECOND
|
||||||
|
FIRST ! SECOND - Newer object exists in FIRST
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc diff play/bucket1 play/bucket2
|
||||||
134
source/minio-cli/minio-mc/mc-encrypt.rst
Normal file
134
source/minio-cli/minio-mc/mc-encrypt.rst
Normal file
@ -0,0 +1,134 @@
|
|||||||
|
==============
|
||||||
|
``mc encrypt``
|
||||||
|
==============
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc encrypt
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-encrypt-desc
|
||||||
|
|
||||||
|
The :mc:`mc encrypt` mc sets, updates, or disables the default
|
||||||
|
bucket Server-Side Encryption (SSE) mode. MinIO automatically encrypts
|
||||||
|
objects using the specified SSE mode.
|
||||||
|
|
||||||
|
For more information on configuring SSE, see
|
||||||
|
:doc:`/security/minio-security-server-side-encryption`.
|
||||||
|
|
||||||
|
.. end-mc-encrypt-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc encrypt` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc encrypt COMMAND [COMMAND FLAGS] [ARGUMENTS...]
|
||||||
|
|
||||||
|
:mc:`~mc encrypt` supports the following commands:
|
||||||
|
|
||||||
|
.. mc-cmd:: set
|
||||||
|
|
||||||
|
Sets the default encryption settings for the bucket. The command has the
|
||||||
|
following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc encrypt set ENCRYPTION [KMSKEY] TARGET
|
||||||
|
|
||||||
|
The mc requires the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: ENCRYPTION
|
||||||
|
|
||||||
|
Specify the server-side encryption type to use as the default SSE mode.
|
||||||
|
Supports the following values:
|
||||||
|
|
||||||
|
- ``sse-kms`` - SSE using a Key Management System (KMS)
|
||||||
|
- ``sse-s3`` - SSE using client-provided keys (SSE-C).
|
||||||
|
|
||||||
|
.. mc-cmd:: KMSKEY
|
||||||
|
|
||||||
|
Specify the KMS Master Key to use for performing SSE object encryption.
|
||||||
|
Only required if :mc-cmd:`~mc encrypt ENCRYPTION` is ``sse-kms``.
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
The full path to the bucket on which to set the default SSE mode. Specify
|
||||||
|
the :mc-cmd:`~mc alias` of a configured S3 service as the prefix to the
|
||||||
|
TARGET path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc encrypt set ENCRYPTION [KMSKEY] play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: clear
|
||||||
|
|
||||||
|
Removes the default encryption settings for the bucket. The command has
|
||||||
|
the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc encrypt clear TARGET
|
||||||
|
|
||||||
|
The command requires the following argument:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
The full path to the bucket on which to clear the default SSE mode.
|
||||||
|
Specify the :mc-cmd:`~mc alias` of a configured S3 service as the prefix
|
||||||
|
to the TARGET path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc encrypt remove play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: info
|
||||||
|
|
||||||
|
Returns the current default bucket encryption settings. The command
|
||||||
|
has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc encrypt info TARGET
|
||||||
|
|
||||||
|
The command requires the following argument:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
The full path to the bucket on which to return the default SSE mode.
|
||||||
|
Specify the :mc-cmd:`~mc alias` of a configured S3 service as the prefix
|
||||||
|
to the TARGET path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc encrypt remove play/mybucket
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
:mc:`mc encrypt` makes no assumptions about the MinIO server's current
|
||||||
|
encryption state. Specifying default encryption settings which the
|
||||||
|
server cannot support may result in undesired behavior.
|
||||||
|
|
||||||
|
Setting or modifying the default server-side encryption settings does *not*
|
||||||
|
automatically encrypt or decrypt the existing bucket contents. If the bucket
|
||||||
|
contents *must* have consistent encryption settings, use the
|
||||||
|
:mc:`mc mv` mc with the :mc-cmd:`~mc mv --encrypt` or
|
||||||
|
:mc-cmd:`~mc mv --encrypt-key` arguments to manually modify the
|
||||||
|
encryption settings or encrypted state of the bucket contents *before*
|
||||||
|
changing the bucket default.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
ToDo
|
||||||
|
|
||||||
270
source/minio-cli/minio-mc/mc-event.rst
Normal file
270
source/minio-cli/minio-mc/mc-event.rst
Normal file
@ -0,0 +1,270 @@
|
|||||||
|
============
|
||||||
|
``mc event``
|
||||||
|
============
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc event
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-event-desc
|
||||||
|
|
||||||
|
The :mc:`mc event` command supports adding, removing, and listing
|
||||||
|
the bucket event notifications.
|
||||||
|
|
||||||
|
MinIO automatically sends triggered events to the configured notification
|
||||||
|
targets. MinIO supports notification targets like AMQP, Redis, ElasticSearch,
|
||||||
|
NATS and PostgreSQL. See
|
||||||
|
:doc:`MinIO Bucket Notifications </minio-features/bucket-notifications>`
|
||||||
|
for more information.
|
||||||
|
|
||||||
|
.. end-mc-event-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc event` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc event COMMAND [COMMAND FLAGS | -h] [ARGUMENTS ...]
|
||||||
|
|
||||||
|
:mc:`~mc event` supports the following commands:
|
||||||
|
|
||||||
|
.. mc-cmd:: add
|
||||||
|
|
||||||
|
Adds a new bucket event notification. For supported event types, see
|
||||||
|
:ref:`mc-event-supported-events`. The command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc event add TARGET ARN [FLAGS]
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The S3 service :mc:`alias <mc alias>` and bucket to
|
||||||
|
which the command adds the new event notification. Specify the
|
||||||
|
:mc-cmd:`alias <mc alias>` of a configured S3 service as the prefix to
|
||||||
|
the ``TARGET`` path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc event add play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: ARN
|
||||||
|
|
||||||
|
*Required* The :aws-docs:`Amazon Resource Name (ARN)
|
||||||
|
<general/latest/gr/aws-arns-and-namespaces>` of the notification target.
|
||||||
|
|
||||||
|
The MinIO server outputs an ARN for each configured
|
||||||
|
notification target at server startup. See
|
||||||
|
:doc:`/minio-features/bucket-notifications` for more
|
||||||
|
information.
|
||||||
|
|
||||||
|
.. mc-cmd:: event
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The event(s) for which MinIO generates bucket notifications.
|
||||||
|
Specify multiple events using a comma ``,`` delimiter.
|
||||||
|
See :ref:`mc-event-supported-events` for supported events.
|
||||||
|
|
||||||
|
Defaults to ``put,delete, get``.
|
||||||
|
|
||||||
|
.. mc-cmd:: prefix
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The bucket prefix in which the specified :mc-cmd-option:`~mc event event`
|
||||||
|
can trigger a bucket notification.
|
||||||
|
|
||||||
|
For example, given a :mc-cmd:`~mc event TARGET` of ``play/mybucket`` and a
|
||||||
|
:mc-cmd-option:`~mc event prefix` of ``photos``, only events in
|
||||||
|
``play/mybucket/photos`` trigger bucket notifications.
|
||||||
|
|
||||||
|
.. mc-cmd:: suffix
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The bucket suffix in which the specified :mc-cmd-option:`~mc event event`
|
||||||
|
can trigger a bucket notification.
|
||||||
|
|
||||||
|
For example, given a :mc-cmd:`~mc event TARGET` of ``play/mybucket`` and a
|
||||||
|
:mc-cmd-option:`~mc event suffix` of ``.jpg``, only events in
|
||||||
|
``play/mybucket/*.jpg`` trigger bucket notifications.
|
||||||
|
|
||||||
|
.. mc-cmd:: remove
|
||||||
|
|
||||||
|
Removes an existing bucket event notification. The command has the
|
||||||
|
following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc event remove TARGET ARN [FLAGS]
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The S3 service :mc:`alias <mc alias>` and bucket from
|
||||||
|
which the command removes the event notification. Specify the
|
||||||
|
:mc-cmd:`alias <mc alias>` of a configured S3 service as the prefix to
|
||||||
|
the ``TARGET`` path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc event add play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: ARN
|
||||||
|
|
||||||
|
*Required* The :aws-docs:`Amazon Resource Name (ARN)
|
||||||
|
<general/latest/gr/aws-arns-and-namespaces>` of the notification target.
|
||||||
|
|
||||||
|
The MinIO server outputs an ARN for each configured
|
||||||
|
notification target at server startup. See
|
||||||
|
:doc:`/minio-features/bucket-notifications` for more information.
|
||||||
|
|
||||||
|
.. mc-cmd:: force
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Removes all events on the :mc-cmd:`~mc event TARGET` bucket with the
|
||||||
|
:mc-cmd-option:`~mc event ARN` notification target.
|
||||||
|
|
||||||
|
.. mc-cmd:: event
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The event(s) to remove. Specify multiple events using a comma ``,``
|
||||||
|
delimiter. See :ref:`mc-event-supported-events` for supported events.
|
||||||
|
|
||||||
|
Defaults to removing all events on the :mc-cmd:`~mc event TARGET` bucket
|
||||||
|
with the :mc-cmd-option:`~mc event ARN` notification target.
|
||||||
|
|
||||||
|
.. mc-cmd:: prefix
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The bucket prefix in which the command removes bucket notifications.
|
||||||
|
|
||||||
|
For example, given a :mc-cmd:`~mc event TARGET` of ``play/mybucket`` and a
|
||||||
|
:mc-cmd-option:`~mc event prefix` of ``photos``, the command only removes
|
||||||
|
bucket notifications in ``play/mybucket/photos``.
|
||||||
|
|
||||||
|
.. mc-cmd:: suffix
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The bucket suffix in which the command removes bucket notifications.
|
||||||
|
|
||||||
|
For example, given a :mc-cmd:`~mc event TARGET` of ``play/mybucket`` and a
|
||||||
|
:mc-cmd-option:`~mc event suffix` of ``.jpg``, the command only removes
|
||||||
|
bucket notifications in ``play/mybucket/*.jpg``.
|
||||||
|
|
||||||
|
.. mc-cmd:: list
|
||||||
|
|
||||||
|
Lists bucket event notifications.
|
||||||
|
|
||||||
|
The command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc event add TARGET ARN [FLAGS]
|
||||||
|
|
||||||
|
:mc-cmd:`~mc alias list` supports the following arguments
|
||||||
|
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The S3 service :mc:`alias <mc alias>` and bucket to
|
||||||
|
which the command lists event notification. Specify the
|
||||||
|
:mc-cmd:`alias <mc alias>` of a configured S3 service as the prefix to
|
||||||
|
the ``TARGET`` path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc event add play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: ARN
|
||||||
|
|
||||||
|
*Required* The :aws-docs:`Amazon Resource Name (ARN)
|
||||||
|
<general/latest/gr/aws-arns-and-namespaces>` of the bucket resource.
|
||||||
|
|
||||||
|
The MinIO server outputs an ARN for each configured
|
||||||
|
notification target at server startup. See
|
||||||
|
:doc:`/minio-features/bucket-notifications` for more information.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
.. _mc-event-supported-events:
|
||||||
|
|
||||||
|
Supported Bucket Events
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
MinIO supports the following S3 events.
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
:widths: 20 80
|
||||||
|
:width: 100%
|
||||||
|
|
||||||
|
* - MinIO Alias
|
||||||
|
- Corresponding S3 Event
|
||||||
|
|
||||||
|
* - ``put``
|
||||||
|
- ``s3:ObjectCreated:Put``
|
||||||
|
|
||||||
|
* - ``completeMultipartUpload``
|
||||||
|
- ``s3:ObjectCreated:CompleteMultipartUpload``
|
||||||
|
|
||||||
|
* - ``head``
|
||||||
|
- ``s3:ObjectAccessed:Head``
|
||||||
|
|
||||||
|
* - ``post``
|
||||||
|
- ``s3:ObjectCreated:Post``
|
||||||
|
|
||||||
|
* - ``delete``
|
||||||
|
- ``s3:ObjectRemoved:Delete``
|
||||||
|
|
||||||
|
* - ``copy``
|
||||||
|
- ``s3:ObjectCreated:Copy``
|
||||||
|
|
||||||
|
* - ``get``
|
||||||
|
- ``s3:ObjectAccessed:Get``
|
||||||
|
|
||||||
|
For more complete documentation on the listed S3 events, see
|
||||||
|
:s3-docs:`S3 Supported Event Types
|
||||||
|
<NotificationHowTo.html#notification-how-to-event-types-and-destinations>`.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Create a New Notification Event in Bucket
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc event play/mybucket arn:minio:sqs::notification-target-name:notification-target \
|
||||||
|
--event put,delete
|
||||||
|
|
||||||
|
|
||||||
|
Remove an Existing Notification Event in Bucket
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc event play/mybucket arn:minio:sqs::notification-target-name:notification-target \
|
||||||
|
--event put,delete
|
||||||
|
|
||||||
|
|
||||||
223
source/minio-cli/minio-mc/mc-find.rst
Normal file
223
source/minio-cli/minio-mc/mc-find.rst
Normal file
@ -0,0 +1,223 @@
|
|||||||
|
===========
|
||||||
|
``mc find``
|
||||||
|
===========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc find
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-find-desc
|
||||||
|
|
||||||
|
The :mc:`mc find` command searches the specified paths using
|
||||||
|
the given criteria and returns only those objects that match the criteria.
|
||||||
|
|
||||||
|
.. end-mc-find-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc find` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc find PATH [FLAGS]
|
||||||
|
|
||||||
|
:mc:`~mc find` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: PATH
|
||||||
|
|
||||||
|
The full path to search. Specify the :mc:`~mc alias` of
|
||||||
|
a configured S3 service as the prefix to the
|
||||||
|
:mc-cmd:`~mc mirror PATH`. For example:
|
||||||
|
|
||||||
|
.. code-block::
|
||||||
|
|
||||||
|
mc find play/mybucket [FLAGS]
|
||||||
|
|
||||||
|
.. mc-cmd:: exec
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Spawns an external process for each object returned by
|
||||||
|
:mc:`mc find`. Supports
|
||||||
|
:ref:`substitution formatting <mc-find-substitution-format>` of the
|
||||||
|
output.
|
||||||
|
|
||||||
|
.. mc-cmd:: ignore
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Exclude objects whose names match the specified wildcard pattern.
|
||||||
|
|
||||||
|
.. mc-cmd:: name
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Return objects whose names match the specified wildcard pattern.
|
||||||
|
|
||||||
|
.. mc-cmd:: older
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Mirror object(s) older than the specified time limit. Specify a string
|
||||||
|
in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``
|
||||||
|
|
||||||
|
Defaults to ``0`` (all objects).
|
||||||
|
|
||||||
|
.. mc-cmd:: newer
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Mirror object(s) newer than the specified number of days. Specify a
|
||||||
|
string in ``#d#hh#mm#ss`` format. For example:
|
||||||
|
``--older-than 1d2hh3mm4ss``
|
||||||
|
|
||||||
|
.. mc-cmd:: path
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Return the contents of directories whose names match the specified
|
||||||
|
wildcard pattern.
|
||||||
|
|
||||||
|
.. mc-cmd:: print
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Prints results to ``STDOUT``. Supports
|
||||||
|
:ref:`substitution formatting <mc-find-substitution-format>` of the
|
||||||
|
output.
|
||||||
|
|
||||||
|
.. mc-cmd:: regex
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Returns objects or the contents of directories whose names match the
|
||||||
|
specified PCRE regex pattern.
|
||||||
|
|
||||||
|
.. mc-cmd:: larger
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Match all objects larger than the specified size in
|
||||||
|
:ref:`units <mc-find-units>`.
|
||||||
|
|
||||||
|
.. mc-cmd:: smaller
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Match all objects smaller than the specifized size in
|
||||||
|
:ref:`units <mc-find-units>`.
|
||||||
|
|
||||||
|
.. mc-cmd:: maxdepth
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Limits directory navigation to the specified depth.
|
||||||
|
|
||||||
|
.. mc-cmd:: watch
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Continuously monitor the :mc-cmd:`~mc find PATH` and return
|
||||||
|
any new objects which match the specified criteria.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
.. _mc-find-units:
|
||||||
|
|
||||||
|
Units of Measurement
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The :mc-cmd-option:`mc find smaller` and :mc-cmd-option:`mc find larger` 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``.
|
||||||
|
|
||||||
|
|
||||||
|
.. _mc-find-substitution-format:
|
||||||
|
|
||||||
|
Substitution Format
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The :mc-cmd-option:`mc find exec` and :mc-cmd-option:`mc find print` commands
|
||||||
|
support string substitutions with special interpretations for following
|
||||||
|
keywords.
|
||||||
|
|
||||||
|
The following keywords are supported for both filesystem and S3 service targets:
|
||||||
|
|
||||||
|
- ``{}`` - Substitutes to full path.
|
||||||
|
- ``{base}`` - Substitutes to basename of path.
|
||||||
|
- ``{dir}`` - Substitutes to dirname of the path.
|
||||||
|
- ``{size}`` - Substitutes to object size of the path.
|
||||||
|
- ``{time}`` - Substitutes to object modified time of the path.
|
||||||
|
|
||||||
|
The following keyword is supported only for S3 service targets:
|
||||||
|
|
||||||
|
- ``{url}`` - Substitutes to a shareable URL of the path.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Find All Objects with Specific File Extension
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc find play/bucket --name "*.jpg"
|
||||||
|
|
||||||
|
Find All Matching Objects and Copy To S3 Service
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc find ~/data/images/ --name "*.jpg" --exec "mc cp {} play/images/"
|
||||||
|
|
||||||
|
To continuously watch the specified directory and copy new objects,
|
||||||
|
include the :mc-cmd-option:`~mc find watch` argument:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc find ~/data/images/ --name "*.jpg" --watch --exec "mc cp {} play/images/"
|
||||||
|
|
||||||
|
|
||||||
104
source/minio-cli/minio-mc/mc-head.rst
Normal file
104
source/minio-cli/minio-mc/mc-head.rst
Normal file
@ -0,0 +1,104 @@
|
|||||||
|
===========
|
||||||
|
``mc head``
|
||||||
|
===========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc head
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-head-desc
|
||||||
|
|
||||||
|
The :mc:`mc head` command displays the first ``n`` lines of an object,
|
||||||
|
where ``n`` is an argument specified to the command.
|
||||||
|
|
||||||
|
.. end-mc-head-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc head` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc head [FLAGS] SOURCE [SOURCE...]
|
||||||
|
|
||||||
|
:mc:`~mc head` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: --lines, -n
|
||||||
|
|
||||||
|
The number of lines to print.
|
||||||
|
|
||||||
|
Defaults to ``10``.
|
||||||
|
|
||||||
|
.. mc-cmd:: SOURCE
|
||||||
|
|
||||||
|
**REQUIRED**
|
||||||
|
|
||||||
|
The object or objects to print. You can specify both local paths
|
||||||
|
and S3 paths using a configured S3 service :mc:`alias <mc alias>`.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
mc head play/mybucket/object.txt ~/localfiles/mybucket/object.txt
|
||||||
|
|
||||||
|
.. mc-cmd:: encrypt-key
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Encrypt or decrypt objects using server-side encryption with
|
||||||
|
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
|
||||||
|
|
||||||
|
- Each ``KEY`` represents a bucket or object.
|
||||||
|
- Each ``VALUE`` represents the data key to use for encrypting
|
||||||
|
object(s).
|
||||||
|
|
||||||
|
Enclose the entire list of key-value pairs passed to
|
||||||
|
:mc-cmd-option:`~mc head encrypt-key` in double quotes ``"``.
|
||||||
|
|
||||||
|
:mc-cmd-option:`~mc head encrypt-key` can use the ``MC_ENCRYPT_KEY``
|
||||||
|
environment variable for retrieving a list of encryption key-value pairs
|
||||||
|
as an alternative to specifying them on the command line.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
:mc:`mc head` makes no assumptions about the format of the object data.
|
||||||
|
If the object data is not human readable, the output of :mc:`mc head`
|
||||||
|
will also not be human readable.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Display ``n`` Lines of an Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc head --lines 20 play/mybucket/myobject.txt
|
||||||
|
|
||||||
|
Display ``n`` Lines of an Encrypted Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc head lines --20 \
|
||||||
|
--encrypt-key "play/mybucket=32byteslongsecretkeymustbegiven1" \
|
||||||
|
play/mybucket/myobject.txt
|
||||||
280
source/minio-cli/minio-mc/mc-ilm.rst
Normal file
280
source/minio-cli/minio-mc/mc-ilm.rst
Normal file
@ -0,0 +1,280 @@
|
|||||||
|
==========
|
||||||
|
``mc ilm``
|
||||||
|
==========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc ilm
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-ilm-desc
|
||||||
|
|
||||||
|
The :mc:`mc ilm` command manages object lifecycle management
|
||||||
|
rules on a bucket. See the AWS documentation on
|
||||||
|
:s3-docs:`Object Lifecycle Management <object-lifecycle-mgmt.html>` for more
|
||||||
|
information.
|
||||||
|
|
||||||
|
.. end-mc-ilm-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`mc ilm` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc ilm COMMAND [COMMAND FLAGS] [ARGUMENTS...]
|
||||||
|
|
||||||
|
:mc:`mc ilm` supports the following subcommands:
|
||||||
|
|
||||||
|
.. mc-cmd:: list
|
||||||
|
|
||||||
|
Lists the current lifecycle management rules of the specified bucket. The
|
||||||
|
subcommand has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc ilm list [FLAGS] TARGET
|
||||||
|
|
||||||
|
The subcommand supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to the bucket from which to list existing
|
||||||
|
lifecycle management rules. Specify the :mc-cmd:`alias <mc alias>`
|
||||||
|
of a configured S3 service as the prefix to the ``TARGET`` path.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc ilm list play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: expiry
|
||||||
|
:option:
|
||||||
|
|
||||||
|
:mc-cmd:`mc ilm` returns only fields related to lifecycle rule expiration.
|
||||||
|
|
||||||
|
.. mc-cmd:: transition
|
||||||
|
:option:
|
||||||
|
|
||||||
|
:mc-cmd:`mc ilm` returns only fields related to lifecycle rule transition.
|
||||||
|
|
||||||
|
.. mc-cmd:: minimum
|
||||||
|
:option:
|
||||||
|
|
||||||
|
:mc-cmd:`mc ilm` returns only the following fields:
|
||||||
|
|
||||||
|
- ``id``
|
||||||
|
- ``prefix``
|
||||||
|
- ``status``
|
||||||
|
- ``transition set``
|
||||||
|
- ``expiry set``
|
||||||
|
|
||||||
|
.. mc-cmd:: add
|
||||||
|
|
||||||
|
Adds or modifies bucket lifecycle management rules. The command has
|
||||||
|
the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc ilm add [FLAGS] TARGET
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to the bucket from which to add or modify the
|
||||||
|
lifecycle management rule. Specify the :mc-cmd:`alias <mc alias>`
|
||||||
|
of a configured S3 service as the prefix to the ``TARGET`` path.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc ilm list play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: id
|
||||||
|
:option:
|
||||||
|
|
||||||
|
*Required* The unique name of the rule. Specify the
|
||||||
|
:mc-cmd-option:`mc ilm add id` of an existing rule to modify the
|
||||||
|
lifecycle configuration of that rule.
|
||||||
|
|
||||||
|
.. mc-cmd:: prefix
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The path to the specific subset of the :mc-cmd:`~mc ilm add TARGET` bucket
|
||||||
|
on which to apply the lifecycle configuration rule. MinIO appends the
|
||||||
|
:mc-cmd-option:`~mc cmd add prefix` field to the ``TARGET`` path to
|
||||||
|
construct the full path.
|
||||||
|
|
||||||
|
Omit to apply the rule to the entire ``TARGET`` bucket.
|
||||||
|
|
||||||
|
.. mc-cmd:: tags
|
||||||
|
:option:
|
||||||
|
|
||||||
|
One or more ampersand ``&``-delimited key-value pairs describing
|
||||||
|
the object tags to which to apply the lifecycle configuration rule.
|
||||||
|
|
||||||
|
.. mc-cmd:: expiry-date
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The ISO-8601-formatted date after which MinIO removes objects
|
||||||
|
covered by the rule. Specifying a date that is *prior* to the
|
||||||
|
current date marks all objects covered by the rule for removal.
|
||||||
|
|
||||||
|
.. mc-cmd:: expiry-days
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The number of days from object creation after which MinIO removes
|
||||||
|
objects covered by the rule.
|
||||||
|
|
||||||
|
.. mc-cmd:: transition-date
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The ISO-8601-formatted date after which MinIO transitions objects
|
||||||
|
covered by the rule to the specified ``--storage-class``.
|
||||||
|
Specifying a date that is *prior* to the current date marks all
|
||||||
|
objects covered by the rule for transition.
|
||||||
|
|
||||||
|
.. mc-cmd:: transition-days
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The number of days from object creation after which MinIO
|
||||||
|
transitions objects covered by the rule to the specified
|
||||||
|
``--storage-class``.
|
||||||
|
|
||||||
|
.. mc-cmd:: storage-class
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The Amazon S3 storage class to transition objects covered by the
|
||||||
|
rule. See :s3-docs:`Transition objects using Amazon S3 Lifecycle
|
||||||
|
<lifecycle-transition-general-considerations.html>` for more
|
||||||
|
information on S3 storage classes.
|
||||||
|
|
||||||
|
.. mc-cmd:: disable
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Disables the rule with matching :mc-cmd-option:`~mc ilm add id`.
|
||||||
|
|
||||||
|
.. mc-cmd:: remove
|
||||||
|
|
||||||
|
Removes an existing lifecycle management rule from the bucket. The
|
||||||
|
command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc ilm remove [FLAGS] TARGET
|
||||||
|
|
||||||
|
The command supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to the bucket from which to remove the
|
||||||
|
specified lifecycle management rule. Specify the :mc-cmd:`alias
|
||||||
|
<mc alias>` of a configured S3 service as the prefix to the
|
||||||
|
``TARGET`` path.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc ilm remove [FLAGS] play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: id
|
||||||
|
|
||||||
|
*Required* The unique name of the rule.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`mc ilm remove all`
|
||||||
|
|
||||||
|
.. mc-cmd:: all
|
||||||
|
|
||||||
|
*Required* Removes all rules in the bucket. Mutually exclusive with
|
||||||
|
:mc-cmd-option:`mc ilm remove id`.
|
||||||
|
|
||||||
|
Requires including :mc-cmd-option:`~mc ilm remove force`.
|
||||||
|
|
||||||
|
.. mc-cmd:: force
|
||||||
|
|
||||||
|
Required if specifying :mc-cmd-option:`~mc ilm remove all`.
|
||||||
|
|
||||||
|
.. mc-cmd:: export
|
||||||
|
|
||||||
|
Export the JSON-formatted lifecycle configuration to ``STDOUT``. The command
|
||||||
|
has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc ilm export TARGET
|
||||||
|
|
||||||
|
The command supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to the bucket from which to export the
|
||||||
|
configured lifecycle management rules. Specify the
|
||||||
|
:mc-cmd:`alias <mc alias>` of a configured S3 service as the prefix
|
||||||
|
to the ``TARGET`` path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc ilm export play/mybucket > play_mybucket_lifecycle_rules.json
|
||||||
|
|
||||||
|
.. mc-cmd:: import
|
||||||
|
|
||||||
|
Import a JSON-formatted lifecycle configuration from ``STDIN``. The command
|
||||||
|
has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc ilm import TARGET
|
||||||
|
|
||||||
|
The command supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to the bucket from which to apply the imported
|
||||||
|
lifecycle management rules. Specify the :mc-cmd:`alias <mc alias>` of a
|
||||||
|
configured S3 service as the prefix to the ``TARGET`` path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc ilm import play/mybucket < play_mybucket_lifecycle_rules.json
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Add a Bucket Lifecycle Management Rule
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc ilm add --id "Devices" --expiry-date "2021-01-23" play/mybucket
|
||||||
|
|
||||||
|
|
||||||
|
Remove a Bucket Lifecycle Management Rule
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc ilm remove --id "Devices" play/mybucket
|
||||||
120
source/minio-cli/minio-mc/mc-legalhold.rst
Normal file
120
source/minio-cli/minio-mc/mc-legalhold.rst
Normal file
@ -0,0 +1,120 @@
|
|||||||
|
================
|
||||||
|
``mc legalhold``
|
||||||
|
================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc legalhold
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-legalhold-desc
|
||||||
|
|
||||||
|
The :mc:`mc legalhold` command enables or disables object legal hold.
|
||||||
|
Enabling legal hold on an object prevents any modification or deletion
|
||||||
|
of the object and is equivalent to setting Write-Once Read-Only (WORM)
|
||||||
|
mode on the object.
|
||||||
|
|
||||||
|
.. end-mc-legalhold-desc
|
||||||
|
|
||||||
|
.. important::
|
||||||
|
|
||||||
|
:mc:`mc legalhold` *requires* that the specified bucket has object locking
|
||||||
|
enabled. You can **only** enable object locking at bucket creation.
|
||||||
|
|
||||||
|
See :mc-cmd-option:`mc mb with-lock` for documentation on creating
|
||||||
|
buckets with object locking enabled.
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc legalhold` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc legalhold [FLAGS] TARGET [ ON | OFF ]
|
||||||
|
|
||||||
|
:mc:`~mc legalhold` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to the object or bucket on which to enable or
|
||||||
|
disable the legal hold. Specify the :mc-cmd:`alias <mc alias>`
|
||||||
|
of a configured S3 service as the prefix to the ``TARGET`` path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc legalhold play/mybucket
|
||||||
|
|
||||||
|
You can specify a bucket prefix to apply the legal hold to only objects
|
||||||
|
in the specified prefix. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc legalhold play/mybucket/mydata
|
||||||
|
|
||||||
|
If you specify a path to a bucket or bucket prefix, you must also specify
|
||||||
|
:mc-cmd-option:`mc legalhold recursive`.
|
||||||
|
|
||||||
|
.. mc-cmd:: recursive, r
|
||||||
|
|
||||||
|
Applies the legal hold recursively to all objects in the
|
||||||
|
:mc-cmd:`~mc legalhold TARGET` bucket.
|
||||||
|
|
||||||
|
.. mc-cmd:: ACTION
|
||||||
|
|
||||||
|
*Required*
|
||||||
|
|
||||||
|
Specify ``ON`` to enable legal hold on the :mc-cmd:`~mc legalhold TARGET`
|
||||||
|
path.
|
||||||
|
|
||||||
|
Specify ``OFF`` to disable legal hold on the :mc-cmd:`~mc legalhold TARGET`
|
||||||
|
path.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
:mc:`mc legalhold` *requires* that the specified bucket has object locking
|
||||||
|
enabled. You can **only** enable object locking at bucket creation. See
|
||||||
|
:mc-cmd-option:`mc mb with-lock` for documentation on creating buckets with
|
||||||
|
object locking enabled.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Enable Legal Hold on Bucket
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
This example assumes that the specified bucket has object locking enabled.
|
||||||
|
See :mc-cmd-option:`mc mb with-lock` for more information on creating buckets
|
||||||
|
with object locking enabled.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc legalhold --recursive play/mybucket ON
|
||||||
|
|
||||||
|
Enable Legal Hold on an Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
This example assumes that the specified bucket has object locking enabled.
|
||||||
|
See :mc-cmd-option:`mc mb with-lock` for more information on creating buckets
|
||||||
|
with object locking enabled.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc legalhold --recursive play/mybucket/myobject.csv ON
|
||||||
|
|
||||||
171
source/minio-cli/minio-mc/mc-lock.rst
Normal file
171
source/minio-cli/minio-mc/mc-lock.rst
Normal file
@ -0,0 +1,171 @@
|
|||||||
|
===========
|
||||||
|
``mc lock``
|
||||||
|
===========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc lock
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-lock-desc
|
||||||
|
|
||||||
|
The :mc:`mc lock` command sets or gets the bucket default object lock
|
||||||
|
configuration. Object locking enables Write-Once Read-Many (WORM)
|
||||||
|
object retention for a configurable period of time.
|
||||||
|
|
||||||
|
.. end-mc-lock-desc
|
||||||
|
|
||||||
|
Use :mc:`mc retention` to set object lock settings on specific objects
|
||||||
|
in a bucket. :mc:`mc retention` overrides any bucket default lock
|
||||||
|
settings set using :mc:`mc lock`.
|
||||||
|
|
||||||
|
.. important::
|
||||||
|
|
||||||
|
:mc:`mc lock` *requires* that the specified bucket has object locking
|
||||||
|
enabled. You can **only** enable object locking at bucket creation.
|
||||||
|
|
||||||
|
See :mc-cmd-option:`mc mb with-lock` for documentation on creating
|
||||||
|
buckets with object locking enabled.
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc lock` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc lock TARGET COMMAND | MODE VALIDITY
|
||||||
|
|
||||||
|
:mc:`~mc lock` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to the bucket for which to set or get the bucket
|
||||||
|
default object lock configuration. Specify the :mc-cmd:`alias <mc alias>` of
|
||||||
|
a configured S3-compatible service as the prefix to the ``TARGET`` bucket
|
||||||
|
path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc lock play/mybucket COMMAND | MODE VALIDITY
|
||||||
|
|
||||||
|
.. mc-cmd:: info
|
||||||
|
|
||||||
|
Retrieves the current object lock configuation for the
|
||||||
|
:mc-cmd:`~mc lock TARGET` bucket.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd:`mc lock MODE`.
|
||||||
|
|
||||||
|
.. mc-cmd:: clear
|
||||||
|
|
||||||
|
Unsets the current object lock configuration for the
|
||||||
|
:mc-cmd:`~mc lock TARGET` bucket.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd:`mc lock MODE`.
|
||||||
|
|
||||||
|
.. mc-cmd:: MODE
|
||||||
|
|
||||||
|
Sets the locking mode for the :mc-cmd:`~mc lock TARGET` bucket. Specify
|
||||||
|
one of the following supported values:
|
||||||
|
|
||||||
|
- ``governance``
|
||||||
|
- ``compliance``
|
||||||
|
|
||||||
|
See the AWS S3 documentation on :s3-docs:`Object Lock Overview
|
||||||
|
<object-lock-overview.html>` for more information on the supported
|
||||||
|
modes.
|
||||||
|
|
||||||
|
Requires specifying :mc-cmd:`~mc lock VALIDITY`.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd:`mc lock info` and
|
||||||
|
:mc-cmd:`mc lock clear`.
|
||||||
|
|
||||||
|
.. mc-cmd:: VALIDITY
|
||||||
|
|
||||||
|
The duration which objects remain in the specified
|
||||||
|
:mc-cmd:`~mc lock MODE` after creation.
|
||||||
|
|
||||||
|
- For days, specify a string formatted as ``Nd``. For example,
|
||||||
|
``30d`` for 30 days after object creation.
|
||||||
|
|
||||||
|
- For years, specify a string formatted as ``Ny``. For example,
|
||||||
|
``1y`` for 1 year after object creation.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
:mc:`mc lock` *requires* that the specified bucket has object locking
|
||||||
|
enabled. You can **only** enable object locking at bucket creation. See
|
||||||
|
:mc-cmd-option:`mc mb with-lock` for documentation on creating buckets with
|
||||||
|
object locking enabled.
|
||||||
|
|
||||||
|
Interaction with Legal Holds
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
MinIO supports enabling a legal hold lock on objects. Enabling legal hold on an
|
||||||
|
object prevents any modification or deletion of the object.
|
||||||
|
|
||||||
|
An object with an active legal hold remains locked regardless of the :mc:`mc
|
||||||
|
lock` bucket configuration. Setting, modifying, or clearing the bucket default
|
||||||
|
object lock settings has no effect on objects under legal hold. Object lock
|
||||||
|
settings only apply after the legal hold is explicitly disabled.
|
||||||
|
|
||||||
|
For more information on object legal holds, see :mc-cmd:`mc legalhold`.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Get Bucket Object Lock Configuration
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
This example assumes that the specified bucket has object locking enabled.
|
||||||
|
See :mc-cmd-option:`mc mb with-lock` for more information on creating buckets
|
||||||
|
with object locking enabled.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc legalhold play/mybucket info
|
||||||
|
|
||||||
|
Clear Bucket Object Lock Configuration
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
This example assumes that the specified bucket has object locking enabled.
|
||||||
|
See :mc-cmd-option:`mc mb with-lock` for more information on creating buckets
|
||||||
|
with object locking enabled.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc legalhold play/mybucket clear
|
||||||
|
|
||||||
|
Set Bucket Object Lock Configuration
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
This example assumes that the specified bucket has object locking enabled.
|
||||||
|
See :mc-cmd-option:`mc mb with-lock` for more information on creating buckets
|
||||||
|
with object locking enabled.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc legalhold play/mybucket governance 30d
|
||||||
95
source/minio-cli/minio-mc/mc-mb.rst
Normal file
95
source/minio-cli/minio-mc/mc-mb.rst
Normal file
@ -0,0 +1,95 @@
|
|||||||
|
=========
|
||||||
|
``mc mb``
|
||||||
|
=========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc mb
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-mb-desc
|
||||||
|
|
||||||
|
The :mc:`mc mb` command creates a new bucket or directory at the
|
||||||
|
specified path. For targets on an S3-compatible service, :mc:`mc mb`
|
||||||
|
creates a new bucket. For targets on a filesystem, :mc:`mc mb` has
|
||||||
|
equivalent functionality to ``mkdir -p``.
|
||||||
|
|
||||||
|
.. end-mc-mb-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc mb` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc mb [FLAGS] TARGET [TARGET...]
|
||||||
|
|
||||||
|
:mc:`~mc mb` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to the bucket or directory to create. If
|
||||||
|
creating a directory on a filesystem, :mc:`mc mb` creates all required
|
||||||
|
folders in the specified path similar to ``mkdir -p``.
|
||||||
|
|
||||||
|
To create a bucket, specify the :mc-cmd:`alias <mc alias>` of a configured
|
||||||
|
S3 service as the prefix to the ``TARGET`` path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc mb [FLAGS] play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: region
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The region in which to create the specified bucket. Has no effect if the
|
||||||
|
specified :mc-cmd:`~mc mb TARGET` is a filesystem directory.
|
||||||
|
|
||||||
|
.. mc-cmd:: ignore-existing, p
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Directs :mc-cmd:`mc mb` to do nothing if the bucket or directory already
|
||||||
|
exists.
|
||||||
|
|
||||||
|
.. mc-cmd:: with-lock, l
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Enables object locking on the specified bucket. Has no effect if the
|
||||||
|
specified :mc-cmd:`~mc mb TARGET` is a filesystem directory.
|
||||||
|
|
||||||
|
.. important::
|
||||||
|
|
||||||
|
You can *only* enable object locking when creating the bucket.
|
||||||
|
You cannot use features like Bucket Lifecycle Management,
|
||||||
|
Bucket Object Retention, or Bucket Legal Hold if object locking is
|
||||||
|
disabled for a bucket.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
Certain S3 services may restrict the number of buckets a given user or account
|
||||||
|
can create. For example, Amazon S3 limits each account to
|
||||||
|
:s3-docs:`100 buckets <BucketRestrictions.html>`. :mc:`mc mb` may return an
|
||||||
|
error if the user has reached bucket limits on the target S3 service.
|
||||||
|
|
||||||
|
MinIO Object Storage deployments do not place any limits on the number of
|
||||||
|
buckets each user can create.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc mb --with-lock play/mybucket
|
||||||
173
source/minio-cli/minio-mc/mc-mirror.rst
Normal file
173
source/minio-cli/minio-mc/mc-mirror.rst
Normal file
@ -0,0 +1,173 @@
|
|||||||
|
=============
|
||||||
|
``mc mirror``
|
||||||
|
=============
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc mirror
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-mirror-desc
|
||||||
|
|
||||||
|
The :mc:`mc mirror` command synchronizes content between a source
|
||||||
|
filesystem and a target S3-compatible service. :mc:`~mc mirror` has
|
||||||
|
similar functionality to ``rsync``.
|
||||||
|
|
||||||
|
.. end-mc-mirror-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc mirror` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc mirror [FLAGS] SOURCE TARGET
|
||||||
|
|
||||||
|
:mc:`~mc mirror` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: SOURCE
|
||||||
|
|
||||||
|
**REQUIRED**
|
||||||
|
|
||||||
|
The full path to the object or directory to synchronize. If specifying
|
||||||
|
a directory, :mc:`mc mirror` synchronizes all objects in the
|
||||||
|
directory.
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
**REQUIRED**
|
||||||
|
|
||||||
|
The full path to bucket in which :mc:`mc mirror` copies
|
||||||
|
synchronized SOURCE objects. Specify the :mc:`alias <mc alias>` of a
|
||||||
|
configured S3 service as the prefix to the :mc-cmd:`~mc mirror TARGET`
|
||||||
|
path.
|
||||||
|
|
||||||
|
.. mc-cmd:: overwrite
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Overwrites object(s) on the :mc-cmd:`~mc mirror TARGET`.
|
||||||
|
|
||||||
|
.. mc-cmd:: remove
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Removes extraneous object(s) on the target.
|
||||||
|
|
||||||
|
.. mc-cmd:: watch, w
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Continuously monitor the :mc-cmd:`~mc mirror SOURCE` path and
|
||||||
|
synchronize changes.
|
||||||
|
|
||||||
|
.. mc-cmd:: region
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Specify the ``string`` region when creating new bucket(s) on the
|
||||||
|
target.
|
||||||
|
|
||||||
|
Defaults to ``"us-east-1"``.
|
||||||
|
|
||||||
|
.. mc-cmd:: preserve, a
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Preserve file system attributes and bucket policy rules of the
|
||||||
|
:mc-cmd:`~mc mirror SOURCE` on the
|
||||||
|
:mc-cmd:`~mc mirror TARGET`.
|
||||||
|
|
||||||
|
.. mc-cmd:: exclude
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Exclude object(s) in the :mc-cmd:`~mc mirror SOURCE` path that
|
||||||
|
match the specified object name pattern.
|
||||||
|
|
||||||
|
.. mc-cmd:: older-than
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Mirror object(s) older than the specified time limit. Specify a string
|
||||||
|
in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``
|
||||||
|
|
||||||
|
Defaults to ``0`` (all objects).
|
||||||
|
|
||||||
|
.. mc-cmd:: newer-than
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Mirror object(s) newer than the specified number of days. Specify a
|
||||||
|
string in ``#d#hh#mm#ss`` format. For example:
|
||||||
|
``--older-than 1d2hh3mm4ss``
|
||||||
|
|
||||||
|
Defaults to ``0`` (all objects).
|
||||||
|
|
||||||
|
.. mc-cmd:: fake
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Perform a fake mirror operation. Use this operation to perform
|
||||||
|
validate that the :mc:`mc mirror` operation will only
|
||||||
|
mirror the desired objects or buckets.
|
||||||
|
|
||||||
|
.. mc-cmd:: storage-class, sc
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Set the storage class for the new object(s) on the
|
||||||
|
:mc-cmd:`~mc mirror TARGET`.
|
||||||
|
|
||||||
|
See the Amazon documentation on
|
||||||
|
:aws-docs:`Storage Classes <AmazonS3/latest/dev/storage-class-intro.html>`
|
||||||
|
for more information on S3 storage classses.
|
||||||
|
|
||||||
|
.. mc-cmd:: encrypt-key
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Encrypt or decrypt objects using server-side encryption with
|
||||||
|
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
|
||||||
|
|
||||||
|
- Each ``KEY`` represents a bucket or object.
|
||||||
|
- Each ``VALUE`` represents the data key to use for encrypting
|
||||||
|
object(s).
|
||||||
|
|
||||||
|
Enclose the entire list of key-value pairs passed to
|
||||||
|
:mc-cmd-option:`~mc mirror encrypt-key` in double quotes ``"``.
|
||||||
|
|
||||||
|
:mc-cmd-option:`~mc mirror encrypt-key` can use the ``MC_ENCRYPT_KEY``
|
||||||
|
environment variable for retrieving a list of encryption key-value pairs
|
||||||
|
as an alternative to specifying them on the command line.
|
||||||
|
|
||||||
|
You can only delete encrypted objects if you specify the correct
|
||||||
|
:mc-cmd-option:`~mc mirror encrypt-key` secret key.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Mirror a Local Directory to an S3 Service
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
|
||||||
|
.. code-block::
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc mirror ~/data/ play/mybucket
|
||||||
|
|
||||||
|
Continuously Mirror a Local Directory to an S3 Service
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
|
||||||
|
.. code-block::
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc mirror --watch ~/data/ play/mybucket
|
||||||
274
source/minio-cli/minio-mc/mc-mv.rst
Normal file
274
source/minio-cli/minio-mc/mc-mv.rst
Normal file
@ -0,0 +1,274 @@
|
|||||||
|
=========
|
||||||
|
``mc mv``
|
||||||
|
=========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc mv
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-mv-desc
|
||||||
|
|
||||||
|
The :mc:`mc mv` command moves data from one or more sources to a target
|
||||||
|
S3-compatible service.
|
||||||
|
|
||||||
|
.. end-mc-mv-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc mv` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc mv [FLAGS] SOURCE [SOURCE...] TARGET
|
||||||
|
|
||||||
|
:mc:`~mc mv` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: SOURCE
|
||||||
|
|
||||||
|
**REQUIRED**
|
||||||
|
|
||||||
|
The object or objects to move. You can specify both local paths
|
||||||
|
and S3 paths using a configured S3 service :mc:`alias <mc alias>`.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
.. code-block:: none
|
||||||
|
|
||||||
|
mc mv play/mybucket/object.txt ~/localfiles/mybucket/object.txt TARGET
|
||||||
|
|
||||||
|
If you specify a directory or bucket to :mc-cmd:`~mc mv SOURCE`, you must
|
||||||
|
also specify :mc-cmd-option:`~mc mv recursive` to recursively move the
|
||||||
|
contents of that directory. If you omit the :mc-cmd-option:`~mc mv recursive`
|
||||||
|
argument, :mc:`~mc mv` only moves objects in the top level of the specified
|
||||||
|
directory or bucket.
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
**REQUIRED**
|
||||||
|
|
||||||
|
The full path to the bucket to move the specified
|
||||||
|
:mc-cmd:`~mc mv SOURCES` to. Specify the :mc:`alias <mc alias>`
|
||||||
|
of a configured S3 service as the prefix to the
|
||||||
|
:mc-cmd:`~mc mv TARGET` path.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc mv ~/localfiles/object.txt play/mybucket/
|
||||||
|
|
||||||
|
.. mc-cmd:: recursive, r
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Recursively move the contents of each bucket or directory
|
||||||
|
:mc-cmd:`~mc mv SOURCE` to the :mc-cmd:`~mc mv TARGET`
|
||||||
|
bucket.
|
||||||
|
|
||||||
|
.. mc-cmd:: older-than
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Remove object(s) older than the specified time limit. Specify a string
|
||||||
|
in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``.
|
||||||
|
|
||||||
|
Defaults to ``0`` (all objects).
|
||||||
|
|
||||||
|
.. mc-cmd:: newer-than
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Remove object(s) newer than the specified number of days. Specify a
|
||||||
|
string in ``##d#hh#mm#ss`` format. For example:
|
||||||
|
``--newer-than 1d2hh3mm4ss``.
|
||||||
|
|
||||||
|
Defaults to ``0`` (all objects).
|
||||||
|
|
||||||
|
.. mc-cmd:: storage-class, sc
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Set the storage class for the new object(s) on the
|
||||||
|
:mc-cmd:`~mc mv TARGET`.
|
||||||
|
|
||||||
|
See the Amazon documentation on
|
||||||
|
:aws-docs:`Storage Classes <AmazonS3/latest/dev/storage-class-intro.html>`
|
||||||
|
for more information on S3 storage classses.
|
||||||
|
|
||||||
|
.. mc-cmd:: preserve, a
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Preserve file system attributes and bucket policy rules of the
|
||||||
|
:mc-cmd:`~mc mv SOURCE` directories, buckets, and objects on the
|
||||||
|
:mc-cmd:`~mc mv TARGET` bucket(s).
|
||||||
|
|
||||||
|
.. mc-cmd:: attr
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Add custom metadata for the object. Specify key-value pairs as
|
||||||
|
``KEY=VALUE\;``. For example,
|
||||||
|
``--attr key1=value1\;key2=value2\;key3=value3``.
|
||||||
|
|
||||||
|
.. mc-cmd:: continue, c
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Create or resume a move session.
|
||||||
|
|
||||||
|
.. mc-cmd:: encrypt
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Encrypt or decrypt objects using server-side encryption with
|
||||||
|
server-managed keys. Specify key-value pairs as ``KEY=VALUE``.
|
||||||
|
|
||||||
|
- Each ``KEY`` represents a bucket or object.
|
||||||
|
- Each ``VALUE`` represents the data key to use for encrypting
|
||||||
|
object(s).
|
||||||
|
|
||||||
|
Enclose the entire list of key-value pairs passed to
|
||||||
|
:mc-cmd-option:`~mc mv encrypt` in double-quotes ``"``.
|
||||||
|
|
||||||
|
:mc-cmd-option:`~mc mv encrypt` can use the ``MC_ENCRYPT`` environment
|
||||||
|
variable for retrieving a list of encryption key-value pairs as an
|
||||||
|
alternative to specifying them on the command line.
|
||||||
|
|
||||||
|
.. mc-cmd:: encrypt-key
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Encrypt or decrypt objects using server-side encryption with
|
||||||
|
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
|
||||||
|
|
||||||
|
- Each ``KEY`` represents a bucket or object.
|
||||||
|
- Each ``VALUE`` represents the data key to use for encrypting
|
||||||
|
object(s).
|
||||||
|
|
||||||
|
Enclose the entire list of key-value pairs passed to
|
||||||
|
:mc-cmd-option:`~mc mv encrypt-key` in double quotes ``"``.
|
||||||
|
|
||||||
|
:mc-cmd-option:`~mc mv encrypt-key` can use the ``MC_ENCRYPT_KEY``
|
||||||
|
environment variable for retrieving a list of encryption key-value pairs
|
||||||
|
as an alternative to specifying them on the command line.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
:mc:`mc mv` verifies all move operations to
|
||||||
|
object storage using MD5SUM checksums.
|
||||||
|
|
||||||
|
Interrupted or failed move operations can resume from the point of failure
|
||||||
|
by issuing the :mc:`mc mv` operation again with the
|
||||||
|
:mc-cmd-option:`~mc mv continue` argument.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Move a text file to an object storage.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc mv myobject.txt play/mybucket
|
||||||
|
|
||||||
|
Move a text file to an object storage with specified metadata.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc mv --attr key1=value1;key2=value2 myobject.txt play/mybucket
|
||||||
|
|
||||||
|
Move a folder recursively from MinIO cloud storage to Amazon S3 cloud storage with specified metadata.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-s3-alias
|
||||||
|
:end-before: end-play-s3-alias
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc mv --attr Cache-Control=max-age=90000,min-fresh=9000\;key1=value1\;key2=value2 \
|
||||||
|
--recursive play/mybucket/bucketname/ s3/mybucket/
|
||||||
|
|
||||||
|
|
||||||
|
Move a text file to an object storage and assign ``storage-class`` REDUCED_REDUNDANCY to the uploaded object.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc mv --storage-class REDUCED_REDUNDANCY myobject.txt play/mybucket
|
||||||
|
|
||||||
|
Move a server-side encrypted file to an object storage.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-s3-alias
|
||||||
|
:end-before: end-play-s3-alias
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc mv --recursive \
|
||||||
|
--encrypt-key "s3/documents/=32byteslongsecretkeymustbegiven1 , myminio/documents/=32byteslongsecretkeymustbegiven2" \
|
||||||
|
s3/documents/myobject.txt myminio/documents/
|
||||||
|
|
||||||
|
Perform key-rotation on a server-side encrypted object.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
:mc:`mc mv` key rotation requires creating an additional alias with the same
|
||||||
|
endpoing as the target S3 service alias. :mc:`mc mv` decrypts
|
||||||
|
the object using the old secret key, encrypts the object using the new
|
||||||
|
secret key, and replaces the old object with the newly encrypted object.
|
||||||
|
|
||||||
|
The following example assumes that the ``myminio1`` and ``myminio2`` aliases
|
||||||
|
exists in the :mc:`mc` :ref:`configuration file <mc-configuration>`. See
|
||||||
|
:mc:`mc alias` for more information on aliases.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc mv --encrypt-key 'myminio1/mybucket=32byteslongsecretkeymustgenerate , myminio2/mybucket/=32byteslongsecretkeymustgenerat1' \
|
||||||
|
myminio1/mybucket/encryptedobject myminio2/mybucket/encryptedobject
|
||||||
|
|
||||||
|
Move a javascript file to object storage and assign ``Cache-Control`` header to the uploaded object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc mv --attr Cache-Control=no-cache myscript.js play/mybucket
|
||||||
|
|
||||||
|
Move a text file to an object storage and preserve the filesyatem attributes.
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc mv -a myobject.txt play/mybucket
|
||||||
|
|
||||||
|
|
||||||
221
source/minio-cli/minio-mc/mc-policy.rst
Normal file
221
source/minio-cli/minio-mc/mc-policy.rst
Normal file
@ -0,0 +1,221 @@
|
|||||||
|
=============
|
||||||
|
``mc policy``
|
||||||
|
=============
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc policy
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-policy-desc
|
||||||
|
|
||||||
|
The :mc:`mc policy` command supports setting or removing anonymous
|
||||||
|
policies to a bucket and its contents using AWS S3
|
||||||
|
:s3-docs:`JSON policies <using-iam-policies>`. Buckets with anonymous
|
||||||
|
policies allow public access where clients can perform any action
|
||||||
|
granted by the policy without.
|
||||||
|
|
||||||
|
.. end-mc-policy-desc
|
||||||
|
|
||||||
|
You can set or remove policies on individual folders or objects inside of a
|
||||||
|
bucket for more granular control over anonymous access to a bucket's
|
||||||
|
contents.
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc policy` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc policy COMMAND [ARGUMENTS]
|
||||||
|
|
||||||
|
:mc:`~mc policy` supports the following commands:
|
||||||
|
|
||||||
|
.. mc-cmd:: set
|
||||||
|
|
||||||
|
Adds one of the following built-in policies to the specified
|
||||||
|
bucket. The command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc policy set PERMISSION TARGET
|
||||||
|
|
||||||
|
The command requires the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: PERMISSION
|
||||||
|
|
||||||
|
Name of the policy to assign to the specified ``TARGET``
|
||||||
|
|
||||||
|
:mc-cmd:`mc policy set PERMISSION` supports the following built-in
|
||||||
|
policies:
|
||||||
|
|
||||||
|
- ``none`` - Disable anonymous access to the ``TARGET``.
|
||||||
|
- ``download`` - Enable download-only access to the ``TARGET``.
|
||||||
|
- ``upload`` - Enable upload-only access to the ``TARGET``.
|
||||||
|
- ``public`` - Enable download and upload access to the ``TARGET``.
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
The full path to the bucket, folder, or object to which the command
|
||||||
|
applies the specified :mc-cmd:`~mc policy set PERMISSION`. Specify the
|
||||||
|
:mc:`alias <mc alias>` of a configured S3 service as the
|
||||||
|
prefix to the ``TARGET`` path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc set public play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: set-json
|
||||||
|
|
||||||
|
Adds an AWS S3 :s3-docs:`JSON policy <using-iam-policies>` to the
|
||||||
|
specified bucket. The command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc policy set-json FILE TARGET
|
||||||
|
|
||||||
|
The command requires the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: FILE
|
||||||
|
|
||||||
|
The full path to the S3 policy ``.json`` file which the
|
||||||
|
command applies to the specified :mc-cmd:`~mc policy set-json TARGET`
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
The full path to the bucket, folder, orobject to which the command applies
|
||||||
|
the specified :mc-cmd:`~mc policy set-json FILE` S3 policy document.
|
||||||
|
Specify the :mc:`alias <mc alias>` of a configured S3 service as the
|
||||||
|
prefix to the ``TARGET`` path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc set public play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: get
|
||||||
|
|
||||||
|
Prints the current anonymous policy for the specified bucket, folder,
|
||||||
|
or object on the console.
|
||||||
|
|
||||||
|
The command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc policy get TARGET
|
||||||
|
|
||||||
|
Specify the :mc:`alias <mc alias>` of a configured S3 service
|
||||||
|
as the prefix to the ``TARGET`` bucket path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc get play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: get-json
|
||||||
|
|
||||||
|
Returns the current anonymous policy for the specified bucket, folder,
|
||||||
|
or object in ``JSON`` format.
|
||||||
|
|
||||||
|
The command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc policy get-json TARGET
|
||||||
|
|
||||||
|
Specify the :mc:`alias <mc alias>` of a configured S3 service
|
||||||
|
as the prefix to the ``TARGET`` bucket path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc policy get-json play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: list
|
||||||
|
|
||||||
|
Prints the anonymous policy for the specified bucket and any folders
|
||||||
|
or objects with a different anonymous policy from the bucket.
|
||||||
|
|
||||||
|
The command has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc policy list TARGET
|
||||||
|
|
||||||
|
Specify the :mc:`alias <mc alias>` of a configured S3 service
|
||||||
|
as the prefix to the ``TARGET`` bucket path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc policy list play/mybucket
|
||||||
|
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Get Current Anonymous Policy for Bucket
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc policy get play/mybucket
|
||||||
|
|
||||||
|
To retrieve the :s3-docs`IAM JSON policy document <using-iam-policies>`, use the
|
||||||
|
:mc-cmd:`mc policy get-json` mc:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc policy get-json play/mybucket
|
||||||
|
|
||||||
|
Set Anonymous Policy for Bucket
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc policy set upload play/mybucket
|
||||||
|
|
||||||
|
See :mc-cmd:`mc policy set` for the list of supported built-in policies.
|
||||||
|
|
||||||
|
To set the anonymous policy for the specified bucket using
|
||||||
|
an :s3-docs:`IAM JSON file <using-iam-policies>`, use the
|
||||||
|
:mc-cmd:`mc policy set-json` mc:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc policy set-json ~/policies/s3-upload.json play/mybucket
|
||||||
|
|
||||||
|
Remove Anonymous Policy for Bucket
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc policy set none play/mybucket
|
||||||
59
source/minio-cli/minio-mc/mc-rb.rst
Normal file
59
source/minio-cli/minio-mc/mc-rb.rst
Normal file
@ -0,0 +1,59 @@
|
|||||||
|
=========
|
||||||
|
``mc rb``
|
||||||
|
=========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc rb
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-rb-desc
|
||||||
|
|
||||||
|
The :mc:`mc rb` command removes a bucket and all its contents on the target
|
||||||
|
S3-compatible service.
|
||||||
|
|
||||||
|
Removing a bucket with :mc:`mc rb` also removes any configurations associated to
|
||||||
|
that bucket. To remove only the contents of a bucket, use :mc:`mc rb` instead.
|
||||||
|
|
||||||
|
.. end-mc-rb-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc rb` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc rb [FLAGS] SOURCE TARGET
|
||||||
|
|
||||||
|
.. mc-cmd:: force
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Allows running :mc:`mc rb` on a bucket with versioning enabled.
|
||||||
|
|
||||||
|
.. mc-cmd:: dangerous
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Allows running :mc:`mc rb` when the :mc-cmd:`~mc rb TARGET` specifies the
|
||||||
|
root (all buckets) on the S3-compatible service.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc rb play/mybucket
|
||||||
586
source/minio-cli/minio-mc/mc-retention.rst
Normal file
586
source/minio-cli/minio-mc/mc-retention.rst
Normal file
@ -0,0 +1,586 @@
|
|||||||
|
================
|
||||||
|
``mc retention``
|
||||||
|
================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 2
|
||||||
|
|
||||||
|
.. mc:: mc retention
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-retention-desc
|
||||||
|
|
||||||
|
The :mc:`mc retention` command configures the Write-Once Read-Many (WORM) object
|
||||||
|
lock settings for an object or object(s) in a bucket. You can also set the
|
||||||
|
default object lock settings for a bucket, where all objects without explicit
|
||||||
|
object lock settings inherit the bucket default. For more information on MinIO
|
||||||
|
object locking and data retention, see <link>.
|
||||||
|
|
||||||
|
.. end-mc-retention-desc
|
||||||
|
|
||||||
|
.. important::
|
||||||
|
|
||||||
|
:mc:`mc retention` *requires* that the specified bucket has object locking
|
||||||
|
enabled. You can **only** enable object locking at bucket creation. See
|
||||||
|
:mc-cmd-option:`mc mb with-lock` for documentation on creating buckets with
|
||||||
|
object locking enabled.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Starting in version :release:``, :mc:`mc retention` fully replaces :mc:`mc
|
||||||
|
lock` for setting the default object lock settings for a bucket.
|
||||||
|
:release:`` deprecates and removes :mc:`mc lock`.
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc retention` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc retention COMMANDS [COMMAND ARGUMENTS]
|
||||||
|
|
||||||
|
:mc:`~mc retention` supports the following commands:
|
||||||
|
|
||||||
|
.. mc-cmd:: set
|
||||||
|
:fullpath:
|
||||||
|
|
||||||
|
Sets the object lock settings for the specified
|
||||||
|
:mc-cmd:`~mc retention set TARGET` object.
|
||||||
|
|
||||||
|
:mc-cmd:`mc retention set` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc retention set [FLAGS] TARGET MODE VALIDITY
|
||||||
|
|
||||||
|
- If the ``TARGET`` specifies a bucket or bucket prefix, include
|
||||||
|
:mc-cmd-option:`~mc retention set recursive` to apply the object lock
|
||||||
|
settings to the bucket contents.
|
||||||
|
|
||||||
|
- If the ``TARGET`` bucket has versioning enabled, :mc-cmd:`mc retention set`
|
||||||
|
by default applies to only the latest object version. Use
|
||||||
|
:mc-cmd-option:`~mc retention set verison-id` or
|
||||||
|
:mc-cmd-option:`~mc retention set versions` to apply the object lock
|
||||||
|
settings to a specific version or to all versions of the object.
|
||||||
|
|
||||||
|
:mc-cmd:`mc retention set` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: bypass
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Allows a user with the ``s3:BypassGovernanceRetention`` permission
|
||||||
|
to modify the object. Requires the ``governance`` retention
|
||||||
|
:mc-cmd:`~mc retention set MODE`
|
||||||
|
|
||||||
|
.. mc-cmd:: recursive, r
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Recursively applies the object lock settings to all objects in the
|
||||||
|
specified :mc-cmd:`~mc retention set TARGET` path.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`~mc retention set version-id`.
|
||||||
|
|
||||||
|
.. mc-cmd:: default
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Sets the default object lock settings for the bucket specified to
|
||||||
|
:mc-cmd:`~mc retention set TARGET` using the
|
||||||
|
:mc-cmd:`~mc retention set MODE` and :mc-cmd:`~mc retention set VALIDITY`.
|
||||||
|
Any objects created in the bucket inherit the default object lock settings
|
||||||
|
unless explicitly overriden using :mc-cmd:`mc retention set`.
|
||||||
|
|
||||||
|
.. versionadded:: RELEASE.2020-08-XXT00-00-00Z
|
||||||
|
|
||||||
|
:mc-cmd-option:`mc retention set default` replaces the functionality of
|
||||||
|
the deprecated :mc-cmd:`mc lock` command.
|
||||||
|
|
||||||
|
If specifying :mc-cmd-option:`~mc retention set default`,
|
||||||
|
:mc-cmd:`mc retention set` ignores all other flags.
|
||||||
|
|
||||||
|
.. mc-cmd:: version-id
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Applies the object lock settings to the specified version of the
|
||||||
|
:mc-cmd:`~mc retention set TARGET` object. Requires
|
||||||
|
the bucket to have versioning enabled. Use :mc:`mc version` to
|
||||||
|
enable bucket versioning.
|
||||||
|
|
||||||
|
Mutually exclusive with any of the following flags:
|
||||||
|
|
||||||
|
- :mc-cmd-option:`~mc retention set versions`
|
||||||
|
- :mc-cmd-option:`~mc retention set rewind`
|
||||||
|
- :mc-cmd-option:`~mc retention set recursive`
|
||||||
|
|
||||||
|
.. mc-cmd:: versions
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Applies the object lock settings to all versions of the
|
||||||
|
:mc-cmd:`~mc retention set TARGET` object or object(s). Requires the
|
||||||
|
bucket to have versioning enabled. Use :mc:`mc version` to enable bucket
|
||||||
|
versioning.
|
||||||
|
|
||||||
|
Use :mc-cmd-option:`~mc retention set rewind` and
|
||||||
|
:mc-cmd-option:`~mc retention set versions` together to apply the object
|
||||||
|
lock settings to all versions of the object or object(s) which existed at
|
||||||
|
the specified duration prior to the current date. *or* at the specified
|
||||||
|
date.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`~mc retention set version-id`.
|
||||||
|
|
||||||
|
.. mc-cmd:: rewind
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Applies the object lock settings to the latest version of the object or
|
||||||
|
object(s) which existed at either the specified duration prior to the
|
||||||
|
current date *or* at a specific date.
|
||||||
|
|
||||||
|
- For duration, specify a string in ``#d#hh#mm#ss`` format. For example:
|
||||||
|
``--rewind "1d2hh3mm4ss"``.
|
||||||
|
|
||||||
|
- For a date in time, specify an ISO8601-formatted timestamp. For example:
|
||||||
|
``--rewind "2020.03.24T10:00"``.
|
||||||
|
|
||||||
|
For example, to apply the object lock settings to the object or object(s)
|
||||||
|
as they existed 30 days prior to the current date: ``--rewind "30d"``
|
||||||
|
|
||||||
|
Use :mc-cmd-option:`~mc retention set rewind` and
|
||||||
|
:mc-cmd-option:`~mc retention set versions` together to apply the object
|
||||||
|
lock settings to all versions of the object or object(s) which existed at
|
||||||
|
the specified duration prior to the current date. *or* at the specified
|
||||||
|
date.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`~mc retention set version-id`.
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to the object or objects for which to set
|
||||||
|
object lock configuration. Specify the :mc-cmd:`alias <mc alias>` of
|
||||||
|
a configured S3-compatible service as the prefix to the ``TARGET`` bucket
|
||||||
|
path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc retention play/mybucket/object.txt MODE VALIDITY
|
||||||
|
|
||||||
|
If specifying a bucket prefix, include the
|
||||||
|
:mc-cmd-option:`~mc retention set recursive` flag to apply the object
|
||||||
|
lock configuration to all objects in the bucket.
|
||||||
|
|
||||||
|
.. mc-cmd:: MODE
|
||||||
|
|
||||||
|
Sets the locking mode for the :mc-cmd:`~mc retention set TARGET`.
|
||||||
|
Specify one of the following supported values:
|
||||||
|
|
||||||
|
- ``governance``
|
||||||
|
- ``compliance``
|
||||||
|
|
||||||
|
See the AWS S3 documentation on :s3-docs:`Object Lock Overview
|
||||||
|
<object-lock-overview.html>` for more information on the supported
|
||||||
|
modes.
|
||||||
|
|
||||||
|
Requires specifying :mc-cmd:`~mc retention set VALIDITY`.
|
||||||
|
|
||||||
|
.. mc-cmd:: VALIDITY
|
||||||
|
|
||||||
|
The duration which objects remain in the specified
|
||||||
|
:mc-cmd:`~mc retention set MODE` after creation.
|
||||||
|
|
||||||
|
- For days, specify a string formatted as ``Nd``. For example,
|
||||||
|
``30d`` for 30 days after object creation.
|
||||||
|
|
||||||
|
- For years, specify a string formatted as ``Ny``. For example,
|
||||||
|
``1y`` for 1 year after object creation.
|
||||||
|
|
||||||
|
.. mc-cmd:: info
|
||||||
|
|
||||||
|
Returns the current object lock setting for the specified
|
||||||
|
:mc-cmd:`~mc retention info TARGET`.
|
||||||
|
|
||||||
|
:mc-cmd:`mc retention info` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc retention info [ARGUMENTS] TARGET
|
||||||
|
|
||||||
|
- If the ``TARGET`` specifies a bucket or bucket prefix, include
|
||||||
|
:mc-cmd-option:`~mc retention info recursive` to return the object
|
||||||
|
lock settings for all objects in the bucket or bucket prefix.
|
||||||
|
|
||||||
|
- If the ``TARGET`` bucket has versioning enabled,
|
||||||
|
:mc-cmd:`mc retention info` by default applies to only the latest object
|
||||||
|
version. Use :mc-cmd-option:`~mc retention info verison-id` or
|
||||||
|
:mc-cmd-option:`~mc retention info versions` to return the object lock
|
||||||
|
settings for a specific version or for all versions of the object.
|
||||||
|
|
||||||
|
:mc-cmd:`mc retention info` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: recursive, r
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Recursively returns the object lock settings for all objects in the
|
||||||
|
specified :mc-cmd:`~mc retention info TARGET` path.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`~mc retention info version-id`.
|
||||||
|
|
||||||
|
.. mc-cmd:: default
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Returns the default object lock settings for the bucket specified to
|
||||||
|
:mc-cmd:`~mc retention info TARGET`.
|
||||||
|
|
||||||
|
.. versionadded:: RELEASE.2020-08-XXT00-00-00Z
|
||||||
|
|
||||||
|
:mc-cmd-option:`mc retention info default` replaces the functionality
|
||||||
|
of the deprecated :mc-cmd:`mc lock info` command.
|
||||||
|
|
||||||
|
If specifying :mc-cmd-option:`~mc retention info default`,
|
||||||
|
:mc-cmd:`mc retention info` ignores all other flags.
|
||||||
|
|
||||||
|
.. mc-cmd:: version-id
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Returns the object lock settings of the specified version of the
|
||||||
|
:mc-cmd:`~mc retention info TARGET` object. Requires
|
||||||
|
the bucket to have versioning enabled. Use :mc:`mc version` to
|
||||||
|
enable bucket versioning.
|
||||||
|
|
||||||
|
Mutually exclusive with any of the following flags:
|
||||||
|
|
||||||
|
- :mc-cmd-option:`~mc retention info versions`
|
||||||
|
- :mc-cmd-option:`~mc retention info rewind`
|
||||||
|
- :mc-cmd-option:`~mc retention info recursive`
|
||||||
|
|
||||||
|
.. mc-cmd:: versions
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Returns the object lock settings of all versions of the
|
||||||
|
:mc-cmd:`~mc retention info TARGET` object or object(s). Requires the
|
||||||
|
bucket to have versioning enabled. Use :mc:`mc version` to enable bucket
|
||||||
|
versioning.
|
||||||
|
|
||||||
|
Use :mc-cmd-option:`~mc retention info rewind` and
|
||||||
|
:mc-cmd-option:`~mc retention info versions` together to return the object
|
||||||
|
lock settings of all versions of the object or object(s) which existed at
|
||||||
|
the specified duration prior to the current date. *or* at the specified
|
||||||
|
date.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`~mc retention info version-id`.
|
||||||
|
|
||||||
|
.. mc-cmd:: rewind
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Returns the object lock settings of the latest version of the object or
|
||||||
|
object(s) which existed at either the specified duration prior to the
|
||||||
|
current date *or* at a specific date.
|
||||||
|
|
||||||
|
- For duration, specify a string in ``#d#hh#mm#ss`` format. For example:
|
||||||
|
``--rewind "1d2hh3mm4ss"``.
|
||||||
|
|
||||||
|
- For a date in time, specify an ISO8601-formatted timestamp. For example:
|
||||||
|
``--rewind "2020.03.24T10:00"``.
|
||||||
|
|
||||||
|
For example, to return the object lock settings to the object or object(s)
|
||||||
|
as they existed 30 days prior to the current date: ``--rewind "30d"``
|
||||||
|
|
||||||
|
Use :mc-cmd-option:`~mc retention info rewind` and
|
||||||
|
:mc-cmd-option:`~mc retention info versions` together to return the object
|
||||||
|
lock settings of all versions of the object or object(s) which existed at
|
||||||
|
the specified duration prior to the current date. *or* at the specified
|
||||||
|
date.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`~mc retention info version-id`.
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to the object for which to retreive
|
||||||
|
the object lock configuration. Specify the :mc-cmd:`alias <mc alias>` of a
|
||||||
|
configured S3-compatible service as the prefix to the ``TARGET`` bucket
|
||||||
|
path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc retention play/mybucket/object.txt MODE VALIDITY
|
||||||
|
|
||||||
|
If specifying a bucket or bucket prefix, include the
|
||||||
|
:mc-cmd-option:`~mc retention info recursive` flag to return the object
|
||||||
|
lock configuration to all objects in the prefix.
|
||||||
|
|
||||||
|
.. mc-cmd:: clear
|
||||||
|
|
||||||
|
Clears the object lock setting for the specified ``TARGET``.
|
||||||
|
|
||||||
|
:mc-cmd:`mc retention info` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc retention clear [ARGUMENTS] TARGET
|
||||||
|
|
||||||
|
- If the ``TARGET`` specifies a bucket or bucket prefix, include
|
||||||
|
:mc-cmd-option:`~mc retention clear recursive` to clear the object lock
|
||||||
|
settings to the bucket contents.
|
||||||
|
|
||||||
|
- If the ``TARGET`` bucket has versioning enabled,
|
||||||
|
:mc-cmd:`mc retention clear` by default applies to only the latest object
|
||||||
|
version. Use :mc-cmd-option:`~mc retention clear verison-id` or
|
||||||
|
:mc-cmd-option:`~mc retention clear versions` to clear the object lock
|
||||||
|
settings for a specific version or for all versions of the object.
|
||||||
|
|
||||||
|
:mc-cmd:`mc retention info` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: recursive, r
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Recursively clears the object lock settings for all objects in the
|
||||||
|
specified :mc-cmd:`~mc retention clear TARGET` path.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`~mc retention clear version-id`.
|
||||||
|
|
||||||
|
.. mc-cmd:: default
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Clears the default object lock settings for the bucket specified to
|
||||||
|
:mc-cmd:`~mc retention clear TARGET`.
|
||||||
|
|
||||||
|
.. versionadded:: RELEASE.2020-08-XXT00-00-00Z
|
||||||
|
|
||||||
|
:mc-cmd-option:`mc retention clear default` replaces the functionality
|
||||||
|
of the deprecated :mc-cmd:`mc lock clear` command.
|
||||||
|
|
||||||
|
If specifying :mc-cmd-option:`~mc retention clear default`,
|
||||||
|
:mc-cmd:`mc retention clear` ignores all other flags.
|
||||||
|
|
||||||
|
.. mc-cmd:: version-id
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Clears the object lock settings of the specified version of the
|
||||||
|
:mc-cmd:`~mc retention clear TARGET` object. Requires
|
||||||
|
the bucket to have versioning enabled. Use :mc:`mc version` to
|
||||||
|
enable bucket versioning.
|
||||||
|
|
||||||
|
Mutually exclusive with any of the following flags:
|
||||||
|
|
||||||
|
- :mc-cmd-option:`~mc retention clear versions`
|
||||||
|
- :mc-cmd-option:`~mc retention clear rewind`
|
||||||
|
- :mc-cmd-option:`~mc retention clear recursive`
|
||||||
|
|
||||||
|
.. mc-cmd:: versions
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Clears the object lock settings of all versions of the
|
||||||
|
:mc-cmd:`~mc retention clear TARGET` object or object(s). Requires the
|
||||||
|
bucket to have versioning enabled. Use :mc:`mc version` to enable bucket
|
||||||
|
versioning.
|
||||||
|
|
||||||
|
Use :mc-cmd-option:`~mc retention clear rewind` and
|
||||||
|
:mc-cmd-option:`~mc retention clear versions` together to clear the
|
||||||
|
object lock settings of all versions of the object or object(s) which
|
||||||
|
existed at the specified duration prior to the current date. *or* at the
|
||||||
|
specified date.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`~mc retention clear version-id`.
|
||||||
|
|
||||||
|
.. mc-cmd:: rewind
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Clears the object lock settings of the latest version of the object or
|
||||||
|
object(s) which existed at either the specified duration prior to the
|
||||||
|
current date *or* at a specific date.
|
||||||
|
|
||||||
|
- For duration, specify a string in ``#d#hh#mm#ss`` format. For example:
|
||||||
|
``--rewind "1d2hh3mm4ss"``.
|
||||||
|
|
||||||
|
- For a date in time, specify an ISO8601-formatted timestamp. For example:
|
||||||
|
``--rewind "2020.03.24T10:00"``.
|
||||||
|
|
||||||
|
For example, to clear the object lock settings to the object or object(s)
|
||||||
|
as they existed 30 days prior to the current date: ``--rewind "30d"``
|
||||||
|
|
||||||
|
Use :mc-cmd-option:`~mc retention clear rewind` and
|
||||||
|
:mc-cmd-option:`~mc retention clear versions` together to clear the
|
||||||
|
object lock settings of all versions of the object or object(s) which
|
||||||
|
existed at the specified duration prior to the current date *or* at the
|
||||||
|
specified date.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`~mc retention clear version-id`.
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to the object or objects for which to clear
|
||||||
|
the object lock configuration. Specify the :mc-cmd:`alias <mc alias>` of a
|
||||||
|
configured S3-compatible service as the prefix to the ``TARGET`` bucket
|
||||||
|
path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc retention clear play/mybucket/object.txt MODE VALIDITY
|
||||||
|
|
||||||
|
If specifying a bucket prefix, include the
|
||||||
|
:mc-cmd-option:`~mc retention info recursive` flag to return the object
|
||||||
|
lock configuration to all objects in the prefix.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
Bucket Must Enable Object Locking
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
:mc:`mc retention` *requires* that the specified bucket has object locking
|
||||||
|
enabled. You can **only** enable object locking at bucket creation. See
|
||||||
|
:mc-cmd-option:`mc mb with-lock` for documentation on creating buckets with
|
||||||
|
object locking enabled.
|
||||||
|
|
||||||
|
Retention of Object Versions
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
For buckets with :mc:`versioning enabled <mc version>`, :mc:`mc retention` by
|
||||||
|
default operates on the *latest* version of the target object or object(s).
|
||||||
|
|
||||||
|
- Use the :mc-cmd-option:`mc retention set versions`,
|
||||||
|
:mc-cmd-option:`mc retention info versions`, or
|
||||||
|
:mc-cmd-option:`mc retention clear versions` to target
|
||||||
|
all versions of an object or object(s).
|
||||||
|
|
||||||
|
- Use the :mc-cmd-option:`mc retention set version-id`,
|
||||||
|
:mc-cmd-option:`mc retention info version-id`, or
|
||||||
|
:mc-cmd-option:`mc retention clear version-id` to target a specific
|
||||||
|
version of an object.
|
||||||
|
|
||||||
|
Interaction with Legal Holds
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Enabling a legal hold on an object prevents any modification or deletion of that
|
||||||
|
object, similar to the :mc-cmd:`COMPLIANCE <mc retention set MODE>` object
|
||||||
|
locking mode. Legal holds are independent of object lock settings - an object
|
||||||
|
can have both a legal hold *and* object locking enabled at the same time.
|
||||||
|
*However*, the legal hold *overrides* the object lock settings. That is,
|
||||||
|
regardless of the object lock settings, the legal hold prevents any object
|
||||||
|
modification or deletion until the hold is explicitly lifted. Setting,
|
||||||
|
modifying, or clearing object lock settings for an object under legal hold has
|
||||||
|
no effect until the legal hold either expires or is explicitly disabled.
|
||||||
|
|
||||||
|
For more information on object legal holds, see :mc-cmd:`mc legalhold`.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Set Bucket Object Lock Configuration
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
This example assumes that the specified bucket has object locking enabled.
|
||||||
|
See :mc-cmd-option:`mc mb with-lock` for more information on creating buckets
|
||||||
|
with object locking enabled.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc retention --recursive --default set play/mybucket/ governance 30d
|
||||||
|
|
||||||
|
Set Object Lock Configuration for Specific Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
This example assumes that the specified bucket has object locking enabled.
|
||||||
|
See :mc-cmd-option:`mc mb with-lock` for more information on creating buckets
|
||||||
|
with object locking enabled.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc retention set play/mybucket/data.csv governance 30d
|
||||||
|
|
||||||
|
Set Object Lock Configuration for Versioned Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
This example assumes that the specified bucket has object locking enabled.
|
||||||
|
See :mc-cmd-option:`mc mb with-lock` for more information on creating buckets
|
||||||
|
with object locking enabled.
|
||||||
|
|
||||||
|
For buckets with :mc:`versioning <mc version>` enabled, use the
|
||||||
|
:mc-cmd-option:`~mc retention set versions` option to apply the object lock
|
||||||
|
settings to all versions of the object.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc retention --versions set play/mybucket/data.csv governance 30d
|
||||||
|
|
||||||
|
Use the :mc-cmd-option:`~mc retention set version-id` option to apply the
|
||||||
|
object lock settings to a specific version of the object.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc retention --version-id hTyrbac12.sdsd set play/mybucket/data.csv governance 30d
|
||||||
|
|
||||||
|
Retrieve Object Lock Settings for an Object or Object(s)
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
This example assumes that the specified bucket has object locking enabled.
|
||||||
|
See :mc-cmd-option:`mc mb with-lock` for more information on creating buckets
|
||||||
|
with object locking enabled.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc retention info play/mybucket/data.csv
|
||||||
|
|
||||||
|
To retrieve the object lock settings for all objects in the bucket or a bucket
|
||||||
|
prefix, include the :mc-cmd-option:`~mc retention info recursive` option:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc retention --recursive info play/mybucket
|
||||||
|
|
||||||
|
mc retention --recursive info play/mybucket/myprefix/
|
||||||
|
|
||||||
|
Clear Object Lock Settings for an Object or Object(s)
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
This example assumes that the specified bucket has object locking enabled.
|
||||||
|
See :mc-cmd-option:`mc mb with-lock` for more information on creating buckets
|
||||||
|
with object locking enabled.
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc retention clear play/mybucket/data.csv
|
||||||
|
|
||||||
|
To clear the object lock settings for all objects in the bucket or a bucket
|
||||||
|
prefix, include the :mc-cmd-option:`~mc retention info recursive` option:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc retention --recursive clear play/mybucket
|
||||||
|
|
||||||
|
mc retention --recursive clear play/mybucket/myprefix/
|
||||||
254
source/minio-cli/minio-mc/mc-rm.rst
Normal file
254
source/minio-cli/minio-mc/mc-rm.rst
Normal file
@ -0,0 +1,254 @@
|
|||||||
|
=========
|
||||||
|
``mc rm``
|
||||||
|
=========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc rm
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-rm-desc
|
||||||
|
|
||||||
|
The :mc:`mc rm` command removes objects on a target S3-compatible service.
|
||||||
|
To completely remove a bucket, use :mc:`mc rb` instead.
|
||||||
|
|
||||||
|
.. end-mc-rm-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc rm` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc rm [FLAGS] TARGET [TARGET ...]
|
||||||
|
|
||||||
|
:mc:`~mc rm` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
**REQUIRED**
|
||||||
|
|
||||||
|
The full path to object to remove.
|
||||||
|
Specify the :mc:`alias <mc alias>` of a configured S3 service as the
|
||||||
|
prefix to the :mc-cmd-option:`~mc rm TARGET` path.
|
||||||
|
|
||||||
|
For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc rm play/mybucket/object.txt play/mybucket/otherobject.txt
|
||||||
|
|
||||||
|
If specifying the path to a bucket or bucket prefix, you **must** also
|
||||||
|
specify the :mc-cmd-option:`~mc rm recursive` and :mc-cmd-option:`~mc rm
|
||||||
|
force` arguments. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc rm --recursive --force play/mybucket/
|
||||||
|
|
||||||
|
mc rm --recursive --force play/mybucket/myprefix
|
||||||
|
|
||||||
|
.. mc-cmd:: recursive, r
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Recursively remove the contents of each :mc-cmd-option:`~mc rm TARGET`
|
||||||
|
bucket or bucket prefix.
|
||||||
|
|
||||||
|
If specifying :mc-cmd-option:`~mc rm recursive`, you **must** also
|
||||||
|
specify :mc-cmd-option:`~mc rm force`.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`mc rm version-id`
|
||||||
|
|
||||||
|
.. mc-cmd:: force
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Allows running :mc:`mc rm` with any of the following arguments:
|
||||||
|
|
||||||
|
- :mc-cmd-option:`~mc rm recursive`
|
||||||
|
- :mc-cmd-option:`~mc rm versions`
|
||||||
|
- :mc-cmd-option:`~mc rm stdin`
|
||||||
|
|
||||||
|
.. mc-cmd:: dangerous
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Allows running :mc:`mc rm` when the :mc-cmd:`~mc rm TARGET` specifies the
|
||||||
|
root (all buckets) on the S3-compatible service.
|
||||||
|
|
||||||
|
.. mc-cmd:: version-id
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Removes the specified version of the :mc-cmd:`~mc rm TARGET` object. Requires
|
||||||
|
the bucket to have versioning enabled. Use :mc:`mc version` to enable bucket
|
||||||
|
versioning.
|
||||||
|
|
||||||
|
Mutually exclusive with any of the following flags:
|
||||||
|
|
||||||
|
- :mc-cmd-option:`~mc rm versions`
|
||||||
|
- :mc-cmd-option:`~mc rm rewind`
|
||||||
|
- :mc-cmd-option:`~mc rm recursive`
|
||||||
|
|
||||||
|
.. mc-cmd:: versions
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Removes all versions of the :mc-cmd:`~mc rm TARGET` object or
|
||||||
|
object(s). Requires the bucket to have versioning enabled. Use
|
||||||
|
:mc:`mc version` to enable bucket versioning.
|
||||||
|
|
||||||
|
Use :mc-cmd-option:`~mc rm rewind` and
|
||||||
|
:mc-cmd-option:`~mc rm versions` together to clear the
|
||||||
|
object lock settings of all versions of the object or object(s) which
|
||||||
|
existed at the specified duration prior to the current date. *or* at the
|
||||||
|
specified date.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`~mc rm version-id`.
|
||||||
|
|
||||||
|
.. mc-cmd:: rewind
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Removes the latest version of the object or object(s) which existed at either
|
||||||
|
the specified duration prior to the current date *or* at a specific date.
|
||||||
|
|
||||||
|
- For duration, specify a string in ``#d#hh#mm#ss`` format. For example:
|
||||||
|
``--rewind "1d2hh3mm4ss"``.
|
||||||
|
|
||||||
|
- For a date in time, specify an ISO8601-formatted timestamp. For example:
|
||||||
|
``--rewind "2020.03.24T10:00"``.
|
||||||
|
|
||||||
|
For example, to clear the object lock settings to the object or object(s)
|
||||||
|
as they existed 30 days prior to the current date: ``--rewind "30d"``
|
||||||
|
|
||||||
|
Use :mc-cmd-option:`~mc rm rewind` and :mc-cmd-option:`~mc rm versions`
|
||||||
|
together to remove all versions of the object or object(s) which existed at
|
||||||
|
the specified duration prior to the current date *or* at the specified date.
|
||||||
|
|
||||||
|
Mutually exclusive with :mc-cmd-option:`~mc rm version-id`.
|
||||||
|
|
||||||
|
.. mc-cmd:: older-than
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Remove object(s) older than the specified time limit. Specify a string
|
||||||
|
in ``#d#hh#mm#ss`` format. For example: ``--older-than 1d2hh3mm4ss``.
|
||||||
|
|
||||||
|
|
||||||
|
Defaults to ``0`` (all objects).
|
||||||
|
|
||||||
|
.. mc-cmd:: newer-than
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Remove object(s) newer than the specified number of days. Specify a
|
||||||
|
string in ``#d#hh#mm#ss`` format. For example:
|
||||||
|
``--newer-than 1d2hh3mm4ss``
|
||||||
|
|
||||||
|
Defaults to ``0`` (all objects).
|
||||||
|
|
||||||
|
.. mc-cmd:: incomplete, I
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Remove incomplete uploads for the specified object.
|
||||||
|
|
||||||
|
If any :mc-cmd-option:`~mc rm TARGET` specifies a bucket,
|
||||||
|
you **must** also specify :mc-cmd-option:`~mc rm recursive`
|
||||||
|
and :mc-cmd-option:`~mc rm force`.
|
||||||
|
|
||||||
|
.. mc-cmd:: fake
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Perform a fake remove operation. Use this operation to perform
|
||||||
|
validate that the :mc:`mc rm` operation will only
|
||||||
|
remove the desired objects or buckets.
|
||||||
|
|
||||||
|
.. mc-cmd:: stdin
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Read object names or buckets from ``STDIN``.
|
||||||
|
|
||||||
|
.. mc-cmd:: encrypt-key
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The encryption key to use for performing Server-Side Encryption with Client
|
||||||
|
Keys (SSE-C). Specify comma seperated key-value pairs as ``KEY=VALUE,...``.
|
||||||
|
|
||||||
|
- For ``KEY``, specify the S3-compatible service
|
||||||
|
:mc-cmd:`alias <mc alias>` and full path to the bucket, including any
|
||||||
|
bucket prefixes. Separate the alias and bucket path with a forward slash
|
||||||
|
``\``. For example, ``play/mybucket``
|
||||||
|
|
||||||
|
- For ``VALUE``, specify the data key to use for encryption object(s) in
|
||||||
|
the bucket or bucket prefix specified to ``KEY``.
|
||||||
|
|
||||||
|
:mc-cmd-option:`~mc rm encrypt-key` can use the ``MC_ENCRYPT_KEY``
|
||||||
|
environment variable for populating the list of encryption key-value
|
||||||
|
pairs as an alternative to specifying them on the command line.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
Deleting Bucket Contents
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Using :mc:`mc rm` to remove all contents in a bucket does not delete the bucket
|
||||||
|
itself. Any configurations associated to the bucket remain in place, such as
|
||||||
|
:mc-cmd-option:`default object lock settings <mc retention set default>`.
|
||||||
|
|
||||||
|
To completely remove a bucket, use :mc:`mc rb` instead of :mc:`mc rm`.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Remove a Single Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc rm play/mybucket/myobject.txt
|
||||||
|
|
||||||
|
Recursively Remove a Bucket's Contents
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc rm --recursive --force play/mybucket
|
||||||
|
|
||||||
|
Remove All Incomplete Upload Files for an Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: moveable
|
||||||
|
|
||||||
|
mc rm --incomplete play/mybucket/myobject.1gig
|
||||||
|
|
||||||
|
Remove Objects Older Than Specified Time Period
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: moveable
|
||||||
|
|
||||||
|
mc rm --recursive --force --older-than 1d2h30m play/mybucket
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
264
source/minio-cli/minio-mc/mc-share.rst
Normal file
264
source/minio-cli/minio-mc/mc-share.rst
Normal file
@ -0,0 +1,264 @@
|
|||||||
|
============
|
||||||
|
``mc share``
|
||||||
|
============
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc share
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-share-desc
|
||||||
|
|
||||||
|
The :mc:`mc share` command generates temporary URLs with integrated
|
||||||
|
access credentials for uploading or downloading objects to an S3-compatible
|
||||||
|
host. The temporary URL expires after a configurable time limit.
|
||||||
|
|
||||||
|
.. end-mc-share-desc
|
||||||
|
|
||||||
|
For more information on shareable object URLs, see the Amazon S3
|
||||||
|
documentation on :aws-docs:`Pre-Signed URLs
|
||||||
|
<AmazonS3/latest/dev/ShareObjectPreSignedURL.html>`.
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc share COMMAND
|
||||||
|
|
||||||
|
:mc:`~mc share` supports the following commands:
|
||||||
|
|
||||||
|
.. mc-cmd:: download
|
||||||
|
|
||||||
|
Generates a URL for using an HTTP GET request to retrieve the
|
||||||
|
object(s).
|
||||||
|
|
||||||
|
:mc-cmd:`~mc share download` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc share download [FLAGS] TARGET [TARGET ...]
|
||||||
|
|
||||||
|
:mc-cmd:`~mc share download` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
The full path to the object for which :mc:`mc share` generates a URL.
|
||||||
|
|
||||||
|
If any ``TARGET`` specifies a path to a bucket, :mc:`mc share` *must*
|
||||||
|
include the :mc-cmd-option:`mc share recursive` argument.
|
||||||
|
|
||||||
|
.. mc-cmd:: recursive, r
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Recursively generate URLs for all objects in a :mc-cmd:`mc share TARGET`
|
||||||
|
bucket or bucket prefix.
|
||||||
|
|
||||||
|
Required if any ``TARGET`` specifies a path to a bucket or bucket prefix.
|
||||||
|
|
||||||
|
.. mc-cmd:: expire, E
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Set the expiration time limit for all generated URLs.
|
||||||
|
|
||||||
|
Specify a string with format ``##h##m##s`` format. For example:
|
||||||
|
``12h34m56s`` for an expiry of 12 hours, 34 minutes, and 56 seconds
|
||||||
|
after URL generation.
|
||||||
|
|
||||||
|
Defaults to ``168h`` or 168 hours (7 days).
|
||||||
|
|
||||||
|
|
||||||
|
.. mc-cmd:: upload
|
||||||
|
|
||||||
|
Generates a ``CURL`` command for uploading object(s) using ``HTTP POST``.
|
||||||
|
|
||||||
|
:mc-cmd:`~mc share upload` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc share upload [FLAGS] TARGET [TARGET ...]
|
||||||
|
|
||||||
|
:mc-cmd:`~mc share upload` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
The full path to the object for which :mc:`mc share upload` generates a
|
||||||
|
URL.
|
||||||
|
|
||||||
|
If the ``TARGET`` specifies a single object, :mc-cmd:`mc share upload`
|
||||||
|
names the uploaded object based on the name specified to ``TARGET``.
|
||||||
|
|
||||||
|
If the ``TARGET`` specifies a path to a bucket or bucket prefix,
|
||||||
|
:mc-cmd:`mc share upload` *must* include the
|
||||||
|
:mc-cmd-option:`~mc share upload recursive` argument.
|
||||||
|
|
||||||
|
.. mc-cmd:: recursive, r
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Modifies the CURL URL to support uploading objects to a bucket or bucket
|
||||||
|
prefix. Required if any ``TARGET`` specifies a path to a bucket or bucket
|
||||||
|
prefix. The modified CURL output resembles the following:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
curl ... -F key=TARGET/<NAME> -F file=@<FILE>
|
||||||
|
|
||||||
|
Replace ``<FILE>`` with the path to the file to upload.
|
||||||
|
|
||||||
|
Replace ``<NAME>`` with the name of the file once uploaded.
|
||||||
|
|
||||||
|
|
||||||
|
.. mc-cmd:: expire, E
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Set the expiration time limit for all generated URLs.
|
||||||
|
|
||||||
|
Specify a string with format ``##h##m##s`` format. For example:
|
||||||
|
``12h34m56s`` for an expiry of 12 hours, 34 minutes, and 56 seconds
|
||||||
|
after URL generation.
|
||||||
|
|
||||||
|
Defaults to ``168h`` or 168 hours (7 days).
|
||||||
|
|
||||||
|
|
||||||
|
.. mc-cmd:: list
|
||||||
|
|
||||||
|
List all unexpired upload or download URLs generated by
|
||||||
|
:mc-cmd:`mc share download` and :mc-cmd:`mc share upload`.
|
||||||
|
|
||||||
|
:mc-cmd:`~mc share list` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc share list SUBCOMMAND
|
||||||
|
|
||||||
|
:mc-cmd:`~mc share download` supports the following subcommands:
|
||||||
|
|
||||||
|
.. mc-cmd:: upload
|
||||||
|
|
||||||
|
List all unexpired URLs generated by :mc-cmd:`mc share upload`.
|
||||||
|
|
||||||
|
.. mc-cmd:: download
|
||||||
|
|
||||||
|
List all unexpired URLs generated by :mc-cmd:`mc share download`.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Generate a CURL GET Command for an Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc share download play/mybucket/myobject.txt
|
||||||
|
|
||||||
|
To specify a custom expiry, pass the ``--expiry`` flag. The following
|
||||||
|
command sets a 4 hour expiry for the generated URL:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc share download --expiry 4h play/mybucket/myobject.txt
|
||||||
|
|
||||||
|
Generate a CURL GET Command For Each Object in Bucket or Bucket Prefix
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc share download --recursive play/mybucket/
|
||||||
|
|
||||||
|
The command returns a CURL command for each object in the bucket or bucket
|
||||||
|
prefix.
|
||||||
|
|
||||||
|
To specify a custom expiry, pass the ``--expiry`` flag. The following
|
||||||
|
command sets a 4 hour expiry for the generated URL:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc share download --recursive --expiry 4h play/mybucket/
|
||||||
|
|
||||||
|
Generate a CURL POST Command for an Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc share upload play/mybucket/myobject.csv
|
||||||
|
|
||||||
|
The command returns a CURL command for uploading an object to the specified
|
||||||
|
bucket with the object name. Replace the ``<FILE>`` string in the returned
|
||||||
|
CURL command with the path to the file to upload.
|
||||||
|
|
||||||
|
To specify a custom expiry, pass the ``--expiry`` flag. The following
|
||||||
|
command sets a 4 hour expiry for the generated URL:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc share upload --expiry 4h play/mybucket/myobject.csv
|
||||||
|
|
||||||
|
Generate a CURL POST Command for a Bucket or Bucket Prefix
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc share upload --recursive play/mybucket/photos
|
||||||
|
|
||||||
|
The command returns a CURL command for uploading an object to the specified
|
||||||
|
bucket prefix. Replace the ``<FILE>>`` string in the returned
|
||||||
|
CURL command with the path to the file to upload. Replace the ``<NAME>``
|
||||||
|
string in the returned CURL command with the name of the file in the bucket.
|
||||||
|
|
||||||
|
To specify a custom expiry, pass the ``--expiry`` flag. The following
|
||||||
|
command sets a 4 hour expiry for the generated URL:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc share upload --recursive --expiry 4h play/mybucket/photos
|
||||||
|
|
||||||
|
You can use a shell script loop to recursively upload the contents of a bucket
|
||||||
|
to the S3-compatible service. The following example uses a ``for in``
|
||||||
|
loop:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
#!/bin/sh
|
||||||
|
|
||||||
|
for file in ~/Documents/photos/
|
||||||
|
do
|
||||||
|
curl https://play.min.io/mybucket/ \
|
||||||
|
-F policy=AAAAA -F x-amz-algorithm=AWS4-HMAC-SHA256 \
|
||||||
|
-F x-amz-credential=AAAA/us-east-1/s3/aws4_request \
|
||||||
|
-F x-amz-date=20200812T202556Z \
|
||||||
|
-F x-amz-signature=AAAA \
|
||||||
|
-F bucket=rkbucket -F key=mydata/${file} -F file=@${file}
|
||||||
|
|
||||||
|
done
|
||||||
|
|
||||||
|
Defer to the documented best practices for your preferred scripting language
|
||||||
|
for iterating through files in a directory.
|
||||||
284
source/minio-cli/minio-mc/mc-sql.rst
Normal file
284
source/minio-cli/minio-mc/mc-sql.rst
Normal file
@ -0,0 +1,284 @@
|
|||||||
|
==========
|
||||||
|
``mc sql``
|
||||||
|
==========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc sql
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-sql-desc
|
||||||
|
|
||||||
|
The :mc:`mc sql` command provides an S3 Select interface for performing sql
|
||||||
|
queries on objects in the specified S3-compatible service.
|
||||||
|
|
||||||
|
.. end-mc-sql-desc
|
||||||
|
|
||||||
|
See :s3-docs:`Selecting content from objects
|
||||||
|
<selecting-content-from-objects>` for more information on S3 Select behavior
|
||||||
|
and limitations.
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`mc sql` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc sql [FLAGS] TARGET [TARGET...]
|
||||||
|
|
||||||
|
:mc:`mc sql` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to the bucket or object to run the SQL query
|
||||||
|
against. Specify the :mc-cmd:`alias <mc alias>` of a configured
|
||||||
|
S3 service as the prefix to the ``TARGET`` path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc sql [FLAGS] play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: query, e
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The SQL statement to execute on the specified :mc-cmd:`~mc sql TARGET`
|
||||||
|
directory or object. Wrap the entire SQL query in double quotes ``"``.
|
||||||
|
|
||||||
|
Defaults to ``"select * from s3object"``.
|
||||||
|
|
||||||
|
.. mc-cmd:: recursive, r
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Recursively searches the specified :mc-cmd:`~mc sql TARGET` directory
|
||||||
|
using the :mc-cmd-option:`~mc sql query` SQL statement.
|
||||||
|
|
||||||
|
|
||||||
|
.. mc-cmd:: csv-input
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The data format for ``.csv`` input objects. Specify a string of
|
||||||
|
comma-seperated ``key=value,...`` pairs. See :ref:`mc-sql-csv-format`
|
||||||
|
for more information on valid keys.
|
||||||
|
|
||||||
|
.. mc-cmd:: json-input
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The data format for ``.json`` input objects. Specify the type of the JSON
|
||||||
|
contents as ``type=<VALUE>``. The value can be either:
|
||||||
|
|
||||||
|
- ``DOCUMENT`` - JSON `document <https://www.json.org/json-en.html>`__.
|
||||||
|
- ``LINES`` - JSON `lines <http://jsonlines.org/>`__.
|
||||||
|
|
||||||
|
See the S3 API :s3-api:`JSONInput <API_JSONInput.html>` for more
|
||||||
|
information.
|
||||||
|
|
||||||
|
.. mc-cmd:: compression
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The compression type of the input object. Specify one of the following
|
||||||
|
supported values:
|
||||||
|
|
||||||
|
- ``GZIP``
|
||||||
|
- ``BZIP2``
|
||||||
|
- ``NONE`` (default)
|
||||||
|
|
||||||
|
.. mc-cmd:: csv-output
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The data format for ``.csv`` output. Specify a string of comma-seperated
|
||||||
|
``key=value,...`` pairs. See :ref:`mc-sql-csv-format` for more information
|
||||||
|
on valid keys.
|
||||||
|
|
||||||
|
See the S3 API :s3-api:`CSVOutput <API_CSVOutput.html>` for more
|
||||||
|
information.
|
||||||
|
|
||||||
|
.. mc-cmd:: csv-output-header
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The header row of the ``.csv`` output file. Specify a string of
|
||||||
|
comma-separated fields as ``field1,field2,...``.
|
||||||
|
|
||||||
|
Omit to output a ``.csv`` with no header row.
|
||||||
|
|
||||||
|
|
||||||
|
.. mc-cmd:: json-output
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The data format for the ``.json`` output. Supports the
|
||||||
|
``rd=value`` key, where ``rd`` is the ``RecordDelimiter`` for the JSON
|
||||||
|
document.
|
||||||
|
|
||||||
|
Omit to use the default newline character ``\n``.
|
||||||
|
|
||||||
|
See the S3 API :s3-api:`JSONOutput <API_JSONOutput.html>` for more
|
||||||
|
information.
|
||||||
|
|
||||||
|
.. mc-cmd:: encrypt-key
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The encryption key to use for performing Server-Side Encryption with Client
|
||||||
|
Keys (SSE-C). Specify comma seperated key-value pairs as ``KEY=VALUE,...``.
|
||||||
|
|
||||||
|
- For ``KEY``, specify the S3-compatible service
|
||||||
|
:mc-cmd:`alias <mc alias>` and full path to the bucket, including any
|
||||||
|
bucket prefixes. Separate the alias and bucket path with a forward slash
|
||||||
|
``\``. For example, ``play/mybucket``
|
||||||
|
|
||||||
|
- For ``VALUE``, specify the data key to use for encryption object(s) in
|
||||||
|
the bucket or bucket prefix specified to ``KEY``.
|
||||||
|
|
||||||
|
:mc-cmd-option:`~mc sql encrypt-key` can use the ``MC_ENCRYPT_KEY``
|
||||||
|
environment variable for populating the list of encryption key-value
|
||||||
|
pairs as an alternative to specifying them on the command line.
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
Input Formats
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
:mc:`mc sql` supports the following input formats:
|
||||||
|
|
||||||
|
- ``.csv``
|
||||||
|
- ``.json``
|
||||||
|
- ``.parquet``
|
||||||
|
|
||||||
|
For ``.csv`` file types, use :mc-cmd-option:`mc sql csv-input` to
|
||||||
|
specify the CSV data format. See :ref:`mc-sql-csv-format` for more
|
||||||
|
information on CSV formatting fields.
|
||||||
|
|
||||||
|
For ``.json`` file types, use :mc-cmd-option:`mc sql json-input` to specify
|
||||||
|
the JSON data format.
|
||||||
|
|
||||||
|
For ``.parquet`` file types, :mc-cmd:`mc sql` automatically interprets the
|
||||||
|
data format.
|
||||||
|
|
||||||
|
.. _mc-sql-csv-format:
|
||||||
|
|
||||||
|
CSV Formatting Fields
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The following table lists valid key-value pairs for use with
|
||||||
|
:mc-cmd-option:`mc sql csv-input` and :mc-cmd-option:`mc sql csv-output`.
|
||||||
|
Certain key pairs are only valid for :mc-cmd-option:`~mc sql csv-input`
|
||||||
|
See the documentation for S3 API :s3-api:`CSVInput <API_CSVInput.html>` for more
|
||||||
|
information on S3 CSV formatting.
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
:widths: 20 20 60
|
||||||
|
:width: 100%
|
||||||
|
|
||||||
|
* - Key
|
||||||
|
- ``--csv-input`` Only
|
||||||
|
- Description
|
||||||
|
|
||||||
|
* - ``rd``
|
||||||
|
-
|
||||||
|
- The character that seperates each record (row) in the input ``.csv``
|
||||||
|
file.
|
||||||
|
|
||||||
|
Corresponds to ``RecordDelimiter`` in the S3 API ``CSVInput``.
|
||||||
|
|
||||||
|
* - ``fd``
|
||||||
|
-
|
||||||
|
- The character that seperates each field in a record. Defaults to
|
||||||
|
``,``.
|
||||||
|
|
||||||
|
Corresponds to ``FieldDelimeter`` in the S3 API ``CSVInput``.
|
||||||
|
|
||||||
|
* - ``qc``
|
||||||
|
-
|
||||||
|
- The character used for escaping when the ``fd`` character is part of
|
||||||
|
a value. Defaults to ``"``.
|
||||||
|
|
||||||
|
Corresponds to ``QuoteCharacter`` in the S3 API ``CSVInput``.
|
||||||
|
|
||||||
|
* - ``qec``
|
||||||
|
-
|
||||||
|
- The character used for escaping a quotation mark ``"`` character
|
||||||
|
inside an already escaped value.
|
||||||
|
|
||||||
|
Corresponds to ``QuoteEscapeCharacter`` in the S3 API ``CSVInput``.
|
||||||
|
|
||||||
|
* - ``fh``
|
||||||
|
- Yes
|
||||||
|
- The content of the first line in the ``.csv`` file.
|
||||||
|
|
||||||
|
Specify one of the following supported values:
|
||||||
|
|
||||||
|
- ``NONE`` - The first line is not a header.
|
||||||
|
- ``IGNORE`` - Ignore the first line.
|
||||||
|
- ``USE`` - The first line is a header.
|
||||||
|
|
||||||
|
For ``NONE`` or ``IGNORE``, you must specify column positions
|
||||||
|
``_#`` to identify a column in the :mc-cmd-option:`~mc sql query`
|
||||||
|
statement.
|
||||||
|
|
||||||
|
For ``USE``, you can specify header values to identify a column in
|
||||||
|
the :mc-cmd-option:`~mc sql query` statement.
|
||||||
|
|
||||||
|
Corresponds to ``FieldHeaderInfo`` in the S3 API ``CSVInput``.
|
||||||
|
|
||||||
|
* - ``cc``
|
||||||
|
- Yes
|
||||||
|
- The character used to indicate a record should be ignored. The
|
||||||
|
character *must* appear at the beginning of the record.
|
||||||
|
|
||||||
|
Corresponds to ``Comment`` in the S3 API ``CSVInput``.
|
||||||
|
|
||||||
|
* - ``qrd``
|
||||||
|
- Yes
|
||||||
|
- Specify ``TRUE`` to indicate that fields may contain record delimiter
|
||||||
|
values (``rd``).
|
||||||
|
|
||||||
|
Defaults to ``FALSE``.
|
||||||
|
|
||||||
|
Corresponds to ``AllowQuotedRecordDelimiter`` in the S3 API
|
||||||
|
``CSVInput``.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Select all Columns in all Objects in a Bucket
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc sql --recursive \
|
||||||
|
--query "select * from S3Object" s3/personalbucket/my-large-csvs/
|
||||||
|
|
||||||
|
Run an Aggregation Query on an Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc sql --query "select count(s.power) from S3Object" myminio/iot-devices/power-ratio.csv
|
||||||
|
|
||||||
|
Run an Aggregation Query on an Encrypted Object
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc sql --encrypt-key "myminio/iot-devices=32byteslongsecretkeymustbegiven1" \
|
||||||
|
--query "select count(s.power) from S3Object" myminio/iot-devices/power-ratio-encrypted.csv
|
||||||
88
source/minio-cli/minio-mc/mc-stat.rst
Normal file
88
source/minio-cli/minio-mc/mc-stat.rst
Normal file
@ -0,0 +1,88 @@
|
|||||||
|
===========
|
||||||
|
``mc stat``
|
||||||
|
===========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc stat
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-stat-desc
|
||||||
|
|
||||||
|
The :mc:`mc stat` command displays information on objects contained in the
|
||||||
|
specified S3-compatible service bucket. :mc:`mc stat` has similar functionality
|
||||||
|
as the ``stat`` command when used on a filesystem path.
|
||||||
|
|
||||||
|
.. end-mc-stat-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc stat` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc stat [FLAGS] TARGET
|
||||||
|
|
||||||
|
:mc:`~mc stat` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
The full path to an object or file.
|
||||||
|
|
||||||
|
For objects on an S3-compatible service, specify the :mc:`alias <mc alias>`
|
||||||
|
of a configured S3 service as the prefix to the :mc-cmd:`~mc stat TARGET`
|
||||||
|
path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc stat [FLAGS] play/mybucket
|
||||||
|
|
||||||
|
If you specify a directory or bucket, you must also specify
|
||||||
|
:mc-cmd-option:`mc stat recursive` to recursively apply the command to
|
||||||
|
the contents of that directory or bucket.
|
||||||
|
|
||||||
|
.. mc-cmd:: recursive, r
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Recursively :mc:`mc stat` the contents of
|
||||||
|
:mc-cmd:`~mc stat TARGET`.
|
||||||
|
|
||||||
|
.. mc-cmd:: encrypt-key
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Encrypt or decrypt objects using server-side encryption with
|
||||||
|
client-specified keys. Specify key-value pairs as ``KEY=VALUE``.
|
||||||
|
|
||||||
|
- Each ``KEY`` represents a bucket or object.
|
||||||
|
- Each ``VALUE`` represents the data key to use for encrypting
|
||||||
|
object(s).
|
||||||
|
|
||||||
|
Enclose the entire list of key-value pairs passed to
|
||||||
|
:mc-cmd-option:`~mc stat encrypt-key` in double quotes ``"``.
|
||||||
|
|
||||||
|
:mc-cmd-option:`~mc stat encrypt-key` can use the ``MC_ENCRYPT_KEY``
|
||||||
|
environment variable for retrieving a list of encryption key-value pairs
|
||||||
|
as an alternative to specifying them on the command line.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
68
source/minio-cli/minio-mc/mc-tree.rst
Normal file
68
source/minio-cli/minio-mc/mc-tree.rst
Normal file
@ -0,0 +1,68 @@
|
|||||||
|
===========
|
||||||
|
``mc tree``
|
||||||
|
===========
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc tree
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-tree-desc
|
||||||
|
|
||||||
|
The :mc:`mc tree` command lists buckets and directories in a tree format.
|
||||||
|
|
||||||
|
When applied to an S3-compatible service bucket, :mc:`mc tree` returns
|
||||||
|
a tree listing of the bucket and all bucket prefixes.
|
||||||
|
|
||||||
|
When applied to a local filesystem directory, :mc:`mc tree` returns a
|
||||||
|
tree listing of the directory and all of its subdirectories.
|
||||||
|
|
||||||
|
.. end-mc-tree-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc tree` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc tree [FLAGS] TARGET [TARGET...]
|
||||||
|
|
||||||
|
:mc:`~mc tree` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The full path to an S3-compatible service bucket *or* local
|
||||||
|
filesystem directory.
|
||||||
|
|
||||||
|
For objects on an S3-compatible service, specify the :mc:`alias <mc alias>`
|
||||||
|
of a configured service as the prefix to the :mc-cmd:`~mc stat TARGET`
|
||||||
|
path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc stat [FLAGS] play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: files, f
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Includes files in the object or directory in the :mc:`mc tree` output.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc tree play/mybucket
|
||||||
33
source/minio-cli/minio-mc/mc-update.rst
Normal file
33
source/minio-cli/minio-mc/mc-update.rst
Normal file
@ -0,0 +1,33 @@
|
|||||||
|
=============
|
||||||
|
``mc update``
|
||||||
|
=============
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc update
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-update-desc
|
||||||
|
|
||||||
|
The :command:`mc update` command automatically updates the ``mc`` binary to
|
||||||
|
the latest stable version.
|
||||||
|
|
||||||
|
.. end-mc-update-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:command:`~mc update` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc update
|
||||||
|
|
||||||
|
Consider updating ``mc`` whenever you update the ``minio`` server binary to
|
||||||
|
ensure consistent behavior and compatibility.
|
||||||
120
source/minio-cli/minio-mc/mc-version.rst
Normal file
120
source/minio-cli/minio-mc/mc-version.rst
Normal file
@ -0,0 +1,120 @@
|
|||||||
|
==============
|
||||||
|
``mc version``
|
||||||
|
==============
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc version
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-version-desc
|
||||||
|
|
||||||
|
The :mc:`mc version` command enables or disables bucket versioning.
|
||||||
|
|
||||||
|
.. end-mc-version-desc
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
The :release:`RELEASE.2020-08-08T02-33-58Z` release renamed
|
||||||
|
``mc versioning`` to :mc:`mc version`.
|
||||||
|
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc version` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc version TARGET COMMAND
|
||||||
|
|
||||||
|
:mc:`~mc version` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
**Required** The full path to the bucket on which to enable or
|
||||||
|
disable bucket versioning. Specify the
|
||||||
|
:command:`alias <mc alias>` of a configured S3-compatible service as the
|
||||||
|
prefix to the :mc-cmd:`~mc version TARGET` path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc version play/mybucket COMMAND
|
||||||
|
|
||||||
|
.. mc-cmd:: enable
|
||||||
|
|
||||||
|
The :mc-cmd:`mc version TARGET enable <mc version enable>` command
|
||||||
|
enables bucket versioning on the :mc-cmd:`~mc version TARGET` bucket.
|
||||||
|
|
||||||
|
.. mc-cmd:: suspend
|
||||||
|
|
||||||
|
The :mc-cmd:`mc version TARGET suspend <mc version suspend>` command
|
||||||
|
disables bucket versioning on the :mc-cmd:`~mc version TARGET` bucket.
|
||||||
|
|
||||||
|
.. mc-cmd:: info
|
||||||
|
|
||||||
|
The :mc-cmd:`mc version TARGET info <mc version info>` command
|
||||||
|
returns the current bucket versioning configuration.
|
||||||
|
|
||||||
|
|
||||||
|
Behavior
|
||||||
|
--------
|
||||||
|
|
||||||
|
Object Locking Enables Bucket Versioning
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
While bucket versioning is disabled by default, configuring
|
||||||
|
object locking on a bucket or an object in that bucket automatically
|
||||||
|
enables versioning for the bucket. See
|
||||||
|
:mc:`mc lock` for more information on configuring object locking.
|
||||||
|
|
||||||
|
Requires Erasure Coding
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Bucket versioning requires that the MinIO deployment supports erasure coding.
|
||||||
|
See <erasure coding link> for more information.
|
||||||
|
|
||||||
|
Bucket Versioning with Existing Data
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Enabling bucket versioning on a bucket with existing data immediately applies
|
||||||
|
a versioning ID to any unversioned object.
|
||||||
|
|
||||||
|
Disabling bucket versioning on a bucket with existing versioned data does
|
||||||
|
*not* remove any versioned objects. Applications can continue to access
|
||||||
|
versioned data after disabling bucket versioning. Use
|
||||||
|
:mc:`mc rm` to delete an object *and* all its versions.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Enable Bucket Versioning
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc version play/mybucket enable
|
||||||
|
|
||||||
|
Disable Bucket Versioning
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc version play/mybucket suspend
|
||||||
108
source/minio-cli/minio-mc/mc-watch.rst
Normal file
108
source/minio-cli/minio-mc/mc-watch.rst
Normal file
@ -0,0 +1,108 @@
|
|||||||
|
============
|
||||||
|
``mc watch``
|
||||||
|
============
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
.. mc:: mc watch
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
.. start-mc-watch-desc
|
||||||
|
|
||||||
|
The :mc:`mc watch` command watches for events on the specified S3-compatible
|
||||||
|
service bucket or local filesystem path. For S3 services, use :mc:`mc event` to
|
||||||
|
configure bucket event notifications on S3-compatible services.
|
||||||
|
|
||||||
|
.. end-mc-watch-desc
|
||||||
|
|
||||||
|
Syntax
|
||||||
|
------
|
||||||
|
|
||||||
|
:mc:`~mc watch` has the following syntax:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc watch [FLAGS] TARGET
|
||||||
|
|
||||||
|
:mc:`~mc watch` supports the following arguments:
|
||||||
|
|
||||||
|
.. mc-cmd:: TARGET
|
||||||
|
|
||||||
|
*Required* The S3 service :mc:`alias <mc alias>` and bucket *or* the local
|
||||||
|
filesystem directory to watch for event notifications. Specify the
|
||||||
|
:mc-cmd:`alias <mc alias>` of a configured S3 service as the prefix to the
|
||||||
|
``TARGET`` path. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc event add play/mybucket
|
||||||
|
|
||||||
|
.. mc-cmd:: event
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The event(s) to watch for. Specify multiple events using a comma ``,``
|
||||||
|
delimiter. See :ref:`mc-event-supported-events` for supported events.
|
||||||
|
|
||||||
|
Defaults to ``put,delete, get``.
|
||||||
|
|
||||||
|
.. mc-cmd:: prefix
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The bucket prefix in which to watch for the speciified
|
||||||
|
:mc-cmd-option:`~mc event event`.
|
||||||
|
|
||||||
|
For example, given a :mc-cmd:`~mc event TARGET` of ``play/mybucket`` and a
|
||||||
|
:mc-cmd-option:`~mc event prefix` of ``photos``, only events in
|
||||||
|
``play/mybucket/photos`` trigger bucket notifications.
|
||||||
|
|
||||||
|
.. mc-cmd:: suffix
|
||||||
|
:option:
|
||||||
|
|
||||||
|
The bucket suffix in which to watch for the speciified
|
||||||
|
:mc-cmd-option:`~mc event event`.
|
||||||
|
|
||||||
|
For example, given a :mc-cmd:`~mc event TARGET` of ``play/mybucket`` and a
|
||||||
|
:mc-cmd-option:`~mc event suffix` of ``.jpg``, only events in
|
||||||
|
``play/mybucket/*.jpg`` trigger bucket notifications.
|
||||||
|
|
||||||
|
.. mc-cmd:: recursive, r
|
||||||
|
:option:
|
||||||
|
|
||||||
|
Recursively watch for events in the specified
|
||||||
|
:mc-cmd:`~mc watch TARGET` bucket path or local directory.
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
Watch for Events in a Bucket
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc watch play/testbucket
|
||||||
|
|
||||||
|
Watch for Events in a Local Directory
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
.. include:: /includes/play-alias-available.rst
|
||||||
|
:start-after: play-alias-only
|
||||||
|
:end-before: end-play-alias-only
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
mc watch ~/photos
|
||||||
|
|
||||||
|
|
||||||
1416
source/minio-features/bucket-notifications.md
Normal file
1416
source/minio-features/bucket-notifications.md
Normal file
File diff suppressed because it is too large
Load Diff
28
source/minio-features/overview.rst
Normal file
28
source/minio-features/overview.rst
Normal file
@ -0,0 +1,28 @@
|
|||||||
|
=====================
|
||||||
|
MinIO Server Features
|
||||||
|
=====================
|
||||||
|
|
||||||
|
MinIO’s enterprise class features represent the standard in the object storage
|
||||||
|
space. From the AWS S3 API to S3 Select and our implementations of inline
|
||||||
|
erasure coding and security, our code is widely admired and frequently copied by
|
||||||
|
some of the biggest names in technology and business.
|
||||||
|
|
||||||
|
The following table lists MinIO features and their corresponding documentation:
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
:widths: 30 70
|
||||||
|
|
||||||
|
* - Feature
|
||||||
|
- Description
|
||||||
|
|
||||||
|
* - :doc:`Bucket Versioning </minio-features/bucket-notifications>`
|
||||||
|
- MinIO Bucket Versioning allows you to automatically publish notifications
|
||||||
|
to one or more configured notification targets when specific events
|
||||||
|
occur in a bucket.
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:titlesonly:
|
||||||
|
:hidden:
|
||||||
|
|
||||||
|
/minio-features/bucket-notifications
|
||||||
38
source/security/minio-security-TLS-encryption.rst
Normal file
38
source/security/minio-security-TLS-encryption.rst
Normal file
@ -0,0 +1,38 @@
|
|||||||
|
==============================
|
||||||
|
MinIO Transport Layer Security
|
||||||
|
==============================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
Overview
|
||||||
|
--------
|
||||||
|
|
||||||
|
The MinIO server supports enabling TLS encryption of incoming and outgoing
|
||||||
|
traffic. MinIO recommends all MinIO servers run with TLS enabled to ensure
|
||||||
|
end-to-end security of client-server or server-server transmissions.
|
||||||
|
|
||||||
|
The MinIO server looks for a private key ``private.key`` and public certificate
|
||||||
|
``public.crt`` in the following directories:
|
||||||
|
|
||||||
|
- **Linux/OSX** : ``${HOME}/.minio/certs``
|
||||||
|
|
||||||
|
- **Windows** : ``%%USERPROFILE%%\.minio\certs``
|
||||||
|
|
||||||
|
MinIO only supports keys and certificates in the PEM format.
|
||||||
|
|
||||||
|
You can customize the certificate directory by passing the ``--certs-dir``
|
||||||
|
option to ``minio server``. The ``certs`` directory must also include any
|
||||||
|
intermediate certificates required to establish a chain of trust to the root CA.
|
||||||
|
|
||||||
|
Creating a Certificate for a MinIO Server
|
||||||
|
-----------------------------------------
|
||||||
|
|
||||||
|
This section includes guidance for creating a private key and public
|
||||||
|
certificate for a MinIO Server instance.
|
||||||
|
|
||||||
|
For MinIO deployments on Kubernetes, see the <future TLS kubernetes doc>
|
||||||
|
tutorial for more specific instructions.
|
||||||
659
source/security/minio-security-policy-based-access-control.rst
Normal file
659
source/security/minio-security-policy-based-access-control.rst
Normal file
@ -0,0 +1,659 @@
|
|||||||
|
===========================
|
||||||
|
Policy Based Access Control
|
||||||
|
===========================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. _minio-security-pbac-built-in:
|
||||||
|
|
||||||
|
Built-In Policies
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
MinIO provides the following built-in policies for assigning to users
|
||||||
|
and groups:
|
||||||
|
|
||||||
|
.. userpolicy:: readonly
|
||||||
|
|
||||||
|
Grants read-only permissions for all buckets and objects on the MinIO server.
|
||||||
|
|
||||||
|
.. userpolicy:: readwrite
|
||||||
|
|
||||||
|
Grants read and write permissions for all buckets and objects on the
|
||||||
|
MinnIO server.
|
||||||
|
|
||||||
|
.. userpolicy:: diagnostics
|
||||||
|
|
||||||
|
Grants permission to perform diagnostic actions on the MinIO server.
|
||||||
|
|
||||||
|
.. userpolicy:: writeonly
|
||||||
|
|
||||||
|
Grants write-only permissions for all buckets and objects on the MinIO
|
||||||
|
server.
|
||||||
|
|
||||||
|
.. _minio-security-pbac-document:
|
||||||
|
|
||||||
|
Policy Document Structure
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
MinIO policy documents use the same schema as
|
||||||
|
:aws-docs:`AWS IAM Policy <IAM/latest/UserGuide/access.html>` documents.
|
||||||
|
|
||||||
|
The following sample document provides a general schema for creating custom
|
||||||
|
policies for use with a MinIO deployment. For more complete documentation on IAM
|
||||||
|
policy elements, see the :aws-docs:`IAM JSON Policy Elements Reference
|
||||||
|
<IAM/latest/UserGuide/reference_policies_elements.html>`.
|
||||||
|
|
||||||
|
.. code-block:: javascript
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
{
|
||||||
|
"Version" : "2012-10-17",
|
||||||
|
"Statement" : [
|
||||||
|
{
|
||||||
|
"Effect" : "Allow",
|
||||||
|
"Action" : [ "s3:<ActionName>", ... ],
|
||||||
|
"Resource" : "arn:minio:s3:::*",
|
||||||
|
"Condition" : { ... }
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"Effect" : "Deny",
|
||||||
|
"Action" : [ "s3:<ActionName>", ... ],
|
||||||
|
"Resource" : "arn:minio:s3:::*",
|
||||||
|
"Condition" : { ... }
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
- For the ``Statement.Action`` array, specify one or more
|
||||||
|
:ref:`supported S3 actions <minio-security-pbac-actions>`. MinIO deployments
|
||||||
|
supports a subset of AWS S3 actions.
|
||||||
|
|
||||||
|
- For the ``Statement.Resource`` key, you can replace the ``*`` with
|
||||||
|
the specific bucket to which the policy statement should apply.
|
||||||
|
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
|
||||||
|
deployments supports a subset of AWS S3 conditions.
|
||||||
|
|
||||||
|
.. _minio-security-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>`.
|
||||||
|
|
||||||
|
The following table lists the MinIO-supported policy action keys.
|
||||||
|
|
||||||
|
.. policy-action:: s3:*
|
||||||
|
|
||||||
|
Selector for all supported S3 actions.
|
||||||
|
|
||||||
|
.. policy-action:: s3:AbortMultipartUpload
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:AbortMultipartUpload
|
||||||
|
<API_AbortMultipartUpload.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:CreateBucket
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:CreateBucket <API_CreateBucket.html>` IAM
|
||||||
|
action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:DeleteBucket
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:DeleteBucket <API_DeleteBucket.html>` IAM
|
||||||
|
action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:ForceDeleteBucket
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:DeleteBucket <API_ForceDeleteBucket.html>`
|
||||||
|
IAM action for operations with the ``x-minio-force-delete`` flag.
|
||||||
|
|
||||||
|
.. policy-action:: s3:DeleteBucketPolicy
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:DeleteBucketPolicy
|
||||||
|
<API_DeleteBucketPolicy.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:DeleteObject
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:DeleteObject <API_DeleteObject.html>` IAM
|
||||||
|
action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetBucketLocation
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetBucketLocation
|
||||||
|
<API_GetBucketLocation.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetBucketNotification
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetBucketNotification
|
||||||
|
<API_GetBucketNotification.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetBucketPolicy
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetBucketPolicy <API_GetBucketPolicy.html>`
|
||||||
|
IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetObject
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetObject <API_GetObject.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:HeadBucket
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:HeadBucket <API_HeadBucket.html>` IAM action.
|
||||||
|
|
||||||
|
*This action is unused in MinIO.*
|
||||||
|
|
||||||
|
.. policy-action:: s3:ListAllMyBuckets
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:ListAllMyBuckets <API_ListAllMyBuckets.html>`
|
||||||
|
IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:ListBucket
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:ListBucket <API_ListBucket.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:ListMultipartUploads
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:ListMultipartUploads
|
||||||
|
<API_ListMultipartUploads.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:ListenNotification
|
||||||
|
|
||||||
|
MinIO Extension for controlling API operations related to MinIO Bucket
|
||||||
|
Notifications.
|
||||||
|
|
||||||
|
This action is **not** intended for use with other S3-compatible services.
|
||||||
|
|
||||||
|
.. policy-action:: s3:ListenBucketNotification
|
||||||
|
|
||||||
|
MinIO Extension for controlling API operations related to MinIO Bucket
|
||||||
|
Notifications.
|
||||||
|
|
||||||
|
This action is **not** intended for use with other S3-compatible services.
|
||||||
|
|
||||||
|
.. policy-action:: s3:ListParts
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:ListParts <API_ListParts.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:PutBucketLifecycle
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:PutBucketLifecycle
|
||||||
|
<API_PutBucketLifecycle.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetBucketLifecycle
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetBucketLifecycle
|
||||||
|
<API_GetBucketLifecycle.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:PutObjectNotification
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:PutObjectNotification
|
||||||
|
<API_PutObjectNotification.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:PutBucketPolicy
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:PutBucketPolicy <API_PutBucketPolicy.html>`
|
||||||
|
IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:PutObject
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:PutObject <API_PutObject.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:DeleteObjectVersion
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:DeleteObjectVersion
|
||||||
|
<API_DeleteObjectVersion.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:DeleteObjectVersionTagging
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:DeleteObjectVersionTagging
|
||||||
|
<API_DeleteObjectVersionTagging.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetObjectVersion
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetObjectVersion
|
||||||
|
<API_GetObjectVersion.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetObjectVersionTagging
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetObjectVersionTagging
|
||||||
|
<API_GetObjectVersionTagging.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:PutObjectVersionTagging
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:PutObjectVersionTagging
|
||||||
|
<API_PutObjectVersionTagging.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:BypassGovernanceRetention
|
||||||
|
|
||||||
|
Corresponds to the :s3-docs:`s3:BypassGovernanceRetention
|
||||||
|
<object-lock-managing.html#object-lock-managing-bypass>` IAM action.
|
||||||
|
|
||||||
|
This action applies to the following API operations on objects locked under
|
||||||
|
:mc-cmd:`GOVERNANCE <mc retention set MODE>` retention mode:
|
||||||
|
|
||||||
|
- ``PutObjectRetention``
|
||||||
|
- ``PutObject``
|
||||||
|
- ``DeleteObject``
|
||||||
|
|
||||||
|
.. policy-action:: s3:PutObjectRetention
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:PutObjectRetention
|
||||||
|
<API_PutObjectRetention.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetObjectRetention
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetObjectRetention
|
||||||
|
<API_GetObjectRetention.html>` IAM action.
|
||||||
|
|
||||||
|
This action applies to the following API operations on objects locked under
|
||||||
|
any retention mode:
|
||||||
|
|
||||||
|
- ``GetObject``
|
||||||
|
- ``HeadObject``
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetObjectLegalHold
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetObjectLegalHold
|
||||||
|
<API_GetObjectLegalHold.html>` IAM action.
|
||||||
|
|
||||||
|
This action applies to the following API operations on objects locked under
|
||||||
|
legal hold:
|
||||||
|
|
||||||
|
- ``GetObject``
|
||||||
|
|
||||||
|
.. policy-action:: s3:PutObjectLegalHold
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:PutObjectLegalHold
|
||||||
|
<API_PutObjectLegalHold.html>` IAM action.
|
||||||
|
|
||||||
|
This action applies to the following API operations on objects locked
|
||||||
|
under legal hold:
|
||||||
|
|
||||||
|
- ``PutObject``
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetBucketObjectLockConfiguration
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetBucketObjectLockConfiguration
|
||||||
|
<API_GetBucketObjectLockConfiguration.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:PutBucketObjectLockConfiguration
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:PutBucketObjectLockConfiguration
|
||||||
|
<API_PutBucketObjectLockConfiguration.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetBucketTagging
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetBucketTagging <API_GetBucketTagging.html>`
|
||||||
|
IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:PutBucketTagging
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:PutBucketTagging <API_PutBucketTagging.html>`
|
||||||
|
IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:Get
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:Get <API_Get.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:Put
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:Put <API_Put.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:Delete
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:Delete <API_Delete.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:PutBucketEncryption
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:PutBucketEncryption
|
||||||
|
<API_PutBucketEncryption.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetBucketEncryption
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetBucketEncryption
|
||||||
|
<API_GetBucketEncryption.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:PutBucketVersioning
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:PutBucketVersioning
|
||||||
|
<API_PutBucketVersioning.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetBucketVersioning
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetBucketVersioning
|
||||||
|
<API_GetBucketVersioning.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetReplicationConfiguration
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetReplicationConfiguration
|
||||||
|
<API_GetReplicationConfiguration.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:PutReplicationConfiguration
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:PutReplicationConfiguration
|
||||||
|
<PutReplicationConfiguration.html>` IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:ReplicateObject
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:ReplicateObject <API_ReplicateObject.html>`
|
||||||
|
IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:ReplicateDelete
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:ReplicateDelete <API_ReplicateDelete.html>`
|
||||||
|
IAM action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:ReplicateTags
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:ReplicateTags <API_ReplicateTags.html>` IAM
|
||||||
|
action.
|
||||||
|
|
||||||
|
.. policy-action:: s3:GetObjectVersionForReplication
|
||||||
|
|
||||||
|
Corresponds to the :s3-api:`s3:GetObjectVersionForReplication
|
||||||
|
<API_GetObjectVersionForReplication.html>` IAM action.
|
||||||
|
|
||||||
|
|
||||||
|
.. _minio-security-pbac-mc-admin-actions:
|
||||||
|
|
||||||
|
``mc admin`` Policy Action Keys
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
MinIO supports the following actions for use with defining policies
|
||||||
|
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:Heal
|
||||||
|
|
||||||
|
Allows heal command
|
||||||
|
|
||||||
|
.. policy-action:: admin:StorageInfo
|
||||||
|
|
||||||
|
Allows listing server info
|
||||||
|
|
||||||
|
.. policy-action:: admin:DataUsageInfo
|
||||||
|
|
||||||
|
Allows listing data usage info
|
||||||
|
|
||||||
|
.. policy-action:: admin:TopLocksInfo
|
||||||
|
|
||||||
|
Allows listing top locks
|
||||||
|
|
||||||
|
.. policy-action:: admin:Profiling
|
||||||
|
|
||||||
|
Allows profiling
|
||||||
|
|
||||||
|
.. policy-action:: admin:ServerTrace
|
||||||
|
|
||||||
|
Allows listing server trace
|
||||||
|
|
||||||
|
.. policy-action:: admin:ConsoleLog
|
||||||
|
|
||||||
|
Allows listing console logs on terminal
|
||||||
|
|
||||||
|
.. policy-action:: admin:KMSCreateKey
|
||||||
|
|
||||||
|
Allows creating a new KMS master key
|
||||||
|
|
||||||
|
.. policy-action:: admin:KMSKeyStatus
|
||||||
|
|
||||||
|
Allows getting KMS key status
|
||||||
|
|
||||||
|
.. policy-action:: admin:ServerInfo
|
||||||
|
|
||||||
|
Allows listing server info
|
||||||
|
|
||||||
|
.. policy-action:: admin:OBDInfo
|
||||||
|
|
||||||
|
Allows obtaining cluster on-board diagnostics
|
||||||
|
|
||||||
|
.. policy-action:: admin:ServerUpdate
|
||||||
|
|
||||||
|
Allows MinIO binary update
|
||||||
|
|
||||||
|
.. policy-action:: admin:ServiceRestart
|
||||||
|
|
||||||
|
Allows restart of MinIO service.
|
||||||
|
|
||||||
|
.. policy-action:: admin:ServiceStop
|
||||||
|
|
||||||
|
Allows stopping MinIO service.
|
||||||
|
|
||||||
|
.. policy-action:: admin:ConfigUpdate
|
||||||
|
|
||||||
|
Allows MinIO config management
|
||||||
|
|
||||||
|
.. policy-action:: admin:CreateUser
|
||||||
|
|
||||||
|
Allows creating MinIO user
|
||||||
|
|
||||||
|
.. policy-action:: admin:DeleteUser
|
||||||
|
|
||||||
|
Allows deleting MinIO user
|
||||||
|
|
||||||
|
.. policy-action:: admin:ListUsers
|
||||||
|
|
||||||
|
Allows list users permission
|
||||||
|
|
||||||
|
.. policy-action:: admin:EnableUser
|
||||||
|
|
||||||
|
Allows enable user permission
|
||||||
|
|
||||||
|
.. policy-action:: admin:DisableUser
|
||||||
|
|
||||||
|
Allows disable user permission
|
||||||
|
|
||||||
|
.. policy-action:: admin:GetUser
|
||||||
|
|
||||||
|
Allows GET permission on user info
|
||||||
|
|
||||||
|
.. policy-action:: admin:AddUserToGroup
|
||||||
|
|
||||||
|
Allows adding user to group permission
|
||||||
|
|
||||||
|
.. policy-action:: admin:RemoveUserFromGroup
|
||||||
|
|
||||||
|
Allows removing user to group permission
|
||||||
|
|
||||||
|
.. policy-action:: admin:GetGroup
|
||||||
|
|
||||||
|
Allows getting group info
|
||||||
|
|
||||||
|
.. policy-action:: admin:ListGroups
|
||||||
|
|
||||||
|
Allows list groups permission
|
||||||
|
|
||||||
|
.. policy-action:: admin:EnableGroup
|
||||||
|
|
||||||
|
Allows enable group permission
|
||||||
|
|
||||||
|
.. policy-action:: admin:DisableGroup
|
||||||
|
|
||||||
|
Allows disable group permission
|
||||||
|
|
||||||
|
.. policy-action:: admin:CreatePolicy"
|
||||||
|
|
||||||
|
Allows create policy permission
|
||||||
|
|
||||||
|
.. policy-action:: admin:DeletePolicy
|
||||||
|
|
||||||
|
Allows delete policy permission
|
||||||
|
|
||||||
|
.. policy-action:: admin:GetPolicy
|
||||||
|
|
||||||
|
Allows get policy permission
|
||||||
|
|
||||||
|
.. policy-action:: admin:AttachUserOrGroupPolicy
|
||||||
|
|
||||||
|
Allows attaching a policy to a user/group
|
||||||
|
|
||||||
|
.. policy-action:: admin:ListUserPolicies
|
||||||
|
|
||||||
|
Allows listing user policies
|
||||||
|
|
||||||
|
.. policy-action:: admin:SetBucketQuota
|
||||||
|
|
||||||
|
Allows setting bucket quota
|
||||||
|
|
||||||
|
.. policy-action:: admin:GetBucketQuota
|
||||||
|
|
||||||
|
Allows getting bucket quota
|
||||||
|
|
||||||
|
.. policy-action:: admin:SetBucketTarget
|
||||||
|
|
||||||
|
Allows setting bucket target
|
||||||
|
|
||||||
|
.. policy-action:: admin:GetBucketTarget
|
||||||
|
|
||||||
|
Allows getting bucket targets
|
||||||
|
|
||||||
|
.. _minio-security-pbac-conditions:
|
||||||
|
|
||||||
|
Supported Policy Condition Keys
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
MinIO policy documents support IAM
|
||||||
|
:iam-docs:`conditional statements <reference_policies_elements_condition.html>`.
|
||||||
|
|
||||||
|
Each condition element consists of
|
||||||
|
:iam-docs:`operators <reference_policies_elements_condition_operators.html>`
|
||||||
|
and condition keys. MinIO supports a subset of IAM condition keys. For complete
|
||||||
|
information on any listed condition key, see the
|
||||||
|
:iam-docs:`IAM Condition Element Documentation
|
||||||
|
<reference_policies_elements_condition.html>`
|
||||||
|
|
||||||
|
MinIO supports the following condition keys for all supported
|
||||||
|
:ref:`actions <minio-security-pbac-actions>`:
|
||||||
|
|
||||||
|
- ``aws:Referer``
|
||||||
|
- ``aws:SourceIp``
|
||||||
|
- ``aws:UserAgent``
|
||||||
|
- ``aws:SecureTransport``
|
||||||
|
- ``aws:CurrentTime``
|
||||||
|
- ``aws:EpochTime``
|
||||||
|
- ``aws:PrincipalType``
|
||||||
|
- ``aws:userid``
|
||||||
|
- ``aws:username``
|
||||||
|
- ``s3:x-amz-content-sha256``
|
||||||
|
|
||||||
|
The following table lists additional supported condition keys for specific
|
||||||
|
actions:
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
:widths: 30 70
|
||||||
|
:width: 100%
|
||||||
|
|
||||||
|
* - Action Key
|
||||||
|
- Condition Keys
|
||||||
|
|
||||||
|
* - :policy-action:`s3:GetObject`
|
||||||
|
- | ``s3:x-amz-server-side-encryption``
|
||||||
|
| ``s3:x-amz-server-side-encryption-customer-algorithm``
|
||||||
|
|
||||||
|
* - :policy-action:`s3:ListBucket`
|
||||||
|
- | ``s3:prefix``
|
||||||
|
| ``s3:delimiter``
|
||||||
|
| ``s3:max-keys``
|
||||||
|
|
||||||
|
* - :policy-action:`s3:PutObject`
|
||||||
|
- | ``s3:x-amz-copy-source``
|
||||||
|
| ``s3:x-amz-server-side-encryption``
|
||||||
|
| ``s3:x-amz-server-side-encryption-customer-algorithm``
|
||||||
|
| ``s3:x-amz-metadata-directive``
|
||||||
|
| ``s3:x-amz-storage-class``
|
||||||
|
| ``s3:object-lock-retain-until-date``
|
||||||
|
| ``s3:object-lock-mode``
|
||||||
|
| ``s3:object-lock-legal-hold``
|
||||||
|
|
||||||
|
* - :policy-action:`s3:PutObjectRetention`
|
||||||
|
- | ``s3:x-amz-object-lock-remaining-retention-days``
|
||||||
|
| ``s3:x-amz-object-lock-retain-until-date``
|
||||||
|
| ``s3:x-amz-object-lock-mode``
|
||||||
|
|
||||||
|
* - :policy-action:`s3:PutObjectLegalHold`
|
||||||
|
- ``s3:object-lock-legal-hold``
|
||||||
|
|
||||||
|
* - :policy-action:`s3:BypassGovernanceRetention`
|
||||||
|
- | ``s3:object-lock-remaining-retention-days``
|
||||||
|
| ``s3:object-lock-retain-until-date``
|
||||||
|
| ``s3:object-lock-mode``
|
||||||
|
| ``s3:object-lock-legal-hold``
|
||||||
|
|
||||||
|
* - :policy-action:`s3:GetObjectVersion`
|
||||||
|
- ``s3:versionid``
|
||||||
|
|
||||||
|
* - :policy-action:`s3:GetObjectVersionTagging`
|
||||||
|
- ``s3:versionid``
|
||||||
|
|
||||||
|
* - :policy-action:`s3:DeleteObjectVersion`
|
||||||
|
- ``s3:versionid``
|
||||||
|
|
||||||
|
* - :policy-action:`s3:DeleteObjectVersionTagging`
|
||||||
|
- ``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>`.
|
||||||
|
|
||||||
|
- ``aws:Referer``
|
||||||
|
- ``aws:SourceIp``
|
||||||
|
- ``aws:UserAgent``
|
||||||
|
- ``aws:SecureTransport``
|
||||||
|
- ``aws:CurrentTime``
|
||||||
|
- ``aws:EpochTime``
|
||||||
|
|
||||||
|
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
|
||||||
|
IAM policy specifications. For example:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc config host add myminio http://myminio1.example.net:9000 <access_key> <secret_key>
|
||||||
|
|
||||||
|
mc admin policy add myminio/ new_policy new_policy.json
|
||||||
|
|
||||||
|
To add this policy to a user or group, use the ``mc admin policy set`` command:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
|
||||||
|
mc admin policy set myminio/ new_policy user=user_name
|
||||||
|
|
||||||
|
mc admin policy set myminio/ new_policy group=group_name
|
||||||
|
|
||||||
|
Add Policies to a User or Group
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
Remove Policies from a User or Group
|
||||||
|
------------------------------------
|
||||||
70
source/security/minio-security-security-token-service.rst
Normal file
70
source/security/minio-security-security-token-service.rst
Normal file
@ -0,0 +1,70 @@
|
|||||||
|
============================
|
||||||
|
MinIO Security Token Service
|
||||||
|
============================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
Overview
|
||||||
|
--------
|
||||||
|
|
||||||
|
The MinIO Security Token Service (STS) is an endpoint service that enables
|
||||||
|
clients to request temporary credentials for MinIO resources. Temporary
|
||||||
|
credentials work almost identically to default admin credentials, with some
|
||||||
|
differences:
|
||||||
|
|
||||||
|
- Temporary credentials are short-term, as the name implies. They can be
|
||||||
|
configured to last for anywhere from a few minutes to several hours. After the
|
||||||
|
credentials expire, MinIO no longer recognizes them or allows any kind of
|
||||||
|
access from API requests made with them.
|
||||||
|
|
||||||
|
- Temporary credentials do not need to be stored with the application but are
|
||||||
|
generated dynamically and provided to the application when requested. When (or
|
||||||
|
even before) the temporary credentials expire, the application can request new
|
||||||
|
credentials.
|
||||||
|
|
||||||
|
Consider the following advantages of using temporary credentials:
|
||||||
|
|
||||||
|
- Eliminates the need to embed long-term credentials with an application.
|
||||||
|
|
||||||
|
- Eliminates the need to provide access to buckets and objects without having to
|
||||||
|
define static credentials.
|
||||||
|
|
||||||
|
- Temporary credentials have a limited lifetime, there is no need to rotate them
|
||||||
|
or explicitly revoke them. Expired temporary credentials cannot be reused.
|
||||||
|
|
||||||
|
Identity Federation
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
MinIO STS supports the following identity federation providers:
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
:widths: 30 70
|
||||||
|
|
||||||
|
* - Provider
|
||||||
|
- Description
|
||||||
|
|
||||||
|
* - OpenID Providers
|
||||||
|
- Applications can request a client credential grant from an
|
||||||
|
OpenID-compatible identity provider. Clients validate their identity
|
||||||
|
using a JWT access token supplied by the identity provider.
|
||||||
|
|
||||||
|
See <doc> for more information on configuring OpenID-based identity
|
||||||
|
federation.
|
||||||
|
|
||||||
|
* - OpenID WebIdentity
|
||||||
|
- Applications can request temporary credentials using any OpenID (OIDC)
|
||||||
|
compatible web identity provider. See <doc> for more information.
|
||||||
|
|
||||||
|
* - AssumeRole
|
||||||
|
- Applications can request temporary credentials using a MinIO User
|
||||||
|
access and secret key.
|
||||||
|
|
||||||
|
* - Active Directory / Lightweight Directory Access Protocol (AD/LDAP)
|
||||||
|
- Applications can request temporary credentials using an external
|
||||||
|
AD/LDAP service.
|
||||||
|
|
||||||
153
source/security/minio-security-server-side-encryption.rst
Normal file
153
source/security/minio-security-server-side-encryption.rst
Normal file
@ -0,0 +1,153 @@
|
|||||||
|
=============================
|
||||||
|
Server-Side Object Encryption
|
||||||
|
=============================
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
.. contents:: On This Page
|
||||||
|
:local:
|
||||||
|
:depth: 1
|
||||||
|
|
||||||
|
Overview
|
||||||
|
--------
|
||||||
|
|
||||||
|
MinIO supports Server-Side Encryption (SSE) of objects, where the MinIO
|
||||||
|
stores objects on disk in an encrypted format. Only clients with access
|
||||||
|
to the correct secret key can decrypt and read the object.
|
||||||
|
|
||||||
|
MinIO supports two types of SSE encryption:
|
||||||
|
|
||||||
|
SSE-C
|
||||||
|
The server uses a secret key provided by the client to perform
|
||||||
|
encryption and decryption. SSE-C requires TLS connectivity between
|
||||||
|
clients and the MinIO server.
|
||||||
|
|
||||||
|
SSE-S3
|
||||||
|
The server uses a secret key managed by a Key Management System (KMS)
|
||||||
|
to perform encryption and decryption. SSE-S3 requires a compatible KMS
|
||||||
|
provider accessible by the MinIO server.
|
||||||
|
|
||||||
|
Encryption Process Overview
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
The MinIO server uses three distinct keys when encrypting or decrypting an
|
||||||
|
object:
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
:widths: 30 70
|
||||||
|
|
||||||
|
* - Key
|
||||||
|
- Description
|
||||||
|
|
||||||
|
* - External Key (EK)
|
||||||
|
- An external secret key used to generate additional encryption keys.
|
||||||
|
|
||||||
|
For SSE-C, the EK is the client-supplied secret key.
|
||||||
|
|
||||||
|
For SSE-S3, the EK is the KMS-supplied secret key.
|
||||||
|
|
||||||
|
* - Key Encryption Key (KEK)
|
||||||
|
- A unique secret key deterministically generated on-demand using the EK.
|
||||||
|
MinIO never stores the KEK on disk.
|
||||||
|
|
||||||
|
* - Object Encryption Key (OEK)
|
||||||
|
- A randomly generated per-object key used to encrypt or decrypt the
|
||||||
|
object. MinIO encrypts the OEK using the KEK and stores the encrypted
|
||||||
|
OEK as metadata with the object.
|
||||||
|
|
||||||
|
SSE Encryption Types
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
SSE with Client Provided Keys (SSE-C)
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
SSE-C allows S3 clients to specify an Encryption Key (EK) for encrypting or
|
||||||
|
decrypting an object stored on the MinIO server. The S3 client sends the secret
|
||||||
|
key as part of the HTTP request. For read requests with the correct secret key,
|
||||||
|
the MinIO server sends the *decrypted* object to the client applications. SSE-C
|
||||||
|
therefore *requires* TLS between the client and server to ensure end-to-end
|
||||||
|
security and protection of the secret key and any unencrypted data. While the
|
||||||
|
MinIO server never stores the client EK to disk, the client EK resides in system
|
||||||
|
RAM during the encryption or decryption process.
|
||||||
|
|
||||||
|
MinIO does not assume or require that S3 clients send a unique EK. However,
|
||||||
|
if clients use a single EK for multiple objects or buckets, the loss or
|
||||||
|
compromise of that EK *also* results in the loss or compromise of all data
|
||||||
|
encrypted with that EK.
|
||||||
|
|
||||||
|
Key Rotation
|
||||||
|
````````````
|
||||||
|
|
||||||
|
S3 clients can rotate the client EK of an existing object using an S3 ``COPY``
|
||||||
|
operation. The ``COPY`` source and destination *must* be the same, while the
|
||||||
|
request headers must contain both the current and the new client EK. For
|
||||||
|
example, the following request headers support rotating the client EK for an
|
||||||
|
object:
|
||||||
|
|
||||||
|
.. code-block:: shell
|
||||||
|
:class: copyable
|
||||||
|
|
||||||
|
X-Amz-Server-Side-Encryption-Customer-Key: Base64 encoded new key.
|
||||||
|
X-Amz-Copy-Source-Server-Side-Encryption-Customer-Key: Base64 encoded current key.
|
||||||
|
|
||||||
|
Such a special COPY request is also known as S3 SSE-C key rotation.
|
||||||
|
|
||||||
|
SSE with KMS Provided Keys (SSE-S3)
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
SSE-S3 allows S3 clinets to encrypt or decrypt an object at the MinIO server
|
||||||
|
using an external Key Management Service (KMS). The MinIO server requires
|
||||||
|
the KMS provide the following services:
|
||||||
|
|
||||||
|
- ``GenerateKey``: The MinIO server specifies the ID of a master key to the
|
||||||
|
KMS. The KMS then uses the master key to generate a new data key and
|
||||||
|
returns the plain data key and the master-key encrypted data key.
|
||||||
|
|
||||||
|
- ``DecryptKey``: The MinIO server specifies the ID of a master key to the KMS
|
||||||
|
along with an encrypted data key. The KMS uses the master key to decrypt
|
||||||
|
the data key and return the plain data key.
|
||||||
|
|
||||||
|
The MinIO server requests a new data key from the KMS for each uploaded
|
||||||
|
object and uses that data key as the Encryption Key (EK). MinIO stores
|
||||||
|
the encrypted EK and the master key ID as part of the object metadata.
|
||||||
|
While the MinIO server never stores the plain EK to disk, the EK resides
|
||||||
|
in system RAM during the encryption or decryption process.
|
||||||
|
|
||||||
|
Key Rotation
|
||||||
|
````````````
|
||||||
|
|
||||||
|
The MinIO server supports key rotation for SSE-S3 encrypted objects. The MinIO
|
||||||
|
server decrypts the Object Encryption Key (OEK) using the current encrypted data
|
||||||
|
key and the master key ID of the object metadata. If this succeeds, the server
|
||||||
|
requests a new data key from the KMS using the master key ID of the current
|
||||||
|
MinIO KMS configuration and re-wraps the OEK with a new KEK derived from the new
|
||||||
|
data key / EK.
|
||||||
|
|
||||||
|
<Diagram to come>
|
||||||
|
|
||||||
|
Only the root MinIO user can perform an SSE-S3 key rotation using the Admin-API via
|
||||||
|
the ``mc`` client. Refer to the ``mc admin guide`` <todo>
|
||||||
|
|
||||||
|
Secure Erasure and Locking
|
||||||
|
``````````````````````````
|
||||||
|
|
||||||
|
The MinIO server requires an available KMS to en/decrypt SSE-S3 encrypted
|
||||||
|
objects. Therefore it is possible to erase or lock some or all encrypted
|
||||||
|
objects. For example in case of a detected attack or other emergency situations
|
||||||
|
the following actions can be taken:
|
||||||
|
|
||||||
|
- Seal the KMS such that it cannot be accessed by MinIO server anymore. That
|
||||||
|
will lock all SSE-S3 encrypted objects protected by master keys stored on the
|
||||||
|
KMS. All these objects can not be decrypted as long as the KMS is sealed.
|
||||||
|
|
||||||
|
- Seal/Unmount one/some master keys. That will lock all SSE-S3 encrypted objects
|
||||||
|
protected by these master keys. All these objects can not be decrypted as long
|
||||||
|
as the key(s) are sealed.
|
||||||
|
|
||||||
|
- Delete one/some master keys. From a security standpoint, this is equal to
|
||||||
|
erasing all SSE-S3 encrypted objects protected by these master keys. All these
|
||||||
|
objects are lost forever as they cannot be decrypted. Especially deleting all
|
||||||
|
master keys at the KMS is equivalent to secure erasing all SSE-S3 encrypted
|
||||||
|
objects.
|
||||||
|
|
||||||
47
source/security/minio-security.rst
Normal file
47
source/security/minio-security.rst
Normal file
@ -0,0 +1,47 @@
|
|||||||
|
==============
|
||||||
|
MinIO Security
|
||||||
|
==============
|
||||||
|
|
||||||
|
.. default-domain:: minio
|
||||||
|
|
||||||
|
MinIO provides support for the following security features:
|
||||||
|
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
:widths: 30 70
|
||||||
|
|
||||||
|
* - Feature
|
||||||
|
- Description
|
||||||
|
|
||||||
|
* - Server-Side Object Encryption
|
||||||
|
- Encrypt objects using a secret key provided by the S3 client
|
||||||
|
or a supported Key Management System (KMS). Only clients with access
|
||||||
|
to the secret key can decrypt the object.
|
||||||
|
|
||||||
|
* - Transport Layer Security (TLS) Encryption
|
||||||
|
- Enable TLS encryption of all network traffic. Several MinIO
|
||||||
|
security features, such as Server-Side Object Encryption, require
|
||||||
|
TLS encryption to ensure end-to-end security of data.
|
||||||
|
|
||||||
|
* - Policy Based Access Control (RBAC)
|
||||||
|
- MinIO uses :aws-docs:`IAM-compatible policy documents
|
||||||
|
<IAM/latest/UserGuide/access_policies>` for controlling user privileges.
|
||||||
|
You can also assign privileges to a group, where all members of the
|
||||||
|
group inherit the group privileges. MinIO provides built-in
|
||||||
|
policies for the most common access patterns.
|
||||||
|
|
||||||
|
* - Security Token Service (STS)
|
||||||
|
- MinIO Security Token Service (STS) is an endpoint service that allows
|
||||||
|
clients to request temporary credentials for accessing MinIO resources.
|
||||||
|
MinIO STS supports multiple forms of identity federation, including
|
||||||
|
OpenID identity providers and Active Directory/LDAP services.
|
||||||
|
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:titlesonly:
|
||||||
|
:hidden:
|
||||||
|
|
||||||
|
/security/minio-security-policy-based-access-control
|
||||||
|
/security/minio-security-TLS-encryption
|
||||||
|
/security/minio-security-server-side-encryption
|
||||||
|
/security/minio-security-security-token-service
|
||||||
675
sphinxext/minio.py
Normal file
675
sphinxext/minio.py
Normal file
@ -0,0 +1,675 @@
|
|||||||
|
"""
|
||||||
|
sphinx.domains.minio
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The MinIO domain.
|
||||||
|
|
||||||
|
:copyright: Copyright 2007-2020 by MinIO Inc. See AUTHORS
|
||||||
|
:license: Apache License 2.0. See LICENSE
|
||||||
|
|
||||||
|
Based on the default JavaScript domain distributed with Sphinx (BSD 2-clause)
|
||||||
|
|
||||||
|
Additional work to adapt for MinIO done by MinIO Inc. (See AUTHORS)
|
||||||
|
|
||||||
|
See https://github.com/sphinx-doc/sphinx/blob/3.x/sphinx/domains/javascript.py.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
"""
|
||||||
|
|
||||||
|
from typing import Any, Dict, Iterator, List, Tuple
|
||||||
|
from typing import cast
|
||||||
|
|
||||||
|
from docutils import nodes
|
||||||
|
from docutils.nodes import Element, Node
|
||||||
|
from docutils.parsers.rst import directives
|
||||||
|
|
||||||
|
from sphinx import addnodes
|
||||||
|
from sphinx.addnodes import desc_signature, pending_xref
|
||||||
|
from sphinx.application import Sphinx
|
||||||
|
from sphinx.builders import Builder
|
||||||
|
from sphinx.directives import ObjectDescription
|
||||||
|
from sphinx.domains import Domain, ObjType
|
||||||
|
from sphinx.domains.python import _pseudo_parse_arglist
|
||||||
|
from sphinx.environment import BuildEnvironment
|
||||||
|
from sphinx.locale import _, __
|
||||||
|
from sphinx.roles import XRefRole
|
||||||
|
from sphinx.util import logging
|
||||||
|
from sphinx.util.docfields import Field, GroupedField, TypedField
|
||||||
|
from sphinx.util.docutils import SphinxDirective
|
||||||
|
from sphinx.util.nodes import make_id, make_refnode
|
||||||
|
|
||||||
|
|
||||||
|
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
|
||||||
|
as a prefix for linking purposes.
|
||||||
|
"""
|
||||||
|
|
||||||
|
has_content = False
|
||||||
|
required_arguments = 1
|
||||||
|
optional_arguments = 1 #for mc admin?
|
||||||
|
final_argument_whitespace = True
|
||||||
|
option_spec = {
|
||||||
|
'noindex': directives.flag # in case we do not want to create an index entry.
|
||||||
|
}
|
||||||
|
|
||||||
|
def run(self) -> List[Node]:
|
||||||
|
command = self.arguments[0].strip()
|
||||||
|
if (len(self.arguments) > 1):
|
||||||
|
command += " " + self.arguments[1].strip()
|
||||||
|
|
||||||
|
self.env.ref_context['minio:command'] = command
|
||||||
|
noindex = 'noindex' in self.options
|
||||||
|
ret = []
|
||||||
|
if not noindex:
|
||||||
|
domain = cast(MinIODomain, self.env.get_domain('minio'))
|
||||||
|
|
||||||
|
node_id = make_id(self.env, self.state.document, 'command', command)
|
||||||
|
domain.note_module(command, node_id)
|
||||||
|
# Make a duplicate entry in 'objects' to facilitate searching for
|
||||||
|
# the module in JavaScriptDomain.find_obj()
|
||||||
|
domain.note_object(command, 'command', node_id,
|
||||||
|
location=(self.env.docname, self.lineno))
|
||||||
|
|
||||||
|
target = nodes.target('', '', ids=[node_id], ismod=True)
|
||||||
|
|
||||||
|
self.state.document.note_explicit_target(target)
|
||||||
|
ret.append(target)
|
||||||
|
indextext = _('%s (command)') % command
|
||||||
|
inode = addnodes.index(entries=[('single', indextext, node_id, '', None)])
|
||||||
|
ret.append(inode)
|
||||||
|
return ret
|
||||||
|
|
||||||
|
class MinioMCObject(ObjectDescription):
|
||||||
|
"""
|
||||||
|
Description of a Minio ``mc`` or ``mc admin`` subcommand or subcommand argument
|
||||||
|
"""
|
||||||
|
|
||||||
|
has_arguments = True
|
||||||
|
|
||||||
|
display_prefix = None
|
||||||
|
|
||||||
|
allow_nesting = True
|
||||||
|
|
||||||
|
option_spec = {
|
||||||
|
'noindex': directives.flag,
|
||||||
|
'noindexentry': directives.flag,
|
||||||
|
'fullpath': directives.flag,
|
||||||
|
'option': directives.flag,
|
||||||
|
}
|
||||||
|
|
||||||
|
def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str]:
|
||||||
|
"""Breaks down construct signatures
|
||||||
|
|
||||||
|
Parses out prefix and argument list from construct definition. The
|
||||||
|
namespace and class will be determined by the nesting of domain
|
||||||
|
directives.
|
||||||
|
"""
|
||||||
|
sig = sig.strip()
|
||||||
|
if ',' in sig:
|
||||||
|
# For subcommands w/ aliases
|
||||||
|
member, alias = sig.split(',', 1)
|
||||||
|
member = member.strip()
|
||||||
|
alias = alias.strip()
|
||||||
|
else:
|
||||||
|
member = sig
|
||||||
|
alias = None
|
||||||
|
# If construct is nested, prefix the current prefix
|
||||||
|
prefix = self.env.ref_context.get('minio:object', None)
|
||||||
|
|
||||||
|
#Grab the top-level command name.
|
||||||
|
command_name = self.env.ref_context.get('minio:command')
|
||||||
|
name = member
|
||||||
|
format_name = member
|
||||||
|
format_alias = alias
|
||||||
|
if prefix:
|
||||||
|
fullname = ' '.join([prefix, name])
|
||||||
|
else:
|
||||||
|
fullname = name
|
||||||
|
|
||||||
|
if 'option' in self.options:
|
||||||
|
format_name = "--" + name
|
||||||
|
|
||||||
|
if 'option' in self.options and alias != None:
|
||||||
|
format_alias = "--" + alias
|
||||||
|
|
||||||
|
|
||||||
|
signode['command'] = command_name
|
||||||
|
signode['object'] = prefix
|
||||||
|
signode['fullname'] = fullname
|
||||||
|
|
||||||
|
if prefix:
|
||||||
|
signode += addnodes.desc_addname(prefix + ' ', ' ')
|
||||||
|
elif command_name and ('fullpath' in self.options):
|
||||||
|
signode += addnodes.desc_addname(command_name + ' ', command_name + ' ')
|
||||||
|
elif command_name:
|
||||||
|
signode += addnodes.desc_addname(command_name + ' ', ' ')
|
||||||
|
|
||||||
|
if (alias != None):
|
||||||
|
signode += addnodes.desc_name(name + ', ' + alias, format_name + ', ' + format_alias)
|
||||||
|
else:
|
||||||
|
signode += addnodes.desc_name(name, format_name)
|
||||||
|
|
||||||
|
return fullname, prefix
|
||||||
|
|
||||||
|
def add_target_and_index(self, name_obj: Tuple[str, str], sig: str,
|
||||||
|
signode: desc_signature) -> None:
|
||||||
|
mod_name = self.env.ref_context.get('minio:command')
|
||||||
|
fullname = (mod_name + ' ' if mod_name else '') + name_obj[0]
|
||||||
|
node_id = make_id(self.env, self.state.document, '', fullname)
|
||||||
|
signode['ids'].append(node_id)
|
||||||
|
|
||||||
|
self.state.document.note_explicit_target(signode)
|
||||||
|
|
||||||
|
domain = cast(MinIODomain, self.env.get_domain('minio'))
|
||||||
|
domain.note_object(fullname, self.objtype, node_id, location=signode)
|
||||||
|
|
||||||
|
if 'noindexentry' not in self.options:
|
||||||
|
indextext = self.get_index_text(mod_name, name_obj)
|
||||||
|
if indextext:
|
||||||
|
self.indexnode['entries'].append(('single', indextext, node_id, '', None))
|
||||||
|
|
||||||
|
def get_index_text(self, objectname: str, name_obj: Tuple[str, str]) -> str:
|
||||||
|
name, obj = name_obj
|
||||||
|
if self.objtype == 'function':
|
||||||
|
if not obj:
|
||||||
|
return _('%s() (built-in function)') % name
|
||||||
|
return _('%s() (%s method)') % (name, obj)
|
||||||
|
elif self.objtype == 'class':
|
||||||
|
return _('%s() (class)') % name
|
||||||
|
elif self.objtype == 'data':
|
||||||
|
return _('%s (global variable or constant)') % name
|
||||||
|
elif self.objtype == 'attribute':
|
||||||
|
return _('%s (%s attribute)') % (name, obj)
|
||||||
|
return ''
|
||||||
|
|
||||||
|
def before_content(self) -> None:
|
||||||
|
"""Handle object nesting before content
|
||||||
|
|
||||||
|
:minio:`MinioObject` represents MinIO language constructs. For
|
||||||
|
constructs that are nestable, this method will build up a stack of the
|
||||||
|
nesting heirarchy so that it can be later de-nested correctly, in
|
||||||
|
:minio:meth:`after_content`.
|
||||||
|
|
||||||
|
The following keys are used in ``self.env.ref_context``:
|
||||||
|
|
||||||
|
minio:objects
|
||||||
|
Stores the object prefix history. With each nested element, we
|
||||||
|
add the object prefix to this list. When we exit that object's
|
||||||
|
nesting level, ::`after_content` is triggered and the
|
||||||
|
prefix is removed from the end of the list.
|
||||||
|
|
||||||
|
minio:object
|
||||||
|
Current object prefix. This should generally reflect the last
|
||||||
|
element in the prefix history
|
||||||
|
"""
|
||||||
|
prefix = None
|
||||||
|
if self.names:
|
||||||
|
(obj_name, obj_name_prefix) = self.names.pop()
|
||||||
|
prefix = obj_name_prefix.strip('.') if obj_name_prefix else None
|
||||||
|
if self.allow_nesting:
|
||||||
|
prefix = obj_name
|
||||||
|
if prefix:
|
||||||
|
self.env.ref_context['minio:object'] = prefix
|
||||||
|
if self.allow_nesting:
|
||||||
|
objects = self.env.ref_context.setdefault('minio:objects', [])
|
||||||
|
objects.append(prefix)
|
||||||
|
|
||||||
|
def after_content(self) -> None:
|
||||||
|
"""Handle object de-nesting after content
|
||||||
|
|
||||||
|
If this class is a nestable object, removing the last nested class prefix
|
||||||
|
ends further nesting in the object.
|
||||||
|
|
||||||
|
If this class is not a nestable object, the list of classes should not
|
||||||
|
be altered as we didn't affect the nesting levels in
|
||||||
|
:py:meth:`before_content`.
|
||||||
|
"""
|
||||||
|
objects = self.env.ref_context.setdefault('minio:objects', [])
|
||||||
|
if self.allow_nesting:
|
||||||
|
try:
|
||||||
|
objects.pop()
|
||||||
|
except IndexError:
|
||||||
|
pass
|
||||||
|
self.env.ref_context['minio:object'] = (objects[-1] if len(objects) > 0
|
||||||
|
else None)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
class MinioObject(ObjectDescription):
|
||||||
|
"""
|
||||||
|
Description of a MinIO object.
|
||||||
|
"""
|
||||||
|
#: If set to ``True`` this object is callable and a `desc_parameterlist` is
|
||||||
|
#: added
|
||||||
|
has_arguments = False
|
||||||
|
|
||||||
|
#: what is displayed right before the documentation entry
|
||||||
|
display_prefix = None # type: str
|
||||||
|
|
||||||
|
#: If ``allow_nesting`` is ``True``, the object prefixes will be accumulated
|
||||||
|
#: based on directive nesting
|
||||||
|
allow_nesting = False
|
||||||
|
|
||||||
|
option_spec = {
|
||||||
|
'noindex': directives.flag,
|
||||||
|
'noindexentry': directives.flag,
|
||||||
|
}
|
||||||
|
|
||||||
|
def handle_signature(self, sig: str, signode: desc_signature) -> Tuple[str, str]:
|
||||||
|
"""Breaks down construct signatures
|
||||||
|
|
||||||
|
Parses out prefix and argument list from construct definition. The
|
||||||
|
namespace and class will be determined by the nesting of domain
|
||||||
|
directives.
|
||||||
|
"""
|
||||||
|
sig = sig.strip()
|
||||||
|
if '(' in sig and sig[-1:] == ')':
|
||||||
|
member, arglist = sig.split('(', 1)
|
||||||
|
member = member.strip()
|
||||||
|
arglist = arglist[:-1].strip()
|
||||||
|
elif ',' in sig:
|
||||||
|
# Bit ugly. For subcommands w/ aliases
|
||||||
|
member, alias = sig.split(',', 1)
|
||||||
|
member = member.strip()
|
||||||
|
alias = alias.strip()
|
||||||
|
else:
|
||||||
|
member = sig
|
||||||
|
arglist = None
|
||||||
|
alias = None
|
||||||
|
# If construct is nested, prefix the current prefix
|
||||||
|
prefix = self.env.ref_context.get('minio:object', None)
|
||||||
|
mod_name = self.env.ref_context.get('minio:command')
|
||||||
|
name = member
|
||||||
|
try:
|
||||||
|
member_prefix, member_name = member.rsplit('.', 1)
|
||||||
|
except ValueError:
|
||||||
|
member_name = name
|
||||||
|
member_prefix = ''
|
||||||
|
finally:
|
||||||
|
name = member_name
|
||||||
|
if prefix and member_prefix:
|
||||||
|
prefix = '.'.join([prefix, member_prefix])
|
||||||
|
elif prefix is None and member_prefix:
|
||||||
|
prefix = member_prefix
|
||||||
|
fullname = name
|
||||||
|
if prefix and self.allow_nesting==False:
|
||||||
|
fullname = '.'.join([prefix, name])
|
||||||
|
elif prefix and self.allow_nesting==True:
|
||||||
|
fullname = ' '.join([prefix, name])
|
||||||
|
|
||||||
|
signode['module'] = mod_name
|
||||||
|
signode['object'] = prefix
|
||||||
|
signode['fullname'] = fullname
|
||||||
|
|
||||||
|
if self.display_prefix:
|
||||||
|
signode += addnodes.desc_annotation(self.display_prefix,
|
||||||
|
self.display_prefix)
|
||||||
|
|
||||||
|
# In our current usage, we only nest for command/subcommand. So we
|
||||||
|
# need to split some of the logic here from nesting of YAML or JSON
|
||||||
|
# So if allow_nesting is true, we should use " " instead of "." for
|
||||||
|
# the prefix description.
|
||||||
|
# We also have an exit for the 'subcommand' type so that we don't end
|
||||||
|
# up building long name strings for subcommands
|
||||||
|
# Finally for subcommands w/ aliases, need to append the alias name
|
||||||
|
|
||||||
|
|
||||||
|
if prefix and self.allow_nesting == False:
|
||||||
|
signode += addnodes.desc_addname(prefix + '.', prefix + '.')
|
||||||
|
elif prefix and self.allow_nesting == True and self.objtype != 'subcommand':
|
||||||
|
signode += addnodes.desc_addname(prefix + ' ', prefix + ' ')
|
||||||
|
signode += addnodes.desc_addname(alias + ' ', alias + ' ')
|
||||||
|
elif mod_name:
|
||||||
|
signode += addnodes.desc_addname(mod_name + '.', mod_name + '.')
|
||||||
|
if (alias != None):
|
||||||
|
signode += addnodes.desc_name(name + ", " + alias, name + ", " + alias)
|
||||||
|
else:
|
||||||
|
signode += addnodes.desc_name(name, name)
|
||||||
|
if self.has_arguments:
|
||||||
|
if not arglist:
|
||||||
|
signode += addnodes.desc_parameterlist()
|
||||||
|
else:
|
||||||
|
_pseudo_parse_arglist(signode, arglist)
|
||||||
|
return fullname, prefix
|
||||||
|
|
||||||
|
def add_target_and_index(self, name_obj: Tuple[str, str], sig: str,
|
||||||
|
signode: desc_signature) -> None:
|
||||||
|
mod_name = self.env.ref_context.get('minio:module')
|
||||||
|
fullname = (mod_name + '.' if mod_name else '') + name_obj[0]
|
||||||
|
node_id = make_id(self.env, self.state.document, '', fullname)
|
||||||
|
signode['ids'].append(node_id)
|
||||||
|
|
||||||
|
# Assign old styled node_id not to break old hyperlinks (if possible)
|
||||||
|
# Note: Will be removed in Sphinx-5.0 (RemovedInSphinx50Warning)
|
||||||
|
old_node_id = self.make_old_id(fullname)
|
||||||
|
if old_node_id not in self.state.document.ids and old_node_id not in signode['ids']:
|
||||||
|
signode['ids'].append(old_node_id)
|
||||||
|
|
||||||
|
self.state.document.note_explicit_target(signode)
|
||||||
|
|
||||||
|
domain = cast(MinIODomain, self.env.get_domain('minio'))
|
||||||
|
domain.note_object(fullname, self.objtype, node_id, location=signode)
|
||||||
|
|
||||||
|
if 'noindexentry' not in self.options:
|
||||||
|
indextext = self.get_index_text(mod_name, name_obj)
|
||||||
|
if indextext:
|
||||||
|
self.indexnode['entries'].append(('single', indextext, node_id, '', None))
|
||||||
|
|
||||||
|
def get_index_text(self, objectname: str, name_obj: Tuple[str, str]) -> str:
|
||||||
|
name, obj = name_obj
|
||||||
|
if self.objtype == 'function':
|
||||||
|
if not obj:
|
||||||
|
return _('%s() (built-in function)') % name
|
||||||
|
return _('%s() (%s method)') % (name, obj)
|
||||||
|
elif self.objtype == 'class':
|
||||||
|
return _('%s() (class)') % name
|
||||||
|
elif self.objtype == 'data':
|
||||||
|
return _('%s (global variable or constant)') % name
|
||||||
|
elif self.objtype == 'attribute':
|
||||||
|
return _('%s (%s attribute)') % (name, obj)
|
||||||
|
return ''
|
||||||
|
|
||||||
|
def before_content(self) -> None:
|
||||||
|
"""Handle object nesting before content
|
||||||
|
|
||||||
|
:py:class:`MinioObject` represents MinIO language constructs. For
|
||||||
|
constructs that are nestable, this method will build up a stack of the
|
||||||
|
nesting heirarchy so that it can be later de-nested correctly, in
|
||||||
|
:py:meth:`after_content`.
|
||||||
|
|
||||||
|
For constructs that aren't nestable, the stack is bypassed, and instead
|
||||||
|
only the most recent object is tracked. This object prefix name will be
|
||||||
|
removed with :py:meth:`after_content`.
|
||||||
|
|
||||||
|
The following keys are used in ``self.env.ref_context``:
|
||||||
|
|
||||||
|
minio:objects
|
||||||
|
Stores the object prefix history. With each nested element, we
|
||||||
|
add the object prefix to this list. When we exit that object's
|
||||||
|
nesting level, :py:meth:`after_content` is triggered and the
|
||||||
|
prefix is removed from the end of the list.
|
||||||
|
|
||||||
|
minio:object
|
||||||
|
Current object prefix. This should generally reflect the last
|
||||||
|
element in the prefix history
|
||||||
|
"""
|
||||||
|
prefix = None
|
||||||
|
if self.names:
|
||||||
|
(obj_name, obj_name_prefix) = self.names.pop()
|
||||||
|
prefix = obj_name_prefix.strip('.') if obj_name_prefix else None
|
||||||
|
if self.allow_nesting:
|
||||||
|
prefix = obj_name
|
||||||
|
if prefix:
|
||||||
|
self.env.ref_context['minio:object'] = prefix
|
||||||
|
if self.allow_nesting:
|
||||||
|
objects = self.env.ref_context.setdefault('minio:objects', [])
|
||||||
|
objects.append(prefix)
|
||||||
|
|
||||||
|
def after_content(self) -> None:
|
||||||
|
"""Handle object de-nesting after content
|
||||||
|
|
||||||
|
If this class is a nestable object, removing the last nested class prefix
|
||||||
|
ends further nesting in the object.
|
||||||
|
|
||||||
|
If this class is not a nestable object, the list of classes should not
|
||||||
|
be altered as we didn't affect the nesting levels in
|
||||||
|
:py:meth:`before_content`.
|
||||||
|
"""
|
||||||
|
objects = self.env.ref_context.setdefault('minio:objects', [])
|
||||||
|
if self.allow_nesting:
|
||||||
|
try:
|
||||||
|
objects.pop()
|
||||||
|
except IndexError:
|
||||||
|
pass
|
||||||
|
self.env.ref_context['minio:object'] = (objects[-1] if len(objects) > 0
|
||||||
|
else None)
|
||||||
|
|
||||||
|
def make_old_id(self, fullname: str) -> str:
|
||||||
|
"""Generate old styled node_id for Minio objects.
|
||||||
|
|
||||||
|
.. note:: Old Styled node_id was used until Sphinx-3.0.
|
||||||
|
This will be removed in Sphinx-5.0.
|
||||||
|
"""
|
||||||
|
return fullname.replace('$', '_S_')
|
||||||
|
|
||||||
|
class MinioCallable(MinioObject):
|
||||||
|
"""Description of a MinIO function, method or constructor."""
|
||||||
|
has_arguments = True
|
||||||
|
|
||||||
|
doc_field_types = [
|
||||||
|
TypedField('arguments', label=_('Arguments'),
|
||||||
|
names=('argument', 'arg', 'parameter', 'param'),
|
||||||
|
typerolename='func', typenames=('paramtype', 'type')),
|
||||||
|
GroupedField('errors', label=_('Throws'), rolename='err',
|
||||||
|
names=('throws', ),
|
||||||
|
can_collapse=True),
|
||||||
|
Field('returnvalue', label=_('Returns'), has_arg=False,
|
||||||
|
names=('returns', 'return')),
|
||||||
|
Field('returntype', label=_('Return type'), has_arg=False,
|
||||||
|
names=('rtype',)),
|
||||||
|
]
|
||||||
|
|
||||||
|
class MinioConstructor(MinioCallable):
|
||||||
|
"""Like a callable but with a different prefix."""
|
||||||
|
display_prefix = 'class '
|
||||||
|
allow_nesting = True
|
||||||
|
|
||||||
|
class MinioCommand(MinioObject):
|
||||||
|
allow_nesting = True
|
||||||
|
|
||||||
|
class MinioCMDOptionXRefRole(XRefRole):
|
||||||
|
def process_link(self, env: BuildEnvironment, refnode: Element,
|
||||||
|
has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
|
||||||
|
# basically what sphinx.domains.python.PyXRefRole does
|
||||||
|
refnode['minio:object'] = env.ref_context.get('minio:object')
|
||||||
|
refnode['minio:module'] = env.ref_context.get('minio:module')
|
||||||
|
refnode['minio:command'] = env.ref_context.get('minio:commannd')
|
||||||
|
if not has_explicit_title:
|
||||||
|
title = title.lstrip('.')
|
||||||
|
target = target.lstrip('~')
|
||||||
|
if title[0:1] == '~':
|
||||||
|
title = title[1:]
|
||||||
|
# Handle stripping lead path from commands.
|
||||||
|
space = title.rfind(' ')
|
||||||
|
if space != -1:
|
||||||
|
title = title[space + 1:]
|
||||||
|
title = "--" + title
|
||||||
|
else:
|
||||||
|
#full command, so need to insert the `--`
|
||||||
|
title = title[:title.rfind(" ")] + " --" + title[title.rfind(" ")+1:]
|
||||||
|
if target[0:1] == '.':
|
||||||
|
target = target[1:]
|
||||||
|
refnode['refspecific'] = True
|
||||||
|
return title, target
|
||||||
|
|
||||||
|
class MinioXRefRole(XRefRole):
|
||||||
|
def process_link(self, env: BuildEnvironment, refnode: Element,
|
||||||
|
has_explicit_title: bool, title: str, target: str) -> Tuple[str, str]:
|
||||||
|
# basically what sphinx.domains.python.PyXRefRole does
|
||||||
|
refnode['minio:object'] = env.ref_context.get('minio:object')
|
||||||
|
refnode['minio:module'] = env.ref_context.get('minio:module')
|
||||||
|
refnode['minio:command'] = env.ref_context.get('minio:commannd')
|
||||||
|
if not has_explicit_title:
|
||||||
|
title = title.lstrip('.')
|
||||||
|
target = target.lstrip('~')
|
||||||
|
if title[0:1] == '~':
|
||||||
|
title = title[1:]
|
||||||
|
dot = title.rfind('.')
|
||||||
|
if dot != -1:
|
||||||
|
title = title[dot + 1:]
|
||||||
|
|
||||||
|
# Handle stripping lead path from commands.
|
||||||
|
space = title.rfind(' ')
|
||||||
|
if space != -1:
|
||||||
|
title = title[space + 1:]
|
||||||
|
if target[0:1] == '.':
|
||||||
|
target = target[1:]
|
||||||
|
refnode['refspecific'] = True
|
||||||
|
return title, target
|
||||||
|
|
||||||
|
class MinIODomain(Domain):
|
||||||
|
"""MinIO language domain."""
|
||||||
|
name = 'minio'
|
||||||
|
label = 'MinIO'
|
||||||
|
# if you add a new object type make sure to edit MinioObject.get_index_string
|
||||||
|
object_types = {
|
||||||
|
'data': ObjType(_('data'), 'data'),
|
||||||
|
'kubeconf': ObjType(_('kubeconf'), 'kubeconf'),
|
||||||
|
'userpolicy': ObjType(_('userpolicy'), 'userpolicy'),
|
||||||
|
'command': ObjType(_('command'), 'command'),
|
||||||
|
'subcommand': ObjType(_('subcommand'), 'subcommand'),
|
||||||
|
'flag': ObjType(_('flag'), 'flag'),
|
||||||
|
'mc': ObjType(_('mc'), 'mc'),
|
||||||
|
'mc-cmd': ObjType(_('mc-cmd'), 'mc-cmd'),
|
||||||
|
'mc-cmd-option': ObjType(_('mc-cmd-option'), 'mc-cmd-option'),
|
||||||
|
'policy-action': ObjType(_('policy-action'), 'policy-action'),
|
||||||
|
}
|
||||||
|
directives = {
|
||||||
|
'data': MinioObject,
|
||||||
|
'kubeconf': MinioObject,
|
||||||
|
'userpolicy': MinioObject,
|
||||||
|
'command': MinioCommand,
|
||||||
|
'subcommand': MinioCommand,
|
||||||
|
'flag': MinioObject,
|
||||||
|
'mc': MinioMCCommand,
|
||||||
|
'mc-cmd': MinioMCObject,
|
||||||
|
'policy-action': MinioObject
|
||||||
|
}
|
||||||
|
roles = {
|
||||||
|
'data': MinioXRefRole(),
|
||||||
|
'kubeconf': MinioXRefRole(),
|
||||||
|
'userpolicy': MinioXRefRole(),
|
||||||
|
'command': MinioXRefRole(),
|
||||||
|
'subcommand': MinioXRefRole(),
|
||||||
|
'flag': MinioXRefRole(),
|
||||||
|
'mc': MinioXRefRole(),
|
||||||
|
'mc-cmd': MinioXRefRole(),
|
||||||
|
'mc-cmd-option': MinioCMDOptionXRefRole(),
|
||||||
|
'policy-action': MinioXRefRole(),
|
||||||
|
|
||||||
|
}
|
||||||
|
initial_data = {
|
||||||
|
'objects': {}, # fullname -> docname, node_id, objtype
|
||||||
|
'modules': {}, # modname -> docname, node_id
|
||||||
|
'commands': {},
|
||||||
|
} # type: Dict[str, Dict[str, Tuple[str, str]]]
|
||||||
|
|
||||||
|
@property
|
||||||
|
def objects(self) -> Dict[str, Tuple[str, str, str]]:
|
||||||
|
return self.data.setdefault('objects', {}) # fullname -> docname, node_id, objtype
|
||||||
|
|
||||||
|
def note_object(self, fullname: str, objtype: str, node_id: str,
|
||||||
|
location: Any = None) -> None:
|
||||||
|
if fullname in self.objects:
|
||||||
|
docname = self.objects[fullname][0]
|
||||||
|
logger.warning(__('duplicate %s description of %s, other %s in %s'),
|
||||||
|
objtype, fullname, objtype, docname, location=location)
|
||||||
|
self.objects[fullname] = (self.env.docname, node_id, objtype)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def modules(self) -> Dict[str, Tuple[str, str]]:
|
||||||
|
return self.data.setdefault('modules', {}) # modname -> docname, node_id
|
||||||
|
|
||||||
|
def note_module(self, modname: str, node_id: str) -> None:
|
||||||
|
self.modules[modname] = (self.env.docname, node_id)
|
||||||
|
|
||||||
|
@property
|
||||||
|
def command(self) -> Dict[str, Tuple[str, str]]:
|
||||||
|
return self.data.setdefault('command', {}) # command -> commandname, node_id
|
||||||
|
|
||||||
|
def note_command(self, commandname: str, node_id: str) -> None:
|
||||||
|
self.command[commandname] = (self.env.docname, node_id)
|
||||||
|
|
||||||
|
def clear_doc(self, docname: str) -> None:
|
||||||
|
for fullname, (pkg_docname, node_id, _l) in list(self.objects.items()):
|
||||||
|
if pkg_docname == docname:
|
||||||
|
del self.objects[fullname]
|
||||||
|
for modname, (pkg_docname, node_id) in list(self.modules.items()):
|
||||||
|
if pkg_docname == docname:
|
||||||
|
del self.modules[modname]
|
||||||
|
|
||||||
|
def merge_domaindata(self, docnames: List[str], otherdata: Dict) -> None:
|
||||||
|
# XXX check duplicates
|
||||||
|
for fullname, (fn, node_id, objtype) in otherdata['objects'].items():
|
||||||
|
if fn in docnames:
|
||||||
|
self.objects[fullname] = (fn, node_id, objtype)
|
||||||
|
for mod_name, (pkg_docname, node_id) in otherdata['modules'].items():
|
||||||
|
if pkg_docname in docnames:
|
||||||
|
self.modules[mod_name] = (pkg_docname, node_id)
|
||||||
|
|
||||||
|
def find_obj(self, env: BuildEnvironment, mod_name: str, prefix: str, name: str,
|
||||||
|
typ: str, searchorder: int = 0) -> Tuple[str, Tuple[str, str, str]]:
|
||||||
|
if name[-2:] == '()':
|
||||||
|
name = name[:-2]
|
||||||
|
|
||||||
|
searches = []
|
||||||
|
if mod_name and prefix:
|
||||||
|
searches.append('.'.join([mod_name, prefix, name]))
|
||||||
|
if mod_name:
|
||||||
|
searches.append('.'.join([mod_name, name]))
|
||||||
|
if prefix:
|
||||||
|
searches.append('.'.join([prefix, name]))
|
||||||
|
searches.append(name)
|
||||||
|
|
||||||
|
if searchorder == 0:
|
||||||
|
searches.reverse()
|
||||||
|
|
||||||
|
newname = None
|
||||||
|
for search_name in searches:
|
||||||
|
if search_name in self.objects:
|
||||||
|
newname = search_name
|
||||||
|
|
||||||
|
return newname, self.objects.get(newname)
|
||||||
|
|
||||||
|
def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
|
||||||
|
typ: str, target: str, node: pending_xref, contnode: Element
|
||||||
|
) -> Element:
|
||||||
|
mod_name = node.get('minio:module')
|
||||||
|
prefix = node.get('minio:object')
|
||||||
|
searchorder = 1 if node.hasattr('refspecific') else 0
|
||||||
|
name, obj = self.find_obj(env, mod_name, prefix, target, typ, searchorder)
|
||||||
|
if not obj:
|
||||||
|
return None
|
||||||
|
return make_refnode(builder, fromdocname, obj[0], obj[1], contnode, name)
|
||||||
|
|
||||||
|
def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
|
||||||
|
target: str, node: pending_xref, contnode: Element
|
||||||
|
) -> List[Tuple[str, Element]]:
|
||||||
|
mod_name = node.get('minio:module')
|
||||||
|
prefix = node.get('minio:object')
|
||||||
|
name, obj = self.find_obj(env, mod_name, prefix, target, None, 1)
|
||||||
|
if not obj:
|
||||||
|
return []
|
||||||
|
return [('minio:' + self.role_for_objtype(obj[2]),
|
||||||
|
make_refnode(builder, fromdocname, obj[0], obj[1], contnode, name))]
|
||||||
|
|
||||||
|
def get_objects(self) -> Iterator[Tuple[str, str, str, str, str, int]]:
|
||||||
|
for refname, (docname, node_id, typ) in list(self.objects.items()):
|
||||||
|
yield refname, refname, typ, docname, node_id, 1
|
||||||
|
|
||||||
|
def get_full_qualified_name(self, node: Element) -> str:
|
||||||
|
modname = node.get('minio:module')
|
||||||
|
prefix = node.get('minio:object')
|
||||||
|
target = node.get('reftarget')
|
||||||
|
if target is None:
|
||||||
|
return None
|
||||||
|
else:
|
||||||
|
return '.'.join(filter(None, [modname, prefix, target]))
|
||||||
|
|
||||||
|
|
||||||
|
def setup(app: Sphinx) -> Dict[str, Any]:
|
||||||
|
app.add_domain(MinIODomain)
|
||||||
|
|
||||||
|
return {
|
||||||
|
'version': 'builtin',
|
||||||
|
'env_version': 2,
|
||||||
|
'parallel_read_safe': True,
|
||||||
|
'parallel_write_safe': True,
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user