Proxmox BS: File-Level Restore from VM backup

Introduction

This tutorial explains how to use Proxmox Backup Server for file-level restore from a VM backup without deploying the entire virtual machine. You will learn how to retrieve individual files through the Proxmox backup file browser in the Proxmox VE web interface and how to perform command-line Proxmox file recovery with proxmox-backup-client. This workflow is useful when you need to restore individual files Proxmox backups contain without performing a complete VM backup restore.

Target audience: Intermediate system administrators
Estimated time: 20-40 minutes
End goal: By the end of this tutorial, you will be able to restore specific files from a Proxmox Backup Server VM backup without restoring the full VM.

Prerequisites

Before you begin, make sure you have:

• A working Proxmox VE host with a configured Proxmox Backup Server storage.
• Proxmox Backup Server 3.x or 4.x with an existing datastore.
• A completed VM backup stored in the PBS datastore.
• Access to the Proxmox VE web interface with permissions to browse backups and restore files.
• Shell access to the Proxmox VE host for the CLI method.
• The proxmox-backup-client command available on the Proxmox VE host.
• Root shell access for the CLI mapping method, because loop device mapping and filesystem mounting require elevated permissions.
• The encryption key file if the VM backup uses client-side encryption.
• Basic knowledge of Linux filesystems, mount points, and Proxmox VE backup storage.

Step 1: Understand File-Level Restore Options

Proxmox Backup Server stores Proxmox VE virtual machine backups as block-level disk image backups. This means a VM backup usually contains files such as drive-scsi0.img.fidx, qemu-server.conf.blob, and client.log.blob, not a normal directory tree.

For granular file recovery Proxmox VE workflows, you have two practical options:

• Use the Proxmox VE web interface to browse the backup snapshot and download files.
• Use proxmox-backup-client map to map a VM disk image from the backup to a local loop device, then mount the guest filesystem read-only.

The Proxmox VE File Restore button opens a file browser for backup contents. The proxmox-backup-client map command maps a VM backup drive image to a local loopback device and should be followed by unmap after recovery.

Step 2: Restore Individual Files Through the Proxmox VE Web Interface

Use this method when you want the simplest way to retrieve specific files without deploying the entire VM.

Open the Backup View

1. Log in to the Proxmox VE web interface.
2. In the left navigation tree, select the VM.
3. Open the Backup tab.
4. Select the Proxmox Backup Server storage from the storage selector if your environment has multiple backup storages.

You should see a list of available backup snapshots for the selected VM.

Open the Proxmox Backup File Browser

1. Select the backup snapshot that contains the file you need.
2. Click File Restore.
3. Wait for Proxmox VE to open the backup file browser.
4. Expand the VM disk that contains the guest operating system or data volume.

You should now be browsing backup snapshots through the Proxmox VE interface. This view supports the Proxmox Backup Server restore files workflow, allowing you to recover selected data without performing a full VM backup restore.

Download the Required File

1. Navigate to the directory that contains the file.
2. Select the file.
3. Click Download.
4. Save the file to your workstation.

You should receive the selected file through your browser. This completes a browser-based file-level restore from the VM backup.

Step 3: Prepare the CLI Environment

Use this method when restoring data from PBS datastore backups through the command line.

Define Recovery Variables

Run the following commands on the Proxmox VE host. Replace the placeholders with values from your environment.

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>"

Example values:

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..."

The variables define the PBS repository, the VM backup snapshot, the disk archive to map, the temporary mount point, and the local recovery target. Set the PBS_PASSWORD and PBS_FINGERPRINT environment variables. Retrieve the certificate fingerprint on the Proxmox Backup Server by running proxmox-backup-manager cert info.

During the first connection, the login command interactively asks you to confirm the certificate fingerprint and enter the password. Without these variables, automated commands fail with certificate validation failed when the fingerprint is missing or no password input mechanism available when no password is provided.

Log In to Proxmox Backup Server

Run the login command:

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

Expected output:

Password:

Enter the password for the PBS user. If authentication succeeds, the client stores a temporary ticket.

Step 4: Identify the VM Backup Snapshot and Disk Archive

List backup groups in the PBS repository:

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

Expected output example: backup table.

List snapshots for the VM group:

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

Expected output example: snapshot table.

List files in the selected snapshot:

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

Expected output example:

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

Step 5: Map the VM Backup Disk to a Loop Device

Create the restore directories:

mkdir -p "$RESTORE_MOUNT" "$RESTORE_TARGET"

Map the VM disk image from PBS:

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

Expected output example:

/dev/loop0

Save the returned loop device in a variable:

export LOOP_DEVICE="/dev/loop0"

The map command maps a VM backup drive image to a local loopback device.

Step 6: Inspect the Mapped Disk

List the partitions and filesystems:

lsblk -f "$LOOP_DEVICE"

Expected output example:

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

If partitions do not appear, ask the kernel to read the partition table:

partx -a "$LOOP_DEVICE"

Then check again:

lsblk -f "$LOOP_DEVICE"

You should now see partition devices such as /dev/loop0p1 and /dev/loop0p2.

Step 7: Mount the Guest Filesystem Read-Only

Select the partition that contains the files you need. In this example, the Linux root filesystem is /dev/loop0p2.

Mount it read-only:

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

Expected output: The command should return no output when the mount succeeds.

Check the mounted filesystem:

ls "$RESTORE_MOUNT"

Expected output example:

bin
boot
etc
home
root
usr
var

You are now using the command line to restore individual files Proxmox backups contain, without restoring the entire virtual machine.

Mount an LVM Volume If the Guest Uses LVM

If lsblk -f shows LVM2_member, scan for volume groups:

vgscan --mknodes

Expected output example:

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

Activate the volume group:

vgchange -ay ubuntu-vg

List logical volumes:

lvs

Expected output example:

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

Mount the logical volume read-only:

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

You should now be able to browse the restored guest filesystem under $RESTORE_MOUNT.

Step 8: Copy Specific Files Out of the Backup

Create a local directory for recovered files:

mkdir -p "$RESTORE_TARGET"

Copy one file:

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

Expected output: The command should return no output when the file is copied successfully.

Copy a directory:

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

Expected output: The command should return no output when the directory is copied successfully.

Verify the copied files:

find "$RESTORE_TARGET" -maxdepth 3 -type f

Expected output example:

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

Step 9: Restore Files from a File-Based PBS Backup with pxar

This step is optional for VM file-level restore, but it is useful when the backup snapshot contains a file archive such as root.pxar.

List files in the snapshot:

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

Expected output example:

catalog.pcat1.didx
root.pxar.didx

Open the interactive restore shell:

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

Inside the shell, list directories:

pxar:/ > ls

Expected output example:

etc
home
root
var

Select a file:

pxar:/ > select /etc/hostname

Restore selected files:

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

Exit the shell:

pxar:/ > exit

Step 10: Clean Up the CLI Restore Session

Unmount the guest filesystem:

umount "$RESTORE_MOUNT"

If you activated an LVM volume group, deactivate it after unmounting:

vgchange -an ubuntu-vg

Remove partition mappings if you created them with partx:

partx -d "$LOOP_DEVICE"

Unmap the PBS loop device:

proxmox-backup-client unmap "$LOOP_DEVICE"

Expected output: The command should return no output when the loop device is unmapped successfully.

Remove temporary mount directories if you no longer need them:

rmdir "$RESTORE_MOUNT"

Unset sensitive environment variables:

unset PBS_PASSWORD
unset PBS_REPOSITORY
unset PBS_SNAPSHOT
unset PBS_ARCHIVE
unset LOOP_DEVICE

You have now cleaned up the local recovery environment.

Verification

Verify that the restored files exist:

ls -la "$RESTORE_TARGET"

Expected output example:

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

Compare file contents where appropriate:

cat "$RESTORE_TARGET/hostname"

Expected output example:

app-vm-01

Confirm that the restored copy is outside the mounted backup filesystem:

realpath "$RESTORE_TARGET"

Expected output example:

/root/restored-from-pbs

Check that no PBS loop mappings remain after cleanup:

losetup -a | grep pbs-loopdev || true

Expected output: If the command returns no output, no proxmox-backup loop mappings remain.

Reverting Changes

This tutorial does not modify the original VM backup or the PBS datastore. The web interface method downloads files to your workstation only. The CLI method creates temporary loop mappings, mount points, and local recovered file copies.

To revert the CLI recovery environment, run:

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

If you activated a guest LVM volume group, deactivate it:

vgchange -an ubuntu-vg

If you added partition mappings manually, remove them:

partx -d "$LOOP_DEVICE"

Troubleshooting

File Restore Button Is Missing

Confirm that you selected a backup snapshot on PBS storage, not a local ISO or image storage. Also confirm that your account has enough privileges to browse backup content.

The Web File Browser Cannot Read the Filesystem

The guest filesystem may be unsupported, encrypted inside the VM, damaged, or located inside LVM, RAID, or another storage layer. Try the CLI method so you can inspect partitions manually with lsblk, blkid, vgscan, and filesystem-specific tools.

proxmox-backup-client map Fails with Authentication Errors

Check the repository string and credentials:

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

Expected repository format:

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

If you use a namespace, add --ns to the relevant proxmox-backup-client commands.

The Backup Is Encrypted

Provide the key file when mapping the backup:

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

Expected output example:

/dev/loop0

Partition Devices Do Not Appear

Run:

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

If the disk uses LVM, run:

vgscan --mknodes
lvs

If the disk uses software RAID, ZFS inside the guest, or full-disk encryption, use the appropriate guest storage tools and mount recovered files read-only whenever possible.

Mount Fails with Wrong Filesystem Type

Check the filesystem type:

blkid

Expected output example:

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

Then mount with the correct type if needed:

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

The File Copy Preserves Wrong Ownership

When copying files from a mounted guest filesystem as root, ownership may reference numeric user IDs from the guest. This is expected. Use rsync -a to preserve metadata for later inspection, or copy without preserving ownership if you only need file contents.

Conclusion

You restored individual files from a Proxmox Backup Server VM backup without deploying the entire VM. The web interface method is the fastest path for most Proxmox Backup Server restore files tasks, while the CLI method gives you precise control for advanced Proxmox file recovery and filesystem inspection. For routine operations, use the Proxmox VE File Restore workflow first, and use proxmox-backup-client map when you need deeper command-line recovery from a PBS datastore.

Next Steps

Consider documenting your internal recovery procedure with the exact PBS repository names, namespaces, VM IDs, encryption key storage location, and restore validation checklist. You can also test file-level restore regularly as part of backup verification, because a backup is only useful if you can recover the data you need.

Document Version: 1.0
Last Updated: June 2026
Owner: Technical Documentation Team