[PATCH 19/29] docs: Convert 'formatnetworkport' to rST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
 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>
-&lt;networkport&gt;
-  &lt;uuid&gt;7ae63b5f-fe96-4af0-a7c3-da04ba1b3f54&lt;/uuid&gt;
-  &lt;owner&gt;
-    &lt;uuid&gt;06578fc1-c686-46fa-bc2c-220893b466a6&lt;/uuid&gt;
-    &lt;name&gt;myguest&lt;/name&gt;
-  &lt;/owner&gt;
-  &lt;group&gt;webfront&lt;/group&gt;
-  &lt;mac address='52:54:0:7b:35:93'/&gt;
-  ...</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>
-  ...
-  &lt;bandwidth&gt;
-    &lt;inbound average='1000' peak='5000' floor='200' burst='1024'/&gt;
-    &lt;outbound average='128' peak='256' burst='256'/&gt;
-  &lt;/bandwidth&gt;
-  &lt;rxfilters trustGuest='yes'/&gt;
-  &lt;port isolated='yes'/&gt;
-  &lt;virtualport type='802.1Qbg'&gt;
-    &lt;parameters managerid='11' typeid='1193047' typeidversion='2'/&gt;
-  &lt;/virtualport&gt;
-  ...</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>&lt;port isolated='yes'/&gt;</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>
-  ...
-  &lt;plug type='network' bridge='virbr0'/&gt;
-  ...</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>
-  ...
-  &lt;plug type='bridge' bridge='br2'/&gt;
-  ...</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>
-  ...
-  &lt;plug type='direct' dev='ens3' mode='vepa'/&gt;
-  ...</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>
-  ...
-  &lt;plug type='hostdev-pci' managed='yes'&gt;
-    &lt;driver name='vfio'/&gt;
-    &lt;address domain='0x0001' bus='0x02' slot='0x03' function='0x4'/&gt;
-  &lt;/plug&gt;
-  ...</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




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux