Search
SupportConsoleDevelopersStart a trialContact

Chapter 5. Enabling QEMU Guest Agent features on your virtual machines

download PDF

To use certain features on a virtual machine (VM) hosted on your RHEL 8 system, you must first configure the VM to use the QEMU Guest Agent (GA).

For a complete list of these features, see Virtualization features that require QEMU Guest Agent.

The specific steps required to configure QEMU GA on a VM differ based on the guest operating system used by the VM:

5.1. Enabling QEMU Guest Agent on Linux guests

To allow a RHEL host to perform a certain subset of operations on a Linux virtual machine (VM), you must enable the QEMU Guest Agent (GA).

You can enable QEMU GA both on running and shut-down VMs.

Procedure

  1. Create an XML configuration file for the QEMU GA, for example named qemuga.xml: 

    # touch qemuga.xml

  2. Add the following lines to the file: 

    <channel type='unix'>
   <source mode='bind' path='/var/lib/libvirt/qemu/f16x86_64.agent'/>
   <target type='virtio' name='org.qemu.guest_agent.0'/>
</channel>

  3. Use the XML file to add QEMU GA to the configuration of the VM.

    • If the VM is running, use the following command: 

      # virsh attach-device <vm-name> qemuga.xml --live --config

    • If the VM is shut-down, use the following command: 

      # virsh attach-device <vm-name> qemuga.xml --config

  4. In the Linux guest operating system, install the QEMU GA: 

    # yum install qemu-guest-agent

  5. Start the QEMU GA service on the guest: 

    # systemctl start qemu-guest-agent

Verification

To ensure that QEMU GA is enabled and running on the Linux VM, do any of the following:

  • In the guest operating system, use the systemctl status qemu-guest-agent | grep Loaded command. If the output includes enabled, QEMU GA is active on the VM.
  • Use the virsh domfsinfo <vm-name> command on the host. If it displays any output, QEMU GA is active on the specified VM.

Additional resources

5.2. Enabling QEMU Guest Agent on Windows guests

To allow a RHEL host to perform a certain subset of operations on a Windows virtual machine (VM), you must enable the QEMU Guest Agent (GA). To do so, add a storage device that contains the QEMU Guest Agent installer to an existing VM or when creating a new VM, and install the drivers on the Windows guest operating system.

To install the Guest Agent (GA) by using the graphical interface, see the procedure below. To install the GA in a command-line interface, use the Microsoft Windows Installer (MSI).

Prerequisites

Procedure

  1. In the Windows guest operating system, open the File Explorer application.
  2. Click This PC.
  3. In the Devices and drives pane, open the virtio-win medium.
  4. Open the guest-agent folder.

  5. Based on the operating system installed on the VM, run one of the following installers:

    • If using a 32-bit operating system, run the qemu-ga-i386.msi installer.
    • If using a 64-bit operating system, run the qemu-ga-x86_64.msi installer.
  6. Optional: If you want to use the para-virtualized serial driver (virtio-serial) as the communication interface between the host and the Windows guest, verify that the virtio-serial driver is installed on the Windows guest. For more information about installing virtio drivers, see: Installing virtio drivers on a Windows guest.

Verification

  1. On your Windows VM, navigate to the Services window.

    Computer Management > Services

  2. Ensure that the status of the QEMU Guest Agent service is Running.

Additional resources

5.3. Virtualization features that require QEMU Guest Agent

If you enable QEMU Guest Agent (GA) on a virtual machine (VM), you can use the following commands on your host to manage the VM:

virsh shutdown --mode=agent
This shutdown method is more reliable than virsh shutdown --mode=acpi, because virsh shutdown used with QEMU GA is guaranteed to shut down a cooperative guest in a clean state.
virsh domfsfreeze and virsh domfsthaw
Freezes the guest file system in isolation.
virsh domfstrim

Instructs the guest to trim its file system, which helps to reduce the data that needs to be transferred during migrations.

Important

If you want to use this command to manage a Linux VM, you must also set the following SELinux boolean in the guest operating system: 

# setsebool virt_qemu_ga_read_nonsecurity_files on
virsh domtime
Queries or sets the guest’s clock.
virsh setvcpus --guest
Instructs the guest to take CPUs offline, which is useful when CPUs cannot be hot-unplugged.
virsh domifaddr --source agent
Queries the guest operating system’s IP address by using QEMU GA. For example, this is useful when the guest interface is directly attached to a host interface.
virsh domfsinfo
Shows a list of mounted file systems in the running guest.
virsh set-user-password
Sets the password for a given user account in the guest.
virsh set-user-sshkeys

Edits the authorized SSH keys file for a given user in the guest.

Important

If you want to use this command to manage a Linux VM, you must also set the following SELinux boolean in the guest operating system: 

# setsebool virt_qemu_ga_manage_ssh on

Additional resources

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

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.