Version: TOS 7

VMs CLI

Introduzione

VMs CLI è lo strumento di gestione da riga di comando dell'applicazione di virtualizzazione VMs di TerraMaster e offre capacità di interrogazione e di gestione operative coerenti con l'interfaccia di gestione web. La CLI comunica con il servizio VMs tramite l'unix socket locale, adotta un'interfaccia a comandi standardizzata e un formato di output JSON e può essere integrata in script, operazioni automatizzate e flussi di lavoro di sviluppo secondario.

Caratteristiche principali

Pronto all'uso: viene installato insieme all'applicazione VMs, senza necessità di installazione aggiuntiva
Modalità di invocazione flessibili: supporta terminale locale, SSH remoto, script, strumenti di IA e altre vie di invocazione
Doppia modalità interattiva e non interattiva: adatta sia alla manutenzione quotidiana dell'amministratore sia a script e attività automatizzate
Supporto all'output JSON: facilita l'analisi da parte dei programmi e l'integrazione automatizzata
Comunicazione locale: comunica con il servizio VMs solo tramite l'unix socket locale, senza aprire porte all'esterno
Conferma secondaria per le operazioni pericolose: operazioni come l'eliminazione di una macchina virtuale o di una rete richiedono la conferma per impostazione predefinita

Guida rapida

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

Opzioni globali

Le seguenti opzioni si applicano a tutti i comandi:

Opzione	Abbreviazione	Descrizione
`--help`	`-h`	Mostra le informazioni di aiuto del comando
`--version`	`-v`	Mostra il numero di versione (può essere abbinato a `--json` per generare informazioni strutturate)
`--json`	-	Genera l'output in formato JSON
`--yes`	`-y`	Salta la richiesta di conferma delle operazioni pericolose (obbligatorio in modalità non interattiva)
`--debug`	-	Attiva l'output di debug e mostra il processo di esecuzione dettagliato
`--socket <path>`	-	Percorso dell'unix socket di VMs, per impostazione predefinita `/var/api/VMs.sock`
`--timeout <duration>`	-	Tempo di attesa della richiesta, per impostazione predefinita 30s

Esempio di informazioni sulla versione

vms --version

vms CLI v1.0.058

vms --version --json

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

Ambiente di esecuzione

VMs CLI viene installato insieme all'applicazione VMs. Quando l'applicazione è abilitata, collega la CLI alla directory PATH predefinita del sistema, pertanto è possibile utilizzarla direttamente dopo aver effettuato l'accesso tramite SSH.

Voce	Descrizione
File della CLI	`/Volume1/@apps/VMs/bin/vms`
Percorso del comando	`/usr/local/sbin/vms` (già presente nel PATH di sistema)
Modalità di comunicazione	unix socket locale, per impostazione predefinita `/var/api/VMs.sock`
Destinatari	Amministratori che effettuano l'accesso sul dispositivo locale

Note:

La CLI serve a gestire le macchine virtuali del dispositivo locale e non supporta la gestione remota di altri dispositivi tramite la CLI.
Il backend restituisce sempre HTTP 200; l'esito del comando si determina in base al campo code del corpo della risposta e la CLI lo converte nel codice di uscita corrispondente.
Le operazioni pericolose (eliminazione di macchine virtuali, reti, immagini e spazi di archiviazione) richiedono la conferma in modalità interattiva e l'aggiunta esplicita di --yes in modalità non interattiva.

Tabella riepilogativa dei comandi

Di seguito è riportato un riepilogo di riferimento rapido di tutti i comandi vms:

Comando principale	Sottocomando	Descrizione della funzione	Richiede conferma	Rischio elevato
vms	--version	Mostra le informazioni sulla versione	No	No
vms vm	list	Elenca tutte le macchine virtuali	No	No
vms vm	get	Visualizza i dettagli di una macchina virtuale specificata	No	No
vms vm	list-resource	Elenca le risorse disponibili per creare macchine virtuali	No	No
vms vm	logs	Visualizza il registro delle operazioni della macchina virtuale	No	No
vms vm	poweron	Avvia la macchina virtuale	No	No
vms vm	poweroff	Arresta la macchina virtuale (arresto normale)	Sì	No
vms vm	force-poweroff	Forza l'arresto della macchina virtuale	Sì	✅
vms vm	reboot	Riavvia la macchina virtuale	No	No
vms vm	pause	Sospende la macchina virtuale	No	No
vms vm	resume	Ripristina la macchina virtuale sospesa	No	No
vms vm	autorun	Imposta l'avvio automatico all'accensione	No	No
vms vm	clone	Clona la macchina virtuale	No	No
vms vm	export	Esporta la macchina virtuale come file OVA	No	No
vms vm	delete	Elimina la macchina virtuale	Sì	✅
vms vm disk	list	Visualizza i dischi virtuali della macchina virtuale	No	No
vms vm snapshot	list	Elenca le istantanee della macchina virtuale	No	No
vms vm snapshot	create	Crea un'istantanea	No	No
vms vm snapshot	edit	Modifica la descrizione e lo stato di blocco dell'istantanea	No	No
vms vm snapshot	config	Visualizza la configurazione della macchina virtuale salvata nell'istantanea	No	No
vms vm snapshot	consistency	Visualizza in anteprima la coerenza dell'istantanea	No	No
vms vm	link	Ottiene le informazioni di connessione della console VNC	No	No
vms network	list	Elenca le reti virtuali	No	No
vms network	get	Visualizza i dettagli della rete virtuale	No	No
vms network	create	Crea una rete virtuale	No	No
vms network	update	Aggiorna la rete virtuale	No	No
vms network	delete	Elimina la rete virtuale	Sì	✅
vms network	list-interfaces	Elenca le interfacce di rete del tipo specificato	No	No
vms network	list-vnics	Elenca le schede di rete virtuali sulla rete	No	No
vms network	ovsinfo	Verifica se OVS è abilitato	No	No
vms image	list	Elenca le immagini	No	No
vms image	edit	Modifica le informazioni dell'immagine	No	No
vms image	delete	Elimina l'immagine	Sì	✅
vms image	list-vms	Visualizza le macchine virtuali che utilizzano questa immagine	No	No
vms repo	list	Elenca gli spazi di archiviazione	No	No
vms repo	get	Visualizza i dettagli dello spazio di archiviazione	No	No
vms repo	update	Aggiorna la configurazione dello spazio di archiviazione	No	No
vms repo	delete	Elimina lo spazio di archiviazione	Sì	✅
vms repo	list-volumes	Elenca i volumi disponibili	No	No
vms repo	list-vms	Elenca le macchine virtuali nello spazio di archiviazione	No	No
vms repo	check-running	Verifica le macchine virtuali in esecuzione sullo spazio di archiviazione	No	No
vms repo	whether-exist-data	Verifica se esistono dati nello spazio di archiviazione	No	No
vms setting	get	Visualizza le impostazioni globali	No	No
vms collectd	hostinfo	Visualizza le informazioni di monitoraggio dell'host	No	No
vms collectd	vminfo	Visualizza le informazioni di monitoraggio della macchina virtuale	No	No
vms collectd	storageinfo	Visualizza le informazioni di monitoraggio dell'archiviazione	No	No

Riferimento dei comandi

Nei comandi, <id> è l'ID della macchina virtuale e corrisponde al GUEST ID nell'output dell'elenco delle macchine virtuali; <network_id>, <image_id> e <repo_id> funzionano in modo analogo e possono essere ottenuti rispettivamente tramite vms network list, vms image list e vms repo list.

Informazioni sugli esempi di output: l'output tabellare di vms tronca i valori dei campi troppo lunghi a una larghezza fissa (terminando con i puntini di sospensione e indipendentemente dalla larghezza del terminale), ad esempio VDISKS, VNICS e ISO IMAGES nella configurazione della macchina virtuale, nonché i nomi delle immagini. Pertanto, in questo documento i comandi che coinvolgono campi lunghi forniscono in modo uniforme un esempio di output --json completo, mentre gli altri comandi forniscono un esempio di output tabellare. Nelle operazioni tramite script si consiglia inoltre di utilizzare in modo uniforme --json.

1. Interrogazione delle macchine virtuali

vms vm list – Elenca le macchine virtuali

Elenca tutte le macchine virtuali del dispositivo locale e il loro stato di base.

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

--limit e --offset sono parametri di paginazione
Colonne di output: nome, ID della macchina virtuale, stato di esecuzione, numero di core della CPU, dimensione della memoria (in KB), indirizzo IP

Esempio di output:

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 comuni di STATUS:

Stato	Descrizione
running	In esecuzione
shutdown	Spenta
saved	In sospensione (lo stato di esecuzione è stato salvato su disco)

vms vm get – Visualizza i dettagli della macchina virtuale

Visualizza la configurazione completa e lo stato di esecuzione della macchina virtuale specificata.

vms vm get <id> --json

L'output include tutti i campi di configurazione e di stato di esecuzione della macchina virtuale
I valori vuoti, come l'assenza di descrizione o di IP, vengono mostrati come stringa vuota
Se la macchina virtuale non esiste, il comando restituisce un errore e mostra le informazioni sull'errore

Esempio di output:

