Version: TOS 7

VMs CLI

Введение

VMs CLI — это инструмент управления виртуализационным приложением TerraMaster VMs из командной строки, предоставляющий возможности запросов и эксплуатации, аналогичные веб-интерфейсу управления. CLI взаимодействует со службой VMs через локальный unix socket, использует стандартизированный интерфейс команд и формат вывода JSON, что позволяет интегрировать его в скрипты, автоматизированные операции и рабочие процессы вторичной разработки.

Основные особенности

Готов к работе из коробки: устанавливается вместе с приложением VMs, дополнительная установка не требуется
Гибкие способы вызова: поддерживаются локальный терминал, удалённый SSH, скрипты, инструменты AI и другие способы вызова
Два режима — интерактивный и неинтерактивный: подходят как для повседневного обслуживания администратором, так и для скриптов и автоматизированных задач
Поддержка вывода JSON: удобно для программного разбора и автоматизированной интеграции
Локальное взаимодействие: связь со службой VMs только через локальный unix socket, порты наружу не открываются
Повторное подтверждение опасных операций: операции удаления виртуальной машины, удаления сети и другие по умолчанию требуют подтверждения

Быстрый старт

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

Глобальные параметры

Следующие параметры применимы ко всем командам:

Параметр	Сокращение	Описание
`--help`	`-h`	Показать справку по команде
`--version`	`-v`	Показать номер версии (можно использовать с `--json` для структурированного вывода)
`--json`	-	Вывод в формате JSON
`--yes`	`-y`	Пропустить запрос подтверждения для опасных операций (обязательно в неинтерактивном режиме)
`--debug`	-	Включить отладочный вывод с подробным процессом выполнения
`--socket <path>`	-	Путь к unix socket VMs, по умолчанию `/var/api/VMs.sock`
`--timeout <duration>`	-	Тайм-аут запроса, по умолчанию 30s

Пример информации о версии

vms --version

vms CLI v1.0.058

vms --version --json

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

Среда выполнения

VMs CLI устанавливается вместе с приложением VMs. При включении приложения CLI помещается в системный каталог PATH, и после входа по SSH его можно использовать напрямую.

Пункт	Описание
Файл CLI	`/Volume1/@apps/VMs/bin/vms`
Путь к команде	`/usr/local/sbin/vms` (уже в системном PATH)
Способ связи	Локальный unix socket, по умолчанию `/var/api/VMs.sock`
Для кого	Администратор, вошедший в систему на локальной машине

Примечания:

CLI предназначен для управления локальными виртуальными машинами; удалённое управление другими устройствами через CLI не поддерживается.
Бэкенд всегда возвращает HTTP 200; успешность команды определяется по полю code в теле ответа, на основе которого CLI формирует код выхода.
Опасные операции (удаление виртуальной машины, удаление сети, удаление образа, удаление хранилища) в интерактивном режиме запрашивают подтверждение, а в неинтерактивном режиме требуют явного указания --yes.

Сводная таблица команд

Ниже приведён краткий справочник по всем командам vms:

