Changes
/* Getting list of available qemu-ga commands */
= 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 =
</channel>
</syntaxhighlight>
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 exists and is protected:
<syntaxhighlight lang='xml'>
mkdir -p /var/lib/libvirt/qemu/channel/target/
chown root:qemu /var/lib/libvirt/qemu/channel/target/
chmod 770 /var/lib/libvirt/qemu/channel/target/
</syntaxhighlight>
The sockets are named <code>/var/lib/libvirt/qemu/channel/target/${VMNAME}.org.qemu.guest_agent.0</code>.
Please note: since libvirt will automatically listen on that socket one can not use a tool like <code>qemu-ga-client</code> to do anything on it, everything has to go via libvirt.
= VM =
In the VM one must install and start the <code>qemu-guest-agent</code>.
On Gentoo this means:
<syntaxhighlight lang='bash'>
emerge qemu-guest-agent
/etc/init.d/qemu-guest-agentqemu-guest-agent
rc-update add qemu-guest-agent default
</syntaxhighlight>
= 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 <code>shutdown -P</code> within the VM whereas with ACPI you won't even know whether the guest OS has received the event.
<syntaxhighlight lang='bash'>
virsh shutdown --mode agent $VMNAME
</syntaxhighlight>
'''Example:'''
<pre>
~ # virsh shutdown --mode agent bc58f697-1f21-4613-9f4d-469cdaff0621Domain bc58f697-1f21-4613-9f4d-469cdaff0621 is being shutdown
</pre>
== Manually ping qemu-ga via libvirt ==
Libvirt issues a <code>guest-sync</code> before any other command as a way to ensure availability of qemu-ga. Nevertheless it may be useful to run commands directly, like the <code>guest-ping</code>.
<syntaxhighlight lang='bash'>
virsh qemu-agent-command $VMNAME '{"execute":"guest-ping"}'
</syntaxhighlight>
'''Example:'''
<pre>
~ # virsh qemu-agent-command bc58f697-1f21-4613-9f4d-469cdaff0621 '{"execute":"guest-ping"}'
{"return":{}}
</pre>
== Getting list of available qemu-ga commands ==
<syntaxhighlight lang='bash'>
VMNAME=<UUID>
virsh qemu-agent-command ${VMNAME} '{"execute":"guest-info"}'
</syntaxhighlight>
'''Example:'''
<source lang="bash">
VMNAME=2d52c542-432b-42f1-95a7-5a152788fcd3
virsh qemu-agent-command ${VMNAME} '{"execute":"guest-info"}'
</source>
The return values will look something like:
<source lang="bash">
{"return":
{"version":"2.1.2","supported_commands":[
{"enabled":true,"name":"guest-set-vcpus","success-response":true},
{"enabled":true,"name":"guest-get-vcpus","success-response":true},
{"enabled":true,"name":"guest-network-get-interfaces","success-response":true},
{"enabled":true,"name":"guest-suspend-hybrid","success-response":false},
{"enabled":true,"name":"guest-suspend-ram","success-response":false},
{"enabled":true,"name":"guest-suspend-disk","success-response":false},
{"enabled":true,"name":"guest-fstrim","success-response":true},
{"enabled":true,"name":"guest-fsfreeze-thaw","success-response":true},
{"enabled":true,"name":"guest-fsfreeze-freeze","success-response":true},
{"enabled":true,"name":"guest-fsfreeze-status","success-response":true},
{"enabled":true,"name":"guest-file-flush","success-response":true},
{"enabled":true,"name":"guest-file-seek","success-response":true},
{"enabled":true,"name":"guest-file-write","success-response":true},
{"enabled":true,"name":"guest-file-read","success-response":true},
{"enabled":true,"name":"guest-file-close","success-response":true},
{"enabled":true,"name":"guest-file-open","success-response":true},
{"enabled":true,"name":"guest-shutdown","success-response":false},
{"enabled":true,"name":"guest-info","success-response":true},
{"enabled":true,"name":"guest-set-time","success-response":true},
{"enabled":true,"name":"guest-get-time","success-response":true},
{"enabled":true,"name":"guest-ping","success-response":true},
{"enabled":true,"name":"guest-sync","success-response":true},
{"enabled":true,"name":"guest-sync-delimited","success-response":true}
]}
}
</source>
= Links =
* http://wiki.libvirt.org/page/Qemu_guest_agent
* http://wiki.qemu.org/Features/QAPI/GuestAgent
[[Category:Snippets]]
