Take and restore snapshots

There are two kinds of snapshot, and choosing between them comes down to one question: is the VM running right now?

	Live snapshot	Offline image snapshot
Tools	vm_snapshot_create / _restore / _delete / _list	image_snapshot_create / _apply / _delete / _list
Addressed by	VM name	disk image path
VM state	must be running	must be stopped
Captures	RAM, devices and disk	disk contents only
Restoring gives you	the exact moment you snapshotted, applications still open	the disk as it was, which then boots from cold
Requires	writable disks in qcow2 format	a qcow2 image

Both store their data inside the qcow2 file itself, so snapshots travel with the image when you copy it, and they cost disk space in the same file.

Live snapshots of a running VM

Use these for checkpoints in the middle of work: before applying an update, before a change you expect to have to undo, before letting something untrusted run.

1. Create the checkpoint. The VM pauses briefly while its RAM is written into the disk image, then continues.

   vm_snapshot_create(name="dev", tag="before-upgrade")

   Tags use letters, digits, dots, underscores and hyphens, start with a letter or digit, and are at most 64 characters.

2. Do the risky thing.

3. List what you have if you have lost track:

   vm_snapshot_list(name="dev")

4. Roll back. RAM, devices and disk all revert together, so the guest comes back mid-sentence rather than booting.

   vm_snapshot_restore(name="dev", tag="before-upgrade")

5. Drop a checkpoint you no longer need. The VM keeps running; only the saved state is removed.

   vm_snapshot_delete(name="dev", tag="before-upgrade")

Caution

Restoring throws away everything that happened after the snapshot, with no second chance. If work since the checkpoint matters, copy it out first with guest_file_read or through a forwarded port. A useful habit is to snapshot again under a new tag before restoring an old one, which costs seconds and keeps a way back.

How long a snapshot takes scales with how much RAM the VM has, because that RAM is being written to disk. A 2 GB VM is a few seconds; a 32 GB VM is a coffee break. Restoring is the same work in reverse and is still far quicker than a boot plus getting an application back to the state it was in.

Live snapshots need every writable disk to be qcow2. If a VM has a raw disk attached, vm_snapshot_create fails, and the fix is to convert the disk while the VM is stopped:

image_convert(source="~/vms/data.img", dest="~/vms/data.qcow2", format="qcow2")

Offline snapshots of a stopped image

Use these when the VM is not running: marking a known-good state of a base image, or checkpointing a disk before you modify it from the host (for example before injecting the guest agent, see Install the guest agent).

image_snapshot_create(path="~/vms/base.qcow2", tag="clean-install")
image_snapshot_list(path="~/vms/base.qcow2")
image_snapshot_apply(path="~/vms/base.qcow2", tag="clean-install")
image_snapshot_delete(path="~/vms/base.qcow2", tag="clean-install")

These tools refuse to touch a disk that is attached to a running VM, and say which VM is holding it. Stop that VM first. The refusal is deliberate: editing a disk underneath a live guest corrupts it, and the guest would not notice until much later.

Only disk contents are stored, so image_snapshot_apply gives you an image that boots from cold. That is exactly what you want for a base image, and not what you want mid-session, which is why the live tools exist.

Choosing

Working inside a VM and about to do something reversible. Live snapshot. The restore puts you back in the room you were standing in.

Preparing a base image, or about to edit a disk from the host. Offline snapshot, with the VM stopped.

You want a clean throwaway VM every time, not a checkpoint. Neither. Use sandbox_vm with an overlay, which is faster to create and cheaper to discard than any snapshot; see Disposable sandboxes. Snapshots are for going back inside one VM’s history; overlays are for never changing the original in the first place.

You need a copy you can move to another machine or keep for months. Neither. image_convert writes a standalone image, flattening any backing chain, which is easier to reason about than a snapshot living inside a file that also holds other states.

Related

• Tool reference for exact parameters.
• Architecture for how snapshot state is stored in qcow2.