1# Snapshot and Restore 2 3The goal for the snapshot/restore feature is to provide the user with the 4ability to take a snapshot of a previously paused virtual machine. This 5snapshot can be used as the base for creating new identical virtual machines, 6without the need to boot them from scratch. The restore codepath takes the 7snapshot and creates the exact same virtual machine, restoring the previously 8saved states. The new virtual machine is restored in a paused state, as it was 9before the snapshot was performed. 10 11## Snapshot a Cloud Hypervisor VM 12 13First thing, we must run a Cloud Hypervisor VM: 14 15```bash 16./cloud-hypervisor \ 17 --api-socket /tmp/cloud-hypervisor.sock \ 18 --cpus boot=4 \ 19 --memory size=4G \ 20 --kernel vmlinux \ 21 --cmdline "root=/dev/vda1 console=hvc0 rw" \ 22 --disk path=focal-server-cloudimg-amd64.raw 23``` 24 25At any point in time when the VM is running, one might choose to pause it: 26 27```bash 28./ch-remote --api-socket=/tmp/cloud-hypervisor.sock pause 29``` 30 31Once paused, the VM can be safely snapshot into the specified directory and 32using the following command: 33 34```bash 35./ch-remote --api-socket=/tmp/cloud-hypervisor.sock snapshot file:///home/foo/snapshot 36``` 37 38Given the directory was present on the system, the snapshot will succeed and 39it should contain the following files: 40 41```bash 42ll /home/foo/snapshot/ 43total 4194536 44drwxrwxr-x 2 foo bar 4096 Jul 22 11:50 ./ 45drwxr-xr-x 47 foo bar 4096 Jul 22 11:47 ../ 46-rw------- 1 foo bar 1084 Jul 22 11:19 config.json 47-rw------- 1 foo bar 4294967296 Jul 22 11:19 memory-ranges 48-rw------- 1 foo bar 217853 Jul 22 11:19 state.json 49``` 50 51`config.json` contains the virtual machine configuration. It is used to create 52a similar virtual machine with the correct amount of CPUs, RAM, and other 53expected devices. It is stored in a human readable format so that it could be 54modified between the snapshot and restore phases to achieve some very special 55use cases. But for most cases, manually modifying the configuration should not 56be needed. 57 58`memory-ranges` stores the content of the guest RAM. 59 60`state.json` contains the virtual machine state. It is used to restore each 61component in the state it was left before the snapshot occurred. 62 63## Restore a Cloud Hypervisor VM 64 65Given that one has access to an existing snapshot in `/home/foo/snapshot`, 66it is possible to create a new VM based on this snapshot with the following 67command: 68 69```bash 70./cloud-hypervisor \ 71 --api-socket /tmp/cloud-hypervisor.sock \ 72 --restore source_url=file:///home/foo/snapshot 73``` 74 75Or using two different commands from two terminals: 76 77```bash 78# First terminal 79./cloud-hypervisor --api-socket /tmp/cloud-hypervisor.sock 80 81# Second terminal 82./ch-remote --api-socket=/tmp/cloud-hypervisor.sock restore source_url=file:///home/foo/snapshot 83``` 84 85Remember the VM is restored in a `paused` state, which was the VM's state when 86it was snapshot. For this reason, one must explicitly `resume` the VM before to 87start using it. 88 89```bash 90./ch-remote --api-socket=/tmp/cloud-hypervisor.sock resume 91``` 92 93At this point, the VM is fully restored and is identical to the VM which was 94snapshot earlier. 95 96## Limitations 97 98VFIO devices and Intel SGX are out of scope. 99