* [PATCH qemu v2 1/5] async snapshot: improve disk consistency by only calling vm_start() in savevm-end handler
2026-11-12 13:45 [PATCH-SERIES qemu/qemu-server/docs/manager v2 0/5] vm: snapshot: improve consistency and documentation Fiona Ebner
@ 2026-11-12 13:45 ` Fiona Ebner
2026-11-12 13:45 ` [PATCH qemu-server v2 2/5] snapshot: document how consistency between multiple disks is achieved Fiona Ebner
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Fiona Ebner @ 2026-11-12 13:45 UTC (permalink / raw)
To: pve-devel
A snapshot with VM state is created as follows in Proxmox VE:
1. qemu-server calls savevm-start and waits for query-savevm to return
status 'completed'.
2. process_savevm_co() runs until state saving can converge.
3. blockdevs in IO threads are flushed async as an optimization.
4. The process_savevm_finalize() bottom half is scheduled and runs.
5. The VM is stopped, which drains and flushes all IO.
6. The state is set to 'completed'.
7a. The VM is started if it was running before.
7b. qemu-server sees status 'completed'.
8. qemu-server creates all the disk snapshots.
9. qemu-server calls savevm-end.
Since vm_start() is the very next command after setting the state to
'completed', in practice, step 7a will always happen before step 8,
which is problematic for consistency. The VM should only be started
again after the disk snapshots are taken. The functionality for
restoring the run state is already in place in qmp_savevm_end(), so
rely on that.
Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>
---
...async-for-background-state-snapshots.patch | 26 +++++++++++++------
...add-optional-buffer-size-to-QEMUFile.patch | 6 ++---
...se-migration-blocker-check-for-snaps.patch | 4 +--
3 files changed, 23 insertions(+), 13 deletions(-)
diff --git a/debian/patches/pve/0015-PVE-add-savevm-async-for-background-state-snapshots.patch b/debian/patches/pve/0015-PVE-add-savevm-async-for-background-state-snapshots.patch
index 4bc6855b2e..abd64a812a 100644
--- a/debian/patches/pve/0015-PVE-add-savevm-async-for-background-state-snapshots.patch
+++ b/debian/patches/pve/0015-PVE-add-savevm-async-for-background-state-snapshots.patch
@@ -39,19 +39,21 @@ Signed-off-by: Stefan Reiter <s.reiter@proxmox.com>
Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>
[EF: drop QIOChannel reference]
Signed-off-by: Erik Fastermann <e.fastermann@proxmox.com>
+[FE: defer vm_start() to qmp_savevm_end() in case of success]
+Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>
---
hmp-commands-info.hx | 13 +
hmp-commands.hx | 27 ++
include/migration/snapshot.h | 2 +
include/monitor/hmp.h | 3 +
migration/meson.build | 1 +
- migration/savevm-async.c | 615 +++++++++++++++++++++++++++++++++++
+ migration/savevm-async.c | 623 +++++++++++++++++++++++++++++++++++
monitor/hmp-cmds.c | 38 +++
qapi/migration.json | 34 ++
qapi/misc.json | 25 ++
qemu-options.hx | 12 +
system/vl.c | 10 +
- 11 files changed, 780 insertions(+)
+ 11 files changed, 788 insertions(+)
create mode 100644 migration/savevm-async.c
diff --git a/hmp-commands-info.hx b/hmp-commands-info.hx
@@ -162,10 +164,10 @@ index a9d0c9cc36..1ae3779e39 100644
), gnutls, zlib)
diff --git a/migration/savevm-async.c b/migration/savevm-async.c
new file mode 100644
-index 0000000000..de69350763
+index 0000000000..12e2a5dad2
--- /dev/null
+++ b/migration/savevm-async.c
-@@ -0,0 +1,615 @@
+@@ -0,0 +1,623 @@
+#include "qemu/osdep.h"
+#include "migration/channel-savevm-async.h"
+#include "migration/migration.h"
@@ -415,11 +417,19 @@ index 0000000000..de69350763
+ save_snapshot_error("process_savevm_cleanup: invalid state: %d",
+ snap_state.state);
+ }
-+ if (snap_state.vm_needs_start) {
-+ if (!should_skip_vm_start()) {
-+ vm_start();
++
++ /*
++ * In case of success, qemu-server still needs to create the disk snapshots
++ * while the VM is stopped. qmp_savevm_end() will restore the run state
++ * later.
++ */
++ if (snap_state.state != SAVE_STATE_COMPLETED) {
++ if (snap_state.vm_needs_start) {
++ if (!should_skip_vm_start()) {
++ vm_start();
++ }
++ snap_state.vm_needs_start = false;
+ }
-+ snap_state.vm_needs_start = false;
+ }
+
+ DPRINTF("timing: process_savevm_finalize (full) took %ld ms\n",
diff --git a/debian/patches/pve/0016-PVE-add-optional-buffer-size-to-QEMUFile.patch b/debian/patches/pve/0016-PVE-add-optional-buffer-size-to-QEMUFile.patch
index fe00188373..b3b5899a78 100644
--- a/debian/patches/pve/0016-PVE-add-optional-buffer-size-to-QEMUFile.patch
+++ b/debian/patches/pve/0016-PVE-add-optional-buffer-size-to-QEMUFile.patch
@@ -186,10 +186,10 @@ index 8f824c124d..0ffcb13921 100644
G_DEFINE_AUTOPTR_CLEANUP_FUNC(QEMUFile, qemu_fclose)
diff --git a/migration/savevm-async.c b/migration/savevm-async.c
-index de69350763..67b69bf3ac 100644
+index 12e2a5dad2..c439bc9235 100644
--- a/migration/savevm-async.c
+++ b/migration/savevm-async.c
-@@ -433,7 +433,7 @@ void qmp_savevm_start(const char *statefile, bool has_skip_vm_start,
+@@ -441,7 +441,7 @@ void qmp_savevm_start(const char *statefile, bool has_skip_vm_start,
QIOChannel *ioc = QIO_CHANNEL(qio_channel_savevm_async_new(snap_state.target,
&snap_state.bs_pos));
@@ -198,7 +198,7 @@ index de69350763..67b69bf3ac 100644
object_unref(ioc);
if (!snap_state.file) {
-@@ -572,7 +572,7 @@ int load_snapshot_from_blockdev(const char *filename, Error **errp)
+@@ -580,7 +580,7 @@ int load_snapshot_from_blockdev(const char *filename, Error **errp)
/* restore the VM state */
QIOChannel *ioc = QIO_CHANNEL(qio_channel_savevm_async_new(be, &bs_pos));
diff --git a/debian/patches/pve/0044-savevm-async-reuse-migration-blocker-check-for-snaps.patch b/debian/patches/pve/0044-savevm-async-reuse-migration-blocker-check-for-snaps.patch
index 76b4c23e6b..f59e52d296 100644
--- a/debian/patches/pve/0044-savevm-async-reuse-migration-blocker-check-for-snaps.patch
+++ b/debian/patches/pve/0044-savevm-async-reuse-migration-blocker-check-for-snaps.patch
@@ -136,10 +136,10 @@ index 631421c784..1d07f71a24 100644
bool migration_in_postcopy(void);
bool migration_postcopy_is_alive(MigrationStatus state);
diff --git a/migration/savevm-async.c b/migration/savevm-async.c
-index 67b69bf3ac..3ab0bd4539 100644
+index c439bc9235..25d0b253e5 100644
--- a/migration/savevm-async.c
+++ b/migration/savevm-async.c
-@@ -399,7 +399,7 @@ void qmp_savevm_start(const char *statefile, bool has_skip_vm_start,
+@@ -407,7 +407,7 @@ void qmp_savevm_start(const char *statefile, bool has_skip_vm_start,
return;
}
--
2.47.3
^ permalink raw reply related [flat|nested] 6+ messages in thread* [PATCH docs v2 4/5] qm: document snapshot operations
2026-11-12 13:45 [PATCH-SERIES qemu/qemu-server/docs/manager v2 0/5] vm: snapshot: improve consistency and documentation Fiona Ebner
` (2 preceding siblings ...)
2026-11-12 13:45 ` [PATCH docs v2 3/5] pvesm: add anchor for storage types Fiona Ebner
@ 2026-11-12 13:45 ` Fiona Ebner
2026-11-12 13:45 ` [PATCH manager v2 5/5] ui: qemu: online help: link to new section for snapshots Fiona Ebner
4 siblings, 0 replies; 6+ messages in thread
From: Fiona Ebner @ 2026-11-12 13:45 UTC (permalink / raw)
To: pve-devel
Add a common intro for snapshots and hibernation to describe the
differences and commonalities.
Document why snapshots with multiple disks are consistent. There
already is a 'qm_snapshots' anchor, but that is a subsection for the
configuration chapter, so use 'qm_snapshot_operations' for the new
one.
Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>
---
qm.adoc | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 67 insertions(+), 4 deletions(-)
diff --git a/qm.adoc b/qm.adoc
index 18a4fbe..5eeba55 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -2149,9 +2149,67 @@ It will be called during various phases of the guests lifetime.
For an example and documentation see the example script under
`/usr/share/pve-docs/examples/guest-example-hookscript.pl`.
+[[qm_snapshots_and_hibernation]]
+Snapshots and Hibernation
+-------------------------
+
+You can use snapshots and hibernation to preserve the current state of the VM
+configuration, disks, device state and RAM. Hibernation stops and locks the VM
+and you can resume the VM from the saved state later. Snapshots allow the VM to
+continue running and being modified normally and you can rollback to a snapshot
+at any later time. Passing through host devices to the VM and certain other
+configuration settings might make preserving the state impossible and thus block
+snapshots and hibernation. Certain storages like RBD allow arbitrary snapshot
+trees, other storages like ZFS only allow linear snapshot chains and rollback to
+the latest snapshot. Check the list of xref:_storage_types[Storage Types]
+for snapshots support.
+
+[[qm_snapshot_operations]]
+Snapshots
+~~~~~~~~~
+
+Create a new snapshot of the current configuration and disk state with:
+
+----
+# qm snapshot ID SNAPSHOT_NAME
+----
+
+For a running VM, you may additionally include the device state and RAM with:
+
+----
+# qm snapshot ID SNAPSHOT_NAME --vmstate 1
+----
+
+This creates a new volume on the xref:qm_vmstatestorage[state storage] and
+allows to restore the live state of the VM upon rollback.
+
+NOTE: Proxmox VE ensures consistency between multiple disks by pausing the vCPUs
+and completing and flushing all pending IO via the QEMU block layer before the
+disk snapshots are created.
+
+Delete a snapshot with:
+
+----
+# qm delsnapshot ID SNAPSHOT_NAME
+----
+
+Roll back to a snapshot with:
+
+----
+# qm rollback ID SNAPSHOT_NAME
+----
+
+WARNING: Rollback destroys the current state of the VM (even if running) and
+disks!
+
+The VM configuration and the state of the VM disks are changed back to the point
+in time when the snapshot was taken. If the VM state is included in the
+snapshot, the VM is live after rollback and continues running from the point
+in time when the snapshot was taken.
+
[[qm_hibernate]]
Hibernation
------------
+~~~~~~~~~~~
You can suspend a VM to disk with the GUI option `Hibernate` or with
@@ -2164,9 +2222,14 @@ and the VM gets stopped. On the next start, the memory content will be
loaded and the VM can continue where it was left off.
[[qm_vmstatestorage]]
-.State storage selection
-If no target storage for the memory is given, it will be automatically
-chosen, the first of:
+State storage selection
+~~~~~~~~~~~~~~~~~~~~~~~
+
+To the save the RAM and device state of the virtual machine, a separate volume
+is created. For hibernation, use the `--statestorage` option to specify the
+target storage for the state volume. For snapshots or if not provided for
+hibernation, the target storage for the state volume is automatically chosen,
+the first of:
1. The storage `vmstatestorage` from the VM config.
2. The first shared storage from any VM disk.
--
2.47.3
^ permalink raw reply related [flat|nested] 6+ messages in thread