[TUTORIAL] Restore a file from a vzdump/vma backup on the CLI

[UdoB]

Preface​

While I am basically sure this is documented somewhere I was not able to find a compact guide. And I was never in a situation where this was necessary... yet. What I had found is https://pve.proxmox.com/wiki/VMA and the man-pages of the required commands, but no “walk-through”.

Precondition​

We have lost a PVE installation but we have backups of the VMs, created by the standard procedure from inside the PVE Webgui and written into a Directory Storage. No PBS involved. Now we need to extract an important data file from that backup.

For this example my backup consists of these files:

backuptest/dump# ls -Al
total 2750814
-rw-r--r-- 1 root root       2004 Dec  3 08:14 vzdump-qemu-2055-2024_12_03-08_14_16.log
-rw-r--r-- 1 root root 2814934269 Dec  3 08:14 vzdump-qemu-2055-2024_12_03-08_14_16.vma.zst
-rw-r--r-- 1 root root         24 Dec  3 08:14 vzdump-qemu-2055-2024_12_03-08_14_16.vma.zst.notes

For this article I will stay in this folder; for doing this on a production server I would copy the large file to another working directory.

Remove compression​

Make sure to have enough space available; in my case the size nearly triples and additionally the original is not deleted:

backuptest/dump# zstd -d vzdump-qemu-2055-2024_12_03-08_14_16.vma.zst 
vzdump-qemu-2055-2024_12_03-08_14_16.vma.zst: 8542863872 bytes                 

backuptest/dump# ls -Al
total 6835230
-rw-r--r-- 1 root root       2004 Dec  3 08:14 vzdump-qemu-2055-2024_12_03-08_14_16.log
-rw-r--r-- 1 root root 8542863872 Dec  3 08:14 vzdump-qemu-2055-2024_12_03-08_14_16.vma
-rw-r--r-- 1 root root 2814934269 Dec  3 08:14 vzdump-qemu-2055-2024_12_03-08_14_16.vma.zst
-rw-r--r-- 1 root root         24 Dec  3 08:14 vzdump-qemu-2055-2024_12_03-08_14_16.vma.zst.notes

Extract vma​

SHOWSTOPPER: how to get the vma binary onto this machine with minimal effort? SKIPPED for now as the “pve-qemu-kvm”-package hast too many dependencies for my machine to pull in. Hoping for comments to solve this issue... ;-)

backuptest/dump# vma extract vzdump-qemu-2055-2024_12_03-08_14_16.vma  extractedfiles 
DEVINFO extractedfiles/tmp-disk-drive-scsi0.raw 12884901888

backuptest/dump# cd extractedfiles/ ; ls -Al
total 4083705
-rw-r--r-- 1 root root 12884901888 Dec  3 08:24 disk-drive-scsi0.raw
-rw-r--r-- 1 root root         606 Dec  3 08:24 qemu-server.conf

We could look into qemu-server.conf to see the original configuration of the VM. This file allows to rebuild a new compatible/identical VM.

Partitions​

Now we have the actual disk as a single file. It is not directly mountable because a disk contains a partition table. Probably there is more than one way to to do this. I prefer using "kpartx” which is not installed by default:

/backuptest/dump/extractedfiles# apt install kpartx

Take a look into the file:

backuptest/dump/extractedfiles# kpartx -l disk-drive-scsi0.raw 
loop0p1 : 0 2048 /dev/loop0 2048
loop0p2 : 0 25159680 /dev/loop0 4096

To create the required loop devices:

backuptest/dump/extractedfiles# kpartx -a disk-drive-scsi0.raw

There is no output. We’ll find the result of that operation here:

backuptest/dump/extractedfiles# ls -al /dev/mapper/loop*
lrwxrwxrwx 1 root root 7 Dec  3 08:39 /dev/mapper/loop0p1 -> ../dm-2
lrwxrwxrwx 1 root root 7 Dec  3 08:39 /dev/mapper/loop0p2 -> ../dm-3

Note that “loop0” was chosen automatically. We could have taken another one if we wanted to, see man kpartx.

mount​

backuptest/dump/extractedfiles# mkdir /mnt/extractedpartition
backuptest/dump/extractedfiles# mount /dev/mapper/loop0p2 /mnt/extractedpartition/

Now we can access and copy all the files with whatever tools we want. For example the password file from the VM is this:

backuptest/dump/extractedfiles# ls -Al /mnt/extractedpartition/etc/passwd
-rw-r--r-- 1 root root 1636 Oct 31 10:32 /mnt/extractedpartition/etc/passwd

Clean up​

backuptest/dump/extractedfiles# umount /mnt/extractedpartition 
backuptest/dump/extractedfiles# losetup -D
backuptest/dump# rm -r extractedfiles
backuptest/dump# rm vzdump-qemu-2055-2024_12_03-08_14_16.vma

Perhaps there are much more easy or compact methods than this manually crafted way? Please leave a comment. Anyway it is not bad to have one more approach available as a possible option to access my data