From nobody Mon Feb 9 01:51:18 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 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=1649865794; cv=none; d=zohomail.com; s=zohoarc; b=io2ZGQMGJeBamf+uPqcrdnKOhwRC6zo1Q+3bmKfLUAWTmOvEy/BmPcItm0kmlKrGhxooTlsuYHcpmSZds/Qhwkc3gBqqFljY5kAZIKV74Fjrbt2/M4WiGUhKjn/gYIyJvD//gr24h09pI6FRoXXCZe24mL+x5wrHuxnnbd//0AU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1649865794; 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=IrTjkX6CWJ9QCdu58HmEnB9n4iDjSNAj8zIzm0zjiRo=; b=TsEP1A586oXNGg1+nWjhf6JnLtNui0rIbYNhfQPcfxidhyiVui+Gg5elo/vW3/8GAtnY3Tq0QSLrCvMY9Sw/DVQ53TXCu+Ow7rKHiECJt3ZxrQJSgrMTeubUpWrPiD5Fz5Z6iK+gickAvh19TGnDn0NPEyEJa1f3K5/GwBpZ1bQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1649865794266870.9638103823384; Wed, 13 Apr 2022 09:03:14 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-124-XwdsOGj3MAKPCMECrbpgxA-1; Wed, 13 Apr 2022 12:03:09 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id D0CC638008CB; Wed, 13 Apr 2022 16:02:32 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id AFFD740D0160; Wed, 13 Apr 2022 16:02:32 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 858161940373; Wed, 13 Apr 2022 16:02:32 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 25E701940340 for ; Wed, 13 Apr 2022 16:02:31 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 1BD22145BA5B; Wed, 13 Apr 2022 16:02:31 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0D657141511C for ; Wed, 13 Apr 2022 16:02:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1649865792; 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=IrTjkX6CWJ9QCdu58HmEnB9n4iDjSNAj8zIzm0zjiRo=; b=XBFnmrPzDxxnAxevVlRFvmyuV7edkiL5UoUU92HUaWstyfDa4MSGsbxtXZd3WDLWzbwbQt lYRaqEzGoCSDk6czIaudVCIiszMK1gIm4OADzSGacpsI21SbDmqe2ka0vAhUy5ra0iNdaj Z4U3v+Lg3geqltu067MNfeGlfMUnO60= X-MC-Unique: XwdsOGj3MAKPCMECrbpgxA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 13/14] docs: Convert 'formatnetwork' page to rst Date: Wed, 13 Apr 2022 18:02:14 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.1 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) X-ZM-MESSAGEID: 1649865795768100005 Content-Type: text/plain; charset="utf-8"; x-default="true" Additionally hyperlinks in other parts of the documentation are updated to match. Signed-off-by: Peter Krempa --- docs/formatdomain.rst | 4 +- docs/formatnetwork.html.in | 1479 ------------------------------------ docs/formatnetwork.rst | 1144 ++++++++++++++++++++++++++++ docs/formatnetworkport.rst | 2 +- docs/manpages/virsh.rst | 5 +- docs/meson.build | 2 +- 6 files changed, 1151 insertions(+), 1485 deletions(-) delete mode 100644 docs/formatnetwork.html.in create mode 100644 docs/formatnetwork.rst diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 552b5364f8..6c4096713a 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5542,7 +5542,7 @@ Quality of service This part of interface XML provides setting quality of service. Incoming a= nd outgoing traffic can be shaped independently. The ``bandwidth`` element an= d its -child elements are described in the `QoS `__ +child elements are described in the `QoS `__ section of the Network XML. :anchor:`` @@ -5746,7 +5746,7 @@ address of the other end of a point-to-point network = device :since:`(since :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 `__. This is used by t= he LXC +definitions `__. This is used by the LXC driver. :: diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in deleted file mode 100644 index 56ff32fbf4..0000000000 --- a/docs/formatnetwork.html.in +++ /dev/null @@ -1,1479 +0,0 @@ - - - - -

Network XML format

- -
    -
- -

- This page provides an introduction to the network XML format. For - background information on the concepts referred to here, consult the - relevant wiki p= age. -

- -

Element and attribute overview

- -

- The root element required for all virtual networks is - named network and has no configurable attributes - (although since 0.10.0 there is one - optional read-only attribute - when examining the live - configuration of a network, the - attribute connections, if present, specifies the - number of guest interfaces currently connected via this - network). The network XML format is - available since 0.3.0 -

- -

General metadata

- -

- The first elements provide basic metadata about the virtual - network. -

- - 
-<network ipv6=3D'yes' trustGuestRxFilters=3D'no'>
-  <name>default</name>
-  <uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
-  <metadata>
-    <app1:foo xmlns:app1=3D"http://app1.org/app1/">..</app1:foo&g=
t;
-    <app2:bar xmlns:app2=3D"http://app1.org/app2/">..</app2:bar&g=
t;
-  </metadata>
-  ...
- -
-
name
-
The content of the name element provides - a short name for the virtual network. This name should - consist only of alphanumeric characters and is required - to be unique within the scope of a single host. It is - used to form the filename for storing the persistent - configuration file. Since 0.3.0
-
uuid
-
The content of the uuid element provides - a globally unique identifier for the virtual network. - The format must be RFC 4122 compliant, eg 3e3fce45-4f53-4fa7= -bb32-11f34168b82b. - If omitted when defining/creating a new network, a random - UUID is generated. Since 0.3.0
-
The metadata node can be used by applications to - store custom metadata in the form of XML nodes/trees. Applications - must use custom namespaces on their XML nodes/trees, with only - one top-level element per namespace (if the application needs - structure, they should have sub-elements to their namespace - element). Since 2.1.0
-
ipv6
-
When set to yes, the optional parameter - ipv6 enables - a network definition with no IPv6 gateway addresses specified - to have guest-to-guest communications. For further information, - see the example below for the example with no gateway addresses. - Since 1.0.1
-
trustGuestRxFilters
-
The optional parameter trustGuestRxFilters can - be used to set that attribute of the same name for each domain - interface connected to this network (since - 1.2.10). See - the Network - interfaces section of the domain XML documentation for - more details. Note that an explicit setting of this attribute - in a portgroup or the individual domain interface will - override the setting in the network.
-
- -

Connectivity

- -

- The next set of elements control how a virtual network is - provided connectivity to the physical LAN (if at all). -

- - 
-...
-<bridge name=3D"virbr0" stp=3D"on" delay=3D"5" macTableManager=3D"libvi=
rt"/>
-<mtu size=3D"9000"/>
-<domain name=3D"example.com" localOnly=3D"no"/>
-<forward mode=3D"nat" dev=3D"eth0"/>
-...
- -
-
bridge
-
The name attribute on the bridge eleme= nt - defines the name of a bridge device which will be used to construct - the virtual network. The virtual machines will be connected to this - bridge device allowing them to talk to each other. The bridge devi= ce - may also be connected to the LAN. When defining - a new network with a <forward> mode of - - "nat", "route", or "open" (or an isolated network with - no <forward> element), libvirt will - automatically generate a unique name for the bridge device if - none is given, and this name will be permanently stored in the - network configuration so that that the same name will be used - every time the network is started. For these types of networks - (nat, route, open, and isolated), a bridge name beginning with the - prefix "virbr" is recommended (and that is what is - auto-generated), but not enforced. - Attribute stp specifies if Spanning Tree Protocol - is 'on' or 'off' (default is - 'on'). Attribute delay sets the bridge's forward - delay value in seconds (default is 0). - Since 0.3.0 - -

- The macTableManager attribute of the bridge - element is used to tell libvirt how the bridge's MAC address - table (used to determine the correct egress port for packets - based on destination MAC address) will be managed. In the - default kernel setting, the kernel - automatically adds and removes entries, typically using - learning, flooding, and promiscuous mode on the bridge's - ports in order to determine the proper egress port for - packets. When macTableManager is set - to libvirt, libvirt disables kernel management - of the MAC table (in the case of the Linux host bridge, this - means enabling vlan_filtering on the bridge, and disabling - learning and unicast_filter for all bridge ports), and - explicitly adds/removes entries to the table according to - the MAC addresses in the domain interface configurations. - Allowing libvirt to manage the MAC table can improve - performance - with a Linux host bridge, for example, turning - off learning and unicast_flood on ports has its own - performance advantage, and can also lead to an additional - boost by permitting the kernel to automatically turn off - promiscuous mode on some ports of the bridge (in particular, - the port attaching the bridge to the physical - network). However, it can also cause some networking setups - to stop working (e.g. vlan tagging, multicast, - guest-initiated changes to MAC address) and is not supported - by older kernels. - Since 1.2.11, requires kernel 3.17 or - newer -

- -

- The optional zone attribute of - the bridge element is used to specify - the firewalld - zone for the bridge of a network with forward - mode of "nat", "route", "open", or one with - no forward specified. By default, the bridges - of all virtual networks with these forward modes are placed - in the firewalld zone named "libvirt", which permits - incoming DNS, DHCP, TFTP, and SSH to the host from guests on - the network. This behavior can be changed either by - modifying the libvirt zone (using firewalld management - tools), or by placing the network in a different zone (which - will also be managed using firewalld tools). - Since 5.1.0 -

