Revision as of 09:56, 13 September 2013

Abstract

The Qemu Guest Agent permits access to a VM via a virtual serial socket. This has the advantage that the VM can be accessed via the VM node (hypervisor) without network connection or remote desktop protocol.

This is a requirement to be able to take disk-only-snapshots without downtime by issueing a disk-freeze (shadow-copy) within the guest prior to taking the snapshot.

Furthermore it is useful for orchestrating CPU and memory hotplugging:

• guest OS must be told to enable CPU/memory after hot-plug
• guest OS must release a CPU/memory prior to hot-unplug

Libvirt

The XML must be amended by the following XML snippet in the devices section:

<channel type="unix">
  <source mode="bind"/>
  <target type="virtio" name="org.qemu.guest_agent.0"/>
</channel>

This will create a new virtual serial device within the VM and a new socket under code>/var/lib/libvirt/qemu/channel/target/</code> (make sure that this directory is protected!) named /var/lib/libvirt/qemu/channel/target/${VMNAME}.org.qemu.guest_agent.0.

Please note: since libvirt will automatically listen on that socket one can not use a tool like qemu-ga-client to anything on it, everything has to go via libvirt.

VM

In the VM one must install and start the qemu-guest-agent.

On Gentoo this means:

emerge qemu-guest-agent
/etc/init.d/qemu-guest-agentqemu-guest-agent
rc-update add qemu-guest-agent default

Test

See the links for an example on how to read a file (it is non-trivial and the returned content is base64-encoded, so it must be scripted and there is no point in duplicating it here).

Shutdown a VM via qemu-ga

The advantage of using qemu-ga instead of the ACPI-based mechanism to shutdown a VM is that you get a confirmation if the qemu-ga was able to issue shutdown -P within the VM whereas with ACPI you won't even know whether the guest OS has received the event.

virsh shutdown --mode agent $VMNAME

Example:

~ # virsh shutdown --mode agent bc58f697-1f21-4613-9f4d-469cdaff0621Domain bc58f697-1f21-4613-9f4d-469cdaff0621 is being shutdown

Manually ping qemu-ga via libvirt

Libvirt issues a guest-sync before any other command as a way to ensure availability of qemu-ga. Nevertheless it may be useful to run commands directly, like the guest-ping.

virsh qemu-agent-command $VMNAME '{"execute":"guest-ping"}'

Example:

~ # virsh qemu-agent-command bc58f697-1f21-4613-9f4d-469cdaff0621 '{"execute":"guest-ping"}'

{"return":{}}

Getting list of available qemu-ga commands

virsh qemu-agent-command $VMNAME '{"execute":"guest-info"}'

Example:

~ # virsh qemu-agent-command bc58f697-1f21-4613-9f4d-469cdaff0621 '{"execute":"guest-info"}'
{"return":
  {"version":"1.5.2","supported_commands":[
    {"enabled":true,"name":"guest-set-vcpus"},
    {"enabled":true,"name":"guest-get-vcpus"},
    {"enabled":true,"name":"guest-network-get-interfaces"},
    {"enabled":true,"name":"guest-suspend-hybrid"},
    {"enabled":true,"name":"guest-suspend-ram"},
    {"enabled":true,"name":"guest-suspend-disk"},
    {"enabled":true,"name":"guest-fstrim"},
    {"enabled":true,"name":"guest-fsfreeze-thaw"},
    {"enabled":true,"name":"guest-fsfreeze-freeze"},
    {"enabled":true,"name":"guest-fsfreeze-status"},
    {"enabled":true,"name":"guest-file-flush"},
    {"enabled":true,"name":"guest-file-seek"},
    {"enabled":true,"name":"guest-file-write"},
    {"enabled":true,"name":"guest-file-read"},
    {"enabled":true,"name":"guest-file-close"},
    {"enabled":true,"name":"guest-file-open"},
    {"enabled":true,"name":"guest-shutdown"},
    {"enabled":true,"name":"guest-info"},
    {"enabled":true,"name":"guest-set-time"},
    {"enabled":true,"name":"guest-get-time"},
    {"enabled":true,"name":"guest-ping"},
    {"enabled":true,"name":"guest-sync"},
    {"enabled":true,"name":"guest-sync-delimited"} ]
  }
}

Links

• http://wiki.libvirt.org/page/Qemu_guest_agent
• http://wiki.qemu.org/Features/QAPI/GuestAgent