VMs CLI

Introducere

VMs CLI este un instrument de administrare din linia de comandă pentru aplicația de virtualizare VMs de la TerraMaster, oferind capacități de interogare și operare identice cu cele ale interfeței web de administrare. CLI comunică cu serviciul VMs prin intermediul unui unix socket local, folosește interfețe de comandă standardizate și un format de ieșire JSON și poate fi integrat în scripturi, operațiuni automatizate și fluxuri de lucru de dezvoltare secundară.

Caracteristici principale

• Gata de utilizare: se instalează împreună cu aplicația VMs, fără instalare suplimentară
• Modalități flexibile de apelare: acceptă terminal local, SSH la distanță, scripturi, instrumente AI și numeroase alte căi de apelare
• Mod dual, interactiv și neinteractiv: potrivit atât pentru întreținerea zilnică de către administratori, cât și pentru scripturi și sarcini automatizate
• Suport pentru ieșire JSON: facilitează analizarea de către programe și integrarea automatizată
• Comunicare locală: comunică cu serviciul VMs doar prin unix socket local, fără a expune porturi către exterior
• Confirmare secundară pentru operațiuni periculoase: operațiuni precum ștergerea unei mașini virtuale și ștergerea unei rețele solicită implicit confirmare

Pornire rapidă

# 在终端中执行（可通过本地终端、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    -

Opțiuni globale

Următoarele opțiuni se aplică tuturor comenzilor:

Opțiune	Formă scurtă	Descriere
--help	-h	Afișează informațiile de ajutor ale comenzii
--version	-v	Afișează numărul versiunii (poate fi combinat cu --json pentru ieșire structurată)
--json	-	Ieșire în format JSON
--yes	-y	Ocolește solicitarea de confirmare pentru operațiunile periculoase (obligatoriu în modul neinteractiv)
--debug	-	Activează ieșirea de depanare, afișând procesul detaliat de execuție
--socket <path>	-	Calea unix socket a VMs, implicit /var/api/VMs.sock
--timeout <duration>	-	Durata de expirare a cererii, implicit 30s

Exemplu de informații despre versiune

vms --version

vms CLI v1.0.058

vms --version --json

{
  "build": "20260911",
  "cli_version": "v1.0.058"
}

Mediu de execuție

VMs CLI se instalează împreună cu aplicația VMs. Când aplicația este activată, aceasta creează o legătură a CLI către directorul PATH implicit al sistemului, astfel încât să îl puteți folosi direct după autentificarea prin SSH.

Element	Descriere
Fișier CLI	/Volume1/@apps/VMs/bin/vms
Calea comenzii	/usr/local/sbin/vms（deja în PATH-ul sistemului）
Mod de comunicare	Unix socket local, implicit /var/api/VMs.sock
Public vizat	Administratori autentificați local

Observații:

• CLI este destinat administrării mașinilor virtuale locale și nu acceptă administrarea de la distanță a altor dispozitive prin CLI.
• Backend-ul returnează întotdeauna HTTP 200, iar succesul comenzii este determinat de câmpul code din corpul răspunsului, pe baza căruia CLI îl convertește în cod de ieșire.
• Operațiunile periculoase (ștergerea unei mașini virtuale, ștergerea unei rețele, ștergerea unei imagini, ștergerea unui spațiu de stocare) solicită confirmare în modul interactiv, iar în modul neinteractiv trebuie transmis în mod explicit --yes.

Tabelul sumar al comenzilor

Mai jos este o referință rapidă sumară a tuturor comenzilor vms:

