Proxmox VE Remote Migration: VMs ohne Cluster von Host zu Host migrieren

Die Proxmox VE Remote Migration ist eines der praktischsten Features für alle, die virtuelle Maschinen zwischen zwei Proxmox-Servern verschieben möchten, ohne dafür einen gemeinsamen Clusterverbund aufbauen zu müssen. In diesem ausführlichen Tutorial zeige ich dir Schritt für Schritt, wie du eine VM per qm remote-migrate von einem Quell-Host auf einen Ziel-Host überträgst – inklusive API-Token, Berechtigungen, Fingerprint und einem kompletten Beispiel mit fiktiven IP-Adressen.

Das Ganze funktioniert komplett über die Kommandozeile und eignet sich hervorragend für verteilte Standorte, den Serverumzug in ein neues Rechenzentrum oder einfach den Wechsel auf neue Hardware. Ich bin mir sicher, irgendwann wird diese Funktion auch in die GUI kommen.

Kurz gesagt: Bei der Remote Migration wird eine VM über das Netzwerk vom Quell-Host zum Ziel-Host kopiert. Die beiden Hosts müssen nicht Teil desselben Clusters sein – die Authentifizierung erfolgt über einen API-Token und der TLS-Fingerprint stellt sicher, dass du dich wirklich mit dem richtigen Zielserver verbindest.

Was ist die Proxmox VE Remote Migration?

Die Remote Migration bezeichnet den Prozess, bei dem eine virtuelle Maschine (VM) oder ein Container (LXC) von einem Proxmox-Host auf einen anderen übertragen wird, ohne dass die beteiligten Hosts Teil eines gemeinsamen Clusters sind.

Die Übertragung läuft dabei über das Netzwerk: Die VM-Konfiguration und die zugehörigen Disk-Images werden vom Quellhost zum Zielhost transferiert. Diese Methode ist besonders hilfreich in Umgebungen, in denen eine zentrale Clusterverwaltung nicht möglich oder nicht gewünscht ist – etwa bei geografisch verteilten Standorten, isolierten Systemen oder bei der Migration zwischen physisch komplett getrennten Servern.

Der klassische Weg (Live-Migration innerhalb eines Clusters) setzt voraus, dass beide Nodes im selben Cluster hängen, sich im selben Quorum befinden und idealerweise gemeinsamen Shared Storage nutzen. Genau diese Anforderungen entfallen bei der Remote Migration. Du brauchst lediglich eine Netzwerkverbindung zwischen beiden Hosts und einen gültigen API-Token auf dem Zielsystem.

Wichtig zu wissen: Proxmox kennzeichnet den Befehl qm remote-migrate in der offiziellen Dokumentation aktuell noch als EXPERIMENTAL feature. In der Praxis läuft die Migration bereits sehr zuverlässig, dennoch solltest du für Produktivsysteme immer ein aktuelles Backup vorliegen haben, bevor du startest.

Voraussetzungen für die Remote Migration

Bevor es losgeht, sollten folgende Punkte erfüllt sein:

• Zwei erreichbare Proxmox-VE-Hosts (Quelle und Ziel), idealerweise auf einer aktuellen und möglichst gleichen PVE-Version.
• Netzwerkverbindung zwischen beiden Hosts, wobei der Ziel-Host auf Port 8006 (Proxmox-Web-/API-Port) und für den Datentransfer auf den SSH-Ports erreichbar sein muss.
• Root-Zugriff bzw. eine Shell auf dem Quell-Host, denn dort wird der eigentliche Migrationsbefehl abgesetzt.
• Zugriff auf die Weboberfläche des Ziel-Hosts, um dort den API-Token und die Berechtigungen einzurichten.
• Genügend freier Speicherplatz auf dem Ziel-Storage für die Disk-Images der VM.

Merke dir für den weiteren Verlauf diese einfache Faustregel: Alles, was mit API-Token, Berechtigungen und Fingerprint zu tun hat, richtest du auf dem ZIEL-System ein. Der eigentliche Migrationsbefehl wird auf dem QUELL-System ausgeführt.

Unser Beispiel-Szenario mit fiktiven IP-Adressen

