[libvirt] Libvirt debug API

Chris Lalancette clalance at redhat.com
Fri Apr 9 18:16:06 UTC 2010

On 04/09/2010 10:27 AM, Daniel P. Berrange wrote:
> The concept of command line & monitor is something that is QEMU specific
> and thus is not suitable for the primary XML schema. IMHO, this needs to be
> done as a separate schema, linked in via an XML namespace. For example
>   <domain type='kvm' xmlns:qemu="http://libvirt.org/schemas/domain/qemu/1.0">
>     <name>myguest</name>
>     ...
>     <qemu:commandline>
>       <qemu:arg>-device</arg>
>       <qemu:arg>lsi</arg>
>     </qemu:commandline>
>   </domain>

This is a very good idea.  I didn't really know about namespaces, but now
that you've pointed them out I think this is a great way to partition it up.
I'll start looking at this.

>> Raw access to the qemu monitor will be disabled by default; the
>> <monitorpassthrough/> tag enables the ability to send QMP (or
>> text, if you are using older qemu) messages straight through to the
>> monitor.  To do this there will be an additional API entry point
>> named virDomainDebugCommand() which takes an arbitrary string
>> and passes it to the monitor, and returns an arbitrary string as
>> a result.  Thus you could pass in either "info cpus" if using the
>> text monitor or '{ "execute": "query-cpus" }' if using QMP.
> Again the idea of a 'virDomainDebugCommand' API is QEMU specific, with
> other hypervisors have different approaches for low level extension/
> debug. For example, Xen would involve XenStore access, or XenD XMLRPC,
> etc. So this should really live in a separate API namespace which is
> specific to a hypervisor. For example, as a header file
>   #include <libvirt/libvirt-qemu.h>
> Containing APIs like
>   int virDomainQEMUInvokeMonitor(virDomainPtr dom,
>                                  const char *command,
>                                  char **reply);
>   typedef virConnectQEMUDomainEventCallback(virConnectPtr conn,
>                                             virDomainPtr dom, 
>                                             const char *eventname,
>                                             const char *data,
>                                             void *opaque)
>   int virConnectQEMUDomainEventRegister(virConnectPtr conn,
>                                         virDomainPtr dom,
>                                         const char *eventname,
>                                         virDomainQEMUMonitorCallback cb,
>                                         void *opaque);
> For an add-on library
>   libvirt-qemu.so
> I don't think there's much to be gained from having an XML element to
> turn on/off use of these APIs. If an app doesn't want to use them, it
> can simply not link to libvirt-qemu.so

The reason I wanted to do this was mostly for debug/support reasons.
That is, with this element in place we can easily tell from the dumpxml
output whether a person was using the "unreliable" API's, and thus we can
tell them to try and reproduce without that in place.

>> The <commandline><extra> tag does exactly what you might expect; appends
>> the exact string to the qemu command-line.
> Allowing many args at once in the <extra> blob means that libvirt will
> need to parse & split this up into individual args which than then be
> safely passed to 'exec'. It is better to specify one arg per element
> to avoid this fragile parsing problem.

That is true.  However, it's nicer to the user (and more like the qemu
command-line) to specify the options as one big string.  In any case we
already have the code for parsing a qemu command-line (for the native-to-xml
API), so we can just adapt that.

>> The <alter> tag gets more interesting.  The idea is that <alter> would
>> allow you to modify the libvirt-generated qemu command-line in arbitrary
>> ways.  How this would work is probably best explained with some examples:
>> <commandline>
>>   <alter option="-net">
>>     <rename>-netdev</rename>
>>   </alter>
>> </commandline>
>> In this example, all options named -net on the qemu command-line are
>> renamed to -netdev.
>> In this example, if (and only if) a -net option is seen, then -usbtablet is
>> appended to the qemu command-line.
>> <commandline>
>>   <alter option="-net">
>>     <match>\(.*name=hostnet0.*\)</match>
>>     <modify>\1,tap</modify>
>>   </alter>
>> </commandline>
>> This gets more complicated (but also more powerful).  In this case, any -net
> I think this alteration of existing args is faaaar too complex & fragile,
> and way overkill. If the arg that libvirt generates isn't what someone 
> needs, then remove the bit of the guest config responsible for that and
> add a complete extra arg, rather than munging the existing one.

It is complex, I agree.  I also think it is pretty powerful.  But if
the need arises, we can always add it later.  For now we'll go with just the
monitor passthrough and simple command-line addition, and we can evolve from

Chris Lalancette

More information about the libvir-list mailing list