-
- -
mtu
-
- The size attribute of the mtu> - element specifies the Maximum Transmission Unit (MTU) for the - network. Since 3.1.0. In the case - of a libvirt-managed network (one with forward mode - of nat, route, open, or - no forward element (i.e. an isolated network), - this will be the MTU assigned to the bridge device when - libvirt creates it, and thereafter also assigned to all tap - devices created to connect guest interfaces. Network types not - specifically mentioned here don't support having an MTU set in - the libvirt network config. If mtu size is unspecified, the - default setting for the type of device being used is assumed - (usually 1500). -
- -
domain
-
- The name attribute on the domain - element defines the DNS domain of the DHCP server. This - element is optional, and is only used for those networks with - a <forward> mode of "nat" or "route" (or an - isolated network with no <forward> - element). Since 0.4.5 - -

- If the optional localOnly attribute on the - domain element is "yes", then DNS requests under - this domain will only be resolved by the virtual network's own - DNS server - they will not be forwarded to the host's upstream - DNS server. If localOnly is "no", and by - default, unresolved requests will be forwarded. - Since 1.2.12 -

-
-
forward
-
Inclusion of the forward element indicates that - the virtual network is to be connected to the physical - LAN.Since 0.3.0. - The mode attribute determines the method of - forwarding. If there is no forward element, the - network will be isolated from any other network (unless a - guest connected to that network is acting as a router, of - course). The following are valid settings - for mode (if there is a forward - element but mode is not specified, mode=3D'nat' is - assumed): -
-
nat
-
- All traffic between guests connected to this network and - the physical network will be forwarded to the physical - network via the host's IP routing stack, after the guest's - IP address is translated to appear as the host machine's - public IP address (a.k.a. Network Address Translation, or - "NAT"). This allows multiple guests, all having access to - the physical network, on a host that is only allowed a - single public IP address. If a network has any IPv6 - addresses defined, the IPv6 traffic will be forwarded - using plain routing, since IPv6 has no concept of NAT. - Firewall rules will allow outbound connections to any - other network device whether ethernet, wireless, dialup, - or VPN. If the dev attribute is set, the - firewall rules will restrict forwarding to the named - device only. Inbound connections from other networks are - all prohibited; all connections between guests on the same - network, and to/from the host to the guests, are - unrestricted and not NATed.Since - 0.4.2 - -

Since 1.0.3 it is possible to - specify a public IPv4 address and port range to be used for - the NAT by using the <nat> subelement. - Note that all addresses from the range are used, not just those - that are in use on the host. - The address range is set with the <address> - subelements and start and stop - attributes: -

- 
-...
-  <forward mode=3D'nat'>
-    <nat>
-      <address start=3D'1.2.3.4' end=3D'1.2.3.10'/>
-    </nat>
-  </forward>
-...
-

- A single IPv4 address can be set by setting - start and end attributes to - the same value. -

-

- The port range to be used for the <nat> can - be set via the subelement <port>: -

- 
-...
-  <forward mode=3D'nat'>
-    <nat>
-      <port start=3D'500' end=3D'1000'/>
-    </nat>
-  </forward>
-...
- -

- Since 6.5.0 it is possible to - enable NAT with IPv6 networking. As noted above, IPv6 - has historically done plain forwarding and thus to avoid - breaking historical compatibility, IPv6 NAT must be - explicitly requested. -

- 
-...
-  <forward mode=3D'nat'>
-    <nat ipv6=3D'yes'/>
-  </forward>
-...
-
- -
route
-
- Guest network traffic will be forwarded to the physical - network via the host's IP routing stack, but without - having NAT applied. Again, if the dev - attribute is set, firewall rules will restrict forwarding - to the named device only. This presumes that the local LAN - router has suitable routing table entries to return - traffic to this host. All incoming and outgoing sessions - to guest on these networks are unrestricted. (To restrict - incoming traffic to a guest on a routed network, you can - configure nwfilter rules - on the guest's interfaces.) - Since 0.4.2 -
- -
open
-
- As with mode=3D'route', guest network traffic will be - forwarded to the physical network via the host's IP - routing stack, but there will be no firewall rules added - to either enable or prevent any of this traffic. When - forward=3D'open' is set, the dev attribute - cannot be set (because the forward dev is enforced with - firewall rules, and the purpose of forward=3D'open' is to - have a forwarding mode where libvirt doesn't add any - firewall rules). This mode presumes that the local LAN - router has suitable routing table entries to return - traffic to this host, and that some other management - system has been used to put in place any necessary - firewall rules. Although no firewall rules will be added - for the network, it is of course still possible to add - restrictions for specific guests using - nwfilter rules on the - guests' interfaces.) - Since 2.2.0 -
- -
bridge
-
- This network describes either 1) an existing host bridge - that was configured outside of libvirt (if - a <bridge name=3D'xyz'/> element has been - specified, Since 0.9.4), 2) an - existing Open vSwitch bridge that was configured outside of - libvirt (if both a <bridge name=3D'xyz'/> - element and a <virtualport - type=3D'openvswitch'/> have been - specified Since 0.10.0) 3) an - interface or group of interfaces to be used for a "direct" - connection via macvtap using macvtap's "bridge" mode (if - the forward element has one or - more <interface> - subelements, Since 0.9.4) - (see Direct - attachment to physical interface for descriptions of - the various macvtap modes). libvirt doesn't attempt to - manage the bridge interface at all, thus - the <bridge> element's stp - and delay attributes are not allowed; no - iptables rules, IP addresses, or DHCP/DNS services are - added; at the IP level, the guest interface appears to be - directly connected to the physical - interface.Since 0.9.4 -
-
private
-
- This network uses a macvtap "direct" connection in - "private" mode to connect each guest to the network. The - physical interface to be used will be picked from among - those listed in <interface> subelements - of the <forward> element; when using - 802.1Qbh mode (as indicated by - the <virtualport> type attribute - note - that this requires an 802.1Qbh-capable hardware switch), - each physical interface can only be in use by a single - guest interface at a time; in modes other than 802.1Qbh, - multiple guest interfaces can share each physical - interface (libvirt will attempt to balance usage between - all available interfaces).Since - 0.9.4 -
-
vepa
-
- This network uses a macvtap "direct" connection in "vepa" - mode to connect each guest to the network (this requires - that the physical interfaces used be connected to a - vepa-capable hardware switch. The physical interface to be - used will be picked from among those listed - in <interface> subelements of - the <forward> element; multiple guest - interfaces can share each physical interface (libvirt will - attempt to balance usage between all available - interfaces).Since 0.9.4 -
-
passthrough
-
- This network uses a macvtap "direct" connection in - "passthrough" mode to connect each guest to the network - (note that this is not the same thing as "PCI - passthrough"). The physical interface to be used will be - picked from among those listed - in <interface> subelements of - the <forward> element. Each physical - interface can only be in use by a single guest interface - at a time, so libvirt will keep track of which interfaces - are currently in use, and only assign unused interfaces - (if there are no available physical interfaces when a - domain interface is being attached, an error will be - logged, and the operation causing the attach will fail - (usually either a domain start, or a hotplug interface - attach to a domain).Since 0.9.4 -
-
hostdev
-
- This network facilitates PCI Passthrough of a network - device. A network device is chosen from the interface - pool and directly assigned to the guest using generic - device passthrough, after first optionally setting the - device's MAC address and vlan tag to the configured value, - and optionally associating the device with an 802.1Qbh - capable switch using a <virtualport> - element. 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. Since 0.10.0 - -

- To force use of a particular type of device assignment, - a <forward type=3D'hostdev'> interface can have an - optional driver sub-element with - a name attribute set to either "vfio" (VFIO - is a new method of device assignment that is compatible - with UEFI Secure Boot) or "kvm" (the legacy device - assignment handled directly by the KVM kernel module) - Since 1.0.5 (QEMU and KVM only, - requires kernel 3.6 or newer). When specified, - device assignment will fail if the requested method of - device assignment isn't available on the host. When not - specified, the default is "vfio" on systems where the - VFIO driver is available and loaded, and "kvm" on older - systems, or those where the VFIO driver hasn't been - loaded Since 1.1.3 (prior to - that the default was always "kvm"). -

- -

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, vlan tag, 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.10.0, you - should use a standard - <hostdev> device definition in the - domain's configuration to assign the device to the guest - instead of defining an <interface - type=3D'network'> pointing to a network - with <forward mode=3D'hostdev'/>. -

-
-
- As mentioned above, a <forward> element can - have multiple <interface> subelements, each - one giving the name of a physical interface that can be used - for this network Since 0.9.4: - 
-...
-  <forward mode=3D'passthrough'>
-    <interface dev=3D'eth10'/>
-    <interface dev=3D'eth11'/>
-    <interface dev=3D'eth12'/>
-    <interface dev=3D'eth13'/>
-    <interface dev=3D'eth14'/>
-  </forward>
-...
-
-

- since 0.10.0, - <interface> also has an optional read-only - attribute - when examining the live configuration of a - network, the attribute connections, if present, - specifies the number of guest interfaces currently connected - via this physical interface. -

-

- Additionally, since 0.9.10, libvirt - allows a shorthand for specifying all virtual interfaces - associated with a single physical function, by using - the <pf> subelement to call out the - corresponding physical interface associated with multiple - virtual interfaces: -

- 
-...
-  <forward mode=3D'passthrough'>
-    <pf dev=3D'eth0'/>
-  </forward>
-...
-
- -

When a guest interface is being constructed, libvirt will pick - an interface from this list to use for the connection. In - modes where physical interfaces can be shared by multiple - guest interfaces, libvirt will choose the interface that - currently has the least number of connections. For those modes - that do not allow sharing of the physical device (in - particular, 'passthrough' mode, and 'private' mode when using - 802.1Qbh), libvirt will choose an unused physical interface - or, if it can't find an unused interface, fail the operation.

- -

- since 0.10.0 When using forward - mode 'hostdev', the interface pool is specified with a list - of <address> elements, each of which has - <type> (must always be 'pci'), - <domain>, <bus>, - <slot>and <function> - attributes. -

- 
-...
-  <forward mode=3D'hostdev' managed=3D'yes'>
-    <driver name=3D'vfio'/>
-    <address type=3D'pci' domain=3D'0' bus=3D'4' slot=3D'0' function=3D=
'1'/>
-    <address type=3D'pci' domain=3D'0' bus=3D'4' slot=3D'0' function=3D=
'2'/>
-    <address type=3D'pci' domain=3D'0' bus=3D'4' slot=3D'0' function=3D=
'3'/>
-  </forward>
-...
-
- - Alternatively the interface pool can also be defined using a - single physical function <pf> subelement to - call out the corresponding physical interface associated with - multiple virtual interfaces (similar to passthrough mode): - - 
-...
-  <forward mode=3D'hostdev' managed=3D'yes'>
-    <pf dev=3D'eth0'/>
-  </forward>
-...
-
- -
-
-
Quality of service
- -
-...
-  <forward mode=3D'nat' dev=3D'eth0'/>
-  <bandwidth>
-    <inbound average=3D'1000' peak=3D'5000' burst=3D'5120'/>
-    <outbound average=3D'128' peak=3D'256' burst=3D'256'/>
-  </bandwidth>
-...
- -

- The <bandwidth> element allows setting - quality of service for a particular network - (since 0.9.4). Setting - bandwidth for a network is supported only - for networks with a <forward> mode - of route, nat, bridge, - or no mode at all (i.e. an "isolated" network). Setting - bandwidth is not supported for forward modes - passthrough, private, - or hostdev. Attempts to do this will lead to - a failure to define the network or to create a transient network. -

-

- The <bandwidth> element can only be a - subelement of a domain's <interface>, a - subelement of a <network>, or a subelement of - a <portgroup> in a <network>. -

-

- As a subelement of a domain's <interface>, - the bandwidth only applies to that one interface of the domain. - As a subelement of a <network>, the bandwidth - is a total aggregate bandwidth to/from all guest interfaces attach= ed - to that network, not to each guest interface individually. - If a domain's <interface> has - <bandwidth> element values higher - than the aggregate for the entire network, then the aggregate - bandwidth for the <network> takes precedence. - This is because the two choke points are independent of each other - where the domain's <interface> bandwidth control - is applied on the interface's tap device, while the - <network> bandwidth control is applied on the - interface part of the bridge device created for that network. -

-

- As a subelement of a - <portgroup> in a <network>, - if a domain's <interface> has a - portgroup attribute in its - <source> element and if the - <interface> - itself has no <bandwidth> element, then the - <bandwidth> element of the portgroup will be - applied individually to each guest interface defined to be a - member of that portgroup. Any <bandwidth> - element in the domain's <interface> definition - will override the setting in the portgroup - (since 1.0.1). -

-

- Incoming and outgoing traffic can be shaped independently. The - bandwidth element can have at most one - inbound and at most one outbound - child element. Leaving either of these children elements out - results in no QoS applied for that traffic direction. So, - when you want to shape only incoming traffic, use - inbound only, and vice versa. Each of these - elements have one mandatory attribute - average (or - floor as described below). The attributes are as foll= ows, - where accepted values for each attribute is an integer number. -

-
-
average
-
- Specifies the desired average bit rate for the interface - being shaped (in kilobytes/second). -
-
peak
-
- Optional attribute which specifies the maximum rate at - which the bridge can send data (in kilobytes/second). - Note the limitation of implementation: this attribute in the - outbound element is ignored (as Linux ingress - filters don't know it yet). -
-
burst
-
- Optional attribute which specifies the amount of kibibytes that - can be transmitted in a single burst at peak speed. -
-
floor
-
- Optional attribute available only for the inbound - element. This attribute guarantees minimal throughput for - shaped interfaces. This, however, requires that all traffic - goes through one point where QoS decisions can take place, hence - why this attribute works only for virtual networks for now - (that is <interface type=3D'network'/> with a - forward type of route, nat, open or no forward at all). Moreover= , the - virtual network the interface is connected to is required to have - at least inbound QoS set (average at least). If - using the floor attribute users don't need to speci= fy - average. However, peak and - burst attributes still require average. - Currently, the Linux kernel doesn't allow ingress qdiscs to have - any classes therefore floor can be applied only - on inbound and not outbound. -
-
- -

- Attributes average, peak, and - burst are available - since 0.9.4, while the - floor attribute is available - since 1.0.1. -

- -
Setting VLAN tag (on supported network ty= pes only)
- -
-<network>
-  <name>ovs-net</name>
-  <forward mode=3D'bridge'/>
-  <bridge name=3D'ovsbr0'/>
-  <virtualport type=3D'openvswitch'>
-    <parameters interfaceid=3D'09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/&g=
t;
-  </virtualport>
-  <vlan trunk=3D'yes'>
-    <tag id=3D'42' nativeMode=3D'untagged'/>
-    <tag id=3D'47'/>
-  </vlan>
-  <portgroup name=3D'dontpanic'>
-    <vlan>
-      <tag id=3D'42'/>
-    </vlan>
-  </portgroup>
-</network>
-
- -

- 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 0.10.0. Network - connections that support guest-transparent VLAN tagging include - 1) type=3D'bridge' interfaces connected to an Open vSwitch bridge - Since 0.10.0, 2) SRIOV Virtual - Functions (VF) used via type=3D'hostdev' (direct device - assignment) Since 0.10.0, and 3) - SRIOV VFs used via type=3D'direct' with mode=3D'passthrough' - (macvtap "passthru" mode) 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=3D'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=3D'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 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. -

