Proxmox BS: Ripristino file da backup della VM

Introduzione

Questo tutorial spiega come usare Proxmox Backup Server per il ripristino a livello di file da un backup di una VM senza distribuire l'intera macchina virtuale. Imparerete a recuperare singoli file tramite il file browser dei backup di Proxmox nell'interfaccia web di Proxmox VE e a eseguire il recupero dei file di Proxmox da riga di comando con proxmox-backup-client. Questo flusso di lavoro è utile quando è necessario ripristinare singoli file contenuti nei backup di Proxmox senza eseguire un ripristino completo della VM.

Destinatari: amministratori di sistema di livello intermedio
Tempo stimato: 20-40 minuti
Obiettivo finale: al termine di questo tutorial sarete in grado di ripristinare file specifici da un backup di una VM su Proxmox Backup Server senza ripristinare l'intera VM.

Prerequisiti

Prima di iniziare, assicuratevi di disporre di:

• Un host Proxmox VE funzionante con uno storage Proxmox Backup Server configurato.
• Proxmox Backup Server 3.x o 4.x con un datastore esistente.
• Un backup di VM completato e archiviato nel datastore PBS.
• Accesso all'interfaccia web di Proxmox VE con i permessi per esplorare i backup e ripristinare i file.
• Accesso shell all'host Proxmox VE per il metodo CLI.
• Il comando proxmox-backup-client disponibile sull'host Proxmox VE.
• Accesso shell come root per il metodo di mapping da CLI, perché il mapping dei dispositivi loop e il mount dei file system richiedono privilegi elevati.
• Il file della chiave di cifratura, se il backup della VM utilizza la cifratura lato client.
• Conoscenze di base di file system Linux, punti di mount e storage di backup di Proxmox VE.

Passaggio 1: comprendere le opzioni di ripristino a livello di file

Proxmox Backup Server archivia i backup delle macchine virtuali di Proxmox VE come backup di immagini disco a livello di blocco. Ciò significa che un backup di VM contiene di solito file come drive-scsi0.img.fidx, qemu-server.conf.blob e client.log.blob, e non un normale albero di directory.

Per i flussi di recupero granulare dei file in Proxmox VE sono disponibili due opzioni pratiche:

• Usare l'interfaccia web di Proxmox VE per esplorare lo snapshot del backup e scaricare i file.
• Usare proxmox-backup-client map per mappare l'immagine disco di una VM dal backup a un dispositivo loop locale, quindi montare il file system del guest in sola lettura.

Il pulsante File Restore di Proxmox VE apre un file browser per il contenuto del backup. Il comando proxmox-backup-client map mappa l'immagine di un'unità di backup della VM a un dispositivo loopback locale e deve essere seguito da unmap al termine del recupero.

Passaggio 2: ripristinare singoli file tramite l'interfaccia web di Proxmox VE

Usate questo metodo quando volete recuperare file specifici nel modo più semplice, senza distribuire l'intera VM.

Aprire la vista dei backup

1. Accedete all'interfaccia web di Proxmox VE.
2. Nell'albero di navigazione a sinistra, selezionate la VM.
3. Aprite la scheda Backup.
4. Selezionate lo storage Proxmox Backup Server dal selettore dello storage se il vostro ambiente dispone di più storage di backup.

Dovreste vedere un elenco degli snapshot di backup disponibili per la VM selezionata.

Aprire il file browser dei backup di Proxmox

1. Selezionate lo snapshot di backup che contiene il file necessario.
2. Fate clic su File Restore.
3. Attendete che Proxmox VE apra il file browser del backup.
4. Espandete il disco della VM che contiene il sistema operativo guest o il volume dati.

State ora esplorando gli snapshot di backup tramite l'interfaccia di Proxmox VE. Questa vista supporta il flusso di ripristino dei file di Proxmox Backup Server e consente di recuperare dati selezionati senza eseguire un ripristino completo della VM.

Scaricare il file necessario

1. Passate alla directory che contiene il file.
2. Selezionate il file.
3. Fate clic su Download.
4. Salvate il file sulla vostra workstation.

Dovreste ricevere il file selezionato tramite il browser. Questo completa un ripristino a livello di file da browser a partire dal backup della VM.

Passaggio 3: preparare l'ambiente CLI

Usate questo metodo quando ripristinate dati dai backup del datastore PBS da riga di comando.

Definire le variabili di recupero

Eseguite i comandi seguenti sull'host Proxmox VE. Sostituite i segnaposto con i valori del vostro ambiente.