Родительская команда	Подкоманда	Описание функции	Требует подтверждения	Высокий риск
vms	--version	Показать информацию о версии	Нет	Нет
vms vm	list	Список всех виртуальных машин	Нет	Нет
vms vm	get	Просмотр подробностей указанной виртуальной машины	Нет	Нет
vms vm	list-resource	Список ресурсов, доступных для создания виртуальной машины	Нет	Нет
vms vm	logs	Просмотр журнала операций виртуальной машины	Нет	Нет
vms vm	poweron	Запуск виртуальной машины	Нет	Нет
vms vm	poweroff	Выключение виртуальной машины (штатное завершение работы)	Да	Нет
vms vm	force-poweroff	Принудительное выключение виртуальной машины	Да	✅
vms vm	reboot	Перезапуск виртуальной машины	Нет	Нет
vms vm	pause	Приостановка виртуальной машины	Нет	Нет
vms vm	resume	Возобновление приостановленной виртуальной машины	Нет	Нет
vms vm	autorun	Настройка автоматического запуска при загрузке	Нет	Нет
vms vm	clone	Клонирование виртуальной машины	Нет	Нет
vms vm	export	Экспорт виртуальной машины в файл OVA	Нет	Нет
vms vm	delete	Удаление виртуальной машины	Да	✅
vms vm disk	list	Просмотр виртуальных дисков виртуальной машины	Нет	Нет
vms vm snapshot	list	Список снимков виртуальной машины	Нет	Нет
vms vm snapshot	create	Создание снимка	Нет	Нет
vms vm snapshot	edit	Редактирование описания и состояния блокировки снимка	Нет	Нет
vms vm snapshot	config	Просмотр конфигурации виртуальной машины, сохранённой в снимке	Нет	Нет
vms vm snapshot	consistency	Предварительный просмотр согласованности снимка	Нет	Нет
vms vm	link	Получение информации о подключении к консоли VNC	Нет	Нет
vms network	list	Список виртуальных сетей	Нет	Нет
vms network	get	Просмотр подробностей виртуальной сети	Нет	Нет
vms network	create	Создание виртуальной сети	Нет	Нет
vms network	update	Обновление виртуальной сети	Нет	Нет
vms network	delete	Удаление виртуальной сети	Да	✅
vms network	list-interfaces	Список сетевых интерфейсов указанного типа	Нет	Нет
vms network	list-vnics	Список виртуальных сетевых карт в сети	Нет	Нет
vms network	ovsinfo	Просмотр, включён ли OVS	Нет	Нет
vms image	list	Список образов	Нет	Нет
vms image	edit	Редактирование информации об образе	Нет	Нет
vms image	delete	Удаление образа	Да	✅
vms image	list-vms	Просмотр виртуальных машин, использующих этот образ	Нет	Нет
vms repo	list	Список хранилищ	Нет	Нет
vms repo	get	Просмотр подробностей хранилища	Нет	Нет
vms repo	update	Обновление конфигурации хранилища	Нет	Нет
vms repo	delete	Удаление хранилища	Да	✅
vms repo	list-volumes	Список доступных томов	Нет	Нет
vms repo	list-vms	Список виртуальных машин в хранилище	Нет	Нет
vms repo	check-running	Проверка работающих виртуальных машин в хранилище	Нет	Нет
vms repo	whether-exist-data	Проверка наличия данных в хранилище	Нет	Нет
vms setting	get	Просмотр глобальных настроек	Нет	Нет
vms collectd	hostinfo	Просмотр информации о мониторинге хоста	Нет	Нет
vms collectd	vminfo	Просмотр информации о мониторинге виртуальных машин	Нет	Нет
vms collectd	storageinfo	Просмотр информации о мониторинге хранилища	Нет	Нет

Справочник команд

В командах <id> — это ID виртуальной машины, соответствующий GUEST ID в выводе списка виртуальных машин; <network_id>, <image_id>, <repo_id> аналогично можно получить с помощью vms network list, vms image list, vms repo list соответственно.

О примерах вывода: табличный вывод vms выполняет усечение слишком длинных значений полей до фиксированной ширины (с окончанием многоточием и независимо от ширины терминала), например VDISKS, VNICS, ISO IMAGES в конфигурации виртуальной машины, а также имена образов. Поэтому в этом документе для команд с длинными полями единообразно приводятся полные примеры вывода --json, а для остальных команд — примеры табличного вывода. При обработке скриптами также рекомендуется единообразно использовать --json.

I. Запросы виртуальных машин

vms vm list – Список виртуальных машин

Выводит список всех виртуальных машин на локальной машине и их базовые состояния.

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

--limit, --offset — параметры постраничной навигации
Столбцы вывода: имя, ID виртуальной машины, состояние работы, число ядер CPU, размер памяти (в KB), IP-адрес

Пример вывода:

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    -

Частые значения STATUS:

Состояние	Описание
running	Работает
shutdown	Выключена
saved	Приостановлена (состояние работы сохранено на диск)

vms vm get – Просмотр подробностей виртуальной машины

Просмотр полной конфигурации и состояния работы указанной виртуальной машины.

vms vm get <id> --json

Вывод содержит все поля конфигурации и состояния работы виртуальной машины
Пустые значения, например отсутствие описания или IP, отображаются как пустая строка
Если виртуальная машина не существует, команда возвращает ошибку и выводит сообщение об ошибке

Пример вывода:

