From nobody Mon Feb 9 19:05:35 2026 Delivered-To: importer@patchew.org Received-SPF: none (zohomail.com: 8.43.85.245 is neither permitted nor denied by domain of lists.libvirt.org) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; spf=none (zohomail.com: 8.43.85.245 is neither permitted nor denied by domain of lists.libvirt.org) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 1708423673089844.8124362355784; Tue, 20 Feb 2024 02:07:53 -0800 (PST) Received: by lists.libvirt.org (Postfix, from userid 996) id 038D6445; Tue, 20 Feb 2024 05:07:52 -0500 (EST) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id 872111DBE; Tue, 20 Feb 2024 04:43:46 -0500 (EST) Received: by lists.libvirt.org (Postfix, from userid 996) id 12C371B10; Tue, 20 Feb 2024 04:41:56 -0500 (EST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id 1E6A01B10 for ; Tue, 20 Feb 2024 04:41:45 -0500 (EST) Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-424-uaYAe4NLOIewkPTXUVGwwg-1; Tue, 20 Feb 2024 04:41:43 -0500 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id C87391C54069 for ; Tue, 20 Feb 2024 09:41:42 +0000 (UTC) Received: from harajuku.usersys.redhat.com.homenet.telecomitalia.it (unknown [10.45.224.52]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 601AB107BE for ; Tue, 20 Feb 2024 09:41:42 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.4 X-MC-Unique: uaYAe4NLOIewkPTXUVGwwg-1 From: Andrea Bolognani To: devel@lists.libvirt.org Subject: [PATCH 7/9] docs: Rewrite a few awkward sections Date: Tue, 20 Feb 2024 10:41:33 +0100 Message-ID: <20240220094135.359112-8-abologna@redhat.com> In-Reply-To: <20240220094135.359112-1-abologna@redhat.com> References: <20240220094135.359112-1-abologna@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.5 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Message-ID-Hash: FUTXHYXYKKPVWAT5IFNLHNYTG5QNEEM4 X-Message-ID-Hash: FUTXHYXYKKPVWAT5IFNLHNYTG5QNEEM4 X-MailFrom: abologna@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: Content-Type: text/plain; charset="utf-8"; x-default="true" Content-Transfer-Encoding: quoted-printable X-ZM-MESSAGEID: 1708423674252100001 Address several oddities, and bring them in line with the style used for the vast majority of our documentation. In a couple of cases, some of the possible values for an attribute were listed with :since: information matching that off the attribute itself, making it redundant. Signed-off-by: Andrea Bolognani --- docs/formatdomain.rst | 71 ++++++++++++++++++++++------------------- docs/formatnetwork.rst | 20 ++++++------ docs/formatnwfilter.rst | 19 +++++------ 3 files changed, 58 insertions(+), 52 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index da6a920089..2f9ee1110a 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -50,9 +50,10 @@ General metadata The content of the ``uuid`` element provides a globally unique identifi= er for the virtual machine. The format must be RFC 4122 compliant, eg ``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/crea= ting a - new machine, a random UUID is generated. It is also possible to provide= the - UUID via a `SMBIOS System Information`_ specification. :since:`Since 0.= 0.1, - sysinfo since 0.8.7` + new machine, a random UUID is generated. :since:`Since 0.0.1` + + :since:`Since 0.8.7`, it is also possible to provide the UUID via a + `SMBIOS System Information`_ specification. ``genid`` :since:`Since 4.4.0` , the ``genid`` element can be used to add a Virtu= al Machine Generation ID which exposes a 128-bit, cryptographically random, @@ -338,8 +339,8 @@ them in production. This element has attribute ``useserial`` with possible values ``yes`` or ``no``. It enables or disables Serial Graphics Adapter which allows use= rs to see BIOS messages on a serial port. Therefore, one needs to have `Seria= l port`_ - defined. :since:`Since 0.9.4` . :since:`Since - 0.10.2 (QEMU only)` there is another attribute, ``rebootTimeout`` that + defined. :since:`Since 0.9.4`. + The ``rebootTimeout`` attribute (:since:`since 0.10.2 (QEMU only)`) controls whether and after how long the guest should start booting agai= n in case the boot fails (according to BIOS). The value is in milliseconds w= ith maximum of ``65535`` and special value ``-1`` disables the reboot. @@ -3285,20 +3286,23 @@ paravirtualized driver is specified via the ``disk`= ` element. "qcow2", and "qed". - The optional ``cache`` attribute controls the cache mechanism, possi= ble values are "default", "none", "writethrough", "writeback", "directsy= nc" - (like "writethrough", but it bypasses the host page cache) and "unsa= fe" - (host may cache all disk io, and sync requests from guest are ignore= d). - :since:`Since 0.6.0, "directsync" since 0.9.5, "unsafe" since 0.9.7` + (:since:`since 0.9.5`; like "writethrough", but it bypasses the host= page + cache) and "unsafe" (:since:`since 0.9.7`; host may cache all disk i= o, + and sync requests from guest are ignored). + :since:`Since 0.6.0` - The optional ``error_policy`` attribute controls how the hypervisor = will behave on a disk read or write error, possible values are "stop", - "report", "ignore", and "enospace". :since:`Since 0.8.0, "report" si= nce - 0.9.7` The default is left to the discretion of the hypervisor. Ther= e is - also an optional ``rerror_policy`` that controls behavior for read e= rrors - only. :since:`Since 0.9.7` . If no rerror_policy is given, error_pol= icy is + "report" (:since:`since 0.9.7`), "ignore", and "enospace". + The default is left to the discretion of the hypervisor. + :since:`Since 0.8.0`. + - The optional ``rerror_policy`` attribute controls behavior for read + errors only. If no rerror_policy is given, error_policy is used for both read and write errors. If rerror_policy is given, it overrides the ``error_policy`` for read errors. Also note that "enos= pace" is not a valid policy for read errors, so if ``error_policy`` is set= to "enospace" and no ``rerror_policy`` is given, the read error policy = will be left at its default. + :since:`Since 0.9.7` - The optional ``io`` attribute controls specific policies on I/O; qemu guests support "threads" and "native" :since:`Since 0.8.8` , io_uring :since:`Since 6.3.0 (QEMU 5.0)` . @@ -4253,9 +4257,9 @@ Host device assignment USB / PCI / SCSI devices ^^^^^^^^^^^^^^^^^^^^^^^^ =20 -USB, PCI and SCSI devices attached to the host can be passed through to the -guest using the ``hostdev`` element. :since:`since after 0.4.4 for USB, 0.= 6.0 -for PCI (KVM only) and 1.0.6 for SCSI (KVM only)` : +USB (:since:`since 0.4.4`), PCI (:since:`since 0.6.0, KVM only`) and +SCSI (:since:`since 1.0.6, KVM only`) devices attached to the host can be +passed through to the guest using the ``hostdev`` element. =20 :: =20 @@ -5314,11 +5318,10 @@ requires QEMU 5.1.0 or newer)` Teaming a virtio/hostdev NIC pair ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 -:since:`Since 6.1.0 (QEMU and KVM only, requires QEMU 4.2.0 or newer and a= guest -virtio-net driver supporting the "failover" feature, such as the one inclu= ded in -Linux kernel 4.18 and newer)` The ```` element of two interfaces = can -be used to connect them as a team/bond device in the guest (assuming proper -support in the hypervisor and the guest network driver). +:since:`Since 6.1.0 (QEMU and KVM only)`, the ```` element of two +interfaces can be used to connect them as a team/bond device in the guest. +This requires a guest virtio-net driver supporting the "failover" feature, +such as the one included in Linux 4.18. =20 :: =20 @@ -5917,11 +5920,12 @@ Setting VLAN tag (on supported network types only) If (and only if) the network connection used by the guest supports VLAN ta= gging transparent to the guest, an optional ```` element can specify one o= r more VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` . -Network connections that support guest-transparent VLAN tagging include 1) -type=3D'bridge' interfaces connected to an Open vSwitch bridge :since:`Sin= ce -0.10.0` , 2) SRIOV Virtual Functions (VF) used via type=3D'hostdev' (direc= t device -assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type=3D'dire= ct' with -mode=3D'passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All = other + +Network connections that support guest-transparent VLAN tagging include +``type=3D'bridge'`` interfaces connected to an Open vSwitch bridge, SRIOV +Virtual Functions (VF) used via ``type=3D'hostdev'`` (direct device assign= ment) +and, :since:`since 1.3.5`, SRIOV VFs used via ``type=3D'direct'`` with +``mode=3D'passthrough'`` (macvtap "passthru" mode). All other connection types, including standard linux bridges and libvirt's own virtu= al networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) sw= itches provide their own way (outside of libvirt) to tag guest traffic onto a spe= cific @@ -8034,9 +8038,10 @@ Example: usage of the TPM passthrough device =20 The emulator device type gives access to a TPM emulator providing TPM functionality for each VM. QEMU talks to it over a Unix socket. With the -emulator device type each guest gets its own private TPM. :since:`'emulato= r' -since 4.5.0` The state of the TPM emulator can be encrypted by providing an -``encryption`` element. :since:`'encryption' since 5.6.0` +emulator device type each guest gets its own private TPM. :since:`Since 4.= 5.0` + +:since:`Since 5.6.0`, the state of the TPM emulator can be encrypted by +providing an ``encryption`` element. =20 Example: usage of the TPM Emulator =20 @@ -8604,15 +8609,15 @@ Security label -------------- =20 The ``seclabel`` element allows control over the operation of the security -drivers. There are three basic modes of operation, 'dynamic' where libvirt -automatically generates a unique security label, 'static' where the -application/administrator chooses the labels, or 'none' where confinement = is +drivers. There are three basic modes of operation, 'dynamic' +(:since:`since 0.6.1`) where libvirt automatically generates a unique secu= rity +label, 'static' (:since:`since 0.6.2`) where the application/administrator +chooses the labels, or 'none' (:since:`since 0.9.10`) where confinement is disabled. With dynamic label generation, libvirt will always automatically relabel any resources associated with the virtual machine. With static lab= el assignment, by default, the administrator or application must ensure label= s are set correctly on any resources, however, automatic relabeling can be enabl= ed if -desired. :since:`'dynamic' since 0.6.1, 'static' since 0.6.2, and 'none' s= ince -0.9.10.` +desired. =20 If more than one security driver is used by libvirt, multiple ``seclabel``= tags can be used, one for each driver and the security driver referenced by eac= h tag diff --git a/docs/formatnetwork.rst b/docs/formatnetwork.rst index e65570038d..186190dc6f 100644 --- a/docs/formatnetwork.rst +++ b/docs/formatnetwork.rst @@ -489,9 +489,7 @@ follows, where accepted values for each attribute is an= integer number. ``peak`` and ``burst`` attributes still require ``average``. Currently,= the Linux kernel doesn't allow ingress qdiscs to have any classes therefore ``floor`` can be applied only on ``inbound`` and not ``outbound``. - -Attributes ``average``, ``peak``, and ``burst`` are available :since:`since -0.9.4` , while the ``floor`` attribute is available :since:`since 1.0.1` . + :since:`Since 1.0.1` =20 Setting VLAN tag (on supported network types only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -519,11 +517,12 @@ Setting VLAN tag (on supported network types only) If (and only if) the network connection used by the guest supports VLAN ta= gging transparent to the guest, an optional ```` element can specify one o= r more VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` . -Network connections that support guest-transparent VLAN tagging include 1) -type=3D'bridge' interfaces connected to an Open vSwitch bridge :since:`Sin= ce -0.10.0` , 2) SRIOV Virtual Functions (VF) used via type=3D'hostdev' (direc= t device -assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type=3D'dire= ct' with -mode=3D'passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All = other + +Network connections that support guest-transparent VLAN tagging include +``type=3D'bridge'`` interfaces connected to an Open vSwitch bridge, SRIOV +Virtual Functions (VF) used via ``type=3D'hostdev'`` (direct device assign= ment) +and, :since:`since 1.3.5`, SRIOV VFs used via ``type=3D'direct'`` with +``mode=3D'passthrough'`` (macvtap "passthru" mode). All other connection types, including standard linux bridges and libvirt's own virtu= al networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) sw= itches provide their own way (outside of libvirt) to tag guest traffic onto a spe= cific @@ -844,12 +843,13 @@ of 'route' or 'nat'. The optional ``bootp`` element specifies BOOTP options to be prov= ided by the DHCP server for IPv4 only. Two attributes are supported: ``file`` is mandatory and gives the file to be used for the boot = image; - ``server`` is optional and gives the address of the TFTP server f= rom + ``server`` (:since:`since 0.7.3`) is optional and + gives the address of the TFTP server from which the boot image will be fetched. ``server`` defaults to the = same host that runs the DHCP server, as is the case when the ``tftp`` element is used. The BOOTP options currently have to be the same = for all address ranges and statically assigned addresses. :since:`Sin= ce - 0.7.1` (``server`` :since:`since 0.7.3` ) + 0.7.1` =20 Optionally, ``range`` and ``host`` elements can have ``lease`` child element which specifies the lease time through it's attributes ``exp= iry`` diff --git a/docs/formatnwfilter.rst b/docs/formatnwfilter.rst index b749edadfc..b258a4f74b 100644 --- a/docs/formatnwfilter.rst +++ b/docs/formatnwfilter.rst @@ -472,13 +472,14 @@ A traffic filtering rule starts with the ``rule`` nod= e. This node may contain up to three attributes =20 - action -- mandatory; must either be ``drop`` (matching the rule silently - discards the packet with no further analysis), ``reject`` (matching the= rule - generates an ICMP reject message with no further analysis) :since:`(sin= ce - 0.9.0)` , ``accept`` (matching the rule accepts the packet with no furt= her - analysis), ``return`` (matching the rule passes this filter, but returns - control to the calling filter for further analysis) :since:`(since 0.9.= 7)` , - or ``continue`` (matching the rule goes on to the next rule for further - analysis) :since:`(since 0.9.7)` . + discards the packet with no further analysis), ``reject`` + (:since:`since 0.9.0`; matching the rule generates an ICMP reject messa= ge + with no further analysis), + ``accept`` (matching the rule accepts the packet with no further + analysis), ``return`` (:since:`since 0.9.7`; matching the rule passes t= his + filter, but returns control to the calling filter for further analysis), + or ``continue`` (:since:`since 0.9.7`; matching the rule goes on to the= next + rule for further analysis). =20 - direction -- mandatory; must either be ``in``, ``out`` or ``inout`` if = the rule is for incoming, outgoing or incoming-and-outgoing traffic @@ -1600,8 +1601,8 @@ Second example custom filter =20 In this example we now want to build a similar filter as in the example ab= ove, but extend the list of requirements with an ftp server located inside the = VM. -Further, we will be using features that have been added in :since:`version -0.8.5` . The requirements for this filter are: +Further, we will be using features that have been available +:since:`since 0.8.5`. The requirements for this filter are: =20 - prevents a VM's interface from MAC, IP and ARP spoofing =20 --=20 2.43.2 _______________________________________________ Devel mailing list -- devel@lists.libvirt.org To unsubscribe send an email to devel-leave@lists.libvirt.org