Guida: ripristinare un backup di Proxmox da BorgBackup

Questa guida è il seguito di Backup di Proxmox con BorgBackup e controllo via Borg-UI. Parte dal repository Borg già popolato dal backup giornaliero e spiega come recuperare i dati, dal singolo container fino alla perdita dell’intero host.

Un backup che non è mai stato ripristinato è solo un’ipotesi. Il consiglio numero uno di tutta la guida è: fai una prova di ripristino adesso, su un container piccolo, mentre non hai fretta.

Prima di cominciare

Nei comandi uso questi nomi, che vanno adattati al tuo caso:

Servono due cose: la passphrase del repository e, per il disaster recovery, anche la chiave del repository (se hai usato repokey è dentro il repository stesso, ma conviene avere comunque un’esportazione fuori dall’host).

Per comodità carica la passphrase nell’ambiente. Il backup la legge da un file riservato a root:

source /etc/borg-backup.env
export BORG_REPO=/mnt/nas-backup/borg-proxmox

Se la passphrase non è disponibile in quel file, esportala a mano con export BORG_PASSPHRASE='...' oppure lascia che Borg la chieda.

Il lock. Borg tiene un lock sul repository mentre qualcuno lo usa. Se lo script di backup sta girando (nel mio caso parte alle 08:00) il comando può restare in attesa o fallire. Aspetta che finisca. Usa borg break-lock solo se sei certo che nessun processo stia lavorando sul repository.

1. Capire cosa c’è nel repository

Elenca tutti gli archivi:

borg list "$BORG_REPO"

Solo i dump, o solo la configurazione:

borg list "$BORG_REPO" --glob-archives 'proxmox-*'
borg list "$BORG_REPO" --glob-archives 'pve-config-*'

Guarda il contenuto di un archivio e cerca il dump che ti interessa (l’ID 103 è un esempio):

borg list "$BORG_REPO"::proxmox-2026-11-06_08-00 | grep 'vzdump-.*-103-'

I percorsi nell’archivio non hanno lo slash iniziale: il dump /var/lib/vz/dump/vzdump-lxc-103-...tar.zst appare come var/lib/vz/dump/vzdump-lxc-103-...tar.zst. Copia il nome esatto dal risultato.

Le stesse informazioni si vedono anche in Borg-UI, aprendo il repository e sfogliando gli archivi: è comodo per trovare la data giusta prima di passare alla riga di comando.

2. Estrarre solo ciò che serve

Non estrarre un intero archivio: contiene tutti i dump e può pesare centinaia di GB. Estrai il solo file che ti serve.

Dove estrarre. Scegli un volume con spazio libero e non il filesystem root dell’host (pve-root): è piccolo e riempirlo manda in crisi Proxmox. Il NAS o un datastore capiente vanno bene.

Prima un controllo a vuoto, per verificare che il comando faccia quello che pensi:

borg extract --dry-run --list "$BORG_REPO"::proxmox-2026-11-06_08-00 \
    var/lib/vz/dump/vzdump-lxc-103-2026_11_06-08_00_01.tar.zst

Poi l’estrazione vera:

mkdir -p /mnt/nas-backup/restore
cd /mnt/nas-backup/restore

borg extract "$BORG_REPO"::proxmox-2026-11-06_08-00 \
    var/lib/vz/dump/vzdump-lxc-103-2026_11_06-08_00_01.tar.zst

Il file compare in /mnt/nas-backup/restore/var/lib/vz/dump/.

Alternativa: montare l’archivio. Se hai FUSE disponibile puoi montare l’archivio come se fosse una cartella e copiare ciò che serve:

mkdir -p /mnt/borg
borg mount "$BORG_REPO"::proxmox-2026-11-06_08-00 /mnt/borg
ls /mnt/borg/var/lib/vz/dump/
# ...copia quello che ti serve...
borg umount /mnt/borg

3. Ripristinare un container (LXC)

I dump dei container sono file vzdump-lxc-ID-...tar.zst.

pct restore 203 /mnt/nas-backup/restore/var/lib/vz/dump/vzdump-lxc-103-2026_11_06-08_00_01.tar.zst \
    --storage local-lvm

Punti importanti:

• Usa un ID nuovo (qui 203, mentre l’originale è 103). Così non sovrascrivi il container esistente e puoi verificare che il ripristino funzioni prima di sostituirlo.
• Prima di avviarlo controlla la rete: se il container usa un IP statico, avviare la copia insieme all’originale crea un conflitto di indirizzi. Tieni la copia spenta oppure cambia IP. L’opzione --unique di pct restore genera anche un nuovo indirizzo MAC per la copia.
• Se vuoi sostituire l’originale, fermalo e ripristina sullo stesso ID con --force, che sovrascrive il container esistente:

pct stop 103
pct restore 103 /mnt/nas-backup/restore/var/lib/vz/dump/vzdump-lxc-103-2026_11_06-08_00_01.tar.zst \
    --storage local-lvm --force

