Files of a guest

A restore of a guest creates a whole new guest, see Restore. Often you need less: one config file, one folder, a document someone deleted. For that, the restore points of a guest can be browsed like the restore points of a machine, and files and folders are downloaded as one ZIP.

Where to find it

Servers & clients → File restore. Every container with a restore point is listed in the group Proxmox VE containers, every VM with a restore point in the group Proxmox VE VMs, which carries the badge Preview. The groups sit next to the machines. Choose a guest, then a restore point on the timeline, and browse its folders. A restore point counts whether a job made it or someone started the backup by hand, from Restow or from Proxmox VE.
The page of the guest, opened from VMs & containers or the inventory: each restore point has Browse files, which opens File restore with that guest chosen. The page offers it for restore points that can be browsed (a VM restore point that holds only the EFI variables and the TPM state has nothing to browse).

Tick files and folders, then choose Download as ZIP. A ticked folder includes everything inside it. Restow prepares the ZIP, and your browser starts the download.

The page says what a restore point contains. For a container that is the whole container (/) and every volume mount point that vzdump includes, and the paths are the container’s own: /opt/paperless/... in the browser is /opt/paperless/... inside the container. Bind mounts and device mounts are not part of a vzdump backup, so they are not there.

Files of a VM (Preview)

The folders at the top of a VM restore point are the readable file systems of the VM’s disks, each named after where it lies:

Folder	What it is
`scsi0`	A disk without a partition table.
`scsi0-p2`	Partition 2 of the disk `scsi0` (GPT, or MBR including logical partitions).
`vg0-root`	The logical volume `root` of the LVM volume group `vg0`, assembled from the VM’s disks.

The disks for the EFI variables and the TPM state are left out. What the server cannot read is listed on the page with the reason (for example BitLocker, swap, a RAID or thin logical volume, or no file system it knows).

Readable	Not readable
Partitions of GPT and MBR disks, and linear LVM logical volumes.	btrfs, ZFS, ReFS.
ext2, ext3 and ext4, with the journal replayed in memory.	LVM thin, RAID, striped, cache and snapshot volumes.
XFS.	BitLocker and LUKS.
NTFS and FAT12/16/32 (the EFI partition).	NTFS-compressed files and EFS files. Deduplicated files and other reparse points are listed and never followed, and so are symbolic links.

A file that cannot be read does not stop the download. It is named, with the reason, in _not-restored.txt inside the ZIP.

How the files are read

The Restow server reads the files. Nothing runs on the Proxmox VE node for this, and nothing is mounted, neither on the server nor on the node.

A container. The server opens the restic repository of the container, pve-guests/<guest id>/, with the password it keeps for it. The password never reaches your browser. The ZIP is streamed and not held in memory or on disk.
A VM. The server reads the disks of the restore point from its block maps in the chunk store of the tenant, checks every 4 MiB block against its SHA-256 and hands the bytes to a reader in a short-lived, restricted child process. The reader parses partition tables, LVM, ext, XFS, NTFS and FAT in user space. There is one child per page of a folder or per download, and it is stopped afterwards. It has no keys, no database address and no storage credential, may not start other processes and has a limited memory, time (60 seconds per step) and amount of disk to read. Data of a guest never reaches a file system driver of the kernel, because a crafted file system is a known way to attack one.

A page of a container can answer “The backup data is busy”: the server does not read a container repository while retention or the weekly check works on the same one. Try again in a moment. A running backup does not block it.

Who may do it, and what is recorded

Administrators of the tenant and restore operators (the role “restore”) browse and download. A restore operator reads the Proxmox VE overview and the restore points of a guest, and may browse and download files of container and VM restore points. A restore operator may not restore a whole guest, start a boot test, back up, change jobs or nodes, or read the repository password. See Team and roles.
Every page of a folder that is read and every download that is started is written to the audit log, with the person as actor: pve.snapshot.browsed and pve.snapshot.downloaded. VMs use the same two actions as containers. The audit log words them for containers (“Files of a container restore point browsed”); the entry of a VM carries kind: "vm" in its details.
A prepared download can be started once, within ten minutes, by the person who prepared it. The address alone opens nothing. If it expires or was used, prepare the ZIP again.

What it does not do

It does not put files back into the running guest (0.4.7). Files are downloaded as a ZIP. To get a whole guest back, restore it as a new guest, or copy the files out of the ZIP yourself.
It is no replacement for a restore test. A browsed file proves that the file could be read from the restore point. Whether a guest boots is what a boot test tells you.
It does not read what is not in the backup. A container backup holds what vzdump includes. A VM backup holds the disks that are part of the backup.

What was tested

The release notes of 0.4.0 list file restore of VMs as tested against simulated services only, not yet against a real Proxmox VE cluster. That includes the readers for ext, XFS, NTFS, FAT, partition tables and LVM, which the test suite exercises with small file system images made for it. No release up to 0.4.2 reports a test on a Proxmox VE host. This is why VMs carry the Preview badge. Try it on a test guest, and compare files with the originals, before you depend on it.

If it does not work

Symptom	Cause and fix
The guest is not in the list.	Only guests with a restore point are listed, and only administrators and restore operators of the tenant see the page. Check the restore points on the page of the guest.
The backup data is busy	Retention or the weekly check works on the repository of that container. Try again in a moment.
A folder of a VM is missing at the top.	The file system is not readable, or it is on a disk the page leaves out. The page lists what it could not read, with the reason.
A file is missing from the ZIP.	It is named in `_not-restored.txt` with the reason.
The download does not start.	A prepared ZIP starts once and for ten minutes. Prepare it again.