← All features

Proxmox VE backup (preview)

By Lucas Flores, IT Systeme Flores UG. Last updated 2026-10-29

Restow backs up the virtual machines and containers of Proxmox VE 8.4 and newer through Proxmox's Backup Provider API. It is a preview, available since 0.3.1 and in every edition, Community included. It is not yet recommended as your only backup: the limits are listed below, next to the feature.

How VMs and containers are backed up

VM disks go over NBD with dirty bitmaps, so only changed 4 MiB blocks are uploaded. Containers go through restic. The backups are stored in a repository you choose, see storage.

The node side has two parts: a storage plugin shim, which is a separate work under AGPL-3.0-or-later, and the helper restow-pve, which is Apache-2.0. Guests count in recovery readiness, in warnings and in overdue alerts (backup.overdue), unless an admin excluded them on purpose (since 0.4.7, see excluding a guest).

Restore

A restore creates a new VMID in the pool restow-restore. The general restore rules are on the restore page.

Restoring a container works on current Proxmox VE since 0.4.6: before, a container restore, a boot test of a container and "Restore as a new guest" of a container failed on current Proxmox VE with Can't use string ("restow") as a HASH ref, because it passes the storage ID to the backup provider before the info hash; VMs were not affected. The fix is in the plugin of restow-pve: update restow-pve on every node before you rely on container restores or boot tests. For container restore points that read "Did not boot" or have a failed restore check from before 0.4.3, run "Boot test now" or "Check now" once the node is updated.

Connecting a node

Since 0.3.2, one command connects a node, with the enrollment token in it. The node installer sets up the user restow@pve, the roles and the restore pool itself, creates its own API token, checks its privileges before it installs anything and picks the thin storage for fleecing by itself. Instead, an existing Proxmox VE API token can be used. Restow keeps its id and secret encrypted only until the node has enrolled with them, or the enrollment token expires, and hands them to that node once. "Command for another node" adds the next node.

Since 0.4.0, restow-pve updates itself, while no backup or restore runs; restow-pve update on the node does it by hand. Since 0.4.2 the server's own update brings the nodes along, and since 0.4.3 "Update nodes and agents now" starts that step by hand, see nodes follow a server update.

Nodes, VMs and containers in the inventory

Since 0.3.3, every Proxmox VE node shows in Servers & clients, Inventory, as a row you can expand. It carries the node's online state and counts: protected, failed, no job, not backed up yet and, since 0.4.7, excluded ("Excluded: N"). Expanded, each VM and container shows its status, its backup job and its backup state, and, when the last backup failed, why, linked to the guest's own page. The inventory is for administrators, once a cluster is connected. The page VMs & containers says "Waiting for the node" once a backup has been handed out and "Backup running" while it runs.

Since 0.3.4, backups of unprivileged containers on ext4 no longer fail on the lost+found folder, and a container backup that restic could not read completely (exit code 3) keeps its restore point and names the unreadable items.

What each backup contains

Since 0.3.5, VMs & containers and the inventory have a Backup column. It says what the newest restore point contains and what its run added, for example "9.4 GB in the backup, +2.5 MB new", and showed the first backup on hover. Since 0.4.7 the inventory's column shows two more lines as text in the guest's row, not only on hover, so they can be read and copied: the size of the guest's first backup ("First backup on <date>: <size> stored") and what a follow-up backup adds on average ("Average per follow-up backup: +<size> (last N backups)"). The former Size column is now called Disk. On a guest's own page, restore points show their type (first backup, incremental or full read), what they contain and what they added. The first backup of a container's new backup chain is called "First backup", not "Incremental", since 0.4.6. Since 0.4.3 the column in VMs & containers reads differently, see tabs, filters and a detail panel.

