From 96777db7197cc012116651116582c0c9e36eb300 Mon Sep 17 00:00:00 2001 From: Andrea Bolognani Date: Mon, 19 Feb 2024 11:33:45 +0100 Subject: [PATCH] docs: Other fixes to :since: tags Make sure that they're entirely contained within a single line and that punctuation is used in a way that doesn't make the resulting HTML look weird. Signed-off-by: Andrea Bolognani Reviewed-by: Michal Privoznik --- docs/drvbhyve.rst | 30 +-- docs/drvesx.rst | 19 +- docs/drvqemu.rst | 2 +- docs/drvxen.rst | 2 +- docs/formatcaps.rst | 8 +- docs/formatdomain.rst | 370 ++++++++++++++++--------------- docs/formatnetwork.rst | 55 ++--- docs/formatnetworkport.rst | 2 +- docs/formatnode.rst | 6 +- docs/formatnwfilter.rst | 112 +++++----- docs/formatsecret.rst | 10 +- docs/formatsnapshot.rst | 4 +- docs/formatstorage.rst | 29 +-- docs/formatstorageencryption.rst | 8 +- docs/hooks.rst | 64 +++--- 15 files changed, 367 insertions(+), 354 deletions(-) diff --git a/docs/drvbhyve.rst b/docs/drvbhyve.rst index 214bc2e76e..f9cb99006e 100644 --- a/docs/drvbhyve.rst +++ b/docs/drvbhyve.rst @@ -268,7 +268,7 @@ these commands manually, most likely you might want to tweak them. Using ZFS volumes ~~~~~~~~~~~~~~~~~ -It's possible to use ZFS volumes as disk devices :since:`since 1.2.8` . An +It's possible to use ZFS volumes as disk devices :since:`since 1.2.8`. An example of domain XML device entry for that will look like: :: @@ -307,7 +307,7 @@ not have spaces or they will be tokenized incorrectly. Using UEFI bootrom, VNC, and USB tablet ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:since:`Since 3.2.0` , in addition to +:since:`Since 3.2.0`, in addition to `Using grub2-bhyve or Alternative Bootloaders`_, non-FreeBSD guests could be also booted using an UEFI boot ROM, provided both guest OS and installed ``bhyve(1)`` version support UEFI. To use that, ``loader`` should be @@ -349,7 +349,7 @@ Please note that the tablet device requires to have a USB controller of the ``nec-xhci`` model. Currently, only a single controller of this type and a single tablet are supported per domain. -:since:`Since 3.5.0` , it's possible to configure how the video device is +:since:`Since 3.5.0`, it's possible to configure how the video device is exposed to the guest using the ``vgaconf`` attribute: :: @@ -375,7 +375,7 @@ refer to the manual page and the `bhyve wiki `__ for more details on using the ``vgaconf`` option. -:since:`Since 3.7.0` , it's possible to use ``autoport`` to let libvirt allocate +:since:`Since 3.7.0`, it's possible to use ``autoport`` to let libvirt allocate VNC port automatically (instead of explicitly specifying it with the ``port`` attribute): @@ -383,7 +383,7 @@ attribute): -:since:`Since 6.8.0` , it's possible to set framebuffer resolution using the +:since:`Since 6.8.0`, it's possible to set framebuffer resolution using the ``resolution`` sub-element: :: @@ -394,7 +394,7 @@ attribute): -:since:`Since 6.8.0` , VNC server can be configured to use password based +:since:`Since 6.8.0`, VNC server can be configured to use password based authentication: :: @@ -414,7 +414,7 @@ Originally bhyve supported only localtime for RTC. Support for UTC time was introduced in `FreeBSD changeset r284894 `__ for *10-STABLE* and in `changeset r279225 `__ -for *-CURRENT*. It's possible to use this in libvirt :since:`since 1.2.18` , +for *-CURRENT*. It's possible to use this in libvirt :since:`since 1.2.18`, just place the following to domain XML: :: @@ -443,8 +443,8 @@ e1000 NIC As of `FreeBSD changeset r302504 `__ bhyve supports -Intel e1000 network adapter emulation. It's supported in libvirt :since:`since -3.1.0` and could be used as follows: +Intel e1000 network adapter emulation. It's supported in libvirt +:since:`since 3.1.0` and could be used as follows: :: @@ -460,7 +460,7 @@ Sound device As of `FreeBSD changeset r349355 `__ bhyve supports -sound device emulation. It's supported in libvirt :since:`since 6.7.0` . +sound device emulation. It's supported in libvirt :since:`since 6.7.0`. :: @@ -484,7 +484,7 @@ Virtio-9p filesystem As of `FreeBSD changeset r366413 `__ bhyve supports sharing arbitrary directory tree between the guest and the host. It's supported -in libvirt :since:`since 6.9.0` . +in libvirt :since:`since 6.9.0`. :: @@ -506,7 +506,7 @@ In the Linux guest, this could be mounted using: Wiring guest memory ~~~~~~~~~~~~~~~~~~~ -:since:`Since 4.4.0` , it's possible to specify that guest memory should be +:since:`Since 4.4.0`, it's possible to specify that guest memory should be wired and cannot be swapped out as follows: :: @@ -522,7 +522,7 @@ wired and cannot be swapped out as follows: CPU topology ~~~~~~~~~~~~ -:since:`Since 4.5.0` , it's possible to specify guest CPU topology, if bhyve +:since:`Since 4.5.0`, it's possible to specify guest CPU topology, if bhyve supports that. Support for specifying guest CPU topology was added to bhyve in `FreeBSD changeset r332298 `__ for *-CURRENT*. Example: @@ -540,7 +540,7 @@ for *-CURRENT*. Example: Ignoring unknown MSRs reads and writes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:since:`Since 5.1.0` , it's possible to make bhyve ignore accesses to +:since:`Since 5.1.0`, it's possible to make bhyve ignore accesses to unimplemented Model Specific Registers (MSRs). Example: :: @@ -558,7 +558,7 @@ unimplemented Model Specific Registers (MSRs). Example: Pass-through of arbitrary bhyve commands ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:since:`Since 5.1.0` , it's possible to pass additional command-line arguments +:since:`Since 5.1.0`, it's possible to pass additional command-line arguments to the bhyve process when starting the domain using the ```` element under ``domain``. To supply an argument, use the element ```` with the attribute ``value`` set to additional argument to be added. The arg diff --git a/docs/drvesx.rst b/docs/drvesx.rst index 81625d6f10..13c2bc37e5 100644 --- a/docs/drvesx.rst +++ b/docs/drvesx.rst @@ -56,8 +56,9 @@ URIs have this general form (``[...]`` marks an optional part). type://[username@]hostname[:port]/[[folder/...]datacenter/[folder/...][cluster/]server][?extraparameters] -The ``type://`` is either ``esx://`` or ``gsx://`` or ``vpx://`` :since:`since -0.8.3` . The driver selects the default port depending on the ``type://``. For +The ``type://`` is either ``esx://`` or ``gsx://`` or ``vpx://`` +:since:`since 0.8.3`. +The driver selects the default port depending on the ``type://``. For ``esx://`` and ``vpx://`` the default HTTPS port is 443, for ``gsx://`` it is 8333. If the port parameter is given, it overrides the default port. @@ -75,7 +76,7 @@ of datacenter ``dc1``. vpx://example-vcenter.com/dc1/cluster1/example-esx.com Datacenters and clusters can be organized in folders, those have to be specified -as well. The driver can handle folders :since:`since 0.9.7` . +as well. The driver can handle folders :since:`since 0.9.7`. :: @@ -129,12 +130,12 @@ The driver understands the extra parameters shown below. | | | set to 0, questions are | | | | reported as errors. The | | | | default value is 0. | -| | | :since:`Since 0.7.5` . | +| | | :since:`Since 0.7.5`. | +-----------------+-----------------------------+-----------------------------+ | ``proxy`` | ``[type://]host[:port]`` | Allows to specify a proxy | | | | for HTTP and HTTPS | | | | communication. | -| | | :since:`Since 0.8.2` . The | +| | | :since:`Since 0.8.2`. The | | | | optional ``type`` part may | | | | be one of: ``http``, | | | | ``socks``, ``socks4``, | @@ -272,8 +273,8 @@ will complain if this restrictions are violated. - Memory size has to be a multiple of 4096 - Number of virtual CPU has to be 1 or a multiple of 2. :since:`Since 4.10.0` any number of vCPUs is supported. -- Valid MAC address prefixes are ``00:0c:29`` and ``00:50:56``. :since:`Since - 0.7.6` arbitrary `MAC addresses`_ are supported. +- Valid MAC address prefixes are ``00:0c:29`` and ``00:50:56``. + :since:`Since 0.7.6` arbitrary `MAC addresses`_ are supported. Datastore references ~~~~~~~~~~~~~~~~~~~~ @@ -331,7 +332,7 @@ the ESX server from rejecting out-of-predefined-range MAC addresses. ethernet0.checkMACAddress = "false" -:since:`Since 6.6.0` , one can force libvirt to keep the provided MAC address +:since:`Since 6.6.0`, one can force libvirt to keep the provided MAC address when it's in the reserved VMware range by adding a ``type="static"`` attribute to the ```` element. Note that this attribute is useless if the provided MAC address is outside of the reserved VMWare ranges. @@ -374,7 +375,7 @@ Here a domain XML snippet: ... -The controller element is supported :since:`since 0.8.2` . Prior to this +The controller element is supported :since:`since 0.8.2`. Prior to this ```` was abused to specify the SCSI controller model. This attribute usage is deprecated now. diff --git a/docs/drvqemu.rst b/docs/drvqemu.rst index 22d7e6502b..1ee4b1e366 100644 --- a/docs/drvqemu.rst +++ b/docs/drvqemu.rst @@ -562,7 +562,7 @@ The library provides two API: ``virDomainQemuMonitorCommand``, for sending an arbitrary monitor command (in either HMP or QMP format) to a qemu guest ( :since:`Since 0.8.3` ), and ``virDomainQemuAttach``, for registering a qemu domain that was manually started so that it can then be managed by libvirtd ( -:since:`Since 0.9.4` , :removed:`removed as of 5.5.0` ). +:since:`Since 0.9.4`, :removed:`removed as of 5.5.0` ). Additionally, the following XML additions allow fine-tuning of the command line given to qemu when starting a domain ( :since:`Since 0.8.3` ). In order to use diff --git a/docs/drvxen.rst b/docs/drvxen.rst index c131d52c7a..ba024e7793 100644 --- a/docs/drvxen.rst +++ b/docs/drvxen.rst @@ -139,7 +139,7 @@ using libvirt Domain XML into xl, xm, or sxpr config format. Pass-through of arbitrary command-line arguments to the qemu device model ------------------------------------------------------------------------- -:since:`Since 6.7.0` , the Xen driver supports passing arbitrary command-line +:since:`Since 6.7.0`, the Xen driver supports passing arbitrary command-line arguments to the qemu device model used by Xen with the ```` element under ``domain``. In order to use command-line pass-through, an XML namespace request must be issued that pulls in diff --git a/docs/formatcaps.rst b/docs/formatcaps.rst index 68477e639f..da6b215780 100644 --- a/docs/formatcaps.rst +++ b/docs/formatcaps.rst @@ -148,11 +148,11 @@ The ```` element will typically wrap up the following elements: If present, 32-bit guests can use PAE address space extensions, :since:`since 0.4.1` ``nonpae`` - If present, 32-bit guests can be run without requiring PAE, :since:`since - 0.4.1` + If present, 32-bit guests can be run without requiring PAE, + :since:`since 0.4.1` ``ia64_be`` - If present, IA64 guests can be run in big-endian mode, :since:`since - 0.4.1` + If present, IA64 guests can be run in big-endian mode, + :since:`since 0.4.1` ``acpi`` If this element is present, the ``default`` attribute describes whether the hypervisor exposes ACPI to the guest by default, and the ``toggle`` diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 2f9ee1110a..967283aaa9 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -55,7 +55,7 @@ General metadata :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 + :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, integer value identifier, referred to as a Globally Unique Identifier (GUID) using the same format as the ``uuid``. The value is used to help notify the @@ -77,7 +77,7 @@ General metadata ``title`` The optional element ``title`` provides space for a short description of the - domain. The title should not contain any newlines. :since:`Since 0.9.10` . + domain. The title should not contain any newlines. :since:`Since 0.9.10`. ``description`` The content of the ``description`` element provides a human readable description of the virtual machine. This data is not used by libvirt in any @@ -201,8 +201,8 @@ harddisk, cdrom, network) determining where to obtain/find the boot image. ``docs/interop/firmware.json`` in QEMU repository. Regular users do not need to bother. :since:`Since 5.2.0 (QEMU and KVM only)` For VMware guests, this is set to ``efi`` when the guest uses UEFI, and it is - not set when using BIOS. :since:`Since 5.3.0 (VMware ESX and - Workstation/Player)` + not set when using BIOS. + :since:`Since 5.3.0 (VMware ESX and Workstation/Player)` ``type`` The content of the ``type`` element specifies the type of operating system to be booted in the virtual machine. ``hvm`` indicates that the OS is one @@ -409,8 +409,8 @@ and full virtualized guests. console (eg serial port), or the installation media source / kickstart file ``dtb`` The contents of this element specify the fully-qualified path to the - (optional) device tree binary (dtb) image in the host OS. :since:`Since - 1.0.4` + (optional) device tree binary (dtb) image in the host OS. + :since:`Since 1.0.4` Container boot ~~~~~~~~~~~~~~ @@ -602,7 +602,7 @@ layout of sub-elements, with supported values of: validation and ``date`` format checking, all values are passed as strings to the hypervisor driver. ``chassis`` - :since:`Since 4.1.0,` this is block 3 of SMBIOS, with entry names drawn + :since:`Since 4.1.0`, this is block 3 of SMBIOS, with entry names drawn from: ``manufacturer`` @@ -689,8 +689,8 @@ CPU Allocation :since:`Since 0.4.4` ``current`` The optional attribute ``current`` can be used to specify whether fewer - than the maximum number of virtual CPUs should be enabled. :since:`Since - 0.8.5` + than the maximum number of virtual CPUs should be enabled. + :since:`Since 0.8.5` ``placement`` The optional attribute ``placement`` can be used to indicate the CPU placement mode for domain process. The value can be either "static" or @@ -887,8 +887,8 @@ CPU Tuning The optional ``period`` element specifies the enforcement interval (unit: microseconds). Within ``period``, each vCPU of the domain will not be allowed to consume more than ``quota`` worth of runtime. The value should be in range - [1000, 1000000]. A period with value 0 means no value. :since:`Only QEMU - driver support since 0.9.4, LXC since 0.9.10` + [1000, 1000000]. A period with value 0 means no value. + :since:`Only QEMU driver support since 0.9.4, LXC since 0.9.10` ``quota`` The optional ``quota`` element specifies the maximum allowed bandwidth (unit: microseconds). A domain with ``quota`` as any negative value indicates that @@ -901,8 +901,8 @@ CPU Tuning The optional ``global_period`` element specifies the enforcement CFS scheduler interval (unit: microseconds) for the whole domain in contrast with ``period`` which enforces the interval per vCPU. The value should be in range - 1000, 1000000]. A ``global_period`` with value 0 means no value. :since:`Only - QEMU driver support since 1.3.3` + 1000, 1000000]. A ``global_period`` with value 0 means no value. + :since:`Only QEMU driver support since 1.3.3` ``global_quota`` The optional ``global_quota`` element specifies the maximum allowed bandwidth (unit: microseconds) within a period for the whole domain. A domain with @@ -915,8 +915,8 @@ CPU Tuning (unit: microseconds). Within ``emulator_period``, emulator threads (those excluding vCPUs) of the domain will not be allowed to consume more than ``emulator_quota`` worth of runtime. The value should be in range [1000, - 1000000]. A period with value 0 means no value. :since:`Only QEMU driver - support since 0.10.0` + 1000000]. A period with value 0 means no value. + :since:`Only QEMU driver support since 0.10.0` ``emulator_quota`` The optional ``emulator_quota`` element specifies the maximum allowed bandwidth (unit: microseconds) for domain's emulator threads (those excluding @@ -930,8 +930,8 @@ CPU Tuning (unit: microseconds) for IOThreads. Within ``iothread_period``, each IOThread of the domain will not be allowed to consume more than ``iothread_quota`` worth of runtime. The value should be in range [1000, 1000000]. An - iothread_period with value 0 means no value. :since:`Only QEMU driver support - since 2.1.0` + iothread_period with value 0 means no value. + :since:`Only QEMU driver support since 2.1.0` ``iothread_quota`` The optional ``iothread_quota`` element specifies the maximum allowed bandwidth (unit: microseconds) for IOThreads. A domain with @@ -939,8 +939,8 @@ CPU Tuning have infinite bandwidth, which means that it is not bandwidth controlled. The value should be in range [1000, 17592186044415] or less than 0. An ``iothread_quota`` with value 0 means no value. You can use this feature to - ensure that all IOThreads run at the same speed. :since:`Only QEMU driver - support since 2.1.0` + ensure that all IOThreads run at the same speed. + :since:`Only QEMU driver support since 2.1.0` ``vcpusched``, ``iothreadsched`` and ``emulatorsched`` The optional ``vcpusched``, ``iothreadsched`` and ``emulatorsched`` elements specify the scheduler type (values ``batch``, ``idle``, ``fifo``, ``rr``) for @@ -1053,7 +1053,7 @@ Memory Allocation configured for the guest (See `CPU model and topology`_) the ``memory`` element can be omitted. In the case of crash, optional attribute ``dumpCore`` can be used to control whether the guest memory should be included in the generated - coredump or not (values "on", "off"). ``unit`` :since:`since 0.9.11` , + coredump or not (values "on", "off"). ``unit`` :since:`since 0.9.11`, ``dumpCore`` :since:`since 0.10.2 (QEMU only)` ``maxMemory`` The run time maximum memory allocation of the guest. The initial memory @@ -1064,7 +1064,7 @@ Memory Allocation for adding memory to the guest. The bounds are hypervisor specific. Note that due to alignment of the memory chunks added via memory hotplug the full size allocation specified by this element may be impossible to achieve. - :since:`Since 1.2.14 supported by the QEMU driver.` + :since:`Since 1.2.14 supported by the QEMU driver`. ``currentMemory`` The actual allocation of memory for the guest. This value can be less than the maximum allocation, to allow for ballooning up the guests memory on the @@ -1131,7 +1131,7 @@ influence how virtual memory pages are backed by host pages. above. :since:`Since 1.0.6` ``source`` Using the ``type`` attribute, it's possible to provide "file" to utilize file - memorybacking or keep the default "anonymous". :since:`Since 4.10.0` , you + memorybacking or keep the default "anonymous". :since:`Since 4.10.0`, you may choose "memfd" backing. (QEMU/KVM only) ``access`` Using the ``mode`` attribute, specify if the memory is to be "shared" or @@ -1443,7 +1443,7 @@ In case no restrictions need to be put on CPU model and its features, a simpler :since:`Since 0.8.5` the ``match`` attribute can be omitted and will default to ``exact``. Sometimes the hypervisor is not able to create a virtual CPU - exactly matching the specification passed by libvirt. :since:`Since 3.2.0` , + exactly matching the specification passed by libvirt. :since:`Since 3.2.0`, an optional ``check`` attribute can be used to request a specific way of checking whether the virtual CPU matches the specification. It is usually safe to omit this attribute when starting a domain and stick with the default @@ -1466,7 +1466,7 @@ In case no restrictions need to be put on CPU model and its features, a simpler specification and the domain will not be started unless the two CPUs match. - :since:`Since 0.9.10` , an optional ``mode`` attribute may be used to make it + :since:`Since 0.9.10`, an optional ``mode`` attribute may be used to make it easier to configure a guest CPU to be as close to host CPU as possible. Possible values for the ``mode`` attribute are: @@ -1564,7 +1564,7 @@ In case no restrictions need to be put on CPU model and its features, a simpler directory ``cpu_map``, installed in libvirt's data directory. If a hypervisor is not able to use the exact CPU model, libvirt automatically falls back to a closest model supported by the hypervisor while maintaining the list of CPU - features. :since:`Since 0.9.10` , an optional ``fallback`` attribute can be + features. :since:`Since 0.9.10`, an optional ``fallback`` attribute can be used to forbid this behavior, in which case an attempt to start a domain requesting an unsupported CPU model will fail. Supported values for ``fallback`` attribute are: ``allow`` (this is the default), and ``forbid``. @@ -1679,8 +1679,8 @@ In case no restrictions need to be put on CPU model and its features, a simpler address bits for ``passthrough`` mode, i.e. in case the host CPU reports more bits than that, ``limit`` is used. :since:`Since 9.3.0` -Guest NUMA topology can be specified using the ``numa`` element. :since:`Since -0.9.8` +Guest NUMA topology can be specified using the ``numa`` element. +:since:`Since 0.9.8` :: @@ -1905,7 +1905,7 @@ QEMU/KVM/HVF supports the ``on_poweroff`` and ``on_reboot`` events handling the ``destroy`` and ``restart`` actions, but the combination of ``on_poweroff`` set to ``restart`` and ``on_reboot`` set to ``destroy`` is forbidden. -The ``on_crash`` event supports these additional actions :since:`since 0.8.4` . +The ``on_crash`` event supports these additional actions :since:`since 0.8.4`. ``coredump-destroy`` The crashed domain's core will be dumped, and then the domain will be @@ -1914,7 +1914,7 @@ The ``on_crash`` event supports these additional actions :since:`since 0.8.4` . The crashed domain's core will be dumped, and then the domain will be restarted with the same configuration -:since:`Since 3.9.0` , the lifecycle events can be configured via the +:since:`Since 3.9.0`, the lifecycle events can be configured via the `virDomainSetLifecycleAction `__ API. @@ -2037,8 +2037,9 @@ are: ACPI is useful for power management, for example, with KVM or HVF guests it is required for graceful shutdown to work. ``apic`` - APIC allows the use of programmable IRQ management. :since:`Since 0.10.2 - (QEMU only)` there is an optional attribute ``eoi`` with values ``on`` and + APIC allows the use of programmable IRQ management. + :since:`Since 0.10.2 (QEMU only)` there is an optional + attribute ``eoi`` with values ``on`` and ``off`` which toggles the availability of EOI (End of Interrupt) for the guest. ``hap`` @@ -2076,7 +2077,7 @@ are: avic Enable use Hyper-V SynIC with hardware APICv/AVIC on, off :since:`8.10.0 (QEMU 6.2)` =============== ====================================================================== ============================================ ======================================================= - :since:`Since 8.0.0` , the hypervisor can be configured further by setting + :since:`Since 8.0.0`, the hypervisor can be configured further by setting the ``mode`` attribute to one of the following values: ``custom`` @@ -2201,8 +2202,8 @@ are: ``htm`` Configure HTM (Hardware Transactional Memory) availability for pSeries guests. Possible values for the ``state`` attribute are ``on`` and ``off``. If the - attribute is not defined, the hypervisor default will be used. :since:`Since - 4.6.0` (QEMU/KVM only) + attribute is not defined, the hypervisor default will be used. + :since:`Since 4.6.0` (QEMU/KVM only) ``nested-hv`` Configure nested HV availability for pSeries guests. This needs to be enabled from the host (L0) in order to be effective; having HV support in the (L1) @@ -2215,8 +2216,8 @@ are: Some guests might require ignoring unknown Model Specific Registers (MSRs) reads and writes. It's possible to switch this by setting ``unknown`` attribute of ``msrs`` to ``ignore``. If the attribute is not defined, or set - to ``fault``, unknown reads and writes will not be ignored. :since:`Since - 5.1.0` (bhyve only) + to ``fault``, unknown reads and writes will not be ignored. + :since:`Since 5.1.0` (bhyve only) ``ccf-assist`` Configure ccf-assist (Count Cache Flush Assist) availability for pSeries guests. Possible values for the ``state`` attribute are ``on`` and ``off``. @@ -2240,8 +2241,8 @@ are: ``workaround`` (count cache flush), ``fixed-ibs`` (fixed by serializing indirect branches), ``fixed-ccd`` (fixed by disabling the cache count) and ``fixed-na`` (fixed in hardware - no longer applicable). If the - attribute is not defined, the hypervisor default will be used. :since:`Since - 6.3.0` (QEMU/KVM only) + attribute is not defined, the hypervisor default will be used. + :since:`Since 6.3.0` (QEMU/KVM only) ``tcg`` Various features to change the behavior of the TCG accelerator. @@ -2290,7 +2291,7 @@ Windows, however, expects it to be in so called 'localtime'. is hypervisor specific. ``localtime`` The guest clock will be synchronized to the host's configured timezone - when booted, if any. :since:`Since 0.9.11,` the ``adjustment`` attribute + when booted, if any. :since:`Since 0.9.11`, the ``adjustment`` attribute behaves the same as in 'utc' mode. ``timezone`` The guest clock will be synchronized to the requested timezone using the @@ -2311,8 +2312,8 @@ Windows, however, expects it to be in so called 'localtime'. epoch timestamp. :since:`Since 8.4.0`. - A ``clock`` may have zero or more ``timer`` sub-elements. :since:`Since - 0.8.0` + A ``clock`` may have zero or more ``timer`` sub-elements. + :since:`Since 0.8.0` ``timer`` Each timer element requires a ``name`` attribute, and has other optional @@ -2956,12 +2957,12 @@ paravirtualized driver is specified via the ``disk`` element. ``snapshot`` The ``name`` attribute of ``snapshot`` element can optionally specify an internal snapshot name to be used as the source for storage protocols. - Supported for 'rbd' :since:`since 1.2.11 (QEMU only).` + Supported for 'rbd' :since:`since 1.2.11 (QEMU only)`. ``config`` The ``file`` attribute for the ``config`` element provides a fully qualified path to a configuration file to be provided as a parameter to the client of a networked storage protocol. Supported for 'rbd' - :since:`since 1.2.11 (QEMU only).` + :since:`since 1.2.11 (QEMU only)`. ``auth`` :since:`Since 3.9.0`, the ``auth`` element is supported for a disk ``type`` "network" that is using a ``source`` element with the @@ -3095,7 +3096,7 @@ paravirtualized driver is specified via the ``disk`` element. ``backingStore`` This element describes the backing store used by the disk specified by - sibling ``source`` element. :since:`Since 1.2.4.` If the hypervisor driver + sibling ``source`` element. :since:`Since 1.2.4`. If the hypervisor driver does not support the `backingStoreInput `__ ( :since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored on @@ -3148,14 +3149,14 @@ paravirtualized driver is specified via the ``disk`` element. ``type`` attribute of the mirror, similar to what is done for the overall ``disk`` device element. The ``job`` attribute mentions which API started the operation ("copy" for the ``virDomainBlockRebase`` API, or "active-commit" - for the ``virDomainBlockCommit`` API), :since:`since 1.2.7` . The attribute + for the ``virDomainBlockCommit`` API), :since:`since 1.2.7`. The attribute ``ready``, if present, tracks progress of the job: ``yes`` if the disk is - known to be ready to pivot, or, :since:`since 1.2.7` , ``abort`` or ``pivot`` + known to be ready to pivot, or, :since:`since 1.2.7`, ``abort`` or ``pivot`` if the job is in the process of completing. If ``ready`` is not present, the disk is probably still copying. For now, this element only valid in output; it is ignored on input. The ``source`` sub-element exists for all two-phase - jobs :since:`since 1.2.6` . Older libvirt supported only block copy to a - file, :since:`since 0.9.12` ; for compatibility with older clients, such jobs + jobs :since:`since 1.2.6`. Older libvirt supported only block copy to a + file, :since:`since 0.9.12`; for compatibility with older clients, such jobs include redundant information in the attributes ``file`` and ``format`` in the ``mirror`` element. ``target`` @@ -3165,7 +3166,7 @@ paravirtualized driver is specified via the ``disk`` element. name in the guest OS. Treat it as a device ordering hint. The optional ``bus`` attribute specifies the type of disk device to emulate; possible values are driver specific, with typical values being "ide", "scsi", - "virtio", "xen", "usb", "sata", or "sd" :since:`"sd" since 1.1.2` . If + "virtio", "xen", "usb", "sata", or "sd" :since:`"sd" since 1.1.2`. If omitted, the bus type is inferred from the style of the device name (e.g. a device named 'sda' will typically be exported using a SCSI bus). The optional attribute ``tray`` indicates the tray status of the removable disks (i.e. @@ -3190,8 +3191,8 @@ paravirtualized driver is specified via the ``disk`` element. this to the ``blkiotune`` element (See `Block I/O Tuning`_), which applies globally to the domain). Currently, the only tuning available is Block I/O throttling for qemu. This element has optional sub-elements; any sub-element - not specified or given with a value of 0 implies no limit. :since:`Since - 0.9.8` + not specified or given with a value of 0 implies no limit. + :since:`Since 0.9.8` ``total_bytes_sec`` The optional ``total_bytes_sec`` element is the total throughput limit in @@ -3304,8 +3305,8 @@ paravirtualized driver is specified via the ``disk`` element. 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)` . + guests support "threads" and "native" :since:`Since 0.8.8`, io_uring + :since:`Since 6.3.0 (QEMU 5.0)`. - The optional ``ioeventfd`` attribute allows users to set `domain I/O asynchronous handling `__ for disk device. The default is left to the discretion of the hypervisor. @@ -3321,8 +3322,9 @@ paravirtualized driver is specified via the ``disk`` element. reduce the number of interrupts and exits for the guest. The default is determined by QEMU; usually if the feature is supported, default is on. In case there is a situation where this behavior is suboptimal, this - attribute provides a way to force the feature off. :since:`Since 0.9.5 - (QEMU and KVM only)` **In general you should leave this option alone, + attribute provides a way to force the feature off. + :since:`Since 0.9.5 (QEMU and KVM only)` + **In general you should leave this option alone, unless you are very certain you know what you are doing.** - The optional ``copy_on_read`` attribute controls whether to copy read backing file into the image file. The value can be either "on" or "off". @@ -3332,8 +3334,8 @@ paravirtualized driver is specified via the ``disk`` element. - The optional ``discard`` attribute controls whether discard requests (also known as "trim" or "unmap") are ignored or passed to the filesystem. The value can be either "unmap" (allow the discard request to be passed) or - "ignore" (ignore the discard request). :since:`Since 1.0.6 (QEMU and KVM - only)` + "ignore" (ignore the discard request). + :since:`Since 1.0.6 (QEMU and KVM only)` - The optional ``detect_zeroes`` attribute controls whether to detect zero write requests. The value can be "off", "on" or "unmap". First two values turn the detection off and on, respectively. The third value ("unmap") @@ -3347,8 +3349,9 @@ paravirtualized driver is specified via the ``disk`` element. `IOThreads Allocation`_). Multiple disks may be assigned to the same IOThread and are numbered from 1 to the domain iothreads value. Available for a disk device ``target`` configured to use - "virtio" ``bus`` and "pci" or "ccw" ``address`` types. :since:`Since 1.2.8 - (QEMU 2.1)` *Note:* ``iothread`` is mutually exclusive with ``iothreads``. + "virtio" ``bus`` and "pci" or "ccw" ``address`` types. + :since:`Since 1.2.8 (QEMU 2.1)` + *Note:* ``iothread`` is mutually exclusive with ``iothreads``. - The optional ``iothreads`` sub-element allows specifying multiple IOThreads via the ``iothread`` sub-element with attribute ``id`` the disk will use for I/O operations. Optionally the ``iothread`` element can have multiple @@ -3390,8 +3393,8 @@ paravirtualized driver is specified via the ``disk`` element. image. When enabled, a discard request from within the guest will mark the qcow2 cluster as zero, but will keep the reference/offset of that cluster. But it will still pass the discard further to the lower layer. - This will resolve fragmentation within the qcow2 image. :since:`Since 9.5.0 - (QEMU 8.1)` + This will resolve fragmentation within the qcow2 image. + :since:`Since 9.5.0 (QEMU 8.1)` In the majority of cases the default configuration used by the hypervisor is sufficient so modifying this setting should not be necessary. For @@ -3596,16 +3599,17 @@ A directory on the host that can be accessed directly from the guest. possible values are: ``mount`` - A host directory to mount in the guest. Used by LXC, OpenVZ :since:`(since - 0.6.2)` and QEMU/KVM :since:`(since 0.8.5)` . This is the default ``type`` + A host directory to mount in the guest. Used by LXC, OpenVZ + :since:`(since 0.6.2)` and QEMU/KVM :since:`(since 0.8.5)`. + This is the default ``type`` if one is not specified. This mode also has an optional sub-element ``driver``, with an attribute ``type='path'`` or ``type='handle'`` - :since:`(since 0.9.7)` . The driver block has an optional attribute + :since:`(since 0.9.7)`. The driver block has an optional attribute ``wrpolicy`` that further controls interaction with the host page cache; omitting the attribute gives default behavior, while the value ``immediate`` means that a host writeback is immediately triggered for all pages touched during a guest file write operation :since:`(since 0.9.10)` - . :since:`Since 6.2.0` , ``type='virtiofs'`` is also supported. Using + . :since:`Since 6.2.0`, ``type='virtiofs'`` is also supported. Using virtiofs requires setting up shared memory, see the guide: `Virtiofs `__ ``template`` @@ -3615,7 +3619,7 @@ A directory on the host that can be accessed directly from the guest. filesystem format will be autodetected. Only used by LXC driver. ``block`` A host block device to mount in the guest. The filesystem format will be - autodetected. Only used by LXC driver :since:`(since 0.9.5)` . + autodetected. Only used by LXC driver :since:`(since 0.9.5)`. ``ram`` An in-memory filesystem, using memory from the host OS. The source element has a single attribute ``usage`` which gives the memory usage limit in @@ -3626,7 +3630,7 @@ A directory on the host that can be accessed directly from the guest. guest. Only used by LXC driver :since:`(since 0.9.13)` The filesystem element has an optional attribute ``accessmode`` which - specifies the security mode for accessing the source :since:`(since 0.8.5)` . + specifies the security mode for accessing the source :since:`(since 0.8.5)`. Currently this only works with ``type='mount'`` for the QEMU/KVM driver. For driver type ``virtiofs``, only ``passthrough`` is supported. For other driver types, the possible values are: @@ -3645,15 +3649,16 @@ A directory on the host that can be accessed directly from the guest. usable for people who run the hypervisor as non-root. `More info `__ - :since:`Since 5.2.0` , the filesystem element has an optional attribute + :since:`Since 5.2.0`, the filesystem element has an optional attribute ``model`` with supported values "virtio-transitional", "virtio-non-transitional", or "virtio". See `Virtio transitional devices`_ for more details. The filesystem element has optional attributes ``fmode`` and ``dmode``. These two attributes control the creation mode for files and directories - when used with the ``mapped`` value for ``accessmode`` (:since:`since 6.10.0, - requires QEMU 2.10` ). If not specified, QEMU creates files with mode + when used with the ``mapped`` value for ``accessmode`` + (:since:`since 6.10.0, requires QEMU 2.10` ). + If not specified, QEMU creates files with mode ``600`` and directories with mode ``700``. The setuid, setgid, and sticky bit are unsupported. @@ -3772,8 +3777,9 @@ control where on the bus the device will be placed: 0xff, inclusive), ``slot`` (a hex value between 0x0 and 0x1f, inclusive), and ``function`` (a value between 0 and 7, inclusive). Also available is the ``multifunction`` attribute, which controls turning on the multifunction bit - for a particular slot/function in the PCI control register ( :since:`since - 0.9.7, requires QEMU 0.13` ). ``multifunction`` defaults to 'off', but should + for a particular slot/function in the PCI control register + ( :since:`since 0.9.7, requires QEMU 0.13` ). + ``multifunction`` defaults to 'off', but should be set to 'on' for function 0 of a slot that will have multiple functions used. ( :since:`Since 4.10.0` ), PCI address extensions depending on the architecture are supported. For example, PCI addresses for S390 guests will @@ -3781,7 +3787,7 @@ control where on the bus the device will be placed: between 0x0001 and 0xffff, inclusive), and ``fid`` (a hex value between 0x00000000 and 0xffffffff, inclusive) used by PCI devices on S390 for User-defined Identifiers and Function Identifiers. - :since:`Since 1.3.5` , some hypervisor drivers may accept an + :since:`Since 1.3.5`, some hypervisor drivers may accept an ``
`` element with no other attributes as an explicit request to assign a PCI address for the device rather than some other type of address that may also be appropriate for that same device (e.g. virtio-mmio). @@ -3799,7 +3805,7 @@ control where on the bus the device will be placed: ``ccid`` A CCID address, for smart-cards, has the following additional attributes: ``bus`` (a 2-digit bus number), and ``slot`` attribute (a 2-digit slot within - the bus). :since:`Since 0.8.8.` + the bus). :since:`Since 0.8.8`. ``usb`` USB addresses have the following additional attributes: ``bus`` (a hex value between 0 and 0xfff, inclusive), and ``port`` (a dotted notation of up to @@ -3810,7 +3816,7 @@ control where on the bus the device will be placed: assigned at a non-zero multiple of 0x00001000, but other addresses are valid and permitted by libvirt. Each address has the following additional attribute: ``reg`` (the hex value address of the starting register). - :since:`Since 0.9.9.` + :since:`Since 0.9.9`. ``ccw`` S390 guests with a ``machine`` value of s390-ccw-virtio use the native CCW bus for I/O devices. CCW bus addresses have the following additional @@ -3871,7 +3877,7 @@ you know what you are doing. Virtio transitional devices ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:since:`Since 5.2.0` , some of QEMU's virtio devices, when used with PCI/PCIe +:since:`Since 5.2.0`, some of QEMU's virtio devices, when used with PCI/PCIe machine types, accept the following ``model`` values: ``virtio-transitional`` @@ -3949,7 +3955,7 @@ specific features, such as: ``virtio-serial`` The ``virtio-serial`` controller has two additional optional attributes ``ports`` and ``vectors``, which control how many devices can be connected - through the controller. :since:`Since 5.2.0` , it supports an optional + through the controller. :since:`Since 5.2.0`, it supports an optional attribute ``model`` which can be 'virtio', 'virtio-transitional', or 'virtio-non-transitional'. See `Virtio transitional devices`_ for more details. ``scsi`` @@ -3963,18 +3969,18 @@ specific features, such as: "piix3-uhci", "piix4-uhci", "ehci", "ich9-ehci1", "ich9-uhci1", "ich9-uhci2", "ich9-uhci3", "vt82c686b-uhci", "pci-ohci", "nec-xhci", "qusb1" (xen pvusb with qemu backend, version 1.1), "qusb2" (xen pvusb with qemu backend, - version 2.0) or "qemu-xhci". Additionally, :since:`since 0.10.0` , if the USB + version 2.0) or "qemu-xhci". Additionally, :since:`since 0.10.0`, if the USB bus needs to be explicitly disabled for the guest, ``model='none'`` may be - used. :since:`Since 1.0.5` , no default USB controller will be built on s390. - :since:`Since 1.3.5` , USB controllers accept a ``ports`` attribute to + used. :since:`Since 1.0.5`, no default USB controller will be built on s390. + :since:`Since 1.3.5`, USB controllers accept a ``ports`` attribute to configure how many devices can be connected to the controller. ``ide`` :since:`Since 3.10.0` for the vbox driver, the ``ide`` controller has an optional attribute ``model``, which is one of "piix3", "piix4" or "ich6". ``xenbus`` - :since:`Since 5.2.0` , the ``xenbus`` controller has an optional attribute + :since:`Since 5.2.0`, the ``xenbus`` controller has an optional attribute ``maxGrantFrames``, which specifies the maximum number of grant frames the - controller makes available for connected devices. :since:`Since 6.3.0` , the + controller makes available for connected devices. :since:`Since 6.3.0`, the xenbus controller supports the optional ``maxEventChannels`` attribute, which specifies maximum number of event channels (PV interrupts) that can be used by the guest. @@ -3993,8 +3999,8 @@ An optional sub-element ``driver`` can specify the driver specific options: matching the number of vCPUs. :since:`Since 1.0.5 (QEMU and KVM only)` ``cmd_per_lun`` The optional ``cmd_per_lun`` attribute specifies the maximum number of - commands that can be queued on devices controlled by the host. :since:`Since - 1.2.7 (QEMU and KVM only)` + commands that can be queued on devices controlled by the host. + :since:`Since 1.2.7 (QEMU and KVM only)` ``max_sectors`` The optional ``max_sectors`` attribute specifies the maximum amount of data in bytes that will be transferred to or from the device in a single command. @@ -4006,7 +4012,7 @@ An optional sub-element ``driver`` can specify the driver specific options: or not. Accepted values are "on" and "off". :since:`Since 1.2.18` ``iothread`` Supported for controller type ``scsi`` using model ``virtio-scsi`` for - ``address`` types ``pci`` and ``ccw`` :since:`since 1.3.5 (QEMU 2.4)` . The + ``address`` types ``pci`` and ``ccw`` :since:`since 1.3.5 (QEMU 2.4)`. The optional ``iothread`` attribute assigns the controller to an IOThread as defined by the range for the domain ``iothreads`` (See `IOThreads Allocation`_). Each SCSI ``disk`` @@ -4064,7 +4070,7 @@ emulating (e.g. "i82801b11-bridge") rather than simply the class of device ("pcie-to-pci-bridge", "pci-bridge"), which is set in the controller element's model **attribute**. In almost all cases, you should not manually add a ```` subelement to a controller, nor should you modify one that is -automatically generated by libvirt. :since:`Since 1.2.19 (QEMU only).` +automatically generated by libvirt. :since:`Since 1.2.19 (QEMU only)`. PCI controllers also have an optional subelement ```` with the attributes and subelements listed below. These are configurable items that 1) @@ -4072,7 +4078,7 @@ are visible to the guest OS so must be preserved for guest ABI compatibility, and 2) are usually left to default values or derived automatically by libvirt. In almost all cases, you should not manually add a ```` subelement to a controller, nor should you modify the values in the those that are automatically -generated by libvirt. :since:`Since 1.2.19 (QEMU only).` +generated by libvirt. :since:`Since 1.2.19 (QEMU only)`. ``chassisNr`` PCI controllers that have attribute model="pci-bridge", can also have a @@ -4130,7 +4136,7 @@ generated by libvirt. :since:`Since 1.2.19 (QEMU only).` ``node`` Some PCI controllers (``pci-expander-bus`` for the pc machine type, - ``pcie-expander-bus`` for the q35 machine type and, :since:`since 3.6.0` , + ``pcie-expander-bus`` for the q35 machine type and, :since:`since 3.6.0`, ``pci-root`` for the pseries machine type) can have an optional ```` subelement within the ```` subelement, which is used to set the NUMA node reported to the guest OS for that bus - the guest OS will then know that @@ -4188,8 +4194,8 @@ bridge device that can connect only to one of the 31 slots on the pcie-root bus on its upstream side, and makes a single (PCIe, hotpluggable) port available on the downstream side (at slot='0'). pcie-root-port can be used to provide a single slot to later hotplug a PCIe device (but is not itself hotpluggable - it -must be in the configuration when the domain is started). ( :since:`since -1.2.19` ) +must be in the configuration when the domain is started). +( :since:`since 1.2.19` ) pcie-switch-upstream-port is a more flexible (but also more complex) device that can only plug into a pcie-root-port or pcie-switch-downstream-port on the @@ -4390,7 +4396,7 @@ or: ``scsi_host`` :since:`since 2.5.0` For SCSI devices, user is responsible to make sure the device is not used by host. This ``type`` passes all LUNs presented by - a single HBA to the guest. :since:`Since 5.2.0,` the ``model`` attribute + a single HBA to the guest. :since:`Since 5.2.0`, the ``model`` attribute can be specified further with "virtio-transitional", "virtio-non-transitional", or "virtio". `Virtio transitional devices`_ for more details. @@ -4410,7 +4416,7 @@ or: are either ``on`` or ``off`` (default is 'off'). It is required to use a graphical framebuffer (See `Graphical framebuffers`_) in order to use this attribute, currently only supported with VNC, Spice and egl-headless graphics - devices. :since:`Since version 5.10.0` , there is an optional ``ramfb`` + devices. :since:`Since version 5.10.0`, there is an optional ``ramfb`` attribute for devices with ``model='vfio-pci'``. Supported values are either ``on`` or ``off`` (default is 'off'). When enabled, this attribute provides a memory framebuffer device to the guest. This framebuffer will @@ -4435,7 +4441,7 @@ or: ``vendor`` and ``product`` elements or by the device's address on the host using the ``address`` element. - :since:`Since 1.0.0` , the ``source`` element of USB devices may contain + :since:`Since 1.0.0`, the ``source`` element of USB devices may contain ``startupPolicy`` attribute which can be used to define policy what to do if the specified host USB device is not found. The attribute accepts the following values: @@ -4461,7 +4467,7 @@ or: ``pci`` PCI devices can only be described by their ``address``. - :since:`Since 6.8.0 (Xen only)` , the ``source`` element of a PCI device + :since:`Since 6.8.0 (Xen only)`, the ``source`` element of a PCI device may contain the ``writeFiltering`` attribute to control write access to the PCI configuration space. By default Xen only allows writes of known safe values to the configuration space. Setting ``writeFiltering='no'`` @@ -4474,7 +4480,7 @@ or: hypervisors support larger ``target`` and ``unit`` values. It is up to each hypervisor to determine the maximum value supported for the adapter. - :since:`Since 1.2.8` , the ``source`` element of a SCSI device may contain + :since:`Since 1.2.8`, the ``source`` element of a SCSI device may contain the ``protocol`` attribute. When the attribute is set to "iscsi", the host device XML follows the network disk device (See `Hard drives, floppy disks, CDROMs`_) using the @@ -4486,7 +4492,7 @@ or: subelement. ``scsi_host`` - :since:`Since 2.5.0` , multiple LUNs behind a single SCSI HBA are + :since:`Since 2.5.0`, multiple LUNs behind a single SCSI HBA are described by a ``protocol`` attribute set to "vhost" and a ``wwpn`` attribute that is the vhost_scsi wwpn (16 hexadecimal digits with a prefix of "naa.") established in the host configfs. @@ -4512,16 +4518,17 @@ or: memory map. (In PCI documentation, the "rombar" setting controls the presence of the Base Address Register for the ROM). If no rom bar is specified, the qemu default will be used (older versions of qemu used a default of "off", - while newer qemus have a default of "on"). :since:`Since 0.9.7 (QEMU and KVM - only)` . The optional ``file`` attribute contains an absolute path to a + while newer qemus have a default of "on"). + :since:`Since 0.9.7 (QEMU and KVM only)`. + The optional ``file`` attribute contains an absolute path to a binary file to be presented to the guest as the device's ROM BIOS. This can be useful, for example, to provide a PXE boot ROM for a virtual function of an sr-iov capable ethernet device (which has no boot ROMs for the VFs). - :since:`Since 0.9.10 (QEMU and KVM only)` . The optional ``enabled`` + :since:`Since 0.9.10 (QEMU and KVM only)`. The optional ``enabled`` attribute can be set to ``no`` to disable PCI ROM loading completely for the device; if PCI ROM loading is disabled through this attribute, attempts to tweak the loading process further using the ``bar`` or ``file`` attributes - will be rejected. :since:`Since 4.3.0 (QEMU and KVM only)` . + will be rejected. :since:`Since 4.3.0 (QEMU and KVM only)`. ``address`` The ``address`` element for USB devices has a ``bus`` and ``device`` attribute to specify the USB bus and device number the device appears at on @@ -4539,8 +4546,9 @@ or: ``driver`` PCI hostdev devices can have an optional ``driver`` subelement that specifies which host driver to bind to the device when preparing it - for assignment to a guest. :since:`Since 10.0.0 (useful for QEMU and - KVM only)`. This is done by setting the ```` element's ``model`` + for assignment to a guest. + :since:`Since 10.0.0 (useful for QEMU and KVM only)`. + This is done by setting the ```` element's ``model`` attribute, for example:: ... @@ -4561,7 +4569,7 @@ or: found is "problematic" in some way, the generic vfio-pci driver similarly be forced. - (Note: :since:`Since 1.0.5,` the ``name`` attribute has been + (Note: :since:`Since 1.0.5`, the ``name`` attribute has been described to be used to select the type of PCI device assignment ("vfio", "kvm", or "xen"), but those values have been mostly useless, since the type of device assignment is actually determined @@ -4584,8 +4592,8 @@ Block / character devices Block / character devices from the host can be passed through to the guest using the ``hostdev`` element. This is only possible with container based -virtualization. Devices are specified by a fully qualified path. :since:`since -after 1.0.1 for LXC` : +virtualization. Devices are specified by a fully qualified path. +:since:`since after 1.0.1 for LXC`: :: @@ -4632,8 +4640,8 @@ after 1.0.1 for LXC` : Redirected devices ~~~~~~~~~~~~~~~~~~ -USB device redirection through a character device is supported :since:`since -after 0.9.5 (KVM only)` : +USB device redirection through a character device is supported +:since:`since after 0.9.5 (KVM only)`: :: @@ -4787,7 +4795,7 @@ Each ```` element has an optional ``
`` sub-element that can tie the interface to a particular pci slot, with attribute ``type='pci'`` as documented in the `Device Addresses`_ section. -:since:`Since 6.6.0` , one can force libvirt to keep the provided MAC address +:since:`Since 6.6.0`, one can force libvirt to keep the provided MAC address when it's in the reserved VMware range by adding a ``type="static"`` attribute to the ```` element. Note that this attribute is useless if the provided MAC address is outside of the reserved VMWare ranges. @@ -4812,8 +4820,7 @@ network may be totally isolated (no ```` element given), NAT'ing to an explicit network device or to the default route (````), routed with no NAT (````), or connected directly to one of the host's network interfaces (via macvtap) or bridge devices -(```` :since:`Since -0.9.4` ) +(```` :since:`Since 0.9.4`) For networks with a forward mode of bridge, private, vepa, and passthrough, it is assumed that the host has any necessary DNS and DHCP services already setup @@ -4829,7 +4836,7 @@ with the element (see `Overriding the target element`_). When the source of an interface is a network, a ``portgroup`` can be specified along with the name of the network; one network may have multiple portgroups defined, with each portgroup containing slightly different configuration -information for different classes of network connections. :since:`Since 0.9.4` . +information for different classes of network connections. :since:`Since 0.9.4`. When a guest is running an interface of type ``network`` may include a ``portid`` attribute. This provides the UUID of an associated virNetworkPortPtr @@ -4840,8 +4847,8 @@ automatically during startup and shutdown. :since:`Since 5.1.0` Also, similar to ``direct`` network connections (described below), a connection of type ``network`` may specify a ``virtualport`` element, with configuration data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant switch ( -:since:`Since 0.8.2` ), or to an Open vSwitch virtual switch ( :since:`Since -0.9.11` ). +:since:`Since 0.8.2` ), or to an Open vSwitch virtual switch +( :since:`Since 0.9.11` ). Since the actual type of switch may vary depending on the configuration in the ```` on the host, it is acceptable to omit the virtualport ``type`` @@ -5094,8 +5101,9 @@ device is useful because it permits a virtual machine managed by an unprivileged libvirtd to have emulated network devices based on tap devices. After creating/opening the tap device, an optional shell script (given in the -``path`` attribute of the ``