From a7ad591f6a6b86b24b1ed030cc9b1ca5b3bf4346 Mon Sep 17 00:00:00 2001 Message-Id: From: Laine Stump Date: Thu, 30 Jan 2020 14:12:44 -0500 Subject: [PATCH] docs: document subelement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Laine Stump Reviewed-by: Daniel P. Berrangé (cherry picked from commit f0f34056ab26eaa9f903a51cd1fa155088fd640f) Conflicts: docs/news.xml - feature is in release 6.1.0 upstream, but that release doesn't exist downstream. https://bugzilla.redhat.com/1693587 Signed-off-by: Laine Stump Message-Id: <20200130191244.24174-7-laine@redhat.com> Reviewed-by: Jiri Denemark --- docs/formatdomain.html.in | 101 ++++++++++++++++++++++++++++++++++++++ docs/news.xml | 28 +++++++++++ 2 files changed, 129 insertions(+) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 4db9c292b7..98a811bd09 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -5873,6 +5873,107 @@ </devices> ... +
Teaming a virtio/hostdev NIC pair
+ +

+ Since 6.1.0 (QEMU and KVM only, requires + QEMU 4.2.0 or newer axnd a guest virtio-net driver supporting + the "failover" feature, such as the one included in Linux + kernel 4.18 and newer) + + The <teaming> element of two interfaces can + be used to connect them as a team/bond device in the guest + (assuming proper support in the hypervisor and the guest + network driver). +

+ +
+...
+<devices>
+  <interface type='network'>
+    <source network='mybridge'/>
+    <mac address='00:11:22:33:44:55'/>
+    <model type='virtio'/>
+    <teaming type='persistent'/>
+    <alias name='ua-backup0'/>
+  </interface>
+  <interface type='network'>
+    <source network='hostdev-pool'/>
+    <mac address='00:11:22:33:44:55'/>
+    <model type='virtio'/>
+    <teaming type='transient' persistent='ua-backup0'/>
+  </interface>
+</devices>
+...
+ +

+ The <teaming> element required + attribute type will be set to + either "persistent" to indicate a device that + should always be present in the domain, + or "transient" to indicate a device that may + periodically be removed, then later re-added to the domain. When + type="transient", there should be a second attribute + to <teaming> called "persistent" + - this attribute should be set to the alias name of the other + device in the pair (the one that has <teaming + type="persistent'/>). +

+

+ In the particular case of QEMU, + libvirt's <teaming> element is used to setup + a virtio-net "failover" device pair. For this setup, the + persistent device must be an interface with <model + type="virtio"/>, and the transient device must + be <interface type='hostdev'/> + (or <interface type='network'/> where the + referenced network defines a pool of SRIOV VFs). The guest will + then have a simple network team/bond device made of the virtio + NIC + hostdev NIC pair. In this configuration, the + higher-performing hostdev NIC will normally be preferred for all + network traffic, but when the domain is migrated, QEMU will + automatically unplug the VF from the guest, 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). +

+

+ 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, this means it must start with "ua-"). +

+

+ NB2: Currently the only implementation of the guest OS + virtio-net driver supporting virtio-net failover requires that + the MAC addresses of the virtio and hostdev NIC must + match. Since that may not always be a requirement in the future, + libvirt doesn't enforce this limitation - it is up to the + person/management application that is creating the configuration + to assure the MAC addresses of the two devices match. +

+

+ 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 <source> of the + hostdev NIC (<interface type='hostdev'>) 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 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. Similarly the XML for the + virtio interface must also either work correctly unmodified on + both the source and destination of the migration (e.g. by + connecting to the same bridge device on both hosts, or by using + the same virtual network), or the management software must + properly modify the interface XML during migration so that the + virtio device remains connected to the same network segment + before and after migration. +

Multicast tunnel
diff --git a/docs/news.xml b/docs/news.xml index 731f010297..408ffc8518 100644 --- a/docs/news.xml +++ b/docs/news.xml @@ -65,6 +65,34 @@
+ + + support for virtio+hostdev NIC <teaming> + + + QEMU 4.2.0 and later, combined with a sufficiently recent + guest virtio-net driver (e.g. the driver included in Linux + kernel 4.18 and later), supports setting up a simple network + bond device comprised of one virtio emulated NIC and one + hostdev NIC (which must be an SRIOV VF). (in QEMU, this is + known as the "virtio failover" feature). 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 <teaming> subelement + "type" and "persistent" attributes. + + new PCI hostdev address type: unassigned -- 2.25.0