MinIO 클라이언트

MinIO 클라이언트 (mc)

객체 스토리지를 운영하다 보면 버킷을 만들고, 객체를 올리고 내리고, 상태를 확인하는 일이 반복돼요. MinIO 클라이언트 mc는 파일시스템과 Amazon S3 호환 클라우드 스토리지를 오가며 이런 작업을 해주는 명령줄 도구예요. ls, cat, cp, mirror, diff 같은 유닉스 명령의 현대적 대안 역할을 해요.

출처: AIStor Client — MinIO AIStor Documentation

본문

명령 구문

mc는 다음과 같은 구문을 써요.

mc [ GLOBALFLAGS ] COMMAND --help

명령 이름

일부 운영체제에서는 mc라는 이름의 다른 소프트웨어가 함께 들어 있어요. 그런 경우 AIStor 클라이언트는 mcli라는 명령을 써요. 이 상황이라면 모든 참조 문서에서 mc 대신 mcli를 사용하세요.

Unix 계열 OS에서 명령을 PATH에 넣지 않았다면 ./(점-슬래시)를 붙여 실행해요. 그 경우 바이너리와 같은 폴더에서 ./mc 또는 ./mcli로 실행하면 돼요.

Windows에서 보통은 mc 대신 전체 실행 파일 이름인 mc.exe를 써야 해요.

서버 버전과의 정렬

AIStor 클라이언트는 AIStor 서버와 별도로 릴리스돼요.

최상의 기능·호환성을 위해 서버 릴리스의 달력 날짜에 가장 가까운 클라이언트 버전을 쓰세요.

최신 AIStor 클라이언트는 https://dl.min.io/aistor/mc/release에서 받을 수 있어요.

퀵스타트

1) mc 설치

호스트 머신에 mc 명령줄 도구를 설치해요. 운영체제·환경에 해당하는 탭을 선택하세요.

2) S3 호환 서비스 별칭(alias) 생성

mc alias set 명령으로 AIStor 서버 배포의 호스트명을 추가해요. ACCESS_KEY와 SECRET_KEY를 S3 호환 서비스의 자격 증명으로 바꾸세요. 비밀 키는 최소 8자 이상이어야 해요.

3) 연결 테스트

mc admin info 명령으로 새로 추가한 서버에 대한 연결을 테스트해요.

mc admin info myaistor

성공하면 S3 서비스 정보를 반환해요. 실패하면 다음을 각각 확인해 보세요.

  • 호스트 머신이 S3 서비스 URL에 연결 가능한지 (ping이나 traceroute 사용).
  • 지정한 ACCESS_KEY와 SECRET_KEY가 S3 서비스의 사용자에 대응하는지. 그 사용자는 서비스에 작업을 수행할 권한이 있어야 해요.

명령 빠른 참조

다음 표는 최상위 mc 명령(mc admin 제외) 전체를 정리한 거예요.