{
  "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 – Elenca le risorse disponibili per creare macchine virtuali

Visualizza le risorse che l'host può fornire, come tipi di firmware, immagini, CPU, memoria, reti, spazi di archiviazione e dispositivi a passaggio diretto, da valutare prima di creare una macchina virtuale.

vms vm list-resource --json

Campi restituiti: max_cpu_num, max_ram_size, usbs, pci_devices, networks, repos, images, video_cards, firmware, keyboard_layout.

Esempio di output:

{
  "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 – Visualizza il registro delle operazioni della macchina virtuale

Visualizza il registro delle operazioni relative alla macchina virtuale specificata (accensione e spegnimento, istantanee, modifica, importazione ed esportazione, ecc.).

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

--limit specifica il numero di voci restituite, per impostazione predefinita 50
--desc ordina in modo decrescente per tempo (attivato per impostazione predefinita)
Ogni voce del registro include ora, livello, categoria, utente dell'operazione e descrizione dell'evento; la descrizione dell'evento è testo completo
La descrizione dell'evento (event) è generata dal servizio VMs localizzata in base alla lingua di sistema del dispositivo; gli esempi di questo documento utilizzano in modo uniforme l'inglese

Esempio di output:

[
  {
    "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)"
  }
]

2. Gestione dell'alimentazione delle macchine virtuali

vms vm poweron – Avvia la macchina virtuale

vms vm poweron <id>

La macchina virtuale deve essere spenta; in caso contrario, viene restituito un errore di conflitto di stato
Output: VM powered on: <id>

vms vm poweroff – Arresta la macchina virtuale

Invia alla macchina virtuale una richiesta di arresto normale, per consentire al sistema di chiudersi in modo controllato.

vms vm poweroff <id> [--yes]

È un'operazione pericolosa: in modalità interattiva richiede la conferma e in modalità non interattiva è obbligatorio aggiungere --yes
La macchina virtuale deve essere in esecuzione; in caso contrario, viene restituito un errore di conflitto di stato

Richiesta di conferma in modalità interattiva:

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

Output: VM powered off: <id>

vms vm force-poweroff – Forza l'arresto della macchina virtuale (rischio elevato)

Forza l'arresto della macchina virtuale, equivalente a togliere direttamente l'alimentazione.

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

È un'operazione ad alto rischio: in modalità interattiva richiede la conferma e in modalità non interattiva è obbligatorio aggiungere --yes
Può causare la perdita di dati all'interno della macchina virtuale; si consiglia di utilizzarlo solo quando la macchina virtuale non risponde

Richiesta di conferma in modalità interattiva:

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

Output: VM force powered off: <id>

vms vm reboot – Riavvia la macchina virtuale

vms vm reboot <id>

Output: VM rebooted: <id>

vms vm pause – Sospende la macchina virtuale

Congela lo stato di esecuzione della macchina virtuale e salva lo stato corrente su disco.

vms vm pause <id>

La macchina virtuale deve essere in esecuzione; in caso contrario, viene restituito un errore di conflitto di stato
Dopo la sospensione, lo stato della macchina virtuale viene mostrato come saved
Output: VM paused: <id>

vms vm resume – Ripristina la macchina virtuale

Riporta la macchina virtuale dallo stato di sospensione allo stato di esecuzione.

vms vm resume <id>

La macchina virtuale deve essere sospesa; in caso contrario, viene restituito un errore di conflitto di stato
Output: VM resumed: <id>

vms vm autorun – Imposta l'avvio automatico all'accensione

Imposta se la macchina virtuale si avvia automaticamente all'accensione dell'host.

vms vm autorun <id> <true|false>

Il secondo parametro deve essere true o false
Il comando legge la configurazione corrente e modifica solo l'interruttore di avvio automatico; le altre impostazioni non vengono influenzate
Output: Auto-start enabled for VM <id> o Auto-start disabled for VM <id>

3. Copia, esportazione ed eliminazione delle macchine virtuali

vms vm clone – Clona la macchina virtuale

Crea una nuova macchina virtuale copiando una macchina virtuale esistente come modello.

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

Nel corpo della richiesta, guest_id è l'ID della macchina virtuale di origine e name (o guest_name) è il nome della nuova macchina virtuale
La macchina virtuale di origine deve essere spenta
--body passa il corpo della richiesta direttamente come stringa JSON; --file legge il corpo della richiesta da un file

vms vm export – Esporta la macchina virtuale

Esporta la macchina virtuale come file OVA, per facilitare il backup o la migrazione verso altre piattaforme di virtualizzazione.

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

Nel corpo della richiesta, guest_id è l'ID della macchina virtuale di origine, target_ova_path è il percorso del file di destinazione e ova_mode è la modalità di compatibilità con VMware opzionale
La macchina virtuale di origine deve essere spenta
L'esportazione è un'attività che richiede tempo; l'esportazione di macchine virtuali di grande capacità richiede più tempo

vms vm delete – Elimina la macchina virtuale (rischio elevato)

Elimina definitivamente la macchina virtuale.

vms vm delete <id> [--yes]

È un'operazione ad alto rischio: in modalità interattiva richiede la conferma e in modalità non interattiva è obbligatorio aggiungere --yes
Dopo l'eliminazione non è possibile recuperarla; verificare in anticipo che i dati all'interno della macchina virtuale siano stati salvati

Richiesta di conferma in modalità interattiva:

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

Output: VM deleted: <id>

4. Dischi virtuali

vms vm disk list – Visualizza i dischi virtuali

Elenca tutti i dischi virtuali della macchina virtuale specificata.

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

Esempio di output:

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

VDISK MODE è il numero del tipo di controller del disco virtuale; 1 indica IDE
I dischi virtuali senza nome vengono mostrati come - nella colonna NAME

5. Gestione delle istantanee

vms vm snapshot list – Elenca le istantanee

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

Esempio di output:

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 è lo stato di esecuzione della macchina virtuale al momento della creazione dell'istantanea
ACTUAL CONSISTENCY è il tipo di coerenza dell'istantanea; filesystem indica coerenza del file system e crash indica coerenza da arresto anomalo

vms vm snapshot create – Crea un'istantanea

Crea un'istantanea della macchina virtuale, per eseguire rapidamente un rollback o un backup dello stato corrente.

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

Corpo della richiesta opzionale: description è la descrizione dell'istantanea e locked indica se bloccarla
Il nome dell'istantanea viene generato automaticamente dal sistema in base all'ora di creazione
Le istantanee occupano spazio di archiviazione; se non vengono ripulite a lungo possono saturare lo spazio di archiviazione, quindi si consiglia di organizzarle periodicamente

vms vm snapshot edit – Modifica l'istantanea

Modifica la descrizione o lo stato di blocco dell'istantanea.

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

Vengono modificati solo i campi presenti nel corpo della richiesta; i campi non presenti mantengono il valore originale; modificare solo la descrizione non cambia lo stato di blocco e viceversa

Esempio di output:

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 – Visualizza la configurazione della macchina virtuale dell'istantanea

Visualizza la configurazione della macchina virtuale salvata nell'istantanea.

vms vm snapshot config <id> <snapshot_name>

<id> è l'ID della macchina virtuale e <snapshot_name> è il nome dell'istantanea, ottenibile tramite vms vm snapshot list <id>.

Esempio di output:

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 – Visualizza in anteprima la coerenza dell'istantanea

Visualizza in anteprima il tipo di coerenza che si può ottenere prima di creare un'istantanea, per aiutare a stabilire se il momento attuale è adatto a crearla.

vms vm snapshot consistency <id>

Esempio di output:

PROPERTY          VALUE
CONSISTENCY TYPE  filesystem
REASON            vm_shutdown
VM STATE          shutdown

Creando un'istantanea con la macchina virtuale spenta si ottiene un'istantanea con coerenza del file system; con la macchina in esecuzione di norma si può ottenere solo un'istantanea con coerenza da arresto anomalo.

6. Console remota

vms vm link – Ottiene le informazioni di connessione VNC

Ottiene le informazioni di connessione della console VNC della macchina virtuale, per aprire la console remota nel browser.

vms vm link <id> --json

La macchina virtuale deve essere in esecuzione o in sospensione; in caso contrario, viene restituito un errore di conflitto di stato

Esempio di output:

{
  "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 è il percorso della console relativo all'indirizzo di gestione del NAS, port è la porta del servizio della console e https indica se è necessario accedere tramite HTTPS
Nell'output JSON, il carattere & presente nell'URL viene codificato come \u0026

7. Gestione delle reti virtuali

I tipi di rete si dividono in due:

Tipo	Descrizione
Privata (private)	Rete interna che consente solo la comunicazione tra le macchine virtuali del dispositivo locale, senza essere associata a una scheda di rete fisica
Esterna (external)	Rete associata a una scheda di rete fisica, tramite la quale le macchine virtuali possono comunicare con l'esterno

vms network list – Elenca le reti virtuali

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

Esempio di output:

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 è il numero di macchine virtuali collegate a questa rete e NUM INTERFACES è il numero di schede di rete fisiche selezionate

vms network get – Visualizza i dettagli della rete virtuale

vms network get <network_id> --json

Esempio di output:

{
  "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 è la informazione delle schede di rete associate a questa rete, organizzata per ID host, e checked indica se la scheda di rete è selezionata
metadata registra l'ora di creazione e di aggiornamento della rete

vms network create – Crea una rete virtuale

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

Creazione di una rete privata:

Il corpo della richiesta deve includere name, type (private) e host_name o host_id, per specificare su quale host creare la rete
Prima della creazione è possibile visualizzare gli host disponibili tramite vms network list-interfaces private

Creazione di una rete esterna:

Il corpo della richiesta deve includere name, type (external) e vlan_id e specificare almeno una scheda di rete fisica
È possibile specificare la scheda di rete tramite interface_name (come LAN 1) o interface_id; se il nome della scheda di rete non è univoco tra host, occorre abbinarlo a host_name
Prima della creazione è possibile visualizzare le schede di rete disponibili tramite vms network list-interfaces external

L'output è la informazione della rete dopo la creazione, con la stessa struttura di 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
}

Se non viene specificata alcuna scheda di rete, il comando mostra un avviso:

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 – Aggiorna la rete virtuale

Vengono inviati solo i campi da modificare; i campi non inviati mantengono il valore originale.

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

Il corpo della richiesta deve includere network_id
Il comando legge prima la configurazione corrente della rete e unisce i campi inviati; il nome della rete e le schede di rete selezionate non vengono svuotati
L'output è la informazione della rete dopo l'aggiornamento

vms network delete – Elimina la rete virtuale (rischio elevato)

vms network delete <network_id> [--yes]

È un'operazione ad alto rischio: in modalità interattiva richiede la conferma e in modalità non interattiva è obbligatorio aggiungere --yes
L'eliminazione della rete disconnette tutte le macchine virtuali collegate ad essa
Si consiglia di verificare prima le macchine virtuali collegate tramite vms network list-vnics <network_id>

Richiesta di conferma in modalità interattiva:

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

Output: Network deleted: <network_id>

vms network list-interfaces – Elenca le interfacce di rete

Elenca le interfacce di rete del tipo specificato.

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

external restituisce le schede di rete fisiche disponibili sull'host
private restituisce le informazioni sugli host utilizzabili per creare reti private

Esempio di output (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

Esempio di output (private):

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

vms network list-vnics – Elenca le schede di rete virtuali sulla rete

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

Esempio di output:

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 – Visualizza lo stato di OVS

Verifica se lo switch virtuale Open vSwitch è abilitato.

vms network ovsinfo [--json]

Esempio di output:

PROPERTY  VALUE
RESULT    true

Se VALUE è true, OVS è abilitato.

8. Gestione delle immagini

vms image list – Elenca le immagini

Elenca i file immagine di sistema disponibili per creare macchine virtuali.

vms image list --json

image_name è il nome dell'immagine e file_name è il nome file corrispondente
type è il formato dell'immagine, come iso o qcow2
status è lo stato dell'immagine; available indica che è disponibile
repos è lo spazio di archiviazione in cui si trova l'immagine
progress è l'avanzamento dell'attività di elaborazione dell'immagine; 0 indica che non ci sono attività in corso

Esempio di output:

{
  "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 – Modifica l'immagine

Modifica il nome dell'immagine o regola lo spazio di archiviazione in cui si trova.

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

Il corpo della richiesta deve includere image_id e repos; repos è l'elenco completo degli spazi di archiviazione di destinazione dell'immagine e non può essere vuoto
image_name, file_name, type e file_size sono campi opzionali; se non vengono forniti, si mantengono i valori correnti
Se repos è vuoto, l'immagine verrebbe rimossa da tutti gli spazi di archiviazione; il comando rifiuta la richiesta prima di eseguirla
Output: Image updated

vms image delete – Elimina l'immagine (rischio elevato)

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

--image-id è obbligatorio
È un'operazione ad alto rischio: in modalità interattiva richiede la conferma e in modalità non interattiva è obbligatorio aggiungere --yes
L'eliminazione dell'immagine non influisce sulle macchine virtuali già create, ma influisce sulla successiva creazione di macchine virtuali basate su questa immagine
Si consiglia di verificare prima l'utilizzo tramite vms image list-vms --image-id <image_id>

Richiesta di conferma in modalità interattiva:

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

Output: Image deleted: <image_id>

vms image list-vms – Visualizza le macchine virtuali che utilizzano questa immagine

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

Esempio di output:

GUEST NAME
1454486

Prima di eliminare un'immagine è possibile eseguire questo comando per verificare l'ambito dell'impatto; se nessuna macchina virtuale utilizza l'immagine, l'output è vuoto.

9. Gestione degli spazi di archiviazione

vms repo list – Elenca gli spazi di archiviazione

vms repo list [--json]

Esempio di output:

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 – Visualizza i dettagli dello spazio di archiviazione

vms repo get <repo_id> [--json]

Esempio di output:

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 è il volume in cui si trova lo spazio di archiviazione
SOFT LIMIT e HARD LIMIT sono le soglie di avviso di capacità (in percentuale)
ENABLE LOWER NOTIFY indica se abilitare il promemoria di capacità insufficiente

vms repo update – Aggiorna lo spazio di archiviazione

Vengono inviati solo i campi da modificare; i campi non inviati mantengono il valore originale.

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

L'ID dello spazio di archiviazione può essere passato tramite repo_id o repoId
Il comando legge prima la configurazione corrente e unisce i campi inviati; le altre impostazioni non vengono perse
L'output è la informazione dello spazio di archiviazione dopo l'aggiornamento

vms repo delete – Elimina lo spazio di archiviazione (rischio elevato)

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

Il secondo parametro è need_save_data: true indica che vengono conservati i file di dati sul disco, false indica che vengono eliminati insieme ai dati
È un'operazione ad alto rischio: in modalità interattiva richiede la conferma e in modalità non interattiva è obbligatorio aggiungere --yes
L'eliminazione dello spazio di archiviazione rimuove anche le macchine virtuali e le immagini in esso contenute; si consiglia di eseguire prima vms repo check-running e vms repo whether-exist-data per verificare l'ambito dell'impatto

Richiesta di conferma in modalità interattiva:

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

Output: Repository deleted: <repo_id>

vms repo list-volumes – Elenca i volumi disponibili

Elenca i volumi disponibili per creare spazi di archiviazione.

vms repo list-volumes [--json]

Esempio di output:

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 – Elenca le macchine virtuali nello spazio di archiviazione

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

L'ID dello spazio di archiviazione può essere passato tramite repo_id o repoId
Il comando ottiene prima l'oggetto dello spazio di archiviazione e poi interroga le sue macchine virtuali, rendendo il risultato più affidabile

vms repo check-running – Verifica le macchine virtuali in esecuzione sullo spazio di archiviazione

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

Viene eseguito prima di eliminare lo spazio di archiviazione per verificare che non vi siano macchine virtuali in esecuzione; se non ci sono macchine virtuali in esecuzione, l'output è vuoto.

vms repo whether-exist-data – Verifica se esistono dati nello spazio di archiviazione

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

Viene eseguito prima di eliminare lo spazio di archiviazione per verificare se vi sono ancora dati al suo interno; è coerente con il controllo preliminare all'eliminazione di uno spazio di archiviazione nell'interfaccia web.

10. Impostazioni globali

vms setting get – Visualizza le impostazioni globali

Visualizza la configurazione globale dell'applicazione VMs.

vms setting get [--json]

Esempio di output:

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

HOST SHUTDOWN BEHAVIOR è il modo di gestire le macchine virtuali quando l'host si spegne
KB LAYOUT è la disposizione della tastiera della macchina virtuale

11. Interrogazione delle informazioni di monitoraggio

vms collectd hostinfo – Visualizza le informazioni di monitoraggio dell'host

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

Esempio di output:

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

vms collectd vminfo – Visualizza le informazioni di monitoraggio della macchina virtuale

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

Esempio di output:

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 – Visualizza le informazioni di monitoraggio dell'archiviazione

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

Esempio di output:

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

Modalità interattiva e non interattiva

La CLI determina se è attualmente in esecuzione in un ambiente terminale e adotta comportamenti diversi:

Modalità interattiva (ambiente terminale)

Le operazioni pericolose mostrano una richiesta di conferma; l'opzione predefinita è No
Digitare y o Y per continuare; digitare n o premere Invio per annullare
In caso di annullamento viene generato Operation cancelled e il codice di uscita è 99

Modalità non interattiva (script/automazione)

Le operazioni pericolose devono utilizzare --yes per saltare la conferma; in caso contrario il comando genera direttamente un errore e restituisce il codice di uscita 1
In assenza di un ambiente terminale non attende l'input, il che lo rende adatto a script e attività pianificate
Si consiglia di gestire esplicitamente i codici di uscita negli script, per distinguere successo, errore e conflitto di stato

Formato di output JSON

I comandi di interrogazione supportano il parametro --json, che genera dati JSON normalizzati per facilitare l'analisi da parte dei programmi.

Convenzioni di formato:

I nomi dei campi utilizzano snake_case
I valori booleani sono true/false
L'ora utilizza il formato ISO 8601, con precisione al nanosecondo e offset del fuso orario UTC+8 (ad esempio 2026-09-02T11:43:51.176535374+08:00)
L'output JSON viene inviato a stdout e i messaggi di errore a stderr
I campi lunghi troncati nell'output tabellare sono completi nell'output JSON

Esempio:

vms setting get --json

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

La struttura JSON varia leggermente tra i comandi: vms vm list, vms vm snapshot list e vms vm logs generano direttamente un array; gli altri comandi di tipo elenco generano un oggetto contenente totalCount e un campo dati, il cui nome varia in base alla risorsa (come items, hosts, vms o storage). Ad esempio, 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"
    }
  }
}

L'output JSON di alcuni comandi è un valore semplice; ad esempio vms network ovsinfo --json genera true e vms vm pause --json genera null.

Descrizione dei codici di uscita

Codice di uscita	Significato	Scenario tipico
0	Successo	Il comando viene completato correttamente
1	Errore di parametro	Manca un parametro obbligatorio, il formato del parametro è errato o non è stato aggiunto `--yes`
3	Risorsa inesistente	La convalida preliminare del comando non è superata; ad esempio, l'immagine specificata non esiste
4	Conflitto di stato	Lo stato corrente della macchina virtuale non consente l'operazione (ad esempio, arrestare una macchina virtuale già spenta)
6	Errore di connessione	Non è possibile connettersi al servizio VMs o il percorso del socket è errato
7	Timeout	Il tempo di attesa della richiesta è scaduto; può essere regolato tramite `--timeout`
9	Errore di esecuzione	Il backend restituisce un errore (il messaggio di errore include code_num e la descrizione dell'errore)
99	Annullato dall'utente	È stato scelto No nella conferma interattiva o è stato premuto Invio direttamente

Esempio:

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

Esempi di casi d'uso

Operazioni quotidiane

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

Operazioni in blocco tramite script

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

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

Controllo prima dell'eliminazione

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

Invocazione da strumenti di IA

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

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

Sviluppo interno e integrazione di sistemi

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

Domande frequenti

D: La CLI richiede un'installazione aggiuntiva?

No. La CLI viene installata insieme all'applicazione VMs; una volta abilitata l'applicazione, è sufficiente eseguire il comando vms per utilizzarla.

D: La CLI deve essere usata obbligatoriamente tramite SSH?

No. La CLI può essere invocata da qualsiasi terminale a riga di comando, inclusi terminale locale, SSH remoto, script, strumenti di IA e così via.

D: La CLI può gestire le macchine virtuali di altri dispositivi?

No. La CLI comunica con il servizio VMs tramite l'unix socket locale e serve solo a gestire le macchine virtuali del dispositivo locale.

D: Perché alcuni comandi richiedono la conferma e altri no?

Operazioni come eliminare una macchina virtuale, eliminare una rete, eliminare un'immagine, eliminare uno spazio di archiviazione e l'arresto (poweroff, force-poweroff) influiscono sui dati o sui servizi, per cui richiedono la conferma per impostazione predefinita; i comandi di avvio, riavvio, sospensione, ripristino e interrogazione non hanno questo tipo di limitazione.

D: Come si confermano le operazioni pericolose in modalità non interattiva?

Tutte le operazioni pericolose devono aggiungere il parametro --yes; in caso contrario il comando genera un errore e termina (codice di uscita 1).

D: Come si determina in uno script se un comando è stato eseguito correttamente?

Tramite il codice di uscita: 0 indica successo e un valore diverso da 0 indica errore. È anche possibile analizzare il contenuto dell'output di --json.

D: Perché l'elenco dell'output di --json è un oggetto?

L'output JSON di alcuni comandi è organizzato in un oggetto per ID, con un campo totalCount allegato, il che facilita l'accesso diretto per ID.

Ulteriori informazioni

Tutti i comandi supportano --help per consultare l'uso dettagliato:

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

Introduzione​

Caratteristiche principali​

Guida rapida​

Opzioni globali​

Esempio di informazioni sulla versione​

Ambiente di esecuzione​

Tabella riepilogativa dei comandi​

Riferimento dei comandi​

1. Interrogazione delle macchine virtuali​

vms vm list – Elenca le macchine virtuali​

vms vm get – Visualizza i dettagli della macchina virtuale​

vms vm list-resource – Elenca le risorse disponibili per creare macchine virtuali​

vms vm logs – Visualizza il registro delle operazioni della macchina virtuale​

2. Gestione dell'alimentazione delle macchine virtuali​

vms vm poweron – Avvia la macchina virtuale​

vms vm poweroff – Arresta la macchina virtuale​

vms vm force-poweroff – Forza l'arresto della macchina virtuale (rischio elevato)​

vms vm reboot – Riavvia la macchina virtuale​

vms vm pause – Sospende la macchina virtuale​

vms vm resume – Ripristina la macchina virtuale​

vms vm autorun – Imposta l'avvio automatico all'accensione​

3. Copia, esportazione ed eliminazione delle macchine virtuali​

vms vm clone – Clona la macchina virtuale​

vms vm export – Esporta la macchina virtuale​

vms vm delete – Elimina la macchina virtuale (rischio elevato)​

4. Dischi virtuali​

vms vm disk list – Visualizza i dischi virtuali​

5. Gestione delle istantanee​

vms vm snapshot list – Elenca le istantanee​

vms vm snapshot create – Crea un'istantanea​

vms vm snapshot edit – Modifica l'istantanea​

vms vm snapshot config – Visualizza la configurazione della macchina virtuale dell'istantanea​

vms vm snapshot consistency – Visualizza in anteprima la coerenza dell'istantanea​

6. Console remota​

vms vm link – Ottiene le informazioni di connessione VNC​

7. Gestione delle reti virtuali​

vms network list – Elenca le reti virtuali​

vms network get – Visualizza i dettagli della rete virtuale​

vms network create – Crea una rete virtuale​

vms network update – Aggiorna la rete virtuale​

vms network delete – Elimina la rete virtuale (rischio elevato)​

vms network list-interfaces – Elenca le interfacce di rete​

vms network list-vnics – Elenca le schede di rete virtuali sulla rete​

vms network ovsinfo – Visualizza lo stato di OVS​

8. Gestione delle immagini​

vms image list – Elenca le immagini​

vms image edit – Modifica l'immagine​

vms image delete – Elimina l'immagine (rischio elevato)​

vms image list-vms – Visualizza le macchine virtuali che utilizzano questa immagine​

9. Gestione degli spazi di archiviazione​

vms repo list – Elenca gli spazi di archiviazione​

vms repo get – Visualizza i dettagli dello spazio di archiviazione​

vms repo update – Aggiorna lo spazio di archiviazione​

vms repo delete – Elimina lo spazio di archiviazione (rischio elevato)​

vms repo list-volumes – Elenca i volumi disponibili​

vms repo list-vms – Elenca le macchine virtuali nello spazio di archiviazione​

vms repo check-running – Verifica le macchine virtuali in esecuzione sullo spazio di archiviazione​

vms repo whether-exist-data – Verifica se esistono dati nello spazio di archiviazione​

10. Impostazioni globali​

vms setting get – Visualizza le impostazioni globali​

11. Interrogazione delle informazioni di monitoraggio​

vms collectd hostinfo – Visualizza le informazioni di monitoraggio dell'host​

vms collectd vminfo – Visualizza le informazioni di monitoraggio della macchina virtuale​

vms collectd storageinfo – Visualizza le informazioni di monitoraggio dell'archiviazione​

Modalità interattiva e non interattiva​

Modalità interattiva (ambiente terminale)​

Modalità non interattiva (script/automazione)​

Formato di output JSON​

Descrizione dei codici di uscita​

Esempi di casi d'uso​

Operazioni quotidiane​

Operazioni in blocco tramite script​

Backup e ispezione​

Controllo prima dell'eliminazione​

Invocazione da strumenti di IA​

Sviluppo interno e integrazione di sistemi​

Domande frequenti​

Ulteriori informazioni​

Introduzione

Caratteristiche principali

Guida rapida

Opzioni globali

Esempio di informazioni sulla versione

Ambiente di esecuzione

Tabella riepilogativa dei comandi

Riferimento dei comandi

1. Interrogazione delle macchine virtuali

vms vm list – Elenca le macchine virtuali

vms vm get – Visualizza i dettagli della macchina virtuale

vms vm list-resource – Elenca le risorse disponibili per creare macchine virtuali

vms vm logs – Visualizza il registro delle operazioni della macchina virtuale

2. Gestione dell'alimentazione delle macchine virtuali

vms vm poweron – Avvia la macchina virtuale

vms vm poweroff – Arresta la macchina virtuale

vms vm force-poweroff – Forza l'arresto della macchina virtuale (rischio elevato)

vms vm reboot – Riavvia la macchina virtuale

vms vm pause – Sospende la macchina virtuale

vms vm resume – Ripristina la macchina virtuale

vms vm autorun – Imposta l'avvio automatico all'accensione

3. Copia, esportazione ed eliminazione delle macchine virtuali

vms vm clone – Clona la macchina virtuale

vms vm export – Esporta la macchina virtuale

vms vm delete – Elimina la macchina virtuale (rischio elevato)

4. Dischi virtuali

vms vm disk list – Visualizza i dischi virtuali

5. Gestione delle istantanee

vms vm snapshot list – Elenca le istantanee

vms vm snapshot create – Crea un'istantanea

vms vm snapshot edit – Modifica l'istantanea

vms vm snapshot config – Visualizza la configurazione della macchina virtuale dell'istantanea

vms vm snapshot consistency – Visualizza in anteprima la coerenza dell'istantanea

6. Console remota

vms vm link – Ottiene le informazioni di connessione VNC

7. Gestione delle reti virtuali

vms network list – Elenca le reti virtuali

vms network get – Visualizza i dettagli della rete virtuale

vms network create – Crea una rete virtuale

vms network update – Aggiorna la rete virtuale

vms network delete – Elimina la rete virtuale (rischio elevato)

vms network list-interfaces – Elenca le interfacce di rete

vms network list-vnics – Elenca le schede di rete virtuali sulla rete

vms network ovsinfo – Visualizza lo stato di OVS

8. Gestione delle immagini

vms image list – Elenca le immagini

vms image edit – Modifica l'immagine

vms image delete – Elimina l'immagine (rischio elevato)

vms image list-vms – Visualizza le macchine virtuali che utilizzano questa immagine

9. Gestione degli spazi di archiviazione

vms repo list – Elenca gli spazi di archiviazione

vms repo get – Visualizza i dettagli dello spazio di archiviazione

vms repo update – Aggiorna lo spazio di archiviazione

vms repo delete – Elimina lo spazio di archiviazione (rischio elevato)

vms repo list-volumes – Elenca i volumi disponibili

vms repo list-vms – Elenca le macchine virtuali nello spazio di archiviazione

vms repo check-running – Verifica le macchine virtuali in esecuzione sullo spazio di archiviazione

vms repo whether-exist-data – Verifica se esistono dati nello spazio di archiviazione

10. Impostazioni globali

vms setting get – Visualizza le impostazioni globali

11. Interrogazione delle informazioni di monitoraggio

vms collectd hostinfo – Visualizza le informazioni di monitoraggio dell'host

vms collectd vminfo – Visualizza le informazioni di monitoraggio della macchina virtuale

vms collectd storageinfo – Visualizza le informazioni di monitoraggio dell'archiviazione

Modalità interattiva e non interattiva

Modalità interattiva (ambiente terminale)

Modalità non interattiva (script/automazione)

Formato di output JSON

Descrizione dei codici di uscita

Esempi di casi d'uso

Operazioni quotidiane

Operazioni in blocco tramite script

Backup e ispezione

Controllo prima dell'eliminazione

Invocazione da strumenti di IA

Sviluppo interno e integrazione di sistemi

Domande frequenti

Ulteriori informazioni