> For the complete documentation index, see [llms.txt](https://docs.trilio.io/kubernetes/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trilio.io/kubernetes/appendix/platform-guides/custom-hook-execution-for-windows-vms.md). # 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`: ```yaml 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: name: windows-drivers-disk ``` Replace `` 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](https://catalog.redhat.com/software/containers/container-native-virtualization/virtio-win-rhel9/633ffae83be061d37b2770f6). 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.
Windows Device Manager listing Other devices with warning icons before VirtIO drivers are installed

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: ```powershell 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: ```bash kubectl get vmi -n \ -o jsonpath='{.status.conditions[?(@.type=="AgentConnected")].status}' ``` The expected output is: ``` True ``` You can also verify by inspecting the full VM status: ```bash kubectl get vmi -n -o yaml ``` Look for the following under `.status.conditions`: ```yaml 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](/kubernetes/appendix/platform-guides/openshift-virtualization.md#configuring-virtual-machine-custom-hook-execution-for-backups) (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](#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.