: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
``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
``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
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
~~~~~~~~~~~~~~
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``
: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
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
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
(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
(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
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
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
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
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
: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
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:
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``.
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`
::
``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
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 <html/libvirt-libvirt-domain.html#virDomainSetLifecycleAction>`__
API.
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``
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``
``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)
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``.
``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.
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
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
``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
``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 <formatdomaincaps.html#backingstoreinput>`__ (
:since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored on
``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``
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.
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
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 <https://patchwork.kernel.org/patch/43390/>`__ for
disk device. The default is left to the discretion of the hypervisor.
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".
- 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")
`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
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
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 <kbase/virtiofs.html>`__
``template``
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
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:
usable for people who run the hypervisor as non-root. `More
info <https://lists.gnu.org/archive/html/qemu-devel/2010-09/msg00121.html>`__
- :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.
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
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
``<address type='pci'/>`` 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).
``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
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
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``
``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``
"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.
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.
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``
("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>`` 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
attributes and subelements listed below. These are configurable items that 1)
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
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
``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 ``<node>``
subelement within the ``<target>`` subelement, which is used to set the NUMA
node reported to the guest OS for that bus - the guest OS will then know that
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
``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.
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
``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:
``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'``
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
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.
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
``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 ``<driver>`` 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 ``<driver>`` element's ``model``
attribute, for example::
...
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
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`:
::
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)`:
::
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 ``<mac/>`` element. Note that this attribute is useless if the provided
MAC address is outside of the reserved VMWare ranges.
explicit network device or to the default route (``<forward mode='nat'>``),
routed with no NAT (``<forward mode='route'/>``), or connected directly to one
of the host's network interfaces (via macvtap) or bridge devices
-(``<forward mode='bridge|private|vepa|passthrough'/>`` :since:`Since
-0.9.4` )
+(``<forward mode='bridge|private|vepa|passthrough'/>`` :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
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
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
``<network>`` on the host, it is acceptable to omit the virtualport ``type``
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 ``<script>`` element) will be run. :since:`Since
-0.2.1` Also, after detaching/closing the tap device, an optional shell script
+``path`` attribute of the ``<script>`` element) will be run.
+: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.
:since:`Since 6.4.0` These can be used to do whatever extra host network
integration is required.
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
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
-1.1.3` (prior to that the default was always "kvm").
+where the VFIO driver is available, and "kvm" on older systems.
+: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
the functionality of a standard <hostdev> device, the difference being that this
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.
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,
-requires QEMU 5.1.0 or newer)`
+assign the device to a libvirt domain.
+:since:`Since 6.9.0 (QEMU only, requires QEMU 5.1.0 or newer)`
::
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
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
-1.2.20`
+which the UDP socket packets will originate from the QEMU host.
+:since:`Since 1.2.20`
::
qemu-kvm -net nic,model=? /dev/null
Typical values for QEMU and KVM include: ne2k_isa i82551 i82557b i82559er
-ne2k_pci pcnet rtl8139 e1000 virtio. :since:`Since 5.2.0` ,
+ne2k_pci pcnet rtl8139 e1000 virtio. :since:`Since 5.2.0`,
``virtio-transitional`` and ``virtio-non-transitional`` values are supported.
See `Virtio transitional devices`_ for more details.
:since:`Since 9.3.0` igb is also supported.
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.
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
- (QEMU and KVM only)`
+ present, but silently falls back to 'qemu' without error.
+ :since:`Since 0.8.8 (QEMU and KVM only)`
For interfaces of type='hostdev' (PCI passthrough devices) the ``name``
attribute can optionally be set to "vfio" or "kvm". "vfio" tells libvirt to
use VFIO device assignment rather than traditional KVM device assignment
(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
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
- kernel 3.6 or newer)`
+ but is subject to change).
+ :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
backend driver used is always vhost-user.
``txmode``
processing queues requires the interface having the
``<model type='virtio'/>`` element. Each queue will potentially be handled by
a different processor, resulting in much higher throughput.
- :since:`virtio-net since 1.0.6 (QEMU and KVM only)` :since:`vhost-user since
- 1.2.17 (QEMU and KVM only)`
+ :since:`virtio-net since 1.0.6 (QEMU and KVM only)`
+ :since:`vhost-user since 1.2.17 (QEMU and KVM only)`
``rx_queue_size``
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
may change across its releases. Moreover, some hypervisors may pose some
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
- 2.3.0 (QEMU and KVM only)`
+ requires value to be a power of two from [256, 1024] range.
+ :since:`Since 2.3.0 (QEMU and KVM only)`
**In general you should leave this option alone, unless you are very certain
you know what you are doing.**
``tx_queue_size``
specified targets using these prefixes may be ignored.
Note that for LXC containers, this defines the name of the interface on the host
-side. :since:`Since 1.2.7` , to define the name of the device on the guest side,
+side. :since:`Since 1.2.7`, to define the name of the device on the guest side,
the ``guest`` element should be used, as in the following snippet:
::
while newer qemus have a default of "on"). The optional ``file`` attribute is
used to point to a binary file to be presented to the guest as the device's ROM
BIOS. This can be useful to provide an alternative boot ROM for a network
-device. :since:`Since 0.9.10 (QEMU and KVM only)` .
+device. :since:`Since 0.9.10 (QEMU and KVM only)`.
Setting up a network backend in a driver domain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If (and only if) the network connection used by the guest supports VLAN tagging
transparent to the guest, an optional ``<vlan>`` element can specify one or more
-VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` .
+VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0`.
Network connections that support guest-transparent VLAN tagging include
``type='bridge'`` interfaces connected to an Open vSwitch bridge, SRIOV
normal tagging.
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:
``nativeMode`` may be set to 'tagged' or 'untagged'. The ``id`` attribute of the
``<tag>`` subelement containing ``nativeMode`` sets which VLAN is considered to
</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
traffic from that of other guest interfaces connected to the same network that
also have ``<port isolated='yes'/>``. This setting is only supported for
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
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
-2.1.0)` .
+address of the other end of a point-to-point network device
+:since:`(since 2.1.0)`.
: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
``shift-shift``, ``meta-meta``, ``scrolllock`` or ``ctrl-scrolllock`` to
change the grab key combination.
``input`` type ``evdev`` is currently supported only on linux devices.
-(KVM only) :since:`Since 5.2.0` , the ``input`` element accepts a
+(KVM only) :since:`Since 5.2.0`, the ``input`` element accepts a
``model`` attribute which has the values 'virtio', 'virtio-transitional' and
'virtio-non-transitional'. See `Virtio transitional devices`_ for more details.
of the password by giving a timestamp
``passwdValidTo='2010-04-09T15:51:00'`` assumed to be in UTC. The
``connected`` attribute allows control of connected client during password
- changes. VNC accepts ``keep`` value only :since:`since 0.9.3` . NB, this
+ changes. VNC accepts ``keep`` value only :since:`since 0.9.3`. NB, this
may not be supported by all hypervisors.
The optional ``sharePolicy`` attribute specifies vnc server display
-Shared switch). This is the default value. ``force-shared`` disables
exclusive client access, every connection has to specify -Shared switch
for vncviewer. ``ignore`` welcomes every connection unconditionally
- :since:`since 1.0.6` .
+ :since:`since 1.0.6`.
Rather than using listen/port, QEMU supports a ``socket`` attribute for
- listening on a unix domain socket path :since:`Since 0.8.8` .
+ listening on a unix domain socket path :since:`Since 0.8.8`.
For VNC WebSocket functionality, ``websocket`` attribute may be used to
specify port to listen on (with -1 meaning auto-allocation and
- ``autoport`` having no effect due to security reasons) :since:`Since
- 1.0.6` .
+ ``autoport`` having no effect due to security reasons)
+ :since:`Since 1.0.6`.
For VNC, the ``powerControl`` attribute can be used to enable VM shutdown,
reboot and reset power control features for the VNC client. This is
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.
-Only ``vnc``, ``spice`` and ``rdp`` supports ``<listen>`` element. :since:`Since
-0.9.4` . Available types are:
+Only ``vnc``, ``spice`` and ``rdp`` supports ``<listen>`` element.
+:since:`Since 0.9.4`. Available types are:
``address``
Tells a graphics device to use an address specified in the ``address``
resolved to an IP address via a DNS query) to listen on.
It is possible to omit the ``address`` attribute in order to use an address
- from config files :since:`Since 1.3.5` .
+ from config files :since:`Since 1.3.5`.
The ``address`` attribute is duplicated as ``listen`` attribute in
``graphics`` element for backward compatibility. If both are provided they
data between the guest and host. Note that blob resource support requires
QEMU version 6.1 or newer.
- :since:`Since 5.9.0` , the ``model`` element may also have an optional
+ :since:`Since 5.9.0`, the ``model`` element may also have an optional
``resolution`` sub-element. The ``resolution`` element has attributes ``x``
and ``y`` to set the minimum resolution for the video device. This
sub-element is valid for model types "vga", "qxl", "bochs", "gop",
``accel2d``
Enable 2D acceleration (for vbox driver only, :since:`since 0.7.1` )
``accel3d``
- Enable 3D acceleration (for vbox driver :since:`since 0.7.1` , qemu driver
+ Enable 3D acceleration (for vbox driver :since:`since 0.7.1`, qemu driver
:since:`since 1.3.0` )
``rendernode``
Absolute path to a host's DRI device to be used for rendering (for
If the interface ``type`` presented to the host is "file", then the ``source``
element may contain an optional attribute ``append`` that specifies whether or
not the information in the file should be preserved on domain restart. Allowed
-values are "on" and "off" (default). :since:`Since 1.3.1` .
+values are "on" and "off" (default). :since:`Since 1.3.1`.
Regardless of the ``type``, character devices can have an optional log file
associated with them. This is expressed via a ``log`` sub-element, with a
``file`` attribute. There can also be an ``append`` attribute which takes the
-same values described above. :since:`Since 1.3.3` .
+same values described above. :since:`Since 1.3.3`.
::
optional element ``reconnect`` which configures reconnect timeout if the
connection is lost. There are two attributes, ``enabled`` where possible values
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
-only)` .
+attribute is valid only for ``connect`` mode.
+:since:`Since 3.7.0 (QEMU driver only)`.
Guest interface
^^^^^^^^^^^^^^^
The ``target`` element can have an optional ``port`` attribute, which specifies
the port number (starting from 0), and an optional ``type`` attribute: valid
-values are, :since:`since 1.0.2` , ``isa-serial`` (usable with x86 guests),
+values are, :since:`since 1.0.2`, ``isa-serial`` (usable with x86 guests),
``usb-serial`` (usable whenever USB support is available) and ``pci-serial``
-(usable whenever PCI support is available); :since:`since 3.10.0` ,
+(usable whenever PCI support is available); :since:`since 3.10.0`,
``spapr-vio-serial`` (usable with ppc64/pseries guests), ``system-serial``
-(usable with aarch64/virt and, :since:`since 4.7.0` , riscv/virt guests),
+(usable with aarch64/virt and, :since:`since 4.7.0`, riscv/virt guests),
``sclp-serial`` (usable with s390 and s390x guests) are available as well
and :since:`since 8.1.0` ``isa-debug`` (usable with x86 guests).
-:since:`Since 3.10.0` , the ``target`` element can have an optional ``model``
+:since:`Since 3.10.0`, the ``target`` element can have an optional ``model``
subelement; valid values for its ``name`` attribute are: ``isa-serial`` (usable
with the ``isa-serial`` target type); ``usb-serial`` (usable with the
``usb-serial`` target type); ``pci-serial`` (usable with the ``pci-serial``
target type); ``spapr-vty`` (usable with the ``spapr-vio-serial`` target type);
-``pl011`` and, :since:`since 4.7.0` , ``16550a`` (usable with the
+``pl011`` and, :since:`since 4.7.0`, ``16550a`` (usable with the
``system-serial`` target type); ``sclpconsole`` and ``sclplmconsole`` (usable
with the ``sclp-serial`` target type). :since:`Since: 8.1.0`, ``isa-debugcon``
(usable with the ``isa-debug`` target type); provides a virtual console for
with attribute ``type='virtio'``; an optional attribute ``name`` controls how
the guest will have access to the channel, and defaults to
``name='com.redhat.spice.0'``. The optional ``address`` element can tie the
- channel to a particular ``type='virtio-serial'`` controller. :since:`Since
- 0.8.8`
+ channel to a particular ``type='virtio-serial'`` controller.
+ :since:`Since 0.8.8`
``qemu-vdagent``
Paravirtualized qemu vdagent channel. This channel implements the SPICE
vdagent protocol, but is handled internally by qemu and therefore does not
Alternatively you can use ``telnet`` instead of ``raw`` TCP in order to utilize
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
connections.
</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
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
``ich9`` (:since:`Since 1.1.3`), ``usb`` (:since:`Since 1.2.8`) and ``ich7``
(:since:`Since 6.7.0`, bhyve only).
-:since:`Since 0.9.13` , a sound element with ``ich6`` or ``ich9`` models can have
+:since:`Since 0.9.13`, a sound element with ``ich6`` or ``ich9`` models can have
optional sub-elements ``<codec>`` to attach various audio codecs to the audio
device. If not specified, a default codec will be attached to allow playback
and recording.
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
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
-and KVM only` Additionally, :since:`since 0.8.4` , if the memballoon device
+unless a specific PCI slot needs to be assigned.
+: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.
Example: automatically added device with KVM
``builtin``
This backend uses qemu builtin random generator, which uses
- ``getrandom()`` syscall as the source of entropy. ( :since:`Since 6.1.0
- and QEMU 4.2` )
+ ``getrandom()`` syscall as the source of entropy.
+ ( :since:`Since 6.1.0 and QEMU 4.2` )
``driver``
The subelement ``driver`` can be used to tune the device:
``model``
The ``model`` attribute specifies what device model QEMU provides to the
guest. If no model name is provided, ``tpm-tis`` will automatically be chosen
- for non-PPC64 architectures. :since:`Since 4.4.0` , another available choice
+ for non-PPC64 architectures. :since:`Since 4.4.0`, another available choice
is the ``tpm-crb``, which should only be used when the backend device is a
- TPM 2.0. :since:`Since 6.1.0` , pSeries guests on PPC64 are supported and the
- default is ``tpm-spapr``. :since:`Since 6.5.0` , a new model called
+ TPM 2.0. :since:`Since 6.1.0`, pSeries guests on PPC64 are supported and the
+ default is ``tpm-spapr``. :since:`Since 6.5.0`, a new model called
``spapr-tpm-proxy`` was added for pSeries guests. This model only works with
the ``passthrough`` backend. It creates a TPM Proxy device that communicates
with an existing TPM Resource Manager in the host, for example
This backend type requires exclusive access to a TPM device on the host.
An example for such a device is /dev/tpm0. The fully qualified file name
is specified by path attribute of the ``source`` element. If no file name
- is specified then /dev/tpm0 is automatically used. :since:`Since 6.5.0` ,
+ is specified then /dev/tpm0 is automatically used. :since:`Since 6.5.0`,
when choosing the ``spapr-tpm-proxy`` model, the file name specified is
expected to be a TPM Resource Manager device, e.g. ``/dev/tpmrm0``.
- 'isa' - for ISA pvpanic device
- 'pseries' - default and valid only for pSeries guests.
- - 'hyperv' - for Hyper-V crash CPU feature. :since:`Since 1.3.0, QEMU and
- KVM only`
+ - 'hyperv' - for Hyper-V crash CPU feature.
+ :since:`Since 1.3.0, QEMU and KVM only`
- 's390' - default for S390 guests. :since:`Since 1.3.5`
- 'pvpanic' - for PCI pvpanic device :since:`Since 9.1.0, QEMU only`
...
``model``
- Provide ``dimm`` to add a virtual DIMM module to the guest. :since:`Since
- 1.2.14` Provide ``nvdimm`` model that adds a Non-Volatile DIMM module.
+ Provide ``dimm`` to add a virtual DIMM module to the guest.
+ :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
persistent memory device. :since:`Since 7.1.0` Provide ``virtio-mem`` model
to add paravirtualized memory device. :since:`Since 7.9.0` Provide
``readonly``
The ``readonly`` element is used to mark the vNVDIMM as read-only. Only
the real NVDIMM device backend can guarantee the guest write persistence,
- so other backend types should use the ``readonly`` element. :since:`Since
- 5.0.0`
+ so other backend types should use the ``readonly`` element.
+ :since:`Since 5.0.0`
``block``
For ``virtio-mem`` only.
``address``
For ``virtio-mem`` and ``virtio-pmem`` only.
- The physical address in memory, where device is mapped. :since:`Since
- 9.4.0`
+ The physical address in memory, where device is mapped.
+ :since:`Since 9.4.0`
IOMMU devices
file lives on NFS or other file system that lacks security labeling) or
requesting an alternate label (useful when a management application creates a
special label to allow sharing of some, but not all, resources between domains),
-:since:`since 0.9.9` . When a ``seclabel`` element is attached to a specific
+:since:`since 0.9.9`. When a ``seclabel`` element is attached to a specific
path rather than the top-level domain assignment, only the attribute ``relabel``
-or the sub-element ``label`` are supported. Additionally, :since:`since 1.1.2` ,
+or the sub-element ``label`` are supported. Additionally, :since:`since 1.1.2`,
an output-only element ``labelskip`` will be present for active domains on disks
where labeling was skipped due to the image being on a file system that lacks
security labeling.
``/etc/libvirt/hooks/``. Other Linux distributions may do this differently.
- If your installation of libvirt has instead been compiled from source, it is
likely to be ``/usr/local/etc/libvirt/hooks/``.
-- :since:`Since 6.5.0` , you can also place several hook scripts in the
+- :since:`Since 6.5.0`, you can also place several hook scripts in the
directories ``/etc/libvirt/hooks/<driver>.d/``.
To use hook scripts, you will need to create this ``hooks`` directory manually,
Executed when a network is started or stopped or an interface is
plugged/unplugged to/from the network
-:since:`Since 6.5.0` , you can also have several scripts with any name in the
+:since:`Since 6.5.0`, you can also have several scripts with any name in the
directories ``/etc/libvirt/hooks/<driver>.d/``. They are executed in
alphabetical order after main script.
- Before a QEMU guest is started, the qemu hook script is called in three
locations; if any location fails, the guest is not started. The first
- location, :since:`since 0.9.0` , is before libvirt performs any resource
+ location, :since:`since 0.9.0`, is before libvirt performs any resource
labeling, and the hook can allocate resources not managed by libvirt such
as DRBD or missing bridges. This is called as:
/etc/libvirt/hooks/qemu guest_name prepare begin -
- The second location, available :since:`Since 0.8.0` , occurs after libvirt
+ The second location, available :since:`Since 0.8.0`, occurs after libvirt
has finished labeling all resources, but has not yet started the guest,
called as:
/etc/libvirt/hooks/qemu guest_name start begin -
- The third location, :since:`0.9.13` , occurs after the QEMU process has
+ The third location, :since:`0.9.13`, occurs after the QEMU process has
successfully started up:
::
/etc/libvirt/hooks/qemu guest_name started begin -
- When a QEMU guest is stopped, the qemu hook script is called in two
- locations, to match the startup. First, :since:`since 0.8.0` , the hook is
+ locations, to match the startup. First, :since:`since 0.8.0`, the hook is
called before libvirt restores any labels:
::
/etc/libvirt/hooks/qemu guest_name stopped end -
Then, after libvirt has released all resources, the hook is called again,
- :since:`since 0.9.0` , to allow any additional resource cleanup:
+ :since:`since 0.9.0`, to allow any additional resource cleanup:
::
/etc/libvirt/hooks/qemu guest_name release end -
-- :since:`Since 0.9.11` , the qemu hook script is also called at the beginning
+- :since:`Since 0.9.11`, the qemu hook script is also called at the beginning
of incoming migration. It is called as:
::
is not valid, incoming migration will be canceled. This hook may be used,
e.g., to change location of disk images for incoming domains.
-- :since:`Since 1.2.9` , the qemu hook script is also called when restoring a
+- :since:`Since 1.2.9`, the qemu hook script is also called when restoring a
saved image either via the API or automatically when restoring a managed save
machine. It is called as:
is not valid, restore of the image will be aborted. This hook may be used,
e.g., to change location of disk images for restored domains.
-- :since:`Since 6.5.0` , you can also place several hook scripts in the
+- :since:`Since 6.5.0`, you can also place several hook scripts in the
directory ``/etc/libvirt/hooks/qemu.d/``. They are executed in alphabetical
order after main script. In this case each script also acts as filter and can
modify the domain XML and print it out on its standard output. This script
case any script returns failure common process will be aborted, but all
scripts from the directory will are executed.
-- :since:`Since 0.9.13` , the qemu hook script is also called when the libvirtd
+- :since:`Since 0.9.13`, the qemu hook script is also called when the libvirtd
daemon restarts and reconnects to previously running QEMU processes. If the
script fails, the existing QEMU process will be killed off. It is called as:
/etc/libvirt/hooks/qemu guest_name reconnect begin -
-- :since:`Since 0.9.13` , the qemu hook script is also called when the QEMU
+- :since:`Since 0.9.13`, the qemu hook script is also called when the QEMU
driver is told to attach to an externally launched QEMU process. It is called
as:
- Before a LXC guest is started, the lxc hook script is called in three
locations; if any location fails, the guest is not started. The first
- location, :since:`since 0.9.13` , is before libvirt performs any resource
+ location, :since:`since 0.9.13`, is before libvirt performs any resource
labeling, and the hook can allocate resources not managed by libvirt such
as DRBD or missing bridges. This is called as:
/etc/libvirt/hooks/lxc guest_name prepare begin -
- The second location, available :since:`Since 0.8.0` , occurs after libvirt
+ The second location, available :since:`Since 0.8.0`, occurs after libvirt
has finished labeling all resources, but has not yet started the guest,
called as:
/etc/libvirt/hooks/lxc guest_name start begin -
- The third location, :since:`0.9.13` , occurs after the LXC process has
+ The third location, :since:`0.9.13`, occurs after the LXC process has
successfully started up:
::
/etc/libvirt/hooks/lxc guest_name started begin -
- When a LXC guest is stopped, the lxc hook script is called in two
- locations, to match the startup. First, :since:`since 0.8.0` , the hook is
+ locations, to match the startup. First, :since:`since 0.8.0`, the hook is
called before libvirt restores any labels:
::
/etc/libvirt/hooks/lxc guest_name stopped end -
Then, after libvirt has released all resources, the hook is called again,
- :since:`since 0.9.0` , to allow any additional resource cleanup:
+ :since:`since 0.9.0`, to allow any additional resource cleanup:
::
/etc/libvirt/hooks/lxc guest_name release end -
-- :since:`Since 0.9.13` , the lxc hook script is also called when the libvirtd
+- :since:`Since 0.9.13`, the lxc hook script is also called when the libvirtd
daemon restarts and reconnects to previously running LXC processes. If the
script fails, the existing LXC process will be killed off. It is called as:
- Before a Xen guest is started using libxl driver, the libxl hook script is
called in three locations; if any location fails, the guest is not started.
- The first location, :since:`since 2.1.0` , is before libvirt performs any
+ The first location, :since:`since 2.1.0`, is before libvirt performs any
resource labeling, and the hook can allocate resources not managed by
libvirt. This is called as:
/etc/libvirt/hooks/libxl guest_name prepare begin -
- The second location, available :since:`Since 2.1.0` , occurs after libvirt
+ The second location, available :since:`Since 2.1.0`, occurs after libvirt
has finished labeling all resources, but has not yet started the guest,
called as:
/etc/libvirt/hooks/libxl guest_name start begin -
- The third location, :since:`2.1.0` , occurs after the domain has
+ The third location, :since:`2.1.0`, occurs after the domain has
successfully started up:
::
/etc/libvirt/hooks/libxl guest_name started begin -
- When a libxl-handled Xen guest is stopped, the libxl hook script is called
- in two locations, to match the startup. First, :since:`since 2.1.0` , the
+ in two locations, to match the startup. First, :since:`since 2.1.0`, the
hook is called before libvirt restores any labels:
::
/etc/libvirt/hooks/libxl guest_name stopped end -
Then, after libvirt has released all resources, the hook is called again,
- :since:`since 2.1.0` , to allow any additional resource cleanup:
+ :since:`since 2.1.0`, to allow any additional resource cleanup:
::
/etc/libvirt/hooks/libxl guest_name release end -
-- :since:`Since 2.1.0` , the libxl hook script is also called at the beginning
+- :since:`Since 2.1.0`, the libxl hook script is also called at the beginning
of incoming migration. It is called as:
::
is not valid, incoming migration will be canceled. This hook may be used,
e.g., to change location of disk images for incoming domains.
-- :since:`Since 6.5.0` , you can also place several hook scripts in the
+- :since:`Since 6.5.0`, you can also place several hook scripts in the
directory ``/etc/libvirt/hooks/libxl.d/``. They are executed in alphabetical
order after main script. In this case each script also acts as filter and can
modify the domain XML and print it out on its standard output. This script
case any script returns failure common process will be aborted, but all
scripts from the directory will are executed.
-- :since:`Since 2.1.0` , the libxl hook script is also called when the libvirtd
+- :since:`Since 2.1.0`, the libxl hook script is also called when the libvirtd
daemon restarts and reconnects to previously running Xen domains. If the
script fails, the existing Xen domains will be killed off. It is called as:
- Before an bhyve guest is started, the bhyve hook script is called in three
locations; if any location fails, the guest is not started. The first
- location, :since:`since 6.1.0` , is before libvirt performs any resource
+ location, :since:`since 6.1.0`, is before libvirt performs any resource
labeling, and the hook can allocate resources not managed by libvirt. This is
called as:
/etc/libvirt/hooks/bhyve guest_name prepare begin -
- The second location, available :since:`Since 6.1.0` , occurs after libvirt
+ The second location, available :since:`Since 6.1.0`, occurs after libvirt
has finished labeling all resources, but has not yet started the guest,
called as:
/etc/libvirt/hooks/bhyve guest_name start begin -
- The third location, :since:`6.1.0` , occurs after the bhyve process has
+ The third location, :since:`6.1.0`, occurs after the bhyve process has
successfully started up:
::
/etc/libvirt/hooks/bhyve guest_name started begin -
- When an bhyve guest is stopped, the bhyve hook script is called in two
- locations, to match the startup. First, :since:`since 6.1.0` , the hook is
+ locations, to match the startup. First, :since:`since 6.1.0`, the hook is
called before libvirt restores any labels:
::
/etc/libvirt/hooks/bhyve guest_name stopped end -
Then, after libvirt has released all resources, the hook is called again,
- :since:`since 6.1.0` , to allow any additional resource cleanup:
+ :since:`since 6.1.0`, to allow any additional resource cleanup:
::
/etc/libvirt/hooks/network
^^^^^^^^^^^^^^^^^^^^^^^^^^
-- :since:`Since 1.2.2` , before a network is started, this script is called
+- :since:`Since 1.2.2`, before a network is started, this script is called
as:
::
projects / thirdparty / libvirt.git / commitdiff
