minio:mc:ko [Command Line Interface Helper]

이 문서는 읽기 전용입니다. 원본을 볼 수는 있지만 바꿀 수는 없습니다. 문제가 있다고 생각하면 관리자에게 문의하세요.
{{tag>[cli minio mc s3 object-storage]}}

====== mc (MinIO Client) ======
''mc''는 local filesystem과 MinIO·Amazon S3 호환 object storage를 ''ls'', ''cp'', ''mirror'', ''find'' 같은 명령으로 다루는 MinIO Client이다.

<note important>
''mc'' 설정에는 access key와 secret key가 저장될 수 있다. 실제 credential을 wiki, shell history, source repository에 기록하지 말고 최소 권한 계정과 안전한 secret 전달 방식을 사용한다.
</note>

===== Summary =====

  * Alias 형식: ''ALIAS/BUCKET/PREFIX/OBJECT''
  * 기본 설정 파일: Linux/macOS는 ''~/.mc/config.json'', Windows는 user profile 아래 ''.mc\config.json''
  * 일부 Linux package는 Midnight Commander의 ''mc''와 이름 충돌을 피하려고 실행 파일을 ''mcli''로 설치한다.
  * MinIO Client와 MinIO Server는 별도로 release된다. 기능 호환성을 위해 release date가 가까운 client를 우선 사용한다.

===== Installation =====

==== Debian / Ubuntu ====

MinIO가 제공하는 DEB package를 설치한다. 이 package의 실행 파일 이름은 ''mcli''이다.

<code bash>
curl -O https://dl.min.io/client/mc/release/linux-amd64/mc.deb
sudo apt install ./mc.deb
mcli --version
</code>

ARM64에서는 URL의 ''linux-amd64''를 ''linux-arm64''로 바꾼다. ''mc'' 이름이 필요하면 아래 standalone binary 방식을 사용한다.

==== RHEL / Fedora ====

MinIO가 제공하는 RPM package를 설치한다. package 설치 환경에서는 ''mcli'' 명령을 사용한다.

<code bash>
sudo dnf install https://dl.min.io/client/mc/release/linux-amd64/mc.rpm
mcli --version
</code>

ARM64에서는 URL의 ''linux-amd64''를 ''linux-arm64''로 바꾼다.

==== Linux standalone binary ====

<code bash>
curl -O https://dl.min.io/client/mc/release/linux-amd64/mc
curl -O https://dl.min.io/client/mc/release/linux-amd64/mc.sha256sum
sha256sum -c mc.sha256sum
chmod +x mc
sudo install -m 0755 mc /usr/local/bin/mc
mc --version
</code>

==== macOS ====

<code bash>
brew install minio/stable/mc
mc --version
</code>

==== Windows ====

MinIO upstream은 공식 Windows binary를 제공한다. 공식 ''winget'' 설치 방법은 제공하지 않으므로 binary를 내려받고 신뢰할 수 있는 ''PATH'' directory에 둔다.

<code powershell>
Invoke-WebRequest -Uri "https://dl.min.io/client/mc/release/windows-amd64/mc.exe" -OutFile ".\mc.exe"
.\mc.exe --version
</code>

==== Container ====

<code bash>
docker pull minio/mc
docker run --rm minio/mc ls play
</code>

다른 endpoint를 등록하려면 interactive shell에서 ''mc alias set''을 실행한다.

<code bash>
docker run --rm -it --entrypoint=/bin/sh minio/mc
</code>

===== Usage =====

<code bash>
mc [GLOBAL_FLAGS] COMMAND [COMMAND_FLAGS] [ARGUMENTS]
</code>

  * ''<color #c3c3c3>**mc**</color> <color #22b14c>[GLOBAL_FLAGS]</color> <color #ff7f27>COMMAND</color> <color #22b14c>[COMMAND_FLAGS]</color> <color #7092be>[ARGUMENTS]</color>''
  * package가 ''mcli''를 설치한 환경에서는 아래 모든 ''mc''를 ''mcli''로 바꾼다.

