From nobody Mon Feb 9 17:34:56 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) client-ip=207.211.31.81; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1579880804; cv=none; d=zohomail.com; s=zohoarc; b=eaWiXTbFDyo9j0fTKAmQbrPRm3CSFedfhluI24puceSWxuInqom2Ecz82lD8AVZjFCp99OAOkbrbN+WOcZ6QcVfTsOPhjPvswX8L6dUUVlHM57+kPaUJvZoaSL7GZ8ZonEg7Ty1MoqIzqWfYIiikAkvjWg89oVyZrdxUc3Zs+NU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1579880804; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=ZHXWjY9Cptfss1ypO5cjTBhxVCS7E1msfXscv9ObIx8=; b=R0hDPwNr3C3YAUMwIwjYEWSeFLXXmlvNdnfXpB15YPDUfMmznWiiUWa9yoqFOQXlm7GgUVbKZKsG+HBEMhrszUkHbZVpVabEe++yK0EIvpKHAQWV8GleMyJAEVIjFeyQjkUVAXAtgXmeWmn+ubwQhZ5dnPWQjtKqPK7YtZgnbXo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-1.mimecast.com (us-smtp-2.mimecast.com [207.211.31.81]) by mx.zohomail.com with SMTPS id 1579880804653762.1797945890972; Fri, 24 Jan 2020 07:46:44 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-109-SyU2zYFFNgu8zVTZfm0uvA-1; Fri, 24 Jan 2020 10:46:41 -0500 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id C9F27DD135; Fri, 24 Jan 2020 15:39:50 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id A63625C241; Fri, 24 Jan 2020 15:39:50 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 6191518089CE; Fri, 24 Jan 2020 15:39:50 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 00OFdWN0010352 for ; Fri, 24 Jan 2020 10:39:32 -0500 Received: by smtp.corp.redhat.com (Postfix) id CB4EE5C1BB; Fri, 24 Jan 2020 15:39:32 +0000 (UTC) Received: from vhost2.router.laine.org (ovpn-116-187.phx2.redhat.com [10.3.116.187]) by smtp.corp.redhat.com (Postfix) with ESMTP id 507085C1B0; Fri, 24 Jan 2020 15:39:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1579880803; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=ZHXWjY9Cptfss1ypO5cjTBhxVCS7E1msfXscv9ObIx8=; b=HUihOWCYWi2kUafPoNUuNvcZb06JKoBsd7kDu982YfwImFH2fapyN6Js6evBuSOFumd8uH B7kF6egS0S3+q8KrQCzzYx9mVP3s/rc/oSa3Rr5IA1UDct37MpM+6pR5seKvI+ZoBIk+Go W2sCI38Bwqm3jzbx5ugrLlW+uoRBpGk= From: Laine Stump To: libvir-list@redhat.com Subject: [libvirt PATCH v2 6/6] docs: document subelement Date: Fri, 24 Jan 2020 10:39:21 -0500 Message-Id: <20200124153922.3883568-7-laine@redhat.com> In-Reply-To: <20200124153922.3883568-1-laine@redhat.com> References: <20200124153922.3883568-1-laine@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-loop: libvir-list@redhat.com Cc: Jens Freimann X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-MC-Unique: SyU2zYFFNgu8zVTZfm0uvA-1 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" and the QEMU backend implementation using virtio failover. Signed-off-by: Laine Stump Reviewed-by: Daniel P. Berrang=C3=A9 --- docs/formatdomain.html.in | 100 ++++++++++++++++++++++++++++++++++++++ docs/news.xml | 28 +++++++++++ 2 files changed, 128 insertions(+) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 4db9c292b7..a1c2a1e392 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -5873,6 +5873,106 @@ </devices> ... =20 +
Teaming a virtio/hostdev NIC pair + +

+ Since 6.1.0 (QEMU and KVM only, requires + QEMU 4.2.0 or newer and a guest virtio-net driver supporting + the "failover" feature) + + 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=3D'network'>
+    <source network=3D'mybridge'/>
+    <mac address=3D'00:11:22:33:44:55'/>
+    <model type=3D'virtio'/>
+    <teaming type=3D'persistent'/>
+    <alias name=3D'ua-backup0'/>
+  </interface>
+  <interface type=3D'network'>
+    <source network=3D'hostdev-pool'/>
+    <mac address=3D'00:11:22:33:44:55'/>
+    <model type=3D'virtio'/>
+    <teaming type=3D'transient' persistent=3D'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=3D"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=3D"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=3D"virtio"/>, and the transient device must + be <interface type=3D'hostdev'/> + (or <interface type=3D'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=3D'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. +

=20
Multicast tunnel
=20 diff --git a/docs/news.xml b/docs/news.xml index 056c7ef026..7dc9cc18cb 100644 --- a/docs/news.xml +++ b/docs/news.xml @@ -44,6 +44,34 @@
+ + + support for virtio+hostdev NIC <teaming> + + + 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). (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. + +
--=20 2.24.1