{
  "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 – Список ресурсов, доступных для создания виртуальной машины

Просмотр доступных на хосте ресурсов: типов прошивки, образов, CPU, памяти, сетей, хранилищ, устройств для проброса и т. д., — для оценки перед созданием виртуальной машины.

vms vm list-resource --json

Возвращаемые поля: max_cpu_num, max_ram_size, usbs, pci_devices, networks, repos, images, video_cards, firmware, keyboard_layout.

Пример вывода:

{
  "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 – Просмотр журнала операций виртуальной машины

Просмотр журнала операций, связанных с указанной виртуальной машиной (включение/выключение, снимки, редактирование, импорт/экспорт и т. д.).

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

--limit задаёт число возвращаемых записей, по умолчанию 50
--desc сортировка по времени в обратном порядке (включена по умолчанию)
Каждая запись журнала содержит время, уровень, категорию, пользователя операции и описание события; описание события представляет собой полный текст
Описание события (event) локализуется службой VMs в соответствии с системным языком устройства; в примерах этого документа единообразно используется английский язык

Пример вывода:

[
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:44:09.176535374+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) shutdown successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:43:10.597187659+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) started successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:40:32.74904922+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) shutdown successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:39:55.916718004+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) started successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:39:43.341421576+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) shutdown successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:38:31.518259486+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) shutdown successfully"
  },
  {
    "id": 0,
    "level": "Info",
    "time": "2026-09-02T11:38:07.98065689+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine(win10) started successfully"
  },
  {
    "id": 0,
    "level": "Error",
    "time": "2026-09-02T11:32:35.01952111+08:00",
    "category": "vm",
    "user": "system",
    "event": "Virtual machine (win10) export failed (Error:stat : no such file or directory)"
  }
]

II. Управление питанием виртуальных машин

vms vm poweron – Запуск виртуальной машины

vms vm poweron <id>

Виртуальная машина должна быть выключена, иначе возвращается ошибка конфликта состояния
Вывод: VM powered on: <id>

vms vm poweroff – Выключение виртуальной машины

Отправляет виртуальной машине запрос штатного завершения работы для корректного выключения системы.

vms vm poweroff <id> [--yes]

Относится к опасным операциям: в интерактивном режиме запрашивается подтверждение, в неинтерактивном режиме обязательно указывать --yes
Виртуальная машина должна быть запущена, иначе возвращается ошибка конфликта состояния

Запрос подтверждения в интерактивном режиме:

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

Вывод: VM powered off: <id>

vms vm force-poweroff – Принудительное выключение виртуальной машины (высокий риск)

Принудительно выключает виртуальную машину, что равносильно прямому отключению питания.

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

Относится к операциям высокого риска: в интерактивном режиме запрашивается подтверждение, в неинтерактивном режиме обязательно указывать --yes
Может привести к потере данных внутри виртуальной машины; рекомендуется использовать только при отсутствии отклика виртуальной машины

Запрос подтверждения в интерактивном режиме:

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

Вывод: VM force powered off: <id>

vms vm reboot – Перезапуск виртуальной машины

vms vm reboot <id>

Вывод: VM rebooted: <id>

vms vm pause – Приостановка виртуальной машины

Замораживает состояние работы виртуальной машины и сохраняет текущее состояние на диск.

vms vm pause <id>

Виртуальная машина должна быть запущена, иначе возвращается ошибка конфликта состояния
После приостановки состояние виртуальной машины отображается как saved
Вывод: VM paused: <id>

vms vm resume – Возобновление виртуальной машины

Возобновляет работу виртуальной машины из приостановленного состояния.

vms vm resume <id>

Виртуальная машина должна быть приостановлена, иначе возвращается ошибка конфликта состояния
Вывод: VM resumed: <id>

vms vm autorun – Настройка автоматического запуска при загрузке

Настраивает автоматический запуск виртуальной машины при загрузке хоста.

vms vm autorun <id> <true|false>

Второй параметр должен быть true или false
Команда считывает текущую конфигурацию и изменяет только переключатель автозапуска, остальные параметры не затрагиваются
Вывод: Auto-start enabled for VM <id> или Auto-start disabled for VM <id>

III. Копирование, экспорт и удаление виртуальных машин

vms vm clone – Клонирование виртуальной машины

Создаёт новую виртуальную машину путём копирования существующей в качестве шаблона.

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

В теле запроса guest_id — ID исходной виртуальной машины, name (или guest_name) — имя новой виртуальной машины
Исходная виртуальная машина должна быть выключена
--body передаёт тело запроса напрямую в виде строки JSON, --file считывает тело запроса из файла

vms vm export – Экспорт виртуальной машины

Экспортирует виртуальную машину в файл OVA для резервного копирования или переноса на другие платформы виртуализации.

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

В теле запроса guest_id — ID исходной виртуальной машины, target_ova_path — путь к целевому файлу, ova_mode — необязательный режим совместимости с VMware
Исходная виртуальная машина должна быть выключена
Экспорт — длительная задача; экспорт виртуальных машин большого объёма занимает много времени

vms vm delete – Удаление виртуальной машины (высокий риск)

