12:45 a.m.
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