[PATCH 16/32] docs: formatdomain-devices: Split out <interface>

Peter Krempa pkrempa at redhat.com
Thu Jul 23 13:21:21 UTC 2020


Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/formatdomain-devices-interface.rst | 1258 ++++++++++++++++++++++
 docs/formatdomain-devices.rst           | 1260 +----------------------
 docs/meson.build                        |    1 +
 3 files changed, 1260 insertions(+), 1259 deletions(-)
 create mode 100644 docs/formatdomain-devices-interface.rst

diff --git a/docs/formatdomain-devices-interface.rst b/docs/formatdomain-devices-interface.rst
new file mode 100644
index 0000000000..c828e71df1
--- /dev/null
+++ b/docs/formatdomain-devices-interface.rst
@@ -0,0 +1,1258 @@
+:anchor:`<a id="elementsNICS"/>`
+
+Network interfaces
+~~~~~~~~~~~~~~~~~~
+
+::
+
+   ...
+   <devices>
+     <interface type='direct' trustGuestRxFilters='yes'>
+       <source dev='eth0'/>
+       <mac address='52:54:00:5d:c7:9e'/>
+       <boot order='1'/>
+       <rom bar='off'/>
+     </interface>
+   </devices>
+   ...
+
+There are several possibilities for specifying a network interface visible to
+the guest. Each subsection below provides more details about common setup
+options.
+
+:since:`Since 1.2.10` ), the ``interface`` element property
+``trustGuestRxFilters`` provides the capability for the host to detect and trust
+reports from the guest regarding changes to the interface mac address and
+receive filters by setting the attribute to ``yes``. The default setting for the
+attribute is ``no`` for security reasons and support depends on the guest
+network device model as well as the type of connection on the host - currently
+it is only supported for the virtio device model and for macvtap connections on
+the host.
+
+Each ``<interface>`` element has an optional ``<address>`` sub-element that can
+tie the interface to a particular pci slot, with attribute ``type='pci'`` as
+`documented above <#elementsAddress>`__.
+
+:since:`Since 6.6.0` , one can force libvirt to keep the provided MAC address
+when it's in the reserved VMware range by adding a ``type="static"`` attribute
+to the ``<mac/>`` element. Note that this attribute is useless if the provided
+MAC address is outside of the reserved VMWare ranges.
+
+:anchor:`<a id="elementsNICSVirtual"/>`
+
+Virtual network
+^^^^^^^^^^^^^^^
+
+**This is the recommended config for general guest connectivity on hosts with
+dynamic / wireless networking configs (or multi-host environments where the host
+hardware details are described separately in a ``<network>`` definition
+:since:`Since 0.9.4` ).**
+
+Provides a connection whose details are described by the named network
+definition. Depending on the virtual network's "forward mode" configuration, the
+network may be totally isolated (no ``<forward>`` element given), NAT'ing to an
+explicit network device or to the default route (``<forward mode='nat'>``),
+routed with no NAT (``<forward mode='route'/>``), or connected directly to one
+of the host's network interfaces (via macvtap) or bridge devices
+((``<forward       mode='bridge|private|vepa|passthrough'/>`` :since:`Since
+0.9.4` )
+
+For networks with a forward mode of bridge, private, vepa, and passthrough, it
+is assumed that the host has any necessary DNS and DHCP services already setup
+outside the scope of libvirt. In the case of isolated, nat, and routed networks,
+DHCP and DNS are provided on the virtual network by libvirt, and the IP range
+can be determined by examining the virtual network config with
+'``virsh net-dumpxml [networkname]``'. There is one virtual network called
+'default' setup out of the box which does NAT'ing to the default route and has
+an IP range of ``192.168.122.0/255.255.255.0``. Each guest will have an
+associated tun device created with a name of vnetN, which can also be overridden
+with the <target> element (see `overriding the target
+element <#elementsNICSTargetOverride>`__).
+
+When the source of an interface is a network, a ``portgroup`` can be specified
+along with the name of the network; one network may have multiple portgroups
+defined, with each portgroup containing slightly different configuration
+information for different classes of network connections. :since:`Since 0.9.4` .
+
+When a guest is running an interface of type ``network`` may include a
+``portid`` attribute. This provides the UUID of an associated virNetworkPortPtr
+object that records the association between the domain interface and the
+network. This attribute is read-only since port objects are create and deleted
+automatically during startup and shutdown. :since:`Since 5.1.0`
+
+Also, similar to ``direct`` network connections (described below), a connection
+of type ``network`` may specify a ``virtualport`` element, with configuration
+data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant switch (
+:since:`Since 0.8.2` ), or to an Open vSwitch virtual switch ( :since:`Since
+0.9.11` ).
+
+Since the actual type of switch may vary depending on the configuration in the
+``<network>`` on the host, it is acceptable to omit the virtualport ``type``
+attribute, and specify attributes from multiple different virtualport types (and
+also to leave out certain attributes); at domain startup time, a complete
+``<virtualport>`` element will be constructed by merging together the type and
+attributes defined in the network and the portgroup referenced by the interface.
+The newly-constructed virtualport is a combination of them. The attributes from
+lower virtualport can't make change on the ones defined in higher virtualport.
+Interface takes the highest priority, portgroup is lowest priority. (
+:since:`Since 0.10.0` ). For example, in order to work properly with both an
+802.1Qbh switch and an Open vSwitch switch, you may choose to specify no type,
+but both a ``profileid`` (in case the switch is 802.1Qbh) and an ``interfaceid``
+(in case the switch is Open vSwitch) (you may also omit the other attributes,
+such as managerid, typeid, or profileid, to be filled in from the network's
+``<virtualport>``). If you want to limit a guest to connecting only to certain
+types of switches, you can specify the virtualport type, but still omit some/all
+of the parameters - in this case if the host's network has a different type of
+virtualport, connection of the interface will fail.
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+     </interface>
+     ...
+     <interface type='network'>
+       <source network='default' portgroup='engineering'/>
+       <target dev='vnet7'/>
+       <mac address="00:11:22:33:44:55"/>
+       <virtualport>
+         <parameters instanceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
+       </virtualport>
+     </interface>
+   </devices>
+   ...
+
+:anchor:`<a id="elementsNICSBridge"/>`
+
+Bridge to LAN
+^^^^^^^^^^^^^
+
+**This is the recommended config for general guest connectivity on hosts with
+static wired networking configs.**
+
+Provides a bridge from the VM directly to the LAN. This assumes there is a
+bridge device on the host which has one or more of the hosts physical NICs
+attached. The guest VM will have an associated tun device created with a name of
+vnetN, which can also be overridden with the <target> element (see `overriding
+the target element <#elementsNICSTargetOverride>`__). The tun device will be
+attached to the bridge. The IP range / network configuration is whatever is used
+on the LAN. This provides the guest VM full incoming & outgoing net access just
+like a physical machine.
+
+On Linux systems, the bridge device is normally a standard Linux host bridge. On
+hosts that support Open vSwitch, it is also possible to connect to an Open
+vSwitch bridge device by adding a ``<virtualport type='openvswitch'/>`` to the
+interface definition. ( :since:`Since 0.9.11` ). The Open vSwitch type
+virtualport accepts two parameters in its ``<parameters>`` element - an
+``interfaceid`` which is a standard uuid used to uniquely identify this
+particular interface to Open vSwitch (if you do not specify one, a random
+interfaceid will be generated for you when you first define the interface), and
+an optional ``profileid`` which is sent to Open vSwitch as the interfaces
+"port-profile".
+
+::
+
+   ...
+   <devices>
+     ...
+     <interface type='bridge'>
+       <source bridge='br0'/>
+     </interface>
+     <interface type='bridge'>
+       <source bridge='br1'/>
+       <target dev='vnet7'/>
+       <mac address="00:11:22:33:44:55"/>
+     </interface>
+     <interface type='bridge'>
+       <source bridge='ovsbr'/>
+       <virtualport type='openvswitch'>
+         <parameters profileid='menial' interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
+       </virtualport>
+     </interface>
+     ...
+   </devices>
+   ...
+
+On hosts that support Open vSwitch on the kernel side and have the Midonet Host
+Agent configured, it is also possible to connect to the 'midonet' bridge device
+by adding a ``<virtualport type='midonet'/>`` to the interface definition. (
+:since:`Since 1.2.13` ). The Midonet virtualport type requires an
+``interfaceid`` attribute in its ``<parameters>`` element. This interface id is
+the UUID that specifies which port in the virtual network topology will be bound
+to the interface.
+
+::
+
+   ...
+   <devices>
+     ...
+     <interface type='bridge'>
+       <source bridge='br0'/>
+     </interface>
+     <interface type='bridge'>
+       <source bridge='br1'/>
+       <target dev='vnet7'/>
+       <mac address="00:11:22:33:44:55"/>
+     </interface>
+     <interface type='bridge'>
+       <source bridge='midonet'/>
+       <virtualport type='midonet'>
+         <parameters interfaceid='0b2d64da-3d0e-431e-afdd-804415d6ebbb'/>
+       </virtualport>
+     </interface>
+     ...
+   </devices>
+   ...
+
+:anchor:`<a id="elementsNICSSlirp"/>`
+
+Userspace SLIRP stack
+^^^^^^^^^^^^^^^^^^^^^
+
+Provides a virtual LAN with NAT to the outside world. The virtual network has
+DHCP & DNS services and will give the guest VM addresses starting from
+``10.0.2.15``. The default router will be ``10.0.2.2`` and the DNS server will
+be ``10.0.2.3``. This networking is the only option for unprivileged users who
+need their VMs to have outgoing access. :since:`Since 3.8.0` it is possible to
+override the default network address by including an ``ip`` element specifying
+an IPv4 address in its one mandatory attribute, ``address``. Optionally, a
+second ``ip`` element with a ``family`` attribute set to "ipv6" can be specified
+to add an IPv6 address to the interface. ``address``. Optionally, address
+``prefix`` can be specified.
+
+::
+
+   ...
+   <devices>
+     <interface type='user'/>
+     ...
+     <interface type='user'>
+       <mac address="00:11:22:33:44:55"/>
+       <ip family='ipv4' address='172.17.2.0' prefix='24'/>
+       <ip family='ipv6' address='2001:db8:ac10:fd01::' prefix='64'/>
+     </interface>
+   </devices>
+   ...
+
+:anchor:`<a id="elementsNICSEthernet"/>`
+
+Generic ethernet connection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Provides a means to use a new or existing tap device (or veth device pair,
+depening on the needs of the hypervisor driver) that is partially or wholly
+setup external to libvirt (either prior to the guest starting, or while the
+guest is being started via an optional script specified in the config).
+
+The name of the tap device can optionally be specified with the ``dev``
+attribute of the ``<target>`` element. If no target dev is specified, libvirt
+will create a new standard tap device with a name of the pattern "vnetN", where
+"N" is replaced with a number. If a target dev is specified and that device
+doesn't exist, then a new standard tap device will be created with the exact dev
+name given. If the specified target dev does exist, then that existing device
+will be used. Usually some basic setup of the device is done by libvirt,
+including setting a MAC address, and the IFF_UP flag, but if the ``dev`` is a
+pre-existing device, and the ``managed`` attribute of the ``target`` element is
+also set to "no" (the default value is "yes"), even this basic setup will not be
+performed - libvirt will simply pass the device on to the hypervisor with no
+setup at all. :since:`Since 5.7.0` Using managed='no' with a pre-created tap
+device is useful because it permits a virtual machine managed by an unprivileged
+libvirtd to have emulated network devices based on tap devices.
+
+After creating/opening the tap device, an optional shell script (given in the
+``path`` attribute of the ``<script>`` element) will be run. :since:`Since
+0.2.1` Also, after detaching/closing the tap device, an optional shell script
+(given in the ``path`` attribute of the ``<downscript>`` element) will be run.
+:since:`Since 5.1.0` These can be used to do whatever extra host network
+integration is required.
+
+::
+
+   ...
+   <devices>
+     <interface type='ethernet'>
+       <script path='/etc/qemu-ifup-mynet'/>
+       <downscript path='/etc/qemu-ifdown-mynet'/>
+     </interface>
+     ...
+     <interface type='ethernet'>
+       <target dev='mytap1' managed='no'/>
+       <model type='virtio'/>
+     </interface>
+   </devices>
+   ...
+
+:anchor:`<a id="elementsNICSDirect"/>`
+
+Direct attachment to physical interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+| Provides direct attachment of the virtual machine's NIC to the given physical
+  interface of the host. :since:`Since 0.7.7 (QEMU and KVM only)`
+| This setup requires the Linux macvtap driver to be available. :since:`(Since
+  Linux 2.6.34.)` One of the modes 'vepa' ( `'Virtual Ethernet Port
+  Aggregator' <http://www.ieee802.org/1/files/public/docs2009/new-evb-congdon-vepa-modular-0709-v01.pdf>`__),
+  'bridge' or 'private' can be chosen for the operation mode of the macvtap
+  device, 'vepa' being the default mode. The individual modes cause the delivery
+  of packets to behave as follows:
+
+If the model type is set to ``virtio`` and interface's ``trustGuestRxFilters``
+attribute is set to ``yes``, changes made to the interface mac address,
+unicast/multicast receive filters, and vlan settings in the guest will be
+monitored and propagated to the associated macvtap device on the host (
+:since:`Since 1.2.10` ). If ``trustGuestRxFilters`` is not set, or is not
+supported for the device model in use, an attempted change to the mac address
+originating from the guest side will result in a non-working network connection.
+
+``vepa``
+   All VMs' packets are sent to the external bridge. Packets whose destination
+   is a VM on the same host as where the packet originates from are sent back to
+   the host by the VEPA capable bridge (today's bridges are typically not VEPA
+   capable).
+``bridge``
+   Packets whose destination is on the same host as where they originate from
+   are directly delivered to the target macvtap device. Both origin and
+   destination devices need to be in bridge mode for direct delivery. If either
+   one of them is in ``vepa`` mode, a VEPA capable bridge is required.
+``private``
+   All packets are sent to the external bridge and will only be delivered to a
+   target VM on the same host if they are sent through an external router or
+   gateway and that device sends them back to the host. This procedure is
+   followed if either the source or destination device is in ``private`` mode.
+``passthrough``
+   This feature attaches a virtual function of a SRIOV capable NIC directly to a
+   VM without losing the migration capability. All packets are sent to the VF/IF
+   of the configured network device. Depending on the capabilities of the device
+   additional prerequisites or limitations may apply; for example, on Linux this
+   requires kernel 2.6.38 or newer. :since:`Since 0.9.2`
+
+::
+
+   ...
+   <devices>
+     ...
+     <interface type='direct' trustGuestRxFilters='no'>
+       <source dev='eth0' mode='vepa'/>
+     </interface>
+   </devices>
+   ...
+
+The network access of direct attached virtual machines can be managed by the
+hardware switch to which the physical interface of the host machine is connected
+to.
+
+The interface can have additional parameters as shown below, if the switch is
+conforming to the IEEE 802.1Qbg standard. The parameters of the virtualport
+element are documented in more detail in the IEEE 802.1Qbg standard. The values
+are network specific and should be provided by the network administrator. In
+802.1Qbg terms, the Virtual Station Interface (VSI) represents the virtual
+interface of a virtual machine. :since:`Since 0.8.2`
+
+Please note that IEEE 802.1Qbg requires a non-zero value for the VLAN ID.
+
+``managerid``
+   The VSI Manager ID identifies the database containing the VSI type and
+   instance definitions. This is an integer value and the value 0 is reserved.
+``typeid``
+   The VSI Type ID identifies a VSI type characterizing the network access. VSI
+   types are typically managed by network administrator. This is an integer
+   value.
+``typeidversion``
+   The VSI Type Version allows multiple versions of a VSI Type. This is an
+   integer value.
+``instanceid``
+   The VSI Instance ID Identifier is generated when a VSI instance (i.e. a
+   virtual interface of a virtual machine) is created. This is a globally unique
+   identifier.
+
+::
+
+   ...
+   <devices>
+     ...
+     <interface type='direct'>
+       <source dev='eth0.2' mode='vepa'/>
+       <virtualport type="802.1Qbg">
+         <parameters managerid="11" typeid="1193047" typeidversion="2" instanceid="09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f"/>
+       </virtualport>
+     </interface>
+   </devices>
+   ...
+
+The interface can have additional parameters as shown below if the switch is
+conforming to the IEEE 802.1Qbh standard. The values are network specific and
+should be provided by the network administrator. :since:`Since 0.8.2`
+
+``profileid``
+   The profile ID contains the name of the port profile that is to be applied to
+   this interface. This name is resolved by the port profile database into the
+   network parameters from the port profile, and those network parameters will
+   be applied to this interface.
+
+::
+
+   ...
+   <devices>
+     ...
+     <interface type='direct'>
+       <source dev='eth0' mode='private'/>
+       <virtualport type='802.1Qbh'>
+         <parameters profileid='finance'/>
+       </virtualport>
+     </interface>
+   </devices>
+   ...
+
+:anchor:`<a id="elementsNICSHostdev"/>`
+
+PCI Passthrough
+^^^^^^^^^^^^^^^
+
+A PCI network device (specified by the <source> element) is directly assigned to
+the guest using generic device passthrough, after first optionally setting the
+device's MAC address to the configured value, and associating the device with an
+802.1Qbh capable switch using an optionally specified <virtualport> element (see
+the examples of virtualport given above for type='direct' network devices). Note
+that - due to limitations in standard single-port PCI ethernet card driver
+design - only SR-IOV (Single Root I/O Virtualization) virtual function (VF)
+devices can be assigned in this manner; to assign a standard single-port PCI or
+PCIe ethernet card to a guest, use the traditional <hostdev> device definition
+and :since:`Since 0.9.11`
+
+To use VFIO device assignment rather than traditional/legacy KVM device
+assignment (VFIO is a new method of device assignment that is compatible with
+UEFI Secure Boot), a type='hostdev' interface can have an optional ``driver``
+sub-element with a ``name`` attribute set to "vfio". To use legacy KVM device
+assignment you can set ``name`` to "kvm" (or simply omit the ``<driver>``
+element, since "kvm" is currently the default). :since:`Since 1.0.5 (QEMU and
+KVM only, requires kernel 3.6 or newer)`
+
+Note that this "intelligent passthrough" of network devices is very similar to
+the functionality of a standard <hostdev> device, the difference being that this
+method allows specifying a MAC address and <virtualport> for the passed-through
+device. If these capabilities are not required, if you have a standard
+single-port PCI, PCIe, or USB network card that doesn't support SR-IOV (and
+hence would anyway lose the configured MAC address during reset after being
+assigned to the guest domain), or if you are using a version of libvirt older
+than 0.9.11, you should use standard <hostdev> to assign the device to the guest
+instead of <interface type='hostdev'/>.
+
+Similar to the functionality of a standard <hostdev> device, when ``managed`` is
+"yes", it is detached from the host before being passed on to the guest, and
+reattached to the host after the guest exits. If ``managed`` is omitted or "no",
+the user is responsible to call ``virNodeDeviceDettach`` (or
+``virsh nodedev-detach``) before starting the guest or hot-plugging the device,
+and ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-unplug
+or stopping the guest.
+
+::
+
+   ...
+   <devices>
+     <interface type='hostdev' managed='yes'>
+       <driver name='vfio'/>
+       <source>
+         <address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/>
+       </source>
+       <mac address='52:54:00:6d:90:02'/>
+       <virtualport type='802.1Qbh'>
+         <parameters profileid='finance'/>
+       </virtualport>
+     </interface>
+   </devices>
+   ...
+
+:anchor:`<a id="elementsTeaming"/>`
+
+Teaming a virtio/hostdev NIC pair
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:since:`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, 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.
+
+:anchor:`<a id="elementsNICSMulticast"/>`
+
+Multicast tunnel
+^^^^^^^^^^^^^^^^
+
+A multicast group is setup to represent a virtual network. Any VMs whose network
+devices are in the same multicast group can talk to each other even across
+hosts. This mode is also available to unprivileged users. There is no default
+DNS or DHCP support and no outgoing network access. To provide outgoing network
+access, one of the VMs should have a 2nd NIC which is connected to one of the
+first 4 network types and do the appropriate routing. The multicast protocol is
+compatible with that used by user mode linux guests too. The source address used
+must be from the multicast address block.
+
+::
+
+   ...
+   <devices>
+     <interface type='mcast'>
+       <mac address='52:54:00:6d:90:01'/>
+       <source address='230.0.0.1' port='5558'/>
+     </interface>
+   </devices>
+   ...
+
+:anchor:`<a id="elementsNICSTCP"/>`
+
+TCP tunnel
+^^^^^^^^^^
+
+A TCP client/server architecture provides a virtual network. One VM provides the
+server end of the network, all other VMS are configured as clients. All network
+traffic is routed between the VMs via the server. This mode is also available to
+unprivileged users. There is no default DNS or DHCP support and no outgoing
+network access. To provide outgoing network access, one of the VMs should have a
+2nd NIC which is connected to one of the first 4 network types and do the
+appropriate routing.
+
+::
+
+   ...
+   <devices>
+     <interface type='server'>
+       <mac address='52:54:00:22:c9:42'/>
+       <source address='192.168.0.1' port='5558'/>
+     </interface>
+     ...
+     <interface type='client'>
+       <mac address='52:54:00:8b:c9:51'/>
+       <source address='192.168.0.1' port='5558'/>
+     </interface>
+   </devices>
+   ...
+
+:anchor:`<a id="elementsNICSUDP"/>`
+
+UDP unicast tunnel
+^^^^^^^^^^^^^^^^^^
+
+A UDP unicast architecture provides a virtual network which enables connections
+between QEMU instances using QEMU's UDP infrastructure. The xml "source" address
+is the endpoint address to which the UDP socket packets will be sent from the
+host running QEMU. The xml "local" address is the address of the interface from
+which the UDP socket packets will originate from the QEMU host. :since:`Since
+1.2.20`
+
+::
+
+   ...
+   <devices>
+     <interface type='udp'>
+       <mac address='52:54:00:22:c9:42'/>
+       <source address='127.0.0.1' port='11115'>
+         <local address='127.0.0.1' port='11116'/>
+       </source>
+     </interface>
+   </devices>
+   ...
+
+:anchor:`<a id="elementsNICSModel"/>`
+
+Setting the NIC model
+^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <target dev='vnet1'/>
+       <model type='ne2k_pci'/>
+     </interface>
+   </devices>
+   ...
+
+For hypervisors which support this, you can set the model of emulated network
+interface card.
+
+The values for ``type`` aren't defined specifically by libvirt, but by what the
+underlying hypervisor supports (if any). For QEMU and KVM you can get a list of
+supported models with these commands:
+
+::
+
+   qemu -net nic,model=? /dev/null
+   qemu-kvm -net nic,model=? /dev/null
+
+Typical values for QEMU and KVM include: ne2k_isa i82551 i82557b i82559er
+ne2k_pci pcnet rtl8139 e1000 virtio. :since:`Since 5.2.0` ,
+``virtio-transitional`` and ``virtio-non-transitional`` values are supported.
+See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more
+details.
+
+:anchor:`<a id="elementsDriverBackendOptions"/>`
+
+Setting NIC driver-specific options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <target dev='vnet1'/>
+       <model type='virtio'/>
+       <driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5' rx_queue_size='256' tx_queue_size='256'>
+         <host csum='off' gso='off' tso4='off' tso6='off' ecn='off' ufo='off' mrg_rxbuf='off'/>
+         <guest csum='off' tso4='off' tso6='off' ecn='off' ufo='off'/>
+       </driver>
+       </interface>
+   </devices>
+   ...
+
+Some NICs may have tunable driver-specific options. These are set as attributes
+of the ``driver`` sub-element of the interface definition. Currently the
+following attributes are available for the ``"virtio"`` NIC driver:
+
+``name``
+   The optional ``name`` attribute forces which type of backend driver to use.
+   The value can be either 'qemu' (a user-space backend) or 'vhost' (a kernel
+   backend, which requires the vhost module to be provided by the kernel); an
+   attempt to require the vhost driver without kernel support will be rejected.
+   If this attribute is not present, then the domain defaults to 'vhost' if
+   present, but silently falls back to 'qemu' without error. :since:`Since 0.8.8
+   (QEMU and KVM only)`
+   For interfaces of type='hostdev' (PCI passthrough devices) the ``name``
+   attribute can optionally be set to "vfio" or "kvm". "vfio" tells libvirt to
+   use VFIO device assignment rather than traditional KVM device assignment
+   (VFIO is a new method of device assignment that is compatible with UEFI
+   Secure Boot), and "kvm" tells libvirt to use the legacy device assignment
+   performed directly by the kvm kernel module (the default is currently "kvm",
+   but is subject to change). :since:`Since 1.0.5 (QEMU and KVM only, requires
+   kernel 3.6 or newer)`
+   For interfaces of type='vhostuser', the ``name`` attribute is ignored. The
+   backend driver used is always vhost-user.
+``txmode``
+   The ``txmode`` attribute specifies how to handle transmission of packets when
+   the transmit buffer is full. The value can be either 'iothread' or 'timer'.
+   :since:`Since 0.8.8 (QEMU and KVM only)`
+   If set to 'iothread', packet tx is all done in an iothread in the bottom half
+   of the driver (this option translates into adding "tx=bh" to the qemu
+   commandline -device virtio-net-pci option).
+   If set to 'timer', tx work is done in qemu, and if there is more tx data than
+   can be sent at the present time, a timer is set before qemu moves on to do
+   other things; when the timer fires, another attempt is made to send more
+   data.
+   The resulting difference, according to the qemu developer who added the
+   option is: "bh makes tx more asynchronous and reduces latency, but
+   potentially causes more processor bandwidth contention since the CPU doing
+   the tx isn't necessarily the CPU where the guest generated the packets."
+   **In general you should leave this option alone, unless you are very certain
+   you know what you are doing.**
+``ioeventfd``
+   This optional attribute allows users to set `domain I/O asynchronous
+   handling <https://patchwork.kernel.org/patch/43390/>`__ for interface device.
+   The default is left to the discretion of the hypervisor. Accepted values are
+   "on" and "off". Enabling this allows qemu to execute VM while a separate
+   thread handles I/O. Typically guests experiencing high system CPU utilization
+   during I/O will benefit from this. On the other hand, on overloaded host it
+   could increase guest I/O latency. :since:`Since 0.9.3 (QEMU and KVM only)`
+   **In general you should leave this option alone, unless you are very certain
+   you know what you are doing.**
+``event_idx``
+   The ``event_idx`` attribute controls some aspects of device event processing.
+   The value can be either 'on' or 'off' - if it is on, it will reduce the
+   number of interrupts and exits for the guest. The default is determined by
+   QEMU; usually if the feature is supported, default is on. In case there is a
+   situation where this behavior is suboptimal, this attribute provides a way to
+   force the feature off. :since:`Since 0.9.5 (QEMU and KVM only)`
+   **In general you should leave this option alone, unless you are very certain
+   you know what you are doing.**
+``queues``
+   The optional ``queues`` attribute controls the number of queues to be used
+   for either `Multiqueue
+   virtio-net <https://www.linux-kvm.org/page/Multiqueue>`__ or
+   `vhost-user <#elementVhostuser>`__ network interfaces. Use of multiple packet
+   processing queues requires the interface having the
+   ``<model type='virtio'/>`` element. Each queue will potentially be handled by
+   a different processor, resulting in much higher throughput.
+   :since:`virtio-net since 1.0.6 (QEMU and KVM only)` :since:`vhost-user since
+   1.2.17 (QEMU and KVM only)`
+``rx_queue_size``
+   The optional ``rx_queue_size`` attribute controls the size of virtio ring for
+   each queue as described above. The default value is hypervisor dependent and
+   may change across its releases. Moreover, some hypervisors may pose some
+   restrictions on actual value. For instance, latest QEMU (as of 2016-09-01)
+   requires value to be a power of two from [256, 1024] range. :since:`Since
+   2.3.0 (QEMU and KVM only)`
+   **In general you should leave this option alone, unless you are very certain
+   you know what you are doing.**
+``tx_queue_size``
+   The optional ``tx_queue_size`` attribute controls the size of virtio ring for
+   each queue as described above. The default value is hypervisor dependent and
+   may change across its releases. Moreover, some hypervisors may pose some
+   restrictions on actual value. For instance, QEMU v2.9 requires value to be a
+   power of two from [256, 1024] range. In addition to that, this may work only
+   for a subset of interface types, e.g. aforementioned QEMU enables this option
+   only for ``vhostuser`` type. :since:`Since 3.7.0 (QEMU and KVM only)`
+   **In general you should leave this option alone, unless you are very certain
+   you know what you are doing.**
+virtio options
+   For virtio interfaces, `Virtio-specific options <#elementsVirtio>`__ can also
+   be set. ( :since:`Since 3.5.0` )
+
+Offloading options for the host and guest can be configured using the following
+sub-elements:
+
+``host``
+   The ``csum``, ``gso``, ``tso4``, ``tso6``, ``ecn`` and ``ufo`` attributes
+   with possible values ``on`` and ``off`` can be used to turn off host
+   offloading options. By default, the supported offloads are enabled by QEMU.
+   :since:`Since 1.2.9 (QEMU only)` The ``mrg_rxbuf`` attribute can be used to
+   control mergeable rx buffers on the host side. Possible values are ``on``
+   (default) and ``off``. :since:`Since 1.2.13 (QEMU only)`
+``guest``
+   The ``csum``, ``tso4``, ``tso6``, ``ecn`` and ``ufo`` attributes with
+   possible values ``on`` and ``off`` can be used to turn off guest offloading
+   options. By default, the supported offloads are enabled by QEMU.
+   :since:`Since 1.2.9 (QEMU only)`
+
+:anchor:`<a id="elementsBackendOptions"/>`
+
+Setting network backend-specific options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <target dev='vnet1'/>
+       <model type='virtio'/>
+       <backend tap='/dev/net/tun' vhost='/dev/vhost-net'/>
+       <driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5'/>
+       <tune>
+         <sndbuf>1600</sndbuf>
+       </tune>
+     </interface>
+   </devices>
+   ...
+
+For tuning the backend of the network, the ``backend`` element can be used. The
+``vhost`` attribute can override the default vhost device path
+(``/dev/vhost-net``) for devices with ``virtio`` model. The ``tap`` attribute
+overrides the tun/tap device path (default: ``/dev/net/tun``) for network and
+bridge interfaces. This does not work in session mode. :since:`Since 1.2.9`
+
+For tap devices there is also ``sndbuf`` element which can adjust the size of
+send buffer in the host. :since:`Since 0.8.8`
+
+:anchor:`<a id="elementsNICSTargetOverride"/>`
+
+Overriding the target element
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <target dev='vnet1'/>
+     </interface>
+   </devices>
+   ...
+
+If no target is specified, certain hypervisors will automatically generate a
+name for the created tun device. This name can be manually specified, however
+the name *should not start with either 'vnet', 'vif', 'macvtap', or 'macvlan'*,
+which are prefixes reserved by libvirt and certain hypervisors. Manually
+specified targets using these prefixes may be ignored.
+
+Note that for LXC containers, this defines the name of the interface on the host
+side. :since:`Since 1.2.7` , to define the name of the device on the guest side,
+the ``guest`` element should be used, as in the following snippet:
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <guest dev='myeth'/>
+     </interface>
+   </devices>
+   ...
+
+:anchor:`<a id="elementsNICSBoot"/>`
+
+Specifying boot order
+^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <target dev='vnet1'/>
+       <boot order='1'/>
+     </interface>
+   </devices>
+   ...
+
+For hypervisors which support this, you can set a specific NIC to be used for
+network boot. The ``order`` attribute determines the order in which devices will
+be tried during boot sequence. The per-device ``boot`` elements cannot be used
+together with general boot elements in `BIOS bootloader <#elementsOSBIOS>`__
+section. :since:`Since 0.8.8`
+
+:anchor:`<a id="elementsNICSROM"/>`
+
+Interface ROM BIOS configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <target dev='vnet1'/>
+       <rom bar='on' file='/etc/fake/boot.bin'/>
+     </interface>
+   </devices>
+   ...
+
+For hypervisors which support this, you can change how a PCI Network device's
+ROM is presented to the guest. The ``bar`` attribute can be set to "on" or
+"off", and determines whether or not the device's ROM will be visible in the
+guest's memory map. (In PCI documentation, the "rombar" setting controls the
+presence of the Base Address Register for the ROM). If no rom bar is specified,
+the qemu default will be used (older versions of qemu used a default of "off",
+while newer qemus have a default of "on"). The optional ``file`` attribute is
+used to point to a binary file to be presented to the guest as the device's ROM
+BIOS. This can be useful to provide an alternative boot ROM for a network
+device. :since:`Since 0.9.10 (QEMU and KVM only)` .
+
+:anchor:`<a id="elementDomain"/>`
+
+Setting up a network backend in a driver domain
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     ...
+     <interface type='bridge'>
+       <source bridge='br0'/>
+       <backenddomain name='netvm'/>
+     </interface>
+     ...
+   </devices>
+   ...
+
+The optional ``backenddomain`` element allows specifying a backend domain (aka
+driver domain) for the interface. Use the ``name`` attribute to specify the
+backend domain name. You can use it to create a direct network link between
+domains (so data will not go through host system). Use with type 'ethernet' to
+create plain network link, or with type 'bridge' to connect to a bridge inside
+the backend domain. :since:`Since 1.2.13 (Xen only)`
+
+:anchor:`<a id="elementQoS"/>`
+
+Quality of service
+^^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <target dev='vnet0'/>
+       <bandwidth>
+         <inbound average='1000' peak='5000' floor='200' burst='1024'/>
+         <outbound average='128' peak='256' burst='256'/>
+       </bandwidth>
+     </interface>
+   </devices>
+   ...
+
+This part of interface XML provides setting quality of service. Incoming and
+outgoing traffic can be shaped independently. The ``bandwidth`` element and its
+child elements are described in the `QoS <formatnetwork.html#elementQoS>`__
+section of the Network XML.
+
+:anchor:`<a id="elementVlanTag"/>`
+
+Setting VLAN tag (on supported network types only)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='bridge'>
+       <vlan>
+         <tag id='42'/>
+       </vlan>
+       <source bridge='ovsbr0'/>
+       <virtualport type='openvswitch'>
+         <parameters interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
+       </virtualport>
+     </interface>
+     <interface type='bridge'>
+       <vlan trunk='yes'>
+         <tag id='42'/>
+         <tag id='123' nativeMode='untagged'/>
+       </vlan>
+       ...
+     </interface>
+   </devices>
+   ...
+
+If (and only if) the network connection used by the guest supports VLAN tagging
+transparent to the guest, an optional ``<vlan>`` element can specify one or more
+VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` .
+Network connections that support guest-transparent VLAN tagging include 1)
+type='bridge' interfaces connected to an Open vSwitch bridge :since:`Since
+0.10.0` , 2) SRIOV Virtual Functions (VF) used via type='hostdev' (direct device
+assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type='direct' with
+mode='passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All other
+connection types, including standard linux bridges and libvirt's own virtual
+networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
+provide their own way (outside of libvirt) to tag guest traffic onto a specific
+VLAN. Each tag is given in a separate ``<tag>`` subelement of ``<vlan>`` (for
+example: ``<tag       id='42'/>``). For VLAN trunking of multiple tags (which is
+supported only on Open vSwitch connections), multiple ``<tag>`` subelements can
+be specified, which implies that the user wants to do VLAN trunking on the
+interface for all the specified tags. In the case that VLAN trunking of a single
+tag is desired, the optional attribute ``trunk='yes'`` can be added to the
+toplevel ``<vlan>`` element to differentiate trunking of a single tag from
+normal tagging.
+
+For network connections using Open vSwitch it is also possible to configure
+'native-tagged' and 'native-untagged' VLAN modes :since:`Since 1.1.0.` This is
+done with the optional ``nativeMode`` attribute on the ``<tag>`` subelement:
+``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute of the
+``<tag>`` subelement containing ``nativeMode`` sets which VLAN is considered to
+be the "native" VLAN for this interface, and the ``nativeMode`` attribute
+determines whether or not traffic for that VLAN will be tagged.
+
+:anchor:`<a id="elementPort"/>`
+
+Isolating guests's network traffic from each other
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <port isolated='yes'/>
+     </interface>
+   </devices>
+   ...
+
+:since:`Since 6.1.0.` The ``port`` element property ``isolated``, when set to
+``yes`` (default setting is ``no``) is used to isolate this interface's network
+traffic from that of other guest interfaces connected to the same network that
+also have ``<port isolated='yes'/>``. This setting is only supported for
+emulated interface devices that use a standard tap device to connect to the
+network via a Linux host bridge. This property can be inherited from a libvirt
+network, so if all guests that will be connected to the network should be
+isolated, it is better to put the setting in the network configuration. (NB:
+this only prevents guests that have ``isolated='yes'`` from communicating with
+each other; if there is a guest on the same bridge that doesn't have
+``isolated='yes'``, even the isolated guests will be able to communicate with
+it.)
+
+:anchor:`<a id="elementLink"/>`
+
+Modifying virtual link state
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <target dev='vnet0'/>
+       <link state='down'/>
+     </interface>
+   </devices>
+   ...
+
+This element provides means of setting state of the virtual network link.
+Possible values for attribute ``state`` are ``up`` and ``down``. If ``down`` is
+specified as the value, the interface behaves as if it had the network cable
+disconnected. Default behavior if this element is unspecified is to have the
+link state ``up``. :since:`Since 0.9.5`
+
+:anchor:`<a id="mtu"/>`
+
+MTU configuration
+^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <target dev='vnet0'/>
+       <mtu size='1500'/>
+     </interface>
+   </devices>
+   ...
+
+This element provides means of setting MTU of the virtual network link.
+Currently there is just one attribute ``size`` which accepts a non-negative
+integer which specifies the MTU size for the interface. :since:`Since 3.1.0`
+
+:anchor:`<a id="coalesce"/>`
+
+Coalesce settings
+^^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <target dev='vnet0'/>
+       <coalesce>
+         <rx>
+           <frames max='7'/>
+         </rx>
+       </coalesce>
+     </interface>
+   </devices>
+   ...
+
+This element provides means of setting coalesce settings for some interface
+devices (currently only type ``network`` and ``bridge``. Currently there is just
+one attribute, ``max``, to tweak, in element ``frames`` for the ``rx`` group,
+which accepts a non-negative integer that specifies the maximum number of
+packets that will be received before an interrupt. :since:`Since 3.3.0`
+
+:anchor:`<a id="ipconfig"/>`
+
+IP configuration
+^^^^^^^^^^^^^^^^
+
+::
+
+   ...
+   <devices>
+     <interface type='network'>
+       <source network='default'/>
+       <target dev='vnet0'/>
+       <ip address='192.168.122.5' prefix='24'/>
+       <ip address='192.168.122.5' prefix='24' peer='10.0.0.10'/>
+       <route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/>
+       <route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/>
+     </interface>
+     ...
+     <hostdev mode='capabilities' type='net'>
+       <source>
+         <interface>eth0</interface>
+       </source>
+       <ip address='192.168.122.6' prefix='24'/>
+       <route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/>
+       <route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/>
+     </hostdev>
+     ...
+   </devices>
+   ...
+
+:since:`Since 1.2.12` network devices and hostdev devices with network
+capabilities can optionally be provided one or more IP addresses to set on the
+network device in the guest. Note that some hypervisors or network device types
+will simply ignore them or only use the first one. The ``family`` attribute can
+be set to either ``ipv4`` or ``ipv6``, and the ``address`` attribute contains
+the IP address. The optional ``prefix`` is the number of 1 bits in the netmask,
+and will be automatically set if not specified - for IPv4 the default prefix is
+determined according to the network "class" (A, B, or C - see RFC870), and for
+IPv6 the default prefix is 64. The optional ``peer`` attribute holds the IP
+address of the other end of a point-to-point network device :since:`(since
+2.1.0)` .
+
+:since:`Since 1.2.12` route elements can also be added to define IP routes to
+add in the guest. The attributes of this element are described in the
+documentation for the ``route`` element in `network
+definitions <formatnetwork.html#elementsStaticroute>`__. This is used by the LXC
+driver.
+
+::
+
+   ...
+   <devices>
+     <interface type='ethernet'>
+       <source/>
+         <ip address='192.168.123.1' prefix='24'/>
+         <ip address='10.0.0.10' prefix='24' peer='192.168.122.5'/>
+         <route family='ipv4' address='192.168.42.0' prefix='24' gateway='192.168.123.4'/>
+       <source/>
+       ...
+     </interface>
+     ...
+   </devices>
+   ...
+
+:since:`Since 2.1.0` network devices of type "ethernet" can optionally be
+provided one or more IP addresses and one or more routes to set on the **host**
+side of the network device. These are configured as subelements of the
+``<source>`` element of the interface, and have the same attributes as the
+similarly named elements used to configure the guest side of the interface
+(described above).
+
+:anchor:`<a id="elementVhostuser"/>`
+
+vhost-user interface
+^^^^^^^^^^^^^^^^^^^^
+
+:since:`Since 1.2.7` the vhost-user enables the communication between a QEMU
+virtual machine and other userspace process using the Virtio transport protocol.
+A char dev (e.g. Unix socket) is used for the control plane, while the data
+plane is based on shared memory.
+
+::
+
+   ...
+   <devices>
+     <interface type='vhostuser'>
+       <mac address='52:54:00:3b:83:1a'/>
+       <source type='unix' path='/tmp/vhost1.sock' mode='server'/>
+       <model type='virtio'/>
+     </interface>
+     <interface type='vhostuser'>
+       <mac address='52:54:00:3b:83:1b'/>
+       <source type='unix' path='/tmp/vhost2.sock' mode='client'>
+         <reconnect enabled='yes' timeout='10'/>
+       </source>
+       <model type='virtio'/>
+       <driver queues='5'/>
+     </interface>
+   </devices>
+   ...
+
+The ``<source>`` element has to be specified along with the type of char device.
+Currently, only type='unix' is supported, where the path (the directory path of
+the socket) and mode attributes are required. Both ``mode='server'`` and
+``mode='client'`` are supported. vhost-user requires the virtio model type, thus
+the ``<model>`` element is mandatory. :since:`Since 4.1.0` the element has an
+optional child element ``reconnect`` which configures reconnect timeout if the
+connection is lost. It has two attributes ``enabled`` (which accepts ``yes`` and
+``no``) and ``timeout`` which specifies the amount of seconds after which
+hypervisor tries to reconnect.
+
+:anchor:`<a id="elementNwfilter"/>`
+
+Traffic filtering with NWFilter
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:since:`Since 0.8.0` an ``nwfilter`` profile can be assigned to a domain
+interface, which allows configuring traffic filter rules for the virtual
+machine. See the `nwfilter <formatnwfilter.html>`__ documentation for more
+complete details.
+
+::
+
+   ...
+   <devices>
+     <interface ...>
+       ...
+       <filterref filter='clean-traffic'/>
+     </interface>
+     <interface ...>
+       ...
+       <filterref filter='myfilter'>
+         <parameter name='IP' value='104.207.129.11'/>
+         <parameter name='IP6_ADDR' value='2001:19f0:300:2102::'/>
+         <parameter name='IP6_MASK' value='64'/>
+         ...
+       </filterref>
+     </interface>
+   </devices>
+   ...
+
+The ``filter`` attribute specifies the name of the nwfilter to use. Optional
+``<parameter>`` elements may be specified for passing additional info to the
+nwfilter via the ``name`` and ``value`` attributes. See the
+`nwfilter <formatnwfilter.html#nwfconceptsvars>`__ docs for info on parameters.
diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst
index 4b5391f77b..4334feb428 100644
--- a/docs/formatdomain-devices.rst
+++ b/docs/formatdomain-devices.rst
@@ -48,1265 +48,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
 .. include:: formatdomain-devices-hostdev.rst
 .. include:: formatdomain-devices-redirdev.rst
 .. include:: formatdomain-devices-smartcard.rst
