Restore Proxmox VE guests

A restore creates a new guest with a new VMID in the pool restow-restore. The original stays as it is. Restow never restores over an existing guest, never passes force to Proxmox VE, and the API token of the node can create and delete guests only in that pool. This is the same rule as for every other restore in Restow, see Backup and restore.

Restoring a whole guest is for administrators. A restore operator (the role “restore”) can read the restore points of a guest and browse and download files from them, see Files of a guest, but cannot restore a guest as a whole. Putting single files back into the running guest is not built (0.4.7): files come out as a ZIP.

Files instead of a whole guest

If you need one file or one folder, you do not have to restore the guest. Since 0.4.0, Servers & clients → File restore lists containers and VMs with a restore point, and Browse files on a restore point of the guest page opens it. Choose the files and download them as one ZIP. The file restore of VMs is a preview. See Files of a guest.

Restore a guest from Restow

Open the guest: Servers & clients → VMs & containers, or the Proxmox VE section of Servers & clients → Inventory, and choose the name of the guest.
In the table Restore points, choose Restore as a new guest on the restore point you want.

Fill in the dialog and choose Restore:

Field	What it means
Target storage (Proxmox VE storage id)	The storage that receives the disks of the new guest, for example `local-lvm`. It must exist on the target node, have room, and allow guest disks. The field starts with `local-lvm`: change it to what your node has.
Target node	The node that creates the guest. It starts as the node of the original. Another node of the cluster works if it runs `restow-pve` and has the target storage.
New ID (empty: next free one)	The VMID of the new guest, 100 or higher. Leave it empty and Proxmox VE picks the next free one.
Start after the restore	Off by default.

Restow says “Restore requested. The node starts it at its next check-in, usually within a minute.” Follow it in the Runs table of the guest: a run of the Type Restore that ends as Succeeded or Failed.

When the restore has finished, the new guest is in the pool restow-restore of Proxmox VE. Check it, and move it out of the pool once you accept it. A guest that stays in the pool is a guest that the node’s token may delete.

Current Proxmox VE passes the storage ID to the backup provider’s container restore before the info hash. The plugin of restow-pve before 0.4.6 failed on that with Can't use string ("restow") as a HASH ref: every restore and every boot test (Did not boot) of a container failed, Restore as a new guest included. VMs were not affected. The plugin accepts both forms since 0.4.6. It is installed with the restow-pve update, which reloads the Proxmox VE daemons: the server offers it after its own update and idle nodes update themselves, or run restow-pve update as root (Update and remove nodes). Until a node is updated, container restores on it keep failing as before. The fix was tested with the Perl tests of the plugin (with and without the storage ID), not against a real Proxmox VE node before the release.

A restored guest has the configuration of the original, apart from the MAC addresses of a VM, which Proxmox VE makes new. An IP address that is set inside the guest is the same as the original’s. Leave Start after the restore off, and do not start the restored guest on the same network while the original runs, unless you have changed that.

Which restore points can be restored

Every restore point can be restored on its own, whatever its type, see Restore point types. That includes the restore points of a guest that was excluded from backup (since 0.4.7): excluding it stops new backups, it does not touch what exists. When ransomware detection marks the newest restore point of the guest as suspicious, the page of the guest points to the newest one without findings. A restore point with gaps (a container backup that restic could not read completely) restores what it holds. A restore point of an earlier backup chain of a container, whose repository is gone, is Not available (since 0.4.2) and cannot be restored, see New backup chain and Reset repository. A privileged container cannot be restored: Proxmox VE refuses to restore it from a backup interface, and the dialog says so (“Proxmox VE cannot restore privileged containers from a backup interface.”). Restore such a container by hand as an unprivileged one.

What happens on the node

The node starts the restore at its next report, through the Proxmox VE API with the token that stays on the node. Proxmox VE does the restore itself, and the storage plugin supplies the data:

A VM. For each disk, restow-pve starts a small NBD server on the node that serves the disk of the restore point, and Proxmox VE reads it with qemu-img convert into the target storage. Zero blocks stay holes, so the new disk stays sparse. The configuration and the firewall configuration of the guest come from the restore point. The restore point is read from the Restow server, block by block.
A container. restow-pve unpacks the restic snapshot into a temporary folder on the node, and Proxmox VE copies it into the new root file system. The folder is /var/tmp/restow-pve by default (change it with restow-pve config --restore-tmp), so it needs free space for the files of the container. The new container is created as an unprivileged one.

A node can refuse restores for itself: with restow-pve config --allow-restores=false, Restow answers “Restores are off on this node”, see Update and remove nodes.

Restore from the Proxmox VE web interface

A restore point is also a backup on the storage restow of Proxmox VE. In the Proxmox VE web interface, the storage restow has a Backups tab that lists the restore points. Show configuration reads the configuration of the guest from the restore point, and Restore restores it through the same plugin, with your own Proxmox VE permissions, not those of the node’s token. The run shows up in Restow as started in Proxmox VE. Remove is refused (“retention is managed in Restow”): restore points are removed by retention in Restow only.

Restore without Restow

If the Restow server is gone, the data is still readable:

VM disks. The standalone tool restow-restore reads the manifest of a restore point and the chunk store directly, and writes each disk of the VM as a sparse raw image, disks/<device>.raw, with the zero blocks as holes. Every block is checked against the SHA-256 in the block map, and a disk with a block that does not match is not written. It needs the storage and the master key, see Standalone restore. You attach a raw image to a new VM yourself.
Containers. A container’s restore points are a plain restic repository under pve-guests/<guest id>/ in the tenant’s primary repository, which restic itself can open with the repository password. The password lies next to the repository, sealed with the tenant key, as restow-repository-password.json. In 0.4.7, restow-restore endpoint-password looks only in endpoints/, so it does not open that password for you.

Restore checks

A restore check proves that a restore point can be read back, without creating a guest: it runs weekly for the newest restore point of every guest, and on demand with Check now. The optional monthly restore check of a job restores a guest into restow-restore and deletes it again. See Backup jobs and protection.

A boot test goes further: it restores a restore point as a temporary guest with its network cut, starts it and waits for the guest agent, then destroys it again. It is off until a job turns it on, and Boot test now on a restore point asks for one by hand. See Boot tests.

If a restore fails

See Troubleshooting.