From nobody Mon Feb 9 01:49:07 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) client-ip=205.139.110.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1595510665; cv=none; d=zohomail.com; s=zohoarc; b=O6kam7adliPyh2xWu3UbqSIeDQFxJcDMEZJp+w7luFTBpxebX9gY89SS43sSoNBmssvamwEXsgkciR7Hastr+a0qMVgFQp7fvO8rItZ+Ht4lxa4/vFTniJPqrj51FxrDZm801IdL3vrE2xeCqKWSWyOe6uCt4XIpt2BvjbGoBd0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1595510665; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=qPwQIMRyIgg9GceK+NXMLKQxSt48J2gTtwHTMK9hQmU=; b=i2S+kxdJbk3YJzI9NXfJj0evfbvnBZ4VAWTQ6yV1h9zx5M4jSb5T4BCuczRls0e5zhlesNHnirOqMich/s3Sri7BfFIR3HiDU2Pq6IMPQ0vOuvWnS90azRntjCLXJmPMBq/y2lVU1Ft0H6I3Z2VwspGusDeAhyOKA4cEnBkgT98= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [205.139.110.120]) by mx.zohomail.com with SMTPS id 1595510665706585.0456393622446; Thu, 23 Jul 2020 06:24:25 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-43-GR8SKlmjOeOzXyc7rhJ31Q-1; Thu, 23 Jul 2020 09:22:28 -0400 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 998D3803324; Thu, 23 Jul 2020 13:22:22 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 7BE9C72683; Thu, 23 Jul 2020 13:22:22 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 4B297180530A; Thu, 23 Jul 2020 13:22:22 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 06NDMJj8028595 for ; Thu, 23 Jul 2020 09:22:19 -0400 Received: by smtp.corp.redhat.com (Postfix) id 09B2119D7C; Thu, 23 Jul 2020 13:22:19 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.37]) by smtp.corp.redhat.com (Postfix) with ESMTP id A04B32E162 for ; Thu, 23 Jul 2020 13:22:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1595510664; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=qPwQIMRyIgg9GceK+NXMLKQxSt48J2gTtwHTMK9hQmU=; b=EDbur/2H2n5/d3yGuIB/VlrhdpsPGV1ak8kImgBQ5KyA/1TDRldpgmfXm8yekpy/5OFAus 4sS7F9O1Dd05NvPc7TtOQNJ+AHCVxPgf31ew1+wT4dADNctMTcAUdVX+rfFSKxs4jYyvnh kjPG9dx9wuq49ZdrGz5YoGeTD4kEZlo= X-MC-Unique: GR8SKlmjOeOzXyc7rhJ31Q-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 16/32] docs: formatdomain-devices: Split out Date: Thu, 23 Jul 2020 15:21:21 +0200 Message-Id: <611547f345ab3659abd2743aaae6f8d652185192.1595510131.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa --- 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-de= vices-interface.rst new file mode 100644 index 0000000000..c828e71df1 --- /dev/null +++ b/docs/formatdomain-devices-interface.rst @@ -0,0 +1,1258 @@ +:anchor:`` + +Network interfaces +~~~~~~~~~~~~~~~~~~ + +:: + + ... + + + + + + + + + ... + +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 f= or 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 - curre= ntly +it is only supported for the virtio device model and for macvtap connectio= ns on +the host. + +Each ```` element has an optional ``
`` sub-element tha= t can +tie the interface to a particular pci slot, with attribute ``type=3D'pci'`= ` as +`documented above <#elementsAddress>`__. + +:since:`Since 6.6.0` , one can force libvirt to keep the provided MAC addr= ess +when it's in the reserved VMware range by adding a ``type=3D"static"`` att= ribute +to the ```` element. Note that this attribute is useless if the prov= ided +MAC address is outside of the reserved VMWare ranges. + +:anchor:`` + +Virtual network +^^^^^^^^^^^^^^^ + +**This is the recommended config for general guest connectivity on hosts w= ith +dynamic / wireless networking configs (or multi-host environments where th= e host +hardware details are described separately in a ```` 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" configuratio= n, the +network may be totally isolated (no ```` element given), NAT'ing = to an +explicit network device or to the default route (```= `), +routed with no NAT (````), or connected directly = to one +of the host's network interfaces (via macvtap) or bridge devices +((```` :since:`Si= nce +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 s= etup +outside the scope of libvirt. In the case of isolated, nat, and routed net= works, +DHCP and DNS are provided on the virtual network by libvirt, and the IP ra= nge +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 over= ridden +with the element (see `overriding the target +element <#elementsNICSTargetOverride>`__). + +When the source of an interface is a network, a ``portgroup`` can be speci= fied +along with the name of the network; one network may have multiple portgrou= ps +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 virNetworkPo= rtPtr +object that records the association between the domain interface and the +network. This attribute is read-only since port objects are create and del= eted +automatically during startup and shutdown. :since:`Since 5.1.0` + +Also, similar to ``direct`` network connections (described below), a conne= ction +of type ``network`` may specify a ``virtualport`` element, with configurat= ion +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:`Sin= ce +0.9.11` ). + +Since the actual type of switch may vary depending on the configuration in= the +```` on the host, it is acceptable to omit the virtualport ``type= `` +attribute, and specify attributes from multiple different virtualport type= s (and +also to leave out certain attributes); at domain startup time, a complete +```` element will be constructed by merging together the type= and +attributes defined in the network and the portgroup referenced by the inte= rface. +The newly-constructed virtualport is a combination of them. The attributes= from +lower virtualport can't make change on the ones defined in higher virtualp= ort. +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 t= ype, +but both a ``profileid`` (in case the switch is 802.1Qbh) and an ``interfa= ceid`` +(in case the switch is Open vSwitch) (you may also omit the other attribut= es, +such as managerid, typeid, or profileid, to be filled in from the network's +````). If you want to limit a guest to connecting only to cer= tain +types of switches, you can specify the virtualport type, but still omit so= me/all +of the parameters - in this case if the host's network has a different typ= e of +virtualport, connection of the interface will fail. + +:: + + ... + + + + + ... + + + + + + + + + + ... + +:anchor:`` + +Bridge to LAN +^^^^^^^^^^^^^ + +**This is the recommended config for general guest connectivity on hosts w= ith +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 n= ame of +vnetN, which can also be overridden with the element (see `overri= ding +the target element <#elementsNICSTargetOverride>`__). The tun device will = be +attached to the bridge. The IP range / network configuration is whatever i= s 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 brid= ge. On +hosts that support Open vSwitch, it is also possible to connect to an Open +vSwitch bridge device by adding a ```` = to the +interface definition. ( :since:`Since 0.9.11` ). The Open vSwitch type +virtualport accepts two parameters in its ```` 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". + +:: + + ... + + ... + + + + + + + + + + + + + + + ... + + ... + +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 d= evice +by adding a ```` to the interface definitio= n. ( +:since:`Since 1.2.13` ). The Midonet virtualport type requires an +``interfaceid`` attribute in its ```` element. This interface = id is +the UUID that specifies which port in the virtual network topology will be= bound +to the interface. + +:: + + ... + + ... + + + + + + + + + + + + + + + ... + + ... + +:anchor:`` + +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 possibl= e to +override the default network address by including an ``ip`` element specif= ying +an IPv4 address in its one mandatory attribute, ``address``. Optionally, a +second ``ip`` element with a ``family`` attribute set to "ipv6" can be spe= cified +to add an IPv6 address to the interface. ``address``. Optionally, address +``prefix`` can be specified. + +:: + + ... + + + ... + + + + + + + ... + +:anchor:`` + +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 ```` element. If no target dev is specified, libv= irt +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 exa= ct dev +name given. If the specified target dev does exist, then that existing dev= ice +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`` i= s a +pre-existing device, and the ``managed`` attribute of the ``target`` eleme= nt 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=3D'no' with a pre-created= tap +device is useful because it permits a virtual machine managed by an unpriv= ileged +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 ``