-

- <vlan> elements can also be specified in - a <portgroup> element, as well as directly in - a domain's <interface> element. In the case - that a vlan tag is specified in multiple locations, the setting - in <interface> takes precedence, followed by - the setting in the <portgroup> selected by - the interface config. The <vlan> - in <network> will be selected only if none is - given in <portgroup> - or <interface>. -

- -
Isolating ports from one another
- -
-<network>
-  <name>isolated-ports</name>
-  <forward mode=3D'bridge'/>
-  <bridge name=3D'br0'/>
-  <port isolated=3D'yes'/>
-</network>
-
- -

- Since 6.1.0. The port - element property isolated, when set - to yes (default setting is no) is used - to isolate the network traffic of each guest on the network from - all other guests connected to the network; it does not have an - effect on communication between the guests and the host, or - between the guests and destinations beyond this network. This - setting is only supported for networks that use a Linux host - bridge to connect guest interfaces via a standard tap device - (i.e. those with a forward mode of nat, route, open, bridge, or - no forward mode). -

- -
Portgroups
- -
-...
-  <forward mode=3D'private'/>
-    <interface dev=3D"eth20"/>
-    <interface dev=3D"eth21"/>
-    <interface dev=3D"eth22"/>
-    <interface dev=3D"eth23"/>
-    <interface dev=3D"eth24"/>
-  </forward>
-  <portgroup name=3D'engineering' default=3D'yes'>
-    <virtualport type=3D'802.1Qbh'>
-      <parameters profileid=3D'test'/>
-    </virtualport>
-    <bandwidth>
-      <inbound average=3D'1000' peak=3D'5000' burst=3D'5120'/>
-      <outbound average=3D'1000' peak=3D'5000' burst=3D'5120'/>
-    </bandwidth>
-  </portgroup>
-  <portgroup name=3D'sales' trustGuestRxFilters=3D'no'>
-    <virtualport type=3D'802.1Qbh'>
-      <parameters profileid=3D'salestest'/>
-    </virtualport>
-    <bandwidth>
-      <inbound average=3D'500' peak=3D'2000' burst=3D'2560'/>
-      <outbound average=3D'128' peak=3D'256' burst=3D'256'/>
-    </bandwidth>
-  </portgroup>
-...
- -

- Since 0.9.4 - A portgroup provides a method of easily putting guest - connections to the network into different classes, with each - class potentially having a different level/type of service. - Since 0.9.4 Each - network can have multiple portgroup elements (and one of those - can optionally be designated as the 'default' portgroup for the - network), and each portgroup has a name, as well as various - attributes and subelements associated with it. The currently support= ed - subelements are <bandwidth> - (described here) - and <virtualport> - (documented here). - If a domain interface definition specifies a portgroup (by - adding a portgroup attribute to - the <source> subelement), that portgroup's - info will be merged into the interface's configuration. If no - portgroup is given in the interface definition, and one of the - network's portgroups has default=3D'yes', that - default portgroup will be used. If no portgroup is given in the - interface definition, and there is no default portgroup, then - none will be used. Any <bandwidth> - - specified directly in the domain XML will take precedence over - any setting in the chosen portgroup. if - a <virtualport> is specified in the portgroup - (and/or directly in the network definition), the multiple - virtualports will be merged, and any parameter that is specified - in more than one virtualport, and is not identical, will be - considered an error, and will prevent the interface from - starting. -

-

- portgroups also support the optional - parameter trustGuestRxFilters which can be used to - set that attribute of the same name for each domain interface - using this portgroup (since - 1.2.10). See - the Network - interfaces section of the domain XML documentation for more - details. Note that an explicit setting of this attribute in the - portgroup overrides the network-wide setting, and an explicit - setting in the individual domain interface will override the - setting in the portgroup. -

- -
Static Routes
-

- Static route definitions are used to provide routing information - to the virtualization host for networks which are not directly - reachable from the virtualization host, but *are* reachable from - a guest domain that is itself reachable from the - host since 1.0.6. -

- -

- As shown in this - example, it is possible to define a virtual network - interface with no IPv4 or IPv6 addresses. Such networks are - useful to provide host connectivity to networks which are only - reachable via a guest. A guest with connectivity both to the - guest-only network and to another network that is directly - reachable from the host can act as a gateway between the - networks. A static route added to the "host-visible" network - definition provides the routing information so that IP packets - can be sent from the virtualization host to guests on the hidden - network. -

- -

- Here is a fragment of a definition which shows the static - route specification as well as the IPv4 and IPv6 definitions - for network addresses which are referred to in the - gateway gateway address specifications. Note - that the third static route specification includes the - metric attribute specification with a value of 2. - This particular route would *not* be preferred if there was - another existing rout on the system with the same address and - prefix but with a lower value for the metric. If there is a - route in the host system configuration that should be overridden - by a route in a virtual network whenever the virtual network is - running, the configuration for the system-defined route should - be modified to have a higher metric, and the route on the - virtual network given a lower metric (for example, the default - metric of "1"). -

- - 
-...
-  <ip address=3D"192.168.122.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.122.128" end=3D"192.168.122.254"/>
-    </dhcp>
-  </ip>
-  <route address=3D"192.168.222.0" prefix=3D"24" gateway=3D"192.168.122=
.2"/>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:2::1" prefix=3D"64"/>
-  <route family=3D"ipv6" address=3D"2001:db8:ca2:3::" prefix=3D"64" gat=
eway=3D"2001:db8:ca2:2::2"/>
-  <route family=3D"ipv6" address=3D"2001:db9:4:1::" prefix=3D"64" gatew=
ay=3D"2001:db8:ca2:2::3" metric=3D'2'/>
-...
-
- -

Addressing

- -

- The final set of elements define the addresses (IPv4 and/or - IPv6, as well as MAC) to be assigned to the bridge device - associated with the virtual network, and optionally enable DHCP - services. These elements are only valid for isolated networks - (no forward element specified), and for those with - a forward mode of 'route' or 'nat'. -

- - 
-...
-<mac address=3D'00:16:3E:5D:C7:9E'/>
-<domain name=3D"example.com"/>
-<dns>
-  <txt name=3D"example" value=3D"example value"/>
-  <forwarder addr=3D"8.8.8.8"/>
-  <forwarder domain=3D'example.com' addr=3D"8.8.4.4"/>
-  <forwarder domain=3D'www.example.com'/>
-  <srv service=3D'name' protocol=3D'tcp' domain=3D'test-domain-name' ta=
rget=3D'.'
-    port=3D'1024' priority=3D'10' weight=3D'10'/>
-  <host ip=3D'192.168.122.2'>
-    <hostname>myhost</hostname>
-    <hostname>myhostalias</hostname>
-  </host>
-</dns>
-<ip address=3D"192.168.122.1" netmask=3D"255.255.255.0" localPtr=3D"yes=
">
-  <dhcp>
-    <range start=3D"192.168.122.100" end=3D"192.168.122.254">
-      <lease expiry=3D'1' unit=3D'hours'/>
-    </range>
-    <host mac=3D"00:16:3e:77:e2:ed" name=3D"foo.example.com" ip=3D"192.=
168.122.10">
-      <lease expiry=3D'30' unit=3D'minutes'/>
-    </host>
-    <host mac=3D"00:16:3e:3e:a9:1a" name=3D"bar.example.com" ip=3D"192.=
168.122.11"/>
-  </dhcp>
-</ip>
-<ip family=3D"ipv6" address=3D"2001:db8:ca2:2::1" prefix=3D"64" localPt=
r=3D"yes"/>
-<route family=3D"ipv6" address=3D"2001:db9:ca1:1::" prefix=3D"64" gatew=
ay=3D"2001:db8:ca2:2::2"/>
-
- -
-
mac
-
The address attribute defines a MAC - (hardware) address formatted as 6 groups of 2-digit - hexadecimal numbers, the groups separated by colons - (eg, "52:54:00:1C:DA:2F"). This MAC address is - assigned to the bridge device when it is created. Generally - it is best to not specify a MAC address when creating a - network - in this case, if a defined MAC address is needed for - proper operation, libvirt will automatically generate a random - MAC address and save it in the config. Allowing libvirt to - generate the MAC address will assure that it is compatible - with the idiosyncrasies of the platform where libvirt is - running. Since 0.8.8 -
-
dns
-
The dns element of a network contains configuration - information for the virtual network's DNS - server Since 0.9.3. - -

- The dns element can have an optional enable - attribute Since 2.2.0. - If enable is "no", then no DNS server will be - setup by libvirt for this network (and any other - configuration in <dns> will be ignored). - If enable is "yes" or unspecified (including - the complete absence of any <dns> - element) then a DNS server will be setup by libvirt to - listen on all IP addresses specified in the network's - configuration. -

-

- The dns element - can have an optional forwardPlainNames - attribute Since 1.1.2. - If forwardPlainNames is "no", then DNS resolution - requests for names that are not qualified with a domain - (i.e. names with no "." character) will not be forwarded to - the host's upstream DNS server - they will only be resolved if - they are known locally within the virtual network's own DNS - server. If forwardPlainNames is "yes", - unqualified names will be forwarded to the upstream DNS - server if they can't be resolved by the virtual network's own - DNS server. -

