Snapshots

OpenVMM supports saving and restoring VM snapshots, allowing you to capture the complete state of a running VM and resume it later.

Overview

A snapshot captures three pieces of state:

• Guest RAM — the full contents of guest memory
• Device state — the saved state of all emulated devices
• Manifest — metadata describing the snapshot (architecture, memory size, VP count, page size, etc.)

These are stored as three files in a snapshot directory:

Prerequisites

Snapshots require file-backed guest memory. You must pass --memory-backing-file when launching the VM so that guest RAM is written to a file on disk rather than held in anonymous memory.

Saving a snapshot

Start a VM with file-backed memory:

cargo run -- \
  --uefi \
  --disk memdiff:file:path/to/disk.vhdx \
  --memory-backing-file path/to/memory.bin \
  --memory 4096

Once the VM is running, open the interactive console and issue a save command, specifying the output directory:

save-snapshot path/to/snapshot-dir

OpenVMM writes manifest.bin, state.bin, and a hard link to memory.bin into the specified directory.

Restoring a snapshot

To restore, pass the snapshot directory with --restore-snapshot:

cargo run -- \
  --uefi \
  --disk memdiff:file:path/to/disk.vhdx \
  --memory 4096 \
  --processors 4 \
  --restore-snapshot path/to/snapshot-dir

--restore-snapshot automatically opens memory.bin from the snapshot directory, so --memory-backing-file should not be specified (the two options are mutually exclusive).

Device configuration on restore

The snapshot only stores device state, not device configuration. All device flags (e.g. --disk, --nic, --serial, --virtio-blk, etc.) must be specified on the restore command line exactly as they were when the snapshot was saved — they are not read from the snapshot.

The snapshot manifest validates that --memory, --processors, architecture, and page size match the values recorded at save time. However, it does not record the list of CLI device flags. Instead, device configuration compatibility is enforced at the state-unit level: each emulated device saves its state under a unique name (e.g. "pit", "vmbus", "ide"), and restore matches saved-state entries to the currently instantiated devices by name.

The rules are:

In practice this means:

• You must pass the same device flags on restore as you did on save. Removing a device that was present at save time will cause restore to fail.
• Adding a new device that was not present at save time is technically allowed — the new device will start in its power-on default state. This is not tested and the device may not be functional, since the guest OS will not have enumerated or initialised it during boot. The supported path is to use the same device flags on save and restore.

Device save/restore support

Not all devices support save/restore. If a VM includes a device that does not support saving, the save-snapshot command will fail with SaveError::NotSupported.

The following table summarises support for the device types relevant to OpenVMM snapshots:

Limitations

• Snapshots are not portable across architectures (e.g., you cannot restore an x86_64 snapshot on aarch64)
• After restoring, memory.bin in the snapshot directory becomes the live guest RAM backing file and will be modified as the VM runs. To restore from the same snapshot multiple times, copy the snapshot directory before each restore.
• VMs using VPCI or PCIe devices do not currently support save/restore
• OpenHCL-based VMs do not currently support this snapshot mechanism
• VMs using PCAT firmware do not support save/restore
• --memory and --processors must be specified on restore and match the snapshot manifest values. A future version may read these from the snapshot automatically.