Comandă părinte	Subcomandă	Descrierea funcției	Necesită confirmare	Risc ridicat
vms	--version	Afișează informațiile despre versiune	Nu	Nu
vms vm	list	Listează toate mașinile virtuale	Nu	Nu
vms vm	get	Vizualizează detaliile unei mașini virtuale specificate	Nu	Nu
vms vm	list-resource	Listează resursele disponibile pentru crearea unei mașini virtuale	Nu	Nu
vms vm	logs	Vizualizează jurnalul de operațiuni al mașinii virtuale	Nu	Nu
vms vm	poweron	Pornește mașina virtuală	Nu	Nu
vms vm	poweroff	Oprește mașina virtuală (oprire normală)	Da	Nu
vms vm	force-poweroff	Oprește forțat mașina virtuală	Da	✅
vms vm	reboot	Repornește mașina virtuală	Nu	Nu
vms vm	pause	Suspendă mașina virtuală	Nu	Nu
vms vm	resume	Reia mașina virtuală suspendată	Nu	Nu
vms vm	autorun	Setează pornirea automată la bootare	Nu	Nu
vms vm	clone	Clonează mașina virtuală	Nu	Nu
vms vm	export	Exportă mașina virtuală ca fișier OVA	Nu	Nu
vms vm	delete	Șterge mașina virtuală	Da	✅
vms vm disk	list	Vizualizează discurile virtuale ale mașinii virtuale	Nu	Nu
vms vm snapshot	list	Listează instantaneele mașinii virtuale	Nu	Nu
vms vm snapshot	create	Creează un instantaneu	Nu	Nu
vms vm snapshot	edit	Editează descrierea și starea de blocare a instantaneului	Nu	Nu
vms vm snapshot	config	Vizualizează configurația mașinii virtuale salvată în instantaneu	Nu	Nu
vms vm snapshot	consistency	Previzualizează consistența instantaneului	Nu	Nu
vms vm	link	Obține informațiile de conectare la consola VNC	Nu	Nu
vms network	list	Listează rețelele virtuale	Nu	Nu
vms network	get	Vizualizează detaliile rețelei virtuale	Nu	Nu
vms network	create	Creează o rețea virtuală	Nu	Nu
vms network	update	Actualizează rețeaua virtuală	Nu	Nu
vms network	delete	Șterge rețeaua virtuală	Da	✅
vms network	list-interfaces	Listează interfețele de rețea de tipul specificat	Nu	Nu
vms network	list-vnics	Listează plăcile de rețea virtuale din rețea	Nu	Nu
vms network	ovsinfo	Vizualizează dacă OVS este activat	Nu	Nu
vms image	list	Listează imaginile	Nu	Nu
vms image	edit	Editează informațiile imaginii	Nu	Nu
vms image	delete	Șterge imaginea	Da	✅
vms image	list-vms	Vizualizează mașinile virtuale care folosesc imaginea	Nu	Nu
vms repo	list	Listează spațiile de stocare	Nu	Nu
vms repo	get	Vizualizează detaliile spațiului de stocare	Nu	Nu
vms repo	update	Actualizează configurația spațiului de stocare	Nu	Nu
vms repo	delete	Șterge spațiul de stocare	Da	✅
vms repo	list-volumes	Listează volumele disponibile	Nu	Nu
vms repo	list-vms	Listează mașinile virtuale din spațiul de stocare	Nu	Nu
vms repo	check-running	Verifică mașinile virtuale care rulează pe spațiul de stocare	Nu	Nu
vms repo	whether-exist-data	Verifică dacă există date în spațiul de stocare	Nu	Nu
vms setting	get	Vizualizează setările globale	Nu	Nu
vms collectd	hostinfo	Vizualizează informațiile de monitorizare ale gazdă	Nu	Nu
vms collectd	vminfo	Vizualizează informațiile de monitorizare ale mașinilor virtuale	Nu	Nu
vms collectd	storageinfo	Vizualizează informațiile de monitorizare ale stocării	Nu	Nu

Referința comenzilor

<id> din comenzi este ID-ul mașinii virtuale, corespunzător GUEST ID din ieșirea listei de mașini virtuale. La fel pentru <network_id>, <image_id>, <repo_id>, care pot fi obținute respectiv prin vms network list, vms image list, vms repo list.

Despre exemplele de ieșire：Ieșirea tabelară a vms trunchiază valorile câmpurilor prea lungi la o lățime fixă (se termină cu puncte de suspensie și nu depinde de lățimea terminalului), de exemplu VDISKS, VNICS, ISO IMAGES din configurația mașinii virtuale, precum și numele imaginilor. De aceea, în acest document comenzile care implică câmpuri lungi oferă uniform un exemplu complet de ieșire --json, iar restul comenzilor oferă un exemplu de ieșire tabelară. La procesarea cu scripturi se recomandă, de asemenea, utilizarea uniformă a --json.

I. Interogarea mașinilor virtuale

vms vm list – Listează mașinile virtuale

Listează toate mașinile virtuale de pe mașina locală și starea lor de bază.

vms vm list [--limit N] [--offset N] [--json]

• --limit și --offset sunt parametri de paginare
• Coloane de ieșire: nume, ID mașină virtuală, stare de rulare, număr de nuclee CPU, dimensiune memorie (în KB), adresă IP

Exemplu de ieșire:

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    -

Valori uzuale ale STATUS:

Stare	Descriere
running	În rulare
shutdown	Oprită
saved	Suspendată (starea de rulare a fost salvată pe disc)

