명령어
모든 명령은 --help로 전체 플래그를 확인할 수 있으며, 설치 후 탭 자동완성을 사용할 수 있습니다.
전역 플래그
| 플래그 | 용도 |
|---|---|
--manager-endpoint | Manager API 엔드포인트. config set으로 저장한 값이 기본값입니다. |
--api-token | API 인증 토큰 |
-v, --verbose | 상세 출력 |
--log-level | debug, info, warn, error, fatal |
--version | 빌드 버전, Git SHA, 빌드 날짜 출력 |
config
CLI의 로컬 설정을 저장합니다.
mass-ctl config set manager-endpoint https://<head-node-ip>:30083
mass-ctl config get manager-endpoint
mass-ctl config unset api-token
키: manager-endpoint, api-token.
login / logout
사용자 인증서를 발급하고 정리합니다. 인증 설정을 참조하세요.
mass-ctl login --username alice
mass-ctl login --username alice --validity-hours 168
mass-ctl logout
machine register
호스트를 등록해 해당 호스트의 모든 사용자가 하나의 장기 인증서로 볼륨을 마운트할 수 있게 합니다.
sudo mass-ctl machine register
| 플래그 | 용도 |
|---|---|
--hostname, --fqdn, --ip | 자동 감지된 값을 재정의합니다 |
--cert-dir | 인증서 저장 위치(기본 /etc/boostx-sds/certs) |
--username, --password, --source | 저장된 세션 대신 요청을 직접 인증합니다 |
mount
볼륨을 POSIX 파일시스템으로 마운트합니다. 볼륨 ID는 대시보드의 볼륨 상세 대화상자에 복사해서 바로 쓸 수 있는 명령과 함께 표시됩니다.
sudo mass-ctl mount --volume-id <volume-id> --mount-point /mnt/data
옵션:
| 플래그 | 설명 |
|---|---|
--volume-id | 마운트할 볼륨 (필수) |
-m, --mount-point | 마운트할 로컬 디렉터리 (필수) |
--read-only | 읽기 전용으로 마운트 |
--allow-other | 명령을 실행한 사용자뿐 아니라 호스트의 모든 사용자가 마운트에 접근할 수 있게 합니다. POSIX 소유권과 권한은 사용자별로 그대로 적용됩니다. 머신 아이덴티티 마운트에는 필수입니다. |
--no-fstab | 재부팅 후 유지되지 않는 임시 마운트. root 없이 마운트하는 유일한 방법입니다. |
--disable-caching | 캐싱 비활성화(기본은 활성) |
--cert, --key, --ca | 설정과 자동 탐색을 무시하고 인증서 경로를 직접 지정 |
재부팅 복구가 기본 동작
마운트하면 재부팅 복구가 함께 등록되므로 호스트 재시작 후 자동으로 복원됩니다. 한 번의 재부팅으로 모든 사용자의 마운트가 함께 복구됩니다. root는 직접 등록하고, 비 root 사용자는 패키지와 함께 설치되는 헬퍼를 통해 등록하므로 관리자 도움 없이 자신의 볼륨을 마운트할 수 있습니다.
명시적으로 임시 마운트가 필요하면 --no-fstab을 사용합니다.
--fstab은 폐기(deprecated)되었으며 현재 아무 동작도 하지 않습니다 — 재부팅 복구 등록이 기본입니다.
이전 버전의 마운트 기록은 패키지 업그레이드 시 자동으로 이전됩니다.
노드의 스토리지 서비스가 재시작되어도 기존 마운트는 스스로 복구됩니다. 마운트가 재설정되므로 클라이언트를 재부팅하지 않아도 다음 접근이 정상 동작합니다.
unmount
sudo mass-ctl unmount --mount-point /mnt/data
dsync
번들로 제공되는 MPI 병렬 데이터 무버로 디렉터리 트리를 마운트된 볼륨에 복사·동기화합니다. 필요한 구성 요소는 클라이언트 패키지에 모두 포함되어 있습니다.
mass-ctl dsync --source /data/legacy --target /mnt/data/incoming
| 플래그 | 설명 |
|---|---|
--source | 복사할 원본 경로 (필수) |
--target | 동기화할 대상 경로 (필수) |
--ncpu | MPI 프로세스 수. 기본값은 노드 CPU 코어 수의 절반입니다 |
--mpi-prefix | 번들 MPI 대신 다른 MPI 설치 경로를 지정 |
실행 중 진행 상황이 표시되고, 모든 데이터 복사가 끝나면 완료 알림이 표시됩니다.
migration
외부 소스의 데이터를 볼륨으로 복사합니다. 데이터 이전을 참조하세요.
mass-ctl migration create --volume-id <id> --source nfs \
--nfs-server 10.0.0.5 --nfs-export /export/data
mass-ctl migration list --phase Copying
mass-ctl migration progress <id> --watch
mass-ctl migration describe <id>
mass-ctl migration cancel <id>
mass-ctl migration summary <id>
소스 유형: s3, nfs, local. 대시보드와 달리 CLI는 S3 소스를 지원합니다.
backup
mass-ctl backup cancel <backup-id>
진행 중인 백업을 취소합니다. 해당 백업은 실패로 표시되고 생성 중이던 임시 데이터가 정리됩니다. 백업 생성·실행·복원은 대시보드에서 수행합니다 — 보호 기능 관리 참조.
connect
오브젝트 스토어 볼륨의 접속 정보를 출력하며, 예제 코드를 함께 볼 수 있습니다.
mass-ctl connect <volume-id>
mass-ctl connect <volume-id> --show-example --language python
env
현재 셸 세션의 I/O를 조정하는 환경 변수를 출력합니다. eval과 함께 사용합니다.
# 대용량 순차 I/O(최대 대역폭) 최적화 — 기본값
eval $(mass-ctl env --bandwidth)
# 메타데이터 집약 워크로드(작은 파일 다수) 최적화
eval $(mass-ctl env --metadata)
# 최적화 없는 표준 모드
eval $(mass-ctl env --standard)
| 모드 | 적합한 워크로드 |
|---|---|
--bandwidth | 대용량 파일 읽기·쓰기, AI 학습 데이터 |
--metadata | 작은 파일 다수, 체크포인팅 |
--standard | 최적화 없는 기본 동작 |
--mode 옵션에 값을 넘기는 방식이 아니라 불리언 플래그입니다.
completion
mass-ctl completion bash
mass-ctl completion zsh
mass-ctl completion fish
mass-ctl completion powershell
bash와 zsh 자동완성은 패키지가 자동으로 설치합니다.
관리 명령
스토리지·아이덴티티 관리(volumegroup, volume, identity, policy, node, drive, audit,
cluster, auth-config, reset-admin-password)는 클라이언트 패키지에 포함되지 않습니다. 해당 명령은
어플라이언스에 설치되는 관리용 빌드에 포함됩니다.
일상적인 관리는 대시보드를 사용하십시오 — 사용자 가이드 참조.
attach와 status는 하위 호환을 위해 남아 있으며 폐기 예정입니다. status 대신 대시보드 또는 관리용
빌드의 volume get을 사용하십시오.