External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-07-12 21:05:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: drvqemu: Document overriding of device properties

Browse Source 
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@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This commit is contained in:
Peter Krempa 2022-03-21 12:02:53 +01:00
parent 47d6d1855c
commit 5747dff5f7
1 changed files with 57 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
docs/drvqemu.rst
View File

@ -580,6 +580,63 @@ reconfigure libvirtd.
*DO NOT* use in production.
Overriding properties of QEMU devices
-------------------------------------
For development or testing the ``<qemu:override>`` tag allows to override
specific properties of devices instantiated by libvirt.
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.
Sub element ``<qemu:frontend>`` encapsulates all overrides of properties for the
device frontend and overrides what libvirt formats via ``-device``.
:since:`Since 8.2.0`.
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:override>
<qemu:device alias='ua-devalias'>
<qemu:frontend>
<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:frontend>
</qemu:device>
</qemu:override>
</domain>
Example domain XML config
-------------------------