-
-:anchor:`<a id="elementsNICS"/>`
-
-Network interfaces
-~~~~~~~~~~~~~~~~~~
-
-::
-
-   ...
-   <devices>
-     <interface type='direct' trustGuestRxFilters='yes'>
-       <source dev='eth0'/>
-       <mac address='52:54:00:5d:c7:9e'/>
-       <boot order='1'/>
-       <rom bar='off'/>
-     </interface>
-   </devices>
-   ...
-
-There are several possibilities for specifying a network interface visible to
-the guest. Each subsection below provides more details about common setup
-options.
-
-:since:`Since 1.2.10` ), the ``interface`` element property
-``trustGuestRxFilters`` provides the capability for the host to detect and trust
-reports from the guest regarding changes to the interface mac address and
-receive filters by setting the attribute to ``yes``. The default setting for the
-attribute is ``no`` for security reasons and support depends on the guest
-network device model as well as the type of connection on the host - currently
-it is only supported for the virtio device model and for macvtap connections on
-the host.
-
-Each ``<interface>`` element has an optional ``<address>`` sub-element that can
-tie the interface to a particular pci slot, with attribute ``type='pci'`` as
-`documented above <#elementsAddress>`__.
-
-:since:`Since 6.6.0` , one can force libvirt to keep the provided MAC address
-when it's in the reserved VMware range by adding a ``type="static"`` attribute
-to the ``<mac/>`` element. Note that this attribute is useless if the provided
-MAC address is outside of the reserved VMWare ranges.
-
-:anchor:`<a id="elementsNICSVirtual"/>`
-
-Virtual network
-^^^^^^^^^^^^^^^
-
-**This is the recommended config for general guest connectivity on hosts with
-dynamic / wireless networking configs (or multi-host environments where the host
-hardware details are described separately in a ``<network>`` definition
-:since:`Since 0.9.4` ).**
-
-Provides a connection whose details are described by the named network
-definition. Depending on the virtual network's "forward mode" configuration, the
-network may be totally isolated (no ``<forward>`` element given), NAT'ing to an
-explicit network device or to the default route (``<forward mode='nat'>``),
-routed with no NAT (``<forward mode='route'/>``), or connected directly to one
-of the host's network interfaces (via macvtap) or bridge devices
-((``<forward       mode='bridge|private|vepa|passthrough'/>`` :since:`Since
-0.9.4` )
-
-For networks with a forward mode of bridge, private, vepa, and passthrough, it
-is assumed that the host has any necessary DNS and DHCP services already setup
-outside the scope of libvirt. In the case of isolated, nat, and routed networks,
-DHCP and DNS are provided on the virtual network by libvirt, and the IP range
-can be determined by examining the virtual network config with
-'``virsh net-dumpxml [networkname]``'. There is one virtual network called
-'default' setup out of the box which does NAT'ing to the default route and has
-an IP range of ``192.168.122.0/255.255.255.0``. Each guest will have an
-associated tun device created with a name of vnetN, which can also be overridden
-with the <target> element (see `overriding the target
-element <#elementsNICSTargetOverride>`__).
-
-When the source of an interface is a network, a ``portgroup`` can be specified
-along with the name of the network; one network may have multiple portgroups
-defined, with each portgroup containing slightly different configuration
-information for different classes of network connections. :since:`Since 0.9.4` .
-
-When a guest is running an interface of type ``network`` may include a
-``portid`` attribute. This provides the UUID of an associated virNetworkPortPtr
-object that records the association between the domain interface and the
-network. This attribute is read-only since port objects are create and deleted
-automatically during startup and shutdown. :since:`Since 5.1.0`
-
-Also, similar to ``direct`` network connections (described below), a connection
-of type ``network`` may specify a ``virtualport`` element, with configuration
-data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant switch (
-:since:`Since 0.8.2` ), or to an Open vSwitch virtual switch ( :since:`Since
-0.9.11` ).
-
-Since the actual type of switch may vary depending on the configuration in the
-``<network>`` on the host, it is acceptable to omit the virtualport ``type``
-attribute, and specify attributes from multiple different virtualport types (and
-also to leave out certain attributes); at domain startup time, a complete
-``<virtualport>`` element will be constructed by merging together the type and
-attributes defined in the network and the portgroup referenced by the interface.
-The newly-constructed virtualport is a combination of them. The attributes from
-lower virtualport can't make change on the ones defined in higher virtualport.
-Interface takes the highest priority, portgroup is lowest priority. (
-:since:`Since 0.10.0` ). For example, in order to work properly with both an
-802.1Qbh switch and an Open vSwitch switch, you may choose to specify no type,
-but both a ``profileid`` (in case the switch is 802.1Qbh) and an ``interfaceid``
-(in case the switch is Open vSwitch) (you may also omit the other attributes,
-such as managerid, typeid, or profileid, to be filled in from the network's
-``<virtualport>``). If you want to limit a guest to connecting only to certain
-types of switches, you can specify the virtualport type, but still omit some/all
-of the parameters - in this case if the host's network has a different type of
-virtualport, connection of the interface will fail.
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-     </interface>
-     ...
-     <interface type='network'>
-       <source network='default' portgroup='engineering'/>
-       <target dev='vnet7'/>
-       <mac address="00:11:22:33:44:55"/>
-       <virtualport>
-         <parameters instanceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
-       </virtualport>
-     </interface>
-   </devices>
-   ...
-
-:anchor:`<a id="elementsNICSBridge"/>`
-
-Bridge to LAN
-^^^^^^^^^^^^^
-
-**This is the recommended config for general guest connectivity on hosts with
-static wired networking configs.**
-
-Provides a bridge from the VM directly to the LAN. This assumes there is a
-bridge device on the host which has one or more of the hosts physical NICs
-attached. The guest VM will have an associated tun device created with a name of
-vnetN, which can also be overridden with the <target> element (see `overriding
-the target element <#elementsNICSTargetOverride>`__). The tun device will be
-attached to the bridge. The IP range / network configuration is whatever is used
-on the LAN. This provides the guest VM full incoming & outgoing net access just
-like a physical machine.
-
-On Linux systems, the bridge device is normally a standard Linux host bridge. On
-hosts that support Open vSwitch, it is also possible to connect to an Open
-vSwitch bridge device by adding a ``<virtualport type='openvswitch'/>`` to the
-interface definition. ( :since:`Since 0.9.11` ). The Open vSwitch type
-virtualport accepts two parameters in its ``<parameters>`` element - an
-``interfaceid`` which is a standard uuid used to uniquely identify this
-particular interface to Open vSwitch (if you do not specify one, a random
-interfaceid will be generated for you when you first define the interface), and
-an optional ``profileid`` which is sent to Open vSwitch as the interfaces
-"port-profile".
-
-::
-
-   ...
-   <devices>
-     ...
-     <interface type='bridge'>
-       <source bridge='br0'/>
-     </interface>
-     <interface type='bridge'>
-       <source bridge='br1'/>
-       <target dev='vnet7'/>
-       <mac address="00:11:22:33:44:55"/>
-     </interface>
-     <interface type='bridge'>
-       <source bridge='ovsbr'/>
-       <virtualport type='openvswitch'>
-         <parameters profileid='menial' interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
-       </virtualport>
-     </interface>
-     ...
-   </devices>
-   ...
-
-On hosts that support Open vSwitch on the kernel side and have the Midonet Host
-Agent configured, it is also possible to connect to the 'midonet' bridge device
-by adding a ``<virtualport type='midonet'/>`` to the interface definition. (
-:since:`Since 1.2.13` ). The Midonet virtualport type requires an
-``interfaceid`` attribute in its ``<parameters>`` element. This interface id is
-the UUID that specifies which port in the virtual network topology will be bound
-to the interface.
-
-::
-
-   ...
-   <devices>
-     ...
-     <interface type='bridge'>
-       <source bridge='br0'/>
-     </interface>
-     <interface type='bridge'>
-       <source bridge='br1'/>
-       <target dev='vnet7'/>
-       <mac address="00:11:22:33:44:55"/>
-     </interface>
-     <interface type='bridge'>
-       <source bridge='midonet'/>
-       <virtualport type='midonet'>
-         <parameters interfaceid='0b2d64da-3d0e-431e-afdd-804415d6ebbb'/>
-       </virtualport>
-     </interface>
-     ...
-   </devices>
-   ...
-
-:anchor:`<a id="elementsNICSSlirp"/>`
-
-Userspace SLIRP stack
-^^^^^^^^^^^^^^^^^^^^^
-
-Provides a virtual LAN with NAT to the outside world. The virtual network has
-DHCP & DNS services and will give the guest VM addresses starting from
-``10.0.2.15``. The default router will be ``10.0.2.2`` and the DNS server will
-be ``10.0.2.3``. This networking is the only option for unprivileged users who
-need their VMs to have outgoing access. :since:`Since 3.8.0` it is possible to
-override the default network address by including an ``ip`` element specifying
-an IPv4 address in its one mandatory attribute, ``address``. Optionally, a
-second ``ip`` element with a ``family`` attribute set to "ipv6" can be specified
-to add an IPv6 address to the interface. ``address``. Optionally, address
-``prefix`` can be specified.
-
-::
-
-   ...
-   <devices>
-     <interface type='user'/>
-     ...
-     <interface type='user'>
-       <mac address="00:11:22:33:44:55"/>
-       <ip family='ipv4' address='172.17.2.0' prefix='24'/>
-       <ip family='ipv6' address='2001:db8:ac10:fd01::' prefix='64'/>
-     </interface>
-   </devices>
-   ...
-
-:anchor:`<a id="elementsNICSEthernet"/>`
-
-Generic ethernet connection
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Provides a means to use a new or existing tap device (or veth device pair,
-depening on the needs of the hypervisor driver) that is partially or wholly
-setup external to libvirt (either prior to the guest starting, or while the
-guest is being started via an optional script specified in the config).
-
-The name of the tap device can optionally be specified with the ``dev``
-attribute of the ``<target>`` element. If no target dev is specified, libvirt
-will create a new standard tap device with a name of the pattern "vnetN", where
-"N" is replaced with a number. If a target dev is specified and that device
-doesn't exist, then a new standard tap device will be created with the exact dev
-name given. If the specified target dev does exist, then that existing device
-will be used. Usually some basic setup of the device is done by libvirt,
-including setting a MAC address, and the IFF_UP flag, but if the ``dev`` is a
-pre-existing device, and the ``managed`` attribute of the ``target`` element is
-also set to "no" (the default value is "yes"), even this basic setup will not be
-performed - libvirt will simply pass the device on to the hypervisor with no
-setup at all. :since:`Since 5.7.0` Using managed='no' with a pre-created tap
-device is useful because it permits a virtual machine managed by an unprivileged
-libvirtd to have emulated network devices based on tap devices.
-
-After creating/opening the tap device, an optional shell script (given in the
-``path`` attribute of the ``<script>`` element) will be run. :since:`Since
-0.2.1` Also, after detaching/closing the tap device, an optional shell script
-(given in the ``path`` attribute of the ``<downscript>`` element) will be run.
-:since:`Since 5.1.0` These can be used to do whatever extra host network
-integration is required.
-
-::
-
-   ...
-   <devices>
-     <interface type='ethernet'>
-       <script path='/etc/qemu-ifup-mynet'/>
-       <downscript path='/etc/qemu-ifdown-mynet'/>
-     </interface>
-     ...
-     <interface type='ethernet'>
-       <target dev='mytap1' managed='no'/>
-       <model type='virtio'/>
-     </interface>
-   </devices>
-   ...
-
-:anchor:`<a id="elementsNICSDirect"/>`
-
-Direct attachment to physical interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-| Provides direct attachment of the virtual machine's NIC to the given physical
-  interface of the host. :since:`Since 0.7.7 (QEMU and KVM only)`
-| This setup requires the Linux macvtap driver to be available. :since:`(Since
-  Linux 2.6.34.)` One of the modes 'vepa' ( `'Virtual Ethernet Port
-  Aggregator' <http://www.ieee802.org/1/files/public/docs2009/new-evb-congdon-vepa-modular-0709-v01.pdf>`__),
-  'bridge' or 'private' can be chosen for the operation mode of the macvtap
-  device, 'vepa' being the default mode. The individual modes cause the delivery
-  of packets to behave as follows:
-
-If the model type is set to ``virtio`` and interface's ``trustGuestRxFilters``
-attribute is set to ``yes``, changes made to the interface mac address,
-unicast/multicast receive filters, and vlan settings in the guest will be
-monitored and propagated to the associated macvtap device on the host (
-:since:`Since 1.2.10` ). If ``trustGuestRxFilters`` is not set, or is not
-supported for the device model in use, an attempted change to the mac address
-originating from the guest side will result in a non-working network connection.
-
-``vepa``
-   All VMs' packets are sent to the external bridge. Packets whose destination
-   is a VM on the same host as where the packet originates from are sent back to
-   the host by the VEPA capable bridge (today's bridges are typically not VEPA
-   capable).
-``bridge``
-   Packets whose destination is on the same host as where they originate from
-   are directly delivered to the target macvtap device. Both origin and
-   destination devices need to be in bridge mode for direct delivery. If either
-   one of them is in ``vepa`` mode, a VEPA capable bridge is required.
-``private``
-   All packets are sent to the external bridge and will only be delivered to a
-   target VM on the same host if they are sent through an external router or
-   gateway and that device sends them back to the host. This procedure is
-   followed if either the source or destination device is in ``private`` mode.
-``passthrough``
-   This feature attaches a virtual function of a SRIOV capable NIC directly to a
-   VM without losing the migration capability. All packets are sent to the VF/IF
-   of the configured network device. Depending on the capabilities of the device
-   additional prerequisites or limitations may apply; for example, on Linux this
-   requires kernel 2.6.38 or newer. :since:`Since 0.9.2`
-
-::
-
-   ...
-   <devices>
-     ...
-     <interface type='direct' trustGuestRxFilters='no'>
-       <source dev='eth0' mode='vepa'/>
-     </interface>
-   </devices>
-   ...
-
-The network access of direct attached virtual machines can be managed by the
-hardware switch to which the physical interface of the host machine is connected
-to.
-
-The interface can have additional parameters as shown below, if the switch is
-conforming to the IEEE 802.1Qbg standard. The parameters of the virtualport
-element are documented in more detail in the IEEE 802.1Qbg standard. The values
-are network specific and should be provided by the network administrator. In
-802.1Qbg terms, the Virtual Station Interface (VSI) represents the virtual
-interface of a virtual machine. :since:`Since 0.8.2`
-
-Please note that IEEE 802.1Qbg requires a non-zero value for the VLAN ID.
-
-``managerid``
-   The VSI Manager ID identifies the database containing the VSI type and
-   instance definitions. This is an integer value and the value 0 is reserved.
-``typeid``
-   The VSI Type ID identifies a VSI type characterizing the network access. VSI
-   types are typically managed by network administrator. This is an integer
-   value.
-``typeidversion``
-   The VSI Type Version allows multiple versions of a VSI Type. This is an
-   integer value.
-``instanceid``
-   The VSI Instance ID Identifier is generated when a VSI instance (i.e. a
-   virtual interface of a virtual machine) is created. This is a globally unique
-   identifier.
-
-::
-
-   ...
-   <devices>
-     ...
-     <interface type='direct'>
-       <source dev='eth0.2' mode='vepa'/>
-       <virtualport type="802.1Qbg">
-         <parameters managerid="11" typeid="1193047" typeidversion="2" instanceid="09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f"/>
-       </virtualport>
-     </interface>
-   </devices>
-   ...
-
-The interface can have additional parameters as shown below if the switch is
-conforming to the IEEE 802.1Qbh standard. The values are network specific and
-should be provided by the network administrator. :since:`Since 0.8.2`
-
-``profileid``
-   The profile ID contains the name of the port profile that is to be applied to
-   this interface. This name is resolved by the port profile database into the
-   network parameters from the port profile, and those network parameters will
-   be applied to this interface.
-
-::
-
-   ...
-   <devices>
-     ...
-     <interface type='direct'>
-       <source dev='eth0' mode='private'/>
-       <virtualport type='802.1Qbh'>
-         <parameters profileid='finance'/>
-       </virtualport>
-     </interface>
-   </devices>
-   ...
-
-:anchor:`<a id="elementsNICSHostdev"/>`
-
-PCI Passthrough
-^^^^^^^^^^^^^^^
-
-A PCI network device (specified by the <source> element) is directly assigned to
-the guest using generic device passthrough, after first optionally setting the
-device's MAC address to the configured value, and associating the device with an
-802.1Qbh capable switch using an optionally specified <virtualport> element (see
-the examples of virtualport given above for type='direct' network devices). Note
-that - due to limitations in standard single-port PCI ethernet card driver
-design - only SR-IOV (Single Root I/O Virtualization) virtual function (VF)
-devices can be assigned in this manner; to assign a standard single-port PCI or
-PCIe ethernet card to a guest, use the traditional <hostdev> device definition
-and :since:`Since 0.9.11`
-
-To use VFIO device assignment rather than traditional/legacy KVM device
-assignment (VFIO is a new method of device assignment that is compatible with
-UEFI Secure Boot), a type='hostdev' interface can have an optional ``driver``
-sub-element with a ``name`` attribute set to "vfio". To use legacy KVM device
-assignment you can set ``name`` to "kvm" (or simply omit the ``<driver>``
-element, since "kvm" is currently the default). :since:`Since 1.0.5 (QEMU and
-KVM only, requires kernel 3.6 or newer)`
-
-Note that this "intelligent passthrough" of network devices is very similar to
-the functionality of a standard <hostdev> device, the difference being that this
-method allows specifying a MAC address and <virtualport> for the passed-through
-device. If these capabilities are not required, if you have a standard
-single-port PCI, PCIe, or USB network card that doesn't support SR-IOV (and
-hence would anyway lose the configured MAC address during reset after being
-assigned to the guest domain), or if you are using a version of libvirt older
-than 0.9.11, you should use standard <hostdev> to assign the device to the guest
-instead of <interface type='hostdev'/>.
-
-Similar to the functionality of a standard <hostdev> device, when ``managed`` is
-"yes", it is detached from the host before being passed on to the guest, and
-reattached to the host after the guest exits. If ``managed`` is omitted or "no",
-the user is responsible to call ``virNodeDeviceDettach`` (or
-``virsh nodedev-detach``) before starting the guest or hot-plugging the device,
-and ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-unplug
-or stopping the guest.
-
-::
-
-   ...
-   <devices>
-     <interface type='hostdev' managed='yes'>
-       <driver name='vfio'/>
-       <source>
-         <address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/>
-       </source>
-       <mac address='52:54:00:6d:90:02'/>
-       <virtualport type='802.1Qbh'>
-         <parameters profileid='finance'/>
-       </virtualport>
-     </interface>
-   </devices>
-   ...
-
-:anchor:`<a id="elementsTeaming"/>`
-
-Teaming a virtio/hostdev NIC pair
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-:since:`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, 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.
-
-:anchor:`<a id="elementsNICSMulticast"/>`
-
-Multicast tunnel
-^^^^^^^^^^^^^^^^
-
-A multicast group is setup to represent a virtual network. Any VMs whose network
-devices are in the same multicast group can talk to each other even across
-hosts. This mode is also available to unprivileged users. There is no default
-DNS or DHCP support and no outgoing network access. To provide outgoing network
-access, one of the VMs should have a 2nd NIC which is connected to one of the
-first 4 network types and do the appropriate routing. The multicast protocol is
-compatible with that used by user mode linux guests too. The source address used
-must be from the multicast address block.
-
-::
-
-   ...
-   <devices>
-     <interface type='mcast'>
-       <mac address='52:54:00:6d:90:01'/>
-       <source address='230.0.0.1' port='5558'/>
-     </interface>
-   </devices>
-   ...
-
-:anchor:`<a id="elementsNICSTCP"/>`
-
-TCP tunnel
-^^^^^^^^^^
-
-A TCP client/server architecture provides a virtual network. One VM provides the
-server end of the network, all other VMS are configured as clients. All network
-traffic is routed between the VMs via the server. This mode is also available to
-unprivileged users. There is no default DNS or DHCP support and no outgoing
-network access. To provide outgoing network access, one of the VMs should have a
-2nd NIC which is connected to one of the first 4 network types and do the
-appropriate routing.
-
-::
-
-   ...
-   <devices>
-     <interface type='server'>
-       <mac address='52:54:00:22:c9:42'/>
-       <source address='192.168.0.1' port='5558'/>
-     </interface>
-     ...
-     <interface type='client'>
-       <mac address='52:54:00:8b:c9:51'/>
-       <source address='192.168.0.1' port='5558'/>
-     </interface>
-   </devices>
-   ...
-
-:anchor:`<a id="elementsNICSUDP"/>`
-
-UDP unicast tunnel
-^^^^^^^^^^^^^^^^^^
-
-A UDP unicast architecture provides a virtual network which enables connections
-between QEMU instances using QEMU's UDP infrastructure. The xml "source" address
-is the endpoint address to which the UDP socket packets will be sent from the
-host running QEMU. The xml "local" address is the address of the interface from
-which the UDP socket packets will originate from the QEMU host. :since:`Since
-1.2.20`
-
-::
-
-   ...
-   <devices>
-     <interface type='udp'>
-       <mac address='52:54:00:22:c9:42'/>
-       <source address='127.0.0.1' port='11115'>
-         <local address='127.0.0.1' port='11116'/>
-       </source>
-     </interface>
-   </devices>
-   ...
-
-:anchor:`<a id="elementsNICSModel"/>`
-
-Setting the NIC model
-^^^^^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <target dev='vnet1'/>
-       <model type='ne2k_pci'/>
-     </interface>
-   </devices>
-   ...
-
-For hypervisors which support this, you can set the model of emulated network
-interface card.
-
-The values for ``type`` aren't defined specifically by libvirt, but by what the
-underlying hypervisor supports (if any). For QEMU and KVM you can get a list of
-supported models with these commands:
-
-::
-
-   qemu -net nic,model=? /dev/null
-   qemu-kvm -net nic,model=? /dev/null
-
-Typical values for QEMU and KVM include: ne2k_isa i82551 i82557b i82559er
-ne2k_pci pcnet rtl8139 e1000 virtio. :since:`Since 5.2.0` ,
-``virtio-transitional`` and ``virtio-non-transitional`` values are supported.
-See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more
-details.
-
-:anchor:`<a id="elementsDriverBackendOptions"/>`
-
-Setting NIC driver-specific options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <target dev='vnet1'/>
-       <model type='virtio'/>
-       <driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5' rx_queue_size='256' tx_queue_size='256'>
-         <host csum='off' gso='off' tso4='off' tso6='off' ecn='off' ufo='off' mrg_rxbuf='off'/>
-         <guest csum='off' tso4='off' tso6='off' ecn='off' ufo='off'/>
-       </driver>
-       </interface>
-   </devices>
-   ...
-
-Some NICs may have tunable driver-specific options. These are set as attributes
-of the ``driver`` sub-element of the interface definition. Currently the
-following attributes are available for the ``"virtio"`` NIC driver:
-
-``name``
-   The optional ``name`` attribute forces which type of backend driver to use.
-   The value can be either 'qemu' (a user-space backend) or 'vhost' (a kernel
-   backend, which requires the vhost module to be provided by the kernel); an
-   attempt to require the vhost driver without kernel support will be rejected.
-   If this attribute is not present, then the domain defaults to 'vhost' if
-   present, but silently falls back to 'qemu' without error. :since:`Since 0.8.8
-   (QEMU and KVM only)`
-   For interfaces of type='hostdev' (PCI passthrough devices) the ``name``
-   attribute can optionally be set to "vfio" or "kvm". "vfio" tells libvirt to
-   use VFIO device assignment rather than traditional KVM device assignment
-   (VFIO is a new method of device assignment that is compatible with UEFI
-   Secure Boot), and "kvm" tells libvirt to use the legacy device assignment
-   performed directly by the kvm kernel module (the default is currently "kvm",
-   but is subject to change). :since:`Since 1.0.5 (QEMU and KVM only, requires
-   kernel 3.6 or newer)`
-   For interfaces of type='vhostuser', the ``name`` attribute is ignored. The
-   backend driver used is always vhost-user.
-``txmode``
-   The ``txmode`` attribute specifies how to handle transmission of packets when
-   the transmit buffer is full. The value can be either 'iothread' or 'timer'.
-   :since:`Since 0.8.8 (QEMU and KVM only)`
-   If set to 'iothread', packet tx is all done in an iothread in the bottom half
-   of the driver (this option translates into adding "tx=bh" to the qemu
-   commandline -device virtio-net-pci option).
-   If set to 'timer', tx work is done in qemu, and if there is more tx data than
-   can be sent at the present time, a timer is set before qemu moves on to do
-   other things; when the timer fires, another attempt is made to send more
-   data.
-   The resulting difference, according to the qemu developer who added the
-   option is: "bh makes tx more asynchronous and reduces latency, but
-   potentially causes more processor bandwidth contention since the CPU doing
-   the tx isn't necessarily the CPU where the guest generated the packets."
-   **In general you should leave this option alone, unless you are very certain
-   you know what you are doing.**
-``ioeventfd``
-   This optional attribute allows users to set `domain I/O asynchronous
-   handling <https://patchwork.kernel.org/patch/43390/>`__ for interface device.
-   The default is left to the discretion of the hypervisor. Accepted values are
-   "on" and "off". Enabling this allows qemu to execute VM while a separate
-   thread handles I/O. Typically guests experiencing high system CPU utilization
-   during I/O will benefit from this. On the other hand, on overloaded host it
-   could increase guest I/O latency. :since:`Since 0.9.3 (QEMU and KVM only)`
-   **In general you should leave this option alone, unless you are very certain
-   you know what you are doing.**
-``event_idx``
-   The ``event_idx`` attribute controls some aspects of device event processing.
-   The value can be either 'on' or 'off' - if it is on, it will reduce the
-   number of interrupts and exits for the guest. The default is determined by
-   QEMU; usually if the feature is supported, default is on. In case there is a
-   situation where this behavior is suboptimal, this attribute provides a way to
-   force the feature off. :since:`Since 0.9.5 (QEMU and KVM only)`
-   **In general you should leave this option alone, unless you are very certain
-   you know what you are doing.**
-``queues``
-   The optional ``queues`` attribute controls the number of queues to be used
-   for either `Multiqueue
-   virtio-net <https://www.linux-kvm.org/page/Multiqueue>`__ or
-   `vhost-user <#elementVhostuser>`__ network interfaces. Use of multiple packet
-   processing queues requires the interface having the
-   ``<model type='virtio'/>`` element. Each queue will potentially be handled by
-   a different processor, resulting in much higher throughput.
-   :since:`virtio-net since 1.0.6 (QEMU and KVM only)` :since:`vhost-user since
-   1.2.17 (QEMU and KVM only)`
-``rx_queue_size``
-   The optional ``rx_queue_size`` attribute controls the size of virtio ring for
-   each queue as described above. The default value is hypervisor dependent and
-   may change across its releases. Moreover, some hypervisors may pose some
-   restrictions on actual value. For instance, latest QEMU (as of 2016-09-01)
-   requires value to be a power of two from [256, 1024] range. :since:`Since
-   2.3.0 (QEMU and KVM only)`
-   **In general you should leave this option alone, unless you are very certain
-   you know what you are doing.**
-``tx_queue_size``
-   The optional ``tx_queue_size`` attribute controls the size of virtio ring for
-   each queue as described above. The default value is hypervisor dependent and
-   may change across its releases. Moreover, some hypervisors may pose some
-   restrictions on actual value. For instance, QEMU v2.9 requires value to be a
-   power of two from [256, 1024] range. In addition to that, this may work only
-   for a subset of interface types, e.g. aforementioned QEMU enables this option
-   only for ``vhostuser`` type. :since:`Since 3.7.0 (QEMU and KVM only)`
-   **In general you should leave this option alone, unless you are very certain
-   you know what you are doing.**
-virtio options
-   For virtio interfaces, `Virtio-specific options <#elementsVirtio>`__ can also
-   be set. ( :since:`Since 3.5.0` )
-
-Offloading options for the host and guest can be configured using the following
-sub-elements:
-
-``host``
-   The ``csum``, ``gso``, ``tso4``, ``tso6``, ``ecn`` and ``ufo`` attributes
-   with possible values ``on`` and ``off`` can be used to turn off host
-   offloading options. By default, the supported offloads are enabled by QEMU.
-   :since:`Since 1.2.9 (QEMU only)` The ``mrg_rxbuf`` attribute can be used to
-   control mergeable rx buffers on the host side. Possible values are ``on``
-   (default) and ``off``. :since:`Since 1.2.13 (QEMU only)`
-``guest``
-   The ``csum``, ``tso4``, ``tso6``, ``ecn`` and ``ufo`` attributes with
-   possible values ``on`` and ``off`` can be used to turn off guest offloading
-   options. By default, the supported offloads are enabled by QEMU.
-   :since:`Since 1.2.9 (QEMU only)`
-
-:anchor:`<a id="elementsBackendOptions"/>`
-
-Setting network backend-specific options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <target dev='vnet1'/>
-       <model type='virtio'/>
-       <backend tap='/dev/net/tun' vhost='/dev/vhost-net'/>
-       <driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5'/>
-       <tune>
-         <sndbuf>1600</sndbuf>
-       </tune>
-     </interface>
-   </devices>
-   ...
-
-For tuning the backend of the network, the ``backend`` element can be used. The
-``vhost`` attribute can override the default vhost device path
-(``/dev/vhost-net``) for devices with ``virtio`` model. The ``tap`` attribute
-overrides the tun/tap device path (default: ``/dev/net/tun``) for network and
-bridge interfaces. This does not work in session mode. :since:`Since 1.2.9`
-
-For tap devices there is also ``sndbuf`` element which can adjust the size of
-send buffer in the host. :since:`Since 0.8.8`
-
-:anchor:`<a id="elementsNICSTargetOverride"/>`
-
-Overriding the target element
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <target dev='vnet1'/>
-     </interface>
-   </devices>
-   ...
-
-If no target is specified, certain hypervisors will automatically generate a
-name for the created tun device. This name can be manually specified, however
-the name *should not start with either 'vnet', 'vif', 'macvtap', or 'macvlan'*,
-which are prefixes reserved by libvirt and certain hypervisors. Manually
-specified targets using these prefixes may be ignored.
-
-Note that for LXC containers, this defines the name of the interface on the host
-side. :since:`Since 1.2.7` , to define the name of the device on the guest side,
-the ``guest`` element should be used, as in the following snippet:
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <guest dev='myeth'/>
-     </interface>
-   </devices>
-   ...
-
-:anchor:`<a id="elementsNICSBoot"/>`
-
-Specifying boot order
-^^^^^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <target dev='vnet1'/>
-       <boot order='1'/>
-     </interface>
-   </devices>
-   ...
-
-For hypervisors which support this, you can set a specific NIC to be used for
-network boot. The ``order`` attribute determines the order in which devices will
-be tried during boot sequence. The per-device ``boot`` elements cannot be used
-together with general boot elements in `BIOS bootloader <#elementsOSBIOS>`__
-section. :since:`Since 0.8.8`
-
-:anchor:`<a id="elementsNICSROM"/>`
-
-Interface ROM BIOS configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <target dev='vnet1'/>
-       <rom bar='on' file='/etc/fake/boot.bin'/>
-     </interface>
-   </devices>
-   ...
-
-For hypervisors which support this, you can change how a PCI Network device's
-ROM is presented to the guest. The ``bar`` attribute can be set to "on" or
-"off", and determines whether or not the device's ROM will be visible in the
-guest's memory map. (In PCI documentation, the "rombar" setting controls the
-presence of the Base Address Register for the ROM). If no rom bar is specified,
-the qemu default will be used (older versions of qemu used a default of "off",
-while newer qemus have a default of "on"). The optional ``file`` attribute is
-used to point to a binary file to be presented to the guest as the device's ROM
-BIOS. This can be useful to provide an alternative boot ROM for a network
-device. :since:`Since 0.9.10 (QEMU and KVM only)` .
-
-:anchor:`<a id="elementDomain"/>`
-
-Setting up a network backend in a driver domain
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     ...
-     <interface type='bridge'>
-       <source bridge='br0'/>
-       <backenddomain name='netvm'/>
-     </interface>
-     ...
-   </devices>
-   ...
-
-The optional ``backenddomain`` element allows specifying a backend domain (aka
-driver domain) for the interface. Use the ``name`` attribute to specify the
-backend domain name. You can use it to create a direct network link between
-domains (so data will not go through host system). Use with type 'ethernet' to
-create plain network link, or with type 'bridge' to connect to a bridge inside
-the backend domain. :since:`Since 1.2.13 (Xen only)`
-
-:anchor:`<a id="elementQoS"/>`
-
-Quality of service
-^^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <target dev='vnet0'/>
-       <bandwidth>
-         <inbound average='1000' peak='5000' floor='200' burst='1024'/>
-         <outbound average='128' peak='256' burst='256'/>
-       </bandwidth>
-     </interface>
-   </devices>
-   ...
-
-This part of interface XML provides setting quality of service. Incoming and
-outgoing traffic can be shaped independently. The ``bandwidth`` element and its
-child elements are described in the `QoS <formatnetwork.html#elementQoS>`__
-section of the Network XML.
-
-:anchor:`<a id="elementVlanTag"/>`
-
-Setting VLAN tag (on supported network types only)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='bridge'>
-       <vlan>
-         <tag id='42'/>
-       </vlan>
-       <source bridge='ovsbr0'/>
-       <virtualport type='openvswitch'>
-         <parameters interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
-       </virtualport>
-     </interface>
-     <interface type='bridge'>
-       <vlan trunk='yes'>
-         <tag id='42'/>
-         <tag id='123' nativeMode='untagged'/>
-       </vlan>
-       ...
-     </interface>
-   </devices>
-   ...
-
-If (and only if) the network connection used by the guest supports VLAN tagging
-transparent to the guest, an optional ``<vlan>`` element can specify one or more
-VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` .
-Network connections that support guest-transparent VLAN tagging include 1)
-type='bridge' interfaces connected to an Open vSwitch bridge :since:`Since
-0.10.0` , 2) SRIOV Virtual Functions (VF) used via type='hostdev' (direct device
-assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type='direct' with
-mode='passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All other
-connection types, including standard linux bridges and libvirt's own virtual
-networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
-provide their own way (outside of libvirt) to tag guest traffic onto a specific
-VLAN. Each tag is given in a separate ``<tag>`` subelement of ``<vlan>`` (for
-example: ``<tag       id='42'/>``). For VLAN trunking of multiple tags (which is
-supported only on Open vSwitch connections), multiple ``<tag>`` subelements can
-be specified, which implies that the user wants to do VLAN trunking on the
-interface for all the specified tags. In the case that VLAN trunking of a single
-tag is desired, the optional attribute ``trunk='yes'`` can be added to the
-toplevel ``<vlan>`` element to differentiate trunking of a single tag from
-normal tagging.
-
-For network connections using Open vSwitch it is also possible to configure
-'native-tagged' and 'native-untagged' VLAN modes :since:`Since 1.1.0.` This is
-done with the optional ``nativeMode`` attribute on the ``<tag>`` subelement:
-``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute of the
-``<tag>`` subelement containing ``nativeMode`` sets which VLAN is considered to
-be the "native" VLAN for this interface, and the ``nativeMode`` attribute
-determines whether or not traffic for that VLAN will be tagged.
-
-:anchor:`<a id="elementPort"/>`
-
-Isolating guests's network traffic from each other
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <port isolated='yes'/>
-     </interface>
-   </devices>
-   ...
-
-:since:`Since 6.1.0.` The ``port`` element property ``isolated``, when set to
-``yes`` (default setting is ``no``) is used to isolate this interface's network
-traffic from that of other guest interfaces connected to the same network that
-also have ``<port isolated='yes'/>``. This setting is only supported for
-emulated interface devices that use a standard tap device to connect to the
-network via a Linux host bridge. This property can be inherited from a libvirt
-network, so if all guests that will be connected to the network should be
-isolated, it is better to put the setting in the network configuration. (NB:
-this only prevents guests that have ``isolated='yes'`` from communicating with
-each other; if there is a guest on the same bridge that doesn't have
-``isolated='yes'``, even the isolated guests will be able to communicate with
-it.)
-
-:anchor:`<a id="elementLink"/>`
-
-Modifying virtual link state
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <target dev='vnet0'/>
-       <link state='down'/>
-     </interface>
-   </devices>
-   ...
-
-This element provides means of setting state of the virtual network link.
-Possible values for attribute ``state`` are ``up`` and ``down``. If ``down`` is
-specified as the value, the interface behaves as if it had the network cable
-disconnected. Default behavior if this element is unspecified is to have the
-link state ``up``. :since:`Since 0.9.5`
-
-:anchor:`<a id="mtu"/>`
-
-MTU configuration
-^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <target dev='vnet0'/>
-       <mtu size='1500'/>
-     </interface>
-   </devices>
-   ...
-
-This element provides means of setting MTU of the virtual network link.
-Currently there is just one attribute ``size`` which accepts a non-negative
-integer which specifies the MTU size for the interface. :since:`Since 3.1.0`
-
-:anchor:`<a id="coalesce"/>`
-
-Coalesce settings
-^^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <target dev='vnet0'/>
-       <coalesce>
-         <rx>
-           <frames max='7'/>
-         </rx>
-       </coalesce>
-     </interface>
-   </devices>
-   ...
-
-This element provides means of setting coalesce settings for some interface
-devices (currently only type ``network`` and ``bridge``. Currently there is just
-one attribute, ``max``, to tweak, in element ``frames`` for the ``rx`` group,
-which accepts a non-negative integer that specifies the maximum number of
-packets that will be received before an interrupt. :since:`Since 3.3.0`
-
-:anchor:`<a id="ipconfig"/>`
-
-IP configuration
-^^^^^^^^^^^^^^^^
-
-::
-
-   ...
-   <devices>
-     <interface type='network'>
-       <source network='default'/>
-       <target dev='vnet0'/>
-       <ip address='192.168.122.5' prefix='24'/>
-       <ip address='192.168.122.5' prefix='24' peer='10.0.0.10'/>
-       <route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/>
-       <route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/>
-     </interface>
-     ...
-     <hostdev mode='capabilities' type='net'>
-       <source>
-         <interface>eth0</interface>
-       </source>
-       <ip address='192.168.122.6' prefix='24'/>
-       <route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/>
-       <route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/>
-     </hostdev>
-     ...
-   </devices>
-   ...
-
-:since:`Since 1.2.12` network devices and hostdev devices with network
-capabilities can optionally be provided one or more IP addresses to set on the
-network device in the guest. Note that some hypervisors or network device types
-will simply ignore them or only use the first one. The ``family`` attribute can
-be set to either ``ipv4`` or ``ipv6``, and the ``address`` attribute contains
-the IP address. The optional ``prefix`` is the number of 1 bits in the netmask,
-and will be automatically set if not specified - for IPv4 the default prefix is
-determined according to the network "class" (A, B, or C - see RFC870), and for
-IPv6 the default prefix is 64. The optional ``peer`` attribute holds the IP
-address of the other end of a point-to-point network device :since:`(since
-2.1.0)` .
-
-:since:`Since 1.2.12` route elements can also be added to define IP routes to
-add in the guest. The attributes of this element are described in the
-documentation for the ``route`` element in `network
-definitions <formatnetwork.html#elementsStaticroute>`__. This is used by the LXC
-driver.
-
-::
-
-   ...
-   <devices>
-     <interface type='ethernet'>
-       <source/>
-         <ip address='192.168.123.1' prefix='24'/>
-         <ip address='10.0.0.10' prefix='24' peer='192.168.122.5'/>
-         <route family='ipv4' address='192.168.42.0' prefix='24' gateway='192.168.123.4'/>
-       <source/>
-       ...
-     </interface>
-     ...
-   </devices>
-   ...
-
-:since:`Since 2.1.0` network devices of type "ethernet" can optionally be
-provided one or more IP addresses and one or more routes to set on the **host**
-side of the network device. These are configured as subelements of the
-``<source>`` element of the interface, and have the same attributes as the
-similarly named elements used to configure the guest side of the interface
-(described above).
-
-:anchor:`<a id="elementVhostuser"/>`
-
-vhost-user interface
-^^^^^^^^^^^^^^^^^^^^
-
-:since:`Since 1.2.7` the vhost-user enables the communication between a QEMU
-virtual machine and other userspace process using the Virtio transport protocol.
-A char dev (e.g. Unix socket) is used for the control plane, while the data
-plane is based on shared memory.
-
-::
-
-   ...
-   <devices>
-     <interface type='vhostuser'>
-       <mac address='52:54:00:3b:83:1a'/>
-       <source type='unix' path='/tmp/vhost1.sock' mode='server'/>
-       <model type='virtio'/>
-     </interface>
-     <interface type='vhostuser'>
-       <mac address='52:54:00:3b:83:1b'/>
-       <source type='unix' path='/tmp/vhost2.sock' mode='client'>
-         <reconnect enabled='yes' timeout='10'/>
-       </source>
-       <model type='virtio'/>
-       <driver queues='5'/>
-     </interface>
-   </devices>
-   ...
-
-The ``<source>`` element has to be specified along with the type of char device.
-Currently, only type='unix' is supported, where the path (the directory path of
-the socket) and mode attributes are required. Both ``mode='server'`` and
-``mode='client'`` are supported. vhost-user requires the virtio model type, thus
-the ``<model>`` element is mandatory. :since:`Since 4.1.0` the element has an
-optional child element ``reconnect`` which configures reconnect timeout if the
-connection is lost. It has two attributes ``enabled`` (which accepts ``yes`` and
-``no``) and ``timeout`` which specifies the amount of seconds after which
-hypervisor tries to reconnect.
-
-:anchor:`<a id="elementNwfilter"/>`
-
-Traffic filtering with NWFilter
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-:since:`Since 0.8.0` an ``nwfilter`` profile can be assigned to a domain
-interface, which allows configuring traffic filter rules for the virtual
-machine. See the `nwfilter <formatnwfilter.html>`__ documentation for more
-complete details.
-
-::
-
-   ...
-   <devices>
-     <interface ...>
-       ...
-       <filterref filter='clean-traffic'/>
-     </interface>
-     <interface ...>
-       ...
-       <filterref filter='myfilter'>
-         <parameter name='IP' value='104.207.129.11'/>
-         <parameter name='IP6_ADDR' value='2001:19f0:300:2102::'/>
-         <parameter name='IP6_MASK' value='64'/>
-         ...
-       </filterref>
-     </interface>
-   </devices>
-   ...
-
-The ``filter`` attribute specifies the name of the nwfilter to use. Optional
-``<parameter>`` elements may be specified for passing additional info to the
-nwfilter via the ``name`` and ``value`` attributes. See the
-`nwfilter <formatnwfilter.html#nwfconceptsvars>`__ docs for info on parameters.
+.. include:: formatdomain-devices-interface.rst

 :anchor:`<a id="elementsInput"/>`

diff --git a/docs/meson.build b/docs/meson.build
index c5600ba4d1..9846b3e7df 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -133,6 +133,7 @@ docs_rst_files = [
                   'formatdomain-devices-hostdev.rst',
                   'formatdomain-devices-redirdev.rst',
                   'formatdomain-devices-smartcard.rst',
+                  'formatdomain-devices-interface.rst',
                 ]
   },
   { 'name': 'hacking' },
-- 
2.26.2




More information about the libvir-list mailing list