Version: TOS 7

VMs CLI

Introduction

VMs CLI est l'outil de gestion en ligne de commande de l'application de virtualisation TerraMaster VMs, offrant des capacités d'interrogation et d'exploitation cohérentes avec l'interface de gestion web. Le CLI communique avec le service VMs via un unix socket local, adopte une interface de commande normalisée et un format de sortie JSON, et peut être intégré dans des scripts, des opérations automatisées et des workflows de développement secondaire.

Caractéristiques principales

Prêt à l'emploi : installé en même temps que l'application VMs, aucune installation supplémentaire requise
Modes d'appel flexibles : prend en charge les terminaux locaux, le SSH distant, les scripts, les outils d'IA et de nombreux autres canaux d'appel
Double mode interactif et non interactif : adapté à la fois à la maintenance quotidienne des administrateurs et aux scripts et tâches automatisées
Prise en charge de la sortie JSON : pratique pour l'analyse par programme et l'intégration automatisée
Communication locale : communique avec le service VMs uniquement via un unix socket local et n'expose aucun port vers l'extérieur
Confirmation secondaire des opérations dangereuses : les opérations telles que la suppression d'une machine virtuelle ou d'un réseau nécessitent une confirmation par défaut

Démarrage rapide

# 在终端中执行（可通过本地终端、SSH、脚本、AI 工具等任意命令行途径）
vms --help

# 查看虚拟机列表
vms vm list

# 查看虚拟机详情
vms vm get <id>

# 以 JSON 格式输出（便于脚本解析）
vms vm list --json

Exemple de sortie de 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    -

Options globales

Les options suivantes s'appliquent à toutes les commandes :

Option	Abréviation	Description
`--help`	`-h`	Affiche les informations d'aide de la commande
`--version`	`-v`	Affiche le numéro de version (peut être combiné avec `--json` pour afficher des informations structurées)
`--json`	-	Affiche la sortie au format JSON
`--yes`	`-y`	Ignore l'invite de confirmation des opérations dangereuses (obligatoire en mode non interactif)
`--debug`	-	Active la sortie de débogage et affiche le déroulement détaillé de l'exécution
`--socket <path>`	-	Chemin du unix socket VMs, par défaut `/var/api/VMs.sock`
`--timeout <duration>`	-	Délai d'expiration de la requête, par défaut 30s

Exemple d'informations de version

vms --version

vms CLI v1.0.058

vms --version --json

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

Environnement d'exécution

VMs CLI est installé en même temps que l'application VMs. Lorsque l'application est activée, elle crée un lien du CLI dans le répertoire PATH par défaut du système, de sorte qu'il peut être utilisé directement après une connexion via SSH.

Élément	Description
Fichier CLI	`/Volume1/@apps/VMs/bin/vms`
Chemin de commande	`/usr/local/sbin/vms` (déjà dans le PATH système)
Mode de communication	unix socket local, par défaut `/var/api/VMs.sock`
Public concerné	Administrateurs connectés à la machine locale

Remarques :

Le CLI sert à gérer les machines virtuelles de la machine locale et ne prend pas en charge la gestion à distance d'autres appareils via le CLI.
Le backend renvoie toujours HTTP 200 ; la réussite d'une commande est déterminée par le champ code du corps de la réponse, que le CLI convertit en code de sortie.
Les opérations dangereuses (suppression d'une machine virtuelle, suppression d'un réseau, suppression d'une image, suppression d'un référentiel) demandent une confirmation en mode interactif ; en mode non interactif, --yes doit être transmis explicitement.

Tableau récapitulatif des commandes

Voici un récapitulatif de référence rapide de toutes les commandes vms :