Damit das Ganze greifbar wird, arbeiten wir das komplette Tutorial anhand eines durchgehenden Beispiels durch. Die folgenden Werte sind frei erfunden – du ersetzt sie später einfach durch deine eigenen.

Rolle	Hostname	IP-Adresse	Beschreibung
Quelle (Source)	pve-quelle	192.168.10.10	Hier liegt die VM aktuell und hier setzen wir den Befehl ab.
Ziel (Destination)	pve-ziel	192.168.20.20	Hierhin soll die VM wandern. Hier richten wir Token & Co. ein.

Weitere Eckdaten für unser Beispiel:

• VM-ID auf der Quelle: 100
• Gewünschte VM-ID auf dem Ziel: 200
• Name des API-Tokens: migration
• Benutzer: root@pam
• Netzwerk-Bridge auf dem Ziel: vmbr0
• Storage auf dem Ziel: local-lvm

Das Ziel ist also: Die VM mit der ID 100 auf pve-quelle (192.168.10.10) soll als VM 200 auf pve-ziel (192.168.20.20) landen.

Schritt 1: API-Token auf dem Ziel-Host erstellen

Die Remote Migration authentifiziert sich nicht per SSH-Passwort, sondern über einen API-Token. Das ist ein Zugangsschlüssel, der auf dem Ziel-Host erzeugt wird und dem Quell-Host erlaubt, per API auf das Zielsystem zuzugreifen und die Migration anzustoßen.