A container backup that restic could not read completely shows as "Succeeded with gaps" ("Last backup incomplete" on the guest's page), with the number of unreadable items, and counts as "Incomplete" in the inventory.

"Back up now" and restore say that the node starts the task at its next check-in. A second click says that a backup is already waiting, and the pages refresh every 5 seconds while a guest waits for its node or backs up.

Protecting guests from the inventory

Since 0.3.6, you can protect guests without leaving the inventory. In an expanded node, every VM and container has its backup job as a choice: an existing job, "No backup job" or "New job…". "Back up now" starts a backup of that guest.

To act on several guests at once, tick them one by one, tick the box in the header to take all guests of the node, or use "Select them" next to "N VMs and containers have no backup job" to take every guest without a job in one click. Then add the selection to a job ("Add to job…") or choose "Back up now" to back the guests up together. "New job…" opens the job dialog and puts the selection into the new job. The node starts a requested backup at its next check-in, usually within a minute.

The inventory's protection column is now called "Protection"; it used to share the heading Backup with the column that shows what the newest restore point contains.

Excluding a guest from backup on purpose

Many guests of a cluster are not meant to be backed up, such as test VMs or guests that are backed up elsewhere. A guest in no backup job counts as "No backup job" in the overviews and keeps the tenant from green, unless an admin excluded it on purpose (since 0.4.7). Tenant administrators and the administrators of the provider team may exclude a VM or container: "Exclude from backup" is on the guest's page and, for a selection of a node's guests, in the inventory; "Include again" takes it back, on the page and in the guest's inventory row. Nothing is excluded automatically. Like the rest of Proxmox VE backup, this is a preview, in every edition, Community included.

• No job backs it up, not even the job for all guests, and the recommended job leaves it out. Its own job stays recorded, so including it again restores what it had. Excluding withdraws its queued backups; "Back up now" and putting the guest into a job are refused until it is included again.
• It counts nowhere as unprotected: not in the overviews, recovery readiness, warnings, backup.overdue, the statistics or the provider view (nor in "N VMs and containers have no backup job"), and it never keeps a tenant from green. The guest counts report it as excluded, and the inventory shows "Excluded: N" per node. In VMs & containers it reads "Excluded" (grey, never a problem) and has a state filter of its own.
• Its restore points stay. They remain restorable, and retention treats them as before. The weekly restore check of its newest restore point goes on; the job's monthly restore check and boot tests no longer cover it.

The change is written to the audit log as pve.guest.excluded; the API route is PUT /api/v1/pve/guests/:id/excluded. restow-pve needs no update for it.

VMs & containers: tabs, filters and a detail panel

Since 0.4.3, VMs & containers has three tabs with counts: Guests (the default), Backup jobs and Nodes.

• Search and filters. The guests table searches ID and name and filters by node, kind (VM or container), backup job (also "No backup job") and state. "Problems only" shows the guests that need a look: a failed run, warnings or gaps, a restore check that failed or could not run, a wait for a disconnected or paused node, or no backup at all. Columns sort (ID, name, node, last backup, backup size, state), pages hold 25 to 250 guests, and the table says how many guests the filters leave. Tab, search, filters, order, page and the open guest live in the address, so a link opens the same view.
• One state per row. A row shows one state badge, chosen by priority, with a small progress bar while its backup runs or "+N" when further states apply. Green stays reserved for proof: only a restore check that read the newest restore point back is green, and a backup that merely succeeded is a plain "Backed up".
• Detail panel. A click on a row (or its name) opens a panel with every state of the guest, the complete error and warnings of the last run in a scrollable block that can be copied, the restore check with what it found, the sizes, the backup job, the newest runs and the actions: back up now, stop, withdraw, check now and open the guest's page.
• The Backup column reads for example "First: 32 GB on Oct 3 · Last: +210 MB": how large the first (full) backup was and what the last follow-up backup added. What the newest restore point contains is in the tooltip, and the panel shows the new data of each of the last 30 backups as small bars.
• No jumping. The guest and job tables keep fixed column widths and one row height, long texts are cut to one line, and "Back up now", "Stop", "Withdraw" and "Stopping…" share one button size, so the page no longer moves while backups run. Error texts no longer show in red under a row, and warnings are no longer only in a tooltip.

The Nodes tab shows each node's heartbeat, its restow-pve version with "Update to …" when the server offers a newer release, its Proxmox VE version, how many guests it has, its queue and its problems. Queue control and revoking are in the row menu. The note that the Proxmox VE host itself is not backed up (its own files need the Restow agent on the host) is one line on this tab and can be hidden.

Progress, run log and jobs

Since 0.4.0, VMs & containers, the inventory and a guest's page show the progress of a running backup, for example "34% · 3.2 GB of 9.4 GB · 85 MB/s". It needs restow-pve 0.4.0 on the node; since 0.4.1 a backup on an older node says that progress needs restow-pve 0.4.0 on that node and which version the node runs, instead of "No progress reported yet" for its whole run. The helper's own lines now reach the log that Restow keeps for the run: the run id, what restic added, what it could not read and the commit of the restore point. A backup that succeeded with gaps names the first 20 items restic could not read.

Proxmox VE jobs are in Servers & clients, Jobs, next to the machine jobs, with a Type column: the guests of each job, the schedule, the last and next run, "2 of 5 guests done" while a round runs, and a backup started by hand as a row "Manual backup" until it ends. "New job" is a menu with one entry per type. Next to every "no job" notice, "Create recommended job" shows a preview of what the click creates or adds to, then makes one job per kind (for Proxmox VE: one job, daily at 22:00 in snapshot mode); a second click adds to the same job instead of making another. It is for administrators and recorded in the audit log. A guest's page also shows the average that a follow-up backup adds.

Since 0.4.2, a Proxmox VE job's schedule offers the cadences of a mail job: every few hours, daily, on chosen weekdays, monthly or a cron expression, in a time zone, and not more often than hourly. A backup that vzdump ends with warnings (for example "TASK WARNINGS: 1") after its restore point was committed counts as "Succeeded with warnings", shown in amber, not as failed; restow-pve 0.4.2 also stopped asking vzdump for notes, which is what produced those warnings.

A backup that runs while Restow is updated no longer fails: the node (restow-pve 0.4.0) keeps trying for five minutes, where it gave up after about 30 seconds before, and a backup run whose end never reached the server is closed once the node no longer lists it, instead of staying "running" for 48 hours. restow-pve now updates itself: it checks two minutes after its start (since 0.4.1) and then every six hours, and updates while no backup or restore runs; restow-pve update does it by hand. Older helpers keep working without progress, without the five-minute retry and without the list of active runs.

Stopping a backup

Since 0.4.2 a backup can be stopped from the web app, without SSH on the node. Whoever may start a backup may stop one, every stop asks first, and it is written to the audit log.

• Stop backup is in the VMs & containers table, on the guest's page and in the run drawer. A backup that still waits for its node is withdrawn at once ("Withdraw"): the node never sees it, and History shows a run "Cancelled by <user>". One the node already got, or that is running, gets a cancel request, and the page says "Cancelling…" until the node has stopped it.
• How the node stops it. restow-pve 0.4.2 keeps its heartbeat going while a backup runs, every 15 seconds, and gets the cancel order with it. For a backup Restow asked for, the node stops the vzdump task through the Proxmox VE API; vzdump ends the guest's backup and removes its snapshot and the fleecing image. A backup started in Proxmox VE itself, by a Proxmox VE backup job of several guests, is stopped for that guest only, and vzdump goes on with the others.
• How it ends. The run ends as cancelled, not as failed: no failure alert, no "Last backup failed", the guest's last backup stays as it was, and nothing of the stopped run is committed, so the existing restore points are untouched.
• Per node and per tenant. "Pause queue" on a node hands it no new backup until the queue is resumed; a running backup goes on, and scheduled backups wait (and expire after 12 hours as usual). "Cancel all queued" withdraws every backup that has not started yet, for one node or for the whole tenant.

Stopping a running backup needs restow-pve 0.4.2 on the node. A node before 0.4.2 ends a cancelled backup at its next upload, because the server refuses every upload of a cancelled run.

Nodes follow a server update

Since 0.4.2, after the server runs a new release, new runs stay paused while Proxmox VE nodes and agents install it (they are idle then), until every reachable one reports the new version or 15 minutes have passed. Installation › Updates shows the progress and, for a node that was not reached, the command for an update by hand (/opt/restow-pve/bin/restow-pve update, as root). "Update to <version>" on a node, in the nodes table next to its version, asks for the update at any time; the node installs the signed release as soon as it is idle and restarts. Proxmox VE itself is never updated by Restow.

Since 0.4.3, "Update nodes and agents now" on the card of nodes and agents in Installation › Updates starts that step by hand. It is for a server that runs a newer release than its nodes and agents although no update led into the step where they follow it: the server was updated by hand, or the answer to the announcement of an update got lost. Nodes and agents that are behind show as "Update available". An administrator with every tenant starts it; new runs pause for at most 15 minutes, reachable nodes and agents install the release when they are idle, and the pause ends once they are done. It is audited. A false "The updater is not running" after announcing an update, which also skipped this step, is fixed: the server now waits up to a minute for the updater's answer.

restow-pve now restarts the Proxmox VE daemons that load its storage plugin (pvedaemon, pveproxy, pvestatd and pvescheduler) after it has updated itself, as the installer does; restow-pve update restarts the restow-pve service too. A node that an older restow-pve updated restarts the daemons once by itself after the new release starts. Nodes on restow-pve 0.4.1 act neither on "update now" nor on the follow step: they update with their own check (two minutes after the service starts, then every six hours), or by hand once no backup or restore runs on the node. Run /opt/restow-pve/bin/restow-pve update as root, then systemctl restart restow-pve pvedaemon pvestatd pveproxy pvescheduler.

Where backups land, and a new backup chain

The guest's page, its "Back up now" dialog, the job dialog and the connect dialog name the tenant's effective primary repository, with the installation default on the server's local disk highlighted, and warn "Backups land on the server's own disk" when the primary is a directory on a disk of the Restow server itself (see storage).

A container's restic repository lives on the primary repository only. Since 0.4.2, before a container backup gets its restic credential, the server checks once per run that the repository is there:

• There: the backup runs as always.
• Only on another target of the tenant, for example a retired primary after "keep existing backups where they are": the backup is refused with a message that says to move the backups with a storage "move" or to reset the repository. Nothing is created.
• Nowhere: a new repository and a new backup chain begin. The guest's page says "New backup chain started on <date>: the previous repository was not found at <target>", the earlier restore points show "Not available" (they can no longer be restored, browsed or checked, readiness no longer counts them and retention leaves them alone), and the audit log records it. A storage that does not answer is not "missing": the backup fails instead.

"Reset repository" in the guest's danger zone (containers only) does the same on request, for a damaged repository or one on a target that is gone: the guest's name typed, a recent sign-in, audited. Every restore point of the container becomes unavailable at once, and the next backup begins a new chain. Before 0.4.2, every container with an existing repository failed with "repository does not exist" after a primary change with "keep existing backups where they are"; that choice is now refused while containers have restic repositories, and a "move" takes them along.

The Restow server's own VM

Backing up the VM that runs Restow with Restow itself can deadlock: the backup freezes or snapshots the server that receives it, and restoring it needs the very server being restored. Since 0.4.2 Restow finds that VM by its SMBIOS UUID (restow-pve 0.4.2 reports it with the inventory), or an administrator ticks "This is the Restow server" on the guest's page, which is needed when Restow runs in a container, on another host or behind a node before 0.4.2. The guest then shows "Restow server" in the lists and the job editor, no job plans a backup of it, the recommended job leaves it out, and "Back up now" or putting it into a job needs a confirmation that names the risk. Back that VM up with the Proxmox VE backup (vzdump) to another storage and keep Restow's database dumps.

Files of a container or a VM (preview for VMs)

Servers & clients, File restore lists every container with a restore point in the group "Proxmox VE containers", and every VM with a restore point in the group "Proxmox VE VMs", marked as a preview. A guest's page links its restore points there ("Browse files"). You browse a restore point and download files and folders as one ZIP. Reads and downloads are written to the audit log, and a prepared download can be started once, within ten minutes, by the administrator who prepared it.

• Containers are read by the server from the container's restic repository; paths are the container's own.
• VMs show one folder per readable file system of the VM's disks: partitions of GPT and MBR disks and linear LVM logical volumes with ext2, ext3, ext4 (the journal is replayed in memory), XFS, NTFS or FAT12, FAT16, FAT32. The Restow server reads the disks from the tenant's chunk store with its own readers in a short-lived, restricted child process; nothing is mounted, neither on the server nor on the node. Files that cannot be read are named in _not-restored.txt inside the ZIP.

Not readable in a VM: btrfs, ZFS, ReFS, LVM thin, RAID, BitLocker and LUKS, NTFS-compressed and EFS files. The XFS log and the NTFS log are not replayed, so a crash-consistent restore point can lack the last writes: compare an important restored file with the original before you rely on it. Files are downloaded, not put back into a running guest; for that, restore the whole guest as a new guest. Restore operators can browse and download files of containers and VMs, too.

Boot tests

A Proxmox VE job can boot the newest restore point of each guest, weekly or after every backup. It is off by default, with a memory limit (8 GiB by default) and a wait for the guest agent (five minutes by default), and "Boot test now" on a restore point asks for one by hand. The guest's node restores the restore point as a new guest in the pool restow-restore, isolates it before the start (every network interface disconnected or on an isolated bridge; passthrough devices, serial ports, bind mounts and the hook script removed), starts it, waits for the QEMU guest agent (a container: its init) and destroys the test guest in every case; leftovers are removed when the service starts. One test runs per node at a time, never beside a backup, and only with enough memory and storage.

The result is green when the guest agent answered, yellow when the VM only started and nothing answered (install the QEMU guest agent for proof), and red when the restore, the start or the boot failed. Recovery readiness rates the newest restore point by its boot test where there is one, and two events, boot_test.failed and boot_test.unproven, can alert you. It needs restow-pve 0.4.0 on the node, and the guest's page says when its node cannot. It does not check ports or applications inside the guest, Windows without the guest agent is yellow at best, and a guest that needs passthrough hardware to boot may fail the test, because that hardware is removed for it.

Since 0.4.6 a boot test that did not boot shows the node's message under its badge, on the guest's page and in Recovery readiness, and error texts behind a badge or a cut-off line (the boot test, the restore check of a VM or container) open on hover or keyboard focus in a card with the whole text, selectable and with a Copy button, instead of a browser tooltip.

Restore checks after every backup

Since 0.4.2 the server reads a sample of the data blocks of every new restore point back within minutes of its backup and compares them with the recorded SHA-256 (for a container, a restic check of a 5 % subset). The worker's pass runs every five minutes and takes at most 20 asked-for checks per pass, oldest request first, so a large batch of backups waits its turn ("Check queued"). The setting "Check every new restore point right after the backup" (Installation › Proxmox VE, owner) is on by default; switched off, a new restore point waits for the weekly check. The newest restore point of every guest is checked at least weekly either way, and there is no per-tenant setting.

In Recovery readiness, "Check now" checks a guest's newest restore point and "Check all unverified" the newest restore point of every guest that no check has read yet. On a guest's page, "Check now" on a restore point checks exactly that one, an older one as well. Since 0.4.6, after "Check now" the row says "Check queued" under the last check, and the guest's page says it above the earlier result, until the result is in; both refresh every few seconds meanwhile. A red check shows the error it found (restic's, for example) under its badge in the guest list, in Recovery readiness and on the guest page, instead of only "blocks did not match or could not be read". It is a sampled read-back from storage: not a boot test and not a restore on your node.

