Version: TOS 7

VMs CLI

Introdução

O VMs CLI é a ferramenta de gerenciamento por linha de comando do aplicativo de virtualização VMs da TerraMaster e oferece recursos de consulta e operação consistentes com a interface de gerenciamento web. A CLI se comunica com o serviço VMs por meio do unix socket local, adota uma interface de comandos padronizada e um formato de saída JSON, e pode ser integrada a scripts, operações automatizadas e fluxos de trabalho de desenvolvimento secundário.

Principais características

Pronto para uso: é instalado junto com o aplicativo VMs, sem necessidade de instalação adicional
Formas de chamada flexíveis: suporta terminal local, SSH remoto, scripts, ferramentas de IA e diversas outras formas de chamada
Modo duplo, interativo e não interativo: adequado tanto à manutenção diária do administrador quanto a scripts e tarefas automatizadas
Suporte a saída JSON: facilita a análise por programas e a integração automatizada
Comunicação local: comunica-se com o serviço VMs apenas por meio do unix socket local, sem abrir portas para o exterior
Confirmação secundária para operações perigosas: operações como excluir uma máquina virtual ou excluir uma rede exigem confirmação por padrão

Início 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    -

Opções globais

As opções a seguir se aplicam a todos os comandos:

Opção	Abreviação	Descrição
`--help`	`-h`	Exibe as informações de ajuda do comando
`--version`	`-v`	Exibe o número da versão (pode ser combinado com `--json` para gerar informações estruturadas)
`--json`	-	Gera a saída no formato JSON
`--yes`	`-y`	Ignora a solicitação de confirmação das operações perigosas (obrigatório no modo não interativo)
`--debug`	-	Ativa a saída de depuração e exibe o processo de execução detalhado
`--socket <path>`	-	Caminho do unix socket do VMs, por padrão `/var/api/VMs.sock`
`--timeout <duration>`	-	Tempo limite da solicitação, por padrão 30s

Exemplo de informações da versão

vms --version

vms CLI v1.0.058

vms --version --json

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

Ambiente de execução

O VMs CLI é instalado junto com o aplicativo VMs. Quando o aplicativo está habilitado, vincula a CLI ao diretório PATH padrão do sistema, portanto é possível usá-la diretamente após fazer login por SSH.

Item	Descrição
Arquivo da CLI	`/Volume1/@apps/VMs/bin/vms`
Caminho do comando	`/usr/local/sbin/vms` (já presente no PATH do sistema)
Forma de comunicação	unix socket local, por padrão `/var/api/VMs.sock`
Público-alvo	Administradores que fazem login no dispositivo local

Observações:

A CLI serve para gerenciar as máquinas virtuais do dispositivo local e não oferece suporte ao gerenciamento remoto de outros dispositivos por meio da CLI.
O backend sempre retorna HTTP 200; o sucesso do comando é determinado pelo campo code no corpo da resposta, e a CLI o converte no código de saída correspondente.
Operações perigosas (excluir máquinas virtuais, excluir redes, excluir imagens, excluir espaços de armazenamento) solicitam confirmação no modo interativo e exigem a passagem explícita de --yes no modo não interativo.

Tabela resumida de comandos

A seguir há um resumo de referência rápida de todos os comandos vms:

