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= virsh qemu-agent-command $VMNAME '{"execute":"guest-info"}'
Example:
~ # virsh qemu-agent-command bc58f697-1f21-4613-9f4d-469cdaff0621 '{"execute":"guest-info"}'Invalid language.
You need to specify a language like this: <source lang="html4strict">...</source>
Supported languages for syntax highlighting:
4cs, 6502acme, 6502kickass, 6502tasm, 68000devpac, abap, actionscript, actionscript3, ada, algol68, apache, applescript, apt_sources, arm, asm, asp, asymptote, autoconf, autohotkey, autoit, avisynth, awk, bascomavr, bash, basic4gl, bf, bibtex, blitzbasic, bnf, boo, c, c_loadrunner, c_mac, caddcl, cadlisp, cfdg, cfm, chaiscript, cil, clojure, cmake, cobol, coffeescript, cpp, cpp-qt, csharp, css, cuesheet, d, dcl, dcpu16, dcs, delphi, diff, div, dos, dot, e, ecmascript, eiffel, email, epc, erlang, euphoria, f1, falcon, fo, fortran, freebasic, freeswitch, fsharp, gambas, gdb, genero, genie, gettext, glsl, gml, gnuplot, go, groovy, gwbasic, haskell, haxe, hicest, hq9plus, html4strict, html5, icon, idl, ini, inno, intercal, io, j, java, java5, javascript, jquery, kixtart, klonec, klonecpp, latex, lb, ldif, lisp, llvm, locobasic, logtalk, lolcode, lotusformulas, lotusscript, lscript, lsl2, lua, m68k, magiksf, make, mapbasic, matlab, mirc, mmix, modula2, modula3, mpasm, mxml, mysql, nagios, netrexx, newlisp, nsis, oberon2, objc, objeck, ocaml, ocaml-brief, octave, oobas, oorexx, oracle11, oracle8, oxygene, oz, parasail, parigp, pascal, pcre, per, perl, perl6, pf, php, php-brief, pic16, pike, pixelbender, pli, plsql, postgresql, povray, powerbuilder, powershell, proftpd, progress, prolog, properties, providex, purebasic, pycon, pys60, python, q, qbasic, rails, rebol, reg, rexx, robots, rpmspec, rsplus, ruby, sas, scala, scheme, scilab, sdlbasic, smalltalk, smarty, spark, sparql, sql, stonescript, systemverilog, tcl, teraterm, text, thinbasic, tsql, typoscript, unicon, upc, urbi, uscript, vala, vb, vbnet, vedit, verilog, vhdl, vim, visualfoxpro, visualprolog, whitespace, whois, winbatch, xbasic, xml, xorg_conf, xpp, yaml, z80, zxbasic
{"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}
]}
}