export PBS_REPOSITORY="<PBS_USER>@<PBS_REALM>@<PBS_SERVER>:<DATASTORE>"
export PBS_SNAPSHOT="vm/<VM_ID>/<SNAPSHOT_TIMESTAMP>"
export PBS_ARCHIVE="drive-scsi0.img"
export RESTORE_MOUNT="/mnt/pbs-file-restore"
export RESTORE_TARGET="/root/restored-from-pbs"
export PBS_PASSWORD="<PBS_USER_PASSWORD>"
export PBS_FINGERPRINT="<PBS_SERVER_FINGERPRINT>"

Valori di esempio:

export PBS_REPOSITORY="root@[email protected]:backup"
export PBS_SNAPSHOT="vm/101/2026-06-04T01:30:00Z"
export PBS_ARCHIVE="drive-scsi0.img"
export RESTORE_MOUNT="/mnt/pbs-file-restore"
export RESTORE_TARGET="/root/restored-from-pbs"
export PBS_PASSWORD="12345678"
export PBS_FINGERPRINT="b1:89:bd:c9:b1:f8:33..."

Le variabili definiscono il repository PBS, lo snapshot di backup della VM, l'archivio disco da mappare, il punto di mount temporaneo e la destinazione locale del recupero. Impostate le variabili d'ambiente PBS_PASSWORD e PBS_FINGERPRINT. Ottenete il fingerprint del certificato su Proxmox Backup Server eseguendo proxmox-backup-manager cert info.

Durante la prima connessione, il comando login chiede in modo interattivo di confermare il fingerprint del certificato e di inserire la password. Senza queste variabili, i comandi automatizzati falliscono con certificate validation failed quando manca il fingerprint o con no password input mechanism available quando non viene fornita una password.

Accedere a Proxmox Backup Server

Eseguite il comando di login:

proxmox-backup-client login --repository "$PBS_REPOSITORY"

Output atteso:

Password:

Inserite la password dell'utente PBS. Se l'autenticazione riesce, il client memorizza un ticket temporaneo.

Passaggio 4: identificare lo snapshot di backup della VM e l'archivio disco

Elencate i gruppi di backup nel repository PBS:

proxmox-backup-client list --repository "$PBS_REPOSITORY"

Esempio di output atteso: tabella dei backup.

Elencate gli snapshot del gruppo della VM:

proxmox-backup-client snapshot list vm/<VM_ID> \
  --repository "$PBS_REPOSITORY"

Esempio di output atteso: tabella degli snapshot.

Elencate i file nello snapshot selezionato:

proxmox-backup-client snapshot files "$PBS_SNAPSHOT" \
  --repository "$PBS_REPOSITORY"

Esempio di output atteso:

client.log.blob
drive-scsi0.img.fidx
index.json.blob
qemu-server.conf.blob

Passaggio 5: mappare il disco del backup della VM a un dispositivo loop

Create le directory di ripristino:

mkdir -p "$RESTORE_MOUNT" "$RESTORE_TARGET"

Mappate l'immagine disco della VM da PBS:

proxmox-backup-client map "$PBS_SNAPSHOT" "$PBS_ARCHIVE" \
  --repository "$PBS_REPOSITORY"

Esempio di output atteso:

/dev/loop0

Salvate il dispositivo loop restituito in una variabile:

export LOOP_DEVICE="/dev/loop0"

Il comando map mappa l'immagine di un'unità di backup della VM a un dispositivo loopback locale.

Passaggio 6: ispezionare il disco mappato

Elencate le partizioni e i file system:

lsblk -f "$LOOP_DEVICE"

Esempio di output atteso:

NAME        FSTYPE LABEL UUID                                 MOUNTPOINTS
loop0
├─loop0p1   vfat         1111-2222
└─loop0p2   ext4         aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Se le partizioni non compaiono, chiedete al kernel di rileggere la tabella delle partizioni:

partx -a "$LOOP_DEVICE"

Quindi controllate di nuovo:

lsblk -f "$LOOP_DEVICE"

Dovreste ora vedere dispositivi di partizione come /dev/loop0p1 e /dev/loop0p2.

Passaggio 7: montare il file system del guest in sola lettura

Selezionate la partizione che contiene i file necessari. In questo esempio, il file system root di Linux è /dev/loop0p2.

Montatela in sola lettura:

mount -o ro /dev/loop0p2 "$RESTORE_MOUNT"

Output atteso: il comando non dovrebbe restituire alcun output quando il mount riesce.

Controllate il file system montato:

ls "$RESTORE_MOUNT"

Esempio di output atteso:

bin
boot
etc
home
root
usr
var

State ora usando la riga di comando per ripristinare singoli file contenuti nei backup di Proxmox, senza ripristinare l'intera macchina virtuale.

Montare un volume LVM se il guest usa LVM

Se lsblk -f mostra LVM2_member, cercate i gruppi di volumi:

vgscan --mknodes

Esempio di output atteso:

Found volume group "ubuntu-vg" using metadata type lvm2

Attivate il gruppo di volumi:

vgchange -ay ubuntu-vg

Elencate i volumi logici:

lvs

Esempio di output atteso:

LV        VG        Attr       LSize
ubuntu-lv ubuntu-vg -wi-a----- 50.00g

Montate il volume logico in sola lettura:

mount -o ro /dev/ubuntu-vg/ubuntu-lv "$RESTORE_MOUNT"

Dovreste ora poter esplorare il file system del guest ripristinato in $RESTORE_MOUNT.

Passaggio 8: copiare file specifici dal backup

Create una directory locale per i file recuperati:

mkdir -p "$RESTORE_TARGET"

Copiate un file:

cp -a "$RESTORE_MOUNT/etc/hostname" "$RESTORE_TARGET/"

Output atteso: il comando non dovrebbe restituire alcun output quando il file viene copiato correttamente.

Copiate una directory:

rsync -a "$RESTORE_MOUNT/var/www/html/" \
  "$RESTORE_TARGET/html/"

Output atteso: il comando non dovrebbe restituire alcun output quando la directory viene copiata correttamente.

Verificate i file copiati:

find "$RESTORE_TARGET" -maxdepth 3 -type f

Esempio di output atteso:

/root/restored-from-pbs/hostname
/root/restored-from-pbs/html/index.html

Passaggio 9: ripristinare file da un backup PBS basato su file con pxar

Questo passaggio è facoltativo per il ripristino a livello di file di una VM, ma è utile quando lo snapshot di backup contiene un archivio di file come root.pxar.

Elencate i file nello snapshot:

proxmox-backup-client snapshot files "$PBS_SNAPSHOT" \
  --repository "$PBS_REPOSITORY"

Esempio di output atteso:

catalog.pcat1.didx
root.pxar.didx

Aprite la shell di ripristino interattiva:

proxmox-backup-client catalog shell "$PBS_SNAPSHOT" root.pxar \
  --repository "$PBS_REPOSITORY"

All'interno della shell, elencate le directory:

pxar:/ > ls

Esempio di output atteso:

etc
home
root
var

Selezionate un file:

pxar:/ > select /etc/hostname

Ripristinate i file selezionati:

pxar:/ > restore-selected /root/restored-from-pxar

Uscite dalla shell:

pxar:/ > exit

Passaggio 10: pulire la sessione di ripristino CLI

Smontate il file system del guest:

umount "$RESTORE_MOUNT"

Se avete attivato un gruppo di volumi LVM, disattivatelo dopo lo smontaggio:

vgchange -an ubuntu-vg

Rimuovete i mapping delle partizioni se li avete creati con partx:

partx -d "$LOOP_DEVICE"

Rimuovete il mapping del dispositivo loop PBS:

proxmox-backup-client unmap "$LOOP_DEVICE"

Output atteso: il comando non dovrebbe restituire alcun output quando il mapping del dispositivo loop viene rimosso correttamente.

Rimuovete le directory di mount temporanee se non servono più:

rmdir "$RESTORE_MOUNT"

Rimuovete le variabili d'ambiente sensibili:

unset PBS_PASSWORD
unset PBS_REPOSITORY
unset PBS_SNAPSHOT
unset PBS_ARCHIVE
unset LOOP_DEVICE

Avete ora ripulito l'ambiente di recupero locale.

Verifica

Verificate che i file ripristinati esistano:

ls -la "$RESTORE_TARGET"

Esempio di output atteso:

total 12
drwxr-xr-x  3 root root 4096 Jun  4 02:10 .
drwx------ 10 root root 4096 Jun  4 02:10 ..
-rw-r--r--  1 root root   12 Jun  4 01:00 hostname

Confrontate il contenuto dei file dove opportuno:

cat "$RESTORE_TARGET/hostname"

Esempio di output atteso:

app-vm-01

Confermate che la copia ripristinata si trovi al di fuori del file system di backup montato:

realpath "$RESTORE_TARGET"

Esempio di output atteso:

/root/restored-from-pbs

Verificate che dopo la pulizia non rimangano mapping loop di PBS:

losetup -a | grep pbs-loopdev || true

