The information in formatdomain.html seems too detailed, but it also
didn't seem right to put that information in a wiki page before the
patches are even pushed...
Signed-off-by: Laine Stump <laine@xxxxxxxxxx>
---
docs/formatdomain.html.in | 70 +++++++++++++++++++++++++++++++++++++++
docs/news.xml | 27 +++++++++++++++
2 files changed, 97 insertions(+)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 6e86d057a8..e3ea89fe25 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -5871,6 +5871,76 @@
</devices>
...</pre>
+ <h5><a id="elementsVirtioFailover">Using virtio "failover" to bond an emulated/hostdev NIC pair</a></h5>
+
+ <p>
+ <span class="since">Since 6.1.0 (QEMU and KVM only, requires
+ QEMU 4.2.0 or newer)</span> If the virtio-net driver in the
+ guest OS supports the virtio "failover" feature, it is possible
+ to setup a simple bond device comprised of one emulated virtio
+ NIC and one SRIOV VF "hostdev" NIC. In this configuration, the
+ higher-performing hostdev NIC will normally be preferred for all
+ network traffic, but when the VM is migrated, QEMU will
+ automatically unplug the VF from the VM, and then hotplug a
+ similar device once migration is completed; while migration is
+ taking place, network traffic will use the virtio NIC. (Of
+ course the emulated virtio NIC and the hostdev NIC must be
+ connected to the same subnet for bonding to work properly). The
+ interface <code><driver></code> subelement
+ attributes <code>failover</code> and <code>backupAlias</code>
+ are used to set this up - the virtio NIC will need to
+ have <code>failover='on'</code> set in
+ its <code><driver></code>, and the hostdev NIC will
+ use <code>backupAlias</code> to indicate the alias name of the
+ virtio NIC.
+ </p>
+ <p>
+ NB1: Since you must know the alias name of the virtio
+ NIC when configuring the hostdev NIC, it will need to be
+ manually set in the virtio NIC's configuration (as with all
+ other manually set alias names, it must start with "ua-".
+ </p>
+ <p>
+ NB2: Currently the only known implementation of failover in a
+ guest OS virtio-net driver requires that the MAC addresses of
+ the virtio and hostdev NIC must match. Since that may not always
+ be a requirement, libvirt doesn't enforce this limitation - it
+ is up to the person/management application that is creating the
+ configuration.
+ </p>
+ <p>
+ NB3: Since the PCI addresses of the SRIOV VFs on the hosts that
+ are the source and destination of the migration will almost
+ certainly be different, either higher level management software
+ will need to modify the <code><source></code> of the
+ hostdev NIC (<code><interface type='hostdev'></code>) at
+ the start of migration, or (a simpler solution) the
+ configuration will need to use a libvirt "hostdev" virtual
+ network that maintains a pool of such devices, as is implied in
+ the following example's use of the libvirt network named
+ "hostdev-pool" - as long as the hostdev network pools on both
+ hosts have the same name, libvirt itself will take care of
+ allocating an appropriate device on both ends of the migration.
+ </p>
+
+<pre>
+...
+<devices>
+ <interface type='network'>
+ <source network='mybridge'/>
+ <mac address='00:11:22:33:44:55'/>
+ <model type='virtio'/>
+ <driver failover='on'/>
+ <alias name='ua-backup0'/>
+ </interface>
+ <interface type='network'>
+ <source network='hostdev-pool'/>
+ <mac address='00:11:22:33:44:55'/>
+ <model type='virtio'/>
+ <driver backupAlias='ua-backup0'/>
+ </interface>
+</devices>
+...</pre>
<h5><a id="elementsNICSMulticast">Multicast tunnel</a></h5>
diff --git a/docs/news.xml b/docs/news.xml
index 056c7ef026..051b6b3a54 100644
--- a/docs/news.xml
+++ b/docs/news.xml
@@ -44,6 +44,33 @@
<libvirt>
<release version="v6.1.0" date="unreleased">
<section title="New features">
+ <change>
+ <summary>
+ support for virtio "failover" / QEMU auto-unplug of vfio devices
+ </summary>
+ <description>
+ QEMU 4.2.0 and later, combined with a sufficiently recent
+ guest virtio-net driver, supports setting up a simple
+ network bond device comprised of one virtio emulated NIC and
+ one hostdev NIC (which must be an SRIOV VF). The allure of
+ this setup is that the bond will always favor the hostdev
+ device, providing better performance, until the guest is
+ migrated - at that time QEMU will automatically unplug the
+ hostdev NIC and the bond will send all traffic via the
+ virtio NIC until migration is completed, then QEMU on the
+ destination side will hotplug a new hostdev NIC and the bond
+ will switch back to using the hostdev for network
+ traffic. The result is that guests desiring the extra
+ performance of a hostdev NIC are now migratable without
+ network downtime (performance is just degraded during
+ migration) and without requiring a complicated bonding
+ configuration in the guest OS network config and complicated
+ unplug/replug logic in the management application on the
+ host - it can instead all be accomplished in libvirt with
+ the interface <driver> subelement "failover" and
+ "backupAlias" attributes.
+ </description>
+ </change>
</section>
<section title="Improvements">
</section>
--
2.24.1
