Version: TOS 7

VMs CLI

Wprowadzenie

VMs CLI to narzędzie wiersza poleceń do zarządzania aplikacją wirtualizacyjną TerraMaster VMs, oferujące możliwości odpytywania i obsługi równoważne z interfejsem zarządzania WWW. CLI komunikuje się z usługą VMs przez lokalny unix socket, wykorzystuje standaryzowany interfejs poleceń i format wyjścia JSON, dzięki czemu można go zintegrować ze skryptami, zautomatyzowaną obsługą oraz procesami wtórnego rozwoju.

Najważniejsze cechy

Gotowe do użycia: instalowane wraz z aplikacją VMs, nie wymaga dodatkowej instalacji
Elastyczne wywołanie: obsługa terminala lokalnego, zdalnego SSH, skryptów, narzędzi AI i innych sposobów wywołania
Dwa tryby — interaktywny i nieinteraktywny: odpowiednie zarówno do codziennej konserwacji przez administratora, jak i do skryptów oraz zadań automatycznych
Obsługa wyjścia JSON: ułatwia analizę programową i integrację automatyzacji
Komunikacja lokalna: łączność z usługą VMs wyłącznie przez lokalny unix socket, porty nie są otwierane na zewnątrz
Ponowne potwierdzenie niebezpiecznych operacji: operacje usunięcia maszyny wirtualnej, usunięcia sieci itp. domyślnie wymagają potwierdzenia

Szybki start

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

# 查看虚拟机列表
vms vm list

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

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

vms vm list — przykładowe wyjście:

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    -

Opcje globalne

Następujące opcje dotyczą wszystkich poleceń:

Opcja	Skrót	Opis
`--help`	`-h`	Wyświetlenie informacji pomocy polecenia
`--version`	`-v`	Wyświetlenie numeru wersji (można połączyć z `--json` w celu uzyskania strukturalnego wyjścia)
`--json`	-	Wyjście w formacie JSON
`--yes`	`-y`	Pominięcie monitu potwierdzenia dla niebezpiecznych operacji (wymagane w trybie nieinteraktywnym)
`--debug`	-	Włączenie wyjścia debugowania ze szczegółowym przebiegiem wykonania
`--socket <path>`	-	Ścieżka do unix socket VMs, domyślnie `/var/api/VMs.sock`
`--timeout <duration>`	-	Limit czasu żądania, domyślnie 30s

Przykład informacji o wersji

vms --version

vms CLI v1.0.058

vms --version --json

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

Środowisko uruchomieniowe

VMs CLI jest instalowane wraz z aplikacją VMs. Po włączeniu aplikacji CLI jest podlinkowane do systemowego katalogu PATH, więc po zalogowaniu przez SSH można go używać bezpośrednio.

Pozycja	Opis
Plik CLI	`/Volume1/@apps/VMs/bin/vms`
Ścieżka polecenia	`/usr/local/sbin/vms` (już w systemowym PATH)
Sposób komunikacji	Lokalny unix socket, domyślnie `/var/api/VMs.sock`
Adresat	Administrator zalogowany na maszynie lokalnej

Uwagi:

CLI służy do zarządzania lokalnymi maszynami wirtualnymi; zdalne zarządzanie innymi urządzeniami przez CLI nie jest obsługiwane.
Backend zawsze zwraca HTTP 200; o powodzeniu polecenia decyduje pole code w treści odpowiedzi, na podstawie którego CLI tworzy kod wyjścia.
Niebezpieczne operacje (usunięcie maszyny wirtualnej, usunięcie sieci, usunięcie obrazu, usunięcie przestrzeni dyskowej) w trybie interaktywnym proszą o potwierdzenie, a w trybie nieinteraktywnym wymagają jawnego podania --yes.

Tabela zbiorcza poleceń

Poniżej znajduje się skrócony przegląd wszystkich poleceń vms:

Polecenie nadrzędne	Podpolecenie	Opis funkcji	Wymaga potwierdzenia	Wysokie ryzyko
vms	--version	Wyświetlenie informacji o wersji	Nie	Nie
vms vm	list	Lista wszystkich maszyn wirtualnych	Nie	Nie
vms vm	get	Podgląd szczegółów wskazanej maszyny wirtualnej	Nie	Nie
vms vm	list-resource	Lista zasobów dostępnych do tworzenia maszyny wirtualnej	Nie	Nie
vms vm	logs	Podgląd dziennika operacji maszyny wirtualnej	Nie	Nie
vms vm	poweron	Uruchomienie maszyny wirtualnej	Nie	Nie
vms vm	poweroff	Wyłączenie maszyny wirtualnej (normalne zamknięcie)	Tak	Nie
vms vm	force-poweroff	Wymuszone wyłączenie maszyny wirtualnej	Tak	✅
vms vm	reboot	Ponowne uruchomienie maszyny wirtualnej	Nie	Nie
vms vm	pause	Wstrzymanie maszyny wirtualnej	Nie	Nie
vms vm	resume	Wznowienie wstrzymanej maszyny wirtualnej	Nie	Nie
vms vm	autorun	Ustawienie automatycznego uruchamiania przy starcie	Nie	Nie
vms vm	clone	Klonowanie maszyny wirtualnej	Nie	Nie
vms vm	export	Eksport maszyny wirtualnej do pliku OVA	Nie	Nie
vms vm	delete	Usunięcie maszyny wirtualnej	Tak	✅
vms vm disk	list	Podgląd wirtualnych dysków maszyny wirtualnej	Nie	Nie
vms vm snapshot	list	Lista migawek maszyny wirtualnej	Nie	Nie
vms vm snapshot	create	Utworzenie migawki	Nie	Nie
vms vm snapshot	edit	Edycja opisu i stanu blokady migawki	Nie	Nie
vms vm snapshot	config	Podgląd konfiguracji maszyny wirtualnej zapisanej w migawce	Nie	Nie
vms vm snapshot	consistency	Podgląd spójności migawki	Nie	Nie
vms vm	link	Pobranie informacji o połączeniu z konsolą VNC	Nie	Nie
vms network	list	Lista sieci wirtualnych	Nie	Nie
vms network	get	Podgląd szczegółów sieci wirtualnej	Nie	Nie
vms network	create	Utworzenie sieci wirtualnej	Nie	Nie
vms network	update	Aktualizacja sieci wirtualnej	Nie	Nie
vms network	delete	Usunięcie sieci wirtualnej	Tak	✅
vms network	list-interfaces	Lista interfejsów sieciowych wskazanego typu	Nie	Nie
vms network	list-vnics	Lista wirtualnych kart sieciowych w sieci	Nie	Nie
vms network	ovsinfo	Podgląd, czy OVS jest włączony	Nie	Nie
vms image	list	Lista obrazów	Nie	Nie
vms image	edit	Edycja informacji o obrazie	Nie	Nie
vms image	delete	Usunięcie obrazu	Tak	✅
vms image	list-vms	Podgląd maszyn wirtualnych korzystających z tego obrazu	Nie	Nie
vms repo	list	Lista przestrzeni dyskowych	Nie	Nie
vms repo	get	Podgląd szczegółów przestrzeni dyskowej	Nie	Nie
vms repo	update	Aktualizacja konfiguracji przestrzeni dyskowej	Nie	Nie
vms repo	delete	Usunięcie przestrzeni dyskowej	Tak	✅
vms repo	list-volumes	Lista dostępnych wolumenów	Nie	Nie
vms repo	list-vms	Lista maszyn wirtualnych w przestrzeni dyskowej	Nie	Nie
vms repo	check-running	Sprawdzenie działających maszyn wirtualnych w przestrzeni dyskowej	Nie	Nie
vms repo	whether-exist-data	Sprawdzenie, czy w przestrzeni dyskowej istnieją dane	Nie	Nie
vms setting	get	Podgląd ustawień globalnych	Nie	Nie
vms collectd	hostinfo	Podgląd informacji o monitorowaniu hosta	Nie	Nie
vms collectd	vminfo	Podgląd informacji o monitorowaniu maszyn wirtualnych	Nie	Nie
vms collectd	storageinfo	Podgląd informacji o monitorowaniu przestrzeni dyskowej	Nie	Nie

Dokumentacja poleceń

W poleceniach <id> to identyfikator maszyny wirtualnej odpowiadający GUEST ID w wyjściu listy maszyn wirtualnych; <network_id>, <image_id>, <repo_id> analogicznie można uzyskać odpowiednio przez vms network list, vms image list, vms repo list.

O przykładach wyjścia: wyjście tabelaryczne vms dokonuje skrócenia zbyt długich wartości pól do stałej szerokości (kończące się wielokropkiem i niezależne od szerokości terminala), na przykład VDISKS, VNICS, ISO IMAGES w konfiguracji maszyny wirtualnej oraz nazw obrazów. Dlatego w tym dokumencie dla poleceń z długimi polami podano jednolicie pełne przykłady wyjścia --json, a dla pozostałych poleceń przykłady wyjścia tabelarycznego. Przy przetwarzaniu skryptami zaleca się również jednolite używanie --json.

I. Odpytywanie maszyn wirtualnych

vms vm list – Lista maszyn wirtualnych

Wyświetla listę wszystkich maszyn wirtualnych na maszynie lokalnej i ich podstawowe stany.

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

--limit, --offset to parametry stronicowania
Kolumny wyjścia: nazwa, identyfikator maszyny wirtualnej, stan działania, liczba rdzeni CPU, rozmiar pamięci (w KB), adres IP

Przykładowe wyjście:

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    -

Częste wartości STATUS:

Stan	Opis
running	Działa
shutdown	Wyłączona
saved	Wstrzymana (stan działania zapisany na dysku)

vms vm get – Podgląd szczegółów maszyny wirtualnej

Podgląd pełnej konfiguracji i stanu działania wskazanej maszyny wirtualnej.

vms vm get <id> --json

Wyjście zawiera wszystkie pola konfiguracji i stanu działania maszyny wirtualnej
Puste wartości, np. brak opisu lub brak IP, są wyświetlane jako pusty ciąg
Gdy maszyna wirtualna nie istnieje, polecenie zwraca błąd i wyświetla komunikat o błędzie

Przykładowe wyjście:

{
  "iso_images": [
    "c93083a5-2b39-4f32-b19f-1ad97c6b4de4",
    "9b3f2fdd-9173-4611-a84c-0cc9ce88293c"
  ],
  "image_paths": [
    "",
    ""
  ],
  "autorun": 0,
  "boot_from": "cdrom",
  "bios": "bios",
  "kb_layout": "en-us",
  "serial_console": true,
  "usb_version": 2,
  "usb_device_name": [
    "USB - Integrated Technology Express, Inc. Disk 2.0"
  ],
  "usbs": [
    ":3:3:048d:1234"
  ],
  "use_ovmf": false,
  "vnics": [
    {
      "prefer_sriov": false,
      "vnic_type": 3,
      "mac": "1a:e2:ae:95:4a:51",
      "network_id": "b364a1ec-f60c-4971-9ea2-f7a002f09fa3",
      "virtual_interface_id": "fe972ef5-b066-4967-89fa-8e85e43c8808"
    }
  ],
  "operating_system_type": 0,
  "vdisks": [
    {
      "vdisk_mode": 1,
      "name": "",
      "unmap": false,
      "iops_enable": false,
      "dev_limit": 0,
      "dev_reservation": 0,
      "dev_weight": 3,
      "vdisk_size": 1024,
      "idx": 0,
      "vdisk_id": "f4ed4eae-1512-4273-963b-79ebd93a0932",
      "disk_image_type": "",
      "disk_image_id": ""
    }
  ],
  "name": "win10",
  "vcpu_num": 4,
  "vcpu_usage": 0,
  "vram_size": 2097152,
  "video_card": "vga",
  "machine_type": "1",
  "cpu_weight": 3,
  "ip": "",
  "desc": "",
  "cpu_passthru": false,
  "hyperv_enlighten": true,
  "cpu_pin_num": 0,
  "repo_id": "735ef7f7-5d8d-4102-9377-8a7b8c33cda6",
  "repo_name": "VM-Storage01",
  "poweron_after_create": false,
  "guest_id": "9c7078ab-a1e7-4bc0-819f-6ac83e24cfc1",
  "increaseAllocatedSize": 0,
  "host_id": "15341593-7f43-49f4-9523-6ac750a63a8a",
  "host_name": "",
  "snap_num": 0,
  "has_guest_agent": false,
  "status": "shutdown",
  "status_code": 0,
  "status_desc": "",
  "host_ram_size": 0,
  "total_throughput": 0,
  "total_iops": 0,
  "total_io_latency": 0,
  "total_rx_bytes": 0,
  "total_tx_bytes": 0,
  "memory_usage": 0,
  "cpu_usage": 0,
  "vm_status_progress": 0
}