Output atteso: se il comando non restituisce alcun output, non rimane alcun mapping loop di proxmox-backup.

Annullamento delle modifiche

Questo tutorial non modifica il backup originale della VM né il datastore PBS. Il metodo tramite interfaccia web scarica i file solo sulla vostra workstation. Il metodo CLI crea mapping loop temporanei, punti di mount e copie locali dei file recuperati.

Per ripristinare lo stato iniziale dell'ambiente di recupero CLI, eseguite:

umount "$RESTORE_MOUNT"
proxmox-backup-client unmap "$LOOP_DEVICE"
rm -rf "$RESTORE_TARGET"
rmdir "$RESTORE_MOUNT"

Se avete attivato un gruppo di volumi LVM del guest, disattivatelo:

vgchange -an ubuntu-vg

Se avete aggiunto manualmente mapping di partizioni, rimuoveteli:

partx -d "$LOOP_DEVICE"

Risoluzione dei problemi

Il pulsante File Restore non è presente

Verificate di aver selezionato uno snapshot di backup su uno storage PBS e non su uno storage locale per ISO o immagini. Verificate inoltre che il vostro account disponga dei privilegi sufficienti per esplorare il contenuto dei backup.

Il file browser web non riesce a leggere il file system

Il file system del guest potrebbe non essere supportato, essere cifrato all'interno della VM, essere danneggiato oppure trovarsi all'interno di LVM, RAID o di un altro livello di storage. Provate il metodo CLI per ispezionare manualmente le partizioni con lsblk, blkid, vgscan e strumenti specifici per il file system.

proxmox-backup-client map fallisce con errori di autenticazione

Controllate la stringa del repository e le credenziali:

echo "$PBS_REPOSITORY"
proxmox-backup-client login --repository "$PBS_REPOSITORY"

Formato atteso del repository:

<PBS_USER>@<PBS_REALM>@<PBS_SERVER>:<DATASTORE>

Se utilizzate un namespace, aggiungete --ns ai relativi comandi proxmox-backup-client.

Il backup è cifrato

Fornite il file della chiave durante il mapping del backup:

proxmox-backup-client map "$PBS_SNAPSHOT" "$PBS_ARCHIVE" \
  --repository "$PBS_REPOSITORY" \
  --keyfile <PATH_TO_ENCRYPTION_KEY>

Esempio di output atteso:

/dev/loop0

I dispositivi di partizione non compaiono

Eseguite:

partx -a "$LOOP_DEVICE"
lsblk -f "$LOOP_DEVICE"

Se il disco usa LVM, eseguite:

vgscan --mknodes
lvs

Se il disco usa RAID software, ZFS all'interno del guest o la cifratura dell'intero disco, utilizzate gli strumenti di storage appropriati del guest e montate i file recuperati in sola lettura quando possibile.

Il mount fallisce con un tipo di file system errato

Controllate il tipo di file system:

blkid

Esempio di output atteso:

/dev/loop0p2: UUID="..." TYPE="ext4"

Quindi, se necessario, eseguite il mount con il tipo corretto:

mount -t ext4 -o ro /dev/loop0p2 "$RESTORE_MOUNT"

La copia dei file conserva una proprietà errata

Quando si copiano file come root da un file system guest montato, la proprietà può far riferimento a ID utente numerici del guest. Questo è normale. Usate rsync -a per preservare i metadati per un'ispezione successiva, oppure copiate senza preservare la proprietà se vi serve solo il contenuto dei file.

Conclusione

Avete ripristinato singoli file da un backup di VM su Proxmox Backup Server senza distribuire l'intera VM. Il metodo tramite interfaccia web è il percorso più rapido per la maggior parte delle attività di ripristino dei file da Proxmox Backup Server, mentre il metodo CLI offre un controllo preciso per il recupero avanzato dei file in Proxmox e per l'ispezione dei file system. Per le operazioni di routine, utilizzate prima il flusso File Restore di Proxmox VE e ricorrete a proxmox-backup-client map quando serve un recupero più approfondito da riga di comando a partire da un datastore PBS.

Passaggi successivi

Valutate di documentare la vostra procedura di recupero interna con i nomi esatti dei repository PBS, i namespace, gli ID delle VM, la posizione di archiviazione delle chiavi di cifratura e una checklist di validazione del ripristino. Potete inoltre testare regolarmente il ripristino a livello di file come parte della verifica dei backup, perché un backup è utile solo se è possibile recuperare i dati necessari.

Versione del documento: 1.0
Ultimo aggiornamento: giugno 2026
Responsabile: Team di documentazione tecnica