Commande parente	Sous-commande	Description de la fonction	Confirmation requise	Risque élevé
vms	--version	Affiche les informations de version	Non	Non
vms vm	list	Liste toutes les machines virtuelles	Non	Non
vms vm	get	Affiche les détails d'une machine virtuelle spécifiée	Non	Non
vms vm	list-resource	Liste les ressources disponibles pour créer une machine virtuelle	Non	Non
vms vm	logs	Affiche les journaux d'opérations d'une machine virtuelle	Non	Non
vms vm	poweron	Démarre une machine virtuelle	Non	Non
vms vm	poweroff	Arrête une machine virtuelle (arrêt normal)	Oui	Non
vms vm	force-poweroff	Force l'arrêt d'une machine virtuelle	Oui	✅
vms vm	reboot	Redémarre une machine virtuelle	Non	Non
vms vm	pause	Met en pause une machine virtuelle	Non	Non
vms vm	resume	Reprend une machine virtuelle en pause	Non	Non
vms vm	autorun	Définit le démarrage automatique au boot	Non	Non
vms vm	clone	Clone une machine virtuelle	Non	Non
vms vm	export	Exporte une machine virtuelle au format de fichier OVA	Non	Non
vms vm	delete	Supprime une machine virtuelle	Oui	✅
vms vm disk	list	Affiche les disques virtuels d'une machine virtuelle	Non	Non
vms vm snapshot	list	Liste les snapshots d'une machine virtuelle	Non	Non
vms vm snapshot	create	Crée un snapshot	Non	Non
vms vm snapshot	edit	Modifie la description et l'état de verrouillage du snapshot	Non	Non
vms vm snapshot	config	Affiche la configuration de la machine virtuelle enregistrée dans le snapshot	Non	Non
vms vm snapshot	consistency	Prévisualise la cohérence du snapshot	Non	Non
vms vm	link	Obtient les informations de connexion à la console VNC	Non	Non
vms network	list	Liste les réseaux virtuels	Non	Non
vms network	get	Affiche les détails d'un réseau virtuel	Non	Non
vms network	create	Crée un réseau virtuel	Non	Non
vms network	update	Met à jour un réseau virtuel	Non	Non
vms network	delete	Supprime un réseau virtuel	Oui	✅
vms network	list-interfaces	Liste les interfaces réseau d'un type spécifié	Non	Non
vms network	list-vnics	Liste les cartes réseau virtuelles d'un réseau	Non	Non
vms network	ovsinfo	Indique si OVS est activé	Non	Non
vms image	list	Liste les images	Non	Non
vms image	edit	Modifie les informations de l'image	Non	Non
vms image	delete	Supprime une image	Oui	✅
vms image	list-vms	Affiche les machines virtuelles utilisant l'image	Non	Non
vms repo	list	Liste les référentiels	Non	Non
vms repo	get	Affiche les détails d'un référentiel	Non	Non
vms repo	update	Met à jour la configuration du référentiel	Non	Non
vms repo	delete	Supprime un référentiel	Oui	✅
vms repo	list-volumes	Liste les volumes disponibles	Non	Non
vms repo	list-vms	Liste les machines virtuelles d'un référentiel	Non	Non
vms repo	check-running	Vérifie les machines virtuelles en cours d'exécution sur un référentiel	Non	Non
vms repo	whether-exist-data	Vérifie la présence de données dans un référentiel	Non	Non
vms setting	get	Affiche les paramètres globaux	Non	Non
vms collectd	hostinfo	Affiche les informations de supervision de l'hôte	Non	Non
vms collectd	vminfo	Affiche les informations de supervision de la machine virtuelle	Non	Non
vms collectd	storageinfo	Affiche les informations de supervision du stockage	Non	Non

Référence des commandes

Dans les commandes, <id> est l'ID de la machine virtuelle, correspondant au GUEST ID dans la sortie de la liste des machines virtuelles ; <network_id>, <image_id> et <repo_id> sont analogues et peuvent être obtenus respectivement via vms network list, vms image list et vms repo list.

À propos des exemples de sortie : la sortie tabulaire de vms tronque les valeurs de champ trop longues à une largeur fixe (se terminant par des points de suspension, indépendamment de la largeur du terminal), par exemple VDISKS, VNICS, ISO IMAGES dans la configuration de la machine virtuelle, ainsi que les noms d'images. Par conséquent, dans ce document, les commandes comportant des champs longs fournissent uniformément un exemple complet de sortie --json, tandis que les autres commandes fournissent un exemple de sortie tabulaire. Lors du traitement par script, il est également recommandé d'utiliser uniformément --json.

I. Interrogation des machines virtuelles

vms vm list – Lister les machines virtuelles

Liste toutes les machines virtuelles de la machine locale et leur état de base.

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

--limit et --offset sont des paramètres de pagination
Colonnes de sortie : nom, ID de la machine virtuelle, état d'exécution, nombre de cœurs CPU, taille de mémoire (en KB), adresse IP

Exemple de sortie :

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    -

Valeurs courantes de STATUS :

État	Description
running	En cours d'exécution
shutdown	Arrêté
saved	En pause (l'état d'exécution a été enregistré sur le disque)

vms vm get – Afficher les détails d'une machine virtuelle

Affiche la configuration complète et l'état d'exécution d'une machine virtuelle spécifiée.

vms vm get <id> --json

La sortie contient tous les champs de configuration et d'état d'exécution de la machine virtuelle
Les valeurs vides telles qu'une absence de description ou d'IP s'affichent sous forme de chaîne vide
Si la machine virtuelle n'existe pas, la commande renvoie une erreur et affiche un message d'erreur

Exemple de sortie :

