mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2025-01-08 22:15:21 +00:00
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 <network> XML to support libvirt networks that use existing host bridges and macvtap direct connections, as well as the new <portgroup> element.
This commit is contained in:
Laine Stump
parent
ed009313b1
commit
073ef15c87
@ -70,36 +70,172 @@
|
|||||||
bridge device allowing them to talk to each other. The bridge device
|
bridge device allowing them to talk to each other. The bridge device
|
||||||
may also be connected to the LAN. It is recommended that bridge
|
may also be connected to the LAN. It is recommended that bridge
|
||||||
device names started with the prefix <code>vir</code>, but the name
|
device names started with the prefix <code>vir</code>, but the name
|
||||||
<code>virbr0</code> is reserved for the "default" virtual network.
|
<code>virbr0</code> is reserved for the "default" virtual
|
||||||
This element should always be provided when defining a new network.
|
network. This element should always be provided when defining
|
||||||
Attribute <code>stp</code> specifies if Spanning Tree Protocol is
|
a new network with a <code><forward></code> mode of
|
||||||
'on' or 'off' (default is 'on'). Attribute <code>delay</code> sets
|
"nat" or "route" (or an isolated network with
|
||||||
the bridge's forward delay value in seconds (default is 0).
|
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>
|
<span class="since">Since 0.3.0</span>
|
||||||
</dd>
|
</dd>
|
||||||
<dt><code>domain</code></dt>
|
<dt><code>domain</code></dt>
|
||||||
<dd>
|
<dd>
|
||||||
The <code>name</code> attribute on the <code>domain</code> element
|
The <code>name</code> attribute on the <code>domain</code>
|
||||||
defines the DNS domain of the DHCP server. This element is optional.
|
element defines the DNS domain of the DHCP server. This
|
||||||
<span class="since">Since 0.4.5</span>
|
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>
|
</dd>
|
||||||
<dt><code>forward</code></dt>
|
<dt><code>forward</code></dt>
|
||||||
<dd>Inclusion of the <code>forward</code> element indicates that
|
<dd>Inclusion of the <code>forward</code> element indicates that
|
||||||
the virtual network is to be connected to the physical
|
the virtual network is to be connected to the physical
|
||||||
LAN. the <code>mode</code> attribute determines the method of
|
LAN.<span class="since">Since 0.3.0.</span>
|
||||||
forwarding; possible selections are 'nat' and 'route'. If mode
|
The <code>mode</code> attribute determines the method of
|
||||||
is not specified, NAT forwarding will be used for
|
forwarding. If there is no <code>forward</code> element, the
|
||||||
connectivity. If a network has any IPv6 addresses defined,
|
network will be isolated from any other network (unless a
|
||||||
even if <code>mode</code> is given as 'nat', the IPv6 traffic
|
guest connected to that network is acting as a router, of
|
||||||
will be forwarded using routing, since IPv6 has no concept of NAT.
|
course). The following are valid settings
|
||||||
Firewall rules will allow forwarding to any other network device whether
|
for <code>mode</code> (if there is a <code>forward</code>
|
||||||
ethernet, wireless, dialup, or VPN. If the <code>dev</code> attribute
|
element but mode is not specified, <code>mode='nat'</code> is
|
||||||
is set, the firewall rules will restrict forwarding to the named
|
assumed):
|
||||||
device only. If the <code>mode</code> attribute is set to <code>route</code>
|
<dl>
|
||||||
then the traffic will not have NAT applied. This presumes that the
|
<dt><code>nat</code></dt>
|
||||||
local LAN router has suitable routing table entries to return traffic
|
<dd>
|
||||||
to this host. <span class="since">Since 0.3.0; 'mode' attribute since
|
All traffic between guests connected to this network and
|
||||||
0.4.2</span></dd>
|
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>
|
</dl>
|
||||||
<h5><a name="elementQoS">Quality of service</a></h5>
|
<h5><a name="elementQoS">Quality of service</a></h5>
|
||||||
|
|
||||||
@ -110,7 +246,6 @@
|
|||||||
<inbound average='1000' peak='5000' burst='5120'/>
|
<inbound average='1000' peak='5000' burst='5120'/>
|
||||||
<outbound average='128' peak='256' burst='256'/>
|
<outbound average='128' peak='256' burst='256'/>
|
||||||
</bandwidth></b>
|
</bandwidth></b>
|
||||||
<mac address='00:16:3E:5D:C7:9E'/>
|
|
||||||
...</pre>
|
...</pre>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
@ -134,13 +269,72 @@
|
|||||||
<span class="since">Since 0.9.4</span>
|
<span class="since">Since 0.9.4</span>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
<h5><a name="elementsPortgroup">Portgroups</a></h5>
|
||||||
|
|
||||||
|
<pre>
|
||||||
|
...
|
||||||
|
<forward mode='private'/>
|
||||||
|
<interface dev="eth20"/>
|
||||||
|
<interface dev="eth21"/>
|
||||||
|
<interface dev="eth22"/>
|
||||||
|
<interface dev="eth23"/>
|
||||||
|
<interface dev="eth24"/>
|
||||||
|
</forward>
|
||||||
|
<b><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></b>
|
||||||
|
<b><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></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>
|
||||||
|
(documented <a href="formatdomain.html#elementQoS">here</a>)
|
||||||
|
and <code><virtualport></code>
|
||||||
|
(documented <a href="formatdomain.html#elementsNICSDirect">here</a>).
|
||||||
|
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>
|
<h3><a name="elementsAddress">Addressing</a></h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
The final set of elements define the addresses (IPv4 and/or
|
The final set of elements define the addresses (IPv4 and/or
|
||||||
IPv6, as well as MAC) to be assigned to the bridge device
|
IPv6, as well as MAC) to be assigned to the bridge device
|
||||||
associated with the virtual network, and optionally enable DHCP
|
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>
|
</p>
|
||||||
|
|
||||||
<pre>
|
<pre>
|
||||||
@ -345,5 +539,55 @@
|
|||||||
<ip family="ipv6" address="2001:8794:ca2:3::1" prefix="64" />
|
<ip family="ipv6" address="2001:8794:ca2:3::1" prefix="64" />
|
||||||
</network></pre>
|
</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>
|
</body>
|
||||||
</html>
|
</html>
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user