kvm.restore

Restore a full backup for a KVM virtual machine.

Before restoring, RVC validates the archive and measures the size it extracts to, then chooses a directory to hold a rescue copy of the VM's current disk. It tries each candidate location in order until one has enough room: the VM's own directory (only when its partition can hold the current disk and the extracted archive at the same time), temporary_backup_restore_dir, the configured full_backup directory, /tmp, and finally the directory holding the backup file itself. A rescue copy kept in the VM's own directory is just a rename; one moved to another partition takes longer to complete.

If the restore fails after the current disk has been moved to the rescue directory, RVC puts the rescue copy and its snapshots back and leaves the VM as it was. There is nothing to restore from if no rescue copy could be made.

On success, RVC removes the VM's internal snapshots, extracts the archive over the VM directory, and redefines the snapshot definitions the archive carries. ignore_snapshot_errors keeps the restore going if one of those redefinitions fails. On a cluster, the redefined snapshots are then synced to the peer node.

From RVC 3.13.0, the extracted archive also restores the VM's UEFI NVRAM store and vTPM state to the locations named in the VM's definition, with their original ownership and permissions, and both are included in the rescue copy. A UEFI or vTPM VM comes back with the firmware and TPM identity it had when the backup was taken, so a TPM-bound encrypted volume such as BitLocker unlocks without a recovery prompt, including after a failover to the peer node.

An archive created by an earlier RVC version carries neither. The restore still succeeds, but if the VM has NVRAM or vTPM state on the node, RVC prints a warning before anything is changed, so the restore can still be cancelled. The state already on the node is left in place. Restoring an older disk under the current TPM state may prevent a TPM-bound encrypted volume from unlocking, and the VM may need its boot order set again. See Backing up and restoring your virtual machines.

The warning looks similar to the following:

This backup carries no UEFI variables of its own and no state for its emulated TPM. kvm1 keeps that off its disk, so the restore leaves what is on this host in place: it is not what the backup was taken from, and this archive cannot put it back.

In RVC 3.13.0, a restore does not preserve thin-provisioned disks. A thin disk is restored at its full file length, so the restored disk can take up more space on the node than the original did.

JSON-RPC Request

{"jsonrpc":"2.0","id":1,"method":"kvm.restore","params":{"hostname":"kvm1","filename":"/mnt/backups/kvm1-backup-1.tar.gz","ignore_snapshot_errors":false}}

Request Parameters

Argument	Type	Description	Required	Default
`hostname`	String	The name of the virtual machine.	Yes	-
`filename`	String	The path to the backup file.	Yes	-
`unsafe`	Boolean	Whether or not to allow the restore to proceed with no rescue copy of the current disk when no location has room for one. The disk is then overwritten in place, and a failed restore cannot be rolled back. The check for space to extract the archive still applies.	No	`false`
`ignore_snapshot_errors`	Boolean	Whether or not to proceed with the backup restoration even if there are snapshot errors.	No	`true`

JSON-RPC Response

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": "Restoring full backup /mnt/backups/kvm1-backup-1.tar.gz..."
}

RVC CLI Example

rvc kvm restore --hostname kvm1 --filename /mnt/backups/kvm1-backup-1.tar.gz

Response

Restoring full backup /mnt/backups/kvm1-backup-1.tar.gz...
Validating file /mnt/backups/kvm1-backup-1.tar.gz
Shutting down kvm1...
checking status 30...
checking status 29...
checking status 28...
checking status 27...
kvm1 successfully shut off.
Creating a rescue copy of /kvm/kvm1/disk0.qcow2 in /kvm/kvm1/rescue-data for safety.
The kvm1 disk rescue copy will be saved in /kvm/kvm1/rescue-data.
Restoring full backup /mnt/backups/kvm1-backup-1.tar.gz for kvm1
Full backup successfully restored.
Snapshot synchronization completed.
Starting kvm1...
checking status 30...
kvm1 successfully started.
Full backup restoration process finished.

Output for a cluster managed Virtual Machine:

Restoring full backup /mnt/backups/kvm1-backup-1.tar.gz...
Validating file /mnt/backups/kvm1-backup-1.tar.gz
Maintenance mode set to enabled.
Shutting down kvm1...
checking status 30...
checking status 29...
checking status 28...
checking status 27...
kvm1 successfully shut off.
Creating a rescue copy of /kvm/kvm1/disk0.qcow2 in /kvm/kvm1/rescue-data for safety.
The kvm1 disk rescue copy will be saved in /kvm/kvm1/rescue-data.
Restoring full backup /mnt/backups/kvm1-backup-1.tar.gz for kvm1
Full backup successfully restored.
Snapshot synchronization completed.
Starting kvm1...
checking status 30...
kvm1 successfully started.
Waiting for the refresh of all cluster VM resources statuses.
Maintenance mode set to disabled.
Full backup restoration process finished.