vms vm get – Vizualizează detaliile mașinii virtuale

Vizualizează configurația completă și starea de rulare ale mașinii virtuale specificate.

vms vm get <id> --json

• Ieșirea include toate câmpurile de configurație și de stare de rulare ale mașinii virtuale
• Valorile goale, cum ar fi fără descriere sau fără IP, sunt afișate ca șir gol
• Când mașina virtuală nu există, comanda returnează o eroare și afișează un mesaj de eroare

Exemplu de ieșire:

{
  "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 – Listează resursele disponibile pentru crearea unei mașini virtuale

Vizualizează resursele pe care le poate oferi gazda, cum ar fi tipuri de firmware, imagini, CPU, memorie, rețea, spații de stocare, dispozitive passthrough, pentru evaluare înainte de crearea unei mașini virtuale.

vms vm list-resource --json

Câmpuri returnate: max_cpu_num, max_ram_size, usbs, pci_devices, networks, repos, images, video_cards, firmware, keyboard_layout.

Exemplu de ieșire:

{
  "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 – Vizualizează jurnalul de operațiuni al mașinii virtuale

Vizualizează jurnalul de operațiuni legate de mașina virtuală specificată (pornire/oprire, instantanee, editare, import/export etc.).

vms vm logs <id> --json [--limit N] [--desc]

• --limit specifică numărul de înregistrări returnate, implicit 50
• --desc ordonează descrescător după timp (activat implicit)
• Fiecare înregistrare include timpul, nivelul, categoria, utilizatorul operațiunii și descrierea evenimentului, iar descrierea evenimentului este text complet
• Descrierea evenimentului (event) este produsă de serviciul VMs localizat în funcție de limba de sistem a dispozitivului, iar exemplele din acest document folosesc uniform limba engleză

Exemplu de ieșire:

[
  {
    "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. Gestionarea alimentării mașinilor virtuale

vms vm poweron – Pornește mașina virtuală

vms vm poweron <id>

• Mașina virtuală trebuie să fie oprită, altfel se returnează o eroare de conflict de stare
• Ieșire: VM powered on: <id>

vms vm poweroff – Oprește mașina virtuală

Trimite mașinii virtuale o cerere normală de oprire, pentru ca sistemul să se închidă elegant.

vms vm poweroff <id> [--yes]

• Este o operațiune periculoasă: în modul interactiv se solicită confirmare, iar în modul neinteractiv trebuie adăugat --yes
• Mașina virtuală trebuie să fie în stare de rulare, altfel se returnează o eroare de conflict de stare

Solicitare de confirmare în modul interactiv:

This action will powered off VM "9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1". Do you want to continue? [y/N]: 

• Ieșire: VM powered off: <id>

vms vm force-poweroff – Oprește forțat mașina virtuală (risc ridicat)

Oprește forțat mașina virtuală, echivalent cu o întrerupere directă a alimentării.

vms vm force-poweroff <id> [--yes]

• Este o operațiune cu risc ridicat: în modul interactiv se solicită confirmare, iar în modul neinteractiv trebuie adăugat --yes
• Poate duce la pierderea datelor din mașina virtuală; se recomandă utilizarea doar când mașina virtuală nu răspunde

Solicitare de confirmare în modul interactiv:

This action will force powered off VM "9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1". Do you want to continue? [y/N]: 

• Ieșire: VM force powered off: <id>

vms vm reboot – Repornește mașina virtuală

vms vm reboot <id>

• Ieșire: VM rebooted: <id>

vms vm pause – Suspendă mașina virtuală

Îngheață starea de rulare a mașinii virtuale și salvează starea curentă pe disc.

vms vm pause <id>

• Mașina virtuală trebuie să fie în stare de rulare, altfel se returnează o eroare de conflict de stare
• După suspendare, starea mașinii virtuale este afișată ca saved
• Ieșire: VM paused: <id>

vms vm resume – Reia mașina virtuală

Readuce mașina virtuală din starea de suspendare în starea de rulare.

vms vm resume <id>

• Mașina virtuală trebuie să fie în stare de suspendare, altfel se returnează o eroare de conflict de stare
• Ieșire: VM resumed: <id>

vms vm autorun – Setează pornirea automată la bootare

Setează dacă mașina virtuală pornește automat odată cu gazda.

vms vm autorun <id> <true|false>

• Al doilea parametru trebuie să fie true sau false
• Comanda citește configurația curentă și modifică doar comutatorul de pornire automată, celelalte setări nefiind afectate
• Ieșire: Auto-start enabled for VM <id> sau Auto-start disabled for VM <id>

III. Copierea, exportul și ștergerea mașinilor virtuale

vms vm clone – Clonează mașina virtuală

Creează o mașină virtuală nouă folosind o mașină virtuală existentă ca șablon.

vms vm clone --body '{"guest_id":"<source_id>","name":"my-clone"}'
vms vm clone --file clone.json

• În corpul cererii, guest_id este ID-ul mașinii virtuale sursă, iar name (sau guest_name) este numele noii mașini virtuale
• Mașina virtuală sursă trebuie să fie oprită
• --body transmite direct corpul cererii ca șir JSON, iar --file citește corpul cererii dintr-un fișier

vms vm export – Exportă mașina virtuală

Exportă mașina virtuală ca fișier OVA, pentru backup sau migrare către alte platforme de virtualizare.

vms vm export --body '{"guest_id":"<source_id>","target_ova_path":"/Volume1/export/my-vm.ova"}'
vms vm export --file export.json

• În corpul cererii, guest_id este ID-ul mașinii virtuale sursă, target_ova_path este calea fișierului țintă, iar ova_mode este modul opțional de compatibilitate cu VMware
• Mașina virtuală sursă trebuie să fie oprită
• Exportul este o sarcină consumatoare de timp, iar exportul mașinilor virtuale de capacitate mare durează mai mult

vms vm delete – Șterge mașina virtuală (risc ridicat)

Șterge definitiv mașina virtuală.

vms vm delete <id> [--yes]

• Este o operațiune cu risc ridicat: în modul interactiv se solicită confirmare, iar în modul neinteractiv trebuie adăugat --yes
• După ștergere nu mai este posibilă recuperarea; vă rugăm să confirmați în prealabil că datele din mașina virtuală au fost salvate

Solicitare de confirmare în modul interactiv:

This action will permanently delete VM "5a0391f2-c545-45eb-8eed-0a104972229b". Do you want to continue? [y/N]: 

• Ieșire: VM deleted: <id>

IV. Discuri virtuale

vms vm disk list – Vizualizează discurile virtuale

Listează toate discurile virtuale ale mașinii virtuale specificate.

vms vm disk list <id> [--json]

Exemplu de ieșire:

NAME  VDISK ID                              VDISK SIZE  VDISK MODE  IDX
-     f4ed4eae-1512-4273-963b-79ebd93a0932  1024        1           0

• VDISK MODE este numărul tipului de controler al discului virtual, 1 însemnând IDE
• Discurile virtuale fără nume sunt afișate în coloana NAME ca -

V. Gestionarea instantaneelor

vms vm snapshot list – Listează instantaneele

vms vm snapshot list <id> [--json]

Exemplu de ieșire:

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 este starea de rulare a mașinii virtuale la momentul creării instantaneului
• ACTUAL CONSISTENCY este tipul de consistență al instantaneului, filesystem însemnând consistență la nivel de sistem de fișiere, iar crash însemnând consistență la nivel de crash

vms vm snapshot create – Creează un instantaneu

Creează un instantaneu al mașinii virtuale, pentru revenire rapidă sau backup al stării curente.

vms vm snapshot create <id>
vms vm snapshot create <id> --body '{"description":"before-upgrade","locked":false}'

• Corpul cererii este opțional: description este descrierea instantaneului, iar locked indică dacă este blocat
• Numele instantaneului este generat automat de sistem în funcție de momentul creării
• Instantaneele ocupă spațiu de stocare, iar necurățarea pe termen lung poate umple spațiul de stocare; se recomandă curățarea periodică

vms vm snapshot edit – Editează instantaneul

Modifică descrierea sau starea de blocare a instantaneului.

vms vm snapshot edit <id> <snapshot_name> --body '{"description":"updated description"}'
vms vm snapshot edit <id> <snapshot_name> --body '{"locked":true}'

• Sunt modificate doar câmpurile prezente în corpul cererii, iar câmpurile absente își păstrează valoarea inițială; modificarea doar a descrierii nu schimbă starea de blocare și invers

Exemplu de ieșire:

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 – Vizualizează configurația mașinii virtuale din instantaneu

Vizualizează configurația mașinii virtuale salvată în instantaneu.

vms vm snapshot config <id> <snapshot_name>

<id> este ID-ul mașinii virtuale, iar <snapshot_name> este numele instantaneului, care poate fi obținut prin vms vm snapshot list <id>.

Exemplu de ieșire:

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 – Previzualizează consistența instantaneului

Înainte de crearea unui instantaneu, previzualizează tipul de consistență posibil, ajutând la determinarea momentului potrivit pentru crearea instantaneului.

vms vm snapshot consistency <id>

Exemplu de ieșire:

PROPERTY          VALUE
CONSISTENCY TYPE  filesystem
REASON            vm_shutdown
VM STATE          shutdown

Când mașina virtuală este oprită, crearea unui instantaneu oferă un instantaneu cu consistență la nivel de sistem de fișiere; în stare de rulare, de obicei se poate obține doar un instantaneu cu consistență la nivel de crash.

VI. Consola la distanță

vms vm link – Obține informațiile de conectare VNC

Obține informațiile de conectare la consola VNC a mașinii virtuale, pentru a deschide consola la distanță în browser.

vms vm link <id> --json

• Mașina virtuală trebuie să fie în stare de rulare sau de suspendare, altfel se returnează o eroare de conflict de stare

Exemplu de ieșire:

{
  "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 este calea consolei relativă la adresa de administrare a NAS, port este portul serviciului de consolă, iar https indică dacă este necesar accesul prin HTTPS
• În ieșirea JSON, & din URL este escape-uit ca \u0026

VII. Gestionarea rețelelor virtuale

Tipurile de rețea se împart în două:

Tip	Descriere
Privată (private)	Rețea internă doar pentru comunicarea între mașinile virtuale locale, fără legare la o placă de rețea fizică
Externă (external)	Rețea legată la o placă de rețea fizică, prin care mașinile virtuale pot comunica cu exteriorul

vms network list – Listează rețelele virtuale

vms network list [--limit N] [--offset N] [--json]

Exemplu de ieșire:

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 este numărul de mașini virtuale conectate la această rețea, iar NUM INTERFACES este numărul de plăci de rețea fizice selectate

vms network get – Vizualizează detaliile rețelei virtuale

vms network get <network_id> --json

Exemplu de ieșire:

{
  "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 sunt informațiile plăcilor de rețea legate la această rețea, organizate după ID-ul gazdă, iar checked indică dacă placa de rețea a fost selectată
• metadata înregistrează momentul creării și actualizării rețelei

vms network create – Creează o rețea virtuală

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

Crearea unei rețele private:

• Corpul cererii trebuie să conțină name, type (private), host_name sau host_id, specificând pe care gazdă este creată rețeaua
• Înainte de creare, puteți vizualiza gazdele disponibile prin vms network list-interfaces private

Crearea unei rețele externe:

• Corpul cererii trebuie să conțină name, type (external), vlan_id și să specifice cel puțin o placă de rețea fizică
• Placa de rețea poate fi specificată prin interface_name (precum LAN 1) sau interface_id; când numele plăcii de rețea nu este unic între gazde, acesta trebuie folosit împreună cu host_name
• Înainte de creare, puteți vizualiza plăcile de rețea disponibile prin vms network list-interfaces external

Ieșirea reprezintă informațiile rețelei după creare, cu o structură identică cu cea a 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
}

Când nu este specificată o placă de rețea, comanda afișează o indicație:

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 – Actualizează rețeaua virtuală

Trimite doar câmpurile care necesită modificare, iar câmpurile netrimise își păstrează valoarea inițială.

vms network update --body '{"network_id":"<network_id>","name":"renamed"}'
vms network update --body '{"network_id":"<network_id>","vlan_id":200}'

• Corpul cererii trebuie să conțină network_id
• Comanda citește mai întâi configurația curentă a rețelei și fuzionează câmpurile trimise, astfel încât numele rețelei și plăcile de rețea selectate să nu fie golite
• Ieșirea reprezintă informațiile rețelei după actualizare

vms network delete – Șterge rețeaua virtuală (risc ridicat)

vms network delete <network_id> [--yes]

• Este o operațiune cu risc ridicat: în modul interactiv se solicită confirmare, iar în modul neinteractiv trebuie adăugat --yes
• Ștergerea rețelei deconectează toate mașinile virtuale conectate la aceasta
• Se recomandă confirmarea prealabilă a mașinilor virtuale conectate prin vms network list-vnics <network_id>

Solicitare de confirmare în modul interactiv:

This action will delete network "b364a1ec-f60c-4971-9ea2-f7a002f09fa3". Do you want to continue? [y/N]: 

• Ieșire: Network deleted: <network_id>

vms network list-interfaces – Listează interfețele de rețea

Listează interfețele de rețea de tipul specificat.

vms network list-interfaces external [--limit N] [--offset N]
vms network list-interfaces private [--limit N] [--offset N]

• external returnează plăcile de rețea fizice disponibile pe gazdă
• private returnează informațiile gazdelor care pot fi folosite pentru crearea unei rețele private

Exemplu de ieșire (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

Exemplu de ieșire (private):

INTERFACE NAME  INTERFACE ID  HOST NAME  STATUS  IP  SPEED MBS
-               -             A-eae4     -       -   0

vms network list-vnics – Listează plăcile de rețea virtuale din rețea

vms network list-vnics <network_id> [--limit N] [--offset N] [--json]

Exemplu de ieșire:

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 – Vizualizează starea OVS

Confirmă dacă comutatorul virtual Open vSwitch este activat.

vms network ovsinfo [--json]

Exemplu de ieșire:

PROPERTY  VALUE
RESULT    true

Când VALUE este true, OVS este activat.

VIII. Gestionarea imaginilor

vms image list – Listează imaginile

Listează fișierele imagine de sistem disponibile pentru crearea mașinilor virtuale.

vms image list --json

• image_name este numele imaginii, iar file_name este numele de fișier corespunzător
• type este formatul imaginii, precum iso, qcow2
• status este starea imaginii, available însemnând disponibilă
• repos este spațiul de stocare în care se află imaginea
• progress este progresul sarcinii de procesare a imaginii, 0 însemnând că nu există nicio sarcină în curs

Exemplu de ieșire:

{
  "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 – Editează imaginea

Modifică numele imaginii sau ajustează spațiul de stocare în care se află imaginea.

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"}'

• Corpul cererii trebuie să conțină image_id și repos, unde repos este lista completă a spațiilor de stocare țintă ale imaginii și nu poate fi goală
• image_name, file_name, type, file_size sunt câmpuri opționale și, dacă nu sunt furnizate, se păstrează valorile curente
• repos gol ar duce la scoaterea imaginii din toate spațiile de stocare, astfel că comanda respinge această cerere înainte de execuție
• Ieșire: Image updated

vms image delete – Șterge imaginea (risc ridicat)

vms image delete --image-id <image_id> [--yes]

• --image-id este obligatoriu
• Este o operațiune cu risc ridicat: în modul interactiv se solicită confirmare, iar în modul neinteractiv trebuie adăugat --yes
• Ștergerea imaginii nu afectează mașinile virtuale deja create, dar afectează crearea ulterioară de mașini virtuale pe baza acestei imagini
• Se recomandă confirmarea prealabilă a utilizării prin vms image list-vms --image-id <image_id>

Solicitare de confirmare în modul interactiv:

This action will permanently delete image "efd6da18-9475-44cf-8fb0-e2513421e68a". Do you want to continue? [y/N]: 

• Ieșire: Image deleted: <image_id>

vms image list-vms – Vizualizează mașinile virtuale care folosesc imaginea

vms image list-vms --image-id <image_id> [--json]

Exemplu de ieșire:

GUEST NAME
1454486

Înainte de ștergerea imaginii, puteți executa mai întâi această comandă pentru a confirma aria de impact; când nicio mașină virtuală nu folosește imaginea, ieșirea este goală.

IX. Gestionarea spațiilor de stocare

vms repo list – Listează spațiile de stocare

vms repo list [--json]

Exemplu de ieșire:

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 – Vizualizează detaliile spațiului de stocare

vms repo get <repo_id> [--json]

Exemplu de ieșire:

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 este volumul în care se află spațiul de stocare
• SOFT LIMIT, HARD LIMIT sunt pragurile de avertizare privind capacitatea (procent)
• ENABLE LOWER NOTIFY indică dacă este activată notificarea privind capacitatea insuficientă

vms repo update – Actualizează spațiul de stocare

Trimite doar câmpurile care necesită modificare, iar câmpurile netrimise își păstrează valoarea inițială.

vms repo update --body '{"repo_id":"<repo_id>","name":"new-name"}'
vms repo update --body '{"repoId":"<repo_id>","enable_lower_notify":true}'

• ID-ul spațiului de stocare poate fi transmis prin repo_id sau repoId
• Comanda citește mai întâi configurația curentă și fuzionează câmpurile trimise, astfel încât celelalte setări să nu se piardă
• Ieșirea reprezintă informațiile spațiului de stocare după actualizare

vms repo delete – Șterge spațiul de stocare (risc ridicat)

vms repo delete <repo_id> <true|false> [--yes]

• Al doilea parametru este need_save_data: true înseamnă păstrarea fișierelor de date de pe disc, iar false înseamnă ștergerea împreună cu datele
• Este o operațiune cu risc ridicat: în modul interactiv se solicită confirmare, iar în modul neinteractiv trebuie adăugat --yes
• Ștergerea spațiului de stocare elimină simultan mașinile virtuale și imaginile din el; se recomandă executarea prealabilă a vms repo check-running și vms repo whether-exist-data pentru a confirma aria de impact

Solicitare de confirmare în modul interactiv:

This action will delete repository "735ef7f7-5d8d-4102-9377-8a7b8c33cda6" (save data: true). Do you want to continue? [y/N]: 

• Ieșire: Repository deleted: <repo_id>

vms repo list-volumes – Listează volumele disponibile

Listează volumele care pot fi folosite pentru crearea unui spațiu de stocare.

vms repo list-volumes [--json]

Exemplu de ieșire:

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 – Listează mașinile virtuale din spațiul de stocare

vms repo list-vms --body '{"repo_id":"<repo_id>"}'

• ID-ul spațiului de stocare poate fi transmis prin repo_id sau repoId
• Comanda obține mai întâi obiectul spațiului de stocare și apoi interoghează mașinile sale virtuale, rezultatul fiind mai fiabil

vms repo check-running – Verifică mașinile virtuale care rulează pe spațiul de stocare

vms repo check-running <repo_id> [--json]

Se execută înainte de ștergerea spațiului de stocare, pentru a confirma că nicio mașină virtuală nu rulează; când nu există mașini virtuale în rulare, ieșirea este goală.

vms repo whether-exist-data – Verifică dacă există date în spațiul de stocare

vms repo whether-exist-data --body '{"repo_id":"<repo_id>"}'

Se execută înainte de ștergerea spațiului de stocare, pentru a confirma dacă mai există date în acesta; este identic cu verificarea prealabilă dinaintea ștergerii spațiului de stocare din interfața web.

X. Setări globale

vms setting get – Vizualizează setările globale

Vizualizează configurația globală a aplicației VMs.

vms setting get [--json]

Exemplu de ieșire:

PROPERTY                VALUE
HOST SHUTDOWN BEHAVIOR  1
KB LAYOUT               en-us
SHOW VIRTIO BLK VDISK   false

• HOST SHUTDOWN BEHAVIOR este modul de tratare a mașinilor virtuale la oprirea gazdei
• KB LAYOUT este aspectul tastaturii mașinilor virtuale

XI. Interogarea informațiilor de monitorizare

vms collectd hostinfo – Vizualizează informațiile de monitorizare ale gazdă

vms collectd hostinfo [--limit N] [--offset N] [--json]

Exemplu de ieșire:

NAME    ID  STATUS   TYPE     CPU USAGE  RAM USAGE  DESC
A-eae4  -   running  healthy  2.53       15.66      Info

vms collectd vminfo – Vizualizează informațiile de monitorizare ale mașinilor virtuale

vms collectd vminfo [--limit N] [--offset N] [--json]

Exemplu de ieșire:

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 – Vizualizează informațiile de monitorizare ale stocării

vms collectd storageinfo [--limit N] [--offset N] [--json]

Exemplu de ieșire:

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

Modul interactiv și modul neinteractiv

CLI determină dacă rulează într-un mediu de terminal și adoptă comportamente diferite:

Modul interactiv (mediu de terminal)

• Operațiunile periculoase afișează o solicitare de confirmare, cu opțiunea implicită No
• Introduceți y sau Y pentru a continua, iar n sau simpla apăsare a tastei Enter pentru a anula
• La anularea operațiunii se afișează Operation cancelled, cu codul de ieșire 99

Modul neinteractiv (script/automatizare)

• Operațiunile periculoase trebuie să folosească --yes pentru a sări peste confirmare, altfel comanda raportează direct o eroare și returnează codul de ieșire 1
• Fără un mediu de terminal nu așteaptă introducere de date, fiind potrivit pentru apeluri din scripturi și sarcini programate
• Se recomandă tratarea explicită a codurilor de ieșire în scripturi, pentru a distinge succesul, eșecul și conflictul de stare

Formatul ieșirii JSON

Comenzile de interogare acceptă parametrul --json, producând date JSON standardizate, ușor de analizat de către programe.

Convenții de format:

• Numele câmpurilor folosesc snake_case
• Valorile booleene sunt true/false
• Timpul folosește formatul ISO 8601, cu precizie la nanosecundă și decalaj de fus orar UTC+8 (precum 2026-09-02T11:43:51.176535374+08:00)
• Ieșirea JSON este scrisă în stdout, iar mesajele de eroare în stderr
• Câmpurile lungi trunchiate în ieșirea tabelară apar ca valori complete în ieșirea JSON

Exemplu:

vms setting get --json

{
  "host_shutdown_behavior": 1,
  "kb_layout": "en-us",
  "show_virtio_blk_vdisk": false
}

Structurile JSON diferă ușor între comenzi: vms vm list, vms vm snapshot list, vms vm logs produc direct un tablou; celelalte comenzi de tip listă produc un obiect care conține totalCount și câmpuri de date, ale căror nume variază în funcție de resursă (precum items, hosts, vms, storage). De exemplu 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"
    }
  }
}

Unele comenzi produc valori JSON simple, de exemplu vms network ovsinfo --json produce true, iar vms vm pause --json produce null.

Explicația codurilor de ieșire

Cod de ieșire	Semnificație	Scenariu tipic
0	Succes	Comanda s-a încheiat normal
1	Eroare de parametru	Lipsește un parametru obligatoriu, format de parametru greșit, --yes neadăugat
3	Resursa nu există	Verificarea prealabilă a comenzii nu a trecut, de exemplu imaginea specificată nu există
4	Conflict de stare	Starea curentă a mașinii virtuale nu permite această operațiune (precum oprirea unei mașini virtuale deja oprite)
6	Eroare de conectare	Nu se poate conecta la serviciul VMs sau calea socket este incorectă
7	Expirare	Cererea a expirat; poate fi ajustat prin --timeout
9	Eroare de execuție	Backend-ul a returnat o eroare (mesajul de eroare conține code_num și descrierea erorii)
99	Anulare de către utilizator	S-a ales No sau s-a apăsat direct Enter la confirmarea interactivă

Exemplu:

# 退出码 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

Exemple de scenarii de utilizare

Operare zilnică

# 查看所有虚拟机状态
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>

Operațiuni în masă cu scripturi

# 批量启动所有已关机的虚拟机
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'

Backup și inspecție

# 关机后为虚拟机创建快照
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"}'

Verificare înainte de ștergere

# 删除存储空间前，先确认是否有虚拟机正在运行、是否存在数据
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>

Apelare din instrumente AI

# AI 工具可通过命令行调用 vms 命令
# 例如：获取虚拟机与宿主机状态供 AI 分析
vms vm list --json
vms collectd hostinfo --json

# AI 可解析 JSON 输出并作出决策
vms vm list-resource --json

Dezvoltare internă și integrare în sisteme

# 开发人员可通过 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 @-

Întrebări frecvente

Î: CLI necesită instalare suplimentară?

Nu. CLI se instalează împreună cu aplicația VMs, iar după activarea aplicației puteți folosi direct comanda vms.

Î: CLI trebuie folosit obligatoriu prin SSH?

Nu. CLI poate fi apelat din orice terminal de linie de comandă, inclusiv terminal local, SSH la distanță, scripturi, instrumente AI etc.

Î: CLI poate administra mașini virtuale de pe alte dispozitive?

Nu. CLI comunică cu serviciul VMs prin unix socket local și este folosit doar pentru administrarea mașinilor virtuale locale.

Î: De ce unele comenzi solicită confirmare, iar altele nu?

Operațiuni precum ștergerea unei mașini virtuale, ștergerea unei rețele, ștergerea unei imagini, ștergerea unui spațiu de stocare și oprirea (poweroff, force-poweroff) afectează date sau servicii, de aceea solicită implicit confirmare; comenzile de pornire, repornire, suspendare, reluare și interogare nu au astfel de restricții.

Î: Cum se confirmă operațiunile periculoase în modul neinteractiv?

Toate operațiunile periculoase trebuie să adauge parametrul --yes, altfel comanda se încheie cu eroare (cod de ieșire 1).

Î: Cum se determină în scripturi dacă o comandă s-a executat cu succes?

Prin codul de ieșire: 0 înseamnă succes, iar un cod diferit de 0 înseamnă eșec. De asemenea, puteți analiza conținutul ieșirii --json.

Î: De ce lista din ieșirea --json este un obiect?

Ieșirea JSON a unor comenzi este organizată ca obiect după ID, cu un câmp suplimentar totalCount, pentru a facilita accesul direct după ID.

Ajutor suplimentar

Fiecare comandă acceptă --help pentru vizualizarea utilizării detaliate:

vms --help
vms vm --help
vms vm poweroff --help
vms network create --help