mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-08-04 07:53:50 +00:00
docs: Convert 'formatnetworkport' to rST
Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Erik Skultety <eskultet@redhat.com>
This commit is contained in:
parent
63b12805f2
commit
8ebafe5178
@ -1,223 +0,0 @@
|
|||||||
<?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 a virtual
|
|
||||||
interface of a virtual domain, 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 or 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'/>
|
|
||||||
<port isolated='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 to 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>port</code></dt>
|
|
||||||
<dd> <span class="since">Since 6.1.0.</span>
|
|
||||||
The <code>port</code> element property
|
|
||||||
<code>isolated</code>, when set to <code>yes</code> (default
|
|
||||||
setting is <code>no</code>) is used to isolate this port's
|
|
||||||
network traffic from other ports on the same network that also
|
|
||||||
have <code><port isolated='yes'/></code>. This setting
|
|
||||||
is only supported for emulated network devices connected to a
|
|
||||||
Linux host bridge via a standard tap device.
|
|
||||||
</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>
|
|
175
docs/formatnetworkport.rst
Normal file
175
docs/formatnetworkport.rst
Normal file
@ -0,0 +1,175 @@
|
|||||||
|
.. role:: since
|
||||||
|
|
||||||
|
==================
|
||||||
|
Network XML format
|
||||||
|
==================
|
||||||
|
|
||||||
|
.. contents::
|
||||||
|
|
||||||
|
This page provides an introduction to the network port XML format. This stores
|
||||||
|
information about the connection between a virtual interface of a virtual
|
||||||
|
domain, and the virtual network it is attached to.
|
||||||
|
|
||||||
|
Element and attribute overview
|
||||||
|
------------------------------
|
||||||
|
|
||||||
|
The root element required for all virtual network ports is named ``networkport``
|
||||||
|
and has no configurable attributes The network port XML format is available
|
||||||
|
:since:`since 5.5.0`
|
||||||
|
|
||||||
|
General metadata
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The first elements provide basic metadata about the virtual network port.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
<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'/>
|
||||||
|
...
|
||||||
|
|
||||||
|
``uuid``
|
||||||
|
The content of the ``uuid`` element provides a globally unique identifier for
|
||||||
|
the virtual network port. The format must be RFC 4122 compliant, eg
|
||||||
|
``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/creating a
|
||||||
|
new network port, a random UUID is generated.
|
||||||
|
The ``owner`` node records the domain object that is the owner of the network
|
||||||
|
port. It contains two child nodes:
|
||||||
|
|
||||||
|
``uuid``
|
||||||
|
The content of the ``uuid`` element provides a globally unique identifier
|
||||||
|
for the virtual domain.
|
||||||
|
``name``
|
||||||
|
The unique name of the virtual domain
|
||||||
|
``group``
|
||||||
|
The port group in the virtual network to which the port belongs. Can be
|
||||||
|
omitted if no port groups are defined on the network.
|
||||||
|
``mac``
|
||||||
|
The ``address`` 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.
|
||||||
|
|
||||||
|
Common elements
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The following elements are common to one or more of the plug types listed later
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
...
|
||||||
|
<bandwidth>
|
||||||
|
<inbound average='1000' peak='5000' floor='200' burst='1024'/>
|
||||||
|
<outbound average='128' peak='256' burst='256'/>
|
||||||
|
</bandwidth>
|
||||||
|
<rxfilters trustGuest='yes'/>
|
||||||
|
<port isolated='yes'/>
|
||||||
|
<virtualport type='802.1Qbg'>
|
||||||
|
<parameters managerid='11' typeid='1193047' typeidversion='2'/>
|
||||||
|
</virtualport>
|
||||||
|
...
|
||||||
|
|
||||||
|
``bandwidth``
|
||||||
|
This part of the network port XML provides setting quality of service.
|
||||||
|
Incoming and outgoing traffic can be shaped independently. The ``bandwidth``
|
||||||
|
element and its child elements are described in the
|
||||||
|
`QoS <formatnetwork.html#elementQoS>`__ section of the Network XML. In
|
||||||
|
addition the ``classID`` attribute may exist to provide the ID of the traffic
|
||||||
|
shaping class that is active.
|
||||||
|
``rxfilters``
|
||||||
|
The ``rxfilters`` element property ``trustGuest`` 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
|
||||||
|
``yes``. The default setting for the attribute is ``no`` 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.
|
||||||
|
``port``
|
||||||
|
:since:`Since 6.1.0.` The ``port`` element property ``isolated``, when set to
|
||||||
|
``yes`` (default setting is ``no``) is used to isolate this port's network
|
||||||
|
traffic from other ports on the same network that also have
|
||||||
|
``<port isolated='yes'/>``. This setting is only supported for emulated
|
||||||
|
network devices connected to a Linux host bridge via a standard tap device.
|
||||||
|
``virtualport``
|
||||||
|
The ``virtualport`` element describes metadata that needs to be provided to
|
||||||
|
the underlying network subsystem. It is described in the domain XML
|
||||||
|
`interface documentation <formatdomain.html#elementsNICS>`__.
|
||||||
|
|
||||||
|
Plugs
|
||||||
|
~~~~~
|
||||||
|
|
||||||
|
The ``plug`` element has varying content depending on the value of the ``type``
|
||||||
|
attribute.
|
||||||
|
|
||||||
|
Network
|
||||||
|
^^^^^^^
|
||||||
|
|
||||||
|
The ``network`` plug type refers to a managed virtual network plug that is based
|
||||||
|
on a traditional software bridge device privately managed by libvirt.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
...
|
||||||
|
<plug type='network' bridge='virbr0'/>
|
||||||
|
...
|
||||||
|
|
||||||
|
The ``bridge`` attribute provides the name of the privately managed bridge
|
||||||
|
device associated with the virtual network.
|
||||||
|
|
||||||
|
Bridge
|
||||||
|
^^^^^^
|
||||||
|
|
||||||
|
The ``bridge`` plug type refers to an externally managed traditional software
|
||||||
|
bridge.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
...
|
||||||
|
<plug type='bridge' bridge='br2'/>
|
||||||
|
...
|
||||||
|
|
||||||
|
The ``bridge`` attribute provides the name of the externally managed bridge
|
||||||
|
device associated with the virtual network.
|
||||||
|
|
||||||
|
Direct
|
||||||
|
^^^^^^
|
||||||
|
|
||||||
|
The ``direct`` plug type refers to a connection directly to a physical network
|
||||||
|
interface.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
...
|
||||||
|
<plug type='direct' dev='ens3' mode='vepa'/>
|
||||||
|
...
|
||||||
|
|
||||||
|
The ``dev`` attribute provides the name of the physical network interface to
|
||||||
|
which the port will be connected. The ``mode`` attribute describes how the
|
||||||
|
connection will be setup and takes the same values described in the `domain
|
||||||
|
XML <formatdomain.html#elementsNICSDirect>`__.
|
||||||
|
|
||||||
|
Host PCI
|
||||||
|
^^^^^^^^
|
||||||
|
|
||||||
|
The ``hostdev-pci`` plug type refers to the passthrough of a physical PCI device
|
||||||
|
rather than emulation.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
...
|
||||||
|
<plug type='hostdev-pci' managed='yes'>
|
||||||
|
<driver name='vfio'/>
|
||||||
|
<address domain='0x0001' bus='0x02' slot='0x03' function='0x4'/>
|
||||||
|
</plug>
|
||||||
|
...
|
||||||
|
|
||||||
|
The ``managed`` attribute indicates who is responsible for managing the PCI
|
||||||
|
device in the host. When set to the value ``yes`` libvirt is responsible for
|
||||||
|
automatically detaching the device from host drivers and resetting it if needed.
|
||||||
|
If the value is ``no``, some other party must ensure the device is not attached
|
||||||
|
to any host drivers.
|
@ -25,7 +25,6 @@ docs_html_in_files = [
|
|||||||
'formatcaps',
|
'formatcaps',
|
||||||
'formatdomaincaps',
|
'formatdomaincaps',
|
||||||
'formatnetwork',
|
'formatnetwork',
|
||||||
'formatnetworkport',
|
|
||||||
'formatnode',
|
'formatnode',
|
||||||
'formatnwfilter',
|
'formatnwfilter',
|
||||||
'formatstoragecaps',
|
'formatstoragecaps',
|
||||||
@ -85,6 +84,7 @@ docs_rst_files = [
|
|||||||
'formatbackup',
|
'formatbackup',
|
||||||
'formatcheckpoint',
|
'formatcheckpoint',
|
||||||
'formatdomain',
|
'formatdomain',
|
||||||
|
'formatnetworkport',
|
||||||
'formatsecret',
|
'formatsecret',
|
||||||
'formatsnapshot',
|
'formatsnapshot',
|
||||||
'formatstorage',
|
'formatstorage',
|
||||||
|
Loading…
Reference in New Issue
Block a user