- - Currently supported sub-elements of <dns> are: -
-
forwarder
-
The dns element can have 0 or - more <forwarder> elements. Each - forwarder element defines an alternate DNS server to use - for some, or all, DNS requests sent to this network's DNS - server. There are two attributes - domain, - and addr; at least one of these must be - specified in any <forwarder> - element. If both domain and addr - are specified, then all requests that match the given - domain will be forwarded to the DNS server at addr. If - only domain is specified, then all matching - domains will be resolved locally (or via the host's - standard DNS forwarding if they can't be resolved - locally). If an addr is specified by itself, - then all DNS requests to the network's DNS server will be - forwarded to the DNS server at that address with no - exceptions. addr Since - 1.1.3, domain Since - 2.2.0. -
-
txt
-
A dns element can have 0 or more txt elements. - Each txt element defines a DNS TXT record and has two attribut= es, both - required: a name that can be queried via dns, and a value that= will be - returned when that name is queried. names cannot contain embed= ded spaces - or commas. value is a single string that can contain multiple = values - separated by commas. Since 0.9.3 -
-
host
-
The host element within dns is the - definition of DNS hosts to be passed to the DNS service. The IP - address is identified by the ip attribute and the= names - for that IP address are identified in the hostname - sub-elements of the host element. - Since 0.9.3 -
-
-
-
srv
-
The dns element can have also 0 or more s= rv - record elements. Each srv record element defines = a DNS SRV record - and has 2 mandatory and 5 optional attributes. The mandatory a= ttributes - are service and protocol (tcp, udp) - and the optional attributes are target, - port, priority, weight = and - domain as defined in DNS server SRV RFC (RFC 2782= ). - Since 0.9.9 -
-
-
-
ip
-
The address attribute defines an IPv4 address in - dotted-decimal format, or an IPv6 address in standard colon-separa= ted - hexadecimal format, that will be configured on the bridge device - associated with the virtual network. To the guests this IPv4 addre= ss - will be their IPv4 default route. For IPv6, the default route is - established via Router Advertisement. For IPv4 addresses, the - netmask attribute defines the significant bits of the - network address, again specified in dotted-decimal format. For IPv6 - addresses, and as an alternate method for IPv4 addresses, the - significant bits of the network address can be specified with the - prefix attribute, which is an integer (for example, - netmask=3D'255.255.255.0' could also be given as - prefix=3D'24'). The family attribute is = used - to specify the type of address - ipv4 or - ipv6; if no family is given, - ipv4 is assumed. More than one address of each family= can - be defined for a network. The optional localPtr attri= bute - (since 3.0.0) configures the DNS serv= er to - not forward any reverse DNS requests for IP addresses from the net= work - configured by the address and - netmask/prefix attributes. For some unus= ual - network prefixes (not divisible by 8 for IPv4 or not divisible by = 4 for - IPv6) libvirt may be unable to compute the PTR domain automaticall= y. - The ip element is supported sin= ce - 0.3.0. IPv6, multiple addresses on a single network, - family, and prefix are supported - since 0.8.7. The ip elem= ent may - contain the following elements: - -
-
tftp
-
The optional tftp element and its mandatory - root attribute enable TFTP services. The attribute - specifies the path to the root directory served via TFTP. The - tftp element is not supported for IPv6 addresses, - and can only be specified on a single IPv4 address per network. - Since 0.7.1 -
- -
dhcp
-
The presence of this element enables DHCP services on the - virtual network. The dhcp element is supported for - both IPv4 (since 0.3.0) and IPv6 - (since 1.0.1), but only for one IP - address of each type per network. The following sub-elements a= re - supported: -
-
range
-
The start and end attributes o= n the - range element specify the boundaries of a poo= l of - addresses to be provided to DHCP clients. These two addres= ses - must lie within the scope of the network defined on the pa= rent - ip element. There may be zero or more - range elements specified. - Since 0.3.0 -
-
host
-
Within the dhcp element there may be zero or - more host elements. These specify hosts which= will - be given names and predefined IP addresses by the built-in= DHCP - server. Any IPv4 host element must specify th= e MAC - address of the host to be assigned a given name (via the - mac attribute), the IP to be assigned to that= host - (via the ip attribute), and the name itself (= the - name attribute). The IPv6 host - element differs slightly from that for IPv4: there is no - mac attribute since a MAC address has no defi= ned - meaning in IPv6. Instead, the name attribute = is - used to identify the host to be assigned the IPv6 address.= For - DHCPv6, the name is the plain name of the client host sent= by the - client to the server. Note that this method of assigning a - specific IP address can also be used for IPv4 instead of t= he - mac attribute. - Since 0.4.5 -
-
bootp
-
The optional bootp element specifies BOOTP - options to be provided by the DHCP server for IPv4 only. T= wo - attributes are supported: file is mandatory a= nd - gives the file to be used for the boot image; - server is optional and gives the address of t= he - TFTP server from which the boot image will be fetched. - server defaults to the same host that runs the - DHCP server, as is the case when the tftp ele= ment - is used. The BOOTP options currently have to be the same f= or - all address ranges and statically assigned addresses. Since 0.7.1 (server - since 0.7.3) -
-
- -

- Optionally, range and host element= s can - have lease child element which specifies the le= ase - time through it's attributes expiry and - unit (which accepts seconds, - minutes and hours and defaults to - minutes if omitted). The minimal lease time is 2 - minutes, except when setting an infinite lease time - (expiry=3D'0'). - Since 6.3.0 -

- -
-
-
-
- -

Network namespaces

- -

- A special XML namespace is available for passing options - directly to the underlying dnsmasq configuration - file since 5.6.0. Usage of XML - namespaces comes with no support guarantees, so use at your own - risk. -

- -

- This example XML will pass the option strings foo=3Dbar= and - cname=3D*.foo.example.com,master.example.com directly t= o the - underlying dnsmasq instance. - 

-<network xmlns:dnsmasq=3D'http://libvirt.org/schemas/network/dnsmasq/1.=
0'>
-  ...
-  <dnsmasq:options>
-    <dnsmasq:option value=3D"foo=3Dbar"/>
-    <dnsmasq:option value=3D"cname=3D*.foo.example.com,master.example.c=
om"/>
-  </dnsmasq:options>
-</network>
-

- -

Example configuration

- -

NAT based network

- -

- This example is the so called "default" virtual network. It is - provided and enabled out-of-the-box for all libvirt installations. - This is a configuration that allows guest OS to get outbound - connectivity regardless of whether the host uses ethernet, wireless, - dialup, or VPN networking without requiring any specific admin - configuration. In the absence of host networking, it at least allows - guests to talk directly to each other. -

- - 
-<network>
-  <name>default</name>
-  <bridge name=3D"virbr0"/>
-  <forward mode=3D"nat"/>
-  <ip address=3D"192.168.122.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.122.2" end=3D"192.168.122.254"/>
-    </dhcp>
-  </ip>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:2::1" prefix=3D"64"/>
-</network>
- - -

- Below is a variation of the above example which adds an IPv6 - dhcp range definition. -

- - 
-<network>
-  <name>default6</name>
-  <bridge name=3D"virbr0"/>
-  <forward mode=3D"nat"/>
-  <ip address=3D"192.168.122.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.122.2" end=3D"192.168.122.254"/>
-    </dhcp>
-  </ip>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:2::1" prefix=3D"64">
-    <dhcp>
-      <range start=3D"2001:db8:ca2:2:1::10" end=3D"2001:db8:ca2:2:1::ff=
"/>
-    </dhcp>
-  </ip>
-</network>
- -

IPv6 NAT based network

- -

- Below is a variation for also providing IPv6 NAT. This can be - especially useful when using multiple interfaces where some, - such as WiFi cards, can not be bridged (usually on a laptop), - making it difficult to provide end-to-end IPv6 routing. -

- - 
-<network>
-  <name>default6</name>
-  <bridge name=3D"virbr0"/>
-  <forward mode=3D"nat">
-    <nat ipv6=3D'yes'>
-      <port start=3D'1024' end=3D'65535'/>
-    </nat>
-
-  <ip address=3D"192.168.122.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.122.2" end=3D"192.168.122.254"/>
-    </dhcp>
-  </ip>
-  <ip family=3D"ipv6" address=3D"fdXX:XXXX:XXXX:NNNN:: prefix=3D"64"/&g=
t;
-</network>
- -

IPv6 NAT addressing has some caveats over the more straight - forward IPv4 case. - RFC 4193 - defines the address range fd00::/8 for /48 IPv6 - private networks. It should be concatenated with a random 40-bit - string (i.e. 10 random hexadecimal digits replacing the X - values above, RFC 4193 provides - an algor= ithm - if you do not have a source of sufficient randomness). This - leaves 0 through ffff for subnets (N - above) which you can use at will.

- -

Many operating systems will not consider these addresses as - preferential to IPv4, due to some practical history of these - addresses being present but unroutable and causing networking - issues. On many Linux distributions, you may need to - override /etc/gai.conf with values - from RFC 3484 - to have your IPv6 NAT network correctly preferenced over IPv4.

- -

Routed network config

- -

- This is a variant on the default network which routes traffic - from the virtual network to the LAN without applying any NAT. - It requires that the IP address range be pre-configured in the - routing tables of the router on the host network. This example - further specifies that guest traffic may only go out via the - eth1 host network device. -

- - 
-<network>
-  <name>local</name>
-  <bridge name=3D"virbr1"/>
-  <forward mode=3D"route" dev=3D"eth1"/>
-  <ip address=3D"192.168.122.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.122.2" end=3D"192.168.122.254"/>
-    </dhcp>
-  </ip>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:2::1" prefix=3D"64"/>
-</network>
- -

- Below is another IPv6 variation. Instead of a dhcp range being - specified, this example has a couple of IPv6 host definitions. - Note that most of the dhcp host definitions use an "id" (client - id or DUID) since this has proven to be a more reliable way - of specifying the interface and its association with an IPv6 - address. The first is a DUID-LLT, the second a DUID-LL, and - the third a DUID-UUID. Since 1.0.3 -

- - 
-<network>
-  <name>local6</name>
-  <bridge name=3D"virbr1"/>
-  <forward mode=3D"route" dev=3D"eth1"/>
-  <ip address=3D"192.168.122.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.122.2" end=3D"192.168.122.254"/>
-    </dhcp>
-  </ip>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:2::1" prefix=3D"64">
-    <dhcp>
-      <host name=3D"paul" ip=3D"2001:db8:ca2:2:3::1"/>
-      <host id=3D"0:1:0:1:18:aa:62:fe:0:16:3e:44:55:66" ip=3D"2001:db8:=
ca2:2:3::2"/>
-      <host id=3D"0:3:0:1:0:16:3e:11:22:33" name=3D"ralph" ip=3D"2001:d=
b8:ca2:2:3::3"/>
-      <host id=3D"0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63"
-        name=3D"badbob" ip=3D"2001:db8:ca2:2:3::4"/>
-    </dhcp>
-  </ip>
-</network>
- -

- Below is yet another IPv6 variation. This variation has only - IPv6 defined with DHCPv6 on the primary IPv6 network. A static - link if defined for a second IPv6 network which will not be - directly visible on the bridge interface but there will be a - static route defined for this network via the specified - gateway. Note that the gateway address must be directly - reachable via (on the same subnet as) one of the <ip> - addresses defined for this <network>. - Since 1.0.6 -

- - 
-<network>
-  <name>net7</name>
-  <bridge name=3D"virbr7"/>
-  <forward mode=3D"route"/>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:7::1" prefix=3D"64">
-    <dhcp>
-      <range start=3D"2001:db8:ca2:7::100" end=3D"2001:db8:ca2::1ff"/&g=
t;
-      <host id=3D"0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63"
-        name=3D"lucas" ip=3D"2001:db8:ca2:2:3::4"/>
-    </dhcp>
-  </ip>
-  <route family=3D"ipv6" address=3D"2001:db8:ca2:8::" prefix=3D"64" gat=
eway=3D"2001:db8:ca2:7::4"/>
-</network>
- -