Безвозвратно удаляет виртуальную машину.

vms vm delete <id> [--yes]

Относится к операциям высокого риска: в интерактивном режиме запрашивается подтверждение, в неинтерактивном режиме обязательно указывать --yes
Восстановление после удаления невозможно; заранее убедитесь, что данные внутри виртуальной машины сохранены в резервной копии

Запрос подтверждения в интерактивном режиме:

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

Вывод: VM deleted: <id>

IV. Виртуальные диски

vms vm disk list – Просмотр виртуальных дисков

Выводит список всех виртуальных дисков указанной виртуальной машины.

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

Пример вывода:

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

VDISK MODE — номер типа контроллера виртуального диска, 1 обозначает IDE
Виртуальные диски без имени отображаются в столбце NAME как -

V. Управление снимками

vms vm snapshot list – Список снимков

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

Пример вывода:

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 — состояние работы виртуальной машины на момент создания снимка
ACTUAL CONSISTENCY — тип согласованности снимка, filesystem означает согласованность файловой системы, crash — согласованность при сбое

vms vm snapshot create – Создание снимка

Создаёт снимок виртуальной машины для быстрого отката или резервного копирования текущего состояния.

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

Тело запроса необязательно: description — описание снимка, locked — блокировка или нет
Имя снимка автоматически генерируется системой по времени создания
Снимки занимают место в хранилище; при длительном отсутствии очистки хранилище может заполниться, рекомендуется регулярно проводить очистку

vms vm snapshot edit – Редактирование снимка

Изменяет описание или состояние блокировки снимка.

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

Изменяются только поля, присутствующие в теле запроса; отсутствующие поля сохраняют исходные значения; изменение только описания не меняет состояние блокировки, и наоборот

Пример вывода:

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 – Просмотр конфигурации виртуальной машины из снимка

Просмотр конфигурации виртуальной машины, сохранённой в снимке.

vms vm snapshot config <id> <snapshot_name>

<id> — ID виртуальной машины, <snapshot_name> — имя снимка, которое можно получить с помощью vms vm snapshot list <id>.

Пример вывода:

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 – Предварительный просмотр согласованности снимка

Позволяет перед созданием снимка увидеть возможный тип согласованности и оценить, подходит ли текущий момент для создания снимка.

vms vm snapshot consistency <id>

Пример вывода:

PROPERTY          VALUE
CONSISTENCY TYPE  filesystem
REASON            vm_shutdown
VM STATE          shutdown

При выключенной виртуальной машине можно получить снимок, согласованный с файловой системой; в рабочем состоянии обычно удаётся получить только снимок, согласованный при сбое.

VI. Удалённая консоль

vms vm link – Получение информации о подключении к VNC

Получает информацию о подключении к консоли VNC виртуальной машины для открытия удалённой консоли в браузере.

vms vm link <id> --json

Виртуальная машина должна быть запущена или приостановлена, иначе возвращается ошибка конфликта состояния

Пример вывода:

{
  "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 — путь к консоли относительно адреса управления NAS, port — порт службы консоли, https указывает, требуется ли доступ через HTTPS
В выводе JSON символ & в URL экранируется как \u0026

VII. Управление виртуальными сетями

Типы сетей делятся на два вида:

Тип	Описание
Частная (private)	Внутренняя сеть только для связи между виртуальными машинами на локальной машине, не привязана к физической сетевой карте
Внешняя (external)	Сеть, привязанная к физической сетевой карте; виртуальные машины могут через неё взаимодействовать с внешним миром

vms network list – Список виртуальных сетей

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

Пример вывода:

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 — число виртуальных машин, подключённых к этой сети, NUM INTERFACES — число выбранных физических сетевых карт

vms network get – Просмотр подробностей виртуальной сети

vms network get <network_id> --json

Пример вывода:

{
  "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 — информация о сетевых картах, привязанных к этой сети, сгруппированная по ID хоста; checked указывает, выбрана ли эта сетевая карта
metadata фиксирует время создания и обновления сети

vms network create – Создание виртуальной сети

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

Создание частной сети:

Тело запроса должно содержать name, type (private), host_name или host_id, указывающие, на каком хосте создаётся сеть
Перед созданием можно просмотреть доступные хосты с помощью vms network list-interfaces private

Создание внешней сети:

Тело запроса должно содержать name, type (external), vlan_id и указывать как минимум одну физическую сетевую карту
Сетевую карту можно указать через interface_name (например, LAN 1) или interface_id; если имя сетевой карты не уникально между хостами, его нужно использовать вместе с host_name
Перед созданием можно просмотреть доступные сетевые карты с помощью vms network list-interfaces external

Вывод представляет собой информацию о созданной сети и совпадает по структуре с 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
}

Если сетевая карта не указана, команда выводит подсказку:

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 – Обновление виртуальной сети

Передаются только изменяемые поля, не переданные поля сохраняют исходные значения.

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

Тело запроса должно содержать network_id
Команда сначала считывает текущую конфигурацию сети и объединяет её с переданными полями; имя сети и выбранные сетевые карты не очищаются
Вывод — обновлённая информация о сети

vms network delete – Удаление виртуальной сети (высокий риск)

vms network delete <network_id> [--yes]

Относится к операциям высокого риска: в интерактивном режиме запрашивается подтверждение, в неинтерактивном режиме обязательно указывать --yes
Удаление сети отключает все виртуальные машины, подключённые к этой сети
Рекомендуется сначала проверить подключённые виртуальные машины с помощью vms network list-vnics <network_id>

Запрос подтверждения в интерактивном режиме:

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

Вывод: Network deleted: <network_id>

vms network list-interfaces – Список сетевых интерфейсов

Выводит список сетевых интерфейсов указанного типа.

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

external возвращает доступные физические сетевые карты на хосте
private возвращает информацию о хостах, доступных для создания частной сети

Пример вывода (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

Пример вывода (private):

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

vms network list-vnics – Список виртуальных сетевых карт в сети

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

Пример вывода:

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 – Просмотр состояния OVS

Проверяет, включён ли виртуальный коммутатор Open vSwitch.

vms network ovsinfo [--json]

Пример вывода:

PROPERTY  VALUE
RESULT    true

Значение VALUE равное true означает, что OVS включён.

VIII. Управление образами

vms image list – Список образов

Выводит список файлов системных образов, доступных для создания виртуальных машин.

vms image list --json

image_name — имя образа, file_name — соответствующее имя файла
type — формат образа, например iso, qcow2
status — состояние образа, available означает доступен
repos — хранилище, в котором находится этот образ
progress — прогресс задачи обработки образа, 0 означает отсутствие активных задач

Пример вывода:

{
  "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 – Редактирование образа

Изменяет имя образа или настраивает хранилище, в котором находится образ.

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

Тело запроса должно содержать image_id и repos; repos — полный список целевых хранилищ для этого образа, он не может быть пустым
image_name, file_name, type, file_size — необязательные поля; при отсутствии используются текущие значения
Пустой repos приведёт к удалению образа из всех хранилищ, поэтому команда отклоняет такой запрос до выполнения
Вывод: Image updated

vms image delete – Удаление образа (высокий риск)

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

--image-id — обязательный параметр
Относится к операциям высокого риска: в интерактивном режиме запрашивается подтверждение, в неинтерактивном режиме обязательно указывать --yes
Удаление образа не влияет на уже созданные виртуальные машины, но влияет на последующее создание виртуальных машин на основе этого образа
Рекомендуется сначала проверить использование с помощью vms image list-vms --image-id <image_id>

Запрос подтверждения в интерактивном режиме:

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

Вывод: Image deleted: <image_id>

vms image list-vms – Просмотр виртуальных машин, использующих этот образ

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

Пример вывода:

GUEST NAME
1454486

Перед удалением образа можно сначала выполнить эту команду, чтобы оценить область влияния; если ни одна виртуальная машина не использует этот образ, вывод пуст.

IX. Управление хранилищами

vms repo list – Список хранилищ

vms repo list [--json]

Пример вывода:

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 – Просмотр подробностей хранилища

vms repo get <repo_id> [--json]

Пример вывода:

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 — том, на котором находится хранилище
SOFT LIMIT, HARD LIMIT — пороги предупреждения о ёмкости (в процентах)
ENABLE LOWER NOTIFY — включено ли уведомление о недостатке ёмкости

vms repo update – Обновление хранилища

Передаются только изменяемые поля, не переданные поля сохраняют исходные значения.

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

ID хранилища можно передать через repo_id или repoId
Команда сначала считывает текущую конфигурацию и объединяет её с переданными полями, остальные настройки не теряются
Вывод — обновлённая информация о хранилище

vms repo delete – Удаление хранилища (высокий риск)

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

Второй параметр — need_save_data: true означает сохранить файлы данных на диске, false — удалить вместе с данными
Относится к операциям высокого риска: в интерактивном режиме запрашивается подтверждение, в неинтерактивном режиме обязательно указывать --yes
Удаление хранилища одновременно удаляет находящиеся в нём виртуальные машины и образы; рекомендуется сначала выполнить vms repo check-running и vms repo whether-exist-data, чтобы оценить область влияния

Запрос подтверждения в интерактивном режиме:

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

Вывод: Repository deleted: <repo_id>

vms repo list-volumes – Список доступных томов

Выводит список томов, доступных для создания хранилищ.

vms repo list-volumes [--json]

Пример вывода:

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 – Список виртуальных машин в хранилище

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

ID хранилища можно передать через repo_id или repoId
Команда сначала получает объект хранилища, а затем запрашивает его виртуальные машины, что даёт более надёжный результат

vms repo check-running – Проверка работающих виртуальных машин в хранилище

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

Выполняется перед удалением хранилища, чтобы убедиться, что ни одна виртуальная машина не работает; при отсутствии работающих виртуальных машин вывод пуст.

vms repo whether-exist-data – Проверка наличия данных в хранилище

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

Выполняется перед удалением хранилища, чтобы убедиться, есть ли в нём данные; совпадает с предварительной проверкой перед удалением хранилища в веб-интерфейсе.

X. Глобальные настройки

vms setting get – Просмотр глобальных настроек

Просмотр глобальной конфигурации приложения VMs.

vms setting get [--json]

Пример вывода:

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

HOST SHUTDOWN BEHAVIOR — способ обработки виртуальных машин при выключении хоста
KB LAYOUT — раскладка клавиатуры виртуальной машины

XI. Запросы информации мониторинга

vms collectd hostinfo – Просмотр информации о мониторинге хоста

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

Пример вывода:

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

vms collectd vminfo – Просмотр информации о мониторинге виртуальных машин

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

Пример вывода:

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 – Просмотр информации о мониторинге хранилища

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

Пример вывода:

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

Интерактивный и неинтерактивный режимы

CLI определяет, запущен ли он в среде терминала, и ведёт себя по-разному:

Интерактивный режим (среда терминала)

Для опасных операций отображается запрос подтверждения, вариант по умолчанию — No
Введите y или Y для продолжения, n или пустой Enter для отмены
При отмене операции выводится Operation cancelled, код выхода — 99

Неинтерактивный режим (скрипты/автоматизация)

Для опасных операций необходимо использовать --yes для пропуска подтверждения, иначе команда сразу завершается ошибкой с кодом выхода 1
При отсутствии среды терминала ввод не ожидается, что подходит для вызова из скриптов и заданий по расписанию
Рекомендуется явно обрабатывать коды выхода в скриптах, чтобы различать успех, ошибку и конфликт состояния

Формат вывода JSON

Команды запросов поддерживают параметр --json, выводящий нормализованные данные JSON для удобства программного разбора.

Соглашения о формате:

Имена полей используют snake_case
Логические значения — true/false
Время используется в формате ISO 8601 с точностью до наносекунд и смещением UTC+8 (например, 2026-09-02T11:43:51.176535374+08:00)
JSON выводится в stdout, сообщения об ошибках — в stderr
Длинные поля, усечённые в табличном выводе, в выводе JSON представлены полностью

Пример:

vms setting get --json

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

Структура JSON у разных команд немного различается: vms vm list, vms vm snapshot list, vms vm logs выводят массив напрямую; остальные списочные команды выводят объект, содержащий totalCount и поля данных, имена которых зависят от ресурса (например, items, hosts, vms, storage). Например, 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"
    }
  }
}

