Nodes

What a VMStack node needs: Debian 12 or 13, a CPU with VT-x or AMD-V, amd64 or arm64, memory and disk, and the ports the panel and other nodes use.

A node is a server that runs your customers' virtual machines and containers. The node installer sets up KVM, libvirt and the VMStack agent on it. This page lists what the node must have; Adding nodes covers the install itself.

Operating system#

Supported
Systems Debian 13 (recommended) and Debian 12
Architectures amd64 (x86_64) for virtual machines and containers; arm64 (aarch64) for containers only

The node installer refuses any other distribution, including Ubuntu. Debian 13 is the system nodes are verified on; Debian 12 is accepted.

Install the node on a fresh, minimal Debian. The installer adds packages (QEMU, libvirt, guest disk tools, WireGuard tools, smartmontools, and optionally ZFS, Ceph client, container tools and the Proxmox Backup client), but it does not remove anything.

arm64 nodes#

The installer picks the agent binary by the machine's architecture. An arm64 node runs containers only for now: the panel has no virtual machine images for arm64, and the node page says so under Architecture. The panel keeps each image on nodes of its own architecture, so an amd64 image is never placed on an arm64 node.

CPU virtualisation#

Virtual machines need hardware virtualisation: Intel VT-x (vmx) or AMD-V (svm), turned on in the server's BIOS or UEFI settings.

To check before you install:

grep -Eo 'vmx|svm' /proc/cpuinfo | sort -u
ls -l /dev/kvm

The first command must print vmx or svm; the second must show a character device. The node installer does not stop when either is missing: it prints a warning ("no vmx/svm CPU flag found" or "/dev/kvm is missing") and installs anyway, but virtual machines will not start until virtualisation works. Containers do not need it.

A node inside a virtual machine#

You can run a node inside a virtual machine (for a test node, for example) only when the outer hypervisor passes virtualisation through to it (nested virtualisation). The two checks above then work inside the VM. Expect slower guests than on bare metal.

Nested virtualisation for your customers' servers#

Whether a customer's server can run its own hypervisor is a separate setting. By default the panel turns nested virtualisation off for servers, because of a known guest-escape risk. You can turn it on per node or per server; see Node settings.

Memory and disk#

The node installer does not check memory or disk size. Size the node for the servers you plan to sell on it, plus room for the operating system and for the node's image cache:

  • Memory: the total of the servers' memory, plus the host's own use. The panel's placement uses each node's capacity and limits; see Groups and locations.
  • Disk: by default server disks are files under /var/lib/vmstack/images. You can give the node LVM-thin, ZFS, NFS or Ceph storages instead or as well; see Storage. With --setup-storage, the installer asks which empty disks to use.
  • A second disk for local backups is optional; see Backup destinations.

Ports#

Port From What for
TCP 8443 The panel The agent's API (mutual TLS: it answers only the panel's certificate). Changed with --port.
TCP 8444 Other nodes Moving servers and copying images between nodes
UDP 51820 Other nodes Private networks between nodes (WireGuard)
TCP 22 You SSH
TCP and UDP 20000–60000 The internet Port forwards of servers behind NAT (only when you use NAT)

The node installer opens the agent port in ufw or firewalld when one of them is active. With --panel-ip, it allows the agent port only from the panel's address. When the node has other firewall rules, allow these ports yourself. After enrolment, the panel can manage the node's firewall for you; see Node firewall.

Out from the node: HTTPS to the panel (the agent and its updates are downloaded from it), and HTTPS to the image servers and repositories your images and packages come from.

Before you start#

  • The node needs a public address the panel can reach on the agent port.
  • The IP addresses your servers will use must be routed or bridged to the node by your provider; see Network modes.
  • Each node needs its own licence slot when the panel enforces a licence; see Small and Unlimited nodes.