Backing up Hyper-V VMs (bkp_hyperV)

Go to the contents

bkp_hyperV backs up a VM under Hyper-V as one VM run: all virtual hard disks, the configuration and the state files of the VM, so for a VM with vTPM also its state. The basis is a recovery checkpoint, as Microsoft provides it for backup programs: the VM keeps running during the backup. After the first backup bkp_hyperV only reads the areas that have changed since then (Resilient Change Tracking, RCT); the store takes over unchanged parts from the previous run without reading them.

bkp_hyperV_restore creates a new VM from a VM run (new VM ID, switched off) or restores single virtual hard disks as new VHDX files. Existing VMs and files are never changed in the process.

20.1 Requirements#

• Windows Server 2016 or newer with the Hyper-V role; the backup runs on the host, not in the guest.
• The components hyperv, agent and restore (Chapter 2). The setup only offers hyperv if the Hyper-V role is installed.
• For application-consistent backups the integration service “Backup (volume shadow copy)” in the guest (for Linux guests hv_vss_daemon). Without it the backup is crash-consistent, as after a power failure; log and result say so.
• A single host. Failover clusters with CSV, pass-through disks, shared VHDX and shielded VMs are not supported yet.

20.2 Backing up#

Backing up a VM (destinations from sinks.cfg, Chapter 4)

bkp_hyperV --vm dc01 --sink rz1
bkp_hyperV --vm dc01 --disk scsi0-0 -- --sink rz1 --sink local

Course of a run: bkp_hyperV creates the checkpoint “cybackup <name>”, reads its configuration, attaches every virtual hard disk of the checkpoint read-only and lets bkp_agent read only the changed areas. Then follow the files of the VM (vmcx, vmgs, vmrs). Once the VM run is stored, the checkpoint becomes the reference point for the next backup; older reference points of this backup name are removed. If the run fails or is cancelled, bkp_hyperV deletes the checkpoint, and the previous reference point stays the basis.

A disk is read completely without a reference point (first backup), after the disk has been enlarged, after a migration or a storage move of the VM and with --full. The log names the reason plainly; this is not an error.

If a volume in the guest is encrypted with BitLocker, bkp_hyperV cannot see from outside which space in it is free: the first time the volume is read as far as the VHDX contains data, after that as always only the changed areas. Encrypted data can neither be compressed nor deduplicated; in the store it takes up about as much as in the VHDX.

20.3 Settings per VM and job in the scheduler#

%ProgramData%\AegisGrid\bkp_hyperv.cfg

[dc01]
vm=dc01
consistency=app
sinks=rz1,local
retention=30d

With this section bkp_hyperV --name dc01 is enough. Destinations, certificates and keys are in sinks.cfg as for the agent. The backup is planned in the job scheduler with command=hyperv; the profile name goes to bkp_hyperV as --name:

%ProgramData%\AegisGrid\bkp_sched.cfg

[dc01-nightly]
command=hyperv
profile=dc01
schedule=0 1 * * *

In the management console the command is called “Back up a Hyper-V VM (bkp_hyperV)”; the field “Further parameters” takes for example --vm dc01 if the profile names no VM. The notification mail and the run list of the API name per run disks, files of the VM and the consistency reached. If a job is cancelled, the scheduler removes the checkpoint afterwards (--discard-interrupted); the VM stays unchanged.

20.4 Restoring#

Restoring a VM as a new VM

bkp_hyperV_restore --name dc01 --dest D:\VMs --dry-run
bkp_hyperV_restore --name dc01 --dest D:\VMs
bkp_hyperV_restore --name dc01 --at "2026-10-19 22:00" --switch LAN=LAN-Test --new-name dc01-test

The new VM is called <name>_bkp01, at the next restore <name>_bkp02 and so on (the first free number); --new-name sets another name, a name already in use is refused. Under --dest the folder of the VM is created with “Virtual Machines” and “Virtual Hard Disks”. Boot order, Secure Boot, CPU, memory and the vTPM state come along. The VM stays switched off so that network and settings can be checked before the first start.

If a restore is cancelled, bkp_hyperV_restore removes everything it has created. A single disk also works with bkp_restore --disk scsi0-0 (Chapter 7); bkp_restore --disk vmgs gets back a single file of the VM.

20.5 vTPM and guardian#

The vTPM state of a VM is encrypted with its key protector. Only a host that has the certificates of a guardian of this key protector including the private key can open it, on a single host its own guardian “UntrustedGuardian” in the certificate store “Shielded VM Local Certificates” of the local computer. On the host on which the backup was made, the restored VM therefore starts with its TPM; a guest with BitLocker needs no recovery key.

bkp_hyperV_restore checks before the first step whether the host has a guardian of the VM, and names it in the log. If it is missing, the restore creates nothing and says what to do. Without the certificates Hyper-V could not start the VM (“The key protector could not be unwrapped”).

• Preparing for a total failure: bkp_hyperV --with-guardian (in the profile with-guardian=yes) backs up the two certificates of the guardian with private key as the fourth file of the VM (guardian). Because every VM of this guardian can be opened with them, this only works into encrypted sinks (encryption= and key= in sinks.cfg, Chapter 4). If a sink is unencrypted, bkp_hyperV backs up nothing and says which one; the VM stays untouched.
• Restoring on a new host: bkp_hyperV_restore --import-guardian first takes the backed-up certificates over into the certificate store and then creates the VM. The certificates stay there; afterwards they also open the other backed-up VMs of the same guardian. The host's own guardian stays unchanged.
• Certificates by hand: whoever keeps them themselves (PFX with private key) imports them into “Shielded VM Local Certificates” of the local computer and then restores as usual.
• --without-guardian creates the VM anyway, for example to get at its data; it can only be started with the certificates.

Backing up the guardian too and taking it over on a new host

bkp_hyperV --vm dc01 --with-guardian -- --sink rz1-encrypted
bkp_hyperV_restore --name dc01 --sink rz1-encrypted --import-guardian