Isolated network config

- -

- This variant provides a completely isolated private network - for guests. The guests can talk to each other, and the host - OS, but cannot reach any other machines on the LAN, due to - the omission of the forward element in the XML - description. -

- - 
-<network>
-  <name>private</name>
-  <bridge name=3D"virbr2"/>
-  <ip address=3D"192.168.152.1" netmask=3D"255.255.255.0">
-    <dhcp>
-      <range start=3D"192.168.152.2" end=3D"192.168.152.254"/>
-    </dhcp>
-  </ip>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:3::1" prefix=3D"64"/>
-</network>
- -

Isolated IPv6 network config

- -

- This variation of an isolated network defines only IPv6. - Note that most of the dhcp host definitions use an "id" (client - id or DUID) since this has proven to be a more reliable way - of specifying the interface and its association with an IPv6 - address. The first is a DUID-LLT, the second a DUID-LL, and - the third a DUID-UUID. Since 1.0.3 -

- - 
-<network>
-  <name>sixnet</name>
-  <bridge name=3D"virbr6"/>
-  <ip family=3D"ipv6" address=3D"2001:db8:ca2:6::1" prefix=3D"64">
-    <dhcp>
-      <host name=3D"peter" ip=3D"2001:db8:ca2:6:6::1"/>
-      <host id=3D"0:1:0:1:18:aa:62:fe:0:16:3e:44:55:66" ip=3D"2001:db8:=
ca2:6:6::2"/>
-      <host id=3D"0:3:0:1:0:16:3e:11:22:33" name=3D"dariusz" ip=3D"2001=
:db8:ca2:6:6::3"/>
-      <host id=3D"0:4:7e:7d:f0:7d:a8:bc:c5:d2:13:32:11:ed:16:ea:84:63"
-        name=3D"anita" ip=3D"2001:db8:ca2:6:6::4"/>
-    </dhcp>
-  </ip>
-</network>
- -

Using an existing host bridge

- -

- Since 0.9.4 - This shows how to use a pre-existing host bridge "br0". The - guests will effectively be directly connected to the physical - network (i.e. their IP addresses will all be on the subnet of - the physical network, and there will be no restrictions on - inbound or outbound connections). -

- - 
-<network>
-  <name>host-bridge</name>
-  <forward mode=3D"bridge"/>
-  <bridge name=3D"br0"/>
-</network>
- -

Using a macvtap "direct" connection - -