vms vm list-resource – Lista zasobów dostępnych do tworzenia maszyny wirtualnej

Podgląd zasobów, które host może udostępnić: typów oprogramowania układowego, obrazów, CPU, pamięci, sieci, przestrzeni dyskowych, urządzeń do przekazania itp., w celu oceny przed utworzeniem maszyny wirtualnej.

vms vm list-resource --json

Zwracane pola: max_cpu_num, max_ram_size, usbs, pci_devices, networks, repos, images, video_cards, firmware, keyboard_layout.

Przykładowe wyjście:

{
  "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 – Podgląd dziennika operacji maszyny wirtualnej

Podgląd dziennika operacji związanych ze wskazaną maszyną wirtualną (włączanie/wyłączanie, migawki, edycja, import/eksport itp.).

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

--limit określa liczbę zwracanych wpisów, domyślnie 50
--desc sortowanie według czasu w kolejności odwrotnej (domyślnie włączone)
Każdy wpis dziennika zawiera czas, poziom, kategorię, użytkownika operacji i opis zdarzenia; opis zdarzenia to pełny tekst
Opis zdarzenia (event) jest lokalizowany przez usługę VMs zgodnie z językiem systemowym urządzenia; w przykładach tego dokumentu jednolicie użyto języka angielskiego

Przykładowe wyjście:

[
  {
    "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. Zarządzanie zasilaniem maszyn wirtualnych

vms vm poweron – Uruchomienie maszyny wirtualnej

vms vm poweron <id>

Maszyna wirtualna musi być wyłączona, w przeciwnym razie zwracany jest błąd konfliktu stanu
Wyjście: VM powered on: <id>

vms vm poweroff – Wyłączenie maszyny wirtualnej

Wysyła do maszyny wirtualnej żądanie normalnego zamknięcia, aby system zamknął się w sposób łagodny.

vms vm poweroff <id> [--yes]

Należy do niebezpiecznych operacji: w trybie interaktywnym prosi o potwierdzenie, w trybie nieinteraktywnym wymaga podania --yes
Maszyna wirtualna musi działać, w przeciwnym razie zwracany jest błąd konfliktu stanu

Monit potwierdzenia w trybie interaktywnym:

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

Wyjście: VM powered off: <id>

vms vm force-poweroff – Wymuszone wyłączenie maszyny wirtualnej (wysokie ryzyko)

Wymusza wyłączenie maszyny wirtualnej, co jest równoznaczne z bezpośrednim odcięciem zasilania.

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

Należy do operacji wysokiego ryzyka: w trybie interaktywnym prosi o potwierdzenie, w trybie nieinteraktywnym wymaga podania --yes
Może spowodować utratę danych w maszynie wirtualnej; zaleca się stosowanie tylko wtedy, gdy maszyna wirtualna nie odpowiada

Monit potwierdzenia w trybie interaktywnym:

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

Wyjście: VM force powered off: <id>

vms vm reboot – Ponowne uruchomienie maszyny wirtualnej

vms vm reboot <id>

Wyjście: VM rebooted: <id>

vms vm pause – Wstrzymanie maszyny wirtualnej

Zamraża stan działania maszyny wirtualnej i zapisuje bieżący stan na dysku.

vms vm pause <id>

Maszyna wirtualna musi działać, w przeciwnym razie zwracany jest błąd konfliktu stanu
Po wstrzymaniu stan maszyny wirtualnej jest wyświetlany jako saved
Wyjście: VM paused: <id>

vms vm resume – Wznowienie maszyny wirtualnej

Przywraca maszynę wirtualną ze stanu wstrzymania do stanu działania.

vms vm resume <id>

Maszyna wirtualna musi być wstrzymana, w przeciwnym razie zwracany jest błąd konfliktu stanu
Wyjście: VM resumed: <id>

vms vm autorun – Ustawienie automatycznego uruchamiania przy starcie

Ustawia, czy maszyna wirtualna ma się automatycznie uruchamiać wraz ze startem hosta.

vms vm autorun <id> <true|false>

Drugi parametr musi mieć wartość true lub false
Polecenie odczytuje bieżącą konfigurację i modyfikuje tylko przełącznik autostartu, pozostałe ustawienia nie są zmieniane
Wyjście: Auto-start enabled for VM <id> lub Auto-start disabled for VM <id>

III. Kopiowanie, eksport i usuwanie maszyn wirtualnych

vms vm clone – Klonowanie maszyny wirtualnej

Tworzy nową maszynę wirtualną, kopiując istniejącą jako szablon.

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

W treści żądania guest_id to identyfikator źródłowej maszyny wirtualnej, name (lub guest_name) to nazwa nowej maszyny wirtualnej
Źródłowa maszyna wirtualna musi być wyłączona
--body przekazuje treść żądania bezpośrednio jako ciąg JSON, --file odczytuje treść żądania z pliku

vms vm export – Eksport maszyny wirtualnej

Eksportuje maszynę wirtualną do pliku OVA, co ułatwia tworzenie kopii zapasowej lub migrację na inne platformy wirtualizacyjne.

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

W treści żądania guest_id to identyfikator źródłowej maszyny wirtualnej, target_ova_path to ścieżka pliku docelowego, ova_mode to opcjonalny tryb zgodności z VMware
Źródłowa maszyna wirtualna musi być wyłączona
Eksport jest zadaniem czasochłonnym; eksport maszyn wirtualnych o dużej pojemności trwa długo

vms vm delete – Usunięcie maszyny wirtualnej (wysokie ryzyko)

Trwale usuwa maszynę wirtualną.

vms vm delete <id> [--yes]

Należy do operacji wysokiego ryzyka: w trybie interaktywnym prosi o potwierdzenie, w trybie nieinteraktywnym wymaga podania --yes
Po usunięciu przywrócenie nie jest możliwe; wcześniej upewnij się, że dane w maszynie wirtualnej zostały zarchiwizowane

Monit potwierdzenia w trybie interaktywnym:

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

Wyjście: VM deleted: <id>

IV. Wirtualne dyski

vms vm disk list – Podgląd wirtualnych dysków

Wyświetla listę wszystkich wirtualnych dysków wskazanej maszyny wirtualnej.

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

Przykładowe wyjście:

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

VDISK MODE to numer typu kontrolera wirtualnego dysku, 1 oznacza IDE
Wirtualne dyski bez nazwy są wyświetlane w kolumnie NAME jako -

V. Zarządzanie migawkami

vms vm snapshot list – Lista migawek

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

Przykładowe wyjście:

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 to stan działania maszyny wirtualnej w momencie tworzenia migawki
ACTUAL CONSISTENCY to typ spójności migawki, filesystem oznacza spójność systemu plików, crash oznacza spójność po awarii

vms vm snapshot create – Utworzenie migawki

Tworzy migawkę maszyny wirtualnej do szybkiego przywrócenia lub archiwizacji bieżącego stanu.

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

Treść żądania jest opcjonalna: description to opis migawki, locked to informacja o zablokowaniu
Nazwa migawki jest generowana automatycznie przez system na podstawie czasu utworzenia
Migawki zajmują przestrzeń dyskową; przy długotrwałym braku czyszczenia mogą zapełnić przestrzeń dyskową, zaleca się regularne porządkowanie

vms vm snapshot edit – Edycja migawki

Zmienia opis lub stan blokady migawki.

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

Zmieniane są tylko pola występujące w treści żądania, pola nieobecne zachowują pierwotne wartości; zmiana samego opisu nie zmienia stanu blokady i odwrotnie

Przykładowe wyjście:

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 – Podgląd konfiguracji maszyny wirtualnej z migawki

Podgląd konfiguracji maszyny wirtualnej zapisanej w migawce.

vms vm snapshot config <id> <snapshot_name>

<id> to identyfikator maszyny wirtualnej, <snapshot_name> to nazwa migawki, którą można uzyskać przez vms vm snapshot list <id>.

Przykładowe wyjście:

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 – Podgląd spójności migawki

Pozwala przed utworzeniem migawki podejrzeć możliwy typ spójności i ocenić, czy bieżący moment nadaje się do utworzenia migawki.

vms vm snapshot consistency <id>

Przykładowe wyjście:

PROPERTY          VALUE
CONSISTENCY TYPE  filesystem
REASON            vm_shutdown
VM STATE          shutdown

Przy wyłączonej maszynie wirtualnej można uzyskać migawkę spójną z systemem plików; w stanie działania zwykle można uzyskać jedynie migawkę spójną po awarii.

VI. Konsola zdalna

vms vm link – Pobranie informacji o połączeniu z VNC

Pobiera informacje o połączeniu z konsolą VNC maszyny wirtualnej, służące do otwarcia konsoli zdalnej w przeglądarce.

vms vm link <id> --json

Maszyna wirtualna musi działać lub być wstrzymana, w przeciwnym razie zwracany jest błąd konfliktu stanu

Przykładowe wyjście:

{
  "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 to ścieżka konsoli względem adresu zarządzania NAS, port to port usługi konsoli, https wskazuje, czy wymagany jest dostęp przez HTTPS
W wyjściu JSON znak & w adresie URL jest zastępowany przez \u0026

VII. Zarządzanie sieciami wirtualnymi

Typy sieci dzielą się na dwa rodzaje:

Typ	Opis
Prywatna (private)	Sieć wewnętrzna tylko do komunikacji między maszynami wirtualnymi na maszynie lokalnej, niepowiązana z fizyczną kartą sieciową
Zewnętrzna (external)	Sieć powiązana z fizyczną kartą sieciową; maszyny wirtualne mogą przez nią komunikować się z zewnątrz

vms network list – Lista sieci wirtualnych

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

Przykładowe wyjście:

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 to liczba maszyn wirtualnych podłączonych do tej sieci, NUM INTERFACES to liczba wybranych fizycznych kart sieciowych

vms network get – Podgląd szczegółów sieci wirtualnej

vms network get <network_id> --json

Przykładowe wyjście:

{
  "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 to informacje o kartach sieciowych powiązanych z tą siecią, zorganizowane według identyfikatora hosta; checked wskazuje, czy dana karta sieciowa jest wybrana
metadata rejestruje czas utworzenia i aktualizacji sieci

vms network create – Utworzenie sieci wirtualnej

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

Tworzenie sieci prywatnej:

Treść żądania musi zawierać name, type (private), host_name lub host_id, wskazujące, na którym hoście tworzona jest sieć
Przed utworzeniem można wyświetlić dostępne hosty przez vms network list-interfaces private

Tworzenie sieci zewnętrznej:

Treść żądania musi zawierać name, type (external), vlan_id oraz wskazywać co najmniej jedną fizyczną kartę sieciową
Kartę sieciową można wskazać przez interface_name (np. LAN 1) lub interface_id; gdy nazwa karty sieciowej nie jest unikalna między hostami, należy użyć jej razem z host_name
Przed utworzeniem można wyświetlić dostępne karty sieciowe przez vms network list-interfaces external

Wyjście stanowi informacja o utworzonej sieci i jest zgodne strukturalnie z 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
}

Gdy karta sieciowa nie zostanie wskazana, polecenie wyświetla podpowiedź:

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 – Aktualizacja sieci wirtualnej

Przekazywane są tylko pola do zmiany, nieprzekazane pola zachowują pierwotne wartości.

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

Treść żądania musi zawierać network_id
Polecenie najpierw odczytuje bieżącą konfigurację sieci i scala ją z przekazanymi polami; nazwa sieci i wybrane karty sieciowe nie są czyszczone
Wyjście to zaktualizowana informacja o sieci

vms network delete – Usunięcie sieci wirtualnej (wysokie ryzyko)

vms network delete <network_id> [--yes]

Należy do operacji wysokiego ryzyka: w trybie interaktywnym prosi o potwierdzenie, w trybie nieinteraktywnym wymaga podania --yes
Usunięcie sieci rozłącza wszystkie maszyny wirtualne podłączone do tej sieci
Zaleca się najpierw sprawdzić podłączone maszyny wirtualne przez vms network list-vnics <network_id>

Monit potwierdzenia w trybie interaktywnym:

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

Wyjście: Network deleted: <network_id>

vms network list-interfaces – Lista interfejsów sieciowych

Wyświetla listę interfejsów sieciowych wskazanego typu.

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

external zwraca dostępne fizyczne karty sieciowe na hoście
private zwraca informacje o hostach dostępnych do utworzenia sieci prywatnej

Przykładowe wyjście (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

Przykładowe wyjście (private):

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

vms network list-vnics – Lista wirtualnych kart sieciowych w sieci

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

Przykładowe wyjście:

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 – Podgląd stanu OVS

Sprawdza, czy przełącznik wirtualny Open vSwitch jest włączony.

vms network ovsinfo [--json]

Przykładowe wyjście:

PROPERTY  VALUE
RESULT    true

Wartość VALUE równa true oznacza, że OVS jest włączony.

VIII. Zarządzanie obrazami

vms image list – Lista obrazów

Wyświetla listę plików obrazów systemowych dostępnych do tworzenia maszyn wirtualnych.

vms image list --json

image_name to nazwa obrazu, file_name to odpowiadająca jej nazwa pliku
type to format obrazu, np. iso, qcow2
status to stan obrazu, available oznacza dostępny
repos to przestrzeń dyskowa, w której znajduje się obraz
progress to postęp zadania przetwarzania obrazu, 0 oznacza brak zadań w toku

Przykładowe wyjście:

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

Zmienia nazwę obrazu lub dostosowuje przestrzeń dyskową, w której znajduje się obraz.

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

Treść żądania musi zawierać image_id i repos; repos to pełna lista docelowych przestrzeni dyskowych dla tego obrazu, nie może być pusta
image_name, file_name, type, file_size to pola opcjonalne; w razie braku używane są bieżące wartości
Pusty repos spowodowałby usunięcie obrazu ze wszystkich przestrzeni dyskowych, dlatego polecenie odrzuca takie żądanie przed wykonaniem
Wyjście: Image updated

vms image delete – Usunięcie obrazu (wysokie ryzyko)

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

--image-id jest parametrem wymaganym
Należy do operacji wysokiego ryzyka: w trybie interaktywnym prosi o potwierdzenie, w trybie nieinteraktywnym wymaga podania --yes
Usunięcie obrazu nie wpływa na już utworzone maszyny wirtualne, ale wpływa na późniejsze tworzenie maszyn wirtualnych na podstawie tego obrazu
Zaleca się najpierw sprawdzić użycie przez vms image list-vms --image-id <image_id>

Monit potwierdzenia w trybie interaktywnym:

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

Wyjście: Image deleted: <image_id>

vms image list-vms – Podgląd maszyn wirtualnych korzystających z tego obrazu

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

Przykładowe wyjście:

GUEST NAME
1454486

Przed usunięciem obrazu można najpierw wykonać to polecenie, aby ocenić zakres wpływu; gdy żadna maszyna wirtualna nie korzysta z tego obrazu, wyjście jest puste.

IX. Zarządzanie przestrzeniami dyskowymi

vms repo list – Lista przestrzeni dyskowych

vms repo list [--json]

Przykładowe wyjście:

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 – Podgląd szczegółów przestrzeni dyskowej

vms repo get <repo_id> [--json]

Przykładowe wyjście:

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 to wolumen, na którym znajduje się przestrzeń dyskowa
SOFT LIMIT, HARD LIMIT to progi ostrzeżenia o pojemności (w procentach)
ENABLE LOWER NOTIFY to informacja, czy włączone jest powiadomienie o niewystarczającej pojemności

vms repo update – Aktualizacja przestrzeni dyskowej

Przekazywane są tylko pola do zmiany, nieprzekazane pola zachowują pierwotne wartości.

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

Identyfikator przestrzeni dyskowej można przekazać przez repo_id lub repoId
Polecenie najpierw odczytuje bieżącą konfigurację i scala ją z przekazanymi polami, pozostałe ustawienia nie są tracone
Wyjście to zaktualizowana informacja o przestrzeni dyskowej

vms repo delete – Usunięcie przestrzeni dyskowej (wysokie ryzyko)

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

Drugi parametr to need_save_data: true oznacza zachowanie plików danych na dysku, false oznacza usunięcie wraz z danymi
Należy do operacji wysokiego ryzyka: w trybie interaktywnym prosi o potwierdzenie, w trybie nieinteraktywnym wymaga podania --yes
Usunięcie przestrzeni dyskowej jednocześnie usuwa znajdujące się w niej maszyny wirtualne i obrazy; zaleca się najpierw wykonać vms repo check-running i vms repo whether-exist-data, aby ocenić zakres wpływu

Monit potwierdzenia w trybie interaktywnym:

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

Wyjście: Repository deleted: <repo_id>

vms repo list-volumes – Lista dostępnych wolumenów

Wyświetla listę wolumenów dostępnych do tworzenia przestrzeni dyskowych.

vms repo list-volumes [--json]

Przykładowe wyjście:

NAME  UUID                                  DEVICE               FILESYSTEM  STATUS  VOLUME TYPE  TOTAL                            USED                           AVAILABLE                        USAGE
lv3   00000004-2608-1311-3025-6cbfb504eae4  /dev/mapper/vg0-lv3  ext4        -       -            {"unit":"KB","value":102626232}  {"unit":"KB","value":52}       {"unit":"KB","value":101561220}  0.000051200619070623694
lv2   00000003-2606-2215-3256-6cbfb504eae4  /dev/mapper/vg0-lv2  btrfs       -       -            {"unit":"KB","value":104857600}  {"unit":"KB","value":9715824}  {"unit":"KB","value":93096464}   9.450061066630479

vms repo list-vms – Lista maszyn wirtualnych w przestrzeni dyskowej

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

Identyfikator przestrzeni dyskowej można przekazać przez repo_id lub repoId
Polecenie najpierw pobiera obiekt przestrzeni dyskowej, a następnie odczytuje jej maszyny wirtualne, co daje bardziej niezawodny wynik

vms repo check-running – Sprawdzenie działających maszyn wirtualnych w przestrzeni dyskowej

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

Wykonywane przed usunięciem przestrzeni dyskowej, aby upewnić się, że żadna maszyna wirtualna nie działa; gdy nie ma działających maszyn wirtualnych, wyjście jest puste.

vms repo whether-exist-data – Sprawdzenie, czy w przestrzeni dyskowej istnieją dane

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

Wykonywane przed usunięciem przestrzeni dyskowej, aby upewnić się, czy w przestrzeni dyskowej są jeszcze dane; zgodne ze wstępną kontrolą przed usunięciem przestrzeni dyskowej w interfejsie WWW.

X. Ustawienia globalne

vms setting get – Podgląd ustawień globalnych

Podgląd globalnej konfiguracji aplikacji VMs.

vms setting get [--json]

Przykładowe wyjście:

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

HOST SHUTDOWN BEHAVIOR to sposób obsługi maszyn wirtualnych przy wyłączaniu hosta
KB LAYOUT to układ klawiatury maszyny wirtualnej

XI. Odpytywanie informacji o monitorowaniu

vms collectd hostinfo – Podgląd informacji o monitorowaniu hosta

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

Przykładowe wyjście:

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

vms collectd vminfo – Podgląd informacji o monitorowaniu maszyn wirtualnych

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

Przykładowe wyjście:

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 – Podgląd informacji o monitorowaniu przestrzeni dyskowej

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

Przykładowe wyjście:

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

Tryb interaktywny i nieinteraktywny

CLI ustala, czy działa w środowisku terminala, i stosuje odmienne zachowanie:

Tryb interaktywny (środowisko terminala)

Dla niebezpiecznych operacji wyświetlany jest monit potwierdzenia, domyślna opcja to No
Wpisz y lub Y, aby kontynuować, n lub naciśnij Enter, aby anulować
Przy anulowaniu operacji wyświetlane jest Operation cancelled, kod wyjścia to 99

Tryb nieinteraktywny (skrypty/automatyzacja)

Dla niebezpiecznych operacji należy użyć --yes, aby pominąć potwierdzenie, w przeciwnym razie polecenie zgłosi błąd i zwróci kod wyjścia 1
W środowisku bez terminala nie oczekuje się na wprowadzenie, co jest odpowiednie dla wywołań ze skryptów i zadań cyklicznych
Zaleca się jawne obsługiwanie kodów wyjścia w skryptach, aby rozróżnić powodzenie, błąd i konflikt stanu

Format wyjścia JSON

Polecenia odpytywania obsługują parametr --json, który wyświetla znormalizowane dane JSON ułatwiające analizę programową.

Konwencje formatu:

Nazwy pól używają snake_case
Wartości logiczne to true/false
Czas jest podawany w formacie ISO 8601 z dokładnością do nanosekund i przesunięciem UTC+8 (np. 2026-09-02T11:43:51.176535374+08:00)
JSON jest wyprowadzany do stdout, komunikaty o błędach do stderr
Długie pola obcięte w wyjściu tabelarycznym w wyjściu JSON są podane w pełnej wartości

Przykład:

vms setting get --json

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

Struktura JSON w różnych poleceniach nieco się różni: vms vm list, vms vm snapshot list, vms vm logs wyprowadzają tablicę bezpośrednio; pozostałe polecenia list wyprowadzają obiekt zawierający totalCount i pola danych, których nazwy zależą od zasobu (np. items, hosts, vms, storage). Na przykład 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"
    }
  }
}

Wyjście JSON niektórych poleceń to prosta wartość: na przykład vms network ovsinfo --json wyświetla true, a vms vm pause --json wyświetla null.

Opis kodów wyjścia

Kod wyjścia	Znaczenie	Typowy scenariusz
0	Powodzenie	Polecenie zakończone pomyślnie
1	Błąd parametru	Brak wymaganego parametru, nieprawidłowy format parametru, brak `--yes`
3	Zasób nie istnieje	Wstępna walidacja polecenia nie przeszła, np. wskazany obraz nie istnieje
4	Konflikt stanu	Bieżący stan maszyny wirtualnej nie pozwala na tę operację (np. wyłączenie już wyłączonej maszyny wirtualnej)
6	Błąd połączenia	Nie można połączyć się z usługą VMs lub nieprawidłowa ścieżka socket
7	Limit czasu	Przekroczono limit czasu żądania, można dostosować przez `--timeout`
9	Błąd wykonania	Backend zwrócił błąd (komunikat o błędzie zawiera code_num i opis błędu)
99	Anulowanie przez użytkownika	Przy interaktywnym potwierdzeniu wybrano No lub naciśnięto Enter

Przykład:

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

Przykłady scenariuszy użycia

Codzienna obsługa

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

Operacje wsadowe w skryptach

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

Tworzenie kopii zapasowych i inspekcja

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

Kontrole przed usunięciem

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

Wywołanie z narzędzi AI

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

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

Rozwój wewnętrzny i integracja systemowa

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

Często zadawane pytania

Q: Czy CLI wymaga dodatkowej instalacji?

Nie. CLI jest instalowane wraz z aplikacją VMs; po włączeniu aplikacji wystarczy wykonać polecenie vms.

Q: Czy CLI musi być używane przez SSH?

Nie. CLI można wywoływać z dowolnego terminala wiersza poleceń, w tym z terminala lokalnego, zdalnego SSH, skryptów, narzędzi AI itp.

Q: Czy CLI może zarządzać maszynami wirtualnymi na innych urządzeniach?

Nie. CLI komunikuje się z usługą VMs przez lokalny unix socket i służy wyłącznie do zarządzania lokalnymi maszynami wirtualnymi.

Q: Dlaczego jedne polecenia proszą o potwierdzenie, a inne nie?

Operacje usunięcia maszyny wirtualnej, usunięcia sieci, usunięcia obrazu, usunięcia przestrzeni dyskowej oraz wyłączenia (poweroff, force-poweroff) wpływają na dane lub usługi, dlatego domyślnie wymagają potwierdzenia; polecenia uruchomienia, ponownego uruchomienia, wstrzymania, wznowienia i odpytywania takich ograniczeń nie mają.

Q: Jak potwierdzać niebezpieczne operacje w trybie nieinteraktywnym?

Wszystkie niebezpieczne operacje wymagają dodania parametru --yes, w przeciwnym razie polecenie zakończy się błędem (kod wyjścia 1).

Q: Jak w skrypcie ustalić, czy polecenie zakończyło się powodzeniem?

Na podstawie kodu wyjścia: 0 oznacza powodzenie, wartość niezerowa oznacza błąd. Można też analizować treść wyjścia --json.

Q: Dlaczego lista w wyjściu --json jest obiektem?

W wyjściu JSON niektórych poleceń lista jest zorganizowana w obiekt według ID z polem totalCount, co ułatwia bezpośrednie pobieranie według ID.

Więcej pomocy

Każde polecenie obsługuje --help do wyświetlenia szczegółowego użycia:

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

Wprowadzenie​

Najważniejsze cechy​

Szybki start​

Opcje globalne​

Przykład informacji o wersji​

Środowisko uruchomieniowe​

Tabela zbiorcza poleceń​

Dokumentacja poleceń​

I. Odpytywanie maszyn wirtualnych​

vms vm list – Lista maszyn wirtualnych​

vms vm get – Podgląd szczegółów maszyny wirtualnej​

vms vm list-resource – Lista zasobów dostępnych do tworzenia maszyny wirtualnej​

vms vm logs – Podgląd dziennika operacji maszyny wirtualnej​

II. Zarządzanie zasilaniem maszyn wirtualnych​

vms vm poweron – Uruchomienie maszyny wirtualnej​

vms vm poweroff – Wyłączenie maszyny wirtualnej​

vms vm force-poweroff – Wymuszone wyłączenie maszyny wirtualnej (wysokie ryzyko)​

vms vm reboot – Ponowne uruchomienie maszyny wirtualnej​

vms vm pause – Wstrzymanie maszyny wirtualnej​

vms vm resume – Wznowienie maszyny wirtualnej​

vms vm autorun – Ustawienie automatycznego uruchamiania przy starcie​

III. Kopiowanie, eksport i usuwanie maszyn wirtualnych​

vms vm clone – Klonowanie maszyny wirtualnej​

vms vm export – Eksport maszyny wirtualnej​

vms vm delete – Usunięcie maszyny wirtualnej (wysokie ryzyko)​

IV. Wirtualne dyski​

vms vm disk list – Podgląd wirtualnych dysków​

V. Zarządzanie migawkami​

vms vm snapshot list – Lista migawek​

vms vm snapshot create – Utworzenie migawki​

vms vm snapshot edit – Edycja migawki​

vms vm snapshot config – Podgląd konfiguracji maszyny wirtualnej z migawki​

vms vm snapshot consistency – Podgląd spójności migawki​

VI. Konsola zdalna​

vms vm link – Pobranie informacji o połączeniu z VNC​

VII. Zarządzanie sieciami wirtualnymi​

vms network list – Lista sieci wirtualnych​

vms network get – Podgląd szczegółów sieci wirtualnej​

vms network create – Utworzenie sieci wirtualnej​

vms network update – Aktualizacja sieci wirtualnej​

vms network delete – Usunięcie sieci wirtualnej (wysokie ryzyko)​

vms network list-interfaces – Lista interfejsów sieciowych​

vms network list-vnics – Lista wirtualnych kart sieciowych w sieci​

vms network ovsinfo – Podgląd stanu OVS​

VIII. Zarządzanie obrazami​

vms image list – Lista obrazów​

vms image edit – Edycja obrazu​

vms image delete – Usunięcie obrazu (wysokie ryzyko)​

vms image list-vms – Podgląd maszyn wirtualnych korzystających z tego obrazu​

IX. Zarządzanie przestrzeniami dyskowymi​

vms repo list – Lista przestrzeni dyskowych​

vms repo get – Podgląd szczegółów przestrzeni dyskowej​

vms repo update – Aktualizacja przestrzeni dyskowej​

vms repo delete – Usunięcie przestrzeni dyskowej (wysokie ryzyko)​

vms repo list-volumes – Lista dostępnych wolumenów​

vms repo list-vms – Lista maszyn wirtualnych w przestrzeni dyskowej​

vms repo check-running – Sprawdzenie działających maszyn wirtualnych w przestrzeni dyskowej​

vms repo whether-exist-data – Sprawdzenie, czy w przestrzeni dyskowej istnieją dane​

X. Ustawienia globalne​

vms setting get – Podgląd ustawień globalnych​

XI. Odpytywanie informacji o monitorowaniu​

vms collectd hostinfo – Podgląd informacji o monitorowaniu hosta​

vms collectd vminfo – Podgląd informacji o monitorowaniu maszyn wirtualnych​

vms collectd storageinfo – Podgląd informacji o monitorowaniu przestrzeni dyskowej​

Tryb interaktywny i nieinteraktywny​

Tryb interaktywny (środowisko terminala)​

Tryb nieinteraktywny (skrypty/automatyzacja)​

Format wyjścia JSON​

Opis kodów wyjścia​

Przykłady scenariuszy użycia​

Codzienna obsługa​

Operacje wsadowe w skryptach​

Tworzenie kopii zapasowych i inspekcja​

Kontrole przed usunięciem​

Wywołanie z narzędzi AI​

Rozwój wewnętrzny i integracja systemowa​

Często zadawane pytania​

Więcej pomocy​

Wprowadzenie

Najważniejsze cechy

Szybki start

Opcje globalne

Przykład informacji o wersji

Środowisko uruchomieniowe

Tabela zbiorcza poleceń

Dokumentacja poleceń

I. Odpytywanie maszyn wirtualnych

vms vm list – Lista maszyn wirtualnych

vms vm get – Podgląd szczegółów maszyny wirtualnej

vms vm list-resource – Lista zasobów dostępnych do tworzenia maszyny wirtualnej

vms vm logs – Podgląd dziennika operacji maszyny wirtualnej

II. Zarządzanie zasilaniem maszyn wirtualnych

vms vm poweron – Uruchomienie maszyny wirtualnej

vms vm poweroff – Wyłączenie maszyny wirtualnej

vms vm force-poweroff – Wymuszone wyłączenie maszyny wirtualnej (wysokie ryzyko)

vms vm reboot – Ponowne uruchomienie maszyny wirtualnej

vms vm pause – Wstrzymanie maszyny wirtualnej

vms vm resume – Wznowienie maszyny wirtualnej

vms vm autorun – Ustawienie automatycznego uruchamiania przy starcie

III. Kopiowanie, eksport i usuwanie maszyn wirtualnych

vms vm clone – Klonowanie maszyny wirtualnej

vms vm export – Eksport maszyny wirtualnej

vms vm delete – Usunięcie maszyny wirtualnej (wysokie ryzyko)

IV. Wirtualne dyski

vms vm disk list – Podgląd wirtualnych dysków

V. Zarządzanie migawkami

vms vm snapshot list – Lista migawek

vms vm snapshot create – Utworzenie migawki

vms vm snapshot edit – Edycja migawki

vms vm snapshot config – Podgląd konfiguracji maszyny wirtualnej z migawki

vms vm snapshot consistency – Podgląd spójności migawki

VI. Konsola zdalna

vms vm link – Pobranie informacji o połączeniu z VNC

VII. Zarządzanie sieciami wirtualnymi

vms network list – Lista sieci wirtualnych

vms network get – Podgląd szczegółów sieci wirtualnej

vms network create – Utworzenie sieci wirtualnej

vms network update – Aktualizacja sieci wirtualnej

vms network delete – Usunięcie sieci wirtualnej (wysokie ryzyko)

vms network list-interfaces – Lista interfejsów sieciowych

vms network list-vnics – Lista wirtualnych kart sieciowych w sieci

vms network ovsinfo – Podgląd stanu OVS

VIII. Zarządzanie obrazami

vms image list – Lista obrazów

vms image edit – Edycja obrazu

vms image delete – Usunięcie obrazu (wysokie ryzyko)

vms image list-vms – Podgląd maszyn wirtualnych korzystających z tego obrazu

IX. Zarządzanie przestrzeniami dyskowymi

vms repo list – Lista przestrzeni dyskowych

vms repo get – Podgląd szczegółów przestrzeni dyskowej

vms repo update – Aktualizacja przestrzeni dyskowej

vms repo delete – Usunięcie przestrzeni dyskowej (wysokie ryzyko)

vms repo list-volumes – Lista dostępnych wolumenów

vms repo list-vms – Lista maszyn wirtualnych w przestrzeni dyskowej

vms repo check-running – Sprawdzenie działających maszyn wirtualnych w przestrzeni dyskowej

vms repo whether-exist-data – Sprawdzenie, czy w przestrzeni dyskowej istnieją dane

X. Ustawienia globalne

vms setting get – Podgląd ustawień globalnych

XI. Odpytywanie informacji o monitorowaniu

vms collectd hostinfo – Podgląd informacji o monitorowaniu hosta

vms collectd vminfo – Podgląd informacji o monitorowaniu maszyn wirtualnych

vms collectd storageinfo – Podgląd informacji o monitorowaniu przestrzeni dyskowej

Tryb interaktywny i nieinteraktywny

Tryb interaktywny (środowisko terminala)

Tryb nieinteraktywny (skrypty/automatyzacja)

Format wyjścia JSON

Opis kodów wyjścia

Przykłady scenariuszy użycia

Codzienna obsługa

Operacje wsadowe w skryptach

Tworzenie kopii zapasowych i inspekcja

Kontrole przed usunięciem

Wywołanie z narzędzi AI

Rozwój wewnętrzny i integracja systemowa

Często zadawane pytania

Więcej pomocy