У некоторых команд вывод JSON представляет собой простое значение: например, vms network ovsinfo --json выводит true, а vms vm pause --json выводит null.

Описание кодов выхода

Код выхода	Значение	Типичный сценарий
0	Успех	Команда успешно завершена
1	Ошибка параметров	Отсутствует обязательный параметр, неверный формат параметра, не указан `--yes`
3	Ресурс не существует	Предварительная проверка команды не пройдена, например указанный образ не существует
4	Конфликт состояния	Текущее состояние виртуальной машины не допускает эту операцию (например, выключение уже выключенной виртуальной машины)
6	Ошибка подключения	Не удаётся подключиться к службе VMs или неверен путь к socket
7	Тайм-аут	Тайм-аут запроса, можно настроить с помощью `--timeout`
9	Ошибка выполнения	Бэкенд вернул ошибку (сообщение об ошибке содержит code_num и описание ошибки)
99	Отмена пользователем	При интерактивном подтверждении выбран No или нажат пустой Enter

Пример:

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

Примеры сценариев использования

Ежедневное обслуживание

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

Пакетные операции в скриптах

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

Резервное копирование и инспекция

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

Проверки перед удалением

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

Вызов из инструментов AI

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

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

Внутренняя разработка и системная интеграция

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

Часто задаваемые вопросы

