Language and Page Formatting Options
11.2. Using the QEMU Guest Agent with libvirt
Installing the QEMU guest agent allows various libvirt commands to become more powerful. The guest agent enhances the following
virsh shutdown --mode=agent- This shutdown method is more reliable than
virsh shutdown --mode=acpi, as
virsh shutdownused 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 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 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-onlycommand (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 -FvvRcommand listed in Table 11.1, “QEMU guest agent package contents” in the table row labeled
The qemu-guest-agent binary RPM includes the following files:
Table 11.1. QEMU guest agent package contents
| ||Service control script (start/stop) for the QEMU guest agent.|
| || Configuration file for the QEMU guest agent, as it is read by the |
| ||QEMU guest agent binary file.|
| ||Root directory for hook scripts.|
| ||Main hook script. No modifications are needed here.|
| || 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 |
| ||Directory with sample scripts (for example purposes only). The scripts contained here are not executed.|
The main hook script,
/etc/qemu-ga/fsfreeze-hooklogs 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.