{
  "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 – Lister les ressources disponibles pour créer une machine virtuelle

Affiche les ressources que l'hôte peut fournir, telles que les types de firmware, les images, le CPU, la mémoire, les réseaux, les référentiels et les périphériques pouvant être transmis (passthrough), afin d'évaluer avant de créer une machine virtuelle.

vms vm list-resource --json

Champs renvoyés : max_cpu_num, max_ram_size, usbs, pci_devices, networks, repos, images, video_cards, firmware, keyboard_layout.

Exemple de sortie :

{
  "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 – Afficher les journaux d'opérations d'une machine virtuelle

Affiche les journaux d'opérations liés à une machine virtuelle spécifiée (démarrage/arrêt, snapshots, modification, import/export, etc.).

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

--limit spécifie le nombre d'entrées renvoyées, par défaut 50
--desc trie par ordre chronologique inverse (activé par défaut)
Chaque entrée de journal contient l'heure, le niveau, la catégorie, l'utilisateur opérateur et la description de l'événement ; la description de l'événement est le texte complet
La description de l'événement (event) est localisée par le service VMs selon la langue système de l'appareil ; les exemples de ce document utilisent uniformément l'anglais

Exemple de sortie :

[
  {
    "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. Gestion de l'alimentation des machines virtuelles

vms vm poweron – Démarrer une machine virtuelle

vms vm poweron <id>

La machine virtuelle doit être à l'arrêt, sinon une erreur de conflit d'état est renvoyée
Sortie : VM powered on: <id>

vms vm poweroff – Arrêter une machine virtuelle

Envoie une demande d'arrêt normale à la machine virtuelle, permettant au système de s'arrêter proprement.

vms vm poweroff <id> [--yes]

Il s'agit d'une opération dangereuse : le mode interactif demande une confirmation, le mode non interactif doit ajouter --yes
La machine virtuelle doit être en cours d'exécution, sinon une erreur de conflit d'état est renvoyée

Invite de confirmation en mode interactif :

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

Sortie : VM powered off: <id>

vms vm force-poweroff – Forcer l'arrêt d'une machine virtuelle (risque élevé)

Force l'arrêt de la machine virtuelle, équivalent à couper directement l'alimentation.

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

Il s'agit d'une opération à risque élevé : le mode interactif demande une confirmation, le mode non interactif doit ajouter --yes
Elle peut entraîner une perte de données dans la machine virtuelle ; il est recommandé de l'utiliser uniquement lorsque la machine virtuelle ne répond pas

Invite de confirmation en mode interactif :

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

Sortie : VM force powered off: <id>

vms vm reboot – Redémarrer une machine virtuelle

vms vm reboot <id>

Sortie : VM rebooted: <id>

vms vm pause – Mettre en pause une machine virtuelle

Gèle l'état d'exécution de la machine virtuelle et enregistre l'état actuel sur le disque.

vms vm pause <id>

La machine virtuelle doit être en cours d'exécution, sinon une erreur de conflit d'état est renvoyée
Après la mise en pause, l'état de la machine virtuelle s'affiche comme saved
Sortie : VM paused: <id>

vms vm resume – Reprendre une machine virtuelle

Rétablit la machine virtuelle de l'état de pause à l'état d'exécution.

vms vm resume <id>

La machine virtuelle doit être en pause, sinon une erreur de conflit d'état est renvoyée
Sortie : VM resumed: <id>

vms vm autorun – Définir le démarrage automatique au boot

Définit si la machine virtuelle démarre automatiquement lorsque l'hôte démarre.

vms vm autorun <id> <true|false>

Le deuxième paramètre doit être true ou false
La commande lit la configuration actuelle et ne modifie que le commutateur de démarrage automatique ; les autres configurations ne sont pas affectées
Sortie : Auto-start enabled for VM <id> ou Auto-start disabled for VM <id>

III. Clonage, export et suppression des machines virtuelles

vms vm clone – Cloner une machine virtuelle

Crée une nouvelle machine virtuelle en copiant une machine virtuelle existante comme modèle.

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

Dans le corps de la requête, guest_id est l'ID de la machine virtuelle source et name (ou guest_name) est le nom de la nouvelle machine virtuelle
La machine virtuelle source doit être à l'arrêt
--body transmet le corps de la requête directement sous forme de chaîne JSON, et --file lit le corps de la requête depuis un fichier

vms vm export – Exporter une machine virtuelle

Exporte la machine virtuelle sous forme de fichier OVA, pour la sauvegarde ou la migration vers d'autres plateformes de virtualisation.

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

Dans le corps de la requête, guest_id est l'ID de la machine virtuelle source, target_ova_path est le chemin du fichier cible et ova_mode est un mode de compatibilité VMware facultatif
La machine virtuelle source doit être à l'arrêt
L'export est une tâche longue ; l'export d'une machine virtuelle de grande capacité prend beaucoup de temps

vms vm delete – Supprimer une machine virtuelle (risque élevé)

Supprime définitivement une machine virtuelle.

vms vm delete <id> [--yes]

Il s'agit d'une opération à risque élevé : le mode interactif demande une confirmation, le mode non interactif doit ajouter --yes
Elle ne peut pas être récupérée après suppression ; veuillez confirmer au préalable que les données de la machine virtuelle ont été sauvegardées

Invite de confirmation en mode interactif :

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

Sortie : VM deleted: <id>

IV. Disques virtuels

vms vm disk list – Afficher les disques virtuels

Liste tous les disques virtuels d'une machine virtuelle spécifiée.

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

Exemple de sortie :

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

VDISK MODE est le numéro de type du contrôleur de disque virtuel ; 1 indique IDE
Un disque virtuel sans nom s'affiche comme - dans la colonne NAME

V. Gestion des snapshots

vms vm snapshot list – Lister les snapshots

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

Exemple de sortie :

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 est l'état d'exécution de la machine virtuelle au moment de la création du snapshot
ACTUAL CONSISTENCY est le type de cohérence du snapshot ; filesystem indique une cohérence de système de fichiers et crash une cohérence de plantage

vms vm snapshot create – Créer un snapshot

Crée un snapshot pour une machine virtuelle, afin de revenir rapidement en arrière ou de sauvegarder l'état actuel.

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

Le corps de la requête est facultatif : description est la description du snapshot et locked indique s'il faut verrouiller
Le nom du snapshot est généré automatiquement par le système en fonction de l'heure de création
Les snapshots occupent de l'espace de stockage ; s'ils ne sont pas nettoyés pendant longtemps, ils peuvent saturer l'espace de stockage, il est donc recommandé de les nettoyer régulièrement

vms vm snapshot edit – Modifier un snapshot

Modifie la description ou l'état de verrouillage d'un snapshot.

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

Seuls les champs présents dans le corps de la requête sont modifiés ; les champs absents conservent leur valeur d'origine ; modifier uniquement la description ne change pas l'état de verrouillage, et inversement

Exemple de sortie :

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 – Afficher la configuration de la machine virtuelle d'un snapshot

Affiche la configuration de la machine virtuelle enregistrée dans un snapshot.

vms vm snapshot config <id> <snapshot_name>

<id> est l'ID de la machine virtuelle et <snapshot_name> est le nom du snapshot, qui peut être obtenu via vms vm snapshot list <id>.

Exemple de sortie :

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 – Prévisualiser la cohérence du snapshot

Prévisualise le type de cohérence susceptible d'être obtenu avant la création d'un snapshot, aidant à déterminer si le moment actuel convient à sa création.

vms vm snapshot consistency <id>

Exemple de sortie :

PROPERTY          VALUE
CONSISTENCY TYPE  filesystem
REASON            vm_shutdown
VM STATE          shutdown

Créer un snapshot lorsque la machine virtuelle est à l'arrêt permet d'obtenir un snapshot cohérent au niveau du système de fichiers ; en cours d'exécution, on ne peut généralement obtenir qu'un snapshot cohérent au niveau du plantage.

VI. Console distante

vms vm link – Obtenir les informations de connexion VNC

Obtient les informations de connexion de la console VNC de la machine virtuelle, pour ouvrir la console distante dans un navigateur.

vms vm link <id> --json

La machine virtuelle doit être en cours d'exécution ou en pause, sinon une erreur de conflit d'état est renvoyée

Exemple de sortie :

{
  "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 est le chemin de la console relatif à l'adresse de gestion de NAS, port est le port du service de console et https indique si l'accès doit se faire via HTTPS
Dans la sortie JSON, le & présent dans l'URL est échappé en \u0026

VII. Gestion des réseaux virtuels

Les types de réseau se divisent en deux catégories :

Type	Description
Privé (private)	Un réseau interne destiné uniquement à la communication entre les machines virtuelles de la machine locale, non lié à une carte réseau physique
Externe (external)	Un réseau lié à une carte réseau physique, par lequel les machines virtuelles peuvent communiquer avec l'extérieur

vms network list – Lister les réseaux virtuels

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

Exemple de sortie :

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 est le nombre de machines virtuelles connectées au réseau et NUM INTERFACES le nombre de cartes réseau physiques sélectionnées

vms network get – Afficher les détails d'un réseau virtuel

vms network get <network_id> --json

Exemple de sortie :

{
  "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 corresponds aux informations des cartes réseau liées au réseau, organisées par ID d'hôte, et checked indique si la carte réseau est sélectionnée
metadata enregistre les heures de création et de mise à jour du réseau

vms network create – Créer un réseau virtuel

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

Créer un réseau privé :

Le corps de la requête doit contenir name, type (private) et host_name ou host_id, précisant sur quel hôte le réseau est créé
Avant la création, vous pouvez consulter les hôtes disponibles via vms network list-interfaces private

Créer un réseau externe :

Le corps de la requête doit contenir name, type (external) et vlan_id, et au moins une carte réseau physique doit être spécifiée
La carte réseau peut être spécifiée via interface_name (tel que LAN 1) ou interface_id ; lorsque le nom de la carte réseau n'est pas unique entre les hôtes, il doit être utilisé avec host_name
Avant la création, vous pouvez consulter les cartes réseau disponibles via vms network list-interfaces external

La sortie correspond aux informations du réseau après création, cohérentes avec la structure de 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
}

Lorsqu'aucune carte réseau n'est spécifiée, la commande affiche une invite :

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 – Mettre à jour un réseau virtuel

Seuls les champs à modifier sont soumis ; les champs non soumis conservent leur valeur d'origine.

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

Le corps de la requête doit contenir network_id
La commande lit d'abord la configuration réseau actuelle et fusionne les champs soumis ; le nom du réseau et les cartes réseau sélectionnées ne sont pas vidés
La sortie correspond aux informations du réseau mis à jour

vms network delete – Supprimer un réseau virtuel (risque élevé)

vms network delete <network_id> [--yes]

Il s'agit d'une opération à risque élevé : le mode interactif demande une confirmation, le mode non interactif doit ajouter --yes
La suppression d'un réseau déconnecte toutes les machines virtuelles connectées à ce réseau
Il est recommandé de confirmer d'abord les machines virtuelles connectées via vms network list-vnics <network_id>

Invite de confirmation en mode interactif :

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

Sortie : Network deleted: <network_id>

vms network list-interfaces – Lister les interfaces réseau

Liste les interfaces réseau d'un type spécifié.

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

external renvoie les cartes réseau physiques disponibles sur l'hôte
private renvoie les informations des hôtes disponibles pour créer un réseau privé

Exemple de sortie (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

Exemple de sortie (private) :

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

vms network list-vnics – Lister les cartes réseau virtuelles d'un réseau

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

Exemple de sortie :

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 – Afficher l'état OVS

Confirme si le commutateur virtuel Open vSwitch est activé.

vms network ovsinfo [--json]

Exemple de sortie :

PROPERTY  VALUE
RESULT    true

Une VALUE de true indique que OVS est activé.

VIII. Gestion des images

vms image list – Lister les images

Liste les fichiers d'image système disponibles pour créer des machines virtuelles.

vms image list --json

image_name est le nom de l'image et file_name le nom de fichier correspondant
type est le format de l'image, tel que iso ou qcow2
status est l'état de l'image ; available indique qu'elle est disponible
repos est le référentiel où se trouve l'image
progress est la progression de la tâche de traitement de l'image ; 0 indique qu'aucune tâche n'est en cours

Exemple de sortie :

{
  "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 – Modifier une image

Modifie le nom de l'image ou ajuste le référentiel où se trouve l'image.

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

Le corps de la requête doit contenir image_id et repos ; repos est la liste complète des référentiels cibles de l'image et ne peut pas être vide
image_name, file_name, type et file_size sont des champs facultatifs ; s'ils ne sont pas fournis, les valeurs actuelles sont utilisées
Un repos vide entraînerait le retrait de l'image de tous les référentiels ; la commande refuse la requête avant l'exécution
Sortie : Image updated

vms image delete – Supprimer une image (risque élevé)

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

--image-id est obligatoire
Il s'agit d'une opération à risque élevé : le mode interactif demande une confirmation, le mode non interactif doit ajouter --yes
La suppression d'une image n'affecte pas les machines virtuelles déjà créées, mais elle affecte la création ultérieure de machines virtuelles basées sur cette image
Il est recommandé de confirmer d'abord l'utilisation via vms image list-vms --image-id <image_id>

Invite de confirmation en mode interactif :

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

Sortie : Image deleted: <image_id>

vms image list-vms – Afficher les machines virtuelles utilisant l'image

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

Exemple de sortie :

GUEST NAME
1454486

Avant de supprimer une image, vous pouvez exécuter cette commande pour confirmer l'étendue de l'impact ; lorsqu'aucune machine virtuelle n'utilise l'image, la sortie est vide.

IX. Gestion des référentiels

vms repo list – Lister les référentiels

vms repo list [--json]

Exemple de sortie :

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 – Afficher les détails d'un référentiel

vms repo get <repo_id> [--json]

Exemple de sortie :

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 est le volume où se trouve le référentiel
SOFT LIMIT et HARD LIMIT sont les seuils d'alerte de capacité (pourcentage)
ENABLE LOWER NOTIFY indique si le rappel de capacité insuffisante est activé

vms repo update – Mettre à jour un référentiel

Seuls les champs à modifier sont soumis ; les champs non soumis conservent leur valeur d'origine.

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

L'ID du référentiel peut être transmis via repo_id ou repoId
La commande lit d'abord la configuration actuelle et fusionne les champs soumis ; les autres paramètres ne sont pas perdus
La sortie correspond aux informations du référentiel mis à jour

vms repo delete – Supprimer un référentiel (risque élevé)

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

Le deuxième paramètre est need_save_data : true indique conserver les fichiers de données sur le disque, et false indique les supprimer avec les données
Il s'agit d'une opération à risque élevé : le mode interactif demande une confirmation, le mode non interactif doit ajouter --yes
La suppression d'un référentiel supprime en même temps les machines virtuelles et les images qu'il contient ; il est recommandé d'exécuter d'abord vms repo check-running et vms repo whether-exist-data pour confirmer l'étendue de l'impact

Invite de confirmation en mode interactif :

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

Sortie : Repository deleted: <repo_id>

vms repo list-volumes – Lister les volumes disponibles

Liste les volumes disponibles pour créer un référentiel.

vms repo list-volumes [--json]

Exemple de sortie :

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 – Lister les machines virtuelles d'un référentiel

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

L'ID du référentiel peut être transmis via repo_id ou repoId
La commande obtient d'abord l'objet référentiel puis interroge ses machines virtuelles, ce qui rend le résultat plus fiable

vms repo check-running – Vérifier les machines virtuelles en cours d'exécution sur un référentiel

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

À exécuter avant de supprimer un référentiel, pour confirmer qu'aucune machine virtuelle n'est en cours d'exécution ; lorsqu'il n'y a aucune machine virtuelle en cours d'exécution, la sortie est vide.

vms repo whether-exist-data – Vérifier la présence de données dans un référentiel

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

À exécuter avant de supprimer un référentiel, pour confirmer s'il reste encore des données dans le référentiel ; cohérent avec la pré-vérification avant la suppression d'un référentiel dans l'interface web.

X. Paramètres globaux

vms setting get – Afficher les paramètres globaux

Affiche la configuration globale de l'application VMs.

vms setting get [--json]

Exemple de sortie :

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

HOST SHUTDOWN BEHAVIOR est la manière dont les machines virtuelles sont traitées lorsque l'hôte s'arrête
KB LAYOUT est la disposition du clavier de la machine virtuelle

XI. Interrogation des informations de supervision

vms collectd hostinfo – Afficher les informations de supervision de l'hôte

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

Exemple de sortie :

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

vms collectd vminfo – Afficher les informations de supervision d'une machine virtuelle

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

Exemple de sortie :

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 – Afficher les informations de supervision du stockage

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

Exemple de sortie :

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

Mode interactif et mode non interactif

Le CLI détermine s'il s'exécute actuellement dans un environnement de terminal et adopte des comportements différents :

Mode interactif (environnement de terminal)

Les opérations dangereuses affichent une invite de confirmation, l'option par défaut étant Non
Saisissez y ou Y pour poursuivre l'exécution, et n ou appuyez directement sur Entrée pour annuler
En cas d'annulation d'une opération, Operation cancelled est affiché, avec un code de sortie de 99

Mode non interactif (script/automatisation)

Les opérations dangereuses doivent utiliser --yes pour ignorer la confirmation, sinon la commande échoue directement et renvoie le code de sortie 1
En l'absence d'environnement de terminal, il n'y a pas d'attente de saisie, ce qui convient aux scripts et aux appels de tâches planifiées
Il est recommandé de traiter explicitement les codes de sortie dans les scripts pour distinguer le succès, l'échec et le conflit d'état

Format de sortie JSON

Les commandes d'interrogation prennent en charge le paramètre --json et affichent des données JSON normalisées, pratiques pour l'analyse par programme.

Conventions de format :

Les noms de champs utilisent le snake_case
Les valeurs booléennes sont true/false
L'heure utilise le format ISO 8601, avec une précision à la nanoseconde et un décalage UTC+8 (tel que 2026-09-02T11:43:51.176535374+08:00)
Le JSON est affiché sur stdout, les informations d'erreur sur stderr
Les champs longs tronqués dans la sortie tabulaire sont des valeurs complètes dans la sortie JSON

Exemple :

vms setting get --json

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

Les structures JSON des différentes commandes diffèrent légèrement : vms vm list, vms vm snapshot list et vms vm logs affichent directement des tableaux ; les autres commandes de type liste affichent des objets contenant totalCount et un champ de données, le nom du champ de données variant selon la ressource (tel que items, hosts, vms, storage). Par exemple, 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"
    }
  }
}

La sortie JSON de certaines commandes est une valeur simple, par exemple vms network ovsinfo --json affiche true et vms vm pause --json affiche null.

Description des codes de sortie

Code de sortie	Signification	Scénario typique
0	Succès	La commande se termine normalement
1	Erreur de paramètre	Paramètre obligatoire manquant, format de paramètre incorrect ou `--yes` non ajouté
3	Ressource introuvable	La pré-vérification de la commande échoue, par exemple l'image spécifiée n'existe pas
4	Conflit d'état	L'état actuel de la machine virtuelle ne permet pas l'opération (par exemple arrêter une machine virtuelle déjà arrêtée)
6	Erreur de connexion	Impossible de se connecter au service VMs, ou le chemin du socket est incorrect
7	Délai d'expiration	La requête a expiré ; cela peut être ajusté via `--timeout`
9	Erreur d'exécution	Le backend renvoie une erreur (le message d'erreur contient code_num et la description de l'erreur)
99	Annulation par l'utilisateur	Sélection de Non ou appui direct sur Entrée lors de la confirmation interactive

Exemple :

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

Exemples de scénarios d'utilisation

Maintenance quotidienne

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

Traitement par lots en 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'

Sauvegarde et inspection

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

Vérifications avant suppression

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

Appel par des outils d'IA

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

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

Développement interne et intégration système

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

Questions fréquentes

Q : Le CLI nécessite-t-il une installation supplémentaire ?

Non. Le CLI est installé en même temps que l'application VMs ; après l'activation de l'application, il suffit d'exécuter la commande vms pour l'utiliser.

Q : Le CLI doit-il être utilisé via SSH ?

Non. Le CLI peut être appelé depuis n'importe quel terminal en ligne de commande, y compris un terminal local, le SSH distant, des scripts, des outils d'IA, etc.

Q : Le CLI peut-il gérer les machines virtuelles d'autres appareils ?

Non. Le CLI communique avec le service VMs via un unix socket local et sert uniquement à gérer les machines virtuelles de la machine locale.

Q : Pourquoi certaines commandes demandent-elles une confirmation et d'autres non ?

Les opérations telles que la suppression d'une machine virtuelle, la suppression d'un réseau, la suppression d'une image, la suppression d'un référentiel et l'arrêt (poweroff, force-poweroff) affectent les données ou les services, elles nécessitent donc une confirmation par défaut ; les commandes de démarrage, de redémarrage, de mise en pause, de reprise et d'interrogation n'ont pas de telles restrictions.

Q : Comment confirmer les opérations dangereuses en mode non interactif ?

Toutes les opérations dangereuses doivent ajouter le paramètre --yes, sinon la commande échoue et se termine (code de sortie 1).

Q : Comment déterminer dans un script si une commande a réussi ?

Par le code de sortie : 0 indique le succès et une valeur différente de 0 indique un échec. Vous pouvez également analyser la sortie de --json.

Q : Pourquoi la liste affichée par --json est-elle un objet ?

La sortie JSON de certaines commandes est organisée en objet par ID, avec un champ totalCount attaché, ce qui facilite l'accès direct par ID.

Aide supplémentaire

Chaque commande prend en charge --help pour afficher l'utilisation détaillée :

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

Introduction​

Caractéristiques principales​

Démarrage rapide​

Options globales​

Exemple d'informations de version​

Environnement d'exécution​

Tableau récapitulatif des commandes​

Référence des commandes​

I. Interrogation des machines virtuelles​

vms vm list – Lister les machines virtuelles​

vms vm get – Afficher les détails d'une machine virtuelle​

vms vm list-resource – Lister les ressources disponibles pour créer une machine virtuelle​

vms vm logs – Afficher les journaux d'opérations d'une machine virtuelle​

II. Gestion de l'alimentation des machines virtuelles​

vms vm poweron – Démarrer une machine virtuelle​

vms vm poweroff – Arrêter une machine virtuelle​

vms vm force-poweroff – Forcer l'arrêt d'une machine virtuelle (risque élevé)​

vms vm reboot – Redémarrer une machine virtuelle​

vms vm pause – Mettre en pause une machine virtuelle​

vms vm resume – Reprendre une machine virtuelle​

vms vm autorun – Définir le démarrage automatique au boot​

III. Clonage, export et suppression des machines virtuelles​

vms vm clone – Cloner une machine virtuelle​

vms vm export – Exporter une machine virtuelle​

vms vm delete – Supprimer une machine virtuelle (risque élevé)​

IV. Disques virtuels​

vms vm disk list – Afficher les disques virtuels​

V. Gestion des snapshots​

vms vm snapshot list – Lister les snapshots​

vms vm snapshot create – Créer un snapshot​

vms vm snapshot edit – Modifier un snapshot​

vms vm snapshot config – Afficher la configuration de la machine virtuelle d'un snapshot​

vms vm snapshot consistency – Prévisualiser la cohérence du snapshot​

VI. Console distante​

vms vm link – Obtenir les informations de connexion VNC​

VII. Gestion des réseaux virtuels​

vms network list – Lister les réseaux virtuels​

vms network get – Afficher les détails d'un réseau virtuel​

vms network create – Créer un réseau virtuel​

vms network update – Mettre à jour un réseau virtuel​

vms network delete – Supprimer un réseau virtuel (risque élevé)​

vms network list-interfaces – Lister les interfaces réseau​

vms network list-vnics – Lister les cartes réseau virtuelles d'un réseau​

vms network ovsinfo – Afficher l'état OVS​

VIII. Gestion des images​

vms image list – Lister les images​

vms image edit – Modifier une image​

vms image delete – Supprimer une image (risque élevé)​

vms image list-vms – Afficher les machines virtuelles utilisant l'image​

IX. Gestion des référentiels​

vms repo list – Lister les référentiels​

vms repo get – Afficher les détails d'un référentiel​

vms repo update – Mettre à jour un référentiel​

vms repo delete – Supprimer un référentiel (risque élevé)​

vms repo list-volumes – Lister les volumes disponibles​

vms repo list-vms – Lister les machines virtuelles d'un référentiel​

vms repo check-running – Vérifier les machines virtuelles en cours d'exécution sur un référentiel​

vms repo whether-exist-data – Vérifier la présence de données dans un référentiel​

X. Paramètres globaux​

vms setting get – Afficher les paramètres globaux​

XI. Interrogation des informations de supervision​

vms collectd hostinfo – Afficher les informations de supervision de l'hôte​

vms collectd vminfo – Afficher les informations de supervision d'une machine virtuelle​

vms collectd storageinfo – Afficher les informations de supervision du stockage​

Mode interactif et mode non interactif​

Mode interactif (environnement de terminal)​

Mode non interactif (script/automatisation)​

Format de sortie JSON​

Description des codes de sortie​

Exemples de scénarios d'utilisation​

Maintenance quotidienne​

Traitement par lots en script​

Sauvegarde et inspection​

Vérifications avant suppression​

Appel par des outils d'IA​

Développement interne et intégration système​

Questions fréquentes​

Aide supplémentaire​

Introduction

Caractéristiques principales

Démarrage rapide

Options globales

Exemple d'informations de version

Environnement d'exécution

Tableau récapitulatif des commandes

Référence des commandes

I. Interrogation des machines virtuelles

vms vm list – Lister les machines virtuelles

vms vm get – Afficher les détails d'une machine virtuelle

vms vm list-resource – Lister les ressources disponibles pour créer une machine virtuelle

vms vm logs – Afficher les journaux d'opérations d'une machine virtuelle

II. Gestion de l'alimentation des machines virtuelles

vms vm poweron – Démarrer une machine virtuelle

vms vm poweroff – Arrêter une machine virtuelle

vms vm force-poweroff – Forcer l'arrêt d'une machine virtuelle (risque élevé)

vms vm reboot – Redémarrer une machine virtuelle

vms vm pause – Mettre en pause une machine virtuelle

vms vm resume – Reprendre une machine virtuelle

vms vm autorun – Définir le démarrage automatique au boot

III. Clonage, export et suppression des machines virtuelles

vms vm clone – Cloner une machine virtuelle

vms vm export – Exporter une machine virtuelle

vms vm delete – Supprimer une machine virtuelle (risque élevé)

IV. Disques virtuels

vms vm disk list – Afficher les disques virtuels

V. Gestion des snapshots

vms vm snapshot list – Lister les snapshots

vms vm snapshot create – Créer un snapshot

vms vm snapshot edit – Modifier un snapshot

vms vm snapshot config – Afficher la configuration de la machine virtuelle d'un snapshot

vms vm snapshot consistency – Prévisualiser la cohérence du snapshot

VI. Console distante

vms vm link – Obtenir les informations de connexion VNC

VII. Gestion des réseaux virtuels

vms network list – Lister les réseaux virtuels

vms network get – Afficher les détails d'un réseau virtuel

vms network create – Créer un réseau virtuel

vms network update – Mettre à jour un réseau virtuel

vms network delete – Supprimer un réseau virtuel (risque élevé)

vms network list-interfaces – Lister les interfaces réseau

vms network list-vnics – Lister les cartes réseau virtuelles d'un réseau

vms network ovsinfo – Afficher l'état OVS

VIII. Gestion des images

vms image list – Lister les images

vms image edit – Modifier une image

vms image delete – Supprimer une image (risque élevé)

vms image list-vms – Afficher les machines virtuelles utilisant l'image

IX. Gestion des référentiels

vms repo list – Lister les référentiels

vms repo get – Afficher les détails d'un référentiel

vms repo update – Mettre à jour un référentiel

vms repo delete – Supprimer un référentiel (risque élevé)

vms repo list-volumes – Lister les volumes disponibles

vms repo list-vms – Lister les machines virtuelles d'un référentiel

vms repo check-running – Vérifier les machines virtuelles en cours d'exécution sur un référentiel

vms repo whether-exist-data – Vérifier la présence de données dans un référentiel

X. Paramètres globaux

vms setting get – Afficher les paramètres globaux

XI. Interrogation des informations de supervision

vms collectd hostinfo – Afficher les informations de supervision de l'hôte

vms collectd vminfo – Afficher les informations de supervision d'une machine virtuelle

vms collectd storageinfo – Afficher les informations de supervision du stockage

Mode interactif et mode non interactif

Mode interactif (environnement de terminal)

Mode non interactif (script/automatisation)

Format de sortie JSON

Description des codes de sortie

Exemples de scénarios d'utilisation

Maintenance quotidienne

Traitement par lots en script

Sauvegarde et inspection

Vérifications avant suppression

Appel par des outils d'IA

Développement interne et intégration système

Questions fréquentes

Aide supplémentaire