Q: Нужно ли дополнительно устанавливать CLI?

Нет. CLI устанавливается вместе с приложением VMs; после включения приложения достаточно выполнить команду vms.

Q: Обязательно ли использовать CLI через SSH?

Нет. CLI можно вызывать из любого терминала командной строки, включая локальный терминал, удалённый SSH, скрипты, инструменты AI и т. д.

Q: Может ли CLI управлять виртуальными машинами на других устройствах?

Нет. CLI взаимодействует со службой VMs через локальный unix socket и предназначен только для управления локальными виртуальными машинами.

Q: Почему одни команды запрашивают подтверждение, а другие нет?

Операции удаления виртуальной машины, удаления сети, удаления образа, удаления хранилища, а также выключения (poweroff, force-poweroff) влияют на данные или службы, поэтому по умолчанию требуют подтверждения; команды запуска, перезапуска, приостановки, возобновления и запросов таких ограничений не имеют.

Q: Как подтвердить опасные операции в неинтерактивном режиме?

Для всех опасных операций необходимо добавлять параметр --yes, иначе команда завершится ошибкой (код выхода 1).

Q: Как в скрипте определить, успешно ли выполнена команда?

По коду выхода: 0 означает успех, не 0 — ошибку. Также можно разбирать содержимое вывода --json.

Q: Почему список в выводе --json представляет собой объект?

В выводе JSON некоторых команд список организован в объект по ID с полем totalCount, что позволяет напрямую обращаться по ID.

Дополнительная справка

Каждая команда поддерживает --help для просмотра подробного использования:

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

Введение​

Основные особенности​

Быстрый старт​

Глобальные параметры​

Пример информации о версии​

Среда выполнения​

Сводная таблица команд​

Справочник команд​

I. Запросы виртуальных машин​

vms vm list – Список виртуальных машин​

vms vm get – Просмотр подробностей виртуальной машины​

vms vm list-resource – Список ресурсов, доступных для создания виртуальной машины​

vms vm logs – Просмотр журнала операций виртуальной машины​

II. Управление питанием виртуальных машин​

vms vm poweron – Запуск виртуальной машины​

vms vm poweroff – Выключение виртуальной машины​

vms vm force-poweroff – Принудительное выключение виртуальной машины (высокий риск)​

vms vm reboot – Перезапуск виртуальной машины​

vms vm pause – Приостановка виртуальной машины​

vms vm resume – Возобновление виртуальной машины​

vms vm autorun – Настройка автоматического запуска при загрузке​

III. Копирование, экспорт и удаление виртуальных машин​

vms vm clone – Клонирование виртуальной машины​

vms vm export – Экспорт виртуальной машины​

vms vm delete – Удаление виртуальной машины (высокий риск)​

IV. Виртуальные диски​

vms vm disk list – Просмотр виртуальных дисков​

V. Управление снимками​

vms vm snapshot list – Список снимков​

vms vm snapshot create – Создание снимка​

vms vm snapshot edit – Редактирование снимка​

vms vm snapshot config – Просмотр конфигурации виртуальной машины из снимка​

vms vm snapshot consistency – Предварительный просмотр согласованности снимка​

VI. Удалённая консоль​

vms vm link – Получение информации о подключении к VNC​

VII. Управление виртуальными сетями​

vms network list – Список виртуальных сетей​

vms network get – Просмотр подробностей виртуальной сети​

vms network create – Создание виртуальной сети​

vms network update – Обновление виртуальной сети​

vms network delete – Удаление виртуальной сети (высокий риск)​

vms network list-interfaces – Список сетевых интерфейсов​

vms network list-vnics – Список виртуальных сетевых карт в сети​

vms network ovsinfo – Просмотр состояния OVS​

VIII. Управление образами​

vms image list – Список образов​

vms image edit – Редактирование образа​

vms image delete – Удаление образа (высокий риск)​

vms image list-vms – Просмотр виртуальных машин, использующих этот образ​

IX. Управление хранилищами​

vms repo list – Список хранилищ​

vms repo get – Просмотр подробностей хранилища​

vms repo update – Обновление хранилища​

vms repo delete – Удаление хранилища (высокий риск)​

vms repo list-volumes – Список доступных томов​

vms repo list-vms – Список виртуальных машин в хранилище​