Melde dich also an der Weboberfläche des Ziel-Hosts (pve-ziel, https://192.168.20.20:8006) an und navigiere zu:

Datacenter → Permissions → API Tokens → Add

Dort füllst du aus:

• User: root@pam
• Token ID: ein beliebiger Name, in unserem Beispiel migration
• Privilege Separation: Für den einfachsten Einstieg entfernst du hier den Haken (Privilege Separation deaktivieren). Damit erbt der Token dieselben Rechte wie der Benutzer. Alternativ lässt du die Trennung aktiv und vergibst die Rechte im nächsten Schritt explizit – das ist der sauberere Weg (mehr dazu gleich).

Nach dem Klick auf Add zeigt Proxmox dir einmalig das Token-Secret an. Diese Kombination aus Token-ID und Secret musst du dir jetzt sicher abspeichern, denn das Secret wird nie wieder angezeigt.

Die vollständige Kennung des Tokens setzt sich so zusammen:

PVEAPIToken=root@pam!migration=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

• root@pam – der Benutzer inklusive Realm
• migration – die Token-ID (getrennt durch ein !)
• der lange Wert dahinter – das eigentliche Secret

Schritt 2: Berechtigung für den API-Token setzen

Damit der Token die Migration tatsächlich durchführen darf, benötigt er ausreichende Rechte auf dem Ziel-Host. Hast du im vorigen Schritt die Privilege Separation aktiv gelassen, ist dieser Schritt zwingend. Hast du sie deaktiviert, erbt der Token bereits die Root-Rechte – dann kannst du diesen Schritt überspringen, solltest ihn aus Sicherheitssicht aber trotzdem kennen.

Navigiere in der Weboberfläche des Ziel-Hosts zu:

Datacenter → Permissions → Add → API Token Permission

Dort trägst du ein:

• Path: / (das Wurzelverzeichnis, damit der Token systemweit agieren darf)
• API Token: den zuvor erstellten Token, also root@pam!migration
• Role: Administrator
• Propagate: aktiviert lassen (damit die Rechte an alle Unterobjekte weitergegeben werden)

Damit hat der Token die nötigen Rechte, um auf dem Ziel-Host eine neue VM anzulegen, Storage zu belegen und die Disk-Daten entgegenzunehmen.

Sicherheitshinweis: Die Rolle Administrator auf dem Pfad / ist maximal komfortabel, aber auch maximal weitreichend. In sicherheitskritischen Umgebungen solltest du überlegen, ob eine eingeschränktere Rolle (z. B. mit den Rechten VM.Allocate, VM.Config.*, Datastore.AllocateSpace und Datastore.Audit) ausreicht und den Token nach abgeschlossener Migration wieder löschen.

Schritt 3: Fingerprint des Ziel-Hosts abfragen

Jetzt kommt ein oft missverstandener, aber sicherheitstechnisch wichtiger Teil: der Fingerprint.

Wofür ist der Fingerprint da?

Der Quell-Host baut die Verbindung zum Ziel-Host über eine TLS-verschlüsselte Verbindung auf. Da beide Server nicht im selben Cluster hängen, kennen sie sich gegenseitig nicht und vertrauen sich nicht automatisch. Damit die Migration nicht auf einen falschen oder untergeschobenen Server läuft (Stichwort Man-in-the-Middle-Angriff), prüft der Quell-Host das TLS-Zertifikat des Ziel-Hosts anhand eines eindeutigen Fingerabdrucks.

Dieser Fingerprint ist ein SHA-256-Hash des TLS-Zertifikats des Ziel-Hosts. Er ist quasi der „Fingerabdruck“ des Servers: Nur wenn der Fingerprint übereinstimmt, ist sichergestellt, dass sich der Quell-Host wirklich mit dem echten Ziel-Host verbindet – und nicht mit einem Angreifer, der sich dazwischengeschaltet hat.

Fingerprint auf dem Ziel-Host abrufen

Den Fingerprint fragst du direkt auf dem Ziel-Host (pve-ziel) in einer Shell ab. Führe dort folgenden Befehl aus:

openssl x509 -fingerprint -sha256 -noout -in /etc/pve/nodes/$(hostname)/pve-ssl.pem

Die Ausgabe sieht ungefähr so aus:

sha256 Fingerprint=AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90

Den Teil nach sha256 Fingerprint= (also die lange, durch Doppelpunkte getrennte Zeichenkette) kopierst du dir heraus. Genau diesen Wert brauchst du gleich im Migrationsbefehl.

Hinweis: Der Befehl nutzt $(hostname), um automatisch den korrekten Node-Namen einzusetzen. Falls du mehrere Nodes hast oder der Hostname abweicht, kannst du den Pfad /etc/pve/nodes/<nodename>/pve-ssl.pem auch manuell angeben. Verwendest du auf dem Ziel-Host ein eigenes (z. B. per Let’s Encrypt ausgestelltes) Zertifikat, ist unter Umständen die Datei pveproxy-ssl.pem maßgeblich.

Schritt 4: Die Migration auf dem Quell-Host starten

Jetzt haben wir alle Bausteine beisammen:

• die Ziel-IP (192.168.20.20)
• den API-Token (PVEAPIToken=root@pam!migration=<SECRET>)
• den Fingerprint des Ziel-Hosts

Der eigentliche Migrationsbefehl wird jetzt auf dem Quell-Host (pve-quelle, 192.168.10.10) in einer Shell ausgeführt. Der Befehl lautet in seiner allgemeinen Form laut offizieller Proxmox-Dokumentation:

qm remote-migrate <vmid> [<target-vmid>] <target-endpoint> --target-bridge <bridge> --target-storage <storage> [OPTIONS]

Der <target-endpoint> fasst dabei Ziel-Host, API-Token und Fingerprint in einem String zusammen:

apitoken=PVEAPIToken=user@realm!token=SECRET,host=<ADDRESS>[,fingerprint=<FINGERPRINT>][,port=<PORT>]

Der vollständige Beispielbefehl

Auf pve-quelle sähe der Befehl für unser Szenario komplett so aus (hier zur besseren Lesbarkeit mit Backslashes über mehrere Zeilen umgebrochen):

qm remote-migrate 100 200 \
  'apitoken=PVEAPIToken=root@pam!migration=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,host=192.168.20.20,fingerprint=AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90' \
  --target-bridge vmbr0 \
  --target-storage local-lvm \
  --online

In einer einzigen Zeile geschrieben (so wie du ihn auch direkt kopieren und einfügen kannst):

qm remote-migrate 100 200 'apitoken=PVEAPIToken=root@pam!migration=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,host=192.168.20.20,fingerprint=AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90' --target-bridge vmbr0 --target-storage local-lvm --online

Wichtig: Setze den Endpoint-String in einfache Anführungszeichen ('...'). Er enthält Sonderzeichen wie !, @ und =, die die Shell sonst falsch interpretieren würde. Gerade das Ausrufezeichen im Token führt in der Bash sonst schnell zu Fehlern (History-Expansion).

Nach dem Absenden läuft die Migration automatisch durch. Proxmox legt auf dem Ziel-Host die VM 200 an, überträgt die Disk-Images auf local-lvm, hängt die Netzwerkkarten an die Bridge vmbr0 und startet – bei --online – die VM übergangslos auf dem Zielsystem.

Die Parameter im Detail erklärt

Damit du den Befehl vollständig verstehst und flexibel anpassen kannst, hier alle Bestandteile im Überblick:

Parameter	Bedeutung	Beispielwert
<vmid>	ID der zu migrierenden VM auf dem Quell-Host	100
<target-vmid>	Gewünschte ID der VM auf dem Ziel-Host	200
apitoken=	Vollständige API-Token-Kennung des Ziel-Hosts	PVEAPIToken=root@pam!migration=<SECRET>
host=	IP-Adresse (oder DNS-Name) des Ziel-Hosts	192.168.20.20
fingerprint=	SHA-256-Fingerprint des Ziel-Zertifikats	AB:CD:...:90
port=	Optionaler Port des Ziel-Hosts (Standard 8006)	8006
--target-bridge	Netzwerk-Bridge, an die die VM auf dem Ziel gehängt wird	vmbr0
--target-storage	Storage, auf dem die Disks auf dem Ziel landen	local-lvm
--online	Live-Migration bei laufender VM (ohne Downtime)	–

Ergänzend gibt es laut offizieller Doku noch diese nützlichen Optionen:

• --online – Nutzt die Online-/Live-Migration, wenn die VM läuft. Bei gestoppter VM wird die Option ignoriert. Ohne --online muss die VM für die Migration gestoppt sein (Offline-Migration).
• --delete – Löscht die Original-VM nach erfolgreicher Migration. Standard ist 0, das heißt: Die Original-VM bleibt auf dem Quell-Host erhalten – allerdings in gestopptem Zustand. Das ist ein bewusstes Sicherheitsnetz: Läuft bei der Migration etwas schief, hast du das Original noch. Erst wenn du sicher bist, dass auf dem Ziel alles rund läuft, kannst du die Quelle löschen (manuell oder direkt via --delete).
• --bwlimit – Begrenzt die genutzte Bandbreite in KiB/s. Praktisch, wenn die Migration über eine produktive oder schmale Leitung läuft und du das Netzwerk nicht komplett auslasten willst.
• --target-bridge 1 – Der Spezialwert 1 bildet jede Quell-Bridge auf sich selbst ab (nützlich, wenn beide Hosts identisch benannte Bridges haben). Analog bildet --target-storage 1 jeden Quell-Storage auf sich selbst ab.

Der Mapping-Charakter von --target-bridge und --target-storage ist wichtig: Gibst du nur eine einzelne Bridge- bzw. Storage-ID an, werden alle Quell-Bridges bzw. -Storages auf dieses eine Ziel abgebildet. Hat deine VM mehrere Disks auf unterschiedlichen Storages oder mehrere NICs an verschiedenen Bridges, kannst du das Mapping auch pro Quelle angeben.

LXC-Container migrieren: pct remote-migrate

Was für virtuelle Maschinen qm remote-migrate ist, ist für LXC-Container der analoge Befehl pct remote-migrate. Die Vorbereitung (API-Token, Berechtigung, Fingerprint) ist identisch – lediglich der Befehl auf dem Quell-Host unterscheidet sich:

pct remote-migrate 105 205 'apitoken=PVEAPIToken=root@pam!migration=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,host=192.168.20.20,fingerprint=AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90' --target-bridge vmbr0 --target-storage local-lvm --online

Bei Containern ist zu beachten, dass die Live-Migration technisch anders funktioniert als bei VMs. In der Praxis wird ein Container für die Remote Migration in der Regel kurz neu gestartet (Restart-Migration), sodass eine kleine Downtime entsteht. Plane das bei produktiven Containern entsprechend ein.

Was passiert im Hintergrund?

Damit du nicht nur die Befehle abtippst, sondern auch verstehst, was Proxmox tatsächlich tut, hier der Ablauf einer Remote Migration Schritt für Schritt:

1. Der Quell-Host baut über den API-Token eine authentifizierte, TLS-verschlüsselte Verbindung zum Ziel-Host auf (Port 8006).
2. Der Fingerprint wird geprüft: Stimmt der Fingerabdruck des vom Ziel präsentierten Zertifikats mit dem im Befehl angegebenen Wert überein? Nur dann geht es weiter.
3. Auf dem Ziel-Host wird eine neue VM mit der gewünschten Ziel-ID (200) angelegt und die Konfiguration übertragen (mit Anpassung von Bridge und Storage gemäß deiner Mapping-Angaben).
4. Die Disk-Images werden über einen sicheren Tunnel vom Quell- zum Ziel-Storage übertragen.
5. Bei --online und laufender VM werden während der Übertragung auch die noch anfallenden Änderungen (der RAM-Zustand und die Disk-Deltas) nachgezogen, sodass am Ende ein nahtloser Umschwenk auf das Zielsystem möglich ist.
6. Die VM läuft nun auf dem Ziel-Host. Die Original-VM auf der Quelle bleibt (ohne --delete) gestoppt erhalten.

Häufige Fehler und Troubleshooting

Ein paar Stolpersteine, die bei der Proxmox VE Remote Migration immer wieder auftauchen:

„fingerprint does not match“ / TLS-Fehler: Der angegebene Fingerprint stimmt nicht mit dem des Ziel-Hosts überein. Prüfe, ob du den Fingerprint wirklich auf dem Ziel-Host abgefragt hast und ob das richtige Zertifikat (pve-ssl.pem bzw. bei Custom-Zertifikaten pveproxy-ssl.pem) verwendet wird.

„authentication failure“ / 401: Der API-Token oder das Secret ist falsch, oder der Token hat nicht die nötigen Rechte. Kontrolliere die Token-Kennung (user@realm!tokenname) und die im Schritt 2 gesetzte Berechtigung mit Path / und Rolle Administrator.

Ausrufezeichen-Probleme in der Bash: Das ! im Token löst in interaktiven Bash-Sessions die History-Expansion aus. Setze den Endpoint-String zwingend in einfache Anführungszeichen ('...'), nicht in doppelte.

Storage nicht gefunden: Der mit --target-storage angegebene Storage muss auf dem Ziel-Host existieren und genügend Platz sowie den passenden Content-Type (images für VM-Disks) haben.

Verbindung/Timeout: Prüfe, ob der Ziel-Host von der Quelle aus auf Port 8006 erreichbar ist und ob Firewalls dazwischen den Traffic durchlassen.

Version-Mismatch: Deutlich unterschiedliche PVE-Versionen zwischen Quelle und Ziel können zu Problemen führen. Halte beide Hosts möglichst auf einem aktuellen und ähnlichen Stand.

Fazit

Die Proxmox VE Remote Migration ist ein enorm praktisches Werkzeug, um VMs und Container zwischen zwei eigenständigen Proxmox-Hosts zu verschieben, ohne einen Cluster aufsetzen zu müssen. Der Ablauf ist immer gleich: Auf dem Ziel-Host erstellst du einen API-Token, vergibst die Berechtigung und liest den Fingerprint aus – auf dem Quell-Host setzt du dann den qm remote-migrate-Befehl ab.

Besonders schön ist, dass die Original-VM standardmäßig erhalten bleibt, sodass du ein Sicherheitsnetz hast. Für Produktivumgebungen gilt trotzdem: vorher ein Backup ziehen, den Token nach getaner Arbeit wieder entfernen und den experimentellen Charakter des Features im Hinterkopf behalten.

Hast du Fragen zur Remote Migration oder Feedback zu diesem Tutorial? Schreib es gerne in die Kommentare!

Quellen und weiterführende Links

• Offizielle Proxmox-Dokumentation zum qm-Befehl (inkl. qm remote-migrate): https://pve.proxmox.com/pve-docs/qm.1.html
• Offizielle Proxmox-Dokumentation zum pct-Befehl (inkl. pct remote-migrate): https://pve.proxmox.com/pve-docs/pct.1.html
• Proxmox VE Administration Guide – Migration: https://pve.proxmox.com/wiki/Migration