mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-10-30 01:43:23 +00:00
4b4a981d60
Introduce a virNetworkPortDefPtr struct to represent the data associated with a virtual network port. Add APIs for parsing/formatting XML docs with the data. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
213 lines
7.0 KiB
XML
213 lines
7.0 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html>
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<body>
|
|
<h1>Network XML format</h1>
|
|
|
|
<ul id="toc">
|
|
</ul>
|
|
|
|
<p>
|
|
This page provides an introduction to the network port XML format.
|
|
This stores information about the connection between an virtual
|
|
interface on a virtual domain's, and the virtual network it is
|
|
attached to.
|
|
</p>
|
|
|
|
<h2><a id="elements">Element and attribute overview</a></h2>
|
|
|
|
<p>
|
|
The root element required for all virtual network ports is
|
|
named <code>networkport</code> and has no configurable attributes
|
|
The network port XML format is available <span class="since">since
|
|
5.5.0</span>
|
|
</p>
|
|
|
|
<h3><a id="elementsMetadata">General metadata</a></h3>
|
|
|
|
<p>
|
|
The first elements provide basic metadata about the virtual
|
|
network port.
|
|
</p>
|
|
|
|
<pre>
|
|
<networkport
|
|
<uuid>7ae63b5f-fe96-4af0-a7c3-da04ba1b3f54</uuid>
|
|
<owner>
|
|
<uuid>06578fc1-c686-46fa-bc2c-220893b466a6</uuid>
|
|
<name>myguest<name>
|
|
</owner>
|
|
<group>webfront<group>
|
|
<mac address='52:54:0:7b:35:93'/>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>uuid</code></dt>
|
|
<dd>The content of the <code>uuid</code> element provides
|
|
a globally unique identifier for the virtual network port.
|
|
The format must be RFC 4122 compliant, eg <code>3e3fce45-4f53-4fa7-bb32-11f34168b82b</code>.
|
|
If omitted when defining/creating a new network port, a random
|
|
UUID is generated.</dd>
|
|
<dd>The <code>owner</code> node records the domain object that
|
|
is the owner of the network port. It contains two child nodes:
|
|
<dl>
|
|
<dt><code>uuid</code></dt>
|
|
<dd>The content of the <code>uuid</code> element provides
|
|
a globally unique identifier for the virtual domain.</dd>
|
|
<dt><code>name</code></dt>
|
|
<dd>The unique name of the virtual domain</dd>
|
|
</dl>
|
|
</dd>
|
|
<dt><code>group</code></dt>
|
|
<dd>The port group in the virtual network to which the
|
|
port belongs. Can be omitted if no port groups are
|
|
defined on the network.</dd>
|
|
<dt><code>mac</code></dt>
|
|
<dd>The <code>address</code> attribute provides the MAC
|
|
address of the virtual port that will be see by the
|
|
guest. The MAC address must not start with 0xFE as this
|
|
byte is reserved for use on the host side of the port.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3><a id="elementsCommon">Common elements</a></h3>
|
|
|
|
<p>
|
|
The following elements are common to one of more of the plug
|
|
types listed later
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<bandwidth>
|
|
<inbound average='1000' peak='5000' floor='200' burst='1024'/>
|
|
<outbound average='128' peak='256' burst='256'/>
|
|
</bandwidth>
|
|
<rxfilters trustGuest='yes'/>
|
|
<virtualport type='802.1Qbg'>
|
|
<parameters managerid='11' typeid='1193047' typeidversion='2'/>
|
|
</virtualport>
|
|
...</pre>
|
|
|
|
<dl>
|
|
<dt><code>bandwidth</code></dt>
|
|
<dd>This part of the network port XML provides setting quality of service.
|
|
Incoming and outgoing traffic can be shaped independently.
|
|
The <code>bandwidth</code> element and its child elements are described
|
|
in the <a href="formatnetwork.html#elementQoS">QoS</a> section of
|
|
the Network XML. In addition the <code>classID</code> attribute may
|
|
exist provide the ID of the traffic shaping class that is active.
|
|
</dd>
|
|
<dt><code>rxfilters</code></dt>
|
|
<dd>The <code>rxfilters</code> element property
|
|
<code>trustGuest</code> provides the
|
|
capability for the host to detect and trust reports from the
|
|
guest regarding changes to the interface mac address and receive
|
|
filters by setting the attribute to <code>yes</code>. The default
|
|
setting for the attribute is <code>no</code> for security
|
|
reasons and support depends on the guest network device model as
|
|
well as the type of connection on the host - currently it is
|
|
only supported for the virtio device model and for macvtap
|
|
connections on the host.
|
|
</dd>
|
|
<dt><code>virtualport</code></dt>
|
|
<dd>The <code>virtualport</code> element describes metadata that
|
|
needs to be provided to the underlying network subsystem. It
|
|
is described in the domain XML
|
|
<a href="formatdomain.html#elementsNICS">interface documentation</a>.
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
<h3><a id="elementsPlug">Plugs</a></h3>
|
|
|
|
<p>
|
|
The <code>plug</code> element has varying content depending
|
|
on the value of the <code>type</code> attribute.
|
|
</p>
|
|
|
|
<h4><a id="elementsPlugNetwork">Network</a></h4>
|
|
|
|
<p>
|
|
The <code>network</code> plug type refers to a managed virtual
|
|
network plug that is based on a traditional software bridge
|
|
device privately managed by libvirt.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<plug type='network' bridge='virbr0'>
|
|
...</pre>
|
|
|
|
<p>
|
|
The <code>bridge</code> attribute provides the name of the
|
|
privately managed bridge device associated with the virtual
|
|
network.
|
|
</p>
|
|
|
|
<h4><a id="elementsPlugNetwork">Bridge</a></h4>
|
|
|
|
<p>
|
|
The <code>bridge</code> plug type refers to an externally
|
|
managed traditional software bridge.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<plug type='bridge' bridge='br2'>
|
|
...</pre>
|
|
|
|
<p>
|
|
The <code>bridge</code> attribute provides the name of the
|
|
externally managed bridge device associated with the virtual
|
|
network.
|
|
</p>
|
|
|
|
<h4><a id="elementsPlugNetwork">Direct</a></h4>
|
|
|
|
<p>
|
|
The <code>direct</code> plug type refers to a connection
|
|
directly to a physical network interface.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<plug type='direct' dev='ens3' mode='vepa'/>
|
|
...</pre>
|
|
|
|
<p>
|
|
The <code>dev</code> attribute provides the name of the
|
|
physical network interface to which the port will be
|
|
connected. The <code>mode</code> attribute describes
|
|
how the connection will be setup and takes the same
|
|
values described in the
|
|
<a href="formatdomain.html#elementsNICSDirect">domain XML</a>.
|
|
</p>
|
|
|
|
<h4><a id="elementsPlugNetwork">Host PCI</a></h4>
|
|
|
|
<p>
|
|
The <code>hostdev-pci</code> plug type refers to the
|
|
passthrough of a physical PCI device rather than emulation.
|
|
</p>
|
|
|
|
<pre>
|
|
...
|
|
<plug type='hostdev-pci' managed='yes'>
|
|
<driver name='vfio'/>
|
|
<address domain='0x0001' bus='0x02' slot='0x03' function='0x4'/>
|
|
</plug>
|
|
...</pre>
|
|
|
|
<p>
|
|
The <code>managed</code> attribute indicates who is responsible for
|
|
managing the PCI device in the host. When set to the value <code>yes</code>
|
|
libvirt is responsible for automatically detaching the device from host
|
|
drivers and resetting it if needed. If the value is <code>no</code>,
|
|
some other party must ensure the device is not attached to any
|
|
host drivers.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|