Version: TOS 7

VMs CLI

Introducción

VMs CLI es la herramienta de administración por línea de comandos de la aplicación de virtualización VMs de TerraMaster, y ofrece capacidades de consulta y operación coherentes con la interfaz de administración web. La CLI se comunica con el servicio VMs mediante el unix socket local, adopta una interfaz de comandos estandarizada y un formato de salida JSON, y puede integrarse en scripts, operaciones automatizadas y flujos de trabajo de desarrollo secundario.

Características principales

Listo para usar: se instala junto con la aplicación VMs, sin necesidad de instalación adicional
Métodos de invocación flexibles: admite terminal local, SSH remoto, scripts, herramientas de IA y otras vías de invocación
Doble modo interactivo y no interactivo: adecuado tanto para el mantenimiento diario del administrador como para scripts y tareas automatizadas
Compatibilidad con salida JSON: facilita el análisis por programas y la integración automatizada
Comunicación local: se comunica con el servicio VMs solo mediante el unix socket local, sin abrir puertos al exterior
Confirmación secundaria para operaciones peligrosas: operaciones como eliminar una máquina virtual o eliminar una red requieren confirmación de forma predeterminada

Inicio rápido

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

Opciones globales

Las siguientes opciones se aplican a todos los comandos:

Opción	Abreviatura	Descripción
`--help`	`-h`	Muestra la información de ayuda del comando
`--version`	`-v`	Muestra el número de versión (puede combinarse con `--json` para generar información estructurada)
`--json`	-	Genera la salida en formato JSON
`--yes`	`-y`	Omite la solicitud de confirmación de las operaciones peligrosas (obligatorio en el modo no interactivo)
`--debug`	-	Activa la salida de depuración y muestra el proceso de ejecución detallado
`--socket <path>`	-	Ruta del unix socket de VMs, por defecto `/var/api/VMs.sock`
`--timeout <duration>`	-	Tiempo de espera de la solicitud, por defecto 30s

Ejemplo de información de versión

vms --version

vms CLI v1.0.058

vms --version --json

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

Entorno de ejecución

VMs CLI se instala junto con la aplicación VMs. Cuando la aplicación está habilitada, enlaza la CLI en el directorio PATH predeterminado del sistema, por lo que se puede usar directamente tras iniciar sesión por SSH.

Elemento	Descripción
Archivo de la CLI	`/Volume1/@apps/VMs/bin/vms`
Ruta del comando	`/usr/local/sbin/vms` (ya está en el PATH del sistema)
Método de comunicación	unix socket local, por defecto `/var/api/VMs.sock`
Usuarios objetivo	Administradores que inician sesión en el equipo local

Notas:

La CLI se utiliza para administrar las máquinas virtuales del equipo local; no admite la administración remota de otros dispositivos mediante la CLI.
El backend siempre devuelve HTTP 200; el éxito del comando se determina según el campo code del cuerpo de la respuesta, y la CLI lo convierte en el código de salida correspondiente.
Las operaciones peligrosas (eliminar máquinas virtuales, eliminar redes, eliminar imágenes, eliminar espacios de almacenamiento) solicitan confirmación en el modo interactivo y requieren pasar explícitamente --yes en el modo no interactivo.

Tabla resumen de comandos

A continuación se presenta un resumen de referencia rápida de todos los comandos vms:

Comando principal	Subcomando	Descripción de la función	Requiere confirmación	Alto riesgo
vms	--version	Muestra la información de versión	No	No
vms vm	list	Enumera todas las máquinas virtuales	No	No
vms vm	get	Consulta los detalles de una máquina virtual especificada	No	No
vms vm	list-resource	Enumera los recursos disponibles para crear máquinas virtuales	No	No
vms vm	logs	Consulta el registro de operaciones de la máquina virtual	No	No
vms vm	poweron	Inicia la máquina virtual	No	No
vms vm	poweroff	Apaga la máquina virtual (apagado normal)	Sí	No
vms vm	force-poweroff	Fuerza el apagado de la máquina virtual	Sí	✅
vms vm	reboot	Reinicia la máquina virtual	No	No
vms vm	pause	Pausa la máquina virtual	No	No
vms vm	resume	Reanuda la máquina virtual pausada	No	No
vms vm	autorun	Configura el inicio automático al arrancar	No	No
vms vm	clone	Clona la máquina virtual	No	No
vms vm	export	Exporta la máquina virtual como archivo OVA	No	No
vms vm	delete	Elimina la máquina virtual	Sí	✅
vms vm disk	list	Consulta los discos virtuales de la máquina virtual	No	No
vms vm snapshot	list	Enumera las instantáneas de la máquina virtual	No	No
vms vm snapshot	create	Crea una instantánea	No	No
vms vm snapshot	edit	Edita la descripción y el estado de bloqueo de la instantánea	No	No
vms vm snapshot	config	Consulta la configuración de la máquina virtual guardada en la instantánea	No	No
vms vm snapshot	consistency	Previsualiza la consistencia de la instantánea	No	No
vms vm	link	Obtiene la información de conexión de la consola VNC	No	No
vms network	list	Enumera las redes virtuales	No	No
vms network	get	Consulta los detalles de la red virtual	No	No
vms network	create	Crea una red virtual	No	No
vms network	update	Actualiza la red virtual	No	No
vms network	delete	Elimina la red virtual	Sí	✅
vms network	list-interfaces	Enumera las interfaces de red del tipo especificado	No	No
vms network	list-vnics	Enumera las tarjetas de red virtuales de la red	No	No
vms network	ovsinfo	Consulta si OVS está habilitado	No	No
vms image	list	Enumera las imágenes	No	No
vms image	edit	Edita la información de la imagen	No	No
vms image	delete	Elimina la imagen	Sí	✅
vms image	list-vms	Consulta las máquinas virtuales que utilizan esta imagen	No	No
vms repo	list	Enumera los espacios de almacenamiento	No	No
vms repo	get	Consulta los detalles del espacio de almacenamiento	No	No
vms repo	update	Actualiza la configuración del espacio de almacenamiento	No	No
vms repo	delete	Elimina el espacio de almacenamiento	Sí	✅
vms repo	list-volumes	Enumera los volúmenes disponibles	No	No
vms repo	list-vms	Enumera las máquinas virtuales del espacio de almacenamiento	No	No
vms repo	check-running	Comprueba las máquinas virtuales en ejecución en el espacio de almacenamiento	No	No
vms repo	whether-exist-data	Comprueba si existen datos en el espacio de almacenamiento	No	No
vms setting	get	Consulta la configuración global	No	No
vms collectd	hostinfo	Consulta la información de monitoreo del host	No	No
vms collectd	vminfo	Consulta la información de monitoreo de la máquina virtual	No	No
vms collectd	storageinfo	Consulta la información de monitoreo del almacenamiento	No	No

Referencia de comandos

En los comandos, <id> es el ID de la máquina virtual, que corresponde al GUEST ID de la salida de la lista de máquinas virtuales; <network_id>, <image_id> y <repo_id> funcionan de forma similar y pueden obtenerse mediante vms network list, vms image list y vms repo list, respectivamente.

Acerca de los ejemplos de salida: la salida de tabla de vms trunca los valores de campo demasiado largos a un ancho fijo (terminando en puntos suspensivos y con independencia del ancho del terminal), por ejemplo VDISKS, VNICS e ISO IMAGES en la configuración de la máquina virtual, así como los nombres de las imágenes. Por lo tanto, en este documento los comandos que implican campos largos ofrecen de forma uniforme un ejemplo de salida completo con --json, y el resto de los comandos ofrecen ejemplos de salida en tabla. También se recomienda usar --json de forma uniforme al procesar con scripts.

1. Consulta de máquinas virtuales

vms vm list – Enumera las máquinas virtuales

Enumera todas las máquinas virtuales del equipo local y su estado básico.

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

--limit y --offset son parámetros de paginación
Columnas de salida: nombre, ID de la máquina virtual, estado de ejecución, número de núcleos de CPU, tamaño de memoria (en KB), dirección IP

Ejemplo de salida:

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    -

Valores comunes de STATUS:

Estado	Descripción
running	En ejecución
shutdown	Apagada
saved	En pausa (el estado de ejecución se ha guardado en el disco)

vms vm get – Consulta los detalles de la máquina virtual

Consulta la configuración completa y el estado de ejecución de la máquina virtual especificada.

vms vm get <id> --json

La salida incluye todos los campos de configuración y estado de ejecución de la máquina virtual
Los valores vacíos, como la ausencia de descripción o de IP, se muestran como una cadena vacía
Si la máquina virtual no existe, el comando devuelve un error y muestra la información del error

Ejemplo de salida:

{
  "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 – Enumera los recursos disponibles para crear máquinas virtuales

Consulta los recursos que el host puede proporcionar, como tipos de firmware, imágenes, CPU, memoria, redes, espacios de almacenamiento y dispositivos de paso directo, para evaluarlos antes de crear una máquina virtual.

vms vm list-resource --json

Campos devueltos: max_cpu_num, max_ram_size, usbs, pci_devices, networks, repos, images, video_cards, firmware, keyboard_layout.

Ejemplo de salida:

{
  "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 – Consulta el registro de operaciones de la máquina virtual

Consulta el registro de operaciones relacionadas con la máquina virtual especificada (encendido y apagado, instantáneas, edición, importación y exportación, etc.).

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

--limit especifica el número de entradas devueltas, por defecto 50
--desc ordena por tiempo de forma descendente (activado de forma predeterminada)
Cada entrada del registro incluye hora, nivel, categoría, usuario de la operación y descripción del evento; la descripción del evento es texto completo
La descripción del evento (event) la genera el servicio VMs localizada según el idioma del sistema del dispositivo; los ejemplos de este documento utilizan uniformemente el inglés

Ejemplo de salida:

[
  {
    "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. Administración de energía de máquinas virtuales

vms vm poweron – Inicia la máquina virtual

vms vm poweron <id>

La máquina virtual debe estar apagada; de lo contrario, devuelve un error de conflicto de estado
Salida: VM powered on: <id>

vms vm poweroff – Apaga la máquina virtual

Envía a la máquina virtual una solicitud de apagado normal para que el sistema se cierre de forma ordenada.

vms vm poweroff <id> [--yes]

Es una operación peligrosa: en el modo interactivo solicita confirmación y en el modo no interactivo es obligatorio añadir --yes
La máquina virtual debe estar en ejecución; de lo contrario, devuelve un error de conflicto de estado

Solicitud de confirmación en el modo interactivo:

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

Salida: VM powered off: <id>

vms vm force-poweroff – Fuerza el apagado de la máquina virtual (alto riesgo)

Fuerza el apagado de la máquina virtual, lo que equivale a cortar la alimentación directamente.

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

Es una operación de alto riesgo: en el modo interactivo solicita confirmación y en el modo no interactivo es obligatorio añadir --yes
Puede provocar la pérdida de datos dentro de la máquina virtual; se recomienda usarlo solo cuando la máquina virtual no responde

Solicitud de confirmación en el modo interactivo:

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

Salida: VM force powered off: <id>

vms vm reboot – Reinicia la máquina virtual

vms vm reboot <id>

Salida: VM rebooted: <id>

vms vm pause – Pausa la máquina virtual

Congela el estado de ejecución de la máquina virtual y guarda el estado actual en el disco.

vms vm pause <id>

La máquina virtual debe estar en ejecución; de lo contrario, devuelve un error de conflicto de estado
Tras la pausa, el estado de la máquina virtual se muestra como saved
Salida: VM paused: <id>

vms vm resume – Reanuda la máquina virtual

Restaura la máquina virtual del estado de pausa al estado de ejecución.

vms vm resume <id>

La máquina virtual debe estar en pausa; de lo contrario, devuelve un error de conflicto de estado
Salida: VM resumed: <id>

vms vm autorun – Configura el inicio automático al arrancar

Configura si la máquina virtual se inicia automáticamente al arrancar el host.

vms vm autorun <id> <true|false>

El segundo parámetro debe ser true o false
El comando lee la configuración actual y solo modifica el interruptor de inicio automático; el resto de la configuración no se ve afectada
Salida: Auto-start enabled for VM <id> o Auto-start disabled for VM <id>

3. Copia, exportación y eliminación de máquinas virtuales

vms vm clone – Clona la máquina virtual

Crea una nueva máquina virtual copiando una máquina virtual existente como plantilla.

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

En el cuerpo de la solicitud, guest_id es el ID de la máquina virtual de origen y name (o guest_name) es el nombre de la nueva máquina virtual
La máquina virtual de origen debe estar apagada
--body pasa el cuerpo de la solicitud directamente como una cadena JSON; --file lee el cuerpo de la solicitud desde un archivo

vms vm export – Exporta la máquina virtual

Exporta la máquina virtual como archivo OVA, lo que facilita la copia de seguridad o la migración a otras plataformas de virtualización.

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

En el cuerpo de la solicitud, guest_id es el ID de la máquina virtual de origen, target_ova_path es la ruta del archivo de destino y ova_mode es el modo de compatibilidad con VMware opcional
La máquina virtual de origen debe estar apagada
La exportación es una tarea que consume tiempo; la exportación de máquinas virtuales de gran capacidad tarda más

vms vm delete – Elimina la máquina virtual (alto riesgo)

Elimina la máquina virtual de forma permanente.

vms vm delete <id> [--yes]

Es una operación de alto riesgo: en el modo interactivo solicita confirmación y en el modo no interactivo es obligatorio añadir --yes
Una vez eliminada, no se puede recuperar; confirme con antelación que los datos de la máquina virtual se han copiado

Solicitud de confirmación en el modo interactivo:

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

Salida: VM deleted: <id>

4. Discos virtuales

vms vm disk list – Consulta los discos virtuales

Enumera todos los discos virtuales de la máquina virtual especificada.

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

Ejemplo de salida:

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

VDISK MODE es el número del tipo de controlador del disco virtual; 1 indica IDE
Los discos virtuales sin nombre se muestran como - en la columna NAME

5. Administración de instantáneas

vms vm snapshot list – Enumera las instantáneas

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

Ejemplo de salida:

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 es el estado de ejecución de la máquina virtual en el momento de crear la instantánea
ACTUAL CONSISTENCY es el tipo de consistencia de la instantánea; filesystem indica consistencia del sistema de archivos y crash indica consistencia por fallo

vms vm snapshot create – Crea una instantánea

Crea una instantánea de la máquina virtual para revertir rápidamente o hacer una copia de seguridad del estado actual.

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

Cuerpo de la solicitud opcional: description es la descripción de la instantánea y locked indica si se bloquea
El nombre de la instantánea lo genera automáticamente el sistema según la hora de creación
Las instantáneas ocupan espacio de almacenamiento; si no se limpian durante mucho tiempo, pueden llenar el espacio de almacenamiento, por lo que se recomienda organizarlas periódicamente

vms vm snapshot edit – Edita la instantánea

Modifica la descripción o el estado de bloqueo de la instantánea.

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

Solo se modifican los campos que aparecen en el cuerpo de la solicitud; los campos que no aparecen conservan su valor original; cambiar solo la descripción no altera el estado de bloqueo, y viceversa

Ejemplo de salida:

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 – Consulta la configuración de la máquina virtual de la instantánea

Consulta la configuración de la máquina virtual guardada en la instantánea.

vms vm snapshot config <id> <snapshot_name>

<id> es el ID de la máquina virtual y <snapshot_name> es el nombre de la instantánea, que puede obtenerse mediante vms vm snapshot list <id>.

Ejemplo de salida:

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 – Previsualiza la consistencia de la instantánea

Previsualiza el tipo de consistencia que se puede obtener antes de crear una instantánea, lo que ayuda a determinar si el momento actual es adecuado para crearla.

vms vm snapshot consistency <id>

Ejemplo de salida:

PROPERTY          VALUE
CONSISTENCY TYPE  filesystem
REASON            vm_shutdown
VM STATE          shutdown

Crear una instantánea con la máquina virtual apagada permite obtener una instantánea con consistencia del sistema de archivos; con la máquina en ejecución normalmente solo se puede obtener una instantánea con consistencia por fallo.

6. Consola remota

vms vm link – Obtiene la información de conexión VNC

Obtiene la información de conexión de la consola VNC de la máquina virtual, para abrir la consola remota en el navegador.

vms vm link <id> --json

La máquina virtual debe estar en ejecución o en pausa; de lo contrario, devuelve un error de conflicto de estado

Ejemplo de salida:

{
  "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 es la ruta de la consola relativa a la dirección de administración del NAS, port es el puerto del servicio de la consola y https indica si se debe acceder a través de HTTPS
En la salida JSON, el & de la URL se escapa como \u0026

7. Administración de redes virtuales

Los tipos de red se dividen en dos:

Tipo	Descripción
Privada (private)	Red interna que solo permite la comunicación entre las máquinas virtuales del equipo local, sin enlazarse a una tarjeta de red física
Externa (external)	Red enlazada a una tarjeta de red física, a través de la cual las máquinas virtuales pueden comunicarse con el exterior

vms network list – Enumera las redes virtuales

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

Ejemplo de salida:

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 es el número de máquinas virtuales conectadas a esta red y NUM INTERFACES es el número de tarjetas de red físicas seleccionadas

vms network get – Consulta los detalles de la red virtual

vms network get <network_id> --json

Ejemplo de salida:

{
  "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 es la información de las tarjetas de red enlazadas a esta red, organizada por ID de host, y checked indica si la tarjeta de red está seleccionada
metadata registra la hora de creación y de actualización de la red

vms network create – Crea una red virtual

vms network create --body '{"name":"net1","type":"private","host_name":"TNAS"}' --json
vms network create --body '{"name":"net1","type":"external","vlan_id":100,"host_name":"TNAS","interface_name":"LAN 1"}' --json

Crear una red privada:

El cuerpo de la solicitud debe incluir name, type (private) y host_name o host_id, para especificar en qué host se crea la red
Antes de crearla, puede consultar los hosts disponibles mediante vms network list-interfaces private

Crear una red externa:

El cuerpo de la solicitud debe incluir name, type (external) y vlan_id, y especificar al menos una tarjeta de red física
Puede especificar la tarjeta de red mediante interface_name (como LAN 1) o interface_id; si el nombre de la tarjeta de red no es único entre hosts, debe combinarse con host_name
Antes de crearla, puede consultar las tarjetas de red disponibles mediante vms network list-interfaces external

La salida es la información de la red una vez creada, con la misma estructura que 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
}

Si no se especifica ninguna tarjeta de red, el comando emite un aviso:

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 – Actualiza la red virtual

Solo se envían los campos que se desean modificar; los campos no enviados conservan su valor original.

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

El cuerpo de la solicitud debe incluir network_id
El comando lee primero la configuración actual de la red y combina los campos enviados; el nombre de la red y las tarjetas de red seleccionadas no se borran
La salida es la información de la red una vez actualizada

vms network delete – Elimina la red virtual (alto riesgo)

vms network delete <network_id> [--yes]

Es una operación de alto riesgo: en el modo interactivo solicita confirmación y en el modo no interactivo es obligatorio añadir --yes
Eliminar la red desconecta todas las máquinas virtuales conectadas a ella
Se recomienda confirmar primero las máquinas virtuales conectadas mediante vms network list-vnics <network_id>

Solicitud de confirmación en el modo interactivo:

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

Salida: Network deleted: <network_id>

vms network list-interfaces – Enumera las interfaces de red

Enumera las interfaces de red del tipo especificado.

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

external devuelve las tarjetas de red físicas disponibles en el host
private devuelve la información de los hosts que pueden utilizarse para crear redes privadas

Ejemplo de salida (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

Ejemplo de salida (private):

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

vms network list-vnics – Enumera las tarjetas de red virtuales de la red

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

Ejemplo de salida:

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 – Consulta el estado de OVS

Confirma si el conmutador virtual Open vSwitch está habilitado.

vms network ovsinfo [--json]

Ejemplo de salida:

PROPERTY  VALUE
RESULT    true

Si VALUE es true, OVS está habilitado.

8. Administración de imágenes

vms image list – Enumera las imágenes

Enumera los archivos de imagen de sistema disponibles para crear máquinas virtuales.

vms image list --json

image_name es el nombre de la imagen y file_name es el nombre de archivo correspondiente
type es el formato de la imagen, como iso o qcow2
status es el estado de la imagen; available indica que está disponible
repos es el espacio de almacenamiento donde se encuentra la imagen
progress es el progreso de la tarea de procesamiento de la imagen; 0 indica que no hay tareas en curso

Ejemplo de salida:

{
  "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 – Edita la imagen

Modifica el nombre de la imagen o ajusta el espacio de almacenamiento donde se encuentra.

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

El cuerpo de la solicitud debe incluir image_id y repos; repos es la lista completa de espacios de almacenamiento de destino de la imagen y no puede estar vacía
image_name, file_name, type y file_size son campos opcionales; si no se proporcionan, se mantienen los valores actuales
Si repos está vacío, la imagen se eliminaría de todos los espacios de almacenamiento; el comando rechaza la solicitud antes de ejecutarla
Salida: Image updated

vms image delete – Elimina la imagen (alto riesgo)

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

--image-id es obligatorio
Es una operación de alto riesgo: en el modo interactivo solicita confirmación y en el modo no interactivo es obligatorio añadir --yes
Eliminar la imagen no afecta a las máquinas virtuales ya creadas, pero sí afecta a la creación posterior de máquinas virtuales basadas en esta imagen
Se recomienda confirmar primero el uso mediante vms image list-vms --image-id <image_id>

Solicitud de confirmación en el modo interactivo:

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

Salida: Image deleted: <image_id>

vms image list-vms – Consulta las máquinas virtuales que utilizan esta imagen

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

Ejemplo de salida:

GUEST NAME
1454486

Antes de eliminar una imagen, puede ejecutar este comando para confirmar el alcance del impacto; si ninguna máquina virtual utiliza la imagen, la salida está vacía.

9. Administración de espacios de almacenamiento

vms repo list – Enumera los espacios de almacenamiento

vms repo list [--json]

Ejemplo de salida:

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 – Consulta los detalles del espacio de almacenamiento

vms repo get <repo_id> [--json]

Ejemplo de salida:

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 es el volumen donde se encuentra el espacio de almacenamiento
SOFT LIMIT y HARD LIMIT son los umbrales de aviso de capacidad (porcentaje)
ENABLE LOWER NOTIFY indica si se habilita el recordatorio de capacidad insuficiente

vms repo update – Actualiza el espacio de almacenamiento

Solo se envían los campos que se desean modificar; los campos no enviados conservan su valor original.

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

El ID del espacio de almacenamiento puede pasarse mediante repo_id o repoId
El comando lee primero la configuración actual y combina los campos enviados; el resto de la configuración no se pierde
La salida es la información del espacio de almacenamiento una vez actualizado

vms repo delete – Elimina el espacio de almacenamiento (alto riesgo)

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

El segundo parámetro es need_save_data: true indica que se conservan los archivos de datos del disco y false indica que se eliminan junto con los datos
Es una operación de alto riesgo: en el modo interactivo solicita confirmación y en el modo no interactivo es obligatorio añadir --yes
Eliminar el espacio de almacenamiento también elimina las máquinas virtuales y las imágenes que contiene; se recomienda ejecutar primero vms repo check-running y vms repo whether-exist-data para confirmar el alcance del impacto

Solicitud de confirmación en el modo interactivo:

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

Salida: Repository deleted: <repo_id>

vms repo list-volumes – Enumera los volúmenes disponibles

Enumera los volúmenes disponibles para crear espacios de almacenamiento.

vms repo list-volumes [--json]

Ejemplo de salida:

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 – Enumera las máquinas virtuales del espacio de almacenamiento

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

El ID del espacio de almacenamiento puede pasarse mediante repo_id o repoId
El comando obtiene primero el objeto del espacio de almacenamiento y después consulta sus máquinas virtuales, lo que hace el resultado más fiable

vms repo check-running – Comprueba las máquinas virtuales en ejecución en el espacio de almacenamiento

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

Se ejecuta antes de eliminar el espacio de almacenamiento para confirmar que no hay ninguna máquina virtual en ejecución; si no hay máquinas virtuales en ejecución, la salida está vacía.

vms repo whether-exist-data – Comprueba si existen datos en el espacio de almacenamiento

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

Se ejecuta antes de eliminar el espacio de almacenamiento para confirmar si todavía hay datos en él; es coherente con la comprobación previa a eliminar un espacio de almacenamiento en la interfaz web.

10. Configuración global

vms setting get – Consulta la configuración global

Consulta la configuración global de la aplicación VMs.

vms setting get [--json]

Ejemplo de salida:

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

HOST SHUTDOWN BEHAVIOR es la forma de tratar las máquinas virtuales cuando el host se apaga
KB LAYOUT es la distribución del teclado de la máquina virtual

11. Consulta de información de monitoreo

vms collectd hostinfo – Consulta la información de monitoreo del host

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

Ejemplo de salida:

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

vms collectd vminfo – Consulta la información de monitoreo de la máquina virtual

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

Ejemplo de salida:

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 – Consulta la información de monitoreo del almacenamiento

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

Ejemplo de salida:

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

Modo interactivo y modo no interactivo

La CLI determina si se está ejecutando actualmente en un entorno de terminal y adopta comportamientos diferentes:

Modo interactivo (entorno de terminal)

Las operaciones peligrosas muestran una solicitud de confirmación; la opción predeterminada es No
Escriba y o Y para continuar; escriba n o pulse Intro para cancelar
Al cancelar la operación se genera Operation cancelled y el código de salida es 99

Modo no interactivo (scripts/automatización)

Las operaciones peligrosas deben usar --yes para omitir la confirmación; de lo contrario, el comando informa de un error directamente y devuelve el código de salida 1
Cuando no hay entorno de terminal, no espera la entrada, lo que lo hace adecuado para scripts y tareas programadas
Se recomienda gestionar explícitamente los códigos de salida en los scripts para distinguir entre éxito, fallo y conflicto de estado

Formato de salida JSON

Los comandos de consulta admiten el parámetro --json, que genera datos JSON normalizados para facilitar el análisis por programas.

Convenciones de formato:

Los nombres de los campos utilizan snake_case
Los valores booleanos son true/false
La hora utiliza el formato ISO 8601, con precisión de nanosegundos y desplazamiento de la zona horaria UTC+8 (por ejemplo, 2026-09-02T11:43:51.176535374+08:00)
La salida JSON se envía a stdout y los mensajes de error a stderr
Los campos largos truncados en la salida de tabla aparecen con su valor completo en la salida JSON

Ejemplo:

vms setting get --json

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

La estructura JSON varía ligeramente entre comandos: vms vm list, vms vm snapshot list y vms vm logs generan directamente un arreglo; el resto de los comandos de tipo lista generan un objeto que contiene totalCount y un campo de datos, cuyo nombre varía según el recurso (como items, hosts, vms o storage). Por ejemplo, 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 salida JSON de algunos comandos es un valor simple; por ejemplo, vms network ovsinfo --json genera true y vms vm pause --json genera null.

Descripción de los códigos de salida

Código de salida	Significado	Escenario típico
0	Éxito	El comando finaliza correctamente
1	Error de parámetro	Falta un parámetro obligatorio, el formato del parámetro es incorrecto o no se añadió `--yes`
3	El recurso no existe	No se superó la validación previa del comando; por ejemplo, la imagen especificada no existe
4	Conflicto de estado	El estado actual de la máquina virtual no permite la operación (por ejemplo, apagar una máquina virtual que ya está apagada)
6	Error de conexión	No se puede conectar al servicio VMs o la ruta del socket es incorrecta
7	Tiempo de espera agotado	Se agotó el tiempo de espera de la solicitud; puede ajustarse mediante `--timeout`
9	Error de ejecución	El backend devuelve un error (el mensaje de error incluye code_num y la descripción del error)
99	Cancelado por el usuario	Se eligió No en la confirmación interactiva o se pulsó Intro directamente

Ejemplo:

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

Ejemplos de casos de uso

Operaciones diarias

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

Operaciones por lotes con scripts

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

Copia de seguridad e inspección

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

Comprobación antes de eliminar

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

Invocación desde herramientas de IA

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

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

Desarrollo interno e integración de sistemas

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

Preguntas frecuentes

P: ¿La CLI requiere instalación adicional?

No. La CLI se instala junto con la aplicación VMs; una vez habilitada la aplicación, basta con ejecutar el comando vms para usarla.

P: ¿Es obligatorio usar la CLI a través de SSH?

No. La CLI puede invocarse desde cualquier terminal de línea de comandos, incluidos el terminal local, SSH remoto, scripts, herramientas de IA, etc.

P: ¿Puede la CLI administrar máquinas virtuales de otros dispositivos?

No. La CLI se comunica con el servicio VMs mediante el unix socket local y solo sirve para administrar las máquinas virtuales del equipo local.

P: ¿Por qué algunos comandos solicitan confirmación y otros no?

Operaciones como eliminar una máquina virtual, eliminar una red, eliminar una imagen, eliminar un espacio de almacenamiento y el apagado (poweroff, force-poweroff) afectan a los datos o a los servicios, por lo que requieren confirmación de forma predeterminada; los comandos de inicio, reinicio, pausa, reanudación y consulta no tienen este tipo de limitación.

P: ¿Cómo se confirman las operaciones peligrosas en el modo no interactivo?

Todas las operaciones peligrosas deben añadir el parámetro --yes; de lo contrario, el comando informa de un error y finaliza (código de salida 1).

P: ¿Cómo determinar en un script si un comando se ejecutó correctamente?

Mediante el código de salida: 0 indica éxito y un valor distinto de 0 indica fallo. También puede analizarse el contenido de la salida de --json.

P: ¿Por qué la lista de la salida de --json es un objeto?

La salida JSON de algunos comandos se organiza en un objeto por ID, con un campo totalCount adjunto, lo que facilita el acceso directo por ID.

Más ayuda

Todos los comandos admiten --help para consultar el uso detallado:

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

Introducción​

Características principales​

Inicio rápido​

Opciones globales​

Ejemplo de información de versión​

Entorno de ejecución​

Tabla resumen de comandos​

Referencia de comandos​

1. Consulta de máquinas virtuales​

vms vm list – Enumera las máquinas virtuales​

vms vm get – Consulta los detalles de la máquina virtual​

vms vm list-resource – Enumera los recursos disponibles para crear máquinas virtuales​

vms vm logs – Consulta el registro de operaciones de la máquina virtual​

2. Administración de energía de máquinas virtuales​

vms vm poweron – Inicia la máquina virtual​

vms vm poweroff – Apaga la máquina virtual​

vms vm force-poweroff – Fuerza el apagado de la máquina virtual (alto riesgo)​

vms vm reboot – Reinicia la máquina virtual​

vms vm pause – Pausa la máquina virtual​

vms vm resume – Reanuda la máquina virtual​

vms vm autorun – Configura el inicio automático al arrancar​

3. Copia, exportación y eliminación de máquinas virtuales​

vms vm clone – Clona la máquina virtual​

vms vm export – Exporta la máquina virtual​

vms vm delete – Elimina la máquina virtual (alto riesgo)​

4. Discos virtuales​

vms vm disk list – Consulta los discos virtuales​

5. Administración de instantáneas​

vms vm snapshot list – Enumera las instantáneas​

vms vm snapshot create – Crea una instantánea​

vms vm snapshot edit – Edita la instantánea​

vms vm snapshot config – Consulta la configuración de la máquina virtual de la instantánea​

vms vm snapshot consistency – Previsualiza la consistencia de la instantánea​

6. Consola remota​

vms vm link – Obtiene la información de conexión VNC​

7. Administración de redes virtuales​

vms network list – Enumera las redes virtuales​

vms network get – Consulta los detalles de la red virtual​

vms network create – Crea una red virtual​

vms network update – Actualiza la red virtual​

vms network delete – Elimina la red virtual (alto riesgo)​

vms network list-interfaces – Enumera las interfaces de red​

vms network list-vnics – Enumera las tarjetas de red virtuales de la red​

vms network ovsinfo – Consulta el estado de OVS​

8. Administración de imágenes​

vms image list – Enumera las imágenes​

vms image edit – Edita la imagen​

vms image delete – Elimina la imagen (alto riesgo)​

vms image list-vms – Consulta las máquinas virtuales que utilizan esta imagen​

9. Administración de espacios de almacenamiento​

vms repo list – Enumera los espacios de almacenamiento​

vms repo get – Consulta los detalles del espacio de almacenamiento​

vms repo update – Actualiza el espacio de almacenamiento​

vms repo delete – Elimina el espacio de almacenamiento (alto riesgo)​

vms repo list-volumes – Enumera los volúmenes disponibles​

vms repo list-vms – Enumera las máquinas virtuales del espacio de almacenamiento​

vms repo check-running – Comprueba las máquinas virtuales en ejecución en el espacio de almacenamiento​

vms repo whether-exist-data – Comprueba si existen datos en el espacio de almacenamiento​

10. Configuración global​

vms setting get – Consulta la configuración global​

11. Consulta de información de monitoreo​

vms collectd hostinfo – Consulta la información de monitoreo del host​

vms collectd vminfo – Consulta la información de monitoreo de la máquina virtual​

vms collectd storageinfo – Consulta la información de monitoreo del almacenamiento​

Modo interactivo y modo no interactivo​

Modo interactivo (entorno de terminal)​

Modo no interactivo (scripts/automatización)​

Formato de salida JSON​

Descripción de los códigos de salida​

Ejemplos de casos de uso​

Operaciones diarias​

Operaciones por lotes con scripts​

Copia de seguridad e inspección​

Comprobación antes de eliminar​

Invocación desde herramientas de IA​

Desarrollo interno e integración de sistemas​

Preguntas frecuentes​

Más ayuda​

Introducción

Características principales

Inicio rápido

Opciones globales

Ejemplo de información de versión

Entorno de ejecución

Tabla resumen de comandos

Referencia de comandos

1. Consulta de máquinas virtuales

vms vm list – Enumera las máquinas virtuales

vms vm get – Consulta los detalles de la máquina virtual

vms vm list-resource – Enumera los recursos disponibles para crear máquinas virtuales

vms vm logs – Consulta el registro de operaciones de la máquina virtual

2. Administración de energía de máquinas virtuales

vms vm poweron – Inicia la máquina virtual

vms vm poweroff – Apaga la máquina virtual

vms vm force-poweroff – Fuerza el apagado de la máquina virtual (alto riesgo)

vms vm reboot – Reinicia la máquina virtual

vms vm pause – Pausa la máquina virtual

vms vm resume – Reanuda la máquina virtual

vms vm autorun – Configura el inicio automático al arrancar

3. Copia, exportación y eliminación de máquinas virtuales

vms vm clone – Clona la máquina virtual

vms vm export – Exporta la máquina virtual

vms vm delete – Elimina la máquina virtual (alto riesgo)

4. Discos virtuales

vms vm disk list – Consulta los discos virtuales

5. Administración de instantáneas

vms vm snapshot list – Enumera las instantáneas

vms vm snapshot create – Crea una instantánea

vms vm snapshot edit – Edita la instantánea

vms vm snapshot config – Consulta la configuración de la máquina virtual de la instantánea

vms vm snapshot consistency – Previsualiza la consistencia de la instantánea

6. Consola remota

vms vm link – Obtiene la información de conexión VNC

7. Administración de redes virtuales

vms network list – Enumera las redes virtuales

vms network get – Consulta los detalles de la red virtual

vms network create – Crea una red virtual

vms network update – Actualiza la red virtual

vms network delete – Elimina la red virtual (alto riesgo)

vms network list-interfaces – Enumera las interfaces de red

vms network list-vnics – Enumera las tarjetas de red virtuales de la red

vms network ovsinfo – Consulta el estado de OVS

8. Administración de imágenes

vms image list – Enumera las imágenes

vms image edit – Edita la imagen

vms image delete – Elimina la imagen (alto riesgo)

vms image list-vms – Consulta las máquinas virtuales que utilizan esta imagen

9. Administración de espacios de almacenamiento

vms repo list – Enumera los espacios de almacenamiento

vms repo get – Consulta los detalles del espacio de almacenamiento

vms repo update – Actualiza el espacio de almacenamiento

vms repo delete – Elimina el espacio de almacenamiento (alto riesgo)

vms repo list-volumes – Enumera los volúmenes disponibles

vms repo list-vms – Enumera las máquinas virtuales del espacio de almacenamiento

vms repo check-running – Comprueba las máquinas virtuales en ejecución en el espacio de almacenamiento

vms repo whether-exist-data – Comprueba si existen datos en el espacio de almacenamiento

10. Configuración global

vms setting get – Consulta la configuración global

11. Consulta de información de monitoreo

vms collectd hostinfo – Consulta la información de monitoreo del host

vms collectd vminfo – Consulta la información de monitoreo de la máquina virtual

vms collectd storageinfo – Consulta la información de monitoreo del almacenamiento

Modo interactivo y modo no interactivo

Modo interactivo (entorno de terminal)

Modo no interactivo (scripts/automatización)

Formato de salida JSON

Descripción de los códigos de salida

Ejemplos de casos de uso

Operaciones diarias

Operaciones por lotes con scripts

Copia de seguridad e inspección

Comprobación antes de eliminar

Invocación desde herramientas de IA

Desarrollo interno e integración de sistemas

Preguntas frecuentes

Más ayuda