The Proxmox VE import reads a host's (or cluster's) virtual machines through the Proxmox VE API and copies each one to a VMStack node with Proxmox VE's own backup tool, vzdump. By default the node logs into the Proxmox VE host over SSH and reads the backup as it streams: nothing is written on the host and no backup server is needed. A Proxmox Backup Server storage can be used instead. The VM in Proxmox VE is left as it is, except for a shutdown when you ask for a final copy.
Only QEMU/KVM VMs are imported. LXC containers are listed and counted, not imported.
What you need#
| Connection | From | To | Port |
|---|---|---|---|
| Proxmox VE API | The panel | The Proxmox VE host | TCP 8006 |
| SSH (direct transfer) | Each VMStack node that receives servers | The Proxmox VE host | TCP 22, or the port you set |
| PBS (only for the PBS transfer) | Each VMStack node | The Proxmox Backup Server | TCP 8007 |
- Proxmox VE 7.2 or later.
- An API token for the panel, for example
vmstack@pve!import. Give it VM.Audit on/vms, plus VM.PowerMgmt for final copies and VM.Config.Options to turn off "start at boot" after an import. The built-in role PVEVMAdmin has all of them. With privilege separation on, give the roles to the token itself (Datacenter › Permissions). - For the direct transfer, an SSH user on the Proxmox VE host that may run
vzdump.rootis the simple case. - Nodes with a current agent. For the PBS transfer, the nodes also need
proxmox-backup-client(the installer's--pbs-client, see Proxmox Backup Server).
Add the source#
- Go to Infrastructure › Import from Proxmox › Add Proxmox VE source.
- Under Proxmox VE API: Name, Host (name or address, no scheme), Port (8006), API token ID (
user@realm!tokenid), Token secret and, optionally, the Certificate fingerprint (SHA-256, from Node › System › Certificates). - Under Direct transfer (SSH from the nodes): SSH host (empty: the API's host), Port, User (
rootby default), the node to Check the SSH login from, and Imports at once from this host (1 to 8; 1 copies one VM after the other). - Optionally, under Transfer through Proxmox Backup Server (optional): the PBS storage of Proxmox VE (offered as a list after the first check), the PBS API token the nodes read with and its secret, and the PBS certificate fingerprint (optional) (taken from Proxmox VE's storage configuration when it pins one).
- Press Save and check.
Secrets are stored encrypted and never shown again; leave a secret field empty on edit to keep it.
Trust the certificate and the SSH host key#
The check reads the Proxmox VE certificate first and sends nothing until it is trusted. If you did not paste the fingerprint, the source shows it: compare it with Node › System › Certificates in Proxmox VE, then press Trust this certificate…. The panel pins the certificate's public key; a host that later shows another key is refused before anything is sent.
The SSH host key is handled the same way. The source shows the key the host offered; compare it on the Proxmox VE host with the file the page names, for example:
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
and press Trust this host key….
Add the nodes' keys to the Proxmox VE host#
Each VMStack node logs in with its own SSH key; its private half never leaves the node. The source lists The nodes' keys to add to the host's /root/.ssh/authorized_keys. Add one line per node on the Proxmox VE host, for example:
from="203.0.113.5" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... vmstack-node1
The from= restriction is optional and uses the node's address as the panel knows it; leave it out if the node reaches the host from another address (behind NAT). Allow TCP 22 from those nodes to the host.
Press Check and read VMs again. The check lines say, in order: the certificate, the Proxmox VE version, the token's permissions, the PBS storage (a warning only, needed only for the PBS transfer), the SSH login ("vzdump runs") and the VMs it read.
A direct import copies only VMs of the Proxmox VE node the SSH host is. For a VM on another node of the cluster, migrate it in Proxmox VE, point the SSH host at its node (a second source), or use the PBS transfer.
Import VMs#
-
On Infrastructure › Import from Proxmox, the source lists its VMs with size, system and addresses, and why a VM cannot be imported (a template, a lock, a disk excluded from backups, an ARM VM).
-
Press Import… on one VM, or tick several and press Import N VMs selected….
-
On the import page choose:
Section Choices The VM(s) The host name of each new server Where Node (or Automatic: the first node that can take each VM at its turn) and Storage of the disks. Nodes that cannot take the import say why (agent, transfer, no free routed address) Who Owner, and a Plan or the VM's own size Network Keep their addresses (when they are free addresses of the node) or New addresses from the node; for one VM with cloud-init, a network seed so it takes its new addresses at first start Transfer Direct (SSH) or Through the PBS storage; While it runs or Final copy: shut it down first; Start the server when the copy is done; Turn off “Start at boot” on the Proxmox VE VM after the import -
Press Import.
A single VM's server is made at once, so limit and address problems show before Proxmox VE does anything. Several VMs are queued and go "Imports at once" at a time; each server is made when its turn comes.
While it runs or a final copy#
- While it runs: Proxmox VE backs the VM up in snapshot mode (the guest agent freezes the file systems for a moment) without stopping it. What the VM writes after the copy is not brought over. The new server is not started while the VM still runs in Proxmox VE, because both would have the same MAC address and possibly the same addresses; shut the VM down there, then start the server.
- Final copy: Proxmox VE shuts the VM down and copies it; it stays off. If the import fails or is cancelled, the VM is started again.
What is carried over#
| Proxmox VE | VMStack |
|---|---|
| sockets × cores (or vcpus), memory | vCPUs and memory (at least 512 MB) |
| Disks | Disk 0 is the first disk of the boot order; the others become extra disks with their own sizes |
| BIOS or OVMF (UEFI), Secure Boot with Microsoft keys | BIOS, UEFI or UEFI with Secure Boot; the UEFI variables when they fit the node's 4 MB firmware |
| Machine type | q35 or i440FX |
| The first network card | Its model (virtio, e1000, rtl8139) and its MAC address |
ostype win* |
Windows settings |
| A TPM | A new, empty TPM 2.0 (BitLocker or LUKS keys sealed to the old TPM need their recovery key) |
Not carried: other network cards (add private networks on VMStack for them), CD-ROM drives, PCI and USB passthrough, unused disks, the VM's snapshots, Proxmox VE firewall rules. The import page lists each of these as a note for the VM concerned.
An imported server keeps its own operating system, users and passwords: the panel does not know its root password, and it counts as "installed from an ISO". A VM whose system sets a static address gets a note naming its address and the one VMStack gives, so you can change it inside the server.
Follow, cancel and retry#
Infrastructure › Imports in progress (also linked from the import page) shows each queued or running import with a progress bar, bytes, speed, time left and the stage: queued, check, stop, backup (PBS transfer), connect, copy (per disk), write, create, start, done. Each import also has its own page, linked from Recent imports on the source page.
- Cancel before the node builds the server deletes the new server and frees its addresses; a VM the import shut down is started again. A queued import is simply cancelled.
- Retry on a failed import starts over (for a final copy the VM is shut down again first). With the PBS transfer, a copy made while the VM ran retries with the same backup.
- A failed import keeps the new server's addresses until you retry or delete it.
The PBS transfer#
When the source has a PBS storage, the import page offers Through the PBS storage: Proxmox VE backs the VM up to its PBS storage (never pruning existing backups), and the node reads it from the PBS with proxmox-backup-client. The backup stays on the PBS afterwards. Requirements:
- A Proxmox VE storage of type Proxmox Backup Server without encryption; the nodes cannot read encrypted backups.
- The panel's API token also needs VM.Backup on
/vmsand Datastore.AllocateSpace and Datastore.Audit on the PBS storage (PVEDatastoreUser). - A PBS token for the nodes with DatastoreReader on the datastore and namespace (or the token Proxmox VE writes with).
- The nodes reach the PBS on TCP 8007 and have
proxmox-backup-client.
The API has the same operations for administrators: GET /proxmox-sources, GET /proxmox-sources/{id}/vms, POST /proxmox-imports and POST /proxmox-imports/batch, cancel and retry. Sources are added only on the page. See the API reference.