QEMU Guest Agent on Windows VMs for Application-Consistent Backups

Install and configure the QEMU Guest Agent on Windows VMs so Trilio for Kubernetes can run freeze/unfreeze custom hooks for application-consistent backups.

Overview

Trilio for Kubernetes (T4K) uses custom hooks to perform application-consistent backups of KubeVirt Virtual Machines. During a backup, T4K automatically executes freeze (quiesce) and unfreeze (unquiesce) operations on the VM's filesystems through the QEMU Guest Agent. This ensures that the data captured in the snapshot is in a consistent state.

On Linux VMs, the QEMU Guest Agent is typically pre-installed or easily available through package managers, and the freeze/unfreeze operations work out of the box. On Windows VMs, however, the QEMU Guest Agent is not installed by default. Without it, T4K cannot communicate with the guest OS, and the freeze/unfreeze operations will fail.

This guide walks through the steps required to install and configure the QEMU Guest Agent on Windows VMs running in KubeVirt, so that T4K can perform freeze/unfreeze operations during backups.

Prerequisites

• A KubeVirt cluster with Windows VM support

• Trilio for Kubernetes (T4K) installed

• A Windows VM with the VirtIO drivers disk attached as a CD-ROM volume

• Access to the Windows VM console (via VNC or RDP)

How Custom Hooks Work on VMs

When T4K runs a backup that includes a KubeVirt VirtualMachine, the following happens:

1. T4K checks whether the QEMU Guest Agent is connected by looking for the AgentConnected condition on the VM's status.

2. If the agent is connected, T4K issues a freeze command to the VM via the KubeVirt subresource API before taking volume snapshots. This tells the guest OS to flush its filesystem buffers and pause I/O, producing a crash-consistent (and often application-consistent) snapshot.

3. After the volume snapshots are taken, T4K issues an unfreeze command to resume normal I/O on the VM.

If the QEMU Guest Agent is not connected, T4K logs a warning and skips the freeze/unfreeze operations. The backup still proceeds, but the resulting snapshot may not be application-consistent.

The following steps walk through setting up the QEMU Guest Agent on a Windows VM so that T4K can perform freeze/unfreeze operations during backups.

Step 1: Attach the VirtIO Drivers Disk

Your Windows VM specification must include the VirtIO drivers disk as a volume. This disk contains the QEMU Guest Agent installer and the VirtIO Serial Driver, both of which are required.

Add the following to your VirtualMachine spec under volumes and devices.disks:

spec:
  template:
    spec:
      domain:
        devices:
          disks:
            - bootOrder: 2
              cdrom:
                bus: sata
              name: windows-drivers-disk
      volumes:
        - containerDisk:
            image: registry.redhat.io/container-native-virtualization/virtio-win-rhel9@sha256:<digest>
          name: windows-drivers-disk

Replace <digest> with the appropriate image digest for your environment. You can find the available image tags and digests on the Red Hat Ecosystem Catalog — virtio-win-rhel9. The image provides the full set of VirtIO drivers and the QEMU Guest Agent installer for Windows guests.

Step 2: Install the QEMU Guest Agent

1. Boot into the Windows VM and open File Explorer.

2. Navigate to the attached virtio-win CD drive.

3. Open the guest-agent folder.

4. Run the installer:

   • For 64-bit Windows: qemu-ga-x64.msi

   • For 32-bit Windows: qemu-ga-x86.msi

5. Complete the installation wizard.

6. Open Services (services.msc) and verify that the QEMU Guest Agent service is:

   • Startup type: Automatic

   • Status: Running

Note: At this point, the service is running but cannot yet communicate with the KubeVirt host. The AgentConnected condition will not appear on the VM status until the VirtIO Serial Driver is also installed.

Step 3: Install the VirtIO Serial Driver

The VirtIO Serial Driver provides the communication channel (virtio-serial port) between the QEMU Guest Agent inside the VM and the KubeVirt host.

Device Manager showing devices under Other devices that still need drivers (for example PCI Device, PCI Simple Communications Controller, or SCSI Controller)

1. Open Device Manager inside the Windows VM.

