11.2. Using the QEMU Guest Agent with libvirt

download PDF
Installing the QEMU guest agent allows various libvirt commands to become more powerful. The guest agent enhances the following virsh commands:
  • 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 must 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 domfsfreeze and virsh domfsthaw - Quiesces the guest filesystem in isolation.
  • virsh domfstrim - Instructs the guest to trim its filesystem.
  • virsh domtime - Queries or sets the guest's clock.
  • virsh setvcpus --guest - Instructs the guest to take CPUs offline.
  • virsh domifaddr --source agent - Queries the guest operating system's IP address via the guest agent.
  • virsh domfsinfo - Shows a list of mounted filesystems within the running guest.
  • virsh set-user-password - Sets the password for a user account in the guest.

11.2.1. Creating a Guest Disk Backup

libvirt can communicate with qemu-guest-agent to ensure that snapshots of guest virtual machine file systems are consistent internally and ready to use as needed. Guest system administrators can write and install application-specific freeze/thaw hook scripts. Before freezing the filesystems, the qemu-guest-agent invokes the main hook script (included in the qemu-guest-agent package). The freezing process temporarily deactivates all guest virtual machine applications.
The snapshot process is comprised of the following steps:
  • File system applications / databases flush working buffers to the virtual disk and stop accepting client connections
  • Applications bring their data files into a consistent state
  • Main hook script returns
  • qemu-guest-agent freezes the filesystems and the management stack takes a snapshot
  • Snapshot is confirmed
  • Filesystem function resumes
Thawing happens in reverse order.
To create a snapshot of the guest's file system, run the virsh snapshot-create --quiesce --disk-only command (alternatively, run virsh snapshot-create-as guest_name --quiesce --disk-only, explained in further detail in Section 20.39.2, “Creating a Snapshot for the Current Guest Virtual Machine”).


An application-specific hook script might need various SELinux permissions in order to run correctly, as is done when the script needs to connect to a socket in order to talk to a database. In general, local SELinux policies should be developed and installed for such purposes. Accessing file system nodes should work out of the box, after issuing the restorecon -FvvR command listed in Table 11.1, “QEMU guest agent package contents” in the table row labeled /etc/qemu-ga/fsfreeze-hook.d/.
The qemu-guest-agent binary RPM includes the following files:
Table 11.1. QEMU guest agent package contents
File name Description
/usr/lib/systemd/system/qemu-guest-agent.service Service control script (start/stop) for the QEMU guest agent.
/etc/sysconfig/qemu-ga Configuration file for the QEMU guest agent, as it is read by the /usr/lib/systemd/system/qemu-guest-agent.service control script. The settings are documented in the file with shell script comments.
/usr/bin/qemu-ga QEMU guest agent binary file.
/etc/qemu-ga Root directory for hook scripts.
/etc/qemu-ga/fsfreeze-hook Main hook script. No modifications are needed here.
/etc/qemu-ga/fsfreeze-hook.d Directory for individual, application-specific hook scripts. The guest system administrator should copy hook scripts manually into this directory, ensure proper file mode bits for them, and then run restorecon -FvvR on this directory.
/usr/share/qemu-kvm/qemu-ga/ Directory with sample scripts (for example purposes only). The scripts contained here are not executed.
The main hook script, /etc/qemu-ga/fsfreeze-hook logs its own messages, as well as the application-specific script's standard output and error messages, in the following log file: /var/log/qemu-ga/fsfreeze-hook.log. For more information, see the libvirt upstream website.
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.