명령 설명
mc alias S3 호환 호스트에 연결하고 작업을 실행하는 것을 지원해요.
mc anonymous 버킷과 그 내용에 익명 정책을 설정·제거해요. 인증 없이 정책이 허용한 동작을 수행할 수 있게 하는 공개 접근을 허용해요.
mc batch AIStor 배포에서 하나 이상의 작업을 실행해요.
mc cat 파일·객체 내용을 다른 파일·객체로 연결하거나 STDOUT에 표시해요.
mc cp AIStor 배포로/부터 객체를 복사해요. 소스는 AIStor 또는 로컬 파일시스템일 수 있어요.
mc diff 두 파일시스템 디렉터리 또는 AIStor 버킷 사이의 차이를 계산해요. 누락되거나 크기가 다른 객체만 나열해요. 내용은 비교하지 않아요.
mc du 버킷·폴더의 디스크 사용량을 요약해요. 로컬 파일시스템에도 쓸 수 있어요.
mc encrypt 기본 버킷 서버측 암호화(SSE) 모드를 설정·업데이트·비활성화해요.
mc event 버킷 이벤트 알림을 추가·제거·나열해요.
mc find AIStor 배포의 객체나 파일시스템의 파일을 검색해요.
mc get 대상 S3 배포에서 객체를 로컬 파일시스템으로 다운로드해요.
mc head 인수로 지정된 n줄만큼 객체의 처음 n줄을 표시해요.
mc idp ldap 타사 Active Directory 또는 LDAP IAM 통합 구성을 관리해요.
mc idp openid 타사 OpenID IAM 통합 구성을 관리해요.
mc idp ldap policy 정책과 관련 그룹·사용자 사이의 매핑 관계를 보여줘요.
mc ilm rule AIStor 배포의 객체 라이프사이클 관리 규칙을 관리해요.
mc ilm tier AIStor 배포의 티어링을 관리해요.
mc legalhold 객체 법적 보존(WORM) 설정을 설정·제거·조회해요.
mc license MinIO SUBNET 클러스터 등록을 다뤄요. 배포 등록, 라이선스 정보 표시, 라이선스 키 업데이트.
mc ls AIStor 또는 다른 S3 호환 서비스의 버킷·객체를 나열해요.
mc mb 지정된 경로에 새 버킷이나 디렉터리를 만들어요.
mc mirror AIStor 배포에 내용을 동기화해요. rsync 유틸리티와 비슷해요. 소스로 파일시스템, AIStor 배포, 다른 S3 호환 호스트를 지원해요.
mc mv 소스에서 대상으로 객체를 이동해요. AIStor 배포 사이 또는 같은 배포의 버킷 사이처럼요. 로컬 파일시스템과 AIStor 사이 이동도 지원해요.
mc od 로컬 파일을 지정된 파트 수·파트 크기로 원격 위치에 복사해요. 업로드에 걸린 시간을 출력해요.
mc ping 지정된 대상에서 liveness(생존) 검사를 수행해요.
mc pipe STDIN의 내용을 대상 객체로 스트리밍해요.
mc put 로컬 파일시스템에서 대상 S3 배포의 버킷으로 객체를 업로드해요.
mc rb AIStor 또는 다른 S3 호환 서비스의 버킷 하나 이상을 제거해요. 버킷 내용만 제거하려면 mc rm을 쓰세요.
mc ready 클러스터 상태와 클러스터가 read·write 쿼럼을 유지하는지 확인해요.
mc replicate AIStor의 서버측 버킷 복제를 구성·관리해요. 액티브-액티브 복제 구성과 재동기화를 포함해요.
mc retention 버킷 객체의 WORM 잠금 설정을 구성해요. 버킷의 기본 객체 잠금 설정도 할 수 있어요.
mc rm AIStor 배포 버킷에서 객체를 제거해요. 버킷을 완전히 제거하려면 mc rb를 쓰세요.
mc share AIStor 버킷에 객체를 다운로드·업로드하기 위한 사전 서명(presigned) URL을 관리해요.
mc sql 지정된 AIStor 배포 객체에 SQL 쿼리를 수행하는 S3 Select 인터페이스를 제공해요.
mc stat AIStor 버킷 객체의 정보(객체 메타데이터 포함)를 표시해요. 버킷 메타데이터도 조회할 수 있어요.
mc support 배포 상태·성능 분석, 진단 실행 도구를 제공해요. 생성한 상태 리포트를 MinIO AIStor 엔지니어링 분석용으로 업로드할 수도 있어요.
mc table AIStor Tables Iceberg 웨어하우스, 네임스페이스, 테이블을 관리해요.
mc tag 버킷·객체와 연관된 태그를 추가·제거·나열해요.
mc tree AIStor 버킷 안의 모든 프리픽스를 트리 형태로 나열해요. 각 프리픽스의 모든 객체(버킷 루트 포함)도 나열할 수 있어요.
mc undo 지정된 경로의 PUT·DELETE 연산으로 인한 변경을 되돌려요.
mc update mc 바이너리를 최신 안정 버전으로 업데이트해요.
mc version AIStor 버킷의 버전 관리 상태를 활성화·비활성화·조회해요.
mc watch 지정된 AIStor 버킷 또는 로컬 파일시스템 경로의 이벤트를 감시해요. S3 서비스에는 mc event add로 버킷 이벤트 알림을 구성하세요.

설정 파일

mc는 aliases처럼 특정 종류의 정보를 저장할 때 JSON 형식의 설정 파일을 써요.

Linux·macOS의 기본 설정 파일 위치는 ~/.mc/config.json이에요.

