From 60f99824d4edc3dbb64b600942c3e2f1c35f1ff9 Mon Sep 17 00:00:00 2001 From: Eric Blake Date: Mon, 19 Dec 2011 11:48:04 -0700 Subject: [PATCH] docs: document xml Even though we technically don't support (as in, if you mis-use things, you get to keep the pieces), we should at least document how to use it. [See also http://berrange.com/posts/2011/12/19/using-command-line-arg-monitor-command-passthrough-with-libvirt-and-kvm/] * docs/drvqemu.html.in (qemucommand): New section. --- docs/drvqemu.html.in | 67 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/docs/drvqemu.html.in b/docs/drvqemu.html.in index 4da3817648..fa5496c877 100644 --- a/docs/drvqemu.html.in +++ b/docs/drvqemu.html.in @@ -513,6 +513,73 @@ $ virsh domxml-to-native qemu-argv demo.xml -serial none -parallel none -usb +

Pass-through of arbitrary qemu + commands

+ +

Libvirt provides an XML namespace and an optional + library libvirt-qemu.so for dealing specifically + with qemu. When used correctly, these extensions allow testing + specific qemu features that have not yet been ported to the + generic libvirt XML and API interfaces. However, they + are unsupported, in that the library is not guaranteed to + have a stable API, abusing the library or XML may result in + inconsistent state the crashes libvirtd, and upgrading either + qemu-kvm or libvirtd may break behavior of a domain that was + relying on a qemu-specific pass-through. If you find yourself + needing to use them to access a particular qemu feature, then + please post an RFE to the libvirt mailing list to get that + feature incorporated into the stable libvirt XML and API + interfaces. +

+

The library provides two + API: virDomainQemuMonitorCommand, for sending an + arbitrary monitor command (in either HMP or QMP format) to a + qemu guest (Since 0.8.3), + and virDomainQemuAttach, for registering a qemu + domain that was manually started so that it can then be managed + by libvirtd (Since 0.9.4). +

+

Additionally, the following XML additions allow fine-tuning of + the command line given to qemu when starting a domain + (Since 0.8.3). In order to use the + XML additions, it is necessary to issue an XML namespace request + (the special xmlns:name attribute) that + pulls in http://libirt.org/schemas/domain/qemu/1.0; + typically, the namespace is given the name + of qemu. With the namespace in place, it is then + possible to add an element <qemu:commandline> + under driver, with the following sub-elements + repeated as often as needed: +

+
qemu:arg
+
Add an additional command-line argument to the qemu + process when starting the domain, given by the value of the + attribute value. +
+
qemu:env
+
Add an additional environment variable to the qemu + process when starting the domain, given with the name-value + pair recorded in the attributes name + and optional value.
+
+ +

Example:

+<domain type='qemu' xmlns:qemu='http://libirt.org/schemas/domain/qemu/1.0'>
+  <name>QEmu-fedora-i686</name>
+  <memory>219200</memory>
+  <os>
+    <type arch='i686' machine='pc'>hvm</type>
+  </os>
+  <devices>
+    <emulator>/usr/bin/qemu-system-x86_64</emulator>
+  </devices>
+  <qemu:commandline>
+    <qemu:arg value='-newarg'/>
+    <qemu:env name='QEMU_ENV' value='VAL'/>
+  </qemu:commandline>
+</domain>
+
+

Example domain XML config

QEMU emulated guest on x86_64

-- GitLab