A locked repository is not a failed check

Right after a container backup, the new restore check could run into the lock that another run still held on the container's restic repository, usually the guest's own backup, whose lock a cancel or an API restart had left behind. It then showed a red "Restore check failed" although it had never run. Since 0.4.3 a check that a lock keeps out is not a failed check:

• It is tried again. The check is postponed by ten minutes, and the previous result stands meanwhile. The guest shows "Restore check postponed", its page "Check postponed: repository locked".
• After two hours the restore point reads "Could not check: repository locked": yellow (attention) in Recovery readiness, never red and never green, with restic's report of who holds the lock. Nothing is known about the restore point then, so it is no proof. The weekly check tries the guest again after a day, the next backup's check and "Check now" or "Check all unverified" sooner. A check that restic was stopped before it finished reads "Could not check: check interrupted" in the same way.
• Fewer locks to meet. The worker removes stale restic locks (only locks no live run refreshes) before the check and before retention, and restic waits up to two minutes for a lock during the check. A guest is not checked while a run of it is going or its node took on a backup of it, and a new restore point is checked two minutes after its commit at the earliest. Since 0.4.3, restow-pve waits up to 15 minutes for the server's lock during a container backup.

Restore checks that a lock failed before the update stay red until the next check of the guest: choose "Check now" on the guest or in VMs & containers. See also verification.

