Re: [libvirt] [PATCH] docs: document <qemu:commandline> xml

Even though we technically don't support <qemu:commandline> (as in, if you mis-use things, you get to keep the pieces), we should at least document how to use it. * docs/drvqemu.html.in (qemucommand): New section. --- I wrote this in response to an IRC comment lamenting that the only existing documentation was reading the examples in the testsuite.

diff --git a/docs/drvqemu.html.in b/docs/drvqemu.html.in index 4da3817..d6effb5 100644 --- a/docs/drvqemu.html.in +++ b/docs/drvqemu.html.in @@ -513,6 +513,67 @@ $ virsh domxml-to-native qemu-argv demo.xml -serial none -parallel none -usb </pre> + <h2><a name="qemucommand">Pass-through of arbitrary qemu + commands</a></h2> + + <p>Libvirt provides an optional + library <code>libvirt-qemu.so</code> for dealing specifically + with qemu. This library is <b>unsupported</b>, in that it is + not guaranteed to have a stable API, and that mis-using the + library may result in inconsistent state the crashes libvirtd. + However, when used correctly, this library allows testing + specific qemu features that have not yet been ported to the + generic libvirt XML and API interfaces. + </p> + <p>The library provides two + API: <code>virDomainQemuMonitorCommand</code>, for sending an + arbitrary monitor command (in either HMP or QMP format) to a + qemu guest (<span class="since">Since 0.8.3</span>), + and <code>virDomainQemuAttach</code>, for registering a qemu + domain that was manually started so that it can then be managed + by libvirtd (<span class="since">Since 0.9.4</span>). + </p> + <p>Additionally, the following XML additions allow fine-tuning of + the command line given to qemu when starting a domain + (<span class="since">Since 0.8.3</span>). In order to use the + XML additions, it is necessary to issue an XML namespace request + (the special <code>xmlns:<i>name</i></code> attribute) that + pulls in <code>http://libirt.org/schemas/domain/qemu/1.0</code>; + typically, the namespace is given the name + of <code>qemu</code>. With the namespace in place, it is then + possible to add an element <code>&lt;qemu:commandline&gt;</code> + under <code>driver</code>, with the following sub-elements + repeated as often as needed: + <dl> + <dt><code>qemu:arg</code></dt> + <dd>Add an additional command-line argument to the qemu + process when starting the domain, given by the value of the + attribute <code>value</code>. + </dd> + <dt><code>qemu:env</code></dt> + <dd>Add an additional environment variable to the qemu + process when starting the domain, given with the name-value + pair recorded in the attributes <code>name</code> + and <code>value</code>.</dd> + </dl> + + <p>Example:</p><pre> +&lt;domain type='qemu' xmlns:qemu='http://libirt.org/schemas/domain/qemu/1.0'&gt; + &lt;name&gt;QEmu-fedora-i686&lt;/name&gt; + &lt;memory&gt;219200&lt;/memory&gt; + &lt;os&gt; + &lt;type arch='i686' machine='pc'&gt;hvm&lt;/type&gt; + &lt;/os&gt; + &lt;devices&gt; + &lt;emulator&gt;/usr/bin/qemu-system-x86_64&lt;/emulator&gt; + &lt;/devices&gt; + &lt;qemu:commandline&gt; + &lt;qemu:arg value='-newarg'/&gt; + &lt;qemu:env name='QEMU_ENV' value='VAL'/&gt; + &lt;/qemu:commandline&gt; +&lt;/domain&gt; +</pre> + <h2><a name="xmlconfig">Example domain XML config</a></h2> <h3>QEMU emulated guest on x86_64</h3>