[PATCH 19/29] docs: Convert 'formatnetworkport' to rST
Peter Krempa
pkrempa at redhat.com
Mon Mar 28 12:10:34 UTC 2022
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/formatnetworkport.html.in | 223 ---------------------------------
docs/formatnetworkport.rst | 175 ++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 176 insertions(+), 224 deletions(-)
delete mode 100644 docs/formatnetworkport.html.in
create mode 100644 docs/formatnetworkport.rst
diff --git a/docs/formatnetworkport.html.in b/docs/formatnetworkport.html.in
deleted file mode 100644
index 2d41552618..0000000000
--- a/docs/formatnetworkport.html.in
+++ /dev/null
@@ -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>
diff --git a/docs/formatnetworkport.rst b/docs/formatnetworkport.rst
new file mode 100644
index 0000000000..a85888907d
--- /dev/null
+++ b/docs/formatnetworkport.rst
@@ -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.
diff --git a/docs/meson.build b/docs/meson.build
index 81f348398d..bb1359aacd 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -23,7 +23,6 @@ docs_html_in_files = [
'dbus',
'docs',
'formatnetwork',
- 'formatnetworkport',
'formatnode',
'formatnwfilter',
'formatstoragecaps',
@@ -85,6 +84,7 @@ docs_rst_files = [
'formatcheckpoint',
'formatdomain',
'formatdomaincaps',
+ 'formatnetworkport',
'formatsecret',
'formatsnapshot',
'formatstorage',
--
2.35.1
More information about the libvir-list
mailing list