External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-22 13:45:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Other fixes to :since: tags

Browse Source 
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 <abologna@redhat.com>
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This commit is contained in:
Andrea Bolognani 2024-02-19 11:33:45 +01:00
parent fd1dac6cd4
commit 96777db719
15 changed files with 367 additions and 354 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/drvbhyve.rst
View File

@ -443,8 +443,8 @@ e1000 NIC
As of `FreeBSD changeset As of `FreeBSD changeset
r302504 <https://svnweb.freebsd.org/changeset/base/302504>`__ bhyve supports r302504 <https://svnweb.freebsd.org/changeset/base/302504>`__ bhyve supports
Intel e1000 network adapter emulation. It's supported in libvirt :since:`since Intel e1000 network adapter emulation. It's supported in libvirt
3.1.0` and could be used as follows: :since:`since 3.1.0` and could be used as follows:
:: ::

9
docs/drvesx.rst
View File

@ -56,8 +56,9 @@ URIs have this general form (``[...]`` marks an optional part).
type://[username@]hostname[:port]/[[folder/...]datacenter/[folder/...][cluster/]server][?extraparameters] type://[username@]hostname[:port]/[[folder/...]datacenter/[folder/...][cluster/]server][?extraparameters]
The ``type://`` is either ``esx://`` or ``gsx://`` or ``vpx://`` :since:`since The ``type://`` is either ``esx://`` or ``gsx://`` or ``vpx://``
0.8.3` . The driver selects the default port depending on the ``type://``. For :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 ``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. 8333. If the port parameter is given, it overrides the default port.
@ -272,8 +273,8 @@ will complain if this restrictions are violated.
- Memory size has to be a multiple of 4096 - 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` - Number of virtual CPU has to be 1 or a multiple of 2. :since:`Since 4.10.0`
any number of vCPUs is supported. any number of vCPUs is supported.
- Valid MAC address prefixes are ``00:0c:29`` and ``00:50:56``. :since:`Since - Valid MAC address prefixes are ``00:0c:29`` and ``00:50:56``.
0.7.6` arbitrary `MAC addresses`_ are supported. :since:`Since 0.7.6` arbitrary `MAC addresses`_ are supported.
Datastore references Datastore references
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~

8
docs/formatcaps.rst
View File

@ -148,11 +148,11 @@ The ``<guest/>`` element will typically wrap up the following elements:
If present, 32-bit guests can use PAE address space extensions, If present, 32-bit guests can use PAE address space extensions,
:since:`since 0.4.1` :since:`since 0.4.1`
``nonpae`` ``nonpae``
If present, 32-bit guests can be run without requiring PAE, :since:`since If present, 32-bit guests can be run without requiring PAE,
0.4.1` :since:`since 0.4.1`
``ia64_be`` ``ia64_be``
If present, IA64 guests can be run in big-endian mode, :since:`since If present, IA64 guests can be run in big-endian mode,
0.4.1` :since:`since 0.4.1`
``acpi`` ``acpi``
If this element is present, the ``default`` attribute describes whether If this element is present, the ``default`` attribute describes whether
the hypervisor exposes ACPI to the guest by default, and the ``toggle`` the hypervisor exposes ACPI to the guest by default, and the ``toggle``

238
docs/formatdomain.rst
View File

@ -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 ``docs/interop/firmware.json`` in QEMU repository. Regular users do not need
to bother. :since:`Since 5.2.0 (QEMU and KVM only)` 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 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 not set when using BIOS.
Workstation/Player)` :since:`Since 5.3.0 (VMware ESX and Workstation/Player)`
``type`` ``type``
The content of the ``type`` element specifies the type of operating system to 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 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 console (eg serial port), or the installation media source / kickstart file
``dtb`` ``dtb``
The contents of this element specify the fully-qualified path to the The contents of this element specify the fully-qualified path to the
(optional) device tree binary (dtb) image in the host OS. :since:`Since (optional) device tree binary (dtb) image in the host OS.
1.0.4` :since:`Since 1.0.4`
Container boot 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 validation and ``date`` format checking, all values are passed as strings
to the hypervisor driver. to the hypervisor driver.
``chassis`` ``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: from:
``manufacturer`` ``manufacturer``
@ -689,8 +689,8 @@ CPU Allocation
:since:`Since 0.4.4` :since:`Since 0.4.4`
``current`` ``current``
The optional attribute ``current`` can be used to specify whether fewer The optional attribute ``current`` can be used to specify whether fewer
than the maximum number of virtual CPUs should be enabled. :since:`Since than the maximum number of virtual CPUs should be enabled.
0.8.5` :since:`Since 0.8.5`
``placement`` ``placement``
The optional attribute ``placement`` can be used to indicate the CPU The optional attribute ``placement`` can be used to indicate the CPU
placement mode for domain process. The value can be either "static" or 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: The optional ``period`` element specifies the enforcement interval (unit:
microseconds). Within ``period``, each vCPU of the domain will not be allowed 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 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 [1000, 1000000]. A period with value 0 means no value.
driver support since 0.9.4, LXC since 0.9.10` :since:`Only QEMU driver support since 0.9.4, LXC since 0.9.10`
``quota`` ``quota``
The optional ``quota`` element specifies the maximum allowed bandwidth (unit: The optional ``quota`` element specifies the maximum allowed bandwidth (unit:
microseconds). A domain with ``quota`` as any negative value indicates that 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 The optional ``global_period`` element specifies the enforcement CFS
scheduler interval (unit: microseconds) for the whole domain in contrast with scheduler interval (unit: microseconds) for the whole domain in contrast with
``period`` which enforces the interval per vCPU. The value should be in range ``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 1000, 1000000]. A ``global_period`` with value 0 means no value.
QEMU driver support since 1.3.3` :since:`Only QEMU driver support since 1.3.3`
``global_quota`` ``global_quota``
The optional ``global_quota`` element specifies the maximum allowed bandwidth The optional ``global_quota`` element specifies the maximum allowed bandwidth
(unit: microseconds) within a period for the whole domain. A domain with (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 (unit: microseconds). Within ``emulator_period``, emulator threads (those
excluding vCPUs) of the domain will not be allowed to consume more than 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, ``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 1000000]. A period with value 0 means no value.
support since 0.10.0` :since:`Only QEMU driver support since 0.10.0`
``emulator_quota`` ``emulator_quota``
The optional ``emulator_quota`` element specifies the maximum allowed The optional ``emulator_quota`` element specifies the maximum allowed
bandwidth (unit: microseconds) for domain's emulator threads (those excluding 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 (unit: microseconds) for IOThreads. Within ``iothread_period``, each IOThread
of the domain will not be allowed to consume more than ``iothread_quota`` 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 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 iothread_period with value 0 means no value.
since 2.1.0` :since:`Only QEMU driver support since 2.1.0`
``iothread_quota`` ``iothread_quota``
The optional ``iothread_quota`` element specifies the maximum allowed The optional ``iothread_quota`` element specifies the maximum allowed
bandwidth (unit: microseconds) for IOThreads. A domain with 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 have infinite bandwidth, which means that it is not bandwidth controlled. The
value should be in range [1000, 17592186044415] or less than 0. An 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 ``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 ensure that all IOThreads run at the same speed.
support since 2.1.0` :since:`Only QEMU driver support since 2.1.0`
``vcpusched``, ``iothreadsched`` and ``emulatorsched`` ``vcpusched``, ``iothreadsched`` and ``emulatorsched``
The optional ``vcpusched``, ``iothreadsched`` and ``emulatorsched`` elements The optional ``vcpusched``, ``iothreadsched`` and ``emulatorsched`` elements
specify the scheduler type (values ``batch``, ``idle``, ``fifo``, ``rr``) for specify the scheduler type (values ``batch``, ``idle``, ``fifo``, ``rr``) for
@ -1064,7 +1064,7 @@ Memory Allocation
for adding memory to the guest. The bounds are hypervisor specific. Note that 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 due to alignment of the memory chunks added via memory hotplug the full size
allocation specified by this element may be impossible to achieve. 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`` ``currentMemory``
The actual allocation of memory for the guest. This value can be less than 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 the maximum allocation, to allow for ballooning up the guests memory on the
@ -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 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` more bits than that, ``limit`` is used. :since:`Since 9.3.0`
Guest NUMA topology can be specified using the ``numa`` element. :since:`Since Guest NUMA topology can be specified using the ``numa`` element.
0.9.8` :since:`Since 0.9.8`
:: ::
@ -2037,8 +2037,9 @@ are:
ACPI is useful for power management, for example, with KVM or HVF guests it ACPI is useful for power management, for example, with KVM or HVF guests it
is required for graceful shutdown to work. is required for graceful shutdown to work.
``apic`` ``apic``
APIC allows the use of programmable IRQ management. :since:`Since 0.10.2 APIC allows the use of programmable IRQ management.
(QEMU only)` there is an optional attribute ``eoi`` with values ``on`` and :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 ``off`` which toggles the availability of EOI (End of Interrupt) for the
guest. guest.
``hap`` ``hap``
@ -2201,8 +2202,8 @@ are:
``htm`` ``htm``
Configure HTM (Hardware Transactional Memory) availability for pSeries guests. Configure HTM (Hardware Transactional Memory) availability for pSeries guests.
Possible values for the ``state`` attribute are ``on`` and ``off``. If the Possible values for the ``state`` attribute are ``on`` and ``off``. If the
attribute is not defined, the hypervisor default will be used. :since:`Since attribute is not defined, the hypervisor default will be used.
4.6.0` (QEMU/KVM only) :since:`Since 4.6.0` (QEMU/KVM only)
``nested-hv`` ``nested-hv``
Configure nested HV availability for pSeries guests. This needs to be enabled 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) 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) Some guests might require ignoring unknown Model Specific Registers (MSRs)
reads and writes. It's possible to switch this by setting ``unknown`` 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 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 to ``fault``, unknown reads and writes will not be ignored.
5.1.0` (bhyve only) :since:`Since 5.1.0` (bhyve only)
``ccf-assist`` ``ccf-assist``
Configure ccf-assist (Count Cache Flush Assist) availability for pSeries Configure ccf-assist (Count Cache Flush Assist) availability for pSeries
guests. Possible values for the ``state`` attribute are ``on`` and ``off``. 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 ``workaround`` (count cache flush), ``fixed-ibs`` (fixed by serializing
indirect branches), ``fixed-ccd`` (fixed by disabling the cache count) and indirect branches), ``fixed-ccd`` (fixed by disabling the cache count) and
``fixed-na`` (fixed in hardware - no longer applicable). If the ``fixed-na`` (fixed in hardware - no longer applicable). If the
attribute is not defined, the hypervisor default will be used. :since:`Since attribute is not defined, the hypervisor default will be used.
6.3.0` (QEMU/KVM only) :since:`Since 6.3.0` (QEMU/KVM only)
``tcg`` ``tcg``
Various features to change the behavior of the TCG accelerator. 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. is hypervisor specific.
``localtime`` ``localtime``
The guest clock will be synchronized to the host's configured timezone 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. behaves the same as in 'utc' mode.
``timezone`` ``timezone``
The guest clock will be synchronized to the requested timezone using the 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. epoch timestamp.
:since:`Since 8.4.0`. :since:`Since 8.4.0`.
A ``clock`` may have zero or more ``timer`` sub-elements. :since:`Since A ``clock`` may have zero or more ``timer`` sub-elements.
0.8.0` :since:`Since 0.8.0`
``timer`` ``timer``
Each timer element requires a ``name`` attribute, and has other optional Each timer element requires a ``name`` attribute, and has other optional
@ -2956,12 +2957,12 @@ paravirtualized driver is specified via the ``disk`` element.
``snapshot`` ``snapshot``
The ``name`` attribute of ``snapshot`` element can optionally specify an The ``name`` attribute of ``snapshot`` element can optionally specify an
internal snapshot name to be used as the source for storage protocols. 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`` ``config``
The ``file`` attribute for the ``config`` element provides a fully The ``file`` attribute for the ``config`` element provides a fully
qualified path to a configuration file to be provided as a parameter to qualified path to a configuration file to be provided as a parameter to
the client of a networked storage protocol. Supported for 'rbd' 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`` ``auth``
:since:`Since 3.9.0`, the ``auth`` element is supported for a :since:`Since 3.9.0`, the ``auth`` element is supported for a
disk ``type`` "network" that is using a ``source`` element with the disk ``type`` "network" that is using a ``source`` element with the
@ -3095,7 +3096,7 @@ paravirtualized driver is specified via the ``disk`` element.
``backingStore`` ``backingStore``
This element describes the backing store used by the disk specified by 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 does not support the
`backingStoreInput <formatdomaincaps.html#backingstoreinput>`__ ( `backingStoreInput <formatdomaincaps.html#backingstoreinput>`__ (
:since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored on :since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored on
@ -3190,8 +3191,8 @@ paravirtualized driver is specified via the ``disk`` element.
this to the ``blkiotune`` element (See `Block I/O Tuning`_), which applies 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 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 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 not specified or given with a value of 0 implies no limit.
0.9.8` :since:`Since 0.9.8`
``total_bytes_sec`` ``total_bytes_sec``
The optional ``total_bytes_sec`` element is the total throughput limit in The optional ``total_bytes_sec`` element is the total throughput limit in
@ -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 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 determined by QEMU; usually if the feature is supported, default is on. In
case there is a situation where this behavior is suboptimal, this 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 attribute provides a way to force the feature off.
(QEMU and KVM only)` **In general you should leave this option alone, :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.** unless you are very certain you know what you are doing.**
- The optional ``copy_on_read`` attribute controls whether to copy read - 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". 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 - The optional ``discard`` attribute controls whether discard requests (also
known as "trim" or "unmap") are ignored or passed to the filesystem. The 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 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 "ignore" (ignore the discard request).
only)` :since:`Since 1.0.6 (QEMU and KVM only)`
- The optional ``detect_zeroes`` attribute controls whether to detect zero - The optional ``detect_zeroes`` attribute controls whether to detect zero
write requests. The value can be "off", "on" or "unmap". First two values write requests. The value can be "off", "on" or "unmap". First two values
turn the detection off and on, respectively. The third value ("unmap") 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 `IOThreads Allocation`_). Multiple disks may be
assigned to the same IOThread and are numbered from 1 to the domain assigned to the same IOThread and are numbered from 1 to the domain
iothreads value. Available for a disk device ``target`` configured to use iothreads value. Available for a disk device ``target`` configured to use
"virtio" ``bus`` and "pci" or "ccw" ``address`` types. :since:`Since 1.2.8 "virtio" ``bus`` and "pci" or "ccw" ``address`` types.
(QEMU 2.1)` *Note:* ``iothread`` is mutually exclusive with ``iothreads``. :since:`Since 1.2.8 (QEMU 2.1)`
*Note:* ``iothread`` is mutually exclusive with ``iothreads``.
- The optional ``iothreads`` sub-element allows specifying multiple IOThreads - The optional ``iothreads`` sub-element allows specifying multiple IOThreads
via the ``iothread`` sub-element with attribute ``id`` the disk will use via the ``iothread`` sub-element with attribute ``id`` the disk will use
for I/O operations. Optionally the ``iothread`` element can have multiple 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 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. 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. 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 This will resolve fragmentation within the qcow2 image.
(QEMU 8.1)` :since:`Since 9.5.0 (QEMU 8.1)`
In the majority of cases the default configuration used by the hypervisor In the majority of cases the default configuration used by the hypervisor
is sufficient so modifying this setting should not be necessary. For is sufficient so modifying this setting should not be necessary. For
@ -3596,8 +3599,9 @@ A directory on the host that can be accessed directly from the guest.
possible values are: possible values are:
``mount`` ``mount``
A host directory to mount in the guest. Used by LXC, OpenVZ :since:`(since A host directory to mount in the guest. Used by LXC, OpenVZ
0.6.2)` and QEMU/KVM :since:`(since 0.8.5)` . This is the default ``type`` :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 if one is not specified. This mode also has an optional sub-element
``driver``, with an attribute ``type='path'`` or ``type='handle'`` ``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
@ -3652,8 +3656,9 @@ A directory on the host that can be accessed directly from the guest.
The filesystem element has optional attributes ``fmode`` and ``dmode``. The filesystem element has optional attributes ``fmode`` and ``dmode``.
These two attributes control the creation mode for files and directories These two attributes control the creation mode for files and directories
when used with the ``mapped`` value for ``accessmode`` (:since:`since 6.10.0, when used with the ``mapped`` value for ``accessmode``
requires QEMU 2.10` ). If not specified, QEMU creates files with mode (: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 ``600`` and directories with mode ``700``. The setuid, setgid, and sticky
bit are unsupported. 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 0xff, inclusive), ``slot`` (a hex value between 0x0 and 0x1f, inclusive), and
``function`` (a value between 0 and 7, inclusive). Also available is the ``function`` (a value between 0 and 7, inclusive). Also available is the
``multifunction`` attribute, which controls turning on the multifunction bit ``multifunction`` attribute, which controls turning on the multifunction bit
for a particular slot/function in the PCI control register ( :since:`since for a particular slot/function in the PCI control register
0.9.7, requires QEMU 0.13` ). ``multifunction`` defaults to 'off', but should ( :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 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 used. ( :since:`Since 4.10.0` ), PCI address extensions depending on the
architecture are supported. For example, PCI addresses for S390 guests will architecture are supported. For example, PCI addresses for S390 guests will
@ -3799,7 +3805,7 @@ control where on the bus the device will be placed:
``ccid`` ``ccid``
A CCID address, for smart-cards, has the following additional attributes: 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 ``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``
USB addresses have the following additional attributes: ``bus`` (a hex value USB addresses have the following additional attributes: ``bus`` (a hex value
between 0 and 0xfff, inclusive), and ``port`` (a dotted notation of up to 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 assigned at a non-zero multiple of 0x00001000, but other addresses are valid
and permitted by libvirt. Each address has the following additional and permitted by libvirt. Each address has the following additional
attribute: ``reg`` (the hex value address of the starting register). attribute: ``reg`` (the hex value address of the starting register).
:since:`Since 0.9.9.` :since:`Since 0.9.9`.
``ccw`` ``ccw``
S390 guests with a ``machine`` value of s390-ccw-virtio use the native 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 bus for I/O devices. CCW bus addresses have the following additional
@ -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)` matching the number of vCPUs. :since:`Since 1.0.5 (QEMU and KVM only)`
``cmd_per_lun`` ``cmd_per_lun``
The optional ``cmd_per_lun`` attribute specifies the maximum number of The optional ``cmd_per_lun`` attribute specifies the maximum number of
commands that can be queued on devices controlled by the host. :since:`Since commands that can be queued on devices controlled by the host.
1.2.7 (QEMU and KVM only)` :since:`Since 1.2.7 (QEMU and KVM only)`
``max_sectors`` ``max_sectors``
The optional ``max_sectors`` attribute specifies the maximum amount of data 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. in bytes that will be transferred to or from the device in a single command.
@ -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 ("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 model **attribute**. In almost all cases, you should not manually add a
``<model>`` subelement to a controller, nor should you modify one that is ``<model>`` 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 ``<target>`` with the PCI controllers also have an optional subelement ``<target>`` with the
attributes and subelements listed below. These are configurable items that 1) 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. and 2) are usually left to default values or derived automatically by libvirt.
In almost all cases, you should not manually add a ``<target>`` subelement to a In almost all cases, you should not manually add a ``<target>`` subelement to a
controller, nor should you modify the values in the those that are automatically 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`` ``chassisNr``
PCI controllers that have attribute model="pci-bridge", can also have a PCI controllers that have attribute model="pci-bridge", can also have a
@ -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 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 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 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 must be in the configuration when the domain is started).
1.2.19` ) ( :since:`since 1.2.19` )
pcie-switch-upstream-port is a more flexible (but also more complex) device that 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 can only plug into a pcie-root-port or pcie-switch-downstream-port on the
@ -4390,7 +4396,7 @@ or:
``scsi_host`` ``scsi_host``
:since:`since 2.5.0` For SCSI devices, user is responsible to make sure :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 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", can be specified further with "virtio-transitional",
"virtio-non-transitional", or "virtio". `Virtio transitional devices`_ "virtio-non-transitional", or "virtio". `Virtio transitional devices`_
for more details. for more details.
@ -4512,8 +4518,9 @@ or:
memory map. (In PCI documentation, the "rombar" setting controls the presence 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 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", 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 while newer qemus have a default of "on").
only)` . The optional ``file`` attribute contains an absolute path to a :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 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 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). an sr-iov capable ethernet device (which has no boot ROMs for the VFs).
@ -4539,8 +4546,9 @@ or:
``driver`` ``driver``
PCI hostdev devices can have an optional ``driver`` subelement that PCI hostdev devices can have an optional ``driver`` subelement that
specifies which host driver to bind to the device when preparing it 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 for assignment to a guest.
KVM only)`. This is done by setting the ``<driver>`` element's ``model`` :since:`Since 10.0.0 (useful for QEMU and KVM only)`.
This is done by setting the ``<driver>`` element's ``model``
attribute, for example:: attribute, for example::
... ...
@ -4561,7 +4569,7 @@ or:
found is "problematic" in some way, the generic vfio-pci driver found is "problematic" in some way, the generic vfio-pci driver
similarly be forced. 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 described to be used to select the type of PCI device assignment
("vfio", "kvm", or "xen"), but those values have been mostly ("vfio", "kvm", or "xen"), but those values have been mostly
useless, since the type of device assignment is actually determined 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 Block / character devices from the host can be passed through to the guest using
the ``hostdev`` element. This is only possible with container based the ``hostdev`` element. This is only possible with container based
virtualization. Devices are specified by a fully qualified path. :since:`since virtualization. Devices are specified by a fully qualified path.
after 1.0.1 for LXC` : :since:`since after 1.0.1 for LXC`:
:: ::
@ -4632,8 +4640,8 @@ after 1.0.1 for LXC` :
Redirected devices Redirected devices
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
USB device redirection through a character device is supported :since:`since USB device redirection through a character device is supported
after 0.9.5 (KVM only)` : :since:`since after 0.9.5 (KVM only)`:
:: ::
@ -4812,8 +4820,7 @@ network may be totally isolated (no ``<forward>`` element given), NAT'ing to an
explicit network device or to the default route (``<forward mode='nat'>``), explicit network device or to the default route (``<forward mode='nat'>``),
routed with no NAT (``<forward mode='route'/>``), or connected directly to one routed with no NAT (``<forward mode='route'/>``), or connected directly to one
of the host's network interfaces (via macvtap) or bridge devices of the host's network interfaces (via macvtap) or bridge devices
(``<forward mode='bridge|private|vepa|passthrough'/>`` :since:`Since (``<forward mode='bridge|private|vepa|passthrough'/>`` :since:`Since 0.9.4`)
0.9.4` )
For networks with a forward mode of bridge, private, vepa, and passthrough, it 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 is assumed that the host has any necessary DNS and DHCP services already setup
@ -4840,8 +4847,8 @@ automatically during startup and shutdown. :since:`Since 5.1.0`
Also, similar to ``direct`` network connections (described below), a connection Also, similar to ``direct`` network connections (described below), a connection
of type ``network`` may specify a ``virtualport`` element, with configuration of type ``network`` may specify a ``virtualport`` element, with configuration
data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant switch ( 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 :since:`Since 0.8.2` ), or to an Open vSwitch virtual switch
0.9.11` ). ( :since:`Since 0.9.11` ).
Since the actual type of switch may vary depending on the configuration in the Since the actual type of switch may vary depending on the configuration in the
``<network>`` on the host, it is acceptable to omit the virtualport ``type`` ``<network>`` 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. libvirtd to have emulated network devices based on tap devices.
After creating/opening the tap device, an optional shell script (given in the After creating/opening the tap device, an optional shell script (given in the
``path`` attribute of the ``<script>`` element) will be run. :since:`Since ``path`` attribute of the ``<script>`` element) will be run.
0.2.1` Also, after detaching/closing the tap device, an optional shell script :since:`Since 0.2.1`
Also, after detaching/closing the tap device, an optional shell script
(given in the ``path`` attribute of the ``<downscript>`` element) will be run. (given in the ``path`` attribute of the ``<downscript>`` element) will be run.
:since:`Since 6.4.0` These can be used to do whatever extra host network :since:`Since 6.4.0` These can be used to do whatever extra host network
integration is required. integration is required.
@ -5256,8 +5264,8 @@ assignment (VFIO is a new method of device assignment that is compatible with
UEFI Secure Boot), a type='hostdev' interface can have an optional ``driver`` UEFI Secure Boot), a type='hostdev' interface can have an optional ``driver``
sub-element with a ``name`` attribute set to "vfio". To use legacy KVM device sub-element with a ``name`` attribute set to "vfio". To use legacy KVM device
assignment you can set ``name`` to "kvm" (the default is "vfio" on systems assignment you can set ``name`` to "kvm" (the default is "vfio" on systems
where the VFIO driver is available, and "kvm" on older systems. :since:`Since where the VFIO driver is available, and "kvm" on older systems.
1.1.3` (prior to that the default was always "kvm"). :since:`Since 1.1.3` (prior to that the default was always "kvm").
Note that this "intelligent passthrough" of network devices is very similar to Note that this "intelligent passthrough" of network devices is very similar to
the functionality of a standard <hostdev> device, the difference being that this the functionality of a standard <hostdev> device, the difference being that this
@ -5302,8 +5310,8 @@ uses a datapath that complies with the virtio specification but has a
vendor-specific control path. To use such a device with libvirt, the host vendor-specific control path. To use such a device with libvirt, the host
device must already be bound to the appropriate device-specific vDPA driver. device must already be bound to the appropriate device-specific vDPA driver.
This creates a vDPA char device (e.g. /dev/vhost-vdpa-0) that can be used to This creates a vDPA char device (e.g. /dev/vhost-vdpa-0) that can be used to
assign the device to a libvirt domain. :since:`Since 6.9.0 (QEMU only, assign the device to a libvirt domain.
requires QEMU 5.1.0 or newer)` :since:`Since 6.9.0 (QEMU only, requires QEMU 5.1.0 or newer)`
:: ::
@ -5499,8 +5507,8 @@ A UDP unicast architecture provides a virtual network which enables connections
between QEMU instances using QEMU's UDP infrastructure. The xml "source" address between QEMU instances using QEMU's UDP infrastructure. The xml "source" address
is the endpoint address to which the UDP socket packets will be sent from the is the endpoint address to which the UDP socket packets will be sent from the
host running QEMU. The xml "local" address is the address of the interface from host running QEMU. The xml "local" address is the address of the interface from
which the UDP socket packets will originate from the QEMU host. :since:`Since which the UDP socket packets will originate from the QEMU host.
1.2.20` :since:`Since 1.2.20`
:: ::
@ -5615,16 +5623,16 @@ following attributes are available for the ``virtio`` NIC driver:
backend, which requires the vhost module to be provided by the kernel); an backend, which requires the vhost module to be provided by the kernel); an
attempt to require the vhost driver without kernel support will be rejected. attempt to require the vhost driver without kernel support will be rejected.
If this attribute is not present, then the domain defaults to 'vhost' if If this attribute is not present, then the domain defaults to 'vhost' if
present, but silently falls back to 'qemu' without error. :since:`Since 0.8.8 present, but silently falls back to 'qemu' without error.
(QEMU and KVM only)` :since:`Since 0.8.8 (QEMU and KVM only)`
For interfaces of type='hostdev' (PCI passthrough devices) the ``name`` For interfaces of type='hostdev' (PCI passthrough devices) the ``name``
attribute can optionally be set to "vfio" or "kvm". "vfio" tells libvirt to attribute can optionally be set to "vfio" or "kvm". "vfio" tells libvirt to
use VFIO device assignment rather than traditional KVM device assignment use VFIO device assignment rather than traditional KVM device assignment
(VFIO is a new method of device assignment that is compatible with UEFI (VFIO is a new method of device assignment that is compatible with UEFI
Secure Boot), and "kvm" tells libvirt to use the legacy device assignment Secure Boot), and "kvm" tells libvirt to use the legacy device assignment
performed directly by the kvm kernel module (the default is currently "kvm", performed directly by the kvm kernel module (the default is currently "kvm",
but is subject to change). :since:`Since 1.0.5 (QEMU and KVM only, requires but is subject to change).
kernel 3.6 or newer)` :since:`Since 1.0.5 (QEMU and KVM only, requires kernel 3.6 or newer)`
For interfaces of type='vhostuser', the ``name`` attribute is ignored. The For interfaces of type='vhostuser', the ``name`` attribute is ignored. The
backend driver used is always vhost-user. backend driver used is always vhost-user.
``txmode`` ``txmode``
@ -5671,15 +5679,15 @@ following attributes are available for the ``virtio`` NIC driver:
processing queues requires the interface having the processing queues requires the interface having the
``<model type='virtio'/>`` element. Each queue will potentially be handled by ``<model type='virtio'/>`` element. Each queue will potentially be handled by
a different processor, resulting in much higher throughput. a different processor, resulting in much higher throughput.
:since:`virtio-net since 1.0.6 (QEMU and KVM only)` :since:`vhost-user since :since:`virtio-net since 1.0.6 (QEMU and KVM only)`
1.2.17 (QEMU and KVM only)` :since:`vhost-user since 1.2.17 (QEMU and KVM only)`
``rx_queue_size`` ``rx_queue_size``
The optional ``rx_queue_size`` attribute controls the size of virtio ring for The optional ``rx_queue_size`` attribute controls the size of virtio ring for
each queue as described above. The default value is hypervisor dependent and each queue as described above. The default value is hypervisor dependent and
may change across its releases. Moreover, some hypervisors may pose some may change across its releases. Moreover, some hypervisors may pose some
restrictions on actual value. For instance, latest QEMU (as of 2016-09-01) restrictions on actual value. For instance, latest QEMU (as of 2016-09-01)
requires value to be a power of two from [256, 1024] range. :since:`Since requires value to be a power of two from [256, 1024] range.
2.3.0 (QEMU and KVM only)` :since:`Since 2.3.0 (QEMU and KVM only)`
**In general you should leave this option alone, unless you are very certain **In general you should leave this option alone, unless you are very certain
you know what you are doing.** you know what you are doing.**
``tx_queue_size`` ``tx_queue_size``
@ -5939,7 +5947,7 @@ toplevel ``<vlan>`` element to differentiate trunking of a single tag from
normal tagging. normal tagging.
For network connections using Open vSwitch it is also possible to configure For network connections using Open vSwitch it is also possible to configure
'native-tagged' and 'native-untagged' VLAN modes :since:`Since 1.1.0.` This is 'native-tagged' and 'native-untagged' VLAN modes :since:`Since 1.1.0`. This is
done with the optional ``nativeMode`` attribute on the ``<tag>`` subelement: done with the optional ``nativeMode`` attribute on the ``<tag>`` subelement:
``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute of the ``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute of the
``<tag>`` subelement containing ``nativeMode`` sets which VLAN is considered to ``<tag>`` subelement containing ``nativeMode`` sets which VLAN is considered to
@ -5961,7 +5969,7 @@ Isolating guests' network traffic from each other
</devices> </devices>
... ...
:since:`Since 6.1.0.` The ``port`` element property ``isolated``, when set to :since:`Since 6.1.0`. The ``port`` element property ``isolated``, when set to
``yes`` (default setting is ``no``) is used to isolate this interface's network ``yes`` (default setting is ``no``) is used to isolate this interface's network
traffic from that of other guest interfaces connected to the same network that traffic from that of other guest interfaces connected to the same network that
also have ``<port isolated='yes'/>``. This setting is only supported for also have ``<port isolated='yes'/>``. This setting is only supported for
@ -6078,8 +6086,8 @@ the IP address. The optional ``prefix`` is the number of 1 bits in the netmask,
and will be automatically set if not specified - for IPv4 the default prefix is and will be automatically set if not specified - for IPv4 the default prefix is
determined according to the network "class" (A, B, or C - see RFC870), and for determined according to the network "class" (A, B, or C - see RFC870), and for
IPv6 the default prefix is 64. The optional ``peer`` attribute holds the IP IPv6 the default prefix is 64. The optional ``peer`` attribute holds the IP
address of the other end of a point-to-point network device :since:`(since address of the other end of a point-to-point network device
2.1.0)` . :since:`(since 2.1.0)`.
:since:`Since 1.2.12` route elements can also be added to define IP routes to :since:`Since 1.2.12` route elements can also be added to define IP routes to
add in the guest. The attributes of this element are described in the add in the guest. The attributes of this element are described in the
@ -6327,8 +6335,8 @@ interaction with the admin.
For VNC WebSocket functionality, ``websocket`` attribute may be used to For VNC WebSocket functionality, ``websocket`` attribute may be used to
specify port to listen on (with -1 meaning auto-allocation and specify port to listen on (with -1 meaning auto-allocation and
``autoport`` having no effect due to security reasons) :since:`Since ``autoport`` having no effect due to security reasons)
1.0.6` . :since:`Since 1.0.6`.
For VNC, the ``powerControl`` attribute can be used to enable VM shutdown, For VNC, the ``powerControl`` attribute can be used to enable VM shutdown,
reboot and reset power control features for the VNC client. This is reboot and reset power control features for the VNC client. This is
@ -6509,8 +6517,8 @@ interaction with the admin.
Graphics device uses a ``<listen>`` to set up where the device should listen for Graphics device uses a ``<listen>`` to set up where the device should listen for
clients. It has a mandatory attribute ``type`` which specifies the listen type. clients. It has a mandatory attribute ``type`` which specifies the listen type.
Only ``vnc``, ``spice`` and ``rdp`` supports ``<listen>`` element. :since:`Since Only ``vnc``, ``spice`` and ``rdp`` supports ``<listen>`` element.
0.9.4` . Available types are: :since:`Since 0.9.4`. Available types are:
``address`` ``address``
Tells a graphics device to use an address specified in the ``address`` Tells a graphics device to use an address specified in the ``address``
@ -6739,8 +6747,8 @@ For character device with type ``unix`` or ``tcp`` the ``source`` has an
optional element ``reconnect`` which configures reconnect timeout if the optional element ``reconnect`` which configures reconnect timeout if the
connection is lost. There are two attributes, ``enabled`` where possible values connection is lost. There are two attributes, ``enabled`` where possible values
are "yes" and "no" and ``timeout`` which is in seconds. The ``reconnect`` are "yes" and "no" and ``timeout`` which is in seconds. The ``reconnect``
attribute is valid only for ``connect`` mode. :since:`Since 3.7.0 (QEMU driver attribute is valid only for ``connect`` mode.
only)` . :since:`Since 3.7.0 (QEMU driver only)`.
Guest interface Guest interface
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
@ -7033,8 +7041,8 @@ types have different ``target`` attributes.
with attribute ``type='virtio'``; an optional attribute ``name`` controls how with attribute ``type='virtio'``; an optional attribute ``name`` controls how
the guest will have access to the channel, and defaults to the guest will have access to the channel, and defaults to
``name='com.redhat.spice.0'``. The optional ``address`` element can tie the ``name='com.redhat.spice.0'``. The optional ``address`` element can tie the
channel to a particular ``type='virtio-serial'`` controller. :since:`Since channel to a particular ``type='virtio-serial'`` controller.
0.8.8` :since:`Since 0.8.8`
``qemu-vdagent`` ``qemu-vdagent``
Paravirtualized qemu vdagent channel. This channel implements the SPICE Paravirtualized qemu vdagent channel. This channel implements the SPICE
vdagent protocol, but is handled internally by qemu and therefore does not vdagent protocol, but is handled internally by qemu and therefore does not
@ -7221,7 +7229,7 @@ Or as a TCP server waiting for a client connection.
Alternatively you can use ``telnet`` instead of ``raw`` TCP in order to utilize Alternatively you can use ``telnet`` instead of ``raw`` TCP in order to utilize
the telnet protocol for the connection. the telnet protocol for the connection.
:since:`Since 0.8.5,` some hypervisors support use of either ``telnets`` (secure :since:`Since 0.8.5`, some hypervisors support use of either ``telnets`` (secure
telnet) or ``tls`` (via secure sockets layer) as the transport protocol for telnet) or ``tls`` (via secure sockets layer) as the transport protocol for
connections. connections.
@ -7243,7 +7251,7 @@ connections.
</devices> </devices>
... ...
:since:`Since 2.4.0,` the optional attribute ``tls`` can be used to control :since:`Since 2.4.0`, the optional attribute ``tls`` can be used to control
whether a chardev TCP communication channel would utilize a hypervisor whether a chardev TCP communication channel would utilize a hypervisor
configured TLS X.509 certificate environment in order to encrypt the data configured TLS X.509 certificate environment in order to encrypt the data
channel. For the QEMU hypervisor, usage of a TLS environment can be controlled channel. For the QEMU hypervisor, usage of a TLS environment can be controlled
@ -7869,8 +7877,9 @@ Memory balloon device
A virtual memory balloon device is added to all Xen and KVM/QEMU guests. It will A virtual memory balloon device is added to all Xen and KVM/QEMU guests. It will
be seen as ``memballoon`` element. It will be automatically added when be seen as ``memballoon`` element. It will be automatically added when
appropriate, so there is no need to explicitly add this element in the guest XML appropriate, so there is no need to explicitly add this element in the guest XML
unless a specific PCI slot needs to be assigned. :since:`Since 0.8.3, Xen, QEMU unless a specific PCI slot needs to be assigned.
and KVM only` Additionally, :since:`since 0.8.4` , if the memballoon device :since:`Since 0.8.3, Xen, QEMU and KVM only`
Additionally, :since:`since 0.8.4`, if the memballoon device
needs to be explicitly disabled, ``model='none'`` may be used. needs to be explicitly disabled, ``model='none'`` may be used.
Example: automatically added device with KVM Example: automatically added device with KVM
@ -8002,8 +8011,8 @@ Example: usage of the RNG device:
``builtin`` ``builtin``
This backend uses qemu builtin random generator, which uses This backend uses qemu builtin random generator, which uses
``getrandom()`` syscall as the source of entropy. ( :since:`Since 6.1.0 ``getrandom()`` syscall as the source of entropy.
and QEMU 4.2` ) ( :since:`Since 6.1.0 and QEMU 4.2` )
``driver`` ``driver``
The subelement ``driver`` can be used to tune the device: The subelement ``driver`` can be used to tune the device:
@ -8189,8 +8198,8 @@ Example: usage of panic configuration
- 'isa' - for ISA pvpanic device - 'isa' - for ISA pvpanic device
- 'pseries' - default and valid only for pSeries guests. - 'pseries' - default and valid only for pSeries guests.
- 'hyperv' - for Hyper-V crash CPU feature. :since:`Since 1.3.0, QEMU and - 'hyperv' - for Hyper-V crash CPU feature.
KVM only` :since:`Since 1.3.0, QEMU and KVM only`
- 's390' - default for S390 guests. :since:`Since 1.3.5` - 's390' - default for S390 guests. :since:`Since 1.3.5`
- 'pvpanic' - for PCI pvpanic device :since:`Since 9.1.0, QEMU only` - 'pvpanic' - for PCI pvpanic device :since:`Since 9.1.0, QEMU only`
@ -8361,8 +8370,9 @@ Example: usage of the memory devices
... ...
``model`` ``model``
Provide ``dimm`` to add a virtual DIMM module to the guest. :since:`Since Provide ``dimm`` to add a virtual DIMM module to the guest.
1.2.14` Provide ``nvdimm`` model that adds a Non-Volatile DIMM module. :since:`Since 1.2.14`
Provide ``nvdimm`` model that adds a Non-Volatile DIMM module.
:since:`Since 3.2.0` Provide ``virtio-pmem`` model to add a paravirtualized :since:`Since 3.2.0` Provide ``virtio-pmem`` model to add a paravirtualized
persistent memory device. :since:`Since 7.1.0` Provide ``virtio-mem`` model persistent memory device. :since:`Since 7.1.0` Provide ``virtio-mem`` model
to add paravirtualized memory device. :since:`Since 7.9.0` Provide to add paravirtualized memory device. :since:`Since 7.9.0` Provide
@ -8477,8 +8487,8 @@ Example: usage of the memory devices
``readonly`` ``readonly``
The ``readonly`` element is used to mark the vNVDIMM as read-only. Only The ``readonly`` element is used to mark the vNVDIMM as read-only. Only
the real NVDIMM device backend can guarantee the guest write persistence, the real NVDIMM device backend can guarantee the guest write persistence,
so other backend types should use the ``readonly`` element. :since:`Since so other backend types should use the ``readonly`` element.
5.0.0` :since:`Since 5.0.0`
``block`` ``block``
For ``virtio-mem`` only. For ``virtio-mem`` only.
@ -8499,8 +8509,8 @@ Example: usage of the memory devices
``address`` ``address``
For ``virtio-mem`` and ``virtio-pmem`` only. For ``virtio-mem`` and ``virtio-pmem`` only.
The physical address in memory, where device is mapped. :since:`Since The physical address in memory, where device is mapped.
9.4.0` :since:`Since 9.4.0`
IOMMU devices IOMMU devices

31
docs/formatnetwork.rst
View File

@ -42,8 +42,8 @@ The first elements provide basic metadata about the virtual network.
The content of the ``name`` element provides a short name for the virtual The content of the ``name`` element provides a short name for the virtual
network. This name should consist only of alphanumeric characters and is network. This name should consist only of alphanumeric characters and is
required to be unique within the scope of a single host. It is used to form required to be unique within the scope of a single host. It is used to form
the filename for storing the persistent configuration file. :since:`Since the filename for storing the persistent configuration file.
0.3.0` :since:`Since 0.3.0`
``uuid`` ``uuid``
The content of the ``uuid`` element provides a globally unique identifier for The content of the ``uuid`` element provides a globally unique identifier for
the virtual network. The format must be RFC 4122 compliant, eg the virtual network. The format must be RFC 4122 compliant, eg
@ -170,7 +170,7 @@ to the physical LAN (if at all).
``forward`` ``forward``
Inclusion of the ``forward`` element indicates that the virtual network is to Inclusion of the ``forward`` element indicates that the virtual network is to
be connected to the physical LAN. :since:`Since 0.3.0.` The ``mode`` be connected to the physical LAN. :since:`Since 0.3.0`. The ``mode``
attribute determines the method of forwarding. If there is no ``forward`` attribute determines the method of forwarding. If there is no ``forward``
element, the network will be isolated from any other network (unless a guest element, the network will be isolated from any other network (unless a guest
connected to that network is acting as a router, of course). The following connected to that network is acting as a router, of course). The following
@ -287,8 +287,8 @@ to the physical LAN (if at all).
802.1Qbh-capable hardware switch), each physical interface can only be in 802.1Qbh-capable hardware switch), each physical interface can only be in
use by a single guest interface at a time; in modes other than 802.1Qbh, use by a single guest interface at a time; in modes other than 802.1Qbh,
multiple guest interfaces can share each physical interface (libvirt will multiple guest interfaces can share each physical interface (libvirt will
attempt to balance usage between all available interfaces). :since:`Since attempt to balance usage between all available interfaces).
0.9.4` :since:`Since 0.9.4`
``vepa`` ``vepa``
This network uses a macvtap "direct" connection in "vepa" mode to connect This network uses a macvtap "direct" connection in "vepa" mode to connect
each guest to the network (this requires that the physical interfaces used each guest to the network (this requires that the physical interfaces used
@ -319,8 +319,8 @@ to the physical LAN (if at all).
single-port PCI ethernet card driver design - only SR-IOV (Single Root I/O single-port PCI ethernet card driver design - only SR-IOV (Single Root I/O
Virtualization) virtual function (VF) devices can be assigned in this Virtualization) virtual function (VF) devices can be assigned in this
manner; to assign a standard single-port PCI or PCIe ethernet card to a manner; to assign a standard single-port PCI or PCIe ethernet card to a
guest, use the traditional ``<hostdev>`` device definition. :since:` Since guest, use the traditional ``<hostdev>`` device definition.
0.10.0` :since:`Since 0.10.0`
To force use of a particular device-specific VFIO driver when To force use of a particular device-specific VFIO driver when
assigning the devices to a guest, a <forward type='hostdev'> assigning the devices to a guest, a <forward type='hostdev'>
@ -536,7 +536,7 @@ toplevel ``<vlan>`` element to differentiate trunking of a single tag from
normal tagging. normal tagging.
For network connections using Open vSwitch it is also possible to configure For network connections using Open vSwitch it is also possible to configure
'native-tagged' and 'native-untagged' VLAN modes :since:`Since 1.1.0.` This is 'native-tagged' and 'native-untagged' VLAN modes :since:`Since 1.1.0`. This is
done with the optional ``nativeMode`` attribute on the ``<tag>`` subelement: done with the optional ``nativeMode`` attribute on the ``<tag>`` subelement:
``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute of the ``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute of the
``<tag>`` subelement containing ``nativeMode`` sets which VLAN is considered to ``<tag>`` subelement containing ``nativeMode`` sets which VLAN is considered to
@ -562,7 +562,7 @@ Isolating ports from one another
<port isolated='yes'/> <port isolated='yes'/>
</network> </network>
:since:`Since 6.1.0.` The ``port`` element property ``isolated``, when set to :since:`Since 6.1.0`. The ``port`` element property ``isolated``, when set to
``yes`` (default setting is ``no``) is used to isolate the network traffic of ``yes`` (default setting is ``no``) is used to isolate the network traffic of
each guest on the network from all other guests connected to the network; it each guest on the network from all other guests connected to the network; it
does not have an effect on communication between the guests and the host, or does not have an effect on communication between the guests and the host, or
@ -731,8 +731,9 @@ of 'route' or 'nat'.
The dns element of a network contains configuration information for the The dns element of a network contains configuration information for the
virtual network's DNS server :since:`Since 0.9.3`. virtual network's DNS server :since:`Since 0.9.3`.
The dns element can have an optional ``enable`` attribute :since:`Since The dns element can have an optional ``enable`` attribute
2.2.0` . If ``enable`` is "no", then no DNS server will be setup by libvirt :since:`Since 2.2.0`.
If ``enable`` is "no", then no DNS server will be setup by libvirt
for this network (and any other configuration in ``<dns>`` will be ignored). for this network (and any other configuration in ``<dns>`` will be ignored).
If ``enable`` is "yes" or unspecified (including the complete absence of any If ``enable`` is "yes" or unspecified (including the complete absence of any
``<dns>`` element) then a DNS server will be setup by libvirt to listen on ``<dns>`` element) then a DNS server will be setup by libvirt to listen on
@ -848,15 +849,15 @@ of 'route' or 'nat'.
which the boot image will be fetched. ``server`` defaults to the same 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`` 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 element is used. The BOOTP options currently have to be the same for
all address ranges and statically assigned addresses. :since:`Since all address ranges and statically assigned addresses.
0.7.1` :since:`Since 0.7.1`
Optionally, ``range`` and ``host`` elements can have ``lease`` child Optionally, ``range`` and ``host`` elements can have ``lease`` child
element which specifies the lease time through it's attributes ``expiry`` element which specifies the lease time through it's attributes ``expiry``
and ``unit`` (which accepts ``seconds``, ``minutes`` and ``hours`` and and ``unit`` (which accepts ``seconds``, ``minutes`` and ``hours`` and
defaults to ``minutes`` if omitted). The minimal lease time is 2 minutes, defaults to ``minutes`` if omitted). The minimal lease time is 2 minutes,
except when setting an infinite lease time (``expiry='0'``). :since:`Since except when setting an infinite lease time (``expiry='0'``).
6.3.0` :since:`Since 6.3.0`
Network namespaces Network namespaces
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~

2
docs/formatnetworkport.rst
View File

@ -90,7 +90,7 @@ The following elements are common to one or more of the plug types listed later
connection on the host - currently it is only supported for the virtio device connection on the host - currently it is only supported for the virtio device
model and for macvtap connections on the host. model and for macvtap connections on the host.
``port`` ``port``
:since:`Since 6.1.0.` The ``port`` element property ``isolated``, when set to :since:`Since 6.1.0`. The ``port`` element property ``isolated``, when set to
``yes`` (default setting is ``no``) is used to isolate this port's network ``yes`` (default setting is ``no``) is used to isolate this port's network
traffic from other ports on the same network that also have traffic from other ports on the same network that also have
``<port isolated='yes'/>``. This setting is only supported for emulated ``<port isolated='yes'/>``. This setting is only supported for emulated

4
docs/formatnode.rst
View File

@ -367,8 +367,8 @@ S390 architecture. Sub-elements include:
``vdpa`` ``vdpa``
^^^^^^^^ ^^^^^^^^
Describes a virtual datapath acceleration (vDPA) network device. :since:`Since Describes a virtual datapath acceleration (vDPA) network device.
6.9.0` . Sub-elements include: :since:`Since 6.9.0`. Sub-elements include:
``chardev`` ``chardev``
The path to the character device that is used to access the device. The path to the character device that is used to access the device.

112
docs/formatnwfilter.rst
View File

@ -593,8 +593,8 @@ Note: Rules of this type should go into the ``root`` chain.
| protocolid | UINT16 (0x600-0xffff), | Layer 3 protocol ID | | protocolid | UINT16 (0x600-0xffff), | Layer 3 protocol ID |
| | STRING | | | | STRING | |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 | | comment | STRING | text with max. 256 |
| 0.8.5)` | | characters | | :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
Valid Strings for ``protocolid`` are: arp, rarp, ipv4, ipv6 Valid Strings for ``protocolid`` are: arp, rarp, ipv4, ipv6
@ -710,20 +710,20 @@ chain.
| arpsrcipaddr | IP_ADDR | Source IP address in | | arpsrcipaddr | IP_ADDR | Source IP address in |
| | | ARP/RARP packet | | | | ARP/RARP packet |
+-----------------------------+----------------+-----------------------------+ +-----------------------------+----------------+-----------------------------+
| arpsrcipmask :since:`(Since | IP_MASK | Source IP mask | | arpsrcipmask | IP_MASK | Source IP mask |
| 1.2.3)` | | | | :since:`(Since 1.2.3)` | | |
+-----------------------------+----------------+-----------------------------+ +-----------------------------+----------------+-----------------------------+
| arpdstipaddr | IP_ADDR | Destination IP address in | | arpdstipaddr | IP_ADDR | Destination IP address in |
| | | ARP/RARP packet | | | | ARP/RARP packet |
+-----------------------------+----------------+-----------------------------+ +-----------------------------+----------------+-----------------------------+
| arpdstipmask :since:`(Since | IP_MASK | Destination IP mask | | arpdstipmask | IP_MASK | Destination IP mask |
| 1.2.3)` | | | | :since:`(Since 1.2.3)` | | |
+-----------------------------+----------------+-----------------------------+ +-----------------------------+----------------+-----------------------------+
| comment :since:`(Since | STRING | text with max. 256 | | comment | STRING | text with max. 256 |
| 0.8.5)` | | characters | | :since:`(Since 0.8.5)` | | characters |
+-----------------------------+----------------+-----------------------------+ +-----------------------------+----------------+-----------------------------+
| gratuitous :since:`(Since | BOOLEAN | boolean indicating whether | | gratuitous | BOOLEAN | boolean indicating whether |
| 0.9.2)` | | to check for gratuitous ARP | | :since:`(Since 0.9.2)` | | to check for gratuitous ARP |
| | | packet | | | | packet |
+-----------------------------+----------------+-----------------------------+ +-----------------------------+----------------+-----------------------------+
@ -783,8 +783,8 @@ Note: Rules of this type should either go into the ``root`` or ``ipv4`` chain.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | | dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point | | | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 | | comment | STRING | text with max. 256 |
| 0.8.5)` | | characters | | :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
Valid strings for ``protocol`` are: tcp, udp, udplite, esp, ah, icmp, igmp, sctp Valid strings for ``protocol`` are: tcp, udp, udplite, esp, ah, icmp, igmp, sctp
@ -839,8 +839,8 @@ Note: Rules of this type should either go into the ``root`` or ``ipv6`` chain.
| | | ``protocol`` to be set to | | | | ``protocol`` to be set to |
| | | ``icmpv6`` | | | | ``icmpv6`` |
+--------------------------------+-----------+--------------------------------+ +--------------------------------+-----------+--------------------------------+
| typeend :since:`(Since | UINT8 | ICMPv6 type end of range; | | typeend | UINT8 | ICMPv6 type end of range; |
| 1.2.12)` | | requires ``protocol`` to be | | :since:`(Since 1.2.12)` | | requires ``protocol`` to be |
| | | set to ``icmpv6`` | | | | set to ``icmpv6`` |
+--------------------------------+-----------+--------------------------------+ +--------------------------------+-----------+--------------------------------+
| code :since:`(Since 1.2.12)` | UINT8 | ICMPv6 code; requires | | code :since:`(Since 1.2.12)` | UINT8 | ICMPv6 code; requires |
@ -906,23 +906,23 @@ be omitted or set to ``root``.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | | dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point | | | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 | | comment | STRING | text with max. 256 |
| 0.8.5)` | | characters | | :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| state :since:`(Since | STRING | comma separated list of | | state | STRING | comma separated list of |
| 0.8.5)` | | NEW, ESTABLISHED, | | :since:`(Since 0.8.5)` | | NEW, ESTABLISHED, |
| | | RELATED, INVALID | | | | RELATED, INVALID |
| | | or NONE | | | | or NONE |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| flags :since:`(Since | STRING | TCP-only: format of | | flags | STRING | TCP-only: format of |
| 0.9.1)` | | mask/flags with mask | | :since:`(Sinc 0.9.1)` | | mask/flags with mask |
| | | and flags each being a | | | | and flags each being a |
| | | comma separated list of | | | | comma separated list of |
| | | SYN,ACK,URG,PSH,FIN,RST | | | | SYN,ACK,URG,PSH,FIN,RST |
| | | or NONE or ALL | | | | or NONE or ALL |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| ipset :since:`(Since | STRING | The name of an IPSet | | ipset | STRING | The name of an IPSet |
| 0.9.13)` | | managed outside of | | :since:`(Since 0.9.13)` | | managed outside of |
| | | libvirt | | | | libvirt |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| ipsetflags | IPSETFLAGS | flags for the IPSet; | | ipsetflags | IPSETFLAGS | flags for the IPSet; |
@ -981,16 +981,16 @@ be omitted or set to ``root``.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | | dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point | | | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 | | comment | STRING | text with max. 256 |
| 0.8.5)` | | characters | | :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| state :since:`(Since | STRING | comma separated list of | | state | STRING | comma separated list of |
| 0.8.5)` | | NEW, ESTABLISHED, | | :since:`(Since 0.8.5)` | | NEW, ESTABLISHED, |
| | | RELATED, INVALID | | | | RELATED, INVALID |
| | | or NONE | | | | or NONE |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| ipset :since:`(Since | STRING | The name of an IPSet | | ipset | STRING | The name of an IPSet |
| 0.9.13)` | | managed outside of | | :since:`(Since 0.9.13)` | | managed outside of |
| | | libvirt | | | | libvirt |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| ipsetflags | IPSETFLAGS | flags for the IPSet; | | ipsetflags | IPSETFLAGS | flags for the IPSet; |
@ -1045,16 +1045,16 @@ be omitted or set to ``root``.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | | dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point | | | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 | | comment | STRING | text with max. 256 |
| 0.8.5)` | | characters | | :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| state :since:`(Since | STRING | comma separated list of | | state | STRING | comma separated list of |
| 0.8.5)` | | NEW, ESTABLISHED, | | :since:`(Since 0.8.5)` | | NEW, ESTABLISHED, |
| | | RELATED, INVALID | | | | RELATED, INVALID |
| | | or NONE | | | | or NONE |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| ipset :since:`(Since | STRING | The name of an IPSet | | ipset | STRING | The name of an IPSet |
| 0.9.13)` | | managed outside of | | :since:`(Since 0.9.13)` | | managed outside of |
| | | libvirt | | | | libvirt |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| ipsetflags | IPSETFLAGS | flags for the IPSet; | | ipsetflags | IPSETFLAGS | flags for the IPSet; |
@ -1112,23 +1112,23 @@ be omitted or set to ``root``.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | | dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point | | | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 | | comment | STRING | text with max. 256 |
| 0.8.5)` | | characters | | :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| state :since:`(Since | STRING | comma separated list of | | state | STRING | comma separated list of |
| 0.8.5)` | | NEW, ESTABLISHED, | | :since:`(Since 0.8.5)` | | NEW, ESTABLISHED, |
| | | RELATED, INVALID | | | | RELATED, INVALID |
| | | or NONE | | | | or NONE |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| flags :since:`(Since | STRING | TCP-only: format of | | flags | STRING | TCP-only: format of |
| 0.9.1)` | | mask/flags with mask | | :since:`(Since 0.9.1)` | | mask/flags with mask |
| | | and flags each being a | | | | and flags each being a |
| | | comma separated list of | | | | comma separated list of |
| | | SYN,ACK,URG,PSH,FIN,RST | | | | SYN,ACK,URG,PSH,FIN,RST |
| | | or NONE or ALL | | | | or NONE or ALL |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| ipset :since:`(Since | STRING | The name of an IPSet | | ipset | STRING | The name of an IPSet |
| 0.9.13)` | | managed outside of | | :since:`(Since 0.9.13)` | | managed outside of |
| | | libvirt | | | | libvirt |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| ipsetflags | IPSETFLAGS | flags for the IPSet; | | ipsetflags | IPSETFLAGS | flags for the IPSet; |
@ -1180,16 +1180,16 @@ be omitted or set to ``root``.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | | dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point | | | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 | | comment | STRING | text with max. 256 |
| 0.8.5)` | | characters | | :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| state :since:`(Since | STRING | comma separated list of | | state | STRING | comma separated list of |
| 0.8.5)` | | NEW, ESTABLISHED, | | :since:`(Since 0.8.5)` | | NEW, ESTABLISHED, |
| | | RELATED, INVALID | | | | RELATED, INVALID |
| | | or NONE | | | | or NONE |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| ipset :since:`(Since | STRING | The name of an IPSet | | ipset | STRING | The name of an IPSet |
| 0.9.13)` | | managed outside of | | :since:`(Since 0.9.13)` | | managed outside of |
| | | libvirt | | | | libvirt |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| ipsetflags | IPSETFLAGS | flags for the IPSet; | | ipsetflags | IPSETFLAGS | flags for the IPSet; |
@ -1237,16 +1237,16 @@ be omitted or set to ``root``.
| dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services | | dscp | UINT8 (0x0-0x3f, 0 - | Differentiated Services |
| | 63) | Code Point | | | 63) | Code Point |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| comment :since:`(Since | STRING | text with max. 256 | | comment | STRING | text with max. 256 |
| 0.8.5)` | | characters | | :since:`(Since 0.8.5)` | | characters |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| state :since:`(Since | STRING | comma separated list of | | state | STRING | comma separated list of |
| 0.8.5)` | | NEW, ESTABLISHED, | | :since:`(Since 0.8.5)` | | NEW, ESTABLISHED, |
| | | RELATED, INVALID | | | | RELATED, INVALID |
| | | or NONE | | | | or NONE |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| ipset :since:`(Since | STRING | The name of an IPSet | | ipset | STRING | The name of an IPSet |
| 0.9.13)` | | managed outside of | | :since:`(Since 0.9.13)` | | managed outside of |
| | | libvirt | | | | libvirt |
+-------------------------+-------------------------+-------------------------+ +-------------------------+-------------------------+-------------------------+
| ipsetflags | IPSETFLAGS | flags for the IPSet; | | ipsetflags | IPSETFLAGS | flags for the IPSet; |
@ -1632,8 +1632,8 @@ connection, thus we want to allow it to let packets pass the firewall. The
outgoing TCP connection for the ftp data path. Afterwards, the state to compare outgoing TCP connection for the ftp data path. Afterwards, the state to compare
against is ``ESTABLISHED``, which then applies equally to the incoming and against is ``ESTABLISHED``, which then applies equally to the incoming and
outgoing direction. All this is related to the ftp data traffic originating from outgoing direction. All this is related to the ftp data traffic originating from
TCP port 20 of the VM. This then leads to the following solution :since:`(since TCP port 20 of the VM. This then leads to the following solution
0.8.5 (QEMU, KVM))` : :since:`(since 0.8.5 (QEMU, KVM))` :
:: ::

4
docs/formatsnapshot.rst
View File

@ -199,8 +199,8 @@ The top-level ``domainsnapshot`` element may contain the following elements:
uuid; reverting to a snapshot like this is risky if the current state of the uuid; reverting to a snapshot like this is risky if the current state of the
domain differs from the state that the domain was created in, and requires domain differs from the state that the domain was created in, and requires
the use of the ``VIR_DOMAIN_SNAPSHOT_REVERT_FORCE`` flag in the use of the ``VIR_DOMAIN_SNAPSHOT_REVERT_FORCE`` flag in
``virDomainRevertToSnapshot()``. Newer versions of libvirt ( :since:`since ``virDomainRevertToSnapshot()``. Newer versions of libvirt
0.9.5` ) store the entire inactive `domain configuration (:since:`since 0.9.5`) store the entire inactive `domain configuration
<formatdomain.html>`__ at the time of the snapshot ( :since:`since 0.9.5` ). <formatdomain.html>`__ at the time of the snapshot ( :since:`since 0.9.5` ).
The domain will have security-sensitive information omitted unless the flag The domain will have security-sensitive information omitted unless the flag
``VIR_DOMAIN_SNAPSHOT_XML_SECURE`` is provided on a read-write connection. ``VIR_DOMAIN_SNAPSHOT_XML_SECURE`` is provided on a read-write connection.

29
docs/formatstorage.rst
View File

@ -48,8 +48,8 @@ Storage pool general metadata
``allocation`` ``allocation``
Providing the total storage allocation for the pool. This may be larger than Providing the total storage allocation for the pool. This may be larger than
the sum of the allocation of all volumes due to metadata overhead. This value the sum of the allocation of all volumes due to metadata overhead. This value
is in bytes. This is not applicable when creating a pool. :since:`Since is in bytes. This is not applicable when creating a pool.
0.4.1` :since:`Since 0.4.1`
``capacity`` ``capacity``
Providing the total storage capacity for the pool. Due to underlying device Providing the total storage capacity for the pool. Due to underlying device
constraints it may not be possible to use the full capacity for storage constraints it may not be possible to use the full capacity for storage
@ -201,8 +201,8 @@ following child elements:
"scsi_host". To keep backwards compatibility, this attribute is optional "scsi_host". To keep backwards compatibility, this attribute is optional
**only** for the "scsi_host" adapter, but is mandatory for the "fc_host" **only** for the "scsi_host" adapter, but is mandatory for the "fc_host"
adapter. :since:`Since 1.0.5` A "fc_host" capable scsi_hostN can be adapter. :since:`Since 1.0.5` A "fc_host" capable scsi_hostN can be
determined by using ``virsh nodedev-list --cap fc_host``. :since:`Since determined by using ``virsh nodedev-list --cap fc_host``.
1.2.8` :since:`Since 1.2.8`
Note: Regardless of whether a "scsi_host" adapter type is defined using a Note: Regardless of whether a "scsi_host" adapter type is defined using a
``name`` or a ``parentaddr``, it should refer to a real scsi_host adapter ``name`` or a ``parentaddr``, it should refer to a real scsi_host adapter
@ -360,8 +360,8 @@ following child elements:
:since:`Since 0.8.4` :since:`Since 0.8.4`
``product`` ``product``
Provides an optional product name of the storage device. This contains a Provides an optional product name of the storage device. This contains a
single attribute ``name`` whose value is backend specific. :since:`Since single attribute ``name`` whose value is backend specific.
0.8.4` :since:`Since 0.8.4`
Storage pool target elements Storage pool target elements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -504,7 +504,7 @@ option in libvirt, and thus should never be used in production.
</pool> </pool>
... ...
:since:`Since 5.1.0.` :since:`Since 5.1.0`.
``rbd:config_opts`` ``rbd:config_opts``
Provides an XML namespace mechanism to optionally utilize specifically named Provides an XML namespace mechanism to optionally utilize specifically named
@ -545,13 +545,14 @@ option in libvirt, and thus should never be used in production.
</rbd:config_opts> </rbd:config_opts>
</pool> </pool>
:since:`Since 5.1.0.` :since:`Since 5.1.0`.
Storage volume XML Storage volume XML
------------------ ------------------
A storage volume will generally be either a file or a device node; :since:`since A storage volume will generally be either a file or a device node;
1.2.0` , an optional output-only attribute ``type`` lists the actual type (file, :since:`since 1.2.0`, an optional output-only attribute ``type`` lists
the actual type (file,
block, dir, network, netdir or ploop), which is also available from block, dir, network, netdir or ploop), which is also available from
``virStorageVolGetInfo()``. The storage volume XML format is available ``virStorageVolGetInfo()``. The storage volume XML format is available
:since:`since 0.4.1` :since:`since 0.4.1`
@ -609,12 +610,12 @@ Storage volume general metadata
``capacity`` ``capacity``
Providing the logical capacity for the volume. This value is in bytes by Providing the logical capacity for the volume. This value is in bytes by
default, but a ``unit`` attribute can be specified with the same semantics as default, but a ``unit`` attribute can be specified with the same semantics as
for ``allocation`` This is compulsory when creating a volume. :since:`Since for ``allocation`` This is compulsory when creating a volume.
0.4.1` :since:`Since 0.4.1`
``physical`` ``physical``
This output only element provides the host physical size of the target This output only element provides the host physical size of the target
storage volume. The default output ``unit`` will be in bytes. :since:`Since storage volume. The default output ``unit`` will be in bytes.
3.0.0` :since:`Since 3.0.0`
``source`` ``source``
Provides information about the underlying storage allocation of the volume. Provides information about the underlying storage allocation of the volume.
This may not be available for some pool types. :since:`Since 0.4.1` This may not be available for some pool types. :since:`Since 0.4.1`

4
docs/formatstorageencryption.rst
View File

@ -46,7 +46,7 @@ it using the specified ``uuid``.
``qcow`` format ``qcow`` format
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
:since:`Since 4.5.0,` encryption formats ``default`` and ``qcow`` may no longer :since:`Since 4.5.0`, encryption formats ``default`` and ``qcow`` may no longer
be used to create an encrypted volume. Usage of qcow encrypted volumes in QEMU be used to create an encrypted volume. Usage of qcow encrypted volumes in QEMU
began phasing out in QEMU 2.3 and by QEMU 2.9 creation of a qcow encrypted began phasing out in QEMU 2.3 and by QEMU 2.9 creation of a qcow encrypted
volume via qemu-img required usage of secret objects, but that support was not volume via qemu-img required usage of secret objects, but that support was not
@ -133,7 +133,7 @@ domain volume definition:
</encryption> </encryption>
Here is an example specifying use of the ``luks`` format for a specific cipher Here is an example specifying use of the ``luks`` format for a specific cipher
algorithm for volume creation. :since:`Since 6.10.0,` the ``target`` format can algorithm for volume creation. :since:`Since 6.10.0`, the ``target`` format can
also support ``qcow2`` type with ``luks`` encryption. also support ``qcow2`` type with ``luks`` encryption.
:: ::