Learn Cloud Hypervisor - Snapshot & Restore

#Introduction

Now that VMs can be provisioned automatically with cloud-init in episode 9, it's time to talk about state resilience: what happens when you want to "freeze" a running VM and resume it later — or on another host? The answer is snapshot and restore.

Think of a snapshot as photographing the state of the entire VM: memory (RAM contents), CPU state, and device state are copied to disk. On restore, the VM resumes from exactly that point — running processes have no idea they were ever "frozen". This is the foundation for consistent backups, recovery, and (together with episode 11) live migration.

#What a Snapshot Stores

A Cloud Hypervisor snapshot stores three main things:

• Memory: the entire contents of guest RAM, copied to a file.
• Device state: the configuration and state of each virtio device (blk, net, fs, etc.).
• vCPU state: vCPU registers and each thread's execution status.

Because of this complexity, snapshots can't just be moved around: the device state format is tied to a specific version. Restoring snapshots across different Cloud Hypervisor versions is not supported — a topic we cover in the limitations section.

#Creating a Snapshot: The Snapshot API

Snapshots are created through the API socket while the VM is running. Prepare a VM with --api-socket (episode 8), then call the snapshot endpoint:

curl --unix-socket /tmp/ch.sock -X PUT \
  -H "Content-Type: application/json" \
  --data '{
    "destination_url": "file:///srv/snapshots/vm-01"
  }' \
  http://localhost/api/v1/vm.snapshot

destination_url: file:///srv/snapshots/vm-01 defines the output location. Cloud Hypervisor writes several files into that directory:

/srv/snapshots/vm-01/
├── memory_file                    # isi RAM guest
├── vm.json                        # state device & vCPU
└── (file device opsional lainnya)

The snapshot process happens without stopping the VM. However, note that a snapshot isn't zero-downtime in the fullest sense — during creation there's a brief "stop the world" phase (the VM is paused, memory is copied, the VM resumes). For workloads that truly must keep running without interruption, live migration (episode 11) is the answer.

#Restore: Bringing It Back

Restore is done by running a new cloud-hypervisor that uses the snapshot state:

cloud-hypervisor \
  --restore /srv/snapshots/vm-01 \
  --disk path=ubuntu.raw \
  --net tap=ch0,ip=192.168.100.1,mac=a8:21:95:80:35:e6

--restore /srv/snapshots/vm-01 reads vm.json and memory_file, then resumes guest execution from the point the snapshot was taken. Note: device config such as --disk and --net must be provided again — the device state in the snapshot is re-referenced with matching CLI parameters. The MAC and disk paths must be consistent with when the snapshot was taken, because the guest keeps connection state against those devices.

Verify that processes in the guest continue:

uptime -s
ps aux | grep aplikasi

uptime -s shows the original boot time (when the VM first started), not the restore time — proof that the VM resumed rather than rebooted.

#Offloaded Snapshot Daemon (v53.0)

Since v53.0 (12 July 2026), snapshot creation can be offloaded to a separate daemon process. Instead of the VMM handling memory copying inside its own process, an external daemon takes over that job. The advantages: the VMM is lighter during snapshots, snapshot creation can run in parallel on different hosts, and errors in the snapshot process don't bring down the VM.

cloud-hypervisor-offload --snapshot-daemon --socket /tmp/offload.sock

The flow: the VMM hands the memory reference to the daemon via a socket, the daemon copies memory to the snapshot file while the VMM keeps serving the VM. This reduces the "stop the world" pause and speeds up snapshot time — a significant improvement for environments doing mass snapshots.

#Limitations and Best Practices

#Not Cross-Version

The most important rule: a snapshot made with version X can only be restored with version X (or a compatible point-release within the same LTS). Don't expect a v50 snapshot to restore on v53. In production, store the VMM version used in the snapshot metadata and pin versions when deploying.

#Format Best Practices

• Keep disk paths stable: place the snapshot and disk in a location both hosts can access (shared storage) so cross-host restore goes smoothly.
• Snapshot while idle: snapshotting under heavy load produces larger files and longer pauses. Schedule it during low load.
• Files being written: a snapshot captures in-memory state; data the guest has only written to disk doesn't get captured — make sure the guest filesystem is consistent (e.g., via fstrim/sync) before snapshotting if you want full consistency.
• Test restore regularly: a snapshot never tested for restore is a time bomb. Schedule restore tests as part of the process.

#Recovery Workflow

curl --unix-socket /tmp/ch.sock -X PUT \
  --data '{"destination_url":"file:///srv/snapshots/vm-01"}' \
  http://localhost/api/v1/vm.snapshot
tar czf backup-$(date +%F).tar.gz /srv/snapshots/vm-01

Archive the snapshot together with the VM config (guest.json) and the binary version — that's a complete recovery package.

#Common Pitfalls

• --memory shared=on forgotten: snapshot fails; set it from the start.
• Disk/MAC inconsistent: the guest loses its network connection or can't mount its disk after restore.
• Trying a cross-version restore: fails with a format error; always match versions.
• Repeated snapshots without disks: a snapshot stores state, not disk contents — make sure the disk images are backed up too.

#Conclusion

Key takeaways:

• A snapshot stores the memory, device state, and vCPU state of a running VM.
• Snapshots are created via the vm.snapshot API and restored with --restore.
• Requires --memory shared=on from the start.
• v53.0 adds an offloaded snapshot daemon for snapshotting without burdening the VMM.
• Snapshots can't be moved across Cloud Hypervisor versions.
• Test restores regularly and archive snapshots with the config and binary version.

In the next episode, episode 11, we'll cover live migration — moving VMs between hosts without downtime using the expanded protocol, including page-faults served from the source in v53. We'll set up shared storage and networking, then dissect version and device compatibility constraints. Your VMs can now start to "move house" without noticing.