Windows에서는 mc가 특정 환경 변수를 시도해 기본 파일 경로를 만드는데, 변수가 설정되지 않았으면 다음 변수로 넘어가요. 모두 실패하면 오류를 반환해요. mc가 확인하는 순서는 다음과 같아요.

  1. HOME\.mc\config.json
  2. USERPROFILE\.mc\config.json
  3. HOMEDRIVE+HOMEPATH\.mc\config.json

--config-dir 플래그로 config.json 파일 위치를 지정할 수 있어요.

인증서

AIStor 클라이언트는 배포용 인증서와 CA(인증 기관)를 다음 경로에 저장해요.

Linux, macOS 및 기타 Unix 계열 시스템:

~/.mc/certs/ # certificates
~/.mc/certs/CAs/ # Certificate Authorities

Windows 시스템:

C:\Users\[username]\.mc\certs\ # certificates
C:\Users\[username]\.mc\certs\CAs\ # Certificate Authorities

새 별칭을 만들면 AIStor 클라이언트는 피어 인증서를 가져와 공개 키 지문을 계산하고, 배포 인증서를 수락할지 사용자에게 물어요. 인증서를 신뢰하기로 하면 클라이언트는 인증서를 위 CA 경로에 추가해요.

테스트 환경에서는 특정 명령에 --insecure 플래그를 넘겨 인증서 검사를 건너뛸 수 있어요.

전역 옵션

모든 명령이 다음 전역 옵션을 지원해요. 일부 옵션은 환경 변수로도 정의할 수 있어요.

--config-dir

mc가 데이터 저장에 쓰는 JSON 형식 설정 파일의 경로예요.

대신 환경 변수 MC_CONFIG_DIR를 설정할 수 있어요.

--custom-header

별칭 -H

요청에 key:value 형식의 커스텀 HTTP 헤더를 추가해요.

--debug

콘솔에 상세(verbose) 출력을 활성화해요.

예를 들어 다음 연산은 mc ls에 상세 출력을 추가해요.

mc --debug ls play

대신 환경 변수 MC_DEBUG를 설정할 수 있어요.

--dtrace

분산 추적을 위한 OpenTelemetry trace 세부 사항을 활성화해요.

대신 환경 변수 MC_DTRACE를 설정할 수 있어요.

--disable-pager

별칭 --dp

AIStor 클라이언트의 pager 기능을 비활성화해요. 사용하면 출력이 원시(raw) STDOUT으로 인쇄돼요.

--insecure

TLS/SSL 인증서 검증을 끄고, 유효하지 않은 인증서를 가진 서버와의 TLS 연결을 허용해요. 신뢰할 수 없는 S3 호스트에 대해 이 옵션을 쓰면 주의하세요.

대신 환경 변수 MC_INSECURE를 설정할 수 있어요.

--json

JSON lines 형식의 콘솔 출력을 활성화해요.

예를 들어 다음 연산은 mc ls에 JSON Lines 출력을 추가해요.

mc --json ls play

대신 환경 변수 MC_JSON를 설정할 수 있어요.

--no-color

내장 컬러 테마를 끄고, 터미널에 유용한 평범한 출력을 사용해요.

대신 환경 변수 MC_NO_COLOR를 설정할 수 있어요.

--quiet

콘솔 출력을 억제해요.

대신 환경 변수 MC_QUIET를 설정할 수 있어요.

패턴 매칭

mc CLI는 mc cp, mc stat, mc ls 같은 명령에 지정된 S3 경로의 정확한 매칭을 구현해요. S3 API는 *·? 같은 일반적인 '와일드카드' 문자를 객체 이름에 유효한 것으로 취급해요. 재귀 의미를 지원하는 명령에서 mc는 지정된 문자열을 작업 범위를 필터링하는 엄격한 프리픽스 매치로 취급해요.

다음 표는 mc cp를 이용한 패턴 매칭 예시예요.

명령 결과
mc cp aistor-1/data/* aistor-2/data/ 전체 이름이 *인 객체만 복사하거나 오류를 반환해요.
mc cp --recursive aistor-1/data/* aistor-2/data/ 경로·프리픽스 data/*와 일치하는 모든 객체를 복사해요. data/*object는 필터에 일치하지만 data/object*는 일치하지 않아요.
mc cp --recursive aistor-1/data/File- aistor-2/data/ 경로·프리픽스 data/File-과 일치하는 모든 객체를 복사해요.

mc find와 mc mirror 명령은 프리픽스 기반 와일드카드 매칭을 제한적으로 지원해요.

더 알아보기