- Since 0.9.4, QEMU and KVM only, requires - Linux kernel 2.6.34 or newer - This shows how to use macvtap to connect to the physical network - directly through one of a group of physical devices (without - using a host bridge device). As with the host bridge network, - the guests will effectively be directly connected to the - physical network so their IP addresses will all be on the subnet - of the physical network, and there will be no restrictions on - inbound or outbound connections. Note that, due to a limitation - in the implementation of macvtap, these connections do not allow - communication directly between the host and the guests - if you - require this you will either need the attached physical switch - to be operating in a mirroring mode (so that all traffic coming - to the switch is reflected back to the host's interface), or - provide alternate means for this communication (e.g. a second - interface on each guest that is connected to an isolated - network). The other forward modes that use macvtap (private, - vepa, and passthrough) would be used in a similar fashion. -

- - 
-<network>
-  <name>direct-macvtap</name>
-  <forward mode=3D"bridge">
-    <interface dev=3D"eth20"/>
-    <interface dev=3D"eth21"/>
-    <interface dev=3D"eth22"/>
-    <interface dev=3D"eth23"/>
-    <interface dev=3D"eth24"/>
-  </forward>
-</network>
- -

Network config with no gateway address= es

- -

- A valid network definition can contain no IPv4 or IPv6 addresses. Suc= h a definition - can be used for a "very private" or "very isolated" network since it w= ill not be - possible to communicate with the virtualization host via this network.= However, - this virtual network interface can be used for communication between v= irtual guest - systems. This works for IPv4 and (Since 1.0.1)<= /span> IPv6. - However, the new ipv6=3D'yes' must be added for guest-to-guest IPv6 - communication. -

- - 
-<network ipv6=3D'yes'>
-  <name>nogw</name>
-  <uuid>7a3b7497-1ec7-8aef-6d5c-38dff9109e93</uuid>
-  <bridge name=3D"virbr2" stp=3D"on" delay=3D"0"/>
-  <mac address=3D'00:16:3E:5D:C7:9E'/>
-</network>
- - - diff --git a/docs/formatnetwork.rst b/docs/formatnetwork.rst new file mode 100644 index 0000000000..d6550f6df9 --- /dev/null +++ b/docs/formatnetwork.rst @@ -0,0 +1,1144 @@ +.. role:: since + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Network XML format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +This page provides an introduction to the network XML format. For backgrou= nd +information on the concepts referred to here, consult the `relevant wiki +page `__. + +Element and attribute overview +------------------------------ + +The root element required for all virtual networks is named ``network`` an= d has +no configurable attributes (although :since:`since 0.10.0` there is one op= tional +read-only attribute - when examining the live configuration of a network, = the +attribute ``connections``, if present, specifies the number of guest inter= faces +currently connected via this network). The network XML format is available +:since:`since 0.3.0` + +General metadata +~~~~~~~~~~~~~~~~ + +The first elements provide basic metadata about the virtual network. + +:: + + + default + 3e3fce45-4f53-4fa7-bb32-11f34168b82b + + .. + .. + + ... + +``name`` + The content of the ``name`` element provides a short name for the virtu= al + network. This name should consist only of alphanumeric characters and is + required to be unique within the scope of a single host. It is used to = form + the filename for storing the persistent configuration file. :since:`Sin= ce + 0.3.0` +``uuid`` + The content of the ``uuid`` element provides a globally unique identifi= er for + the virtual network. The format must be RFC 4122 compliant, eg + ``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/crea= ting a + new network, a random UUID is generated. :since:`Since 0.3.0` + The ``metadata`` node can be used by applications to store custom metad= ata in + the form of XML nodes/trees. Applications must use custom namespaces on= their + XML nodes/trees, with only one top-level element per namespace (if the + application needs structure, they should have sub-elements to their nam= espace + element). :since:`Since 2.1.0` +``ipv6`` + When set to ``yes``, the optional parameter ``ipv6`` enables a network + definition with no IPv6 gateway addresses specified to have guest-to-gu= est + communications. For further information, see the example below for the + example with no gateway addresses. :since:`Since 1.0.1` +``trustGuestRxFilters`` + The optional parameter ``trustGuestRxFilters`` can be used to set that + attribute of the same name for each domain interface connected to this + network ( :since:`since 1.2.10` ). See the `Network + interfaces `__ section of the domain XML + documentation for more details. Note that an explicit setting of this + attribute in a portgroup or the individual domain interface will overri= de the + setting in the network. + +Connectivity +~~~~~~~~~~~~ + +The next set of elements control how a virtual network is provided connect= ivity +to the physical LAN (if at all). + +:: + + ... + + + + + ... + +``bridge`` + The ``name`` attribute on the ``bridge`` element defines the name of a = bridge + device which will be used to construct the virtual network. The virtual + machines will be connected to this bridge device allowing them to talk = to + each other. The bridge device may also be connected to the LAN. When de= fining + a new network with a ```` mode of "nat", "route", or "open" (o= r an + isolated network with no ```` element), libvirt will automatic= ally + generate a unique name for the bridge device if none is given, and this= name + will be permanently stored in the network configuration so that that th= e same + name will be used every time the network is started. For these types of + networks (nat, route, open, and isolated), a bridge name beginning with= the + prefix "virbr" is recommended (and that is what is auto-generated), but= not + enforced. Attribute ``stp`` specifies if Spanning Tree Protocol is 'on'= or + 'off' (default is 'on'). Attribute ``delay`` sets the bridge's forward = delay + value in seconds (default is 0). :since:`Since 0.3.0` + + The ``macTableManager`` attribute of the bridge element is used to tell + libvirt how the bridge's MAC address table (used to determine the corre= ct + egress port for packets based on destination MAC address) will be manag= ed. In + the default ``kernel`` setting, the kernel automatically adds and remov= es + entries, typically using learning, flooding, and promiscuous mode on the + bridge's ports in order to determine the proper egress port for packets= . When + ``macTableManager`` is set to ``libvirt``, libvirt disables kernel mana= gement + of the MAC table (in the case of the Linux host bridge, this means enab= ling + vlan_filtering on the bridge, and disabling learning and unicast_filter= for + all bridge ports), and explicitly adds/removes entries to the table acc= ording + to the MAC addresses in the domain interface configurations. Allowing l= ibvirt + to manage the MAC table can improve performance - with a Linux host bri= dge, + for example, turning off learning and unicast_flood on ports has its own + performance advantage, and can also lead to an additional boost by perm= itting + the kernel to automatically turn off promiscuous mode on some ports of = the + bridge (in particular, the port attaching the bridge to the physical + network). However, it can also cause some networking setups to stop wor= king + (e.g. vlan tagging, multicast, guest-initiated changes to MAC address) = and is + not supported by older kernels. :since:`Since 1.2.11, requires kernel 3= .17 or + newer` + + The optional ``zone`` attribute of the ``bridge`` element is used to sp= ecify + the `firewalld `__ zone for the bridge of a netw= ork + with ``forward`` mode of "nat", "route", "open", or one with no ``forwa= rd`` + specified. By default, the bridges of all virtual networks with these f= orward + modes are placed in the firewalld zone named "libvirt", which permits + incoming DNS, DHCP, TFTP, and SSH to the host from guests on the networ= k. + This behavior can be changed either by modifying the libvirt zone (using + firewalld management tools), or by placing the network in a different z= one + (which will also be managed using firewalld tools). :since:`Since 5.1.0` + +``mtu`` + The ``size`` attribute of the ``mtu>`` element specifies the Maximum + Transmission Unit (MTU) for the network. :since:`Since 3.1.0` . In the = case + of a libvirt-managed network (one with forward mode of ``nat``, ``route= ``, + ``open``, or no ``forward`` element (i.e. an isolated network), this wi= ll be + the MTU assigned to the bridge device when libvirt creates it, and ther= eafter + also assigned to all tap devices created to connect guest interfaces. N= etwork + types not specifically mentioned here don't support having an MTU set i= n the + libvirt network config. If mtu size is unspecified, the default setting= for + the type of device being used is assumed (usually 1500). +``domain`` + The ``name`` attribute on the ``domain`` element defines the DNS domain= of + the DHCP server. This element is optional, and is only used for those + networks with a ```` mode of "nat" or "route" (or an isolated + network with no ```` element). :since:`Since 0.4.5` + + If the optional ``localOnly`` attribute on the ``domain`` element is "y= es", + then DNS requests under this domain will only be resolved by the virtual + network's own DNS server - they will not be forwarded to the host's ups= tream + DNS server. If ``localOnly`` is "no", and by default, unresolved reques= ts + **will** be forwarded. :since:`Since 1.2.12` + +``forward`` + Inclusion of the ``forward`` element indicates that the virtual network= is to + be connected to the physical LAN. :since:`Since 0.3.0.` The ``mode`` + attribute determines the method of forwarding. If there is no ``forward= `` + element, the network will be isolated from any other network (unless a = guest + connected to that network is acting as a router, of course). The follow= ing + are valid settings for ``mode`` (if there is a ``forward`` element but = mode + is not specified, ``mode=3D'nat'`` is assumed): + + ``nat`` + All traffic between guests connected to this network and the physical + network will be forwarded to the physical network via the host's IP + routing stack, after the guest's IP address is translated to appear = as the + host machine's public IP address (a.k.a. Network Address Translation= , or + "NAT"). This allows multiple guests, all having access to the physic= al + network, on a host that is only allowed a single public IP address. = If a + network has any IPv6 addresses defined, the IPv6 traffic will be for= warded + using plain routing, since IPv6 has no concept of NAT. Firewall rule= s will + allow outbound connections to any other network device whether ether= net, + wireless, dialup, or VPN. If the ``dev`` attribute is set, the firew= all + rules will restrict forwarding to the named device only. Inbound + connections from other networks are all prohibited; all connections + between guests on the same network, and to/from the host to the gues= ts, + are unrestricted and not NATed. :since:`Since 0.4.2` + + :since:`Since 1.0.3` it is possible to specify a public IPv4 address= and + port range to be used for the NAT by using the ```` subelement.= Note + that all addresses from the range are used, not just those that are = in use + on the host. The address range is set with the ``
`` subelem= ents + and ``start`` and ``stop`` attributes: + + :: + + ... + + +
+ + + ... + + A single IPv4 address can be set by setting ``start`` and ``end`` + attributes to the same value. + + The port range to be used for the ```` can be set via the subel= ement + ````: + + :: + + ... + + + + + + ... + + :since:`Since 6.5.0` it is possible to enable NAT with IPv6 networki= ng. As + noted above, IPv6 has historically done plain forwarding and thus to= avoid + breaking historical compatibility, IPv6 NAT must be explicitly reque= sted. + + :: + + ... + + + + ... + + ``route`` + Guest network traffic will be forwarded to the physical network via = the + host's IP routing stack, but without having NAT applied. Again, if t= he + ``dev`` attribute is set, firewall rules will restrict forwarding to= the + named device only. This presumes that the local LAN router has suita= ble + routing table entries to return traffic to this host. All incoming a= nd + outgoing sessions to guest on these networks are unrestricted. (To + restrict incoming traffic to a guest on a routed network, you can + configure `nwfilter rules `__ on the guest's + interfaces.) :since:`Since 0.4.2` + ``open`` + As with mode=3D'route', guest network traffic will be forwarded to t= he + physical network via the host's IP routing stack, but there will be = no + firewall rules added to either enable or prevent any of this traffic= . When + forward=3D'open' is set, the ``dev`` attribute cannot be set (becaus= e the + forward dev is enforced with firewall rules, and the purpose of + forward=3D'open' is to have a forwarding mode where libvirt doesn't = add any + firewall rules). This mode presumes that the local LAN router has su= itable + routing table entries to return traffic to this host, and that some = other + management system has been used to put in place any necessary firewa= ll + rules. Although no firewall rules will be added for the network, it = is of + course still possible to add restrictions for specific guests using + `nwfilter rules `__ on the guests' interfaces.) + :since:`Since 2.2.0` + ``bridge`` + This network describes either 1) an existing host bridge that was + configured outside of libvirt (if a ```` eleme= nt has + been specified, :since:`Since 0.9.4` ), 2) an existing Open vSwitch = bridge + that was configured outside of libvirt (if both a ```` + element **and** a ```= ` have + been specified :since:`Since 0.10.0` ) 3) an interface or group of + interfaces to be used for a "direct" connection via macvtap using + macvtap's "bridge" mode (if the forward element has one or more + ```` subelements, :since:`Since 0.9.4` ) (see `Direct + attachment to physical interface `__ + for descriptions of the various macvtap modes). libvirt doesn't atte= mpt to + manage the bridge interface at all, thus the ```` element's + ``stp`` and ``delay`` attributes are not allowed; no iptables rules,= IP + addresses, or DHCP/DNS services are added; at the IP level, the guest + interface appears to be directly connected to the physical interface. + :since:`Since 0.9.4` + ``private`` + This network uses a macvtap "direct" connection in "private" mode to + connect each guest to the network. The physical interface to be used= will + be picked from among those listed in ```` subelements of = the + ```` element; when using 802.1Qbh mode (as indicated by the + ```` type attribute - note that this requires an + 802.1Qbh-capable hardware switch), each physical interface can only = be in + use by a single guest interface at a time; in modes other than 802.1= Qbh, + multiple guest interfaces can share each physical interface (libvirt= will + attempt to balance usage between all available interfaces). :since:`= Since + 0.9.4` + ``vepa`` + This network uses a macvtap "direct" connection in "vepa" mode to co= nnect + each guest to the network (this requires that the physical interface= s used + be connected to a vepa-capable hardware switch. The physical interfa= ce to + be used will be picked from among those listed in ```` + subelements of the ```` element; multiple guest interfaces = can + share each physical interface (libvirt will attempt to balance usage + between all available interfaces). :since:`Since 0.9.4` + ``passthrough`` + This network uses a macvtap "direct" connection in "passthrough" mod= e to + connect each guest to the network (note that this is *not* the same = thing + as "PCI passthrough"). The physical interface to be used will be pic= ked + from among those listed in ```` subelements of the + ```` element. Each physical interface can only be in use by= a + single guest interface at a time, so libvirt will keep track of which + interfaces are currently in use, and only assign unused interfaces (= if + there are no available physical interfaces when a domain interface is + being attached, an error will be logged, and the operation causing t= he + attach will fail (usually either a domain start, or a hotplug interf= ace + attach to a domain). :since:`Since 0.9.4` + ``hostdev`` + This network facilitates PCI Passthrough of a network device. A netw= ork + device is chosen from the interface pool and directly assigned to the + guest using generic device passthrough, after first optionally setti= ng the + device's MAC address and vlan tag to the configured value, and optio= nally + associating the device with an 802.1Qbh capable switch using a + ```` element. Note that - due to limitations in standard + single-port PCI ethernet card driver design - only SR-IOV (Single Ro= ot I/O + Virtualization) virtual function (VF) devices can be assigned in this + manner; to assign a standard single-port PCI or PCIe ethernet card t= o a + guest, use the traditional ```` device definition. :since:`= Since + 0.10.0` + + To force use of a particular type of device assignment, a interface can have an optional ``driver`` sub-elem= ent with + a ``name`` attribute set to either "vfio" (VFIO is a new method of d= evice + assignment that is compatible with UEFI Secure Boot) or "kvm" (the l= egacy + device assignment handled directly by the KVM kernel module) :since:= `Since + 1.0.5 (QEMU and KVM only, requires kernel 3.6 or newer)` . When spec= ified, + device assignment will fail if the requested method of device assign= ment + isn't available on the host. When not specified, the default is "vfi= o" on + systems where the VFIO driver is available and loaded, and "kvm" on = older + systems, or those where the VFIO driver hasn't been loaded :since:`S= ince + 1.1.3` (prior to that the default was always "kvm"). + + Note that this "intelligent passthrough" of network devices is very + similar to the functionality of a standard ```` device, the + difference being that this method allows specifying a MAC address, v= lan + tag, and ```` for the passed-through device. If these + capabilities are not required, if you have a standard single-port PC= I, + PCIe, or USB network card that doesn't support SR-IOV (and hence wou= ld + anyway lose the configured MAC address during reset after being assi= gned + to the guest domain), or if you are using a version of libvirt older= than + 0.10.0, you should use a standard ```` device definition in= the + domain's configuration to assign the device to the guest instead of + defining an ```` pointing to= a + network with ````. + + As mentioned above, a ```` element can have multiple ```` + subelements, each one giving the name of a physical interface that can = be + used for this network :since:`Since 0.9.4` : + + :: + + ... + + + + + + + + ... + + :since:`since 0.10.0` , ```` also has an optional read-only + attribute - when examining the live configuration of a network, the att= ribute + ``connections``, if present, specifies the number of guest interfaces + currently connected via this physical interface. + + Additionally, :since:`since 0.9.10` , libvirt allows a shorthand for + specifying all virtual interfaces associated with a single physical fun= ction, + by using the ```` subelement to call out the corresponding physical + interface associated with multiple virtual interfaces: + + :: + + ... + + + + ... + + When a guest interface is being constructed, libvirt will pick an inter= face + from this list to use for the connection. In modes where physical inter= faces + can be shared by multiple guest interfaces, libvirt will choose the int= erface + that currently has the least number of connections. For those modes tha= t do + not allow sharing of the physical device (in particular, 'passthrough' = mode, + and 'private' mode when using 802.1Qbh), libvirt will choose an unused + physical interface or, if it can't find an unused interface, fail the + operation. + + :since:`since 0.10.0` When using forward mode 'hostdev', the interface = pool + is specified with a list of ``
`` elements, each of which has + ```` (must always be ``'pci'``), ````, ````, + ````\ and ```` attributes. + + :: + + ... + + +
+
+
+ + ... + + Alternatively the interface pool can also be defined using a single phy= sical + function ```` subelement to call out the corresponding physical int= erface + associated with multiple virtual interfaces (similar to passthrough mod= e): + + :: + + ... + + + + ... + +Quality of service +^^^^^^^^^^^^^^^^^^ + +:: + + ... + + + + + + ... + +The ```` element allows setting quality of service for a partic= ular +network ( :since:`since 0.9.4` ). Setting ``bandwidth`` for a network is +supported only for networks with a ```` mode of ``route``, ``nat`= `, +``bridge``, or no mode at all (i.e. an "isolated" network). Setting +``bandwidth`` is **not** supported for forward modes ``passthrough``, +``private``, or ``hostdev``. Attempts to do this will lead to a failure to +define the network or to create a transient network. + +The ```` element can only be a subelement of a domain's +````, a subelement of a ````, or a subelement of a +```` in a ````. + +As a subelement of a domain's ````, the bandwidth only applies = to +that one interface of the domain. As a subelement of a ````, the +bandwidth is a total aggregate bandwidth to/from all guest interfaces atta= ched +to that network, **not** to each guest interface individually. If a domain= 's +```` has ```` element values higher than the aggrega= te for +the entire network, then the aggregate bandwidth for the ```` tak= es +precedence. This is because the two choke points are independent of each o= ther +where the domain's ```` bandwidth control is applied on the +interface's tap device, while the ```` bandwidth control is appli= ed on +the interface part of the bridge device created for that network. + +As a subelement of a ```` in a ````, if a domain's +```` has a ``portgroup`` attribute in its ```` element +**and** if the ```` itself has no ```` element, then= the +```` element of the portgroup will be applied individually to e= ach +guest interface defined to be a member of that portgroup. Any ```` +element in the domain's ```` definition will override the setti= ng in +the portgroup ( :since:`since 1.0.1` ). + +Incoming and outgoing traffic can be shaped independently. The ``bandwidth= `` +element can have at most one ``inbound`` and at most one ``outbound`` child +element. Leaving either of these children elements out results in no QoS a= pplied +for that traffic direction. So, when you want to shape only incoming traff= ic, +use ``inbound`` only, and vice versa. Each of these elements have one mand= atory +attribute - ``average`` (or ``floor`` as described below). The attributes = are as +follows, where accepted values for each attribute is an integer number. + +``average`` + Specifies the desired average bit rate for the interface being shaped (= in + kilobytes/second). +``peak`` + Optional attribute which specifies the maximum rate at which the bridge= can + send data (in kilobytes/second). Note the limitation of implementation:= this + attribute in the ``outbound`` element is ignored (as Linux ingress filt= ers + don't know it yet). +``burst`` + Optional attribute which specifies the amount of kibibytes that can be + transmitted in a single burst at ``peak`` speed. +``floor`` + Optional attribute available only for the ``inbound`` element. This att= ribute + guarantees minimal throughput for shaped interfaces. This, however, req= uires + that all traffic goes through one point where QoS decisions can take pl= ace, + hence why this attribute works only for virtual networks for now (that = is + ```` with a forward type of route, nat, op= en or no + forward at all). Moreover, the virtual network the interface is connect= ed to + is required to have at least inbound QoS set (``average`` at least). If= using + the ``floor`` attribute users don't need to specify ``average``. Howeve= r, + ``peak`` and ``burst`` attributes still require ``average``. Currently,= the + Linux kernel doesn't allow ingress qdiscs to have any classes therefore + ``floor`` can be applied only on ``inbound`` and not ``outbound``. + +Attributes ``average``, ``peak``, and ``burst`` are available :since:`since +0.9.4` , while the ``floor`` attribute is available :since:`since 1.0.1` . + +Setting VLAN tag (on supported network types only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + + ovs-net + + + + + + + + + + + + + + + + +If (and only if) the network connection used by the guest supports VLAN ta= gging +transparent to the guest, an optional ```` element can specify one o= r 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=3D'bridge' interfaces connected to an Open vSwitch bridge :since:`Sin= ce +0.10.0` , 2) SRIOV Virtual Functions (VF) used via type=3D'hostdev' (direc= t device +assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type=3D'dire= ct' with +mode=3D'passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All = other +connection types, including standard linux bridges and libvirt's own virtu= al +networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) sw= itches +provide their own way (outside of libvirt) to tag guest traffic onto a spe= cific +VLAN. Each tag is given in a separate ```` subelement of ```` (= for +example: ````). For VLAN trunking of multiple tags (= which is +supported only on Open vSwitch connections), multiple ```` subelement= s 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=3D'yes'`` can be added to t= he +toplevel ```` 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.` Thi= s is +done with the optional ``nativeMode`` attribute on the ```` subelemen= t: +``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute = of the +```` subelement containing ``nativeMode`` sets which VLAN is consider= ed to +be the "native" VLAN for this interface, and the ``nativeMode`` attribute +determines whether or not traffic for that VLAN will be tagged. + +```` elements can also be specified in a ```` element, as= well +as directly in a domain's ```` element. In the case that a vlan= tag +is specified in multiple locations, the setting in ```` takes +precedence, followed by the setting in the ```` selected by the +interface config. The ```` in ```` will be selected only if= none +is given in ```` or ````. + +Isolating ports from one another +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + + isolated-ports + + + + + +:since:`Since 6.1.0.` The ``port`` element property ``isolated``, when set= to +``yes`` (default setting is ``no``) is used to isolate the network traffic= of +each guest on the network from all other guests connected to the network; = it +does not have an effect on communication between the guests and the host, = or +between the guests and destinations beyond this network. This setting is o= nly +supported for networks that use a Linux host bridge to connect guest inter= faces +via a standard tap device (i.e. those with a forward mode of nat, route, o= pen, +bridge, or no forward mode). + +Portgroups +^^^^^^^^^^ + +:: + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + ... + +:since:`Since 0.9.4` A portgroup provides a method of easily putting guest +connections to the network into different classes, with each class potenti= ally +having a different level/type of service. :since:`Since 0.9.4` Each networ= k can +have multiple portgroup elements (and one of those can optionally be desig= nated +as the 'default' portgroup for the network), and each portgroup has a name= , as +well as various attributes and subelements associated with it. The current= ly +supported subelements are ```` (described in `Quality of servic= e`_) +and ```` (documented +`here `__). If a domain interface +definition specifies a portgroup (by adding a ``portgroup`` attribute to t= he +```` subelement), that portgroup's info will be merged into the +interface's configuration. If no portgroup is given in the interface defin= ition, +and one of the network's portgroups has ``default=3D'yes'``, that default +portgroup will be used. If no portgroup is given in the interface definiti= on, +and there is no default portgroup, then none will be used. Any ```` +specified directly in the domain XML will take precedence over any setting= in +the chosen portgroup. if a ```` is specified in the portgroup +(and/or directly in the network definition), the multiple virtualports wil= l be +merged, and any parameter that is specified in more than one virtualport, = and is +not identical, will be considered an error, and will prevent the interface= from +starting. + +portgroups also support the optional parameter ``trustGuestRxFilters`` whi= ch can +be used to set that attribute of the same name for each domain interface u= sing +this portgroup ( :since:`since 1.2.10` ). See the `Network +interfaces `__ section of the domain XML +documentation for more details. Note that an explicit setting of this attr= ibute +in the portgroup overrides the network-wide setting, and an explicit setti= ng in +the individual domain interface will override the setting in the portgroup. + +Static Routes +^^^^^^^^^^^^^ + +Static route definitions are used to provide routing information to the +virtualization host for networks which are not directly reachable from the +virtualization host, but \*are\* reachable from a guest domain that is its= elf +reachable from the host :since:`since 1.0.6` . + +As shown in `Network config with no gateway addresses`_ example, it is +possible to define a virtual network interface with no IPv4 or IPv6 addres= ses. +Such networks are useful to provide host connectivity to networks which ar= e only +reachable via a guest. A guest with connectivity both to the guest-only ne= twork +and to another network that is directly reachable from the host can act as= a +gateway between the networks. A static route added to the "host-visible" n= etwork +definition provides the routing information so that IP packets can be sent= from +the virtualization host to guests on the hidden network. + +Here is a fragment of a definition which shows the static route specificat= ion as +well as the IPv4 and IPv6 definitions for network addresses which are refe= rred +to in the ``gateway`` gateway address specifications. Note that the third = static +route specification includes the ``metric`` attribute specification with a= value +of 2. This particular route would \*not\* be preferred if there was another +existing rout on the system with the same address and prefix but with a lo= wer +value for the metric. If there is a route in the host system configuration= that +should be overridden by a route in a virtual network whenever the virtual +network is running, the configuration for the system-defined route should = be +modified to have a higher metric, and the route on the virtual network giv= en a +lower metric (for example, the default metric of "1"). + +:: + + ... + + + + + + + + + + ... + +Addressing +~~~~~~~~~~ + +The final set of elements define the addresses (IPv4 and/or IPv6, as well = as +MAC) to be assigned to the bridge device associated with the virtual netwo= rk, +and optionally enable DHCP services. These elements are only valid for iso= lated +networks (no ``forward`` element specified), and for those with a forward = mode +of 'route' or 'nat'. + +:: + + ... + + + + + + + + + + myhost + myhostalias + + + + + + + + + + + + + + + + +``mac`` + The ``address`` attribute defines a MAC (hardware) address formatted as= 6 + groups of 2-digit hexadecimal numbers, the groups separated by colons (= eg, + ``"52:54:00:1C:DA:2F"``). This MAC address is assigned to the bridge de= vice + when it is created. Generally it is best to not specify a MAC address w= hen + creating a network - in this case, if a defined MAC address is needed f= or + proper operation, libvirt will automatically generate a random MAC addr= ess + and save it in the config. Allowing libvirt to generate the MAC address= will + assure that it is compatible with the idiosyncrasies of the platform wh= ere + libvirt is running. :since:`Since 0.8.8` +``dns`` + The dns element of a network contains configuration information for the + virtual network's DNS server :since:`Since 0.9.3` . + + The dns element can have an optional ``enable`` attribute :since:`Since + 2.2.0` . If ``enable`` is "no", then no DNS server will be setup by lib= virt + for this network (and any other configuration in ```` will be igno= red). + If ``enable`` is "yes" or unspecified (including the complete absence o= f any + ```` element) then a DNS server will be setup by libvirt to listen= on + all IP addresses specified in the network's configuration. + + The dns element can have an optional ``forwardPlainNames`` attribute + :since:`Since 1.1.2` . If ``forwardPlainNames`` is "no", then DNS resol= ution + requests for names that are not qualified with a domain (i.e. names wit= h no + "." character) will not be forwarded to the host's upstream DNS server = - they + will only be resolved if they are known locally within the virtual netw= ork's + own DNS server. If ``forwardPlainNames`` is "yes", unqualified names **= will** + be forwarded to the upstream DNS server if they can't be resolved by the + virtual network's own DNS server. + + Currently supported sub-elements of ```` are: + + ``forwarder`` + The dns element can have 0 or more ```` elements. Each + forwarder element defines an alternate DNS server to use for some, o= r all, + DNS requests sent to this network's DNS server. There are two attrib= utes - + ``domain``, and ``addr``; at least one of these must be specified in= any + ```` element. If both ``domain`` and ``addr`` are specifi= ed, + then all requests that match the given domain will be forwarded to t= he DNS + server at addr. If only ``domain`` is specified, then all matching d= omains + will be resolved locally (or via the host's standard DNS forwarding = if + they can't be resolved locally). If an ``addr`` is specified by itse= lf, + then all DNS requests to the network's DNS server will be forwarded = to the + DNS server at that address with no exceptions. ``addr`` :since:`Since + 1.1.3` , ``domain`` :since:`Since 2.2.0` . + ``txt`` + A ``dns`` element can have 0 or more ``txt`` elements. Each txt elem= ent + defines a DNS TXT record and has two attributes, both required: a na= me + that can be queried via dns, and a value that will be returned when = that + name is queried. names cannot contain embedded spaces or commas. val= ue is + a single string that can contain multiple values separated by commas. + :since:`Since 0.9.3` + ``host`` + The ``host`` element within ``dns`` is the definition of DNS hosts t= o be + passed to the DNS service. The IP address is identified by the ``ip`` + attribute and the names for that IP address are identified in the + ``hostname`` sub-elements of the ``host`` element. :since:`Since 0.9= .3` + + ``srv`` + The ``dns`` element can have also 0 or more ``srv`` record elements.= Each + ``srv`` record element defines a DNS SRV record and has 2 mandatory = and 5 + optional attributes. The mandatory attributes are ``service`` and + ``protocol`` (tcp, udp) and the optional attributes are ``target``, + ``port``, ``priority``, ``weight`` and ``domain`` as defined in DNS = server + SRV RFC (RFC 2782). :since:`Since 0.9.9` + +``ip`` + The ``address`` attribute defines an IPv4 address in dotted-decimal for= mat, + or an IPv6 address in standard colon-separated hexadecimal format, that= will + be configured on the bridge device associated with the virtual network.= To + the guests this IPv4 address will be their IPv4 default route. For IPv6= , the + default route is established via Router Advertisement. For IPv4 address= es, + the ``netmask`` attribute defines the significant bits of the network + address, again specified in dotted-decimal format. For IPv6 addresses, = and as + an alternate method for IPv4 addresses, the significant bits of the net= work + address can be specified with the ``prefix`` attribute, which is an int= eger + (for example, ``netmask=3D'255.255.255.0'`` could also be given as + ``prefix=3D'24'``). The ``family`` attribute is used to specify the typ= e of + address - ``ipv4`` or ``ipv6``; if no ``family`` is given, ``ipv4`` is + assumed. More than one address of each family can be defined for a netw= ork. + The optional ``localPtr`` attribute ( :since:`since 3.0.0` ) configures= the + DNS server to not forward any reverse DNS requests for IP addresses fro= m the + network configured by the ``address`` and ``netmask``/``prefix`` attrib= utes. + For some unusual network prefixes (not divisible by 8 for IPv4 or not + divisible by 4 for IPv6) libvirt may be unable to compute the PTR domain + automatically. The ``ip`` element is supported :since:`since 0.3.0` . I= Pv6, + multiple addresses on a single network, ``family``, and ``prefix`` are + supported :since:`since 0.8.7` . The ``ip`` element may contain the fol= lowing + elements: + + ``tftp`` + The optional ``tftp`` element and its mandatory ``root`` attribute e= nable + TFTP services. The attribute specifies the path to the root directory + served via TFTP. The ``tftp`` element is not supported for IPv6 addr= esses, + and can only be specified on a single IPv4 address per network. + :since:`Since 0.7.1` + ``dhcp`` + The presence of this element enables DHCP services on the virtual ne= twork. + The ``dhcp`` element is supported for both IPv4 ( :since:`since 0.3.= 0` ) + and IPv6 ( :since:`since 1.0.1` ), but only for one IP address of ea= ch + type per network. The following sub-elements are supported: + + ``range`` + The ``start`` and ``end`` attributes on the ``range`` element spe= cify + the boundaries of a pool of addresses to be provided to DHCP clie= nts. + These two addresses must lie within the scope of the network defi= ned on + the parent ``ip`` element. There may be zero or more ``range`` el= ements + specified. :since:`Since 0.3.0` + ``host`` + Within the ``dhcp`` element there may be zero or more ``host`` + elements. These specify hosts which will be given names and prede= fined + IP addresses by the built-in DHCP server. Any IPv4 ``host`` eleme= nt + must specify the MAC address of the host to be assigned a given n= ame + (via the ``mac`` attribute), the IP to be assigned to that host (= via + the ``ip`` attribute), and the name itself (the ``name`` attribut= e). + The IPv6 ``host`` element differs slightly from that for IPv4: th= ere is + no ``mac`` attribute since a MAC address has no defined meaning in + IPv6. Instead, the ``name`` attribute is used to identify the hos= t to + be assigned the IPv6 address. For DHCPv6, the name is the plain n= ame of + the client host sent by the client to the server. Note that this = method + of assigning a specific IP address can also be used for IPv4 inst= ead of + the ``mac`` attribute. :since:`Since 0.4.5` + ``bootp`` + The optional ``bootp`` element specifies BOOTP options to be prov= ided + by the DHCP server for IPv4 only. Two attributes are supported: + ``file`` is mandatory and gives the file to be used for the boot = image; + ``server`` is optional and gives the address of the TFTP server f= rom + which the boot image will be fetched. ``server`` defaults to the = same + host that runs the DHCP server, as is the case when the ``tftp`` + element is used. The BOOTP options currently have to be the same = for + all address ranges and statically assigned addresses. :since:`Sin= ce + 0.7.1` (``server`` :since:`since 0.7.3` ) + + Optionally, ``range`` and ``host`` elements can have ``lease`` child + element which specifies the lease time through it's attributes ``exp= iry`` + and ``unit`` (which accepts ``seconds``, ``minutes`` and ``hours`` a= nd + defaults to ``minutes`` if omitted). The minimal lease time is 2 min= utes, + except when setting an infinite lease time (``expiry=3D'0'``). :sinc= e:`Since + 6.3.0` + +Network namespaces +~~~~~~~~~~~~~~~~~~ + +A special XML namespace is available for passing options directly to the +underlying dnsmasq configuration file :since:`since 5.6.0` . Usage of XML +namespaces comes with no support guarantees, so use at your own risk. + +This example XML will pass the option strings ``foo=3Dbar`` and +``cname=3D*.foo.example.com,master.example.com`` directly to the underlying +dnsmasq instance. + +:: + + + ... + + + + + + +Example configuration +--------------------- + +NAT based network +~~~~~~~~~~~~~~~~~ + +This example is the so called "default" virtual network. It is provided and +enabled out-of-the-box for all libvirt installations. This is a configurat= ion +that allows guest OS to get outbound connectivity regardless of whether th= e host +uses ethernet, wireless, dialup, or VPN networking without requiring any +specific admin configuration. In the absence of host networking, it at lea= st +allows guests to talk directly to each other. + +:: + + + default + + + + + + + + + + +Below is a variation of the above example which adds an IPv6 dhcp range +definition. + +:: + + + default6 + + + + + + + + + + + + + + +IPv6 NAT based network +~~~~~~~~~~~~~~~~~~~~~~ + +Below is a variation for also providing IPv6 NAT. This can be especially u= seful +when using multiple interfaces where some, such as WiFi cards, can not be +bridged (usually on a laptop), making it difficult to provide end-to-end I= Pv6 +routing. + +:: + + + default6 + + + + + + + + + + + + + + +IPv6 NAT addressing has some caveats over the more straight forward IPv4 c= ase. +`RFC 4193 `__ defines the address ran= ge +fd00::/8 for /48 IPv6 private networks. It should be concatenated with a r= andom +40-bit string (i.e. 10 random hexadecimal digits replacing the X values ab= ove, +RFC 4193 provides an +`algorithm `__ if you d= o not +have a source of sufficient randomness). This leaves 0 through ffff for su= bnets +(N above) which you can use at will. + +Many operating systems will not consider these addresses as preferential to +IPv4, due to some practical history of these addresses being present but +unroutable and causing networking issues. On many Linux distributions, you= may +need to override /etc/gai.conf with values from `RFC +3484 `__ to have your IPv6 NAT netwo= rk +correctly preferenced over IPv4. + +Routed network config +~~~~~~~~~~~~~~~~~~~~~ + +This is a variant on the default network which routes traffic from the vir= tual +network to the LAN without applying any NAT. It requires that the IP addre= ss +range be pre-configured in the routing tables of the router on the host ne= twork. +This example further specifies that guest traffic may only go out via the +``eth1`` host network device. + +:: + + + local + + + + + + + + + + +Below is another IPv6 variation. Instead of a dhcp range being specified, = this +example has a couple of IPv6 host definitions. Note that most of the dhcp = host +definitions use an "id" (client id or DUID) since this has proven to be a = more +reliable way of specifying the interface and its association with an IPv6 +address. The first is a DUID-LLT, the second a DUID-LL, and the third a +DUID-UUID. :since:`Since 1.0.3` + +:: + + + local6 + + + + + + + + + + + + + + + + + +Below is yet another IPv6 variation. This variation has only IPv6 defined = with +DHCPv6 on the primary IPv6 network. A static link if defined for a second = IPv6 +network which will not be directly visible on the bridge interface but the= re +will be a static route defined for this network via the specified gateway.= Note +that the gateway address must be directly reachable via (on the same subne= t as) +one of the addresses defined for this . :since:`Since 1.0.6` + +:: + + + net7 + + + + + + + + + + + +Isolated network config +~~~~~~~~~~~~~~~~~~~~~~~ + +This variant provides a completely isolated private network for guests. The +guests can talk to each other, and the host OS, but cannot reach any other +machines on the LAN, due to the omission of the ``forward`` element in the= XML +description. + +:: + + + private + + + + + + + + + +Isolated IPv6 network config +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This variation of an isolated network defines only IPv6. Note that most of= the +dhcp host definitions use an "id" (client id or DUID) since this has prove= n to +be a more reliable way of specifying the interface and its association wit= h an +IPv6 address. The first is a DUID-LLT, the second a DUID-LL, and the third= a +DUID-UUID. :since:`Since 1.0.3` + +:: + + + sixnet + + + + + + + + + + + +Using an existing host bridge +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:since:`Since 0.9.4` This shows how to use a pre-existing host bridge "br0= ". The +guests will effectively be directly connected to the physical network (i.e. +their IP addresses will all be on the subnet of the physical network, and = there +will be no restrictions on inbound or outbound connections). + +:: + + + host-bridge + + + + +Using a macvtap "direct" connection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:since:`Since 0.9.4, QEMU and KVM only, requires Linux kernel 2.6.34 or ne= wer` +This shows how to use macvtap to connect to the physical network directly +through one of a group of physical devices (without using a host bridge de= vice). +As with the host bridge network, the guests will effectively be directly +connected to the physical network so their IP addresses will all be on the +subnet of the physical network, and there will be no restrictions on inbou= nd or +outbound connections. Note that, due to a limitation in the implementation= of +macvtap, these connections do not allow communication directly between the= host +and the guests - if you require this you will either need the attached phy= sical +switch to be operating in a mirroring mode (so that all traffic coming to = the +switch is reflected back to the host's interface), or provide alternate me= ans +for this communication (e.g. a second interface on each guest that is conn= ected +to an isolated network). The other forward modes that use macvtap (private, +vepa, and passthrough) would be used in a similar fashion. + +:: + + + direct-macvtap + + + + + + + + + +Network config with no gateway addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A valid network definition can contain no IPv4 or IPv6 addresses. Such a +definition can be used for a "very private" or "very isolated" network sin= ce it +will not be possible to communicate with the virtualization host via this +network. However, this virtual network interface can be used for communica= tion +between virtual guest systems. This works for IPv4 and :since:`(Since 1.0.= 1)` +IPv6. However, the new ipv6=3D'yes' must be added for guest-to-guest IPv6 +communication. + +:: + + + nogw + 7a3b7497-1ec7-8aef-6d5c-38dff9109e93 + + + diff --git a/docs/formatnetworkport.rst b/docs/formatnetworkport.rst index 86a1bdb60b..6f1a24a52c 100644 --- a/docs/formatnetworkport.rst +++ b/docs/formatnetworkport.rst @@ -78,7 +78,7 @@ The following elements are common to one or more of the p= lug types listed later This part of the network port XML provides setting quality of service. Incoming and outgoing traffic can be shaped independently. The ``bandwi= dth`` element and its child elements are described in the - `QoS `__ section of the Network XML. In + `QoS `__ section of the Network = XML. In addition the ``classID`` attribute may exist to provide the ID of the t= raffic shaping class that is active. ``rxfilters`` diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst index d7753c4970..e8568559fa 100644 --- a/docs/manpages/virsh.rst +++ b/docs/manpages/virsh.rst @@ -2017,7 +2017,8 @@ inbound or outbound bandwidth. *average,peak,burst,fl= oor* is the same as in command *attach-interface*. Values for *average*, *peak* and *floor* are expressed in kilobytes per second, while *burst* is expressed in kilob= ytes in a single burst at *peak* speed as described in the Network XML -documentation at `https://libvirt.org/formatnetwork.html#elementQoS `__. +documentation at +`https://libvirt.org/formatnetwork.html#quality-of-service `__. To clear inbound or outbound settings, use *--inbound* or *--outbound* respectfully with average value of zero. @@ -4824,7 +4825,7 @@ specified. The other two *peak* and *burst* are opti= onal, so are expressed in kilobytes per second, while *burst* is expressed in kilobytes in a single burst at *peak* speed as described in the Network XML documentation at -`https://libvirt.org/formatnetwork.html#elementQoS `__. +`https://libvirt.org/formatnetwork.html#quality-of-service `__. ``--managed`` is usable only for *hostdev* type and tells libvirt that the interface should be managed, which means detached and reattached diff --git a/docs/meson.build b/docs/meson.build index 196f49a1a0..557cfdb3cf 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -18,7 +18,6 @@ docs_assets =3D [ ] docs_html_in_files =3D [ - 'formatnetwork', 'formatnode', 'index', 'remote', @@ -72,6 +71,7 @@ docs_rst_files =3D [ 'formatcheckpoint', 'formatdomain', 'formatdomaincaps', + 'formatnetwork', 'formatnetworkport', 'formatnwfilter', 'formatsecret', --=20 2.35.1