v0.1.7

Multi-Node Dispatch

Last updated


This page explains how QemuRun-pve finds which node hosts a VM and decides whether to run qm locally or over SSH.

Locating a VM's Node


The service scans /etc/pve/nodes/*/qemu-server/*.conf (the Proxmox cluster filesystem, synced to every node) and derives a node-to-VMID mapping from the path:
  1. /etc/pve/nodes/pve2/qemu-server/120.conf → VMID 120 lives on pve2

Where Commands Run


ConditionExecution
VM's node = MAIN_NODELocal qm <args>
Another node with a matching NODE_<node>ssh root@<NODE_node> qm <args>
MAIN_NODE unset, or no NODE_<node>SSH runs with an empty host and the command fails

SSH always carries these options so no interactive prompt can block the API:
  1. -o ConnectTimeout=10
  2. -o StrictHostKeyChecking=no
  3. -o UserKnownHostsFile=/dev/null
  4. -o BatchMode=yes

Operations Using Dispatch


Operationqm subcommand
startqm start
stopqm stop
shutdownqm shutdown
rebootqm reboot
destroyqm destroy
set/cpuqm set --cores
set/memoryqm set --memory [--numa --balloon]
set/diskqm disk resize scsi0 +<size>
set/nodeqm migrate <vmid> <node> --with-local-disks

Exceptions


  • Install: qm create, importdisk, and qm set always run locally on the main node; with node set, migration happens after creation, and only start and reboot go through dispatch
  • GET /vm/:id/status: runs qm status locally on the main node only, so querying a VM on another node fails
  • VM list: reads cluster-wide data via pvesh get /cluster/resources and needs no dispatch

Migration


POST /api/vm/:id/set/node requires a stopped VM, moves local disks with --with-local-disks, and streams qm migrate output line by line over SSE.
中文