Comando principal	Subcomando	Descrição da função	Requer confirmação	Alto risco
vms	--version	Exibe as informações da versão	Não	Não
vms vm	list	Lista todas as máquinas virtuais	Não	Não
vms vm	get	Exibe os detalhes de uma máquina virtual especificada	Não	Não
vms vm	list-resource	Lista os recursos disponíveis para criar máquinas virtuais	Não	Não
vms vm	logs	Exibe o registro de operações da máquina virtual	Não	Não
vms vm	poweron	Inicia a máquina virtual	Não	Não
vms vm	poweroff	Desliga a máquina virtual (desligamento normal)	Sim	Não
vms vm	force-poweroff	Força o desligamento da máquina virtual	Sim	✅
vms vm	reboot	Reinicia a máquina virtual	Não	Não
vms vm	pause	Pausa a máquina virtual	Não	Não
vms vm	resume	Retoma a máquina virtual pausada	Não	Não
vms vm	autorun	Define a inicialização automática ao ligar	Não	Não
vms vm	clone	Clona a máquina virtual	Não	Não
vms vm	export	Exporta a máquina virtual como arquivo OVA	Não	Não
vms vm	delete	Exclui a máquina virtual	Sim	✅
vms vm disk	list	Exibe os discos virtuais da máquina virtual	Não	Não
vms vm snapshot	list	Lista os snapshots da máquina virtual	Não	Não
vms vm snapshot	create	Cria um snapshot	Não	Não
vms vm snapshot	edit	Edita a descrição e o estado de bloqueio do snapshot	Não	Não
vms vm snapshot	config	Exibe a configuração da máquina virtual salva no snapshot	Não	Não
vms vm snapshot	consistency	Pré-visualiza a consistência do snapshot	Não	Não
vms vm	link	Obtém as informações de conexão do console VNC	Não	Não
vms network	list	Lista as redes virtuais	Não	Não
vms network	get	Exibe os detalhes da rede virtual	Não	Não
vms network	create	Cria uma rede virtual	Não	Não
vms network	update	Atualiza a rede virtual	Não	Não
vms network	delete	Exclui a rede virtual	Sim	✅
vms network	list-interfaces	Lista as interfaces de rede do tipo especificado	Não	Não
vms network	list-vnics	Lista as placas de rede virtuais na rede	Não	Não
vms network	ovsinfo	Verifica se o OVS está habilitado	Não	Não
vms image	list	Lista as imagens	Não	Não
vms image	edit	Edita as informações da imagem	Não	Não
vms image	delete	Exclui a imagem	Sim	✅
vms image	list-vms	Exibe as máquinas virtuais que usam essa imagem	Não	Não
vms repo	list	Lista os espaços de armazenamento	Não	Não
vms repo	get	Exibe os detalhes do espaço de armazenamento	Não	Não
vms repo	update	Atualiza a configuração do espaço de armazenamento	Não	Não
vms repo	delete	Exclui o espaço de armazenamento	Sim	✅
vms repo	list-volumes	Lista os volumes disponíveis	Não	Não
vms repo	list-vms	Lista as máquinas virtuais no espaço de armazenamento	Não	Não
vms repo	check-running	Verifica as máquinas virtuais em execução no espaço de armazenamento	Não	Não
vms repo	whether-exist-data	Verifica se existem dados no espaço de armazenamento	Não	Não
vms setting	get	Exibe as configurações globais	Não	Não
vms collectd	hostinfo	Exibe as informações de monitoramento do host	Não	Não
vms collectd	vminfo	Exibe as informações de monitoramento da máquina virtual	Não	Não
vms collectd	storageinfo	Exibe as informações de monitoramento do armazenamento	Não	Não

Referência de comandos

Nos comandos, <id> é o ID da máquina virtual, correspondente ao GUEST ID na saída da lista de máquinas virtuais; <network_id>, <image_id> e <repo_id> funcionam de forma semelhante e podem ser obtidos, respectivamente, por meio de vms network list, vms image list e vms repo list.

Sobre os exemplos de saída: a saída em tabela de vms trunca os valores de campos muito longos em uma largura fixa (terminando em reticências e independentemente da largura do terminal), por exemplo VDISKS, VNICS e ISO IMAGES na configuração da máquina virtual, bem como os nomes das imagens. Por isso, neste documento os comandos que envolvem campos longos fornecem uniformemente um exemplo de saída --json completo, e os demais comandos fornecem exemplos de saída em tabela. Ao processar com scripts, também se recomenda usar uniformemente --json.

1. Consulta de máquinas virtuais

vms vm list – Lista as máquinas virtuais

Lista todas as máquinas virtuais do dispositivo local e seu estado básico.

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

--limit e --offset são parâmetros de paginação
Colunas de saída: nome, ID da máquina virtual, estado de execução, número de núcleos de CPU, tamanho da memória (em KB), endereço IP

Exemplo de saída:

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 comuns de STATUS:

Estado	Descrição
running	Em execução
shutdown	Desligada
saved	Em pausa (o estado de execução foi salvo no disco)

vms vm get – Exibe os detalhes da máquina virtual

Exibe a configuração completa e o estado de execução da máquina virtual especificada.

vms vm get <id> --json

A saída inclui todos os campos de configuração e de estado de execução da máquina virtual
Valores vazios, como a ausência de descrição ou de IP, são exibidos como uma cadeia de caracteres vazia
Se a máquina virtual não existir, o comando retorna um erro e exibe as informações do erro

Exemplo de saída:

{
  "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 – Lista os recursos disponíveis para criar máquinas virtuais

Exibe os recursos que o host pode fornecer, como tipos de firmware, imagens, CPU, memória, redes, espaços de armazenamento e dispositivos de passagem direta, para avaliação antes de criar uma máquina virtual.

vms vm list-resource --json

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

Exemplo de saída:

{
  "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 – Exibe o registro de operações da máquina virtual

Exibe o registro de operações relacionadas à máquina virtual especificada (ligar e desligar, snapshots, edição, importação e exportação, etc.).

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

--limit especifica o número de entradas retornadas, por padrão 50
--desc ordena por tempo de forma decrescente (ativado por padrão)
Cada entrada do registro inclui hora, nível, categoria, usuário da operação e descrição do evento; a descrição do evento é um texto completo
A descrição do evento (event) é gerada pelo serviço VMs localizada conforme o idioma do sistema do dispositivo; os exemplos deste documento usam uniformemente o inglês

Exemplo de saída:

[
  {
    "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. Gerenciamento de energia das máquinas virtuais

vms vm poweron – Inicia a máquina virtual

vms vm poweron <id>

A máquina virtual deve estar desligada; caso contrário, retorna um erro de conflito de estado
Saída: VM powered on: <id>

vms vm poweroff – Desliga a máquina virtual

Envia à máquina virtual uma solicitação de desligamento normal, para que o sistema seja encerrado de forma adequada.

vms vm poweroff <id> [--yes]

É uma operação perigosa: no modo interativo solicita confirmação e, no modo não interativo, é obrigatório adicionar --yes
A máquina virtual deve estar em execução; caso contrário, retorna um erro de conflito de estado

Solicitação de confirmação no modo interativo:

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

Saída: VM powered off: <id>

vms vm force-poweroff – Força o desligamento da máquina virtual (alto risco)

Força o desligamento da máquina virtual, o que equivale a cortar a energia diretamente.

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

É uma operação de alto risco: no modo interativo solicita confirmação e, no modo não interativo, é obrigatório adicionar --yes
Pode causar perda de dados dentro da máquina virtual; recomenda-se usá-lo apenas quando a máquina virtual não responder

Solicitação de confirmação no modo interativo:

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

Saída: VM force powered off: <id>

vms vm reboot – Reinicia a máquina virtual

vms vm reboot <id>

Saída: VM rebooted: <id>

vms vm pause – Pausa a máquina virtual

Congela o estado de execução da máquina virtual e salva o estado atual no disco.

vms vm pause <id>

A máquina virtual deve estar em execução; caso contrário, retorna um erro de conflito de estado
Após a pausa, o estado da máquina virtual é exibido como saved
Saída: VM paused: <id>

vms vm resume – Retoma a máquina virtual

Restaura a máquina virtual do estado de pausa para o estado de execução.

vms vm resume <id>

A máquina virtual deve estar em pausa; caso contrário, retorna um erro de conflito de estado
Saída: VM resumed: <id>

vms vm autorun – Define a inicialização automática ao ligar

Define se a máquina virtual deve ser iniciada automaticamente ao ligar o host.

vms vm autorun <id> <true|false>

O segundo parâmetro deve ser true ou false
O comando lê a configuração atual e modifica apenas o interruptor de inicialização automática; as demais configurações não são afetadas
Saída: Auto-start enabled for VM <id> ou Auto-start disabled for VM <id>

3. Cópia, exportação e exclusão de máquinas virtuais

vms vm clone – Clona a máquina virtual

Cria uma nova máquina virtual copiando uma máquina virtual existente como modelo.

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

No corpo da solicitação, guest_id é o ID da máquina virtual de origem e name (ou guest_name) é o nome da nova máquina virtual
A máquina virtual de origem deve estar desligada
--body passa o corpo da solicitação diretamente como uma cadeia JSON; --file lê o corpo da solicitação de um arquivo

vms vm export – Exporta a máquina virtual

Exporta a máquina virtual como arquivo OVA, o que facilita o backup ou a migração para outras plataformas de virtualização.

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

No corpo da solicitação, guest_id é o ID da máquina virtual de origem, target_ova_path é o caminho do arquivo de destino e ova_mode é o modo de compatibilidade com VMware opcional
A máquina virtual de origem deve estar desligada
A exportação é uma tarefa demorada; a exportação de máquinas virtuais de grande capacidade leva mais tempo

vms vm delete – Exclui a máquina virtual (alto risco)

Exclui permanentemente a máquina virtual.

vms vm delete <id> [--yes]

É uma operação de alto risco: no modo interativo solicita confirmação e, no modo não interativo, é obrigatório adicionar --yes
Após a exclusão, não é possível recuperá-la; confirme com antecedência que os dados dentro da máquina virtual foram copiados

Solicitação de confirmação no modo interativo:

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

Saída: VM deleted: <id>

4. Discos virtuais

vms vm disk list – Exibe os discos virtuais

Lista todos os discos virtuais da máquina virtual especificada.

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

Exemplo de saída:

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

VDISK MODE é o número do tipo de controlador do disco virtual; 1 indica IDE
Os discos virtuais sem nome são exibidos como - na coluna NAME

5. Gerenciamento de snapshots

vms vm snapshot list – Lista os snapshots

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

Exemplo de saída:

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 é o estado de execução da máquina virtual no momento da criação do snapshot
ACTUAL CONSISTENCY é o tipo de consistência do snapshot; filesystem indica consistência do sistema de arquivos e crash indica consistência de falha

vms vm snapshot create – Cria um snapshot

Cria um snapshot da máquina virtual, para reversão rápida ou backup do estado atual.

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

Corpo da solicitação opcional: description é a descrição do snapshot e locked indica se deve ser bloqueado
O nome do snapshot é gerado automaticamente pelo sistema conforme a hora de criação
Os snapshots ocupam espaço de armazenamento; se não forem limpos por muito tempo, podem encher o espaço de armazenamento, por isso recomenda-se organizá-los periodicamente

vms vm snapshot edit – Edita o snapshot

Modifica a descrição ou o estado de bloqueio do snapshot.

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

Apenas os campos presentes no corpo da solicitação são modificados; os campos ausentes mantêm o valor original; alterar apenas a descrição não muda o estado de bloqueio, e vice-versa

Exemplo de saída:

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 – Exibe a configuração da máquina virtual do snapshot

Exibe a configuração da máquina virtual salva no snapshot.

vms vm snapshot config <id> <snapshot_name>

<id> é o ID da máquina virtual e <snapshot_name> é o nome do snapshot, que pode ser obtido por meio de vms vm snapshot list <id>.

Exemplo de saída:

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é-visualiza a consistência do snapshot

Pré-visualiza o tipo de consistência que pode ser obtido antes de criar um snapshot, ajudando a determinar se o momento atual é adequado para criá-lo.

vms vm snapshot consistency <id>

Exemplo de saída:

PROPERTY          VALUE
CONSISTENCY TYPE  filesystem
REASON            vm_shutdown
VM STATE          shutdown

Criar um snapshot com a máquina virtual desligada permite obter um snapshot com consistência do sistema de arquivos; com a máquina em execução, normalmente só é possível obter um snapshot com consistência de falha.

6. Console remoto

vms vm link – Obtém as informações de conexão VNC

Obtém as informações de conexão do console VNC da máquina virtual, para abrir o console remoto no navegador.

vms vm link <id> --json

A máquina virtual deve estar em execução ou em pausa; caso contrário, retorna um erro de conflito de estado

Exemplo de saída:

{
  "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 é o caminho do console relativo ao endereço de gerenciamento do NAS, port é a porta do serviço do console e https indica se é necessário acessar por HTTPS
Na saída JSON, o & presente na URL é escapado como \u0026

7. Gerenciamento de redes virtuais

Os tipos de rede se dividem em dois:

Tipo	Descrição
Privada (private)	Rede interna que permite apenas a comunicação entre as máquinas virtuais do dispositivo local, sem ser vinculada a uma placa de rede física
Externa (external)	Rede vinculada a uma placa de rede física, por meio da qual as máquinas virtuais podem se comunicar com o exterior

vms network list – Lista as redes virtuais

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

Exemplo de saída:

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 é o número de máquinas virtuais conectadas a essa rede e NUM INTERFACES é o número de placas de rede físicas selecionadas

vms network get – Exibe os detalhes da rede virtual

vms network get <network_id> --json

Exemplo de saída:

{
  "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 são as informações das placas de rede vinculadas a essa rede, organizadas por ID de host, e checked indica se a placa de rede está selecionada
metadata registra a hora de criação e de atualização da rede

vms network create – Cria uma rede 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

Criar uma rede privada:

O corpo da solicitação deve incluir name, type (private) e host_name ou host_id, para especificar em qual host a rede é criada
Antes de criá-la, é possível verificar os hosts disponíveis por meio de vms network list-interfaces private

Criar uma rede externa:

O corpo da solicitação deve incluir name, type (external) e vlan_id, e especificar pelo menos uma placa de rede física
É possível especificar a placa de rede por meio de interface_name (como LAN 1) ou interface_id; se o nome da placa de rede não for exclusivo entre hosts, é preciso combiná-lo com host_name
Antes de criá-la, é possível verificar as placas de rede disponíveis por meio de vms network list-interfaces external

A saída são as informações da rede após a criação, com a mesma estrutura 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
}

Se nenhuma placa de rede for especificada, o comando emite um 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 – Atualiza a rede virtual

Apenas os campos que precisam ser modificados são enviados; os campos não enviados mantêm o valor original.

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

O corpo da solicitação deve incluir network_id
O comando lê primeiro a configuração atual da rede e mescla os campos enviados; o nome da rede e as placas de rede selecionadas não são apagados
A saída são as informações da rede após a atualização

vms network delete – Exclui a rede virtual (alto risco)

vms network delete <network_id> [--yes]

É uma operação de alto risco: no modo interativo solicita confirmação e, no modo não interativo, é obrigatório adicionar --yes
Excluir a rede desconecta todas as máquinas virtuais conectadas a ela
Recomenda-se confirmar primeiro as máquinas virtuais conectadas por meio de vms network list-vnics <network_id>

Solicitação de confirmação no modo interativo:

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

Saída: Network deleted: <network_id>

vms network list-interfaces – Lista as interfaces de rede

Lista as interfaces de rede do tipo especificado.

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

external retorna as placas de rede físicas disponíveis no host
private retorna as informações dos hosts que podem ser usados para criar redes privadas

Exemplo de saída (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

Exemplo de saída (private):

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

vms network list-vnics – Lista as placas de rede virtuais na rede

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

Exemplo de saída:

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 – Exibe o estado do OVS

Confirma se o switch virtual Open vSwitch está habilitado.

vms network ovsinfo [--json]

Exemplo de saída:

PROPERTY  VALUE
RESULT    true

Se VALUE for true, o OVS está habilitado.

8. Gerenciamento de imagens

vms image list – Lista as imagens

Lista os arquivos de imagem de sistema disponíveis para criar máquinas virtuais.

vms image list --json

image_name é o nome da imagem e file_name é o nome do arquivo correspondente
type é o formato da imagem, como iso ou qcow2
status é o estado da imagem; available indica que está disponível
repos é o espaço de armazenamento onde a imagem está localizada
progress é o progresso da tarefa de processamento da imagem; 0 indica que não há tarefas em andamento

Exemplo de saída:

{
  "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 a imagem

Modifica o nome da imagem ou ajusta o espaço de armazenamento onde ela está localizada.

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

O corpo da solicitação deve incluir image_id e repos; repos é a lista completa de espaços de armazenamento de destino da imagem e não pode ficar vazia
image_name, file_name, type e file_size são campos opcionais; se não forem fornecidos, mantêm-se os valores atuais
Se repos estiver vazio, a imagem seria removida de todos os espaços de armazenamento; o comando rejeita a solicitação antes de executá-la
Saída: Image updated

vms image delete – Exclui a imagem (alto risco)

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

--image-id é obrigatório
É uma operação de alto risco: no modo interativo solicita confirmação e, no modo não interativo, é obrigatório adicionar --yes
Excluir a imagem não afeta as máquinas virtuais já criadas, mas afeta a criação posterior de máquinas virtuais com base nessa imagem
Recomenda-se confirmar primeiro o uso por meio de vms image list-vms --image-id <image_id>

Solicitação de confirmação no modo interativo:

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

Saída: Image deleted: <image_id>

vms image list-vms – Exibe as máquinas virtuais que usam essa imagem

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

Exemplo de saída:

GUEST NAME
1454486

Antes de excluir uma imagem, é possível executar este comando para confirmar o alcance do impacto; se nenhuma máquina virtual usar a imagem, a saída fica vazia.

9. Gerenciamento de espaços de armazenamento

vms repo list – Lista os espaços de armazenamento

vms repo list [--json]

Exemplo de saída:

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 – Exibe os detalhes do espaço de armazenamento

vms repo get <repo_id> [--json]

Exemplo de saída:

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 é o volume onde o espaço de armazenamento está localizado
SOFT LIMIT e HARD LIMIT são os limites de alerta de capacidade (percentual)
ENABLE LOWER NOTIFY indica se deve ser habilitado o lembrete de capacidade insuficiente

vms repo update – Atualiza o espaço de armazenamento

Apenas os campos que precisam ser modificados são enviados; os campos não enviados mantêm o valor original.

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

O ID do espaço de armazenamento pode ser passado por meio de repo_id ou repoId
O comando lê primeiro a configuração atual e mescla os campos enviados; as demais configurações não são perdidas
A saída são as informações do espaço de armazenamento após a atualização

vms repo delete – Exclui o espaço de armazenamento (alto risco)

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

O segundo parâmetro é need_save_data: true indica que os arquivos de dados no disco são mantidos, false indica que são excluídos junto com os dados
É uma operação de alto risco: no modo interativo solicita confirmação e, no modo não interativo, é obrigatório adicionar --yes
Excluir o espaço de armazenamento também remove as máquinas virtuais e as imagens nele contidas; recomenda-se executar primeiro vms repo check-running e vms repo whether-exist-data para confirmar o alcance do impacto

Solicitação de confirmação no modo interativo:

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

Saída: Repository deleted: <repo_id>

vms repo list-volumes – Lista os volumes disponíveis

Lista os volumes disponíveis para criar espaços de armazenamento.

vms repo list-volumes [--json]

Exemplo de saída:

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 – Lista as máquinas virtuais no espaço de armazenamento

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

O ID do espaço de armazenamento pode ser passado por meio de repo_id ou repoId
O comando obtém primeiro o objeto do espaço de armazenamento e depois consulta suas máquinas virtuais, o que torna o resultado mais confiável

vms repo check-running – Verifica as máquinas virtuais em execução no espaço de armazenamento

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

É executado antes de excluir o espaço de armazenamento, para confirmar que não há máquinas virtuais em execução; se não houver máquinas virtuais em execução, a saída fica vazia.

vms repo whether-exist-data – Verifica se existem dados no espaço de armazenamento

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

É executado antes de excluir o espaço de armazenamento, para confirmar se ainda há dados nele; é consistente com a verificação prévia antes de excluir um espaço de armazenamento na interface web.

10. Configurações globais

vms setting get – Exibe as configurações globais

Exibe a configuração global do aplicativo VMs.

vms setting get [--json]

Exemplo de saída:

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

HOST SHUTDOWN BEHAVIOR é a forma de tratar as máquinas virtuais quando o host é desligado
KB LAYOUT é o layout do teclado da máquina virtual

11. Consulta de informações de monitoramento

vms collectd hostinfo – Exibe as informações de monitoramento do host

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

Exemplo de saída:

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

vms collectd vminfo – Exibe as informações de monitoramento da máquina virtual

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

Exemplo de saída:

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 – Exibe as informações de monitoramento do armazenamento

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

Exemplo de saída:

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 interativo e modo não interativo

A CLI determina se está sendo executada atualmente em um ambiente de terminal e adota comportamentos diferentes:

Modo interativo (ambiente de terminal)

As operações perigosas exibem uma solicitação de confirmação; a opção padrão é No
Digite y ou Y para continuar; digite n ou pressione Enter para cancelar
Ao cancelar a operação, é exibido Operation cancelled e o código de saída é 99

Modo não interativo (script/automação)

As operações perigosas devem usar --yes para ignorar a confirmação; caso contrário, o comando gera um erro diretamente e retorna o código de saída 1
Quando não há ambiente de terminal, não aguarda entrada, o que o torna adequado a scripts e tarefas agendadas
Recomenda-se tratar explicitamente os códigos de saída nos scripts, para distinguir sucesso, falha e conflito de estado

Formato de saída JSON

Os comandos de consulta suportam o parâmetro --json, que gera dados JSON normalizados para facilitar a análise por programas.

Convenções de formato:

Os nomes dos campos usam snake_case
Os valores booleanos são true/false
O horário usa o formato ISO 8601, com precisão de nanossegundos e deslocamento do fuso horário UTC+8 (por exemplo, 2026-09-02T11:43:51.176535374+08:00)
A saída JSON é enviada para stdout e as mensagens de erro para stderr
Os campos longos truncados na saída em tabela aparecem com o valor completo na saída JSON

Exemplo:

vms setting get --json

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

A estrutura JSON varia ligeiramente entre os comandos: vms vm list, vms vm snapshot list e vms vm logs geram diretamente um array; os demais comandos do tipo lista geram um objeto contendo totalCount e um campo de dados, cujo nome varia conforme o recurso (como items, hosts, vms ou storage). Por exemplo, 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"
    }
  }
}

A saída JSON de alguns comandos é um valor simples; por exemplo, vms network ovsinfo --json gera true e vms vm pause --json gera null.

Descrição dos códigos de saída

Código de saída	Significado	Cenário típico
0	Sucesso	O comando é concluído normalmente
1	Erro de parâmetro	Falta um parâmetro obrigatório, o formato do parâmetro está incorreto ou não foi adicionado `--yes`
3	Recurso não existe	A validação prévia do comando não foi aprovada; por exemplo, a imagem especificada não existe
4	Conflito de estado	O estado atual da máquina virtual não permite a operação (por exemplo, desligar uma máquina virtual já desligada)
6	Erro de conexão	Não é possível conectar ao serviço VMs ou o caminho do socket está incorreto
7	Tempo limite esgotado	O tempo limite da solicitação foi esgotado; pode ser ajustado por meio de `--timeout`
9	Erro de execução	O backend retorna um erro (a mensagem de erro inclui code_num e a descrição do erro)
99	Cancelado pelo usuário	Foi escolhido No na confirmação interativa ou foi pressionado Enter diretamente

Exemplo:

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

Exemplos de cenários de uso

Operações diárias

# 查看所有虚拟机状态
vms vm list

# 查看某台虚拟机的配置与运行状态
vms vm get <id>

# 查看虚拟机的操作日志
vms vm logs <id> --limit 20

# 开机、关机与重启
vms vm poweron <id>
vms vm poweroff <id> --yes
vms vm reboot <id>

Operações em lote com 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'

Backup e inspeção

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

Verificação antes da exclusão

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

Chamada por ferramentas de IA

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

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

Desenvolvimento interno e integração 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 @-

Perguntas frequentes

P: A CLI precisa de instalação adicional?

Não. A CLI é instalada junto com o aplicativo VMs; após habilitar o aplicativo, basta executar o comando vms para usá-la.

P: É obrigatório usar a CLI por SSH?

Não. A CLI pode ser chamada em qualquer terminal de linha de comando, incluindo terminal local, SSH remoto, scripts, ferramentas de IA, etc.

P: A CLI pode gerenciar máquinas virtuais de outros dispositivos?

Não. A CLI se comunica com o serviço VMs por meio do unix socket local e serve apenas para gerenciar as máquinas virtuais do dispositivo local.

P: Por que alguns comandos solicitam confirmação e outros não?

Operações como excluir uma máquina virtual, excluir uma rede, excluir uma imagem, excluir um espaço de armazenamento e o desligamento (poweroff, force-poweroff) afetam os dados ou os serviços, por isso exigem confirmação por padrão; os comandos de inicialização, reinicialização, pausa, retomada e consulta não têm esse tipo de limitação.

P: Como confirmar operações perigosas no modo não interativo?

Todas as operações perigosas devem adicionar o parâmetro --yes; caso contrário, o comando gera um erro e termina (código de saída 1).

P: Como determinar em um script se um comando foi executado com sucesso?

Por meio do código de saída: 0 indica sucesso e um valor diferente de 0 indica falha. Também é possível analisar o conteúdo da saída de --json.

P: Por que a lista da saída de --json é um objeto?

A saída JSON de alguns comandos é organizada em um objeto por ID, com um campo totalCount anexado, o que facilita o acesso direto por ID.

Mais ajuda

Todos os comandos suportam --help para consultar o uso detalhado:

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

Introdução​

Principais características​

Início rápido​

Opções globais​

Exemplo de informações da versão​

Ambiente de execução​

Tabela resumida de comandos​

Referência de comandos​

1. Consulta de máquinas virtuais​

vms vm list – Lista as máquinas virtuais​

vms vm get – Exibe os detalhes da máquina virtual​

vms vm list-resource – Lista os recursos disponíveis para criar máquinas virtuais​

vms vm logs – Exibe o registro de operações da máquina virtual​

2. Gerenciamento de energia das máquinas virtuais​

vms vm poweron – Inicia a máquina virtual​

vms vm poweroff – Desliga a máquina virtual​

vms vm force-poweroff – Força o desligamento da máquina virtual (alto risco)​

vms vm reboot – Reinicia a máquina virtual​

vms vm pause – Pausa a máquina virtual​

vms vm resume – Retoma a máquina virtual​

vms vm autorun – Define a inicialização automática ao ligar​

3. Cópia, exportação e exclusão de máquinas virtuais​

vms vm clone – Clona a máquina virtual​

vms vm export – Exporta a máquina virtual​

vms vm delete – Exclui a máquina virtual (alto risco)​

4. Discos virtuais​

vms vm disk list – Exibe os discos virtuais​

5. Gerenciamento de snapshots​

vms vm snapshot list – Lista os snapshots​

vms vm snapshot create – Cria um snapshot​

vms vm snapshot edit – Edita o snapshot​

vms vm snapshot config – Exibe a configuração da máquina virtual do snapshot​

vms vm snapshot consistency – Pré-visualiza a consistência do snapshot​

6. Console remoto​

vms vm link – Obtém as informações de conexão VNC​

7. Gerenciamento de redes virtuais​

vms network list – Lista as redes virtuais​

vms network get – Exibe os detalhes da rede virtual​

vms network create – Cria uma rede virtual​

vms network update – Atualiza a rede virtual​

vms network delete – Exclui a rede virtual (alto risco)​

vms network list-interfaces – Lista as interfaces de rede​

vms network list-vnics – Lista as placas de rede virtuais na rede​

vms network ovsinfo – Exibe o estado do OVS​

8. Gerenciamento de imagens​

vms image list – Lista as imagens​

vms image edit – Edita a imagem​

vms image delete – Exclui a imagem (alto risco)​

vms image list-vms – Exibe as máquinas virtuais que usam essa imagem​

9. Gerenciamento de espaços de armazenamento​

vms repo list – Lista os espaços de armazenamento​

vms repo get – Exibe os detalhes do espaço de armazenamento​

vms repo update – Atualiza o espaço de armazenamento​

vms repo delete – Exclui o espaço de armazenamento (alto risco)​

vms repo list-volumes – Lista os volumes disponíveis​

vms repo list-vms – Lista as máquinas virtuais no espaço de armazenamento​

vms repo check-running – Verifica as máquinas virtuais em execução no espaço de armazenamento​

vms repo whether-exist-data – Verifica se existem dados no espaço de armazenamento​

10. Configurações globais​

vms setting get – Exibe as configurações globais​

11. Consulta de informações de monitoramento​

vms collectd hostinfo – Exibe as informações de monitoramento do host​

vms collectd vminfo – Exibe as informações de monitoramento da máquina virtual​

vms collectd storageinfo – Exibe as informações de monitoramento do armazenamento​

Modo interativo e modo não interativo​

Modo interativo (ambiente de terminal)​

Modo não interativo (script/automação)​

Formato de saída JSON​

Descrição dos códigos de saída​

Exemplos de cenários de uso​

Operações diárias​

Operações em lote com scripts​

Backup e inspeção​

Verificação antes da exclusão​

Chamada por ferramentas de IA​

Desenvolvimento interno e integração de sistemas​

Perguntas frequentes​

Mais ajuda​

Introdução

Principais características

Início rápido

Opções globais

Exemplo de informações da versão

Ambiente de execução

Tabela resumida de comandos

Referência de comandos

1. Consulta de máquinas virtuais

vms vm list – Lista as máquinas virtuais

vms vm get – Exibe os detalhes da máquina virtual

vms vm list-resource – Lista os recursos disponíveis para criar máquinas virtuais

vms vm logs – Exibe o registro de operações da máquina virtual

2. Gerenciamento de energia das máquinas virtuais

vms vm poweron – Inicia a máquina virtual

vms vm poweroff – Desliga a máquina virtual

vms vm force-poweroff – Força o desligamento da máquina virtual (alto risco)

vms vm reboot – Reinicia a máquina virtual

vms vm pause – Pausa a máquina virtual

vms vm resume – Retoma a máquina virtual

vms vm autorun – Define a inicialização automática ao ligar

3. Cópia, exportação e exclusão de máquinas virtuais

vms vm clone – Clona a máquina virtual

vms vm export – Exporta a máquina virtual

vms vm delete – Exclui a máquina virtual (alto risco)

4. Discos virtuais

vms vm disk list – Exibe os discos virtuais

5. Gerenciamento de snapshots

vms vm snapshot list – Lista os snapshots

vms vm snapshot create – Cria um snapshot

vms vm snapshot edit – Edita o snapshot

vms vm snapshot config – Exibe a configuração da máquina virtual do snapshot

vms vm snapshot consistency – Pré-visualiza a consistência do snapshot

6. Console remoto

vms vm link – Obtém as informações de conexão VNC

7. Gerenciamento de redes virtuais

vms network list – Lista as redes virtuais

vms network get – Exibe os detalhes da rede virtual

vms network create – Cria uma rede virtual

vms network update – Atualiza a rede virtual

vms network delete – Exclui a rede virtual (alto risco)

vms network list-interfaces – Lista as interfaces de rede

vms network list-vnics – Lista as placas de rede virtuais na rede

vms network ovsinfo – Exibe o estado do OVS

8. Gerenciamento de imagens

vms image list – Lista as imagens

vms image edit – Edita a imagem

vms image delete – Exclui a imagem (alto risco)

vms image list-vms – Exibe as máquinas virtuais que usam essa imagem

9. Gerenciamento de espaços de armazenamento

vms repo list – Lista os espaços de armazenamento

vms repo get – Exibe os detalhes do espaço de armazenamento

vms repo update – Atualiza o espaço de armazenamento

vms repo delete – Exclui o espaço de armazenamento (alto risco)

vms repo list-volumes – Lista os volumes disponíveis

vms repo list-vms – Lista as máquinas virtuais no espaço de armazenamento

vms repo check-running – Verifica as máquinas virtuais em execução no espaço de armazenamento

vms repo whether-exist-data – Verifica se existem dados no espaço de armazenamento

10. Configurações globais

vms setting get – Exibe as configurações globais

11. Consulta de informações de monitoramento

vms collectd hostinfo – Exibe as informações de monitoramento do host

vms collectd vminfo – Exibe as informações de monitoramento da máquina virtual

vms collectd storageinfo – Exibe as informações de monitoramento do armazenamento

Modo interativo e modo não interativo

Modo interativo (ambiente de terminal)

Modo não interativo (script/automação)

Formato de saída JSON

Descrição dos códigos de saída

Exemplos de cenários de uso

Operações diárias

Operações em lote com scripts

Backup e inspeção

Verificação antes da exclusão

Chamada por ferramentas de IA

Desenvolvimento interno e integração de sistemas

Perguntas frequentes

Mais ajuda