From nobody Mon Feb 9 17:06:32 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1648469514; cv=none; d=zohomail.com; s=zohoarc; b=ZAY0YDbzY/xlbMReOBC6bY4xitB/xzZ+qlUk/bGkXJ7LoWfpnGV5Fv/WI/pYFEIe6ZA3tfuTFyX0BB5KtnljI5kzOlXh/MdFo8jDEgIJNXIBtI3Ap5kgKgHpn8/wl1kO+xorrT4ccjtIFoogCRDNlton0RuACrVdRr4WKgT3xb0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1648469514; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Inm5ZCzMy8MaSIaI8+kPz+AtXcV8h5TysO4/01HyY3Q=; b=Ld6zcGR4fRP8+wLVBJTdHhDVsJrBia5y9U1+ekDzsmm8miqEtVsTeMUcF2tNmjdk3qw9D0KnI09cNALrdL8ykW8WIlvhdOay9cVjPiyEjnciklRxwvHtqXvZ/t3SuKgirYqNzbLLbsElrIcmIN8cdLrHIc/2g/I+5qAefQixKhg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1648469514364410.70638685984466; Mon, 28 Mar 2022 05:11:54 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-645-X_zvgoYMPLOlILlanO9BPA-1; Mon, 28 Mar 2022 08:11:11 -0400 Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.rdu2.redhat.com [10.11.54.10]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id D3F7B801E80; Mon, 28 Mar 2022 12:11:08 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id B882A401E9E; Mon, 28 Mar 2022 12:11:08 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id B468C193F6E1; Mon, 28 Mar 2022 12:11:07 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id EB4CA1949762 for ; Mon, 28 Mar 2022 12:11:05 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id DD7981402642; Mon, 28 Mar 2022 12:11:05 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 1E83C141DC28 for ; Mon, 28 Mar 2022 12:11:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1648469513; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=Inm5ZCzMy8MaSIaI8+kPz+AtXcV8h5TysO4/01HyY3Q=; b=W9DmfFopXUuUnMT5yE3TxFiGkk5DTcslBI9L8m53nwqDYUDvqdOfQZhZsioDUZa2WSSIl/ LPvWzz4u0jIpkZIEJMeDjl6ZajD6oFqyZKe4wW9venhm6Btl3Z/m7qb8Ff7tI9zyvkOvYB bPF1RrWz+nibGiQCb9umRMGDgByE8Xw= X-MC-Unique: X_zvgoYMPLOlILlanO9BPA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 19/29] docs: Convert 'formatnetworkport' to rST Date: Mon, 28 Mar 2022 14:10:34 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.85 on 10.11.54.10 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1648469514732100001 Content-Type: text/plain; charset="utf-8"; x-default="true" Signed-off-by: Peter Krempa --- 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=3D'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=3D'1000' peak=3D'5000' floor=3D'200' burst=3D'1024=
'/>
-    <outbound average=3D'128' peak=3D'256' burst=3D'256'/>
-  </bandwidth>
-  <rxfilters trustGuest=3D'yes'/>
-  <port isolated=3D'yes'/>
-  <virtualport type=3D'802.1Qbg'>
-    <parameters managerid=3D'11' typeid=3D'1193047' typeidversion=3D'2'=
/>
-  </virtualport>
-  ...
- -
-
bandwidth
-
This part of the network port XML provides setting quality of se= rvice. - Incoming and outgoing traffic can be shaped independently. - The bandwidth element and its child elements are desc= ribed - 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 activ= e. -
-
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=3D'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=3D'network' bridge=3D'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=3D'bridge' bridge=3D'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=3D'direct' dev=3D'ens3' mode=3D'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=3D'hostdev-pci' managed=3D'yes'>
-    <driver name=3D'vfio'/>
-    <address domain=3D'0x0001' bus=3D'0x02' slot=3D'0x03' function=3D'0=
x4'/>
-  </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 h= ost - 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 + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Network XML format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +This page provides an introduction to the network port XML format. This st= ores +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 ``network= port`` +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 identifi= er for + the virtual network port. The format must be RFC 4122 compliant, eg + ``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/crea= ting a + new network port, a random UUID is generated. + The ``owner`` node records the domain object that is the owner of the n= etwork + port. It contains two child nodes: + + ``uuid`` + The content of the ``uuid`` element provides a globally unique ident= ifier + 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 t= his + 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 ``bandwi= dth`` + 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 t= raffic + shaping class that is active. +``rxfilters`` + The ``rxfilters`` element property ``trustGuest`` provides the capabili= ty for + the host to detect and trust reports from the guest regarding changes t= o the + interface mac address and receive filters by setting the attribute to + ``yes``. The default setting for the attribute is ``no`` for security r= easons + and support depends on the guest network device model as well as the ty= pe 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 netw= ork + traffic from other ports on the same network that also have + ````. This setting is only supported for emulat= ed + network devices connected to a Linux host bridge via a standard tap dev= ice. +``virtualport`` + The ``virtualport`` element describes metadata that needs to be provide= d 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 ``t= ype`` +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 softw= are +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 net= work +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 f= or +automatically detaching the device from host drivers and resetting it if n= eeded. +If the value is ``no``, some other party must ensure the device is not att= ached +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 =3D [ 'dbus', 'docs', 'formatnetwork', - 'formatnetworkport', 'formatnode', 'formatnwfilter', 'formatstoragecaps', @@ -85,6 +84,7 @@ docs_rst_files =3D [ 'formatcheckpoint', 'formatdomain', 'formatdomaincaps', + 'formatnetworkport', 'formatsecret', 'formatsnapshot', 'formatstorage', --=20 2.35.1