vms repo check-running – Проверка работающих виртуальных машин в хранилище​

vms repo whether-exist-data – Проверка наличия данных в хранилище​

X. Глобальные настройки​

vms setting get – Просмотр глобальных настроек​

XI. Запросы информации мониторинга​

vms collectd hostinfo – Просмотр информации о мониторинге хоста​

vms collectd vminfo – Просмотр информации о мониторинге виртуальных машин​

vms collectd storageinfo – Просмотр информации о мониторинге хранилища​

Интерактивный и неинтерактивный режимы​

Интерактивный режим (среда терминала)​

Неинтерактивный режим (скрипты/автоматизация)​

Формат вывода JSON​

Описание кодов выхода​

Примеры сценариев использования​

Ежедневное обслуживание​

Пакетные операции в скриптах​

Резервное копирование и инспекция​

Проверки перед удалением​

Вызов из инструментов AI​

Внутренняя разработка и системная интеграция​

Часто задаваемые вопросы​

Дополнительная справка​

Введение

Основные особенности

Быстрый старт

Глобальные параметры

Пример информации о версии

Среда выполнения

Сводная таблица команд

Справочник команд

I. Запросы виртуальных машин

vms vm list – Список виртуальных машин

vms vm get – Просмотр подробностей виртуальной машины

vms vm list-resource – Список ресурсов, доступных для создания виртуальной машины

vms vm logs – Просмотр журнала операций виртуальной машины

II. Управление питанием виртуальных машин

vms vm poweron – Запуск виртуальной машины

vms vm poweroff – Выключение виртуальной машины

vms vm force-poweroff – Принудительное выключение виртуальной машины (высокий риск)

vms vm reboot – Перезапуск виртуальной машины

vms vm pause – Приостановка виртуальной машины

vms vm resume – Возобновление виртуальной машины

vms vm autorun – Настройка автоматического запуска при загрузке

III. Копирование, экспорт и удаление виртуальных машин

vms vm clone – Клонирование виртуальной машины

vms vm export – Экспорт виртуальной машины

vms vm delete – Удаление виртуальной машины (высокий риск)

IV. Виртуальные диски

vms vm disk list – Просмотр виртуальных дисков

V. Управление снимками

vms vm snapshot list – Список снимков

vms vm snapshot create – Создание снимка

vms vm snapshot edit – Редактирование снимка

vms vm snapshot config – Просмотр конфигурации виртуальной машины из снимка

vms vm snapshot consistency – Предварительный просмотр согласованности снимка

VI. Удалённая консоль

vms vm link – Получение информации о подключении к VNC

VII. Управление виртуальными сетями

vms network list – Список виртуальных сетей

vms network get – Просмотр подробностей виртуальной сети

vms network create – Создание виртуальной сети

vms network update – Обновление виртуальной сети

vms network delete – Удаление виртуальной сети (высокий риск)

vms network list-interfaces – Список сетевых интерфейсов

vms network list-vnics – Список виртуальных сетевых карт в сети

vms network ovsinfo – Просмотр состояния OVS

VIII. Управление образами

vms image list – Список образов

vms image edit – Редактирование образа

vms image delete – Удаление образа (высокий риск)

vms image list-vms – Просмотр виртуальных машин, использующих этот образ

IX. Управление хранилищами

vms repo list – Список хранилищ

vms repo get – Просмотр подробностей хранилища

vms repo update – Обновление хранилища

vms repo delete – Удаление хранилища (высокий риск)

vms repo list-volumes – Список доступных томов

vms repo list-vms – Список виртуальных машин в хранилище

vms repo check-running – Проверка работающих виртуальных машин в хранилище

vms repo whether-exist-data – Проверка наличия данных в хранилище

X. Глобальные настройки

vms setting get – Просмотр глобальных настроек

XI. Запросы информации мониторинга

vms collectd hostinfo – Просмотр информации о мониторинге хоста

vms collectd vminfo – Просмотр информации о мониторинге виртуальных машин

vms collectd storageinfo – Просмотр информации о мониторинге хранилища

Интерактивный и неинтерактивный режимы

Интерактивный режим (среда терминала)

Неинтерактивный режим (скрипты/автоматизация)

Формат вывода JSON

Описание кодов выхода

Примеры сценариев использования

Ежедневное обслуживание

Пакетные операции в скриптах

Резервное копирование и инспекция

Проверки перед удалением

Вызов из инструментов AI

Внутренняя разработка и системная интеграция

Часто задаваемые вопросы

Дополнительная справка