Upcoming patches will add possibility to override configuration of a
device with custom properties as a more versatile replacement to using
QEMU's '-set' parameter, which doesn't work when we use JSON to
instantiate devices.
Describe the XML used for the override as well as expectations of
upstream support in case something breaks.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/drvqemu.rst | 52 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 52 insertions(+)
diff --git a/docs/drvqemu.rst b/docs/drvqemu.rst
index 9d7dd2656b..b13415936c 100644
--- a/docs/drvqemu.rst
+++ b/docs/drvqemu.rst
@@ -580,6 +580,58 @@ reconfigure libvirtd.
*DO NOT* use in production.
+Overriding properties of QEMU devices
+-------------------------------------
+
+For development or testing the ``<qemu:deviceOverride>`` tag allows to override
+specific properties of devices instantiated by libvirt in QEMU via the
+``-device`` argument.
+
+The ``<qemu:device>`` sub-element groups overrides for a device identified via
+the ``alias`` attribute. The alias corresponds to the ``<alias name=''>``
+property of a device. It's strongly recommended to use user-specified aliases
+for devices with overriden properties.
+
+The individual properties are overriden by a ``<qemu:property>`` element. The
+``name`` specifies the name of the property to override. In case when libvirt
+doesn't configure the property a property with the name is added to the
+commandline. The ``type`` attribute specifies a type of the argument used. The
+type must correspond with the type that is expected by QEMU. Supported values
+for the type attribute are: ``string``, ``number``, ``bool`` (allowed values for
+``bool`` are ``true`` and ``false``) and ``remove``. The ``remove`` type is
+special and instructs libvirt to remove the property without replacement.
+
+The overrides are applied only to initial device configuration passed to QEMU
+via the commandline. Later hotplug operations will not apply any modifications.
+
+Configuring override for a device alias which is not used or attempting to
+remove a device property which is not formatted by libvirt will cause failure
+to startup the VM.
+
+*Note:* The libvirt project doesn't guarantee any form of compatibility and
+stability of devices with overriden properties. The domain is tainted when
+such configuration is used.
+
+Example:
+
+::
+
+ <domain type='kvm'
xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>
+ <name>testvm</name>
+
+ [...]
+
+ <qemu:deviceOverride>
+ <qemu:device alias='ua-devalias'>
+ <qemu:property name='propname1' type='string'
value='test'/>
+ <qemu:property name='propname2' type='unsigned'
value='123'/>
+ <qemu:property name='propname2' type='signed'
value='-123'/>
+ <qemu:property name='propname3' type='bool'
value='false'/>
+ <qemu:property name='propname4' type='remove'/>
+ </qemu:device>
+ </qemu:deviceOverride>
+ </domain>
+
Example domain XML config
-------------------------
--
2.35.1