2. Look for a device with a yellow warning icon under Other devices — for example PCI Serial Port, PCI Simple Communications Controller, PCI Device, SCSI Controller, or Unknown device.

3. Right-click the device and select Update driver.

4. Choose Browse my computer for drivers.

5. Point the file browser to the attached virtio-win CD drive.

6. Check Include subfolders.

7. Click Next to install the VirtIO Serial Driver.

Step 4: Restart the QEMU Guest Agent Service

After the VirtIO Serial Driver is installed, restart the QEMU Guest Agent service so it binds to the newly available serial port:

Restart-Service qemu-ga

Step 5: Verify the Agent Connection

Once both the QEMU Guest Agent and the VirtIO Serial Driver are installed and running, KubeVirt establishes communication with the guest. Verify this by checking the AgentConnected condition on the VirtualMachineInstance:

kubectl get vmi <vm-name> -n <namespace> \
  -o jsonpath='{.status.conditions[?(@.type=="AgentConnected")].status}'

The expected output is:

True

You can also verify by inspecting the full VM status:

kubectl get vmi <vm-name> -n <namespace> -o yaml

Look for the following under .status.conditions:

status:
  conditions:
    - lastProbeTime: "2025-08-28T11:20:03Z"
      lastTransitionTime: null
      status: "True"
      type: AgentConnected

Running a Backup

Once the QEMU Guest Agent is connected, no additional configuration is needed. T4K automatically detects KubeVirt VirtualMachines in your BackupPlan and executes freeze/unfreeze operations during the backup. You do not need to create a separate Hook CR or set a hookConfig on the BackupPlan — the freeze/unfreeze operations are triggered automatically when the AgentConnected condition is True.

Note (Windows and VSS): On Windows, the freeze operation uses the Volume Shadow Copy Service (VSS) through a helper in the QEMU Guest Agent. According to the QEMU Guest Agent documentation, the frozen state is limited to a maximum of about 10 seconds; after that, the Windows VM may automatically unfreeze. If an unfreeze runs after Windows has already unfrozen, you may see log messages that fsfreeze is limited to about 10 seconds. That does not by itself mean the backup failed—the volume snapshot is usually already taken while the guest was frozen.

Disabling custom hook execution for a VM

To turn off freeze/unfreeze (custom hook execution) for a specific VirtualMachine, use the annotation and guidance documented in Backup and Restore Virtual Machines running on OpenShift (section Configuring Virtual Machine Custom Hook Execution for Backups).

Troubleshooting

Symptom	Cause	Resolution
AgentConnected condition is missing from VM status	QEMU Guest Agent is not installed, or the VirtIO Serial Driver is missing	Follow Steps 2–4 above
Freeze operation fails with "QEMU guest agent is not connected"	The agent service is not running, or the serial driver is not installed	Verify the service is running (Get-Service qemu-ga) and the VirtIO Serial Driver is installed
Unfreeze or hook status mentions fsfreeze limited to 10 seconds	Windows VSS limits how long the guest stays frozen; Windows may auto-unfreeze before T4K’s unfreeze runs	See the Note (Windows and VSS) under Running a Backup. The backup can still complete successfully
Hook status shows Failed with retry attempts	Transient communication failure between host and guest agent	T4K retries automatically (default: 3 attempts). Check that the VM is running and the agent service is healthy
Warning: "QEMUGuestAgent is not connected" in backup status	Agent not connected at backup time	Install and configure the QEMU Guest Agent per this guide. The backup proceeds without freeze/unfreeze, but consistency is not guaranteed

Summary

To set up the QEMU Guest Agent on a Windows VM in KubeVirt so that T4K can perform freeze/unfreeze operations:

1. Attach the VirtIO drivers disk to the VM.

2. Install the QEMU Guest Agent from the drivers disk.

3. Install the VirtIO Serial Driver through Device Manager.

4. Restart the QEMU Guest Agent service.

5. Verify the AgentConnected condition shows True.

After completing these steps, T4K will automatically perform application-consistent backups of your Windows VMs using the freeze/unfreeze mechanism through the QEMU Guest Agent.