Save and restore refers to the process of taking a running guest and saving its memory state to a file. At some time later, it is possible to restore the guest to its original running state, continuing execution where it left off.
It is important to note that the save/restore APIs only save the memory state, no storage state is preserved. Thus when the guest is restored, the underlying guest storage must be in exactly the same state as it was when the guest was initially saved. For basic usage this implies that a guest can only be restored once from any given saved state image. To allow a guest to be restored from the same saved state multiple times, the application must also have taken a snapshot of the guest storage at time of saving, and explicitly revert to this storage snapshot when restoring. A future API enhancement in libvirt will allow for an automated snapshot capability which saves memory and storage state in one operation.
The save operation requires the fully qualified path to a file in which the guest memory state will be saved. This filename is in the hypervisor's file system, not the libvirt client application's. There's no difference between the two if managing a local hypervisor, but it is critically important if connecting remotely to a hypervisor across the network. The example that follows demonstrates saving a guest called 'demo-guest' to a file. It checks to verify that the guest is running before saving, though this is technically redundant since the hypervisor driver will do such a check itself.
virDomainPtr dom;
virDomainInfoPtr info;
const char *filename = "/var/lib/libvirt/save/demo-guest.img";
dom = virDomainLookupByName(conn, "demo-guest");
if (!dom) {
fprintf(stderr, "Cannot find guest to be saved");
return;
}
if (virDomainGetInfo(dom, &info) < 0) {
fprintf(stderr, "Cannot check guest state");
return;
}
if (info.state == VIR_DOMAIN_SHUTOFF) {
fprintf(stderr, "Not saving guest that isn't running");
return;
}
if (virDomainSave(dom, filename) < 0) {
fprintf(stderr, "Unable to save guest to %s", filename);
}
fprintf(stderr, "Guest state saved to %s", filename);
Some period of time later, the saved state file can then be used to restart the guest where it left of, using the virDomainRestore API. The hypervisor driver will return an error if the guest is already running, however, it won't prevent attempts to restore from the same state file multiple times. As noted earlier, it is the applications' responsibility to ensure the guest storage is in exactly the same state as it was when the save image was created
virDomainPtr dom;
int id;
const char *filename = "/var/lib/libvirt/save/demo-guest.img";
if ((id = virDomainRestore(conn, filename)) < 0) {
fprintf(stderr, "Unable to restore guest from %s", filename);
}
dom = virDomainLookupByID(conn, id);
if (!dom) {
fprintf(stderr, "Cannot find guest that was restored");
return;
}
fprintf(stderr, "Guest state restored from %s", filename);
