VMs CLI
소개
VMs CLI는 TerraMaster VMs 가상화 애플리케이션의 명령줄 관리 도구로, 웹 관리 인터페이스와 동일한 조회 및 운영 관리 기능을 제공합니다. CLI는 로컬 unix socket을 통해 VMs 서비스와 통신하며, 표준화된 명령 인터페이스와 JSON 출력 형식을 채택하므로 스크립트, 자동화 운영 및 2차 개발 워크플로에 통합할 수 있습니다.
주요 특징
- 바로 사용 가능: VMs 애플리케이션과 함께 설치되며 추가 설치가 필요하지 않습니다
- 유연한 호출 방식: 로컬 터미널, 원격 SSH, 스크립트, AI 도구 등 다양한 호출 경로를 지원합니다
- 대화형 및 비대화형 이중 모드: 관리자의 일상 유지보수와 스크립트 및 자동화 작업 모두에 적합합니다
- JSON 출력 지원: 프로그램 파싱과 자동화 통합에 용이합니다
- 로컬 통신: 로컬 unix socket을 통해서만 VMs 서비스와 통신하며 외부에 포트를 개방하지 않습니다
- 위험 작업 2차 확인: 가상 머신 삭제, 네트워크 삭제 등의 작업은 기본적으로 확인을 요구합니다
빠른 시작
# 在终端中执行（可通过本地终端、SSH、脚本、AI 工具等任意命令行途径）
vms --help
# 查看虚拟机列表
vms vm list
# 查看虚拟机详情
vms vm get <id>
# 以 JSON 格式输出（便于脚本解析）
vms vm list --json
vms vm list 출력 예시:
NAME GUEST ID STATUS VCPU NUM VRAM SIZE IP
145 09fd98ee-4e2d-4c7a-a95c-8bacab80d322 shutdown 4 2097152 -
win10 9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1 shutdown 4 2097152 -
1454486 5a0391f2-c545-45eb-8eed-0a104972229b shutdown 4 2097152 -
win101 32ee5a74-de8b-47a9-959d-1725c881ceab shutdown 4 2097152 -
전역 옵션
다음 옵션은 모든 명령에 적용됩니다:
| 옵션 | 단축 | 설명 |
|---|---|---|
--help | -h | 명령 도움말 정보를 표시합니다 |
--version | -v | 버전 번호를 표시합니다 (--json과 함께 구조화된 정보를 출력할 수 있습니다) |
--json | - | JSON 형식으로 출력합니다 |
--yes | -y | 위험 작업의 확인 프롬프트를 건너뜁니다 (비대화형 모드에서는 필수) |
--debug | - | 디버그 출력을 활성화하고 상세 실행 과정을 표시합니다 |
--socket <path> | - | VMs unix socket 경로, 기본값 /var/api/VMs.sock |
--timeout <duration> | - | 요청 타임아웃 시간, 기본값 30s |
버전 정보 예시
vms --version
vms CLI v1.0.058
vms --version --json
{
"build": "20260911",
"cli_version": "v1.0.058"
}
실행 환경
VMs CLI는 VMs 애플리케이션과 함께 설치됩니다. 애플리케이션을 활성화하면 CLI가 시스템 기본 PATH 디렉터리에 링크되며, SSH 로그인 후 바로 사용할 수 있습니다.
| 항목 | 설명 |
|---|---|
| CLI 파일 | /Volume1/@apps/VMs/bin/vms |
| 명령 경로 | /usr/local/sbin/vms (시스템 PATH에 등록됨) |
| 통신 방식 | 로컬 unix socket, 기본값 /var/api/VMs.sock |
| 대상 | 본 기기에 로그인한 관리자 |
주의 사항:
- CLI는 본 기기의 가상 머신을 관리하기 위한 것이며, CLI를 통한 다른 기기의 원격 관리는 지원하지 않습니다.
- 백엔드는 항상 HTTP 200을 반환하며, 명령 성공 여부는 응답 본문의
code필드로 판단하고 CLI는 이에 따라 종료 코드로 변환합니다. - 위험 작업(가상 머신 삭제, 네트워크 삭제, 이미지 삭제, 스토리지 삭제)은 대화형 모드에서 확인을 요구하며, 비대화형 모드에서는
--yes를 명시적으로 전달해야 합니다.
명령 요약표
다음은 모든 vms 명령의 빠른 참조 요약입니다:
| 상위 명령 | 하위 명령 | 기능 설명 | 확인 필요 | 고위험 |
|---|---|---|---|---|
| vms | --version | 버전 정보 표시 | 아니오 | 아니오 |
| vms vm | list | 모든 가상 머신 나열 | 아니오 | 아니오 |
| vms vm | get | 지정한 가상 머신의 상세 정보 보기 | 아니오 | 아니오 |
| vms vm | list-resource | 가상 머신 생성에 사용 가능한 리소스 나열 | 아니오 | 아니오 |
| vms vm | logs | 가상 머신의 작업 로그 보기 | 아니오 | 아니오 |
| vms vm | poweron | 가상 머신 시작 | 아니오 | 아니오 |
| vms vm | poweroff | 가상 머신 종료(정상 종료) | 예 | 아니오 |
| vms vm | force-poweroff | 가상 머신 강제 종료 | 예 | ✅ |
| vms vm | reboot | 가상 머신 재시작 | 아니오 | 아니오 |
| vms vm | pause | 가상 머신 일시 중지 | 아니오 | 아니오 |
| vms vm | resume | 일시 중지된 가상 머신 재개 | 아니오 | 아니오 |
| vms vm | autorun | 자동 시작 설정 | 아니오 | 아니오 |
| vms vm | clone | 가상 머신 복제 | 아니오 | 아니오 |
| vms vm | export | 가상 머신을 OVA 파일로 내보내기 | 아니오 | 아니오 |
| vms vm | delete | 가상 머신 삭제 | 예 | ✅ |
| vms vm disk | list | 가상 머신의 가상 하드 디스크 보기 | 아니오 | 아니오 |
| vms vm snapshot | list | 가상 머신의 스냅샷 나열 | 아니오 | 아니오 |
| vms vm snapshot | create | 스냅샷 생성 | 아니오 | 아니오 |
| vms vm snapshot | edit | 스냅샷 설명과 잠금 상태 편집 | 아니오 | 아니오 |
| vms vm snapshot | config | 스냅샷에 저장된 가상 머신 구성 보기 | 아니오 | 아니오 |
| vms vm snapshot | consistency | 스냅샷 일관성 미리보기 | 아니오 | 아니오 |
| vms vm | link | VNC 콘솔 연결 정보 가져오기 | 아니오 | 아니오 |
| vms network | list | 가상 네트워크 나열 | 아니오 | 아니오 |
| vms network | get | 가상 네트워크 상세 정보 보기 | 아니오 | 아니오 |
| vms network | create | 가상 네트워크 생성 | 아니오 | 아니오 |
| vms network | update | 가상 네트워크 업데이트 | 아니오 | 아니오 |
| vms network | delete | 가상 네트워크 삭제 | 예 | ✅ |
| vms network | list-interfaces | 지정한 유형의 네트워크 인터페이스 나열 | 아니오 | 아니오 |
| vms network | list-vnics | 네트워크의 가상 NIC 나열 | 아니오 | 아니오 |
| vms network | ovsinfo | OVS 활성화 여부 보기 | 아니오 | 아니오 |
| vms image | list | 이미지 나열 | 아니오 | 아니오 |
| vms image | edit | 이미지 정보 편집 | 아니오 | 아니오 |
| vms image | delete | 이미지 삭제 | 예 | ✅ |
| vms image | list-vms | 이 이미지를 사용하는 가상 머신 보기 | 아니오 | 아니오 |
| vms repo | list | 스토리지 나열 | 아니오 | 아니오 |
| vms repo | get | 스토리지 상세 정보 보기 | 아니오 | 아니오 |
| vms repo | update | 스토리지 구성 업데이트 | 아니오 | 아니오 |
| vms repo | delete | 스토리지 삭제 | 예 | ✅ |
| vms repo | list-volumes | 사용 가능한 볼륨 나열 | 아니오 | 아니오 |
| vms repo | list-vms | 스토리지 내의 가상 머신 나열 | 아니오 | 아니오 |
| vms repo | check-running | 스토리지에서 실행 중인 가상 머신 확인 | 아니오 | 아니오 |
| vms repo | whether-exist-data | 스토리지 내에 데이터가 존재하는지 확인 | 아니오 | 아니오 |
| vms setting | get | 전역 설정 보기 | 아니오 | 아니오 |
| vms collectd | hostinfo | 호스트 모니터링 정보 보기 | 아니오 | 아니오 |
| vms collectd | vminfo | 가상 머신 모니터링 정보 보기 | 아니오 | 아니오 |
| vms collectd | storageinfo | 스토리지 모니터링 정보 보기 | 아니오 | 아니오 |
명령 참조
명령의 <id>는 가상 머신 ID로, 가상 머신 목록 출력의 GUEST ID에 해당합니다. <network_id>, <image_id>, <repo_id>도 마찬가지이며, 각각 vms network list, vms image list, vms repo list로 가져올 수 있습니다.
출력 예시에 대하여:
vms의 테이블 출력은 너무 긴 필드 값을 고정 너비로 잘라냅니다(줄임표로 끝나며 터미널 너비와 무관합니다). 예를 들어 가상 머신 구성의VDISKS,VNICS,ISO IMAGES및 이미지 이름입니다. 따라서 본 문서에서는 긴 필드를 다루는 명령에 대해 완전한--json출력 예시를 제공하고, 나머지 명령에는 테이블 출력 예시를 제공합니다. 스크립트에서 처리할 때도--json을 통일적으로 사용할 것을 권장합니다.
I. 가상 머신 조회
vms vm list – 가상 머신 나열
본 기기의 모든 가상 머신과 기본 상태를 나열합니다.
vms vm list [--limit N] [--offset N] [--json]
--limit,--offset은 페이징 파라미터입니다- 출력 열: 이름, 가상 머신 ID, 실행 상태, CPU 코어 수, 메모리 크기(단위 KB), IP 주소
출력 예시:
NAME GUEST ID STATUS VCPU NUM VRAM SIZE IP
145 09fd98ee-4e2d-4c7a-a95c-8bacab80d322 shutdown 4 2097152 -
win10 9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1 shutdown 4 2097152 -
1454486 5a0391f2-c545-45eb-8eed-0a104972229b shutdown 4 2097152 -
win101 32ee5a74-de8b-47a9-959d-1725c881ceab shutdown 4 2097152 -
STATUS 일반적인 값:
| 상태 | 설명 |
|---|---|
| running | 실행 중 |
| shutdown | 종료됨 |
| saved | 일시 중지됨(실행 상태가 디스크에 저장됨) |
vms vm get – 가상 머신 상세 정보 보기
지정한 가상 머신의 전체 구성과 실행 상태를 봅니다.
vms vm get <id> --json
- 출력에는 가상 머신의 모든 구성 및 실행 상태 필드가 포함됩니다
- 설명 없음, IP 없음 등의 빈 값은 빈 문자열로 표시됩니다
- 가상 머신이 존재하지 않으면 명령은 오류를 반환하고 오류 메시지를 출력합니다
출력 예시:
{
"iso_images": [
"c93083a5-2b39-4f32-b19f-1ad97c6b4de4",
"9b3f2fdd-9173-4611-a84c-0cc9ce88293c"
],
"image_paths": [
"",
""
],
"autorun": 0,
"boot_from": "cdrom",
"bios": "bios",
"kb_layout": "en-us",
"serial_console": true,
"usb_version": 2,
"usb_device_name": [
"USB - Integrated Technology Express, Inc. Disk 2.0"
],
"usbs": [
":3:3:048d:1234"
],
"use_ovmf": false,
"vnics": [
{
"prefer_sriov": false,
"vnic_type": 3,
"mac": "1a:e2:ae:95:4a:51",
"network_id": "b364a1ec-f60c-4971-9ea2-f7a002f09fa3",
"virtual_interface_id": "fe972ef5-b066-4967-89fa-8e85e43c8808"
}
],
"operating_system_type": 0,
"vdisks": [
{
"vdisk_mode": 1,
"name": "",
"unmap": false,
"iops_enable": false,
"dev_limit": 0,
"dev_reservation": 0,
"dev_weight": 3,
"vdisk_size": 1024,
"idx": 0,
"vdisk_id": "f4ed4eae-1512-4273-963b-79ebd93a0932",
"disk_image_type": "",
"disk_image_id": ""
}
],
"name": "win10",
"vcpu_num": 4,
"vcpu_usage": 0,
"vram_size": 2097152,
"video_card": "vga",
"machine_type": "1",
"cpu_weight": 3,
"ip": "",
"desc": "",
"cpu_passthru": false,
"hyperv_enlighten": true,
"cpu_pin_num": 0,
"repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6",
"repo_name": "VM-Storage01",
"poweron_after_create": false,
"guest_id": "9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1",
"increaseAllocatedSize": 0,
"host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
"host_name": "",
"snap_num": 0,
"has_guest_agent": false,
"status": "shutdown",
"status_code": 0,
"status_desc": "",
"host_ram_size": 0,
"total_throughput": 0,
"total_iops": 0,
"total_io_latency": 0,
"total_rx_bytes": 0,
"total_tx_bytes": 0,
"memory_usage": 0,
"cpu_usage": 0,
"vm_status_progress": 0
}
vms vm list-resource – 가상 머신 생성에 사용 가능한 리소스 나열
호스트가 제공할 수 있는 펌웨어 유형, 이미지, CPU, 메모리, 네트워크, 스토리지, 패스스루 가능 장치 등의 리소스를 확인하여 가상 머신 생성 전 평가에 사용합니다.
vms vm list-resource --json
반환 필드: max_cpu_num, max_ram_size, usbs, pci_devices, networks, repos, images, video_cards, firmware, keyboard_layout.
출력 예시:
{
"max_cpu_num": 4,
"max_ram_size": 16503336960,
"usbs": [
{
"product_name": "4-Port USB 2.0 Hub",
"usb_id": ":3:3:0x0bda:0x5423",
"version": ""
},
{
"product_name": "4-Port USB 3.2 Hub",
"usb_id": ":4:2:0x0bda:0x0423",
"version": ""
},
{
"product_name": "Flash Drive",
"usb_id": ":3:2:0x058f:0x6387",
"version": ""
}
],
"pci_devices": [
{
"device_name": "",
"bdf": "0000:02:00.0",
"vendor_id": "0x10ec",
"product_id": "0x8126",
"class_id": "0x020000",
"iommu_group": 13,
"iommu_group_bdfs": [
"0x0000:0x02:0x00.0x0"
],
"driver": "r8169",
"type": "Network Controller"
},
{
"device_name": "",
"bdf": "0000:00:0d.0",
"vendor_id": "0x8086",
"product_id": "0x464e",
"class_id": "0x0c0330",
"iommu_group": 2,
"iommu_group_bdfs": [
"0x0000:0x00:0x0d.0x0"
],
"driver": "xhci_hcd",
"type": "USB Controller"
},
{
"device_name": "",
"bdf": "0000:03:00.0",
"vendor_id": "0x10ec",
"product_id": "0x8126",
"class_id": "0x020000",
"iommu_group": 14,
"iommu_group_bdfs": [
"0x0000:0x03:0x00.0x0"
],
"driver": "r8169",
"type": "Network Controller"
},
{
"device_name": "",
"bdf": "0000:00:14.0",
"vendor_id": "0x8086",
"product_id": "0x54ed",
"class_id": "0x0c0330",
"iommu_group": 3,
"iommu_group_bdfs": [
"0x0000:0x00:0x14.0x2",
"0x0000:0x00:0x14.0x0"
],
"driver": "xhci_hcd",
"type": "USB Controller"
},
{
"device_name": "",
"bdf": "0000:00:14.2",
"vendor_id": "0x8086",
"product_id": "0x54ef",
"class_id": "0x050000",
"iommu_group": 3,
"iommu_group_bdfs": [
"0x0000:0x00:0x14.0x2",
"0x0000:0x00:0x14.0x0"
],
"driver": "",
"type": "IOMMU Group Device"
}
],
"networks": [
{
"name": "VM-Network04",
"network_id": "ce9807c9-47b3-4258-9a80-ea8db1fd785d",
"support_sriov": false
},
{
"name": "VM-Network05",
"network_id": "b56c2f7b-e3f0-4b68-8a3b-245c90a8f8b5",
"support_sriov": false
},
{
"name": "VM-Network01",
"network_id": "b364a1ec-f60c-4971-9ea2-f7a002f09fa3",
"support_sriov": false
},
{
"name": "VM-Network02",
"network_id": "6c9fffd8-c7c4-4968-9b50-6890a640ec94",
"support_sriov": false
},
{
"name": "VM-Network03",
"network_id": "4c05b2a2-dd49-4588-ac5c-64975c92d2d3",
"support_sriov": false
}
],
"repos": [
{
"name": "VM-Storage01",
"free_size": 941970767872,
"repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6",
"volume_size": 1099511627776,
"file_system": "btrfs",
"status": ""
},
{
"name": "VM-Storage02",
"free_size": 445785296896,
"repo_id": "517571ba-f7f7-49e1-9a62-7eb6ddfd9c78",
"volume_size": 536870912000,
"file_system": "btrfs",
"status": ""
}
],
"images": [
{
"id": "c93083a5-2b39-4f32-b19f-1ad97c6b4de4",
"name": "cn_windows_10_consumer_editions_version_1909_updated_jan_2020_x86_dvd_9c50652f",
"status": "available",
"type": "iso",
"used_size": 3884539904
},
{
"id": "9b3f2fdd-9173-4611-a84c-0cc9ce88293c",
"name": "virtio-win-0.1.285pro",
"status": "available",
"type": "iso",
"used_size": 789645312
},
{
"id": "efd6da18-9475-44cf-8fb0-e2513421e68a",
"name": "haos_ova-18.2",
"status": "available",
"type": "qcow2",
"used_size": 1091698688,
"virtual_size": 34359738368
},
{
"id": "cb9d929a-d673-4e46-ac86-9488bbef19b9",
"name": "cn_windows_11_consumer_editions_version_21h2_updated_july_2022_x64_dvd_50ad4acf",
"status": "available",
"type": "iso",
"used_size": 5858816000
}
],
"video_cards": [
"cirrus",
"vga",
"vmvga"
],
"firmware": [
"Legacy BIOS",
"UEFI"
],
"keyboard_layout": [
"fr-be",
"ar",
"bepo",
"cz",
"da",
"de",
"de-ch",
"en-gb",
"en-us",
"es",
"et",
"fo",
"fr",
"fr-be",
"fr-ca",
"fr-ch",
"hr",
"hu",
"is",
"it",
"ja",
"lt",
"lv",
"mk",
"nl",
"nl-be",
"no",
"pl",
"pt",
"pt-br",
"ru",
"sl",
"sv",
"th",
"tr"
]
}
vms vm logs – 가상 머신 작업 로그 보기
지정한 가상 머신과 관련된 작업 로그(전원 켜기/끄기, 스냅샷, 편집, 가져오기/내보내기 등)를 봅니다.
vms vm logs <id> --json [--limit N] [--desc]
--limit은 반환 건수를 지정하며 기본값은 50입니다--desc는 시간 역순으로 정렬합니다(기본 활성화)- 각 로그에는 시간, 레벨, 분류, 작업 사용자 및 이벤트 설명이 포함되며 이벤트 설명은 전체 텍스트입니다
- 이벤트 설명(
event)은 VMs 서비스가 장치의 시스템 언어에 따라 현지화하여 출력하며, 본 문서의 예시는 통일적으로 영어를 사용합니다
출력 예시:
[
{
"id": 0,
"level": "Info",
"time": "2026-09-02T11:44:09.176535374+08:00",
"category": "vm",
"user": "system",
"event": "Virtual machine(win10) shutdown successfully"
},
{
"id": 0,
"level": "Info",
"time": "2026-09-02T11:43:10.597187659+08:00",
"category": "vm",
"user": "system",
"event": "Virtual machine(win10) started successfully"
},
{
"id": 0,
"level": "Info",
"time": "2026-09-02T11:40:32.74904922+08:00",
"category": "vm",
"user": "system",
"event": "Virtual machine(win10) shutdown successfully"
},
{
"id": 0,
"level": "Info",
"time": "2026-09-02T11:39:55.916718004+08:00",
"category": "vm",
"user": "system",
"event": "Virtual machine(win10) started successfully"
},
{
"id": 0,
"level": "Info",
"time": "2026-09-02T11:39:43.341421576+08:00",
"category": "vm",
"user": "system",
"event": "Virtual machine(win10) shutdown successfully"
},
{
"id": 0,
"level": "Info",
"time": "2026-09-02T11:38:31.518259486+08:00",
"category": "vm",
"user": "system",
"event": "Virtual machine(win10) shutdown successfully"
},
{
"id": 0,
"level": "Info",
"time": "2026-09-02T11:38:07.98065689+08:00",
"category": "vm",
"user": "system",
"event": "Virtual machine(win10) started successfully"
},
{
"id": 0,
"level": "Error",
"time": "2026-09-02T11:32:35.01952111+08:00",
"category": "vm",
"user": "system",
"event": "Virtual machine (win10) export failed (Error:stat : no such file or directory)"
}
]
II. 가상 머신 전원 관리
vms vm poweron – 가상 머신 시작
vms vm poweron <id>
- 가상 머신은 종료 상태여야 하며, 그렇지 않으면 상태 충돌 오류를 반환합니다
- 출력:
VM powered on: <id>
vms vm poweroff – 가상 머신 종료
가상 머신에 정상 종료 요청을 보내 시스템을 정상적으로 종료시킵니다.
vms vm poweroff <id> [--yes]
- 위험 작업에 해당합니다: 대화형 모드에서는 확인을 요구하며, 비대화형 모드에서는
--yes를 추가해야 합니다 - 가상 머신은 실행 중 상태여야 하며, 그렇지 않으면 상태 충돌 오류를 반환합니다
대화형 모드 확인 프롬프트:
This action will powered off VM "9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1". Do you want to continue? [y/N]:
- 출력:
VM powered off: <id>
vms vm force-poweroff – 가상 머신 강제 종료(고위험)
가상 머신을 강제 종료하며, 전원을 바로 차단하는 것과 같습니다.
vms vm force-poweroff <id> [--yes]
- 고위험 작업에 해당합니다: 대화형 모드에서는 확인을 요구하며, 비대화형 모드에서는
--yes를 추가해야 합니다 - 가상 머신 내 데이터가 손실될 수 있으므로 가상 머신이 응답하지 않을 때만 사용할 것을 권장합니다
대화형 모드 확인 프롬프트:
This action will force powered off VM "9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1". Do you want to continue? [y/N]:
- 출력:
VM force powered off: <id>
vms vm reboot – 가상 머신 재시작
vms vm reboot <id>
- 출력:
VM rebooted: <id>
vms vm pause – 가상 머신 일시 중지
가상 머신의 실행 상태를 동결하고 현재 상태를 디스크에 저장합니다.
vms vm pause <id>
- 가상 머신은 실행 중 상태여야 하며, 그렇지 않으면 상태 충돌 오류를 반환합니다
- 일시 중지 후 가상 머신 상태는
saved로 표시됩니다 - 출력:
VM paused: <id>
vms vm resume – 가상 머신 재개
가상 머신을 일시 중지 상태에서 실행 상태로 되돌립니다.
vms vm resume <id>
- 가상 머신은 일시 중지 상태여야 하며, 그렇지 않으면 상태 충돌 오류를 반환합니다
- 출력:
VM resumed: <id>
vms vm autorun – 자동 시작 설정
가상 머신이 호스트 시작과 함께 자동으로 부팅될지 여부를 설정합니다.
vms vm autorun <id> <true|false>
- 두 번째 파라미터는
true또는false여야 합니다 - 명령은 현재 구성을 읽고 자동 시작 스위치만 수정하며 다른 구성에는 영향을 미치지 않습니다
- 출력:
Auto-start enabled for VM <id>또는Auto-start disabled for VM <id>
III. 가상 머신 복제, 내보내기 및 삭제
vms vm clone – 가상 머신 복제
기존 가상 머신을 템플릿으로 하여 새로운 가상 머신을 복사합니다.
vms vm clone --body '{"guest_id":"<source_id>","name":"my-clone"}'
vms vm clone --file clone.json
- 요청 본문에서
guest_id는 원본 가상 머신 ID,name(또는guest_name)은 새 가상 머신 이름입니다 - 원본 가상 머신은 종료 상태여야 합니다
--body는 JSON 문자열로 요청 본문을 직접 전달하고,--file은 파일에서 요청 본문을 읽습니다
vms vm export – 가상 머신 내보내기
가상 머신을 OVA 파일로 내보내 백업하거나 다른 가상화 플랫폼으로 마이그레이션하기 쉽게 합니다.
vms vm export --body '{"guest_id":"<source_id>","target_ova_path":"/Volume1/export/my-vm.ova"}'
vms vm export --file export.json
- 요청 본문에서
guest_id는 원본 가상 머신 ID,target_ova_path는 대상 파일 경로,ova_mode는 선택적 VMware 호환 모드입니다 - 원본 가상 머신은 종료 상태여야 합니다
- 내보내기는 시간이 오래 걸리는 작업이며 대용량 가상 머신은 시간이 더 오래 걸립니다
vms vm delete – 가상 머신 삭제(고위험)
가상 머신을 영구적으로 삭제합니다.
vms vm delete <id> [--yes]
- 고위험 작업에 해당합니다: 대화형 모드에서는 확인을 요구하며, 비대화형 모드에서는
--yes를 추가해야 합니다 - 삭제 후에는 복구할 수 없으므로 가상 머신 내 데이터가 백업되었는지 미리 확인하십시오
대화형 모드 확인 프롬프트:
This action will permanently delete VM "5a0391f2-c545-45eb-8eed-0a104972229b". Do you want to continue? [y/N]:
- 출력:
VM deleted: <id>
IV. 가상 하드 디스크
vms vm disk list – 가상 하드 디스크 보기
지정한 가상 머신의 모든 가상 하드 디스크를 나열합니다.
vms vm disk list <id> [--json]
출력 예시:
NAME VDISK ID VDISK SIZE VDISK MODE IDX
- f4ed4eae-1512-4273-963b-79ebd93a0932 1024 1 0
VDISK MODE는 가상 하드 디스크 컨트롤러 유형 번호이며1은 IDE를 나타냅니다- 이름이 없는 가상 하드 디스크는
NAME열에-로 표시됩니다
V. 스냅샷 관리
vms vm snapshot list – 스냅샷 나열
vms vm snapshot list <id> [--json]
출력 예시:
NAME GUEST ID DESCRIPTION LOCKED CREATED AT VM STATE ACTUAL CONSISTENCY
snapshot_2026-09-02T11-43-51.183703274 9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1 cli-test-edited false 2026-09-02T11:43:51+08:00 running crash
snapshot_2026-05-15T17-13-48.986448711 9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1 - false 2026-05-15T17:13:48+08:00 shutdown filesystem
VM STATE는 스냅샷 생성 시 가상 머신의 실행 상태입니다ACTUAL CONSISTENCY는 스냅샷의 일관성 유형이며,filesystem은 파일 시스템 일관성,crash는 크래시 일관성을 나타냅니다
vms vm snapshot create – 스냅샷 생성
가상 머신의 스냅샷을 생성하여 빠른 롤백이나 현재 상태 백업에 사용합니다.
vms vm snapshot create <id>
vms vm snapshot create <id> --body '{"description":"before-upgrade","locked":false}'
- 요청 본문은 선택 사항입니다:
description은 스냅샷 설명,locked는 잠금 여부입니다 - 스냅샷 이름은 생성 시간에 따라 시스템이 자동으로 생성합니다
- 스냅샷은 스토리지를 차지하며, 오랫동안 정리하지 않으면 스토리지를 가득 채울 수 있으므로 정기적인 정리를 권장합니다
vms vm snapshot edit – 스냅샷 편집
스냅샷의 설명 또는 잠금 상태를 수정합니다.
vms vm snapshot edit <id> <snapshot_name> --body '{"description":"updated description"}'
vms vm snapshot edit <id> <snapshot_name> --body '{"locked":true}'
- 요청 본문에 나타난 필드만 수정하고 나타나지 않은 필드는 원래 값을 유지합니다. 설명만 수정하면 잠금 상태는 변경되지 않으며 그 반대도 마찬가지입니다
출력 예시:
PROPERTY VALUE
ACTUAL CONSISTENCY crash
CREATED AT 2026-09-02T11:43:51+08:00
DESCRIPTION cli-test-edited
GUEST ID 9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1
LOCKED false
NAME snapshot_2026-09-02T11-43-51.183703274
VM STATE running
vms vm snapshot config – 스냅샷의 가상 머신 구성 보기
스냅샷에 저장된 가상 머신 구성을 봅니다.
vms vm snapshot config <id> <snapshot_name>
<id>는 가상 머신 ID, <snapshot_name>은 스냅샷 이름이며 vms vm snapshot list <id>로 가져올 수 있습니다.
출력 예시:
PROPERTY VALUE
CPU COMPATIBILITY MODE true
CPU PASSTHRU false
HYPERV ENLIGHTEN true
REPO NAME VM-Storage01
USB DEVICE NAME ["USB - Integrated Technology Express, Inc. Disk 2.0"]
USB VERSION 2
USBS [":3:3:048d:1234"]
VCPU NUM 4
VDISK NUM 1
VDISK TOTAL SIZE 1024
VDISKS [{"name":"disk1","type":"ide","vdisk_size":1024}]
VIDEO CARD vga
VRAM SIZE 2097152
vms vm snapshot consistency – 스냅샷 일관성 미리보기
스냅샷 생성 전에 얻을 수 있는 일관성 유형을 미리 보아 현재 스냅샷 생성에 적합한지 판단하는 데 도움을 줍니다.
vms vm snapshot consistency <id>
출력 예시:
PROPERTY VALUE
CONSISTENCY TYPE filesystem
REASON vm_shutdown
VM STATE shutdown
가상 머신이 종료 상태일 때 스냅샷을 생성하면 파일 시스템 일관성 스냅샷을 얻을 수 있습니다. 실행 상태에서는 일반적으로 크래시 일관성 스냅샷만 얻을 수 있습니다.
VI. 원격 콘솔
vms vm link – VNC 연결 정보 가져오기
가상 머신 VNC 콘솔의 연결 정보를 가져와 브라우저에서 원격 콘솔을 여는 데 사용합니다.
vms vm link <id> --json
- 가상 머신은 실행 중 또는 일시 중지 상태여야 하며, 그렇지 않으면 상태 충돌 오류를 반환합니다
출력 예시:
{
"url": "VMs/noVNC/vnc.html?autoconnect=true\u0026reconnect=true\u0026path=utils/websockify/?token=09fd98ee-4e2d-4c7a-a95c-8bacab80d322\u0026title=145",
"port": 8181,
"https": false
}
url은 NAS 관리 주소에 대한 콘솔 경로,port는 콘솔 서비스 포트,https는 HTTPS를 통한 접근이 필요한지 여부를 나타냅니다- JSON 출력에서 URL의
&는\u0026으로 이스케이프됩니다
VII. 가상 네트워크 관리
네트워크 유형은 두 가지로 나뉩니다:
| 유형 | 설명 |
|---|---|
| 전용(private) | 본 기기 가상 머신 간 통신에만 사용하는 내부 네트워크로 물리 NIC에 바인딩되지 않습니다 |
| 외부(external) | 물리 NIC에 바인딩된 네트워크로, 가상 머신이 이 네트워크를 통해 외부와 통신할 수 있습니다 |
vms network list – 가상 네트워크 나열
vms network list [--limit N] [--offset N] [--json]
출력 예시:
NAME NETWORK ID TYPE VLAN ID NUM GUESTS NUM HOSTS NUM INTERFACES HOST NAME
VM-Network04 ce9807c9-47b3-4258-9a80-ea8db1fd785d external 0 0 1 1 A-eae4
VM-Network01 b364a1ec-f60c-4971-9ea2-f7a002f09fa3 external 0 2 1 1 A-eae4
NUM GUESTS는 이 네트워크에 연결된 가상 머신 수,NUM INTERFACES는 선택된 물리 NIC 수입니다
vms network get – 가상 네트워크 상세 정보 보기
vms network get <network_id> --json
출력 예시:
{
"metadata": {
"createdAt": "2026-05-15T16:46:08.415062294+08:00",
"updatedAt": "2026-05-15T16:46:08.415062415+08:00"
},
"network_id": "b364a1ec-f60c-4971-9ea2-f7a002f09fa3",
"name": "VM-Network01",
"host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
"host_name": "A-eae4",
"interfaces": {
"15341593-7f43-49f4-9523-6ac750a63a8a": {
"totalCount": 1,
"items": [
{
"checked": false,
"host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
"host_name": "A-eae4",
"interface_id": "/00000000-0000-0000-0000-6cbfb504eae5",
"interface_name": "LAN 2",
"ip": [
"192.168.2.121"
],
"mask": [
"ffffff00"
],
"speed_mbs": 1000,
"status": "connected",
"tx_kbps": 0,
"rx_kbps": 0
},
{
"checked": true,
"host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
"host_name": "A-eae4",
"interface_id": "/00000000-0000-0000-0000-6cbfb504eae4",
"interface_name": "LAN 1",
"ip": [
"10.18.8.95"
],
"mask": [
"ffffff00"
],
"speed_mbs": 1000,
"status": "connected",
"tx_kbps": 2.5458984375,
"rx_kbps": 11.45458984375
}
]
}
},
"num_guests": 0,
"num_hosts": 1,
"num_interfaces": 1,
"type": "external",
"vlan_id": 0
}
interfaces는 이 네트워크에 바인딩된 NIC 정보로 호스트 ID별로 구성되며,checked는 해당 NIC가 선택되었는지 여부를 나타냅니다metadata는 네트워크의 생성 및 업데이트 시간을 기록합니다
vms network create – 가상 네트워크 생성
vms network create --body '{"name":"net1","type":"private","host_name":"TNAS"}' --json
vms network create --body '{"name":"net1","type":"external","vlan_id":100,"host_name":"TNAS","interface_name":"LAN 1"}' --json
전용 네트워크 생성:
- 요청 본문에는
name,type(private),host_name또는host_id가 포함되어야 하며, 네트워크를 어느 호스트에 생성할지 지정합니다 - 생성 전
vms network list-interfaces private로 사용 가능한 호스트를 확인할 수 있습니다
외부 네트워크 생성:
- 요청 본문에는
name,type(external),vlan_id가 포함되어야 하며, 최소 한 개의 물리 NIC를 지정해야 합니다 interface_name(예:LAN 1) 또는interface_id로 NIC를 지정할 수 있으며, NIC 이름이 호스트 간에 고유하지 않은 경우host_name과 함께 사용해야 합니다- 생성 전
vms network list-interfaces external로 사용 가능한 NIC를 확인할 수 있습니다
출력은 생성 후의 네트워크 정보이며 vms network get의 구조와 동일합니다:
{
"metadata": {
"createdAt": "2026-09-17T16:57:32.064720576+08:00",
"updatedAt": "2026-09-17T16:57:32.064720634+08:00"
},
"network_id": "27047bd1-eeeb-4762-82ae-45094dea4854",
"name": "cli-demo-net",
"host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
"host_name": "A-eae4",
"interfaces": {
"15341593-7f43-49f4-9523-6ac750a63a8a": {
"totalCount": 1,
"items": [
{
"checked": true,
"host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
"host_name": "A-eae4",
"interface_id": "",
"interface_name": "PNdea4854",
"ip": null,
"mask": null,
"speed_mbs": 0,
"status": ""
}
]
}
},
"num_guests": 0,
"num_hosts": 1,
"num_interfaces": 1,
"type": "private",
"vlan_id": 0
}
NIC를 지정하지 않으면 명령은 다음과 같은 안내를 표시합니다:
network create (type "external") requires selecting at least one interface; add "interface_name" (optionally scoped with "host_name") or "interface_id" to the body, e.g. {"name":"net1","type":"external","vlan_id":100,"host_name":"TNAS","interface_name":"LAN 1"}. Run "vms network list-interfaces external" to see available interfaces. Example available interface: LAN 2 on A-eae4 (host_id=15341593-7f43-49f4-9523-6ac750a63a8a, interface_id=/00000000-0000-0000-0000-6cbfb504eae5)
vms network update – 가상 네트워크 업데이트
수정이 필요한 필드만 제출하며, 제출하지 않은 필드는 원래 값을 유지합니다.
vms network update --body '{"network_id":"<network_id>","name":"renamed"}'
vms network update --body '{"network_id":"<network_id>","vlan_id":200}'
- 요청 본문에는
network_id가 포함되어야 합니다 - 명령은 먼저 현재 네트워크 구성을 읽고 제출된 필드를 병합하며, 네트워크 이름과 선택된 NIC는 지워지지 않습니다
- 출력은 업데이트 후의 네트워크 정보입니다
vms network delete – 가상 네트워크 삭제(고위험)
vms network delete <network_id> [--yes]
- 고위험 작업에 해당합니다: 대화형 모드에서는 확인을 요구하며, 비대화형 모드에서는
--yes를 추가해야 합니다 - 네트워크를 삭제하면 해당 네트워크에 연결된 모든 가상 머신이 연결 해제됩니다
- 먼저
vms network list-vnics <network_id>로 연결된 가상 머신을 확인할 것을 권장합니다
대화형 모드 확인 프롬프트:
This action will delete network "b364a1ec-f60c-4971-9ea2-f7a002f09fa3". Do you want to continue? [y/N]:
- 출력:
Network deleted: <network_id>
vms network list-interfaces – 네트워크 인터페이스 나열
지정한 유형의 네트워크 인터페이스를 나열합니다.
vms network list-interfaces external [--limit N] [--offset N]
vms network list-interfaces private [--limit N] [--offset N]
external은 호스트에서 사용 가능한 물리 NIC를 반환합니다private는 전용 네트워크 생성에 사용할 수 있는 호스트 정보를 반환합니다
출력 예시(external):
INTERFACE NAME INTERFACE ID HOST NAME STATUS IP SPEED MBS
LAN 2 /00000000-0000-0000-0000-6cbfb504eae5 A-eae4 disconnected - -1
LAN 1 /00000000-0000-0000-0000-6cbfb504eae4 A-eae4 connected ["10.18.8.73"] 1000
출력 예시(private):
INTERFACE NAME INTERFACE ID HOST NAME STATUS IP SPEED MBS
- - A-eae4 - - 0
vms network list-vnics – 네트워크의 가상 NIC 나열
vms network list-vnics <network_id> [--limit N] [--offset N] [--json]
출력 예시:
GUEST NAME GUEST ID MAC ADDRESS VIRTUAL INTERFACE ID NETWORK NAME STATUS PREFER SRIOV
win10 9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1 1a:e2:ae:95:4a:51 fe972ef5-b066-4967-89fa-8e85e43c8808 VM-Network01 - false
win101 32ee5a74-de8b-47a9-959d-1725c881ceab 1a:f6:db:fb:3d:79 f93bf16c-01ca-4b60-b164-8a3083fb5f03 VM-Network01 - false
vms network ovsinfo – OVS 상태 보기
Open vSwitch 가상 스위치가 활성화되었는지 확인합니다.
vms network ovsinfo [--json]
출력 예시:
PROPERTY VALUE
RESULT true
VALUE가 true이면 OVS가 활성화되었음을 나타냅니다.
VIII. 이미지 관리
vms image list – 이미지 나열
가상 머신 생성에 사용할 수 있는 시스템 이미지 파일을 나열합니다.
vms image list --json
image_name은 이미지 이름,file_name은 대응하는 파일 이름입니다type은 이미지 형식이며iso,qcow2등이 있습니다status는 이미지 상태이며available은 사용 가능을 나타냅니다repos는 이 이미지가 위치한 스토리지입니다progress는 이미지 처리 작업의 진행률이며0은 진행 중인 작업이 없음을 나타냅니다
출력 예시:
{
"totalCount": 4,
"items": [
{
"image_name": "cn_windows_10_consumer_editions_version_1909_updated_jan_2020_x86_dvd_9c50652f",
"image_id": "c93083a5-2b39-4f32-b19f-1ad97c6b4de4",
"file_name": "cn_windows_10_consumer_editions_version_1909_updated_jan_2020_x86_dvd_9c50652f.iso",
"type": "iso",
"file_size": 3884539904,
"status": "available",
"status_code": 0,
"status_reason": "",
"create_time": 1778835784,
"repos": [
{
"repo_name": "VM-Storage01",
"repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6"
}
],
"progress": 0,
"task_id": 0,
"virtual_size": 0
},
{
"image_name": "cn_windows_11_consumer_editions_version_21h2_updated_july_2022_x64_dvd_50ad4acf",
"image_id": "cb9d929a-d673-4e46-ac86-9488bbef19b9",
"file_name": "cn_windows_11_consumer_editions_version_21h2_updated_july_2022_x64_dvd_50ad4acf.iso",
"type": "iso",
"file_size": 5858816000,
"status": "available",
"status_code": 0,
"status_reason": "",
"create_time": 1778835784,
"repos": [
{
"repo_name": "VM-Storage01",
"repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6"
}
],
"progress": 0,
"task_id": 0,
"virtual_size": 0
},
{
"image_name": "virtio-win-0.1.285pro",
"image_id": "9b3f2fdd-9173-4611-a84c-0cc9ce88293c",
"file_name": "virtio-win-0.1.285.iso",
"type": "iso",
"file_size": 789645312,
"status": "available",
"status_code": 0,
"status_reason": "",
"create_time": 1778836128,
"repos": [
{
"repo_name": "VM-Storage01",
"repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6"
}
],
"progress": 0,
"task_id": 0,
"virtual_size": 0
},
{
"image_name": "haos_ova-18.2",
"image_id": "efd6da18-9475-44cf-8fb0-e2513421e68a",
"file_name": "haos_ova-18.2.qcow2",
"type": "qcow2",
"file_size": 1091698688,
"status": "available",
"status_code": 0,
"status_reason": "",
"create_time": 1787191833,
"repos": [
{
"repo_name": "VM-Storage02",
"repo_id": "517571ba-f7f7-49e1-9a62-7eb6ddfd9c78"
}
],
"progress": 0,
"task_id": 0,
"virtual_size": 0
}
]
}
vms image edit – 이미지 편집
이미지 이름을 수정하거나 이미지가 위치한 스토리지를 조정합니다.
vms image edit --body '{"image_id":"<image_id>","repos":["<repo_id>"]}'
vms image edit --body '{"image_id":"<image_id>","repos":["<repo_id_1>","<repo_id_2>"],"image_name":"renamed.iso"}'
- 요청 본문에는
image_id와repos가 포함되어야 하며,repos는 이 이미지의 전체 대상 스토리지 목록으로 비워둘 수 없습니다 image_name,file_name,type,file_size는 선택적 필드이며 제공하지 않으면 현재 값을 사용합니다repos가 비어 있으면 이미지가 모든 스토리지에서 제거되므로 명령은 실행 전에 해당 요청을 거부합니다- 출력:
Image updated
vms image delete – 이미지 삭제(고위험)
vms image delete --image-id <image_id> [--yes]
--image-id는 필수 항목입니다- 고위험 작업에 해당합니다: 대화형 모드에서는 확인을 요구하며, 비대화형 모드에서는
--yes를 추가해야 합니다 - 이미지를 삭제해도 이미 생성된 가상 머신에는 영향을 미치지 않지만, 이후 해당 이미지를 기반으로 가상 머신을 생성하는 데 영향을 미칩니다
- 먼저
vms image list-vms --image-id <image_id>로 사용 상황을 확인할 것을 권장합니다
대화형 모드 확인 프롬프트:
This action will permanently delete image "efd6da18-9475-44cf-8fb0-e2513421e68a". Do you want to continue? [y/N]:
- 출력:
Image deleted: <image_id>
vms image list-vms – 이 이미지를 사용하는 가상 머신 보기
vms image list-vms --image-id <image_id> [--json]
출력 예시:
GUEST NAME
1454486
이미지를 삭제하기 전에 이 명령을 실행하여 영향 범위를 확인할 수 있습니다. 이 이미지를 사용하는 가상 머신이 없으면 출력은 비어 있습니다.
IX. 스토리지 관리
vms repo list – 스토리지 나열
vms repo list [--json]
출력 예시:
NAME REPO ID STATUS USED PERCENT USED TOTAL SIZE FILE SYSTEM HOST NAME
VM-Storage01 735ef7f7-5d8d-4102-9377-8a7b8c33cda6 - 155583651840 14.150249481201172 1097552691200 btrfs -
VM-Storage02 517571ba-f7f7-49e1-9a62-7eb6ddfd9c78 normal 89361494016 16.64487648010254 535146790912 btrfs A-eae4
vms repo get – 스토리지 상세 정보 보기
vms repo get <repo_id> [--json]
출력 예시:
PROPERTY VALUE
ENABLE LOWER NOTIFY false
FILE SYSTEM btrfs
HARD LIMIT 2
HOST ID 15341593-7f43-49f4-9523-6ac750a63a8a
HOST NAME A-eae4
LAST NOTIFY TRESHOLD -
LOCATION VOLUME /Volume2
NAME VM-Storage02
REPO ID 517571ba-f7f7-49e1-9a62-7eb6ddfd9c78
SOFT LIMIT 10
STATUS normal
TOTAL SIZE 534760128512
LOCATION VOLUME은 스토리지가 위치한 볼륨입니다SOFT LIMIT,HARD LIMIT은 용량 경고 임계값(퍼센트)입니다ENABLE LOWER NOTIFY는 용량 부족 알림을 활성화할지 여부입니다
vms repo update – 스토리지 업데이트
수정이 필요한 필드만 제출하며, 제출하지 않은 필드는 원래 값을 유지합니다.
vms repo update --body '{"repo_id":"<repo_id>","name":"new-name"}'
vms repo update --body '{"repoId":"<repo_id>","enable_lower_notify":true}'
- 스토리지 ID는
repo_id또는repoId로 전달할 수 있습니다 - 명령은 먼저 현재 구성을 읽고 제출된 필드를 병합하며 다른 설정은 손실되지 않습니다
- 출력은 업데이트 후의 스토리지 정보입니다
vms repo delete – 스토리지 삭제(고위험)
vms repo delete <repo_id> <true|false> [--yes]
- 두 번째 파라미터는
need_save_data입니다:true는 디스크의 데이터 파일을 보존함을,false는 데이터까지 함께 삭제함을 나타냅니다 - 고위험 작업에 해당합니다: 대화형 모드에서는 확인을 요구하며, 비대화형 모드에서는
--yes를 추가해야 합니다 - 스토리지를 삭제하면 그 안의 가상 머신과 이미지도 함께 제거되므로 먼저
vms repo check-running과vms repo whether-exist-data를 실행하여 영향 범위를 확인할 것을 권장합니다
대화형 모드 확인 프롬프트:
This action will delete repository "735ef7f7-5d8d-4102-9377-8a7b8c33cda6" (save data: true). Do you want to continue? [y/N]:
- 출력:
Repository deleted: <repo_id>
vms repo list-volumes – 사용 가능한 볼륨 나열
스토리지 생성에 사용할 수 있는 볼륨을 나열합니다.
vms repo list-volumes [--json]
출력 예시:
NAME UUID DEVICE FILESYSTEM STATUS VOLUME TYPE TOTAL USED AVAILABLE USAGE
lv3 00000004-2608-1311-3025-6cbfb504eae4 /dev/mapper/vg0-lv3 ext4 - - {"unit":"KB","value":102626232} {"unit":"KB","value":52} {"unit":"KB","value":101561220} 0.000051200619070623694
lv2 00000003-2606-2215-3256-6cbfb504eae4 /dev/mapper/vg0-lv2 btrfs - - {"unit":"KB","value":104857600} {"unit":"KB","value":9715824} {"unit":"KB","value":93096464} 9.450061066630479
vms repo list-vms – 스토리지 내의 가상 머신 나열
vms repo list-vms --body '{"repo_id":"<repo_id>"}'
- 스토리지 ID는
repo_id또는repoId로 전달할 수 있습니다 - 명령은 먼저 스토리지 객체를 가져온 후 해당 가상 머신을 조회하므로 결과가 더 신뢰할 수 있습니다
vms repo check-running – 스토리지에서 실행 중인 가상 머신 확인
vms repo check-running <repo_id> [--json]
스토리지를 삭제하기 전에 실행하여 실행 중인 가상 머신이 없는지 확인합니다. 실행 중인 가상 머신이 없으면 출력은 비어 있습니다.
vms repo whether-exist-data – 스토리지 내에 데이터가 있는지 확인
vms repo whether-exist-data --body '{"repo_id":"<repo_id>"}'
스토리지를 삭제하기 전에 실행하여 스토리지 내에 아직 데이터가 있는지 확인합니다. 웹 인터페이스에서 스토리지를 삭제하기 전의 사전 검사와 동일합니다.
X. 전역 설정
vms setting get – 전역 설정 보기
VMs 애플리케이션의 전역 구성을 봅니다.
vms setting get [--json]
출력 예시:
PROPERTY VALUE
HOST SHUTDOWN BEHAVIOR 1
KB LAYOUT en-us
SHOW VIRTIO BLK VDISK false
HOST SHUTDOWN BEHAVIOR는 호스트 종료 시 가상 머신에 대한 처리 방식입니다KB LAYOUT은 가상 머신의 키보드 레이아웃입니다
XI. 모니터링 정보 조회
vms collectd hostinfo – 호스트 모니터링 정보 보기
vms collectd hostinfo [--limit N] [--offset N] [--json]
출력 예시:
NAME ID STATUS TYPE CPU USAGE RAM USAGE DESC
A-eae4 - running healthy 2.53 15.66 Info
vms collectd vminfo – 가상 머신 모니터링 정보 보기
vms collectd vminfo [--limit N] [--offset N] [--json]
출력 예시:
NAME ID STATUS TYPE CPU USAGE RAM USAGE DESC
145 09fd98ee-4e2d-4c7a-a95c-8bacab80d322 shutdown healthy 0 0 info
win10 9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1 shutdown healthy 0 0 info
win101 32ee5a74-de8b-47a9-959d-1725c881ceab shutdown healthy 0 0 info
vms collectd storageinfo – 스토리지 모니터링 정보 보기
vms collectd storageinfo [--limit N] [--offset N] [--json]
출력 예시:
NAME ID HOST NAME STATUS TYPE SIZE USED PERCENT USED PERCENT FREE
VM-Storage01 735ef7f7-5d8d-4102-9377-8a7b8c33cda6 A-eae4 none healthy 1097552691200 155583651840 14.328414916992188 85.67158508300781
VM-Storage02 517571ba-f7f7-49e1-9a62-7eb6ddfd9c78 A-eae4 none healthy 535146790912 89361494016 16.966018676757812 83.03398132324219
대화형 모드와 비대화형 모드
CLI는 현재 터미널 환경에서 실행 중인지 판단하여 서로 다른 동작을 취합니다:
대화형 모드(터미널 환경)
- 위험 작업 시 확인 프롬프트를 표시하며 기본 옵션은 No입니다
y또는Y를 입력하면 계속 실행하고,n을 입력하거나 그냥 Enter를 누르면 취소합니다- 작업을 취소하면
Operation cancelled가 출력되고 종료 코드는 99입니다
비대화형 모드(스크립트/자동화)
- 위험 작업은
--yes를 사용하여 확인을 건너뛰어야 하며, 그렇지 않으면 명령이 즉시 오류를 반환하고 종료 코드 1을 반환합니다 - 터미널 환경이 없으면 입력을 기다리지 않으므로 스크립트 및 예약 작업 호출에 적합합니다
- 스크립트에서 종료 코드를 명시적으로 처리하여 성공, 실패 및 상태 충돌을 구분할 것을 권장합니다
JSON 출력 형식
조회 계열 명령은 --json 파라미터를 지원하여 정규화된 JSON 데이터를 출력하므로 프로그램 파싱에 용이합니다.
형식 규약:
- 필드 이름은 snake_case를 사용합니다
- 부울 값은 true/false입니다
- 시간은 ISO 8601 형식을 사용하며 나노초 정밀도와 UTC+8 오프셋을 포함합니다(예: 2026-09-02T11:43:51.176535374+08:00)
- JSON은 stdout으로 출력하고 오류 메시지는 stderr로 출력합니다
- 테이블 출력에서 잘린 긴 필드는 JSON 출력에서 완전한 값이 됩니다
예:
vms setting get --json
{
"host_shutdown_behavior": 1,
"kb_layout": "en-us",
"show_virtio_blk_vdisk": false
}
명령에 따라 JSON 구조가 다소 다릅니다: vms vm list, vms vm snapshot list, vms vm logs는 배열을 직접 출력하고, 나머지 목록 계열 명령은 totalCount와 데이터 필드를 포함하는 객체를 출력하며 데이터 필드 이름은 리소스에 따라 다릅니다(예: items, hosts, vms, storage). 예를 들어 vms repo list --json:
{
"totalCount": 2,
"items": {
"517571ba-f7f7-49e1-9a62-7eb6ddfd9c78": {
"name": "VM-Storage02",
"repo_id": "517571ba-f7f7-49e1-9a62-7eb6ddfd9c78",
"status": "normal",
"used": 89361494016,
"percent_used": 16.64487648010254,
"location_volume": "/Volume2",
"total_size": 535146790912,
"hard_limit": 2,
"soft_limit": 10,
"enable_lower_notify": false,
"file_system": "btrfs"
}
}
}
일부 명령의 JSON 출력은 단순한 값입니다. 예를 들어 vms network ovsinfo --json은 true를 출력하고 vms vm pause --json은 null을 출력합니다.
종료 코드 설명
| 종료 코드 | 의미 | 대표적인 시나리오 |
|---|---|---|
| 0 | 성공 | 명령이 정상적으로 완료됨 |
| 1 | 파라미터 오류 | 필수 파라미터 누락, 파라미터 형식 오류, --yes 미지정 |
| 3 | 리소스가 존재하지 않음 | 명령의 사전 검증을 통과하지 못한 경우, 예를 들어 지정한 이미지가 존재하지 않음 |
| 4 | 상태 충돌 | 가상 머신의 현재 상태에서 해당 작업을 허용하지 않음(예: 종료된 가상 머신에 대한 종료 실행) |
| 6 | 연결 오류 | VMs 서비스에 연결할 수 없거나 socket 경로가 올바르지 않음 |
| 7 | 타임아웃 | 요청 타임아웃이며 --timeout으로 조정할 수 있음 |
| 9 | 실행 오류 | 백엔드가 오류를 반환함(오류 메시지에 code_num과 오류 설명이 포함됨) |
| 99 | 사용자 취소 | 대화형 확인에서 No를 선택하거나 그냥 Enter를 누른 경우 |
예:
# 退出码 1（参数错误）
vms vm poweroff <id>
# Confirmation required. Re-run with --yes to continue.
# 退出码 4（状态冲突）
vms vm pause <id>
# cannot pause a virtual machine: VM must be running (current status: shutdown)
# 退出码 9（执行错误）
vms vm get <id>
# vm check configure error: vdisk check - vm not exist: key not found (code_num=2001, vm check configure error)
# 退出码 6（连接错误）
vms vm list --socket /tmp/nope.sock
# failed to connect to VMs daemon (socket /tmp/nope.sock): dial unix /tmp/nope.sock: connect: no such file or directory
사용 시나리오 예시
일상 운영
# 查看所有虚拟机状态
vms vm list
# 查看某台虚拟机的配置与运行状态
vms vm get <id>
# 查看虚拟机的操作日志
vms vm logs <id> --limit 20
# 开机、关机与重启
vms vm poweron <id>
vms vm poweroff <id> --yes
vms vm reboot <id>
스크립트 일괄 작업
# 批量启动所有已关机的虚拟机
vms vm list --json | jq -r '.[] | select(.status == "shutdown") | .guest_id' | while read -r id; do
vms vm poweron "$id"
done
# 批量关闭所有运行中的虚拟机
vms vm list --json | jq -r '.[] | select(.status == "running") | .guest_id' | while read -r id; do
vms vm poweroff "$id" --yes
done
# 存储空间容量检查，超过 80% 时输出告警
vms collectd storageinfo --json | jq -r '.storage[] | select(.percent_used > 80) | .name'
백업 및 점검
# 关机后为虚拟机创建快照
vms vm poweroff <id> --yes
vms vm snapshot consistency <id>
vms vm snapshot create <id> --body '{"description":"weekly-backup"}'
# 查看快照列表与详情
vms vm snapshot list <id>
vms vm snapshot config <id> <snapshot_name>
# 导出虚拟机为 OVA 文件，用于异地备份
vms vm export --body '{"guest_id":"<id>","target_ova_path":"/Volume1/backup/my-vm.ova"}'
삭제 전 점검
# 删除存储空间前，先确认是否有虚拟机正在运行、是否存在数据
vms repo check-running <repo_id>
vms repo whether-exist-data --body '{"repo_id":"<repo_id>"}'
# 删除映像前，先确认有哪些虚拟机在使用
vms image list-vms --image-id <image_id>
# 删除网络前，先确认接入的虚拟机
vms network list-vnics <network_id>
AI 도구 호출
# AI 工具可通过命令行调用 vms 命令
# 例如：获取虚拟机与宿主机状态供 AI 分析
vms vm list --json
vms collectd hostinfo --json
# AI 可解析 JSON 输出并作出决策
vms vm list-resource --json
내부 개발 및 시스템 통합
# 开发人员可通过 CLI 封装内部运维工具
# 示例：封装虚拟机健康检查函数
check_vm_health() {
vms collectd vminfo --json | jq -r '.vms[] | select(.status != "running") | .name'
}
# 将 CLI 集成到内部监控平台
vms collectd storageinfo --json | curl -X POST https://monitor.example.com/api/report -d @-
자주 묻는 질문
Q: CLI는 추가 설치가 필요한가요?
필요하지 않습니다. CLI는 VMs 애플리케이션과 함께 설치되며, 애플리케이션을 활성화한 후 vms 명령을 직접 실행하면 사용할 수 있습니다.
Q: CLI는 반드시 SSH를 통해 사용해야 하나요?
아닙니다. CLI는 로컬 터미널, 원격 SSH, 스크립트, AI 도구 등 모든 명령줄 터미널을 통해 호출할 수 있습니다.
Q: CLI는 다른 기기의 가상 머신을 관리할 수 있나요?
할 수 없습니다. CLI는 로컬 unix socket을 통해 VMs 서비스와 통신하며 본 기기의 가상 머신 관리에만 사용됩니다.
Q: 왜 어떤 명령은 확인을 요구하고 어떤 것은 요구하지 않나요?
가상 머신 삭제, 네트워크 삭제, 이미지 삭제, 스토리지 삭제 및 종료(poweroff, force-poweroff) 등의 작업은 데이터나 서비스에 영향을 미치므로 기본적으로 확인을 요구합니다. 시작, 재시작, 일시 중지, 재개 및 조회 계열 명령에는 이러한 제한이 없습니다.
Q: 비대화형 모드에서는 위험 작업을 어떻게 확인하나요?
모든 위험 작업에는 --yes 파라미터를 추가해야 하며, 그렇지 않으면 명령이 오류로 종료됩니다(종료 코드 1).
Q: 스크립트에서 명령 실행 성공 여부를 어떻게 판단하나요?
종료 코드로 판단합니다: 0은 성공, 0이 아니면 실패를 나타냅니다. --json의 출력 내용을 파싱하는 방법도 있습니다.
Q: 왜 --json이 출력하는 목록이 객체인가요?
일부 명령의 JSON 출력은 ID별로 객체로 구성되고 totalCount 필드가 첨부되어 ID로 직접 참조하기 쉽습니다.
추가 도움말
모든 명령은 --help로 자세한 사용법을 확인할 수 있습니다:
vms --help
vms vm --help
vms vm poweroff --help
vms network create --help