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> -<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
