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 <abologna@xxxxxxxxxx>
---
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 identifier for
the virtual machine. The format must be RFC 4122 compliant, eg
``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/creating 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 Virtual
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 users to
see BIOS messages on a serial port. Therefore, one needs to have `Serial 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 again in
case the boot fails (according to BIOS). The value is in milliseconds with
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, possible
values are "default", "none", "writethrough", "writeback", "directsync"
- (like "writethrough", but it bypasses the host page cache) and "unsafe"
- (host may cache all disk io, and sync requests from guest are ignored).
- :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 io,
+ 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" since
- 0.9.7` The default is left to the discretion of the hypervisor. There is
- also an optional ``rerror_policy`` that controls behavior for read errors
- only. :since:`Since 0.9.7` . If no rerror_policy is given, error_policy 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 "enospace"
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
^^^^^^^^^^^^^^^^^^^^^^^^
-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.
::
@@ -5314,11 +5318,10 @@ requires QEMU 5.1.0 or newer)`
Teaming a virtio/hostdev NIC pair
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-: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 included in
-Linux kernel 4.18 and newer)` The ``<teaming>`` 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 ``<teaming>`` 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.
::
@@ -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 tagging
transparent to the guest, an optional ``<vlan>`` element can specify one or 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='bridge' interfaces connected to an Open vSwitch bridge :since:`Since
-0.10.0` , 2) SRIOV Virtual Functions (VF) used via type='hostdev' (direct device
-assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type='direct' with
-mode='passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All other
+
+Network connections that support guest-transparent VLAN tagging include
+``type='bridge'`` interfaces connected to an Open vSwitch bridge, SRIOV
+Virtual Functions (VF) used via ``type='hostdev'`` (direct device assignment)
+and, :since:`since 1.3.5`, SRIOV VFs used via ``type='direct'`` with
+``mode='passthrough'`` (macvtap "passthru" mode). All other
connection types, including standard linux bridges and libvirt's own virtual
networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
provide their own way (outside of libvirt) to tag guest traffic onto a specific
@@ -8034,9 +8038,10 @@ Example: usage of the TPM passthrough device
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:`'emulator'
-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.
Example: usage of the TPM Emulator
@@ -8604,15 +8609,15 @@ Security label
--------------
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 security
+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 label
assignment, by default, the administrator or application must ensure labels are
set correctly on any resources, however, automatic relabeling can be enabled if
-desired. :since:`'dynamic' since 0.6.1, 'static' since 0.6.2, and 'none' since
-0.9.10.`
+desired.
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 each 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`
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 tagging
transparent to the guest, an optional ``<vlan>`` element can specify one or 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='bridge' interfaces connected to an Open vSwitch bridge :since:`Since
-0.10.0` , 2) SRIOV Virtual Functions (VF) used via type='hostdev' (direct device
-assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type='direct' with
-mode='passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All other
+
+Network connections that support guest-transparent VLAN tagging include
+``type='bridge'`` interfaces connected to an Open vSwitch bridge, SRIOV
+Virtual Functions (VF) used via ``type='hostdev'`` (direct device assignment)
+and, :since:`since 1.3.5`, SRIOV VFs used via ``type='direct'`` with
+``mode='passthrough'`` (macvtap "passthru" mode). All other
connection types, including standard linux bridges and libvirt's own virtual
networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
provide their own way (outside of libvirt) to tag guest traffic onto a specific
@@ -844,12 +843,13 @@ of 'route' or 'nat'.
The optional ``bootp`` element specifies BOOTP options to be provided
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 from
+ ``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:`Since
- 0.7.1` (``server`` :since:`since 0.7.3` )
+ 0.7.1`
Optionally, ``range`` and ``host`` elements can have ``lease`` child
element which specifies the lease time through it's attributes ``expiry``
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`` node. This node may contain up
to three attributes
- 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:`(since
- 0.9.0)` , ``accept`` (matching the rule accepts the packet with no further
- 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 message
+ 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 this
+ 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).
- 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
In this example we now want to build a similar filter as in the example above,
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:
- prevents a VM's interface from MAC, IP and ARP spoofing
--
2.43.2
_______________________________________________
Devel mailing list -- devel@xxxxxxxxxxxxxxxxx
To unsubscribe send an email to devel-leave@xxxxxxxxxxxxxxxxx
