From 073ef15c876a8257a077b8b3aa054da2d6ca2ef9 Mon Sep 17 00:00:00 2001 From: Laine Stump Date: Wed, 10 Aug 2011 01:41:19 -0400 Subject: [PATCH] docs: describe new virtual switch configuration in network XML docs This should have been done with the rest of the patch for virtual switch / network device abstraction. If documents the new elements (and new usage of existing elements) in the XML to support libvirt networks that use existing host bridges and macvtap direct connections, as well as the new element. --- docs/formatnetwork.html.in | 292 ++++++++++++++++++++++++++++++++++--- 1 file changed, 268 insertions(+), 24 deletions(-) diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in index ddfa77cb92..9e1cb2207c 100644 --- a/docs/formatnetwork.html.in +++ b/docs/formatnetwork.html.in @@ -70,36 +70,172 @@ bridge device allowing them to talk to each other. The bridge device may also be connected to the LAN. It is recommended that bridge device names started with the prefix vir, but the name - virbr0 is reserved for the "default" virtual network. - This element should always be provided when defining a new network. - 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). + virbr0 is reserved for the "default" virtual + network. This element should always be provided when defining + a new network with a <forward> mode of + "nat" or "route" (or an isolated network with + no <forward> element). + 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
domain
- The name attribute on the domain element - defines the DNS domain of the DHCP server. This element is optional. - Since 0.4.5 + 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
forward
Inclusion of the forward element indicates that the virtual network is to be connected to the physical - LAN. the mode attribute determines the method of - forwarding; possible selections are 'nat' and 'route'. If mode - is not specified, NAT forwarding will be used for - connectivity. If a network has any IPv6 addresses defined, - even if mode is given as 'nat', the IPv6 traffic - will be forwarded using routing, since IPv6 has no concept of NAT. - Firewall rules will allow forwarding 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. If the mode attribute is set to route - then the traffic will not have NAT applied. This presumes that the - local LAN router has suitable routing table entries to return traffic - to this host. Since 0.3.0; 'mode' attribute since - 0.4.2
+ 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='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 +
+ +
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. Firewall rules are also installed + that prevent incoming sessions from the physical network + to the guests, but outgoing sessions are unrestricted (as + are sessions from the host to the guests, and between + guests on the same network.)Since + 0.4.2 +
+ +
bridge
+
+ This network describes either 1) an existing host bridge + that was configured outside of libvirt (if + a <bridge name='xyz'/> element has been + specified), or 2) 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) + (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 +
+
+ 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 networkSince 0.9.4: + 
+...
+  <forward mode='passthrough'>
+    <interface dev='eth10'/>
+    <interface dev='eth11'/>
+    <interface dev='eth12'/>
+    <interface dev='eth13'/>
+    <interface dev='eth14'/>
+  </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. +
Quality of service
@@ -110,7 +246,6 @@ <inbound average='1000' peak='5000' burst='5120'/> <outbound average='128' peak='256' burst='256'/> </bandwidth> - <mac address='00:16:3E:5D:C7:9E'/> ...

@@ -134,13 +269,72 @@ Since 0.9.4

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

+ 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. 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 + subelements associated with it. The currently supported + subelements are <bandwidth> + (documented 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='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> + or <virtualport> specified directly in the + domain XML will take precedence over any setting in the chosen + portgroup. +

+

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. + services. These elements are only valid for isolated networks + (no forward element specified), and for those with + a forward mode of 'route' or 'nat'. 

@@ -345,5 +539,55 @@
         <ip family="ipv6" address="2001:8794:ca2:3::1" prefix="64" />
       </network>
+

Using an existing host bridge

+ +

+ 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="bridge"/>
+        <bridge name="br0"/>
+      </network>
+ +

Using a macvtap "direct" connection

+ +

+ 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="bridge">
+          <interface dev="eth20"/>
+          <interface dev="eth21"/>
+          <interface dev="eth22"/>
+          <interface dev="eth23"/>
+          <interface dev="eth24"/>
+        </forward>
+      </network>
+