22 QEMU guest agent #
The QEMU guest agent (GA) runs inside the VM Guest and allows the
VM Host Server to run commands in the guest operating system via libvirt
. It
supports many functions—for example, getting details about guest file
systems, freezing and thawing file systems, or suspending or rebooting a
guest.
QEMU GA is included in the qemu-guest-agent package and is installed, configured and activated by default on KVM virtual machines.
QEMU GA is installed in Xen virtual machines, but it is not activated by default. Although it is possible to use QEMU GA with Xen virtual machines, there is no integration with libvirt as described below for KVM virtual machines. To use QEMU GA with Xen, a channel device must be added to the VM Guest configuration. The channel device includes a Unix domain socket path on the VM Host Server for communicating with QEMU GA.
<channel type='unix'> <source mode='bind' path='/example/path'/> <target type='xen' name='org.qemu.guest_agent.0'/> </channel>
22.1 Running QEMU GA commands #
QEMU GA includes many built-in commands that do not have direct
libvirt
counterparts. Refer to Section 22.4, “More information” to
find the complete list. You can run all the QEMU GA commands by using
libvirt
's general purpose command
qemu-agent-command
:
virsh qemu-agent-command DOMAIN_NAME '{"execute":"QEMU_GA_COMMAND"}'
For example:
>
sudo
virsh qemu-agent-command sle15sp2 '{"execute":"guest-info"}' --pretty { "return": { "version": "4.2.0", "supported_commands": [ { "enabled": true, "name": "guest-get-osinfo", "success-response": true }, [...]
22.2 virsh
commands that require QEMU GA #
Several virsh
commands require QEMU GA for their functionality. For
example, the following ones:
virsh guestinfo
Prints information about the guest from the guest's point of view.
virsh guestvcpus
Queries or changes the state of virtual CPUs from the guest's point of view.
virsh set-user-password
Sets the password for a user account in the guest.
virsh domfsinfo
Shows a list of mounted file systems within the running domain.
virsh dompmsuspend
Suspends a running guest.
22.3 Enhancing libvirt
commands #
If QEMU GA is enabled inside the guest, several virsh
subcommands
have enhanced functionality when run in the agent
mode. The following list includes only certain examples of them. For a
complete list, see the virsh
man page and search for the
agent
string.
virsh shutdown --mode agent
andvirsh reboot --mode agent
This method of shutting down or rebooting leaves the guest clean for its next run, similar to the ACPI method.
virsh domfsfreeze
andvirsh domfsthaw
Instructs the guest to make its file system quiescent—to flush all I/O operations in the cache and leave volumes in a consistent state, so that no checks are needed when they are remounted.
virsh setvcpus --guest
Changes the number of CPUs assigned to a guest.
virsh domifaddr --source agent
Queries the QEMU GA for the guest's IP address.
virsh vcpucount --guest
Prints information about the virtual CPU counts from the perspective of the guest.
22.4 More information #
A complete list of commands supported by the QEMU GA is at https://www.qemu.org/docs/master/interop/qemu-ga-ref.html.
The
virsh
man page (man 1 virsh
) includes descriptions of the commands that support the QEMU GA interface.