From 8ebafe51785c2919b0c8b9c1b2cba7c890cd1163 Mon Sep 17 00:00:00 2001 From: Peter Krempa Date: Thu, 10 Mar 2022 17:57:53 +0100 Subject: [PATCH] docs: Convert 'formatnetworkport' to rST Signed-off-by: Peter Krempa Reviewed-by: Erik Skultety --- 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 @@ - - - - -

Network XML format

- -
    -
- -

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

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

- -

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/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. + +:: + + + 7ae63b5f-fe96-4af0-a7c3-da04ba1b3f54 + + 06578fc1-c686-46fa-bc2c-220893b466a6 + myguest + + webfront + + ... + +``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`` + 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 `__ 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 + ````. 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 `__. + +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. + +:: + + ... + + ... + +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. + +:: + + ... + + ... + +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. + +:: + + ... + + ... + +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 `__. + +Host PCI +^^^^^^^^ + +The ``hostdev-pci`` plug type refers to the passthrough of a physical PCI device +rather than emulation. + +:: + + ... + + +
+ + ... + +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 acc455c7c7..e0e6bb99ff 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -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',