mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 13:45:38 +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:
Peter Krempa
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',
|
||||
'formatdomaincaps',
|
||||
'formatnetwork',
|
||||
'formatnetworkport',
|
||||
'formatnode',
|
||||
'formatnwfilter',
|
||||
'formatstoragecaps',
|
||||
@ -85,6 +84,7 @@ docs_rst_files = [
|
||||
'formatbackup',
|
||||
'formatcheckpoint',
|
||||
'formatdomain',
|
||||
'formatnetworkport',
|
||||
'formatsecret',
|
||||
'formatsnapshot',
|
||||
'formatstorage',
|
||||
|
||||
Loading…
Reference in New Issue
Block a user