What Proxmox vzdump modes actually guarantee

Proxmox offers three backup modes in a single dropdown, which makes them look like three speeds of the same thing. They are not. They differ in what happens to the running guest, and therefore in what the archive is actually a copy of.

The short version, and then the long one:

The word doing all the work in that table is crash-consistent. It means the archive is what the disk would have looked like if somebody had pulled the power cable at that instant. A journalling filesystem will come back from that. A database that had a transaction in flight may not, and an application that keeps state across two files will not know that one of them is older than the other.

Snapshot does not mean quiesced

snapshot is the default, and it is the only mode that does not interrupt anything. Proxmox takes a storage-level snapshot and reads the backup from that, so the guest keeps writing to the live volume the whole time.

There is a way to make that archive better: the QEMU guest agent can freeze the filesystem inside the guest for the moment the snapshot is taken, which flushes writes and gives you an archive that the guest itself considers clean. If the guest agent is installed, running, and answers, that is what happens.

The trap is in that "if". Nothing in the API result tells you whether the freeze happened. The vzdump task returns a task ID and, when it finishes, a status. Whether qemu-guest-agent answered the freeze request is a line in the task log, not a field you can read back.

This is a decision point for anyone automating on top of it, and it is worth being deliberate about. When we built the backup path for our Proxmox integration we ended up recording consistency as what happened, never as what was asked for: a stop backup is recorded as consistent, and both snapshot and suspend are recorded as crash-consistent, full stop. There is a value for "the guest was quiesced" in our schema and the agent never emits it, because emitting it would mean claiming knowledge of a freeze we cannot verify from the API.

An archive that is described as slightly worse than it is costs you nothing. An archive that is described as better than it is costs you the one restore that matters.

Suspend pauses the guest, and it is not a middle ground

suspend reads better than it behaves. People assume it is "snapshot, but safer", a compromise between no downtime and full downtime. What it actually does is pause the guest while the data is read.

It gives you the same crash-consistency guarantee as snapshot, because pausing a machine is not the same as letting it flush and settle. You get an interruption and no stronger promise. The case for it is narrow: a storage backend that cannot snapshot at all, where snapshot mode has nothing to snapshot from.

Stop is the only honest guarantee

stop shuts the guest down, backs it up, and starts it again. It is the longest interruption and the only mode where the archive is unambiguously a copy of a filesystem nobody was writing to.

For a database server that somebody will restore under pressure at three in the morning, that is not a heavy price. For a fleet of web servers it is a price nobody will pay every night. Both are correct answers to different questions, which is why the mode belongs in the policy and not in one global setting.

One implementation detail matters here. Because stop and suspend both interrupt a running machine, a missing or unrecognised mode value must never fall through to one of them. In our command schema the mode travels as the literal Proxmox word (snapshot, suspend, stop) rather than a vocabulary of our own, and an unset value resolves to snapshot. A translation table between our words and theirs would put a mistranslation exactly where a mistranslation shuts down a customer's machine.

The parameters that decide whether the job runs at all

Before consistency there is a more boring question: will vzdump even start. Four things on the request decide that, and three of them fail in ways that are hard to read.

The target storage must accept backups. Proxmox storage has a content list, and only a storage whose list includes backup can take a vzdump. This is not advisory. Send the job to a storage that only holds disk images and Proxmox refuses it with a message like storage 'x' does not support vzdump backups. Accurate, and meaningless to the customer who clicked the button. It is worth checking before you submit, so the refusal can say "this storage does not accept backups" instead.

A related case: a storage that appears in the cluster resource list with status unknown is configured but not answering. An NFS share that is down looks exactly like a valid target right up until the job fails.

Compression has a value that is not the word you expect.

Proxmox writes "no compression" as 0, not as none. Sending none is the kind of mistake that produces a silent refusal rather than a clear one, and it is the reason our test suite asserts the exact string that leaves the agent rather than only asserting that the call succeeded.

Mail notification defaults to noisy, and to the wrong person. Without an explicit mailnotification=failure, Proxmox mails root@pam after every backup. On a machine managed from a platform, that is mail to the provider about something the customer did.

Two optional fields are worth knowing. notes-template attaches a note to the archive, and Proxmox expands its own placeholders such as {{guestname}} inside it. protected=1 marks an archive as protected, and Proxmox will then refuse to prune it. That is the mechanism you want for the copy somebody takes before a risky change, and exactly the wrong default for a nightly job.

Retention is not a vzdump parameter

There is no retention setting on the backup request. Pruning is configured on the storage, in Proxmox, and it is the storage owner who decides how long copies live.

That has a design consequence for anyone building on top: a panel offering a "keep 7 copies" field either reaches into the storage configuration or deletes archives itself. We chose neither, and say so, instead of implying otherwise with a field that does nothing.

Timing out is not the same as failing

A vzdump of a large machine can outlive any sane request timeout. When it does, the important thing to understand is that nothing was cancelled: the job keeps running on the hypervisor, and it will finish or fail on its own schedule.

So a timeout is a statement about your connection, not about the backup. The run stays open, the task ID is still valid, and the honest thing for a UI to do is to say "still running" and reconcile later. The alternative, marking it failed and letting somebody start a second one, puts two vzdump jobs on the same storage for the same machine.

While it runs, the real progress is available: vzdump writes lines like 12% (1.2 GiB of 10.0 GiB) into its task log. A progress bar fed from that is honest. A progress bar fed from an estimate is a guess with a percentage sign on it.

Restoring is a different question, and unique is the one to get right

The mode question ends when the archive exists. Restoring has its own trap, and it is a network one.

Restore an archive into a new VM without asking for new identifiers and the new machine inherits the MAC addresses of the original. If the original is still running, you now have two machines with the same MAC on the same bridge, and the symptom is not "the restore failed" but "the production machine's network went strange". The unique flag on the restore call is what prevents that, and on a platform that restores alongside a running original it is not an option but a precondition.

Two more things are worth knowing before the first restore:

• storage means something different here. On backup it is where the archive goes, and it needs backup in its content list. On restore it is where the restored disks land, and it needs images. Same field name, different requirement.
• Only the disks come back. A restored machine is a machine with disks and hardware from the archive. Address assignments, firewall rules and whatever automation was attached to the original live in your own systems, not in the vzdump file, and they do not travel with it.

What is not measured here

Everything above about the shape of the calls comes from the Proxmox API schema and from building against it; the mode semantics are Proxmox's own, described in its documentation.

What we deliberately do not state is how long each mode costs. We have no measured pause duration for suspend and no measured downtime for stop: that depends on the guest, the storage and the amount of dirty memory, and a number measured on one machine would be quoted as a general one. Those have to come from your own hardware.

Two further gaps worth naming. Everything here is about QEMU guests; container backups have their own rules around mount points and bind mounts, and we have not measured them. And there is no incremental path in any of this: vzdump to a plain storage writes a full archive every time. Incremental backup is what Proxmox Backup Server is for, and that is a different piece of software with a different set of promises.

This came out of building the Proxmox backup path for Provibr, a server management panel for hosting providers, where a backup that is described as better than it is would be the worst possible bug. The setup notes for the hypervisor side are in the Proxmox documentation, and the Proxmox integration page covers what the agent can do. If you are weighing the platform itself, Proxmox next to VMware is the comparison.