mc configuration

MinIO Client의 alias, credential, certificate, runtime option을 안전하게 구성하는 방법을 설명한다.

• Linux/macOS 기본 configuration file: ~/.mc/config.json
• Windows 기본 configuration file: %HOME%\.mc\config.json, %USERPROFILE%\.mc\config.json 또는 %HOMEDRIVE%%HOMEPATH%\.mc\config.json
• custom directory: –config-dir DIRECTORY 또는 MC_CONFIG_DIR
• endpoint 등록은 JSON 직접 편집보다 mc alias set을 우선한다.

~/.mc/config.json
~/.mc/certs/
~/.mc/certs/CAs/

mc는 다음 user profile 변수를 순서대로 확인한다.

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

mc --config-dir /secure/path/mc alias list
MC_CONFIG_DIR=/secure/path/mc mc alias list

MC_CONFIG_DIR에는 file이 아니라 config.json을 담을 directory를 지정한다.

• mc alias set ALIAS URL ACCESS_KEY SECRET_KEY [OPTIONS]

mc alias set local https://minio.example.com "$MINIO_ACCESS_KEY" "$MINIO_SECRET_KEY"
mc alias list local

같은 alias가 이미 있으면 새 URL과 credential로 갱신된다.

• –api S3v4: 기본값이며 일반적으로 권장한다.
• –api S3v2: legacy S3-compatible service가 명시적으로 요구할 때만 사용한다.
• –path auto: client가 bucket lookup 방식을 판단하는 기본값이다.
• –path on: path-style URL을 강제한다.
• –path off: virtual-host-style URL을 강제한다.

mc alias set local https://s3.example.com "$MINIO_ACCESS_KEY" "$MINIO_SECRET_KEY" --api S3v4 --path on

mc alias list local
mc alias export local > local.alias.json
mc alias import local < local.alias.json
mc alias remove local

Alias object에는 다음 핵심 field가 사용된다.

• url: S3-compatible endpoint URL
• accessKey: access key
• secretKey: secret key
• api: S3v4 또는 legacy S3v2 signature
• path: auto, on, off bucket lookup mode

아래는 구조 설명용 redacted example이다. 실제 값은 mc alias set으로 작성한다.

{
  "url": "https://minio.example.com",
  "accessKey": "REDACTED",
  "secretKey": "REDACTED",
  "api": "S3v4",
  "path": "auto"
}

MC_HOST_ALIAS 형식의 environment variable로 configuration file에 alias를 영구 저장하지 않고 script용 endpoint를 지정할 수 있다. suffix의 ALIAS를 실제 alias name으로 바꾼다.

export MC_HOST_ci="https://${MINIO_ACCESS_KEY}:${MINIO_SECRET_KEY}@minio.example.com"
mc ls ci
unset MC_HOST_ci

• MC_CONFIG_DIR: configuration directory
• MC_JSON: JSON Lines output 활성화
• MC_QUIET: output 축소
• MC_NO_COLOR: color 비활성화
• MC_DISABLE_PAGER: internal pager 비활성화
• MC_DEBUG: debug output 활성화
• MC_INSECURE: TLS certificate 검증 비활성화
• MC_LIMIT_UPLOAD, MC_LIMIT_DOWNLOAD: transfer rate limit

새 alias를 등록할 때 client는 server certificate fingerprint의 신뢰 여부를 물을 수 있다. 신뢰한 CA는 Unix-like system에서 ~/.mc/certs/CAs/ 아래에 저장된다.

조직 내부 CA를 사용할 때는 검증된 CA certificate를 CA directory에 배치하고 정상 certificate chain으로 연결한다.

chmod 700 ~/.mc
chmod 600 ~/.mc/config.json

• backup은 encrypted storage에 보관한다.
• 다른 host로 옮길 때 long-lived root credential보다 별도 최소 권한 credential을 재발급한다.
• credential 노출이 의심되면 configuration file만 지우는 것으로 끝내지 말고 server에서 key를 rotate/revoke한다.

mc alias list local
mc ls local
mc admin info local

• alias list: URL, API signature, path mode를 확인한다.
• ls: S3 data-plane authentication과 list permission을 확인한다.
• admin info: MinIO endpoint에서 admin permission과 관리 API 연결을 확인한다.

MC_CONFIG_DIR와 command line의 –config-dir 사용 여부를 확인한다. service account, container, sudo는 interactive user와 home directory가 다를 수 있다.

Alias 존재 여부와 authorization은 별개다. credential이 bucket/prefix에 필요한 S3 action을 허용하는지 server policy를 확인한다.

DNS와 certificate SAN을 수정한다. –resolve HOST[:PORT]=IP로 진단할 수 있지만 request hostname과 certificate 검증 관계를 유지해야 한다.

mc --resolve minio.example.com:443=192.0.2.10 ls local

• mc (MinIO Client)
• mc alias set reference
• MinIO Client settings

• codex:: 2026-08-04 Added configuration guidance for locations, aliases, fields, environment variables, certificates, permissions, validation, and troubleshooting.