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 <network> XML to support libvirt networks that use existing host bridges and macvtap direct connections, as well as the new <portgroup> element. --- docs/formatnetwork.html.in | 286 ++++++++++++++++++++++++++++++++++++++++---- 1 files changed, 262 insertions(+), 24 deletions(-) diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in index ddfa77c..4be03cd 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 <code>vir</code>, but the name - <code>virbr0</code> is reserved for the "default" virtual network. - This element should always be provided when defining a new network. - Attribute <code>stp</code> specifies if Spanning Tree Protocol is - 'on' or 'off' (default is 'on'). Attribute <code>delay</code> sets - the bridge's forward delay value in seconds (default is 0). + <code>virbr0</code> is reserved for the "default" virtual + network. This element should always be provided when defining + a new network with a <code><forward></code> mode of + "nat" or "route" (or an isolated network with + no <code><forward></code> element). + Attribute <code>stp</code> specifies if Spanning Tree Protocol + is 'on' or 'off' (default is + 'on'). Attribute <code>delay</code> sets the bridge's forward + delay value in seconds (default is 0). <span class="since">Since 0.3.0</span> </dd> <dt><code>domain</code></dt> <dd> - The <code>name</code> attribute on the <code>domain</code> element - defines the DNS domain of the DHCP server. This element is optional. - <span class="since">Since 0.4.5</span> + The <code>name</code> attribute on the <code>domain</code> + element defines the DNS domain of the DHCP server. This + element is optional, and is only used for those networks with + a <code><forward></code> mode of "nat" or "route" (or an + isolated network with no <code><forward></code> + element). <span class="since">Since 0.4.5</span> </dd> <dt><code>forward</code></dt> <dd>Inclusion of the <code>forward</code> element indicates that the virtual network is to be connected to the physical - LAN. the <code>mode</code> 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 <code>mode</code> 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 <code>dev</code> attribute - is set, the firewall rules will restrict forwarding to the named - device only. If the <code>mode</code> attribute is set to <code>route</code> - 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. <span class="since">Since 0.3.0; 'mode' attribute since - 0.4.2</span></dd> + LAN.<span class="since">Since 0.3.0.</span> + The <code>mode</code> attribute determines the method of + forwarding. If there is no <code>forward</code> 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 <code>mode</code> (if there is a <code>forward</code> + element but mode is not specified, <code>mode='nat'</code> is + assumed): + <dl> + <dt><code>nat</code></dt> + <dd> + 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 <code>dev</code> 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.<span class="since">Since + 0.4.2</span> + </dd> + + <dt><code>route</code></dt> + <dd> + 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 <code>dev</code> + 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.)<span class="since">Since + 0.4.2</span> + </dd> + + <dt><code>bridge</code></dt> + <dd> + This network describes either 1) an existing host bridge + that was configured outside of libvirt (if + a <code><bridge name='xyz'/></code> 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 <code><interface></code> subelements) + (see <a href="formatdomain.html#elementsNICSDirect">Direct + attachment to physical interface</a> for descriptions of + the various macvtap modes). libvirt doesn't attempt to + manage the bridge interface at all, thus + the <code><bridge></code> element's <code>stp</code> + and <code>delay</code> 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.<span class="since">Since 0.9.4</span> + </dd> + <dt><code>private</code></dt> + <dd> + 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 <code><interface></code> subelements + of the <code><forward></code> element; when using + 802.1Qbh mode (as indicated by + the <code><virtualport></code> 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).<span class="since">Since + 0.9.4</span> + </dd> + <dt><code>vepa</code></dt> + <dd> + 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 <code><interface></code> subelements of + the <code><forward></code> element; multiple guest + interfaces can share each physical interface (libvirt will + attempt to balance usage between all available + interfaces).<span class="since">Since 0.9.4</span> + </dd> + <dt><code>passthrough</code></dt> + <dd> + This network uses a macvtap "direct" connection in + "passthrough" mode to connect each guest to the network + (note that this is <i>not</i> the same thing as "PCI + passthrough"). The physical interface to be used will be + picked from among those listed + in <code><interface></code> subelements of + the <code><forward></code> 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).<span class="since">Since 0.9.4</span> + </dd> + </dl> + As mentioned above, a <code><forward></code> element can + have multiple <code><interface></code> subelements, each + one giving the name of a physical interface that can be used + for this network<span class="since">Since 0.9.4</span>: + <pre> +... + <forward mode='passthrough'> + <interface dev='eth10'/> + <interface dev='eth11'/> + <interface dev='eth12'/> + <interface dev='eth13'/> + <interface dev='eth14'/> + </forward> +... + </pre> + 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. + </dd> </dl> <h5><a name="elementQoS">Quality of service</a></h5> @@ -110,7 +246,6 @@ <inbound average='1000' peak='5000' burst='5120'/> <outbound average='128' peak='256' burst='256'/> </bandwidth></b> - <mac address='00:16:3E:5D:C7:9E'/> ...</pre> <p> @@ -134,13 +269,66 @@ <span class="since">Since 0.9.4</span> </p> + <h5><a name="elementsPortgroup">Portgroups</a></h5> + +<pre> +... + <forward mode='vepa'/> + <bridge name='br0'/> + <b><portgroup name='engineering' default='yes'> + <virtualport type='802.1Qbg'> + <parameters profileid='test'/> + </virtualport> + <bandwidth> + <inbound average='1000' peak='5000' burst='5120'/> + <outbound average='1000' peak='5000' burst='5120'/> + </bandwidth> + </portgroup></b> + <b><portgroup name='sales'> + <virtualport type='802.1Qbg'> + <parameters profileid='salestest'/> + </virtualport> + <bandwidth> + <inbound average='500' peak='2000' burst='2560'/> + <outbound average='128' peak='256' burst='256'/> + </bandwidth> + </portgroup></b> +...</pre> + + <p> + 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 <code><bandwidth></code> + and <code><virtualport></code>, which are both fully + described in the domain XML documentation. If a domain + interface definition specifies a portgroup (by adding + a <code>portgroup</code> attribute to + the <code><source></code> 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 <code>default='yes'</code>, 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 <code><bandwidth></code> + or <code><virtualport></code> specified directly in the + domain XML will take precedence over any setting in the chosen + portgroup. + </p> + <h3><a name="elementsAddress">Addressing</a></h3> <p> 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 <code>forward</code> element specified), and for those with + a forward mode of 'route' or 'nat'. </p> <pre> @@ -345,5 +533,55 @@ <ip family="ipv6" address="2001:8794:ca2:3::1" prefix="64" /> </network></pre> + <h3><a name="examplesBridge">Using an existing host bridge</a></h3> + + <p> + 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). + </p> + + <pre> + <network> + <name>host-bridge</name> + <forward mode="bridge"/> + <bridge name="br0"/> + </network></pre> + + <h3><a name="examplesDirect">Using a macvtap "direct" connection</a></h3> + + <p> + 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. + </p> + + <pre> + <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></pre> + </body> </html> -- 1.7.3.4