Optional monthly restore check

A Proxmox VE backup job has the option "Monthly restore check (restores one guest into the pool restow-restore and deletes it again)", with a second field, "Storage for the restore check", for the storage the test guest is restored to. It is off by default and needs free capacity on that storage. When it is on, the server's maintenance pass, which runs every five minutes, takes one guest of the job that has a restore point and has had no restore check for 30 days, restores its newest restore point as a new guest in the pool restow-restore without starting it, and deletes it again. Privileged containers are left out. These runs are labelled "Restore check".

It tests the restore path on your own Proxmox VE node. It is on top of the sample check that reads data blocks of every guest's newest restore point back from storage and compares them with the recorded SHA-256 (for containers a restic check of a 5 % subset), which runs weekly and, since 0.4.2, after every new backup, needs no capacity on your Proxmox VE node and runs whether or not you turn the monthly one on.

Stated limits, not hidden ones

• Proxmox VE is a preview and not yet recommended as the only backup.
• It was tested against qemu-nbd, qemu-img and restic and, for the node onboarding, against stand-ins for the node tools.
• Excluding a guest from backup (since 0.4.7) was tested in the test suites of the release, not run against a real Proxmox VE node. Excluding a selection of guests in the inventory sends one request per guest, because there is no bulk route; when one fails, the guests before it stay excluded and the list refreshes.
• The restore check after every backup is a sample read back from storage, not a boot test. Stopping a running backup needs restow-pve 0.4.2 on the node. A check that a locked repository keeps out reads "Could not check" in yellow and proves nothing.
• The fix that lets a container be restored on current Proxmox VE (since 0.4.6) was tested with Perl tests of the plugin, the restore with and without the storage ID, and not run against a real Proxmox VE node before the release.
• A file share whose repository went missing after a storage change is not yet healed with a new backup chain the way a container's is; that is planned.
• The VMs & containers page as redesigned since 0.4.3 was tested with DOM tests, not visually in a browser with thousands of guests.
• The inventory's node rows do not yet show "Waiting for the node" or "Backup running"; VMs & containers does.
• Progress, the helper's lines in the run log, boot tests, VM file restore, the five-minute retry, stopping a backup, the restore check after every backup, its retry when a repository is locked and the new backup chain were tested against the simulated node of the test suites (and a simulated S3 store), not against a real Proxmox VE cluster or S3 provider. Files of VMs and containers are downloaded as a ZIP; restoring single files into the running guest is not built. Backing up VM templates and a live restore are not possible, and privileged containers cannot be restored by Restow.

See the roadmap for what comes after and the changelog for what each release changed.

Frequently asked

Server and client backup with an agent →

Read more in Learn: full, incremental and synthetic full backups compared →

Compared with Proxmox Backup Server, fairly: where PBS is the better choice →