Avvia e verifica:

pct start 203
pct status 203

4. Ripristinare una macchina virtuale (QEMU)

I dump delle VM sono file vzdump-qemu-ID-...vma.zst.

qmrestore /mnt/nas-backup/restore/var/lib/vz/dump/vzdump-qemu-102-2026_11_06-08_00_01.vma.zst 202 \
    --storage local-lvm

Valgono le stesse regole del container: ID nuovo per provare (202), --force per sovrascrivere, attenzione a IP e MAC duplicati se avvii la copia mentre l’originale è acceso. Anche qui --unique assegna un MAC nuovo alla copia.

qm start 202
qm status 202

5. Ripristinare la configurazione di Proxmox

Gli archivi pve-config-* contengono /etc/pve, /etc/network/interfaces, /etc/hosts e /etc/hostname.

Estrai in una cartella temporanea e copia a mano solo i file che ti servono:

mkdir -p /root/pve-restore
cd /root/pve-restore
borg extract "$BORG_REPO"::pve-config-2026-11-06_08-00

ls etc/pve/lxc etc/pve/qemu-server
cat etc/pve/storage.cfg

Esempi di recupero mirato:

# configurazione di un container, se hai perso il file .conf
cp etc/pve/lxc/103.conf /etc/pve/lxc/103.conf

# definizione degli storage
diff etc/pve/storage.cfg /etc/pve/storage.cfg

Non estrarre direttamente sopra /etc/pve. È il filesystem di cluster di Proxmox (pmxcfs), non una normale cartella: sovrascriverlo con un blocco di file può rompere l’host. Confronta, copia solo il necessario, e non toccare i file che non conosci.

6. Disaster recovery: l’host è perso

Scenario: il disco di sistema è morto o l’host non si avvia, ma il NAS con il repository è intatto.

1. Reinstalla Proxmox VE sull’hardware (stessa versione maggiore, se possibile) con lo stesso hostname e lo stesso indirizzo IP.

2. Ripristina la rete e il montaggio del NAS. Ricrea il mount del NAS in /mnt/nas-backup con lo stesso percorso (NFS o CIFS, a seconda di come era configurato), perché lo script e gli storage si aspettano quel punto.

3. Installa Borg (apt install borgbackup). Controlla la versione con borg --version: il repository è in formato Borg 1.x, quindi serve una 1.x (meglio se uguale o più recente di quella usata per il backup). Borg 2 usa un formato diverso e non apre direttamente un repository 1.x.

4. Recupera passphrase e chiave. Con repokey la chiave è nel repository, quindi basta la passphrase. Se invece hai esportato la chiave:

   borg key import /mnt/nas-backup/borg-proxmox /percorso/borg-key-backup.txt
   

5. Verifica che il repository si apra:

   export BORG_PASSPHRASE='...'
   borg list /mnt/nas-backup/borg-proxmox | tail
   

6. Ricrea gli storage con gli stessi nomi usati dai backup (per esempio local-lvm), consultando storage.cfg dell’archivio pve-config-* più recente.

7. Ripristina VM e container uno per uno, come nelle sezioni 3 e 4, dal dump più recente, con gli ID originali (l’host nuovo non ha conflitti).

8. Recupera i file di configurazione che servono (sezione 5), senza sovrascrivere in blocco /etc/pve.

9. Reinstalla lo script di backup, il file /etc/borg-backup.env con permessi 600 e la riga di cron.

10. Controlla il primo backup successivo al ripristino, osservando il log e verificando che compaia il nuovo archivio.

7. Verificare periodicamente che i backup siano sani

Controlla l’integrità del repository (la struttura, non i dati) fuori dall’orario del cron:

borg check --repository-only "$BORG_REPO"

Con un repository grande (centinaia di GB) il controllo completo dei dati è lungo:

borg check --verify-data "$BORG_REPO"

Eseguilo ogni tanto, quando puoi lasciare il NAS occupato per ore. Entrambi i comandi tengono il lock, quindi non lanciarli mentre gira il backup.

La verifica più importante resta però la prova pratica: una volta ogni tanto ripristina un container piccolo con un ID nuovo, avvialo, controlla che funzioni, poi eliminalo:

pct destroy 203
rm -rf /mnt/nas-backup/restore

Checklist veloce

• Passphrase del repository fuori dall’host (password manager)
• Chiave del repository esportata con borg key export e conservata altrove
• Estrazione su volume con spazio libero, non sul root dell’host
• ID nuovo per le prove di ripristino
• Mai estrarre direttamente sopra /etc/pve
• Prova di ripristino eseguita almeno una volta
• borg check ogni tanto

Riferimenti utili

• Documentazione Borg: borg extract, borg mount, borg check, borg key
• Documentazione Proxmox: vzdump, pct restore, qmrestore