Come spostare una macchina virtuale tra due host o cluster Proxmox indipendenti usando un token API, il fingerprint del certificato e il comando qm remote-migrate
Obiettivo: spostare una macchina virtuale da un host Proxmox VE a un altro host (o a un altro cluster) che non fa parte dello stesso cluster, senza esportare e reimportare backup. Lo strumento è il comando qm remote-migrate, che trasferisce configurazione e dischi della VM attraverso l'API del nodo di destinazione.
La procedura si riassume in quattro passaggi: creare un token API sull'host di destinazione (sezione 2), assegnargli i permessi (sezione 3), recuperare il fingerprint del certificato dell'host di destinazione (sezione 4) e lanciare la migrazione dall'host sorgente (sezione 5).
ℹ️ Convenzioni usate nella guida
Nei comandi i valori da sostituire sono tra parentesi angolari:
Indice
- 1. Quando usare qm remote-migrate
- 2. Creazione del token API sull'host di destinazione
- 3. Permessi del token sull'host di destinazione
- 4. Recupero del fingerprint del certificato
- 5. Lancio della migrazione dal nodo sorgente
- 6. Verifica e pulizia
- 7. Rischi e avvertenze
- 8. Risoluzione dei problemi
- 9. Riepilogo
- 10. Link utili
1. Quando usare qm remote-migrate
All'interno di un cluster Proxmox la migrazione si fa con la normale funzione Migrate (o qm migrate), perché i nodi condividono la configurazione e si fidano l'uno dell'altro. Quando invece i due host non sono nello stesso cluster (due server standalone, due cluster diversi, un vecchio host da dismettere e uno nuovo) serve qm remote-migrate: il nodo sorgente si autentica sull'API del nodo di destinazione con un token e apre un tunnel websocket attraverso il quale passano configurazione e dischi.
| Scenario | Strumento consigliato |
|---|---|
| Nodi nello stesso cluster | Migrate da interfaccia web o qm migrate |
| Host o cluster indipendenti, collegamento di rete diretto | qm remote-migrate (questa guida) |
| Host senza connettività diretta o con finestre di manutenzione lunghe | Backup con vzdump / Proxmox Backup Server e ripristino |
1.1 Prerequisiti
- Versione:
qm remote-migrateè disponibile da Proxmox VE 7.3 ed è ancora indicata come funzione sperimentale: usala con un backup recente della VM (sezione 7). Negli screenshot entrambi gli host sono Proxmox VE 8.2. - Rete: dal nodo sorgente deve essere raggiungibile la porta 8006 (API e interfaccia web) del nodo di destinazione. Il trasferimento dei dischi passa anch'esso attraverso questa porta, quindi non serve SSH tra i due host.
- Accesso root alla shell del nodo sorgente (da Node > Shell o via SSH).
- Storage e bridge di destinazione: sull'host di destinazione devono esistere lo storage che riceverà i dischi (es.
local-zfs) e il bridge di rete a cui collegare le schede della VM (es.vmbr0), con spazio sufficiente. - ID libero: l'ID che la VM avrà sulla destinazione non deve essere già in uso su quell'host.
2. Creazione del token API sull'host di destinazione
- Sull'interfaccia web dell'host di destinazione apri Datacenter > Permissions > API Tokens e premi Add.
- Come User seleziona
root@pam. - In Token ID inserisci un nome a scelta (es.
migrazione): insieme all'utente formerà l'identificativo completoroot@pam!. - Lascia Expire su never oppure imposta una scadenza vicina, così il token smette di funzionare da solo dopo la migrazione.
- Valuta l'opzione Privilege Separation (vedi sotto) e conferma con Add.
- Copia subito il Token ID completo e il Secret: il secret viene mostrato una sola volta e servirà nel comando di migrazione (sezione 5).
💡 Privilege Separation
Con Privilege Separation disattivata (come nello screenshot) il token ha gli stessi permessi dell'utente a cui appartiene, quindi con root@pam ha già accesso completo. Con l'opzione attiva il token parte senza permessi e devi assegnarglieli esplicitamente come in sezione 3. La seconda soluzione è più restrittiva, ma richiede di non dimenticare il passaggio sui permessi.
⚠️ Conserva il secret in modo sicuro
Token ID e secret danno accesso amministrativo all'host di destinazione. Non salvarli in file condivisi o in ticket, e revoca il token al termine (sezione 6.2).
3. Permessi del token sull'host di destinazione
Il token deve poter creare la VM, allocare spazio sullo storage e usare il bridge di rete sull'host di destinazione. Il modo più semplice è assegnargli il ruolo Administrator sul percorso radice:
- Apri Datacenter > Permissions e premi Add > API Token Permission.
- In Path seleziona
/. - In API Token seleziona il token creato in sezione 2 (
root@pam!). - In Role seleziona Administrator e lascia attivo Propagate.
- Conferma con Add.
La stessa finestra si apre anche dal pannello Permissions di un singolo storage, come nello screenshot: in quel caso il permesso vale solo per quello storage (percorso /storage/). Per la migrazione serve però anche il diritto di creare la VM, quindi il permesso sul percorso / è la scelta che evita errori di autorizzazione.
ℹ️ Se la Privilege Separation è disattivata
In questo caso il token eredita già i permessi di root@pam e questo passaggio non è strettamente necessario; aggiungere il permesso esplicito non crea problemi e rende la configurazione indipendente dall'opzione scelta.
4. Recupero del fingerprint del certificato
Il nodo sorgente verifica l'identità dell'host di destinazione confrontando il fingerprint SHA-256 del certificato TLS esposto sulla porta 8006. Se il fingerprint manca o non corrisponde, la migrazione si interrompe con l'errore fingerprint '…' not verified, abort! (sezione 8).
Dal nodo sorgente, con openssl
Il metodo più affidabile è leggere il certificato realmente esposto dall'host di destinazione, eseguendo dalla shell del nodo sorgente:
openssl s_client -connect L'output ha la forma sha256 Fingerprint=AB:CD:EF:…: copia solo la parte dopo il segno =, cioè 32 coppie di caratteri esadecimali separate da due punti. Il redirect fa terminare subito openssl s_client, che altrimenti resterebbe in attesa di input.
Dal nodo di destinazione
In alternativa, sulla shell dell'host di destinazione:
pvenode cert infoIl comando elenca i certificati del nodo con il relativo fingerprint. Lo stesso dato è visibile nell'interfaccia web in Node > System > Certificates, aprendo il certificato con View Certificate. Se sul nodo è installato un certificato personalizzato (pveproxy-ssl.pem, ad esempio Let's Encrypt), usa il fingerprint di quello, perché è il certificato servito sulla porta 8006.
5. Lancio della migrazione dal nodo sorgente
Apri la shell del nodo sorgente (Node > Shell o SSH come root) ed esegui il comando nella forma generale:
qm remote-migrate =,host=,fingerprint=,port=8006' --target-bridge 5.1 Parametri del comando
| Parametro | Significato |
|---|---|
| ID della VM sull'host sorgente (es. 102). |
| ID che la VM avrà sull'host di destinazione. Può essere uguale al precedente, purché sia libero sulla destinazione. |
apitoken=PVEAPIToken=root@pam! | Credenziali del token creato in sezione 2: utente, nome del token e secret, separati da ! e =. |
host= | Indirizzo IP o nome dell'host di destinazione. |
fingerprint= | Fingerprint SHA-256 del certificato dell'host di destinazione (sezione 4). |
port=8006 | Porta dell'API Proxmox sull'host di destinazione. |
--target-bridge | Bridge di rete a cui collegare le schede della VM sulla destinazione (es. vmbr0). |
--target-storage | Storage di destinazione per i dischi della VM (es. local-zfs). |
--online | Migrazione a caldo di una VM accesa (sezione 5.2). |
--delete | Elimina la VM sorgente e i suoi dati al termine di una migrazione riuscita. Senza questa opzione la VM originale resta sull'host sorgente, spenta. |
--bwlimit | Limite di banda per la copia dei dischi, in KiB/s (se omesso vale il limite di migrazione impostato nel datacenter o sullo storage), utile per non saturare la rete di produzione. |
L'intera stringa dell'endpoint va racchiusa tra apici singoli: il carattere ! del token, dentro le virgolette doppie, verrebbe interpretato dalla shell bash.
💡 Più storage o più bridge
Se la VM ha dischi su storage diversi o schede su bridge diversi, --target-storage e --target-bridge accettano anche una mappatura nella forma sorgente:destinazione, ad esempio --target-storage local-lvm:local-zfs,ZFS-Pool:local-zfs. Indicando un solo valore, tutti gli storage (o i bridge) della VM vengono mappati su quello; il valore speciale 1 mappa ogni storage (o bridge) su quello con lo stesso nome sulla destinazione.
Esempio con valori fittizi, per la VM 102 che mantiene lo stesso ID:
qm remote-migrate 102 102 'apitoken=PVEAPIToken=root@pam!migrazione=,host=,fingerprint=,port=8006' --target-bridge vmbr0 --target-storage local-zfs5.2 Migrazione online o offline
Senza --online la migrazione è offline: la VM deve essere spenta, i dischi vengono copiati interamente e la VM si riavvia sulla destinazione quando decidi tu. È il caso mostrato nello screenshot, in cui i dischi ZFS vengono trasferiti con un invio completo (full send).
Per spostare una VM accesa (migrazione a caldo, l'obiettivo originale dell'articolo) aggiungi l'opzione --online: la VM continua a funzionare durante la copia e viene trasferita sull'altro host con un'interruzione minima al termine.
qm remote-migrate =,host=,fingerprint=,port=8006' --target-bridge | Offline | Online (--online) | |
|---|---|---|
| Stato della VM | Spenta | Accesa |
| Interruzione del servizio | Per tutta la durata della copia | Minima, solo al passaggio finale |
| Carico su rete e storage | Copia dei dischi | Copia dei dischi più sincronizzazione delle modifiche e della RAM |
| Quando sceglierla | Finestra di manutenzione disponibile, VM grandi | Servizi che non possono fermarsi |
5.3 Cosa succede durante la migrazione
L'output del comando permette di seguire le fasi del trasferimento:
- Establishing API connection – connessione all'API dell'host di destinazione con il token.
- local/remote WS tunnel version e websocket tunnel started – apertura del tunnel websocket tra i due host.
- starting migration of VM … to node … – inizio della migrazione verso il nodo remoto.
- found local disk … – elenco dei dischi della VM: anche i dischi unused (non collegati) vengono trasferiti.
- full send of … e la tabella TIME / SENT / SNAPSHOT – avanzamento della copia dei dischi.
Al termine compare un messaggio di migrazione completata. Se la sessione SSH si chiude a metà, il comando si interrompe: per VM grandi conviene lanciarlo dalla shell dell'interfaccia web oppure dentro screen o tmux.
6. Verifica e pulizia
6.1 Verifica sull'host di destinazione
- Sull'host di destinazione controlla che la VM compaia con l'ID previsto (interfaccia web o
qm list). - Verifica in Hardware che i dischi siano sullo storage corretto e che le schede di rete siano collegate al bridge giusto (attenzione ai tag VLAN, che vengono mantenuti).
- Se la migrazione era offline, avvia la VM e controlla che il sistema operativo parta e sia raggiungibile in rete.
- Ricontrolla le impostazioni che dipendono dall'host: opzioni di avvio automatico, regole firewall, pianificazioni di backup e replica, che non vengono ricreate sull'host di destinazione.
qm list6.2 Pulizia
- VM sorgente: se non hai usato
--delete, la VM originale resta sull'host sorgente in stato spento. Non avviarla finché quella migrata è accesa (avresti due macchine con stesso MAC e stesso IP). Quando sei sicuro che la nuova VM funziona, eliminala dall'interfaccia web o con il comando sotto. - Token API: sull'host di destinazione elimina il token da Datacenter > Permissions > API Tokens (o lascialo scadere se hai impostato una data di scadenza) e controlla in Datacenter > Permissions che non resti il permesso assegnato in sezione 3.
qm destroy ⚠️ Prima di eliminare la VM sorgente
Controlla due volte di essere sulla shell del nodo sorgente e di aver indicato l'ID corretto: qm destroy elimina la VM e i suoi dischi in modo definitivo.
7. Rischi e avvertenze
- Funzione sperimentale: esegui sempre un backup della VM prima della migrazione, soprattutto per sistemi critici.
- Token con privilegi elevati: un token di
root@pamsenza Privilege Separation equivale alla password di root dell'host di destinazione. Imposta una scadenza e revocalo appena possibile (sezione 6.2). - Banda: la copia dei dischi può saturare il collegamento tra gli host; usa
--bwlimitse la rete è condivisa con il traffico di produzione. - Differenze tra host: CPU di generazioni diverse possono impedire la migrazione online se la VM usa il tipo di CPU host; in questo caso migra offline o imposta un tipo di CPU compatibile.
- Dischi non collegati: anche i dischi unused vengono copiati e occupano spazio sulla destinazione; eliminali prima se non servono.
8. Risoluzione dei problemi
L'errore più comune è il fingerprint mancante o errato: il nodo sorgente non riesce a verificare il certificato dell'host di destinazione e interrompe la migrazione.
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| fingerprint '…' not verified, abort! | Parametro fingerprint= mancante, errato o relativo a un altro certificato | Rileggi il fingerprint con openssl (sezione 4) e copialo per intero |
| Errore di autenticazione (401) | Token ID o secret errati, oppure token scaduto o eliminato | Ricrea il token (sezione 2) e copia di nuovo il secret |
| Errore di permessi (403) | Token con Privilege Separation senza permessi sufficienti | Assegna il ruolo Administrator sul percorso / (sezione 3) |
| Timeout o connessione rifiutata | Porta 8006 della destinazione non raggiungibile | Verifica routing e firewall tra i due host |
| Errore sullo storage o sul bridge | Storage o bridge indicati non esistenti sulla destinazione, o spazio insufficiente | Controlla i nomi e lo spazio libero (sezione 5.1) |
| La VM accesa non viene migrata | Manca l'opzione --online | Spegni la VM o aggiungi --online (sezione 5.2) |
| Errore sull'ID di destinazione | L'ID scelto è già usato sull'host di destinazione | Indica un |
9. Riepilogo
| Comando | Dove | A cosa serve |
|---|---|---|
openssl s_client … | openssl x509 -noout -fingerprint -sha256 | Nodo sorgente | Leggere il fingerprint del certificato remoto |
pvenode cert info | Nodo di destinazione | Leggere i certificati del nodo e i loro fingerprint |
qm remote-migrate … | Nodo sorgente | Migrare la VM verso l'host remoto |
qm list | Entrambi i nodi | Verificare le VM presenti e il loro stato |
qm destroy | Nodo sorgente | Eliminare la VM originale dopo la verifica |
- Token API creato sull'host di destinazione e secret salvato → sezione 2.
- Permesso Administrator assegnato al token → sezione 3.
- Fingerprint SHA-256 della destinazione recuperato → sezione 4.
- Migrazione lanciata dal nodo sorgente, con
--onlinese la VM è accesa → sezione 5. - VM verificata sulla destinazione, VM sorgente e token rimossi → sezione 6.
