10.3. Running the QEMU Guest Agent on a Windows Guest

download PDF
A Red Hat Enterprise Linux host machine can issue commands to Windows guests by running the QEMU guest agent in the guest. This is supported in hosts running Red Hat Enterprise Linux 6.5 and newer, and in the following Windows guest operating systems:
  • Windows XP Service Pack 3 (VSS is not supported)
  • Windows Server 2003 R2 - x86 and AMD64 (VSS is not supported)
  • Windows Server 2008
  • Windows Server 2008 R2
  • Windows 7 - x86 and AMD64
  • Windows Server 2012
  • Windows Server 2012 R2
  • Windows 8 - x86 and AMD64
  • Windows 8.1 - x86 and AMD64


Windows guest virtual machines require the QEMU guest agent package for Windows, qemu-guest-agent-win. This agent is required for VSS (Volume Shadow Copy Service) support for Windows guest virtual machines running on Red Hat Enterprise Linux. More information can be found here.

Procedure 10.2. Configuring the QEMU guest agent on a Windows guest

Follow these steps for Windows guests running on a Red Hat Enterprise Linux host machine.
  1. Prepare the Red Hat Enterprise Linux host machine

    Make sure the following package is installed on the Red Hat Enterprise Linux host physical machine:
    • virtio-win, located in /usr/share/virtio-win/
    To copy the drivers in the Windows guest, make an *.iso file for the qxl driver using the following command:
    # mkisofs -o /var/lib/libvirt/images/virtiowin.iso /usr/share/virtio-win/drivers
  2. Prepare the Windows guest

    Install the virtio-serial driver in guest by mounting the *.iso to the Windows guest in order to update the driver. Start the guest, then attach the driver .iso file to the guest as shown (using a disk named hdb):
    # virsh attach-disk guest /var/lib/libvirt/images/virtiowin.iso hdb
    To install the drivers using the Windows Control Panel, navigate to the following menus:
    • To install the virtio-win driver - Select Hardware and Sound > Device manager > virtio-serial driver.
  3. Update the Windows guest XML configuration file

    The guest XML file for the Windows guest is located on the Red Hat Enterprise Linux host machine. To gain access to this file, you need the Windows guest name. Use the # virsh list command on the host machine to list the guests that it can recognize. In this example, the guest's name is win7x86.
    Add the following elements to the XML file using the # virsh edit win7x86 command and save the changes. Note that the source socket name must be unique in the host, named win7x86.agent in this example:
      <channel type='unix'>
          <source mode='bind' path='/var/lib/libvirt/qemu/win7x86.agent'/>
          <target type='virtio' name='org.qemu.guest_agent.0'/>
          <address type='virtio-serial' controller='0' bus='0' port='1'/>
       <channel type='spicevmc'>
          <target type='virtio' name='com.redhat.spice.0'/>
          <address type='virtio-serial' controller='0' bus='0' port='2'/>

    Figure 10.2. Editing the Windows guest XML to configure the QEMU guest agent

  4. Reboot the Windows guest

    Reboot the Windows guest to apply the changes:
    # virsh reboot win7x86
  5. Prepare the QEMU guest agent in the Windows guest

    To prepare the guest agent in a Windows guest:
    1. Install the latest virtio-win package

      Run the following command on the Red Hat Enterprise Linux host physical machine terminal window to locate the file to install. Note that the file shown below may not be exactly the same as the one your system finds, but it should be latest official version.
      # rpm -qa|grep virtio-win
      # rpm -iv virtio-win-1.6.8-5.el6.noarch
    2. Confirm the installation completed

      After the virtio-win package finishes installing, check the /usr/share/virtio-win/guest-agent/ folder and you will find an file named qemu-ga-x64.msi or the qemu-ga-x86.msi as shown:
      # ls -l /usr/share/virtio-win/guest-agent/
      total 1544
      -rw-r--r--. 1 root root 856064 Oct 23 04:58 qemu-ga-x64.msi
      -rw-r--r--. 1 root root 724992 Oct 23 04:58 qemu-ga-x86.msi
    3. Install the .msi file

      From the Windows guest (win7x86, for example) install the qemu-ga-x64.msi or the qemu-ga-x86.msi by double clicking on the file. Once installed, it will be shown as a qemu-ga service in the Windows guest within the System Manager. This same manager can be used to monitor the status of the service.

10.3.1. Using libvirt Commands with the QEMU Guest Agent on Windows Guests

The QEMU guest agent can use the following virsh commands with Windows guests:
  • virsh shutdown --mode=agent - This shutdown method is more reliable than virsh shutdown --mode=acpi, as virsh shutdown used with the QEMU guest agent is guaranteed to shut down a cooperative guest in a clean state. If the agent is not present, libvirt has to instead rely on injecting an ACPI shutdown event, but some guests ignore that event and thus will not shut down.
    Can be used with the same syntax for virsh reboot.
  • virsh snapshot-create --quiesce - Allows the guest to flush its I/O into a stable state before the snapshot is created, which allows use of the snapshot without having to perform a fsck or losing partial database transactions. The guest agent allows a high level of disk contents stability by providing guest co-operation.
  • virsh dompmsuspend - Suspends a running guest gracefully using the guest operating system's power management functions.
Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.