Version: TOS 7

VMs CLI

Úvod

VMs CLI je nástroj pro správu virtualizační aplikace TerraMaster VMs z příkazového řádku, který poskytuje možnosti dotazování a provozu odpovídající webovému rozhraní pro správu. CLI komunikuje se službou VMs prostřednictvím místního unix socketu, používá standardizované rozhraní příkazů a formát výstupu JSON, takže jej lze integrovat do skriptů, automatizovaného provozu a pracovních postupů sekundárního vývoje.

Hlavní vlastnosti

Připraveno k použití: instaluje se spolu s aplikací VMs, nevyžaduje další instalaci
Flexibilní způsoby volání: podporuje místní terminál, vzdálený SSH, skripty, nástroje AI a další způsoby volání
Dva režimy — interaktivní a neinteraktivní: vhodné jak pro běžnou údržbu administrátorem, tak pro skripty a automatizované úlohy
Podpora výstupu JSON: usnadňuje programové zpracování a automatizovanou integraci
Místní komunikace: spojení se službou VMs pouze prostřednictvím místního unix socketu, porty se neotevírají navenek
Opětovné potvrzení nebezpečných operací: operace odstranění virtuálního počítače, odstranění sítě a další ve výchozím nastavení vyžadují potvrzení

Rychlý start

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

# 查看虚拟机列表
vms vm list

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

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

vms vm list — příklad výstupu:

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    -

Globální volby

Následující volby platí pro všechny příkazy:

Volba	Zkratka	Popis
`--help`	`-h`	Zobrazí nápovědu k příkazu
`--version`	`-v`	Zobrazí číslo verze (lze použít s `--json` pro strukturovaný výstup)
`--json`	-	Výstup ve formátu JSON
`--yes`	`-y`	Přeskočí výzvu k potvrzení nebezpečných operací (povinné v neinteraktivním režimu)
`--debug`	-	Zapne ladicí výstup se zobrazením podrobného průběhu provádění
`--socket <path>`	-	Cesta k unix socketu VMs, výchozí `/var/api/VMs.sock`
`--timeout <duration>`	-	Časový limit požadavku, výchozí 30s

Příklad informací o verzi

vms --version

vms CLI v1.0.058

vms --version --json

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

Prostředí běhu

VMs CLI se instaluje spolu s aplikací VMs. Při zapnutí aplikace se CLI odkáže do systémového adresáře PATH, takže po přihlášení přes SSH jej lze používat přímo.

Položka	Popis
Soubor CLI	`/Volume1/@apps/VMs/bin/vms`
Cesta příkazu	`/usr/local/sbin/vms` (již v systémovém PATH)
Způsob komunikace	Místní unix socket, výchozí `/var/api/VMs.sock`
Pro koho	Administrátor přihlášený na místním počítači

Poznámky:

CLI slouží ke správě místních virtuálních počítačů; vzdálená správa jiných zařízení prostřednictvím CLI není podporována.
Backend vždy vrací HTTP 200; o úspěchu příkazu rozhoduje pole code v těle odpovědi, podle kterého CLI vytváří návratový kód.
Nebezpečné operace (odstranění virtuálního počítače, odstranění sítě, odstranění obrazu, odstranění úložiště) v interaktivním režimu žádají o potvrzení, v neinteraktivním režimu vyžadují výslovné zadání --yes.

Souhrnná tabulka příkazů

Níže je stručný přehled všech příkazů vms:

Nadřazený příkaz	Podpříkaz	Popis funkce	Vyžaduje potvrzení	Vysoké riziko
vms	--version	Zobrazí informace o verzi	Ne	Ne
vms vm	list	Vypíše všechny virtuální počítače	Ne	Ne
vms vm	get	Zobrazí podrobnosti zadaného virtuálního počítače	Ne	Ne
vms vm	list-resource	Vypíše zdroje dostupné pro vytvoření virtuálního počítače	Ne	Ne
vms vm	logs	Zobrazí protokol operací virtuálního počítače	Ne	Ne
vms vm	poweron	Spustí virtuální počítač	Ne	Ne
vms vm	poweroff	Vypne virtuální počítač (běžné vypnutí)	Ano	Ne
vms vm	force-poweroff	Vynutí vypnutí virtuálního počítače	Ano	✅
vms vm	reboot	Restartuje virtuální počítač	Ne	Ne
vms vm	pause	Pozastaví virtuální počítač	Ne	Ne
vms vm	resume	Obnoví pozastavený virtuální počítač	Ne	Ne
vms vm	autorun	Nastaví automatické spuštění při startu	Ne	Ne
vms vm	clone	Klonuje virtuální počítač	Ne	Ne
vms vm	export	Exportuje virtuální počítač do souboru OVA	Ne	Ne
vms vm	delete	Odstraní virtuální počítač	Ano	✅
vms vm disk	list	Zobrazí virtuální disky virtuálního počítače	Ne	Ne
vms vm snapshot	list	Vypíše snímky virtuálního počítače	Ne	Ne
vms vm snapshot	create	Vytvoří snímek	Ne	Ne
vms vm snapshot	edit	Upraví popis a stav uzamčení snímku	Ne	Ne
vms vm snapshot	config	Zobrazí konfiguraci virtuálního počítače uloženou ve snímku	Ne	Ne
vms vm snapshot	consistency	Zobrazí náhled konzistence snímku	Ne	Ne
vms vm	link	Získá informace o připojení ke konzoli VNC	Ne	Ne
vms network	list	Vypíše virtuální sítě	Ne	Ne
vms network	get	Zobrazí podrobnosti virtuální sítě	Ne	Ne
vms network	create	Vytvoří virtuální síť	Ne	Ne
vms network	update	Aktualizuje virtuální síť	Ne	Ne
vms network	delete	Odstraní virtuální síť	Ano	✅
vms network	list-interfaces	Vypíše síťová rozhraní zadaného typu	Ne	Ne
vms network	list-vnics	Vypíše virtuální síťové karty v síti	Ne	Ne
vms network	ovsinfo	Zobrazí, zda je OVS zapnutý	Ne	Ne
vms image	list	Vypíše obrazy	Ne	Ne
vms image	edit	Upraví informace o obrazu	Ne	Ne
vms image	delete	Odstraní obraz	Ano	✅
vms image	list-vms	Zobrazí virtuální počítače používající tento obraz	Ne	Ne
vms repo	list	Vypíše úložiště	Ne	Ne
vms repo	get	Zobrazí podrobnosti úložiště	Ne	Ne
vms repo	update	Aktualizuje konfiguraci úložiště	Ne	Ne
vms repo	delete	Odstraní úložiště	Ano	✅
vms repo	list-volumes	Vypíše dostupné svazky	Ne	Ne
vms repo	list-vms	Vypíše virtuální počítače v úložišti	Ne	Ne
vms repo	check-running	Zkontroluje běžící virtuální počítače v úložišti	Ne	Ne
vms repo	whether-exist-data	Zkontroluje, zda v úložišti existují data	Ne	Ne
vms setting	get	Zobrazí globální nastavení	Ne	Ne
vms collectd	hostinfo	Zobrazí informace o monitorování hostitele	Ne	Ne
vms collectd	vminfo	Zobrazí informace o monitorování virtuálních počítačů	Ne	Ne
vms collectd	storageinfo	Zobrazí informace o monitorování úložiště	Ne	Ne

Referenční příručka příkazů

V příkazech <id> označuje ID virtuálního počítače, které odpovídá GUEST ID ve výstupu seznamu virtuálních počítačů; <network_id>, <image_id>, <repo_id> obdobně lze získat pomocí vms network list, vms image list, vms repo list.

O příkladech výstupu: tabulkový výstup vms zkracuje příliš dlouhé hodnoty polí na pevnou šířku (s ukončením třemi tečkami a nezávisle na šířce terminálu), například VDISKS, VNICS, ISO IMAGES v konfiguraci virtuálního počítače a názvy obrazů. Proto jsou v tomto dokumentu u příkazů s dlouhými poli jednotně uvedeny úplné příklady výstupu --json a u ostatních příkazů příklady tabulkového výstupu. Při zpracování skripty se rovněž doporučuje jednotně používat --json.

I. Dotazování na virtuální počítače

vms vm list – Výpis virtuálních počítačů

Vypíše všechny virtuální počítače na místním počítači a jejich základní stavy.

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

--limit, --offset jsou parametry stránkování
Sloupce výstupu: název, ID virtuálního počítače, stav běhu, počet jader CPU, velikost paměti (v KB), adresa IP

Příklad výstupu:

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    -

Časté hodnoty STATUS:

Stav	Popis
running	Běží
shutdown	Vypnuto
saved	Pozastaveno (stav běhu uložen na disk)

vms vm get – Zobrazení podrobností virtuálního počítače

Zobrazí úplnou konfiguraci a stav běhu zadaného virtuálního počítače.

vms vm get <id> --json

Výstup obsahuje všechna pole konfigurace a stavu běhu virtuálního počítače
Prázdné hodnoty, například chybějící popis nebo IP, se zobrazují jako prázdný řetězec
Pokud virtuální počítač neexistuje, příkaz vrátí chybu a vypíše chybovou zprávu

Příklad výstupu:

{
  "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 – Výpis zdrojů dostupných pro vytvoření virtuálního počítače

Zobrazí zdroje, které může hostitel poskytnout: typy firmwaru, obrazy, CPU, paměť, sítě, úložiště, zařízení pro průchod atd., pro posouzení před vytvořením virtuálního počítače.

vms vm list-resource --json

Vracená pole: max_cpu_num, max_ram_size, usbs, pci_devices, networks, repos, images, video_cards, firmware, keyboard_layout.

Příklad výstupu:

{
  "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 – Zobrazení protokolu operací virtuálního počítače

Zobrazí protokol operací souvisejících se zadaným virtuálním počítačem (zapnutí/vypnutí, snímky, úpravy, import/export atd.).

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

--limit určuje počet vrácených záznamů, výchozí 50
--desc řazení podle času v opačném pořadí (ve výchozím nastavení zapnuto)
Každý záznam protokolu obsahuje čas, úroveň, kategorii, uživatele operace a popis události; popis události je úplný text
Popis události (event) je lokalizován službou VMs podle systémového jazyka zařízení; v příkladech tohoto dokumentu je jednotně použita angličtina

Příklad výstupu:

[
  {
    "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. Správa napájení virtuálních počítačů

vms vm poweron – Spuštění virtuálního počítače

vms vm poweron <id>

Virtuální počítač musí být vypnutý, jinak je vrácena chyba konfliktu stavu
Výstup: VM powered on: <id>

vms vm poweroff – Vypnutí virtuálního počítače

Odešle virtuálnímu počítači požadavek na běžné vypnutí, aby se systém řádně ukončil.

vms vm poweroff <id> [--yes]

Jde o nebezpečnou operaci: v interaktivním režimu žádá o potvrzení, v neinteraktivním režimu vyžaduje zadání --yes
Virtuální počítač musí běžet, jinak je vrácena chyba konfliktu stavu

Výzva k potvrzení v interaktivním režimu:

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

Výstup: VM powered off: <id>

vms vm force-poweroff – Vynucené vypnutí virtuálního počítače (vysoké riziko)

Vynutí vypnutí virtuálního počítače, což odpovídá přímému odpojení napájení.

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

Jde o operaci s vysokým rizikem: v interaktivním režimu žádá o potvrzení, v neinteraktivním režimu vyžaduje zadání --yes
Může způsobit ztrátu dat ve virtuálním počítači; doporučuje se použít pouze tehdy, když virtuální počítač nereaguje

Výzva k potvrzení v interaktivním režimu:

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

Výstup: VM force powered off: <id>

vms vm reboot – Restart virtuálního počítače

vms vm reboot <id>

Výstup: VM rebooted: <id>

vms vm pause – Pozastavení virtuálního počítače

Zmrazí stav běhu virtuálního počítače a uloží aktuální stav na disk.

vms vm pause <id>

Virtuální počítač musí běžet, jinak je vrácena chyba konfliktu stavu
Po pozastavení se stav virtuálního počítače zobrazuje jako saved
Výstup: VM paused: <id>

vms vm resume – Obnovení virtuálního počítače

Obnoví virtuální počítač z pozastaveného stavu do stavu běhu.

vms vm resume <id>

Virtuální počítač musí být pozastaven, jinak je vrácena chyba konfliktu stavu
Výstup: VM resumed: <id>

vms vm autorun – Nastavení automatického spuštění při startu

Nastaví, zda se má virtuální počítač automaticky spustit při startu hostitele.

vms vm autorun <id> <true|false>

Druhý parametr musí být true nebo false
Příkaz načte aktuální konfiguraci a upraví pouze přepínač automatického spuštění, ostatní nastavení zůstávají nezměněna
Výstup: Auto-start enabled for VM <id> nebo Auto-start disabled for VM <id>

III. Kopírování, export a odstranění virtuálních počítačů

vms vm clone – Klonování virtuálního počítače

Vytvoří nový virtuální počítač zkopírováním stávajícího jako šablony.

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

V těle požadavku guest_id označuje ID zdrojového virtuálního počítače, name (nebo guest_name) název nového virtuálního počítače
Zdrojový virtuální počítač musí být vypnutý
--body předává tělo požadavku přímo jako řetězec JSON, --file načítá tělo požadavku ze souboru

vms vm export – Export virtuálního počítače

Exportuje virtuální počítač do souboru OVA, což usnadňuje zálohování nebo migraci na jiné virtualizační platformy.

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

V těle požadavku guest_id označuje ID zdrojového virtuálního počítače, target_ova_path cestu k cílovému souboru, ova_mode volitelný režim kompatibility s VMware
Zdrojový virtuální počítač musí být vypnutý
Export je časově náročná úloha; export virtuálních počítačů s velkou kapacitou trvá dlouho

vms vm delete – Odstranění virtuálního počítače (vysoké riziko)

Trvale odstraní virtuální počítač.

vms vm delete <id> [--yes]

Jde o operaci s vysokým rizikem: v interaktivním režimu žádá o potvrzení, v neinteraktivním režimu vyžaduje zadání --yes
Po odstranění není obnovení možné; předem se ujistěte, že data ve virtuálním počítači jsou zálohována

Výzva k potvrzení v interaktivním režimu:

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

Výstup: VM deleted: <id>

IV. Virtuální disky

vms vm disk list – Zobrazení virtuálních disků

Vypíše všechny virtuální disky zadaného virtuálního počítače.

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

Příklad výstupu:

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

VDISK MODE je číslo typu řadiče virtuálního disku, 1 označuje IDE
Nepojmenované virtuální disky se ve sloupci NAME zobrazují jako -

V. Správa snímků

vms vm snapshot list – Výpis snímků

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

Příklad výstupu:

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 je stav běhu virtuálního počítače v okamžiku vytvoření snímku
ACTUAL CONSISTENCY je typ konzistence snímku, filesystem znamená konzistenci souborového systému, crash konzistenci při havárii

vms vm snapshot create – Vytvoření snímku

Vytvoří snímek virtuálního počítače pro rychlé vrácení nebo zálohu aktuálního stavu.

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

Tělo požadavku je volitelné: description je popis snímku, locked určuje, zda je uzamčen
Název snímku systém generuje automaticky podle času vytvoření
Snímky zabírají místo v úložišti; při dlouhodobém nečištění mohou úložiště zaplnit, doporučuje se pravidelně provádět úklid

vms vm snapshot edit – Úprava snímku

Změní popis nebo stav uzamčení snímku.

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

Upravují se pouze pole uvedená v těle požadavku, neuvedená pole zachovávají původní hodnoty; změna pouze popisu nezmění stav uzamčení a naopak

Příklad výstupu:

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 – Zobrazení konfigurace virtuálního počítače ze snímku

Zobrazí konfiguraci virtuálního počítače uloženou ve snímku.

vms vm snapshot config <id> <snapshot_name>

<id> je ID virtuálního počítače, <snapshot_name> je název snímku, který lze získat pomocí vms vm snapshot list <id>.

Příklad výstupu:

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 – Náhled konzistence snímku

Umožňuje před vytvořením snímku zobrazit možný typ konzistence a posoudit, zda je aktuální okamžik vhodný pro vytvoření snímku.

vms vm snapshot consistency <id>

Příklad výstupu:

PROPERTY          VALUE
CONSISTENCY TYPE  filesystem
REASON            vm_shutdown
VM STATE          shutdown

Při vypnutém virtuálním počítači lze získat snímek konzistentní se souborovým systémem; ve stavu běhu lze obvykle získat pouze snímek konzistentní při havárii.

VI. Vzdálená konzole

vms vm link – Získání informací o připojení k VNC

Získá informace o připojení ke konzoli VNC virtuálního počítače, které slouží k otevření vzdálené konzole v prohlížeči.

vms vm link <id> --json

Virtuální počítač musí běžet nebo být pozastaven, jinak je vrácena chyba konfliktu stavu

Příklad výstupu:

{
  "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 je cesta ke konzoli relativně k adrese správy NAS, port je port služby konzole, https určuje, zda je vyžadován přístup přes HTTPS
Ve výstupu JSON se znak & v adrese URL escapuje jako \u0026

VII. Správa virtuálních sítí

Typy sítí se dělí na dva druhy:

Typ	Popis
Privátní (private)	Interní síť pouze pro komunikaci mezi virtuálními počítači na místním počítači, nepřipojená k fyzické síťové kartě
Externí (external)	Síť připojená k fyzické síťové kartě; virtuální počítače přes ni mohou komunikovat s vnějškem

vms network list – Výpis virtuálních sítí

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

Příklad výstupu:

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 je počet virtuálních počítačů připojených k této síti, NUM INTERFACES je počet vybraných fyzických síťových karet

vms network get – Zobrazení podrobností virtuální sítě

vms network get <network_id> --json

Příklad výstupu:

{
  "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 jsou informace o síťových kartách připojených k této síti, uspořádané podle ID hostitele; checked určuje, zda je daná síťová karta vybrána
metadata zaznamenává čas vytvoření a aktualizace sítě

vms network create – Vytvoření virtuální sítě

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

Vytvoření privátní sítě:

Tělo požadavku musí obsahovat name, type (private), host_name nebo host_id, které určují, na kterém hostiteli se síť vytváří
Před vytvořením lze zobrazit dostupné hostitele pomocí vms network list-interfaces private

Vytvoření externí sítě:

Tělo požadavku musí obsahovat name, type (external), vlan_id a musí určovat alespoň jednu fyzickou síťovou kartu
Síťovou kartu lze určit pomocí interface_name (např. LAN 1) nebo interface_id; pokud název síťové karty není mezi hostiteli jedinečný, je třeba jej použít spolu s host_name
Před vytvořením lze zobrazit dostupné síťové karty pomocí vms network list-interfaces external

Výstupem jsou informace o vytvořené síti a strukturálně odpovídá 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
}

Pokud není určena síťová karta, příkaz zobrazí nápovědu:

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 – Aktualizace virtuální sítě

Předávají se pouze pole určená ke změně, nepředaná pole zachovávají původní hodnoty.

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

Tělo požadavku musí obsahovat network_id
Příkaz nejprve načte aktuální konfiguraci sítě a sloučí ji s předanými poli; název sítě a vybrané síťové karty se nevymažou
Výstupem jsou aktualizované informace o síti

vms network delete – Odstranění virtuální sítě (vysoké riziko)

vms network delete <network_id> [--yes]

Jde o operaci s vysokým rizikem: v interaktivním režimu žádá o potvrzení, v neinteraktivním režimu vyžaduje zadání --yes
Odstranění sítě odpojí všechny virtuální počítače připojené k této síti
Doporučuje se nejprve zkontrolovat připojené virtuální počítače pomocí vms network list-vnics <network_id>

Výzva k potvrzení v interaktivním režimu:

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

Výstup: Network deleted: <network_id>

vms network list-interfaces – Výpis síťových rozhraní

Vypíše síťová rozhraní zadaného typu.

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

external vrací dostupné fyzické síťové karty na hostiteli
private vrací informace o hostitelích dostupných pro vytvoření privátní sítě

Příklad výstupu (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

Příklad výstupu (private):

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

vms network list-vnics – Výpis virtuálních síťových karet v síti

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

Příklad výstupu:

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 – Zobrazení stavu OVS

Zkontroluje, zda je virtuální přepínač Open vSwitch zapnutý.

vms network ovsinfo [--json]

Příklad výstupu:

PROPERTY  VALUE
RESULT    true

Hodnota VALUE rovna true znamená, že OVS je zapnutý.

VIII. Správa obrazů

vms image list – Výpis obrazů

Vypíše soubory systémových obrazů dostupné pro vytváření virtuálních počítačů.

vms image list --json

image_name je název obrazu, file_name je odpovídající název souboru
type je formát obrazu, např. iso, qcow2
status je stav obrazu, available znamená dostupný
repos je úložiště, ve kterém se obraz nachází
progress je průběh úlohy zpracování obrazu, 0 znamená žádné probíhající úlohy

Příklad výstupu:

{
  "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 – Úprava obrazu

Změní název obrazu nebo upraví úložiště, ve kterém se obraz nachází.

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

Tělo požadavku musí obsahovat image_id a repos; repos je úplný seznam cílových úložišť tohoto obrazu, nesmí být prázdný
image_name, file_name, type, file_size jsou volitelná pole; pokud nejsou uvedena, použijí se aktuální hodnoty
Prázdné repos by způsobilo odstranění obrazu ze všech úložišť, proto příkaz takový požadavek před provedením odmítne
Výstup: Image updated

vms image delete – Odstranění obrazu (vysoké riziko)

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

--image-id je povinný parametr
Jde o operaci s vysokým rizikem: v interaktivním režimu žádá o potvrzení, v neinteraktivním režimu vyžaduje zadání --yes
Odstranění obrazu neovlivní již vytvořené virtuální počítače, ale ovlivní následné vytváření virtuálních počítačů na základě tohoto obrazu
Doporučuje se nejprve zkontrolovat využití pomocí vms image list-vms --image-id <image_id>

Výzva k potvrzení v interaktivním režimu:

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

Výstup: Image deleted: <image_id>

vms image list-vms – Zobrazení virtuálních počítačů používajících tento obraz

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

Příklad výstupu:

GUEST NAME
1454486

Před odstraněním obrazu lze nejprve spustit tento příkaz a posoudit rozsah dopadu; pokud obraz nepoužívá žádný virtuální počítač, je výstup prázdný.

IX. Správa úložišť

vms repo list – Výpis úložišť

vms repo list [--json]

Příklad výstupu:

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 – Zobrazení podrobností úložiště

vms repo get <repo_id> [--json]

Příklad výstupu:

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 je svazek, na kterém se úložiště nachází
SOFT LIMIT, HARD LIMIT jsou prahy upozornění na kapacitu (v procentech)
ENABLE LOWER NOTIFY určuje, zda je zapnuto upozornění na nedostatek kapacity

vms repo update – Aktualizace úložiště

Předávají se pouze pole určená ke změně, nepředaná pole zachovávají původní hodnoty.

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

ID úložiště lze předat pomocí repo_id nebo repoId
Příkaz nejprve načte aktuální konfiguraci a sloučí ji s předanými poli, ostatní nastavení se neztratí
Výstupem jsou aktualizované informace o úložišti

vms repo delete – Odstranění úložiště (vysoké riziko)

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

Druhý parametr je need_save_data: true znamená zachovat datové soubory na disku, false znamená odstranit i s daty
Jde o operaci s vysokým rizikem: v interaktivním režimu žádá o potvrzení, v neinteraktivním režimu vyžaduje zadání --yes
Odstranění úložiště zároveň odstraní virtuální počítače a obrazy v něm; doporučuje se nejprve spustit vms repo check-running a vms repo whether-exist-data a posoudit rozsah dopadu

Výzva k potvrzení v interaktivním režimu:

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

Výstup: Repository deleted: <repo_id>

vms repo list-volumes – Výpis dostupných svazků

Vypíše svazky dostupné pro vytváření úložišť.

vms repo list-volumes [--json]

Příklad výstupu:

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 – Výpis virtuálních počítačů v úložišti

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

ID úložiště lze předat pomocí repo_id nebo repoId
Příkaz nejprve získá objekt úložiště a poté dotáže jeho virtuální počítače, což dává spolehlivější výsledek

vms repo check-running – Kontrola běžících virtuálních počítačů v úložišti

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

Provádí se před odstraněním úložiště, aby se ověřilo, že neběží žádný virtuální počítač; pokud žádný virtuální počítač neběží, je výstup prázdný.

vms repo whether-exist-data – Kontrola, zda v úložišti existují data

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

Provádí se před odstraněním úložiště, aby se ověřilo, zda v úložišti ještě jsou data; odpovídá předběžné kontrole před odstraněním úložiště ve webovém rozhraní.

X. Globální nastavení

vms setting get – Zobrazení globálních nastavení

Zobrazí globální konfiguraci aplikace VMs.

vms setting get [--json]

Příklad výstupu:

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

HOST SHUTDOWN BEHAVIOR je způsob zpracování virtuálních počítačů při vypnutí hostitele
KB LAYOUT je rozložení klávesnice virtuálního počítače

XI. Dotazování na informace o monitorování

vms collectd hostinfo – Zobrazení informací o monitorování hostitele

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

Příklad výstupu:

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

vms collectd vminfo – Zobrazení informací o monitorování virtuálních počítačů

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

Příklad výstupu:

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 – Zobrazení informací o monitorování úložiště

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

Příklad výstupu:

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

Interaktivní a neinteraktivní režim

CLI určuje, zda běží v prostředí terminálu, a chová se odlišně:

Interaktivní režim (prostředí terminálu)

U nebezpečných operací se zobrazuje výzva k potvrzení, výchozí volba je No
Pro pokračování zadejte y nebo Y, pro zrušení zadejte n nebo stiskněte Enter
Při zrušení operace se zobrazí Operation cancelled, návratový kód je 99

Neinteraktivní režim (skripty/automatizace)

U nebezpečných operací je nutné použít --yes pro přeskočení potvrzení, jinak příkaz rovnou ohlásí chybu a vrátí návratový kód 1
V prostředí bez terminálu se nečeká na vstup, což je vhodné pro volání ze skriptů a plánovaných úloh
Doporučuje se ve skriptech explicitně ošetřovat návratové kódy, aby se rozlišil úspěch, selhání a konflikt stavu

Formát výstupu JSON

Dotazovací příkazy podporují parametr --json, který vypisuje normalizovaná data JSON usnadňující programové zpracování.

Konvence formátu:

Názvy polí používají snake_case
Logické hodnoty jsou true/false
Čas je uváděn ve formátu ISO 8601 s přesností na nanosekundy a posunem UTC+8 (např. 2026-09-02T11:43:51.176535374+08:00)
JSON se vypisuje na stdout, chybové zprávy na stderr
Dlouhá pole zkrácená v tabulkovém výstupu mají ve výstupu JSON úplnou hodnotu

Příklad:

vms setting get --json

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

Struktura JSON se u různých příkazů mírně liší: vms vm list, vms vm snapshot list, vms vm logs vypisují pole přímo; ostatní seznamové příkazy vypisují objekt obsahující totalCount a datová pole, jejichž názvy se liší podle zdroje (např. items, hosts, vms, storage). Například 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"
    }
  }
}

Výstup JSON některých příkazů je jednoduchá hodnota: například vms network ovsinfo --json vypisuje true a vms vm pause --json vypisuje null.

Popis návratových kódů

Návratový kód	Význam	Typický scénář
0	Úspěch	Příkaz úspěšně dokončen
1	Chyba parametru	Chybí povinný parametr, nesprávný formát parametru, chybí `--yes`
3	Zdroj neexistuje	Předběžná validace příkazu neproběhla, například zadaný obraz neexistuje
4	Konflikt stavu	Aktuální stav virtuálního počítače tuto operaci neumožňuje (např. vypnutí již vypnutého virtuálního počítače)
6	Chyba připojení	Nelze se připojit ke službě VMs nebo je nesprávná cesta k socketu
7	Časový limit	Vypršel časový limit požadavku, lze upravit pomocí `--timeout`
9	Chyba provádění	Backend vrátil chybu (chybová zpráva obsahuje code_num a popis chyby)
99	Zrušení uživatelem	Při interaktivním potvrzení byla zvolena volba No nebo stisknut Enter

Příklad:

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

Příklady scénářů použití

Běžný provoz

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

Dávkové operace ve skriptech

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

Zálohování a inspekce

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

Kontroly před odstraněním

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

Volání z nástrojů AI

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

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

Interní vývoj a systémová integrace

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

Časté dotazy

Q: Je nutná dodatečná instalace CLI?

Ne. CLI se instaluje spolu s aplikací VMs; po zapnutí aplikace stačí spustit příkaz vms.

Q: Musí se CLI používat přes SSH?

Ne. CLI lze volat z libovolného terminálu příkazového řádku, včetně místního terminálu, vzdáleného SSH, skriptů, nástrojů AI atd.

Q: Může CLI spravovat virtuální počítače na jiných zařízeních?

Ne. CLI komunikuje se službou VMs prostřednictvím místního unix socketu a slouží výhradně ke správě místních virtuálních počítačů.

Q: Proč některé příkazy žádají o potvrzení a jiné ne?

Operace odstranění virtuálního počítače, odstranění sítě, odstranění obrazu, odstranění úložiště a vypnutí (poweroff, force-poweroff) ovlivňují data nebo služby, proto ve výchozím nastavení vyžadují potvrzení; příkazy spuštění, restartu, pozastavení, obnovení a dotazování taková omezení nemají.

Q: Jak potvrzovat nebezpečné operace v neinteraktivním režimu?

U všech nebezpečných operací je nutné přidat parametr --yes, jinak příkaz skončí chybou (návratový kód 1).

Q: Jak ve skriptu zjistit, zda příkaz proběhl úspěšně?

Podle návratového kódu: 0 znamená úspěch, nenulová hodnota znamená selhání. Lze také zpracovat obsah výstupu --json.

Q: Proč je seznam ve výstupu --json objekt?

Ve výstupu JSON některých příkazů je seznam uspořádán do objektu podle ID s polem totalCount, což usnadňuje přímé načtení podle ID.

Další nápověda

Každý příkaz podporuje --help pro zobrazení podrobného použití:

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

Úvod​

Hlavní vlastnosti​

Rychlý start​

Globální volby​

Příklad informací o verzi​

Prostředí běhu​

Souhrnná tabulka příkazů​

Referenční příručka příkazů​

I. Dotazování na virtuální počítače​

vms vm list – Výpis virtuálních počítačů​

vms vm get – Zobrazení podrobností virtuálního počítače​

vms vm list-resource – Výpis zdrojů dostupných pro vytvoření virtuálního počítače​

vms vm logs – Zobrazení protokolu operací virtuálního počítače​

II. Správa napájení virtuálních počítačů​

vms vm poweron – Spuštění virtuálního počítače​

vms vm poweroff – Vypnutí virtuálního počítače​

vms vm force-poweroff – Vynucené vypnutí virtuálního počítače (vysoké riziko)​

vms vm reboot – Restart virtuálního počítače​

vms vm pause – Pozastavení virtuálního počítače​

vms vm resume – Obnovení virtuálního počítače​

vms vm autorun – Nastavení automatického spuštění při startu​

III. Kopírování, export a odstranění virtuálních počítačů​

vms vm clone – Klonování virtuálního počítače​

vms vm export – Export virtuálního počítače​

vms vm delete – Odstranění virtuálního počítače (vysoké riziko)​

IV. Virtuální disky​

vms vm disk list – Zobrazení virtuálních disků​

V. Správa snímků​

vms vm snapshot list – Výpis snímků​

vms vm snapshot create – Vytvoření snímku​

vms vm snapshot edit – Úprava snímku​

vms vm snapshot config – Zobrazení konfigurace virtuálního počítače ze snímku​

vms vm snapshot consistency – Náhled konzistence snímku​

VI. Vzdálená konzole​

vms vm link – Získání informací o připojení k VNC​

VII. Správa virtuálních sítí​

vms network list – Výpis virtuálních sítí​

vms network get – Zobrazení podrobností virtuální sítě​

vms network create – Vytvoření virtuální sítě​

vms network update – Aktualizace virtuální sítě​

vms network delete – Odstranění virtuální sítě (vysoké riziko)​

vms network list-interfaces – Výpis síťových rozhraní​

vms network list-vnics – Výpis virtuálních síťových karet v síti​

vms network ovsinfo – Zobrazení stavu OVS​

VIII. Správa obrazů​

vms image list – Výpis obrazů​

vms image edit – Úprava obrazu​

vms image delete – Odstranění obrazu (vysoké riziko)​

vms image list-vms – Zobrazení virtuálních počítačů používajících tento obraz​

IX. Správa úložišť​

vms repo list – Výpis úložišť​

vms repo get – Zobrazení podrobností úložiště​

vms repo update – Aktualizace úložiště​

vms repo delete – Odstranění úložiště (vysoké riziko)​

vms repo list-volumes – Výpis dostupných svazků​

vms repo list-vms – Výpis virtuálních počítačů v úložišti​

vms repo check-running – Kontrola běžících virtuálních počítačů v úložišti​

vms repo whether-exist-data – Kontrola, zda v úložišti existují data​

X. Globální nastavení​

vms setting get – Zobrazení globálních nastavení​

XI. Dotazování na informace o monitorování​

vms collectd hostinfo – Zobrazení informací o monitorování hostitele​

vms collectd vminfo – Zobrazení informací o monitorování virtuálních počítačů​

vms collectd storageinfo – Zobrazení informací o monitorování úložiště​

Interaktivní a neinteraktivní režim​

Interaktivní režim (prostředí terminálu)​

Neinteraktivní režim (skripty/automatizace)​

Formát výstupu JSON​

Popis návratových kódů​

Příklady scénářů použití​

Běžný provoz​

Dávkové operace ve skriptech​

Zálohování a inspekce​

Kontroly před odstraněním​

Volání z nástrojů AI​

Interní vývoj a systémová integrace​

Časté dotazy​

Další nápověda​

Úvod

Hlavní vlastnosti

Rychlý start

Globální volby

Příklad informací o verzi

Prostředí běhu

Souhrnná tabulka příkazů

Referenční příručka příkazů

I. Dotazování na virtuální počítače

vms vm list – Výpis virtuálních počítačů

vms vm get – Zobrazení podrobností virtuálního počítače

vms vm list-resource – Výpis zdrojů dostupných pro vytvoření virtuálního počítače

vms vm logs – Zobrazení protokolu operací virtuálního počítače

II. Správa napájení virtuálních počítačů

vms vm poweron – Spuštění virtuálního počítače

vms vm poweroff – Vypnutí virtuálního počítače

vms vm force-poweroff – Vynucené vypnutí virtuálního počítače (vysoké riziko)

vms vm reboot – Restart virtuálního počítače

vms vm pause – Pozastavení virtuálního počítače

vms vm resume – Obnovení virtuálního počítače

vms vm autorun – Nastavení automatického spuštění při startu

III. Kopírování, export a odstranění virtuálních počítačů

vms vm clone – Klonování virtuálního počítače

vms vm export – Export virtuálního počítače

vms vm delete – Odstranění virtuálního počítače (vysoké riziko)

IV. Virtuální disky

vms vm disk list – Zobrazení virtuálních disků

V. Správa snímků

vms vm snapshot list – Výpis snímků

vms vm snapshot create – Vytvoření snímku

vms vm snapshot edit – Úprava snímku

vms vm snapshot config – Zobrazení konfigurace virtuálního počítače ze snímku

vms vm snapshot consistency – Náhled konzistence snímku

VI. Vzdálená konzole

vms vm link – Získání informací o připojení k VNC

VII. Správa virtuálních sítí

vms network list – Výpis virtuálních sítí

vms network get – Zobrazení podrobností virtuální sítě

vms network create – Vytvoření virtuální sítě

vms network update – Aktualizace virtuální sítě

vms network delete – Odstranění virtuální sítě (vysoké riziko)

vms network list-interfaces – Výpis síťových rozhraní

vms network list-vnics – Výpis virtuálních síťových karet v síti

vms network ovsinfo – Zobrazení stavu OVS

VIII. Správa obrazů

vms image list – Výpis obrazů

vms image edit – Úprava obrazu

vms image delete – Odstranění obrazu (vysoké riziko)

vms image list-vms – Zobrazení virtuálních počítačů používajících tento obraz

IX. Správa úložišť

vms repo list – Výpis úložišť

vms repo get – Zobrazení podrobností úložiště

vms repo update – Aktualizace úložiště

vms repo delete – Odstranění úložiště (vysoké riziko)

vms repo list-volumes – Výpis dostupných svazků

vms repo list-vms – Výpis virtuálních počítačů v úložišti

vms repo check-running – Kontrola běžících virtuálních počítačů v úložišti

vms repo whether-exist-data – Kontrola, zda v úložišti existují data

X. Globální nastavení

vms setting get – Zobrazení globálních nastavení

XI. Dotazování na informace o monitorování

vms collectd hostinfo – Zobrazení informací o monitorování hostitele

vms collectd vminfo – Zobrazení informací o monitorování virtuálních počítačů

vms collectd storageinfo – Zobrazení informací o monitorování úložiště

Interaktivní a neinteraktivní režim

Interaktivní režim (prostředí terminálu)

Neinteraktivní režim (skripty/automatizace)

Formát výstupu JSON

Popis návratových kódů

Příklady scénářů použití

Běžný provoz

Dávkové operace ve skriptech

Zálohování a inspekce

Kontroly před odstraněním

Volání z nástrojů AI

Interní vývoj a systémová integrace

Časté dotazy

Další nápověda