==== Common global options ====

  * ''<color #22b14c>**--config-dir**</color> <color #7092be>DIRECTORY</color>'', ''<color #22b14c>**-C**</color> <color #7092be>DIRECTORY</color>'': configuration directory 지정. ''MC_CONFIG_DIR''로도 설정할 수 있다.
  * ''<color #22b14c>**--json**</color>'': JSON Lines 형식으로 출력한다.
  * ''<color #22b14c>**--quiet**</color>'', ''<color #22b14c>**-q**</color>'': 일반 출력을 줄인다.
  * ''<color #22b14c>**--no-color**</color>'': ANSI color를 끈다.
  * ''<color #22b14c>**--disable-pager**</color>'', ''<color #22b14c>**--dp**</color>'': pager 없이 raw stdout으로 출력한다.
  * ''<color #22b14c>**--debug**</color>'': debug output을 표시한다.
  * ''<color #22b14c>**--resolve**</color> <color #7092be>HOST[:PORT]=IP</color>'': command별 hostname 해석을 지정한다.
  * ''<color #22b14c>**--insecure**</color>'': TLS certificate 검증을 끈다. production에서는 사용하지 않는다.
  * ''<color #22b14c>**--limit-upload**</color> <color #7092be>RATE</color>'', ''<color #22b14c>**--limit-download**</color> <color #7092be>RATE</color>'': transfer rate를 제한한다.
  * ''<color #22b14c>**--custom-header**</color> <color #7092be>KEY:VALUE</color>'', ''<color #22b14c>**-H**</color> <color #7092be>KEY:VALUE</color>'': HTTP header를 추가한다.
  * ''<color #22b14c>**--help**</color>'', ''<color #22b14c>**-h**</color>'': 도움말을 표시한다.
  * ''<color #22b14c>**--version**</color>'': client version을 표시한다.

===== Commands =====

==== Alias and connection ====

  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**alias list**</color> [<color #7092be>ALIAS</color>]'': 등록된 endpoint alias를 확인한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**alias set**</color> <color #7092be>ALIAS URL ACCESS_KEY SECRET_KEY</color>'': S3-compatible endpoint와 credential을 등록하거나 갱신한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**alias remove**</color> <color #7092be>ALIAS</color>'': 저장한 alias를 제거한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**ping**</color> <color #7092be>ALIAS</color>'': endpoint connectivity를 연속 확인한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**ready**</color> <color #7092be>ALIAS</color>'': cluster의 read/write readiness를 확인한다.

<code bash>
mc alias set local https://minio.example.com "$MINIO_ACCESS_KEY" "$MINIO_SECRET_KEY"
mc alias list local
mc admin info local
</code>

<note tip>
Alias와 credential 저장 방식, certificate directory, environment variable은 [[minio:mc:config:ko|mc configuration]]을 참고한다.
</note>

==== Bucket ====

  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**mb**</color> <color #7092be>ALIAS/BUCKET</color>'': bucket을 만든다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**ls**</color> <color #7092be>ALIAS</color>'': bucket 목록을 표시한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**ls**</color> <color #7092be>ALIAS/BUCKET[/PREFIX]</color>'': object 목록을 표시한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**du**</color> <color #7092be>ALIAS/BUCKET[/PREFIX]</color>'': 사용량을 집계한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**rb**</color> <color #7092be>ALIAS/BUCKET</color>'': 빈 bucket을 삭제한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**version enable**</color> <color #7092be>ALIAS/BUCKET</color>'': bucket versioning을 활성화한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**version suspend**</color> <color #7092be>ALIAS/BUCKET</color>'': 새 version 생성을 중지한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**version info**</color> <color #7092be>ALIAS/BUCKET</color>'': versioning 상태를 확인한다.

<code bash>
mc mb local/backups
mc ls local
mc version enable local/backups
</code>

<note warning>
''mc rb --force''와 ''mc rb --dangerous''는 bucket 또는 여러 bucket을 강제로 제거할 수 있다. 대상 alias와 bucket을 ''mc ls''로 확인한 뒤 사용한다.
</note>

==== Object and file ====

  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**cp**</color> <color #7092be>SOURCE TARGET</color>'': local/remote object를 복사한다. directory는 ''<color #22b14c>**--recursive**</color>''를 사용한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**put**</color> <color #7092be>LOCAL_FILE ALIAS/BUCKET[/OBJECT]</color>'': local file을 upload한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**get**</color> <color #7092be>ALIAS/BUCKET/OBJECT LOCAL_PATH</color>'': object를 local에 저장한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**mv**</color> <color #7092be>SOURCE TARGET</color>'': object를 이동한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**cat**</color> <color #7092be>ALIAS/BUCKET/OBJECT</color>'': object 내용을 stdout으로 출력한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**stat**</color> <color #7092be>ALIAS/BUCKET/OBJECT</color>'': object metadata를 확인한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**find**</color> <color #7092be>ALIAS/BUCKET[/PREFIX]</color> <color #22b14c>[OPTIONS]</color>'': 조건에 맞는 object를 찾는다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**rm**</color> <color #7092be>ALIAS/BUCKET/OBJECT</color>'': object를 삭제한다.

<code bash>
mc cp report.pdf local/archive/
mc cp --recursive ./photos/ local/media/photos/
mc cp local/archive/report.pdf .
mc --json ls local/archive/
mc stat local/archive/report.pdf
</code>

<note warning>
''mc rm --recursive --force''는 prefix 아래 object를 대량 삭제한다. versioned bucket에서는 delete marker와 version 처리도 확인하고, 먼저 ''mc ls --recursive''로 범위를 검증한다.
</note>

==== Synchronization ====

  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**mirror**</color> <color #7092be>SOURCE TARGET</color>'': source를 target에 mirror한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**diff**</color> <color #7092be>FIRST SECOND</color>'': 두 path의 object name, size, date 차이를 표시한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**watch**</color> <color #7092be>ALIAS/BUCKET[/PREFIX]</color>'': object event를 관찰한다.

<code bash>
mc diff ./backup local/backups
mc mirror --overwrite ./backup local/backups
</code>

<note important>
''mc mirror --remove''는 source에 없는 target object를 삭제한다. 실행 전 ''mc diff''로 차이를 확인하고 backup/versioning 정책을 점검한다.
</note>

==== Presigned URL ====

  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**share upload**</color> <color #22b14c>**--expire**</color> <color #7092be>DURATION ALIAS/BUCKET/OBJECT</color>'': upload용 temporary URL을 만든다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**share download**</color> <color #22b14c>**--expire**</color> <color #7092be>DURATION ALIAS/BUCKET/OBJECT</color>'': download용 temporary URL을 만든다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**share list**</color> <color #7092be>ALIAS/BUCKET[/PREFIX]</color>'': 생성한 share URL을 나열한다.

<code bash>
mc share upload --expire 1h local/incoming/report.pdf
mc share download --expire 1h local/archive/report.pdf
</code>

<note warning>
Presigned URL은 만료 전까지 credential처럼 작동할 수 있다. terminal output, chat, ticket, log에 불필요하게 남기지 않는다.
</note>

==== Anonymous access ====

  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**anonymous get**</color> <color #7092be>ALIAS/BUCKET[/PREFIX]</color>'': 현재 anonymous policy를 확인한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**anonymous set**</color> <color #7092be>POLICY ALIAS/BUCKET[/PREFIX]</color>'': ''none'', ''private'', ''public'', ''download'', ''upload'' policy를 지정한다.

<code bash>
mc anonymous get local/public-assets
mc anonymous set download local/public-assets
</code>

<note warning>
''public'', ''download'', ''upload'' policy는 인증되지 않은 접근을 허용한다. 공개가 의도된 bucket/prefix인지 먼저 확인한다.
</note>

==== Administration ====

''admin'' command는 MinIO Server 관리 API를 사용하므로 S3-compatible service 전반에 적용되지 않는다.

  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**admin info**</color> <color #7092be>ALIAS</color>'': server/cluster 정보를 확인한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**admin trace**</color> <color #7092be>ALIAS</color>'': API operation trace를 실시간 표시한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**admin logs**</color> <color #7092be>ALIAS [NODE]</color>'': server log를 확인한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**admin user add**</color> <color #7092be>ALIAS USER SECRET_KEY</color>'': built-in user를 만들거나 password를 갱신한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**admin user info**</color> <color #7092be>ALIAS USER</color>'': user 정보를 확인한다.
  * ''<color #c3c3c3>**mc**</color> <color #ff7f27>**admin policy attach**</color> <color #7092be>ALIAS POLICY</color> <color #22b14c>**--user**</color> <color #7092be>USER</color>'': user에게 policy를 연결한다.

<code bash>
mc admin info local
mc admin user add local app-reader "$MINIO_NEW_USER_SECRET"
mc admin policy attach local readonly --user app-reader
mc admin user info local app-reader
</code>

===== Help =====

현재 작업 환경에는 ''mc''가 설치되어 있지 않아 최신 ''mc --help'' live output은 수록하지 않았다. 설치된 환경에서 아래 명령으로 확인한다.

<code bash>
mc --help
mc COMMAND --help
</code>

++++ mc version --help (기존 기록) |
<code text>
NAME:
  mc version - manage bucket versioning

USAGE:
  mc version COMMAND [COMMAND FLAGS | -h] [ARGUMENTS...]

COMMANDS:
  enable   enable bucket versioning
  suspend  suspend bucket versioning
  info     show bucket versioning status

FLAGS:
  --config-dir value, -C value     path to configuration folder (default: "/home/master/.mc") [$MC_CONFIG_DIR]
  --quiet, -q                      disable progress bar display [$MC_QUIET]
  --disable-pager, --dp            disable mc internal pager and print to raw stdout [$MC_DISABLE_PAGER]
  --no-color                       disable color theme [$MC_NO_COLOR]
  --json                           enable JSON lines formatted output [$MC_JSON]
  --debug                          enable debug output [$MC_DEBUG]
  --resolve value                  resolves HOST[:PORT] to an IP address. Example: minio.local:9000=10.10.75.1 [$MC_RESOLVE]
  --insecure                       disable SSL certificate verification [$MC_INSECURE]
  --limit-upload value             limits uploads to a maximum rate in KiB/s, MiB/s, GiB/s. (default: unlimited) [$MC_LIMIT_UPLOAD]
  --limit-download value           limits downloads to a maximum rate in KiB/s, MiB/s, GiB/s. (default: unlimited) [$MC_LIMIT_DOWNLOAD]
  --custom-header value, -H value  add custom HTTP header to the request. 'key:value' format.
  --help, -h                       show help
</code>
++++

===== Troubleshooting =====

==== mc가 Midnight Commander를 실행함 ====

Linux package가 MinIO Client를 ''mcli''로 설치할 수 있다. 다음 명령으로 어느 executable이 실행되는지 확인한다.

<code bash>
command -v mc
command -v mcli
mcli --version
</code>

==== TLS certificate error ====

정상 CA chain을 구성하거나 조직 CA certificate를 ''~/.mc/certs/CAs/''에 추가한다. ''--insecure''는 certificate 검증을 비활성화하므로 임시 진단 외에는 사용하지 않는다.

==== Access Denied ====

  * ''mc alias list ALIAS''로 endpoint가 맞는지 확인한다.
  * credential에 대상 bucket/prefix action 권한이 있는지 확인한다.
  * ''mc admin policy attach''는 MinIO가 관리하는 user/group용이다. external IdP user는 해당 IdP 정책 흐름을 사용한다.

==== Path-style endpoint가 필요함 ====

일부 S3-compatible endpoint는 path-style lookup이 필요하다.

<code bash>
mc alias set local https://s3.example.com "$MINIO_ACCESS_KEY" "$MINIO_SECRET_KEY" --path on
</code>

===== Compatibility =====

  * ''mc''는 filesystem, MinIO, Amazon S3와 S3-compatible service를 대상으로 한다. 제3자 service는 구현 차이로 일부 command/option이 동작하지 않을 수 있다.
  * ''mc admin''은 MinIO-specific 관리 command이다.
  * current client와 오래된 server 또는 그 반대 조합에서는 새 command가 지원되지 않을 수 있다.
  * DEB/RPM package의 ''mcli''와 standalone/Homebrew의 ''mc''는 같은 client 계열이므로 문서의 executable 이름만 바꾸어 사용한다.

===== Deprecated / Legacy =====

기존 페이지에 기록된 다음 형식은 현재 공식 top-level command 목록과 일치하지 않거나 오타가 있어 보존만 한다.

  * <del>''mc presign put PATH''</del>: upload URL은 ''mc share upload PATH''를 사용한다.
  * <del>''mc presign get PATH''</del>: download URL은 ''mc share download PATH''를 사용한다.
  * <del>''mc anonymouse set AUTHORITY BUCKET''</del>: 오타를 수정한 ''mc anonymous set POLICY ALIAS/BUCKET''을 사용한다.
  * 과거 기록의 ''admin info BUCKET'', ''admin trace BUCKET''에서 첫 대상은 bucket이 아니라 configured server ''ALIAS''이다.

===== See Also =====

  * [[minio:mc:config:ko|mc configuration]]
  * [[https://github.com/minio/mc|MinIO Client source and quickstart]]
  * [[https://docs.min.io/aistor/reference/cli/|MinIO mc command reference]]
  * [[https://dl.min.io/client/mc/release/|MinIO Client downloads]]

===== History =====

  * codex:: 2026-08-04 Migrated the existing page to a language head page and expanded installation, aliases, buckets, objects, synchronization, sharing, access control, administration, safety, and compatibility guidance.

{{indexmenu>.#1|js}}