Difference between revisions of "Qemu Guest Agent Integration"

From stoney cloud
Jump to: navigation, search
[unchecked revision][unchecked revision]
(Created page with "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 connec...")
 
(→‎Getting list of available qemu-ga commands)
 
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
= 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.
 
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 =
 
= Libvirt =
Line 11: Line 21:
 
</channel>
 
</channel>
 
</syntaxhighlight>
 
</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]]
 
[[Category:Snippets]]

Latest revision as of 11:32, 12 March 2015

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 /var/lib/libvirt/qemu/channel/target/

Make sure that this directory exists and is protected: 

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/

The sockets are 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 do 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

VMNAME=<UUID>
virsh qemu-agent-command ${VMNAME} '{"execute":"guest-info"}'

Example: 

VMNAME=2d52c542-432b-42f1-95a7-5a152788fcd3
virsh qemu-agent-command ${VMNAME} '{"execute":"guest-info"}'

The return values will look something like: 

{"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}
  ]}
}

Links

Retrieved from "https://wiki.stoney-cloud.org/mediawiki/index.php?title=Qemu_Guest_Agent_Integration&oldid=4547"