[RFC PATCH 4/5] docs: formatdomain: Split out <devices> section
Peter Krempa
pkrempa at redhat.com
Tue Jul 14 15:07:39 UTC 2020
Start splitting the massive document into smaller pieces using the
.. include:: directive.
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/formatdomain-devices.rst.in | 5051 +++++++++++++++++++++++++++++
docs/formatdomain.rst | 5052 +-----------------------------
2 files changed, 5052 insertions(+), 5051 deletions(-)
create mode 100644 docs/formatdomain-devices.rst.in
diff --git a/docs/formatdomain-devices.rst.in b/docs/formatdomain-devices.rst.in
new file mode 100644
index 0000000000..935794980c
--- /dev/null
+++ b/docs/formatdomain-devices.rst.in
@@ -0,0 +1,5051 @@
+:anchor:`<a id="elementsDevices"/>`
+
+Devices
+-------
+
+The final set of XML elements are all used to describe devices provided to the
+guest domain. All devices occur as children of the main ``devices`` element.
+:since:`Since 0.1.3`
+
+::
+
+ ...
+ <devices>
+ <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
+ </devices>
+ ...
+
+``emulator``
+ The contents of the ``emulator`` element specify the fully qualified path to
+ the device model emulator binary. The `capabilities XML <formatcaps.html>`__
+ specifies the recommended default emulator to use for each particular domain
+ type / architecture combination.
+
+To help users identifying devices they care about, every device can have direct
+child ``alias`` element which then has ``name`` attribute where users can store
+identifier for the device. The identifier has to have "ua-" prefix and must be
+unique within the domain. Additionally, the identifier must consist only of the
+following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
+
+::
+
+ <devices>
+ <disk type='file'>
+ <alias name='ua-myDisk'/>
+ </disk>
+ <interface type='network' trustGuestRxFilters='yes'>
+ <alias name='ua-myNIC'/>
+ </interface>
+ ...
+ </devices>
+
+:anchor:`<a id="elementsDisks"/>`
+
+Hard drives, floppy disks, CDROMs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Any device that looks like a disk, be it a floppy, harddisk, cdrom, or
+paravirtualized driver is specified via the ``disk`` element.
+
+::
+
+ ...
+ <devices>
+ <disk type='file' snapshot='external'>
+ <driver name="tap" type="aio" cache="default"/>
+ <source file='/var/lib/xen/images/fv0' startupPolicy='optional'>
+ <seclabel relabel='no'/>
+ </source>
+ <target dev='hda' bus='ide'/>
+ <iotune>
+ <total_bytes_sec>10000000</total_bytes_sec>
+ <read_iops_sec>400000</read_iops_sec>
+ <write_iops_sec>100000</write_iops_sec>
+ </iotune>
+ <boot order='2'/>
+ <encryption type='...'>
+ ...
+ </encryption>
+ <shareable/>
+ <serial>
+ ...
+ </serial>
+ </disk>
+ ...
+ <disk type='network'>
+ <driver name="qemu" type="raw" io="threads" ioeventfd="on" event_idx="off"/>
+ <source protocol="sheepdog" name="image_name">
+ <host name="hostname" port="7000"/>
+ </source>
+ <target dev="hdb" bus="ide"/>
+ <boot order='1'/>
+ <transient/>
+ <address type='drive' controller='0' bus='1' unit='0'/>
+ </disk>
+ <disk type='network'>
+ <driver name="qemu" type="raw"/>
+ <source protocol="rbd" name="image_name2">
+ <host name="hostname" port="7000"/>
+ <snapshot name="snapname"/>
+ <config file="/path/to/file"/>
+ <auth username='myuser'>
+ <secret type='ceph' usage='mypassid'/>
+ </auth>
+ </source>
+ <target dev="hdc" bus="ide"/>
+ </disk>
+ <disk type='block' device='cdrom'>
+ <driver name='qemu' type='raw'/>
+ <target dev='hdd' bus='ide' tray='open'/>
+ <readonly/>
+ </disk>
+ <disk type='network' device='cdrom'>
+ <driver name='qemu' type='raw'/>
+ <source protocol="http" name="url_path" query="foo=bar&baz=flurb>
+ <host name="hostname" port="80"/>
+ <cookies>
+ <cookie name="test">somevalue</cookie>
+ </cookies>
+ <readahead size='65536'/>
+ <timeout seconds='6'/>
+ </source>
+ <target dev='hde' bus='ide' tray='open'/>
+ <readonly/>
+ </disk>
+ <disk type='network' device='cdrom'>
+ <driver name='qemu' type='raw'/>
+ <source protocol="https" name="url_path">
+ <host name="hostname" port="443"/>
+ <ssl verify="no"/>
+ </source>
+ <target dev='hdf' bus='ide' tray='open'/>
+ <readonly/>
+ </disk>
+ <disk type='network' device='cdrom'>
+ <driver name='qemu' type='raw'/>
+ <source protocol="ftp" name="url_path">
+ <host name="hostname" port="21"/>
+ </source>
+ <target dev='hdg' bus='ide' tray='open'/>
+ <readonly/>
+ </disk>
+ <disk type='network' device='cdrom'>
+ <driver name='qemu' type='raw'/>
+ <source protocol="ftps" name="url_path">
+ <host name="hostname" port="990"/>
+ </source>
+ <target dev='hdh' bus='ide' tray='open'/>
+ <readonly/>
+ </disk>
+ <disk type='network' device='cdrom'>
+ <driver name='qemu' type='raw'/>
+ <source protocol="tftp" name="url_path">
+ <host name="hostname" port="69"/>
+ </source>
+ <target dev='hdi' bus='ide' tray='open'/>
+ <readonly/>
+ </disk>
+ <disk type='block' device='lun'>
+ <driver name='qemu' type='raw'/>
+ <source dev='/dev/sda'>
+ <slices>
+ <slice type='storage' offset='12345' size='123'/>
+ </slices>
+ <reservations managed='no'>
+ <source type='unix' path='/path/to/qemu-pr-helper' mode='client'/>
+ </reservations>
+ </source>
+ <target dev='sda' bus='scsi'/>
+ <address type='drive' controller='0' bus='0' target='3' unit='0'/>
+ </disk>
+ <disk type='block' device='disk'>
+ <driver name='qemu' type='raw'/>
+ <source dev='/dev/sda'/>
+ <geometry cyls='16383' heads='16' secs='63' trans='lba'/>
+ <blockio logical_block_size='512' physical_block_size='4096'/>
+ <target dev='hdj' bus='ide'/>
+ </disk>
+ <disk type='volume' device='disk'>
+ <driver name='qemu' type='raw'/>
+ <source pool='blk-pool0' volume='blk-pool0-vol0'/>
+ <target dev='hdk' bus='ide'/>
+ </disk>
+ <disk type='network' device='disk'>
+ <driver name='qemu' type='raw'/>
+ <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/2'>
+ <host name='example.com' port='3260'/>
+ <auth username='myuser'>
+ <secret type='iscsi' usage='libvirtiscsi'/>
+ </auth>
+ </source>
+ <target dev='vda' bus='virtio'/>
+ </disk>
+ <disk type='network' device='lun'>
+ <driver name='qemu' type='raw'/>
+ <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/1'>
+ <host name='example.com' port='3260'/>
+ <auth username='myuser'>
+ <secret type='iscsi' usage='libvirtiscsi'/>
+ </auth>
+ </source>
+ <target dev='sdb' bus='scsi'/>
+ </disk>
+ <disk type='network' device='lun'>
+ <driver name='qemu' type='raw'/>
+ <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/0'>
+ <host name='example.com' port='3260'/>
+ <initiator>
+ <iqn name='iqn.2013-07.com.example:client'/>
+ </initiator>
+ </source>
+ <target dev='sdb' bus='scsi'/>
+ </disk>
+ <disk type='volume' device='disk'>
+ <driver name='qemu' type='raw'/>
+ <source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/>
+ <target dev='vdb' bus='virtio'/>
+ </disk>
+ <disk type='volume' device='disk'>
+ <driver name='qemu' type='raw'/>
+ <source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/>
+ <target dev='vdc' bus='virtio'/>
+ </disk>
+ <disk type='file' device='disk'>
+ <driver name='qemu' type='qcow2' queues='4'/>
+ <source file='/var/lib/libvirt/images/domain.qcow'/>
+ <backingStore type='file'>
+ <format type='qcow2'/>
+ <source file='/var/lib/libvirt/images/snapshot.qcow'/>
+ <backingStore type='block'>
+ <format type='raw'/>
+ <source dev='/dev/mapper/base'/>
+ <backingStore/>
+ </backingStore>
+ </backingStore>
+ <target dev='vdd' bus='virtio'/>
+ </disk>
+ <disk type='nvme' device='disk'>
+ <driver name='qemu' type='raw'/>
+ <source type='pci' managed='yes' namespace='1'>
+ <address domain='0x0000' bus='0x01' slot='0x00' function='0x0'/>
+ </source>
+ <target dev='vde' bus='virtio'/>
+ </disk>
+ </devices>
+ ...
+
+``disk``
+ The ``disk`` element is the main container for describing disks and supports
+ the following attributes:
+
+ ``type``
+ Valid values are "file", "block", "dir" ( :since:`since 0.7.5` ),
+ "network" ( :since:`since 0.8.7` ), or "volume" ( :since:`since 1.0.5` ),
+ or "nvme" ( :since:`since 6.0.0` ) and refer to the underlying source for
+ the disk. :since:`Since 0.0.3`
+ ``device``
+ Indicates how the disk is to be exposed to the guest OS. Possible values
+ for this attribute are "floppy", "disk", "cdrom", and "lun", defaulting to
+ "disk".
+
+ Using "lun" ( :since:`since 0.9.10` ) is only valid when the ``type`` is
+ "block" or "network" for ``protocol='iscsi'`` or when the ``type`` is
+ "volume" when using an iSCSI source ``pool`` for ``mode`` "host" or as an
+ `NPIV <http://wiki.libvirt.org/page/NPIV_in_libvirt>`__ virtual Host Bus
+ Adapter (vHBA) using a Fibre Channel storage pool. Configured in this
+ manner, the LUN behaves identically to "disk", except that generic SCSI
+ commands from the guest are accepted and passed through to the physical
+ device. Also note that device='lun' will only be recognized for actual raw
+ devices, but never for individual partitions or LVM partitions (in those
+ cases, the kernel will reject the generic SCSI commands, making it
+ identical to device='disk'). :since:`Since 0.1.4`
+
+ ``model``
+ Indicates the emulated device model of the disk. Typically this is
+ indicated solely by the ``bus`` property but for ``bus`` "virtio" the
+ model can be specified further with "virtio-transitional",
+ "virtio-non-transitional", or "virtio". See `Virtio transitional
+ devices <#elementsVirtioTransitional>`__ for more details. :since:`Since
+ 5.2.0`
+ ``rawio``
+ Indicates whether the disk needs rawio capability. Valid settings are
+ "yes" or "no" (default is "no"). If any one disk in a domain has
+ rawio='yes', rawio capability will be enabled for all disks in the domain
+ (because, in the case of QEMU, this capability can only be set on a
+ per-process basis). This attribute is only valid when device is "lun". NB,
+ ``rawio`` intends to confine the capability per-device, however, current
+ QEMU implementation gives the domain process broader capability than that
+ (per-process basis, affects all the domain disks). To confine the
+ capability as much as possible for QEMU driver as this stage, ``sgio`` is
+ recommended, it's more secure than ``rawio``. :since:`Since 0.9.10`
+ ``sgio``
+ If supported by the hypervisor and OS, indicates whether unprivileged
+ SG_IO commands are filtered for the disk. Valid settings are "filtered" or
+ "unfiltered" where the default is "filtered". Only available when the
+ ``device`` is 'lun'. :since:`Since 1.0.2`
+ ``snapshot``
+ Indicates the default behavior of the disk during disk snapshots:
+ "``internal``" requires a file format such as qcow2 that can store both
+ the snapshot and the data changes since the snapshot; "``external``" will
+ separate the snapshot from the live data; and "``no``" means the disk will
+ not participate in snapshots. Read-only disks default to "``no``", while
+ the default for other disks depends on the hypervisor's capabilities. Some
+ hypervisors allow a per-snapshot choice as well, during `domain snapshot
+ creation <formatsnapshot.html>`__. Not all snapshot modes are supported;
+ for example, enabling snapshots with a transient disk generally does not
+ make sense. :since:`Since 0.9.5`
+
+``source``
+ Representation of the disk ``source`` depends on the disk ``type`` attribute
+ value as follows:
+
+ ``file``
+ The ``file`` attribute specifies the fully-qualified path to the file
+ holding the disk. :since:`Since 0.0.3`
+ ``block``
+ The ``dev`` attribute specifies the fully-qualified path to the host
+ device to serve as the disk. :since:`Since 0.0.3`
+ ``dir``
+ The ``dir`` attribute specifies the fully-qualified path to the directory
+ to use as the disk. :since:`Since 0.7.5`
+ ``network``
+ The ``protocol`` attribute specifies the protocol to access to the
+ requested image. Possible values are "nbd", "iscsi", "rbd", "sheepdog",
+ "gluster", "vxhs", "http", "https", "ftp", ftps", or "tftp".
+
+ For any ``protocol`` other than ``nbd`` an additional attribute ``name``
+ is mandatory to specify which volume/image will be used.
+
+ For "nbd", the ``name`` attribute is optional. TLS transport for NBD can
+ be enabled by setting the ``tls`` attribute to ``yes``. For the QEMU
+ hypervisor, usage of a TLS environment can also be globally controlled on
+ the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` in
+ /etc/libvirt/qemu.conf. ('tls' :since:`Since 4.5.0` )
+
+ For protocols ``http`` and ``https`` an optional attribute ``query``
+ specifies the query string. ( :since:`Since 6.2.0` )
+
+ For "iscsi" ( :since:`since 1.0.4` ), the ``name`` attribute may include a
+ logical unit number, separated from the target's name by a slash (e.g.,
+ ``iqn.2013-07.com.example:iscsi-pool/1``). If not specified, the default
+ LUN is zero.
+
+ For "vxhs" ( :since:`since 3.8.0` ), the ``name`` is the UUID of the
+ volume, assigned by the HyperScale server. Additionally, an optional
+ attribute ``tls`` (QEMU only) can be used to control whether a VxHS block
+ device 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 also be globally controlled on the host by
+ the ``vxhs_tls`` and ``vxhs_tls_x509_cert_dir`` or
+ ``default_tls_x509_cert_dir`` settings in the file /etc/libvirt/qemu.conf.
+ If ``vxhs_tls`` is enabled, then unless the domain ``tls`` attribute is
+ set to "no", libvirt will use the host configured TLS environment. If the
+ ``tls`` attribute is set to "yes", then regardless of the qemu.conf
+ setting, TLS authentication will be attempted.
+
+ :since:`Since 0.8.7`
+
+ ``volume``
+ The underlying disk source is represented by attributes ``pool`` and
+ ``volume``. Attribute ``pool`` specifies the name of the `storage
+ pool <formatstorage.html>`__ (managed by libvirt) where the disk source
+ resides. Attribute ``volume`` specifies the name of storage volume
+ (managed by libvirt) used as the disk source. The value for the ``volume``
+ attribute will be the output from the "Name" column of a
+ ``virsh vol-list [pool-name]`` command.
+
+ Use the attribute ``mode`` ( :since:`since 1.1.1` ) to indicate how to
+ represent the LUN as the disk source. Valid values are "direct" and
+ "host". If ``mode`` is not specified, the default is to use "host". Using
+ "direct" as the ``mode`` value indicates to use the `storage
+ pool's <formatstorage.html>`__ ``source`` element ``host`` attribute as
+ the disk source to generate the libiscsi URI (e.g.
+ 'file=iscsi://example.com:3260/iqn.2013-07.com.example:iscsi-pool/1').
+ Using "host" as the ``mode`` value indicates to use the LUN's path as it
+ shows up on host (e.g.
+ 'file=/dev/disk/by-path/ip-example.com:3260-iscsi-iqn.2013-07.com.example:iscsi-pool-lun-1').
+ Using a LUN from an iSCSI source pool provides the same features as a
+ ``disk`` configured using ``type`` 'block' or 'network' and ``device`` of
+ 'lun' with respect to how the LUN is presented to and may be used by the
+ guest. :since:`Since 1.0.5`
+
+ ``nvme``
+ To specify disk source for NVMe disk the ``source`` element has the
+ following attributes:
+
+ ``type``
+ The type of address specified in ``address`` sub-element. Currently,
+ only ``pci`` value is accepted.
+ ``managed``
+ This attribute instructs libvirt to detach NVMe controller
+ automatically on domain startup (``yes``) or expect the controller to
+ be detached by system administrator (``no``).
+ ``namespace``
+ The namespace ID which should be assigned to the domain. According to
+ NVMe standard, namespace numbers start from 1, including.
+
+ The difference between ``<disk type='nvme'>`` and ``<hostdev/>`` is that
+ the latter is plain host device assignment with all its limitations (e.g.
+ no live migration), while the former makes hypervisor to run the NVMe disk
+ through hypervisor's block layer thus enabling all features provided by
+ the layer (e.g. snapshots, domain migration, etc.). Moreover, since the
+ NVMe disk is unbinded from its PCI driver, the host kernel storage stack
+ is not involved (compared to passing say ``/dev/nvme0n1`` via
+ ``<disk type='block'>`` and therefore lower latencies can be achieved.
+
+ With "file", "block", and "volume", one or more optional sub-elements
+ ``seclabel``, `described below <#seclabel>`__ (and :since:`since 0.9.9` ),
+ can be used to override the domain security labeling policy for just that
+ source file. (NB, for "volume" type disk, ``seclabel`` is only valid when the
+ specified storage volume is of 'file' or 'block' type).
+
+ The ``source`` element may also have the ``index`` attribute with same
+ semantics the `index <#elementsDiskBackingStoreIndex>`__ attribute of
+ ``backingStore``
+
+ The ``source`` element may contain the following sub elements:
+
+ ``host``
+ When the disk ``type`` is "network", the ``source`` may have zero or more
+ ``host`` sub-elements used to specify the hosts to connect. The ``host``
+ element supports 4 attributes, viz. "name", "port", "transport" and
+ "socket", which specify the hostname, the port number, transport type and
+ path to socket, respectively. The meaning of this element and the number
+ of the elements depend on the protocol attribute.
+
+ ======== ======================================================= ============================================================ ================
+ Protocol Meaning Number of hosts Default port
+ ======== ======================================================= ============================================================ ================
+ nbd a server running nbd-server only one 10809
+ iscsi an iSCSI server only one 3260
+ rbd monitor servers of RBD one or more librados default
+ sheepdog one of the sheepdog servers (default is localhost:7000) zero or one 7000
+ gluster a server running glusterd daemon one or more ( :since:`Since 2.1.0` ), just one prior to that 24007
+ vxhs a server running Veritas HyperScale daemon only one 9999
+ ======== ======================================================= ============================================================ ================
+
+ gluster supports "tcp", "rdma", "unix" as valid values for the transport
+ attribute. nbd supports "tcp" and "unix". Others only support "tcp". If
+ nothing is specified, "tcp" is assumed. If the transport is "unix", the
+ socket attribute specifies the path to an AF_UNIX socket.
+
+ ``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).`
+ ``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).`
+ ``auth``
+ :since:`Since libvirt 3.9.0` , the ``auth`` element is supported for a
+ disk ``type`` "network" that is using a ``source`` element with the
+ ``protocol`` attributes "rbd" or "iscsi". If present, the ``auth`` element
+ provides the authentication credentials needed to access the source. It
+ includes a mandatory attribute ``username``, which identifies the username
+ to use during authentication, as well as a sub-element ``secret`` with
+ mandatory attribute ``type``, to tie back to a `libvirt secret
+ object <formatsecret.html>`__ that holds the actual password or other
+ credentials (the domain XML intentionally does not expose the password,
+ only the reference to the object that does manage the password). Known
+ secret types are "ceph" for Ceph RBD network sources and "iscsi" for CHAP
+ authentication of iSCSI targets. Both will require either a ``uuid``
+ attribute with the UUID of the secret object or a ``usage`` attribute
+ matching the key that was specified in the secret object.
+ ``encryption``
+ :since:`Since libvirt 3.9.0` , the ``encryption`` can be a sub-element of
+ the ``source`` element for encrypted storage sources. If present,
+ specifies how the storage source is encrypted See the `Storage
+ Encryption <formatstorageencryption.html>`__ page for more information.
+ Note that the 'qcow' format of encryption is broken and thus is no longer
+ supported for use with disk images. ( :since:`Since libvirt 4.5.0` )
+ ``reservations``
+ :since:`Since libvirt 4.4.0` , the ``reservations`` can be a sub-element
+ of the ``source`` element for storage sources (QEMU driver only). If
+ present it enables persistent reservations for SCSI based disks. The
+ element has one mandatory attribute ``managed`` with accepted values
+ ``yes`` and ``no``. If ``managed`` is enabled libvirt prepares and manages
+ any resources needed. When the persistent reservations are unmanaged, then
+ the hypervisor acts as a client and the path to the server socket must be
+ provided in the child element ``source``, which currently accepts only the
+ following attributes: ``type`` with one value ``unix``, ``path`` path to
+ the socket, and finally ``mode`` which accepts one value ``client``
+ specifying the role of hypervisor. It's recommended to allow libvirt
+ manage the persistent reservations.
+ ``initiator``
+ :since:`Since libvirt 4.7.0` , the ``initiator`` element is supported for
+ a disk ``type`` "network" that is using a ``source`` element with the
+ ``protocol`` attribute "iscsi". If present, the ``initiator`` element
+ provides the initiator IQN needed to access the source via mandatory
+ attribute ``name``.
+ ``address``
+ For disk of type ``nvme`` this element specifies the PCI address of the
+ host NVMe controller. :since:`Since 6.0.0`
+ ``slices``
+ The ``slices`` element using its ``slice`` sub-elements allows configuring
+ offset and size of either the location of the image format
+ (``slice type='storage'``) inside the storage source or the guest data
+ inside the image format container (future expansion). The ``offset`` and
+ ``size`` values are in bytes. :since:`Since 6.1.0`
+ ``ssl``
+ For ``https`` and ``ftps`` accessed storage it's possible to tweak the SSL
+ transport parameters with this element. The ``verify`` attribute allows to
+ turn on or off SSL certificate validation. Supported values are ``yes``
+ and ``no``. :since:`Since 6.2.0`
+ ``cookies``
+ For ``http`` and ``https`` accessed storage it's possible to pass one or
+ more cookies. The cookie name and value must conform to the HTTP
+ specification. :since:`Since 6.2.0`
+ ``readahead``
+ Specifies the size of the readahead buffer for protocols which support it.
+ (all 'curl' based drivers in qemu). The size is in bytes. Note that '0' is
+ considered as if the value is not provided. :since:`Since 6.2.0`
+ ``timeout``
+ Specifies the connection timeout for protocols which support it. Note that
+ '0' is considered as if the value is not provided. :since:`Since 6.2.0`
+
+ For a "file" or "volume" disk type which represents a cdrom or floppy (the
+ ``device`` attribute), it is possible to define policy what to do with the
+ disk if the source file is not accessible. (NB, ``startupPolicy`` is not
+ valid for "volume" disk unless the specified storage volume is of "file"
+ type). This is done by the ``startupPolicy`` attribute ( :since:`since 0.9.7`
+ ), accepting these values:
+
+ ========= =====================================================================
+ mandatory fail if missing for any reason (the default)
+ requisite fail if missing on boot up, drop if missing on migrate/restore/revert
+ optional drop if missing at any start attempt
+ ========= =====================================================================
+
+ :since:`Since 1.1.2` the ``startupPolicy`` is extended to support hard disks
+ besides cdrom and floppy. On guest cold bootup, if a certain disk is not
+ accessible or its disk chain is broken, with startupPolicy 'optional' the
+ guest will drop this disk. This feature doesn't support migration currently.
+
+``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
+ does not support the
+ `backingStoreInput <formatdomaincaps.html#featureBackingStoreInput>`__ (
+ :since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored on
+ input and only used for output to describe the detected backing chains of
+ running domains. If ``backingStoreInput`` is supported the ``backingStore``
+ is used as the backing image of ``source`` or other ``backingStore``
+ overriding any backing image information recorded in the image metadata. An
+ empty ``backingStore`` element means the sibling source is self-contained and
+ is not based on any backing store. For the detected backing chain information
+ to be accurate, the backing format must be correctly specified in the
+ metadata of each file of the chain (files created by libvirt satisfy this
+ property, but using existing external files for snapshot or block copy
+ operations requires the end user to pre-create the file correctly). The
+ following attributes are supported in ``backingStore``:
+
+ ``type``
+ The ``type`` attribute represents the type of disk used by the backing
+ store, see disk type attribute above for more details and possible values.
+ ``index``
+ This attribute is only valid in output (and ignored on input) and it can
+ be used to refer to a specific part of the disk chain when doing block
+ operations (such as via the ``virDomainBlockRebase`` API). For example,
+ ``vda[2]`` refers to the backing store with ``index='2'`` of the disk with
+ ``vda`` target.
+
+ Moreover, ``backingStore`` supports the following sub-elements:
+
+ ``format``
+ The ``format`` element contains ``type`` attribute which specifies the
+ internal format of the backing store, such as ``raw`` or ``qcow2``.
+ ``source``
+ This element has the same structure as the ``source`` element in ``disk``.
+ It specifies which file, device, or network location contains the data of
+ the described backing store.
+ ``backingStore``
+ If the backing store is not self-contained, the next element in the chain
+ is described by nested ``backingStore`` element.
+
+``mirror``
+ This element is present if the hypervisor has started a long-running block
+ job operation, where the mirror location in the ``source`` sub-element will
+ eventually have the same contents as the source, and with the file format in
+ the sub-element ``format`` (which might differ from the format of the
+ source). The details of the ``source`` sub-element are determined by the
+ ``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
+ ``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``
+ 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
+ include redundant information in the attributes ``file`` and ``format`` in
+ the ``mirror`` element.
+``target``
+ The ``target`` element controls the bus / device under which the disk is
+ exposed to the guest OS. The ``dev`` attribute indicates the "logical" device
+ name. The actual device name specified is not guaranteed to map to the device
+ 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
+ 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.
+ CDROM or Floppy disk), the value can be either "open" or "closed", defaults
+ to "closed". NB, the value of ``tray`` could be updated while the domain is
+ running. The optional attribute ``removable`` sets the removable flag for USB
+ disks, and its value can be either "on" or "off", defaulting to "off".
+ :since:`Since 0.0.3; ``bus`` attribute since 0.4.3; ``tray`` attribute since
+ 0.9.11; "usb" attribute value since after 0.4.4; "sata" attribute value since
+ 0.9.7; "removable" attribute value since 1.1.3`
+``iotune``
+ The optional ``iotune`` element provides the ability to provide additional
+ per-device I/O tuning, with values that can vary for each device (contrast
+ this to the `<blkiotune> <#elementsBlockTuning>`__ element, 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`
+
+ ``total_bytes_sec``
+ The optional ``total_bytes_sec`` element is the total throughput limit in
+ bytes per second. This cannot appear with ``read_bytes_sec`` or
+ ``write_bytes_sec``.
+ ``read_bytes_sec``
+ The optional ``read_bytes_sec`` element is the read throughput limit in
+ bytes per second.
+ ``write_bytes_sec``
+ The optional ``write_bytes_sec`` element is the write throughput limit in
+ bytes per second.
+ ``total_iops_sec``
+ The optional ``total_iops_sec`` element is the total I/O operations per
+ second. This cannot appear with ``read_iops_sec`` or ``write_iops_sec``.
+ ``read_iops_sec``
+ The optional ``read_iops_sec`` element is the read I/O operations per
+ second.
+ ``write_iops_sec``
+ The optional ``write_iops_sec`` element is the write I/O operations per
+ second.
+ ``total_bytes_sec_max``
+ The optional ``total_bytes_sec_max`` element is the maximum total
+ throughput limit in bytes per second. This cannot appear with
+ ``read_bytes_sec_max`` or ``write_bytes_sec_max``.
+ ``read_bytes_sec_max``
+ The optional ``read_bytes_sec_max`` element is the maximum read throughput
+ limit in bytes per second.
+ ``write_bytes_sec_max``
+ The optional ``write_bytes_sec_max`` element is the maximum write
+ throughput limit in bytes per second.
+ ``total_iops_sec_max``
+ The optional ``total_iops_sec_max`` element is the maximum total I/O
+ operations per second. This cannot appear with ``read_iops_sec_max`` or
+ ``write_iops_sec_max``.
+ ``read_iops_sec_max``
+ The optional ``read_iops_sec_max`` element is the maximum read I/O
+ operations per second.
+ ``write_iops_sec_max``
+ The optional ``write_iops_sec_max`` element is the maximum write I/O
+ operations per second.
+ ``size_iops_sec``
+ The optional ``size_iops_sec`` element is the size of I/O operations per
+ second.
+
+ :since:`Throughput limits since 1.2.11 and QEMU 1.7`
+
+ ``group_name``
+ The optional ``group_name`` provides the cability to share I/O throttling
+ quota between multiple drives. This prevents end-users from circumventing
+ a hosting provider's throttling policy by splitting 1 large drive in N
+ small drives and getting N times the normal throttling quota. Any name may
+ be used.
+
+ :since:`group_name since 3.0.0 and QEMU 2.4`
+
+ ``total_bytes_sec_max_length``
+ The optional ``total_bytes_sec_max_length`` element is the maximum
+ duration in seconds for the ``total_bytes_sec_max`` burst period. Only
+ valid when the ``total_bytes_sec_max`` is set.
+ ``read_bytes_sec_max_length``
+ The optional ``read_bytes_sec_max_length`` element is the maximum duration
+ in seconds for the ``read_bytes_sec_max`` burst period. Only valid when
+ the ``read_bytes_sec_max`` is set.
+ ``write_bytes_sec_max``
+ The optional ``write_bytes_sec_max_length`` element is the maximum
+ duration in seconds for the ``write_bytes_sec_max`` burst period. Only
+ valid when the ``write_bytes_sec_max`` is set.
+ ``total_iops_sec_max_length``
+ The optional ``total_iops_sec_max_length`` element is the maximum duration
+ in seconds for the ``total_iops_sec_max`` burst period. Only valid when
+ the ``total_iops_sec_max`` is set.
+ ``read_iops_sec_max_length``
+ The optional ``read_iops_sec_max_length`` element is the maximum duration
+ in seconds for the ``read_iops_sec_max`` burst period. Only valid when the
+ ``read_iops_sec_max`` is set.
+ ``write_iops_sec_max``
+ The optional ``write_iops_sec_max_length`` element is the maximum duration
+ in seconds for the ``write_iops_sec_max`` burst period. Only valid when
+ the ``write_iops_sec_max`` is set.
+
+ :since:`Throughput length since 2.4.0 and QEMU 2.6`
+
+``driver``
+ The optional driver element allows specifying further details related to the
+ hypervisor driver used to provide the disk. :since:`Since 0.1.8`
+
+ - If the hypervisor supports multiple backend drivers, then the ``name``
+ attribute selects the primary backend driver name, while the optional
+ ``type`` attribute provides the sub-type. For example, xen supports a name
+ of "tap", "tap2", "phy", or "file", with a type of "aio", while qemu only
+ supports a name of "qemu", but multiple types including "raw", "bochs",
+ "qcow2", and "qed".
+ - The optional ``cache`` attribute controls the cache mechanism, possible
+ values are "default", "none", "writethrough", "writeback", "directsync"
+ (like "writethrough", but it bypasses the host page cache) and "unsafe"
+ (host may cache all disk io, and sync requests from guest are ignored).
+ :since:` Since 0.6.0, "directsync" since 0.9.5, "unsafe" since 0.9.7 `
+ - The optional ``error_policy`` attribute controls how the hypervisor will
+ behave on a disk read or write error, possible values are "stop",
+ "report", "ignore", and "enospace". :since:`Since 0.8.0, "report" since
+ 0.9.7` The default is left to the discretion of the hypervisor. There is
+ also an optional ``rerror_policy`` that controls behavior for read errors
+ only. :since:`Since 0.9.7` . If no rerror_policy is given, error_policy is
+ used for both read and write errors. If rerror_policy is given, it
+ overrides the ``error_policy`` for read errors. Also note that "enospace"
+ is not a valid policy for read errors, so if ``error_policy`` is set to
+ "enospace" and no ``rerror_policy`` is given, the read error policy will
+ be left at its default.
+ - 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)` .
+ - 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.
+ Accepted values are "on" and "off". Enabling this allows qemu to execute
+ VM while a separate thread handles I/O. Typically guests experiencing high
+ system CPU utilization during I/O will benefit from this. On the other
+ hand, on overloaded host it could increase guest I/O latency.
+ :since:`Since 0.9.3 (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 ``event_idx`` attribute controls some aspects of device event
+ processing. The value can be either 'on' or 'off' - if it is on, it will
+ 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,
+ 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".
+ Copy-on-read avoids accessing the same backing file sectors repeatedly and
+ is useful when the backing file is over a slow network. By default
+ copy-on-read is off. :since:`Since 0.9.10 (QEMU and KVM only)`
+ - 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)`
+ - 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")
+ turns the detection on and additionally tries to discard such areas from
+ the image based on the value of ``discard`` above (it will act as "on" if
+ ``discard`` is set to "ignore"). NB enabling the detection is a compute
+ intensive operation, but can save file space and/or time on slow media.
+ :since:`Since 2.0.0`
+ - The optional ``iothread`` attribute assigns the disk to an IOThread as
+ defined by the range for the domain
+ `iothreads <#elementsIOThreadsAllocation>`__ value. 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)`
+ - The optional ``queues`` attribute specifies the number of virt queues for
+ virtio-blk. ( :since:`Since 3.9.0` )
+ - For virtio disks, `Virtio-specific options <#elementsVirtio>`__ can also
+ be set. ( :since:`Since 3.5.0` )
+
+``backenddomain``
+ The optional ``backenddomain`` element allows specifying a backend domain
+ (aka driver domain) hosting the disk. Use the ``name`` attribute to specify
+ the backend domain name. :since:`Since 1.2.13 (Xen only)`
+``boot``
+ Specifies that the disk is bootable. The ``order`` attribute determines the
+ order in which devices will be tried during boot sequence. On the S390
+ architecture only the first boot device is used. The optional ``loadparm``
+ attribute is an 8 character string which can be queried by guests on S390 via
+ sclp or diag 308. Linux guests on S390 can use ``loadparm`` to select a boot
+ entry. :since:`Since 3.5.0` The per-device ``boot`` elements cannot be used
+ together with general boot elements in `BIOS bootloader <#elementsOSBIOS>`__
+ section. :since:`Since 0.8.8`
+``encryption``
+ Starting with :since:`libvirt 3.9.0` the ``encryption`` element is preferred
+ to be a sub-element of the ``source`` element. If present, specifies how the
+ volume is encrypted using "qcow". See the `Storage
+ Encryption <formatstorageencryption.html>`__ page for more information.
+``readonly``
+ If present, this indicates the device cannot be modified by the guest. For
+ now, this is the default for disks with attribute ``device='cdrom'``.
+``shareable``
+ If present, this indicates the device is expected to be shared between
+ domains (assuming the hypervisor and OS support this), which means that
+ caching should be deactivated for that device.
+``transient``
+ If present, this indicates that changes to the device contents should be
+ reverted automatically when the guest exits. With some hypervisors, marking a
+ disk transient prevents the domain from participating in migration or
+ snapshots. :since:`Since 0.9.5`
+``serial``
+ If present, this specify serial number of virtual hard drive. For example, it
+ may look like ``<serial>WD-WMAP9A966149</serial>``. Not supported for
+ scsi-block devices, that is those using disk ``type`` 'block' using
+ ``device`` 'lun' on ``bus`` 'scsi'. :since:`Since 0.7.1`
+``wwn``
+ If present, this element specifies the WWN (World Wide Name) of a virtual
+ hard disk or CD-ROM drive. It must be composed of 16 hexadecimal digits.
+ :since:`Since 0.10.1`
+``vendor``
+ If present, this element specifies the vendor of a virtual hard disk or
+ CD-ROM device. It must not be longer than 8 printable characters.
+ :since:`Since 1.0.1`
+``product``
+ If present, this element specifies the product of a virtual hard disk or
+ CD-ROM device. It must not be longer than 16 printable characters.
+ :since:`Since 1.0.1`
+``address``
+ If present, the ``address`` element ties the disk to a given slot of a
+ controller (the actual ``<controller>`` device can often be inferred by
+ libvirt, although it can be `explicitly specified <#elementsControllers>`__).
+ The ``type`` attribute is mandatory, and is typically "pci" or "drive". For a
+ "pci" controller, additional attributes for ``bus``, ``slot``, and
+ ``function`` must be present, as well as optional ``domain`` and
+ ``multifunction``. Multifunction defaults to 'off'; any other value requires
+ QEMU 0.1.3 and :since:`libvirt 0.9.7` . For a "drive" controller, additional
+ attributes ``controller``, ``bus``, ``target`` ( :since:`libvirt 0.9.11` ),
+ and ``unit`` are available, each defaulting to 0.
+``auth``
+ Starting with :since:`libvirt 3.9.0` the ``auth`` element is preferred to be
+ a sub-element of the ``source`` element. The element is still read and
+ managed as a ``disk`` sub-element. It is invalid to use ``auth`` as both a
+ sub-element of ``disk`` and ``source``. The ``auth`` element was introduced
+ as a ``disk`` sub-element in :since:`libvirt 0.9.7.`
+``geometry``
+ The optional ``geometry`` element provides the ability to override geometry
+ settings. This mostly useful for S390 DASD-disks or older DOS-disks.
+ :since:`0.10.0`
+
+ ``cyls``
+ The ``cyls`` attribute is the number of cylinders.
+ ``heads``
+ The ``heads`` attribute is the number of heads.
+ ``secs``
+ The ``secs`` attribute is the number of sectors per track.
+ ``trans``
+ The optional ``trans`` attribute is the BIOS-Translation-Modus (none, lba
+ or auto)
+
+``blockio``
+ If present, the ``blockio`` element allows to override any of the block
+ device properties listed below. :since:`Since 0.10.2 (QEMU and KVM)`
+
+ ``logical_block_size``
+ The logical block size the disk will report to the guest OS. For Linux
+ this would be the value returned by the BLKSSZGET ioctl and describes the
+ smallest units for disk I/O.
+ ``physical_block_size``
+ The physical block size the disk will report to the guest OS. For Linux
+ this would be the value returned by the BLKPBSZGET ioctl and describes the
+ disk's hardware sector size which can be relevant for the alignment of
+ disk data.
+
+:anchor:`<a id="elementsFilesystems"/>`
+
+Filesystems
+~~~~~~~~~~~
+
+A directory on the host that can be accessed directly from the guest.
+:since:`since 0.3.3, since 0.8.5 for QEMU/KVM`
+
+::
+
+ ...
+ <devices>
+ <filesystem type='template'>
+ <source name='my-vm-template'/>
+ <target dir='/'/>
+ </filesystem>
+ <filesystem type='mount' accessmode='passthrough' multidevs='remap'>
+ <driver type='path' wrpolicy='immediate'/>
+ <source dir='/export/to/guest'/>
+ <target dir='/import/from/host'/>
+ <readonly/>
+ </filesystem>
+ <filesystem type='file' accessmode='passthrough'>
+ <driver type='loop' format='raw'/>
+ <driver type='path' wrpolicy='immediate'/>
+ <source file='/export/to/guest.img'/>
+ <target dir='/import/from/host'/>
+ <readonly/>
+ </filesystem>
+ <filesystem type='mount' accessmode='passthrough'>
+ <driver type='virtiofs' queue='1024'/>
+ <binary path='/usr/libexec/virtiofsd' xattr='on'>
+ <cache mode='always'/>
+ <lock posix='on' flock='on'/>
+ </binary>
+ <source dir='/path'/>
+ <target dir='mount_tag'/>
+ </filesystem>
+ ...
+ </devices>
+ ...
+
+``filesystem``
+ The filesystem attribute ``type`` specifies the type of the ``source``. The
+ 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``
+ 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
+ ``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
+ virtiofs requires setting up shared memory, see the guide:
+ `Virtio-FS <kbase/virtiofs.html>`__
+ ``template``
+ OpenVZ filesystem template. Only used by OpenVZ driver.
+ ``file``
+ A host file will be treated as an image and mounted in the guest. The
+ 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)` .
+ ``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
+ KiB, unless units are specified by the ``units`` attribute. Only used by
+ LXC driver. :since:` (since 0.9.13)`
+ ``bind``
+ A directory inside the guest will be bound to another directory inside the
+ 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)` .
+ 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:
+
+ ``passthrough``
+ The ``source`` is accessed with the permissions of the user inside the
+ guest. This is the default ``accessmode`` if one is not specified. `More
+ info <http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html>`__
+ ``mapped``
+ The ``source`` is accessed with the permissions of the hypervisor (QEMU
+ process). `More
+ info <http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html>`__
+ ``squash``
+ Similar to 'passthrough', the exception is that failure of privileged
+ operations like 'chown' are ignored. This makes a passthrough-like mode
+ usable for people who run the hypervisor as non-root. `More
+ info <http://lists.gnu.org/archive/html/qemu-devel/2010-09/msg00121.html>`__
+
+ :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 <#elementsVirtioTransitional>`__ for more details.
+
+ The filesystem element has an optional attribute ``multidevs`` which
+ specifies how to deal with a filesystem export containing more than one
+ device, in order to avoid file ID collisions on guest when using 9pfs (
+ :since:`since 6.3.0, requires QEMU 4.2` ). This attribute is not available
+ for virtiofs. The possible values are:
+
+ ``default``
+ Use QEMU's default setting (which currently is ``warn``).
+ ``remap``
+ This setting allows guest to access multiple devices per export without
+ encountering misbehaviours. Inode numbers from host are automatically
+ remapped on guest to actively prevent file ID collisions if guest accesses
+ one export containing multiple devices.
+ ``forbid``
+ Only allow to access one device per export by guest. Attempts to access
+ additional devices on the same export will cause the individual filesystem
+ access by guest to fail with an error and being logged (once) as error on
+ host side.
+ ``warn``
+ This setting resembles the behaviour of 9pfs prior to QEMU 4.2, that is no
+ action is performed to prevent any potential file ID collisions if an
+ export contains multiple devices, with the only exception: a warning is
+ logged (once) on host side now. This setting may lead to misbehaviours on
+ guest side if more than one device is exported per export, due to the
+ potential file ID collisions this may cause on guest side in that case.
+
+``driver``
+ The optional driver element allows specifying further details related to the
+ hypervisor driver used to provide the filesystem. :since:`Since 1.0.6`
+
+ - If the hypervisor supports multiple backend drivers, then the ``type``
+ attribute selects the primary backend driver name, while the ``format``
+ attribute provides the format type. For example, LXC supports a type of
+ "loop", with a format of "raw" or "nbd" with any format. QEMU supports a
+ type of "path" or "handle", but no formats. Virtuozzo driver supports a
+ type of "ploop" with a format of "ploop".
+ - For virtio-backed devices, `Virtio-specific options <#elementsVirtio>`__
+ can also be set. ( :since:`Since 3.5.0` )
+ - For ``virtiofs``, the ``queue`` attribute can be used to specify the queue
+ size (i.e. how many requests can the queue fit). ( :since:`Since 6.2.0` )
+
+``binary``
+ The optional ``binary`` element can tune the options for virtiofsd. All of
+ the following attributes and elements are optional. The attribute ``path``
+ can be used to override the path to the daemon. Attribute ``xattr`` enables
+ the use of filesystem extended attributes. Caching can be tuned via the
+ ``cache`` element, possible ``mode`` values being ``none`` and ``always``.
+ Locking can be controlled via the ``lock`` element - attributes ``posix`` and
+ ``flock`` both accepting values ``on`` or ``off``. ( :since:`Since 6.2.0` )
+``source``
+ The resource on the host that is being accessed in the guest. The ``name``
+ attribute must be used with ``type='template'``, and the ``dir`` attribute
+ must be used with ``type='mount'``. The ``usage`` attribute is used with
+ ``type='ram'`` to set the memory limit in KiB, unless units are specified by
+ the ``units`` attribute.
+``target``
+ Where the ``source`` can be accessed in the guest. For most drivers this is
+ an automatic mount point, but for QEMU/KVM this is merely an arbitrary string
+ tag that is exported to the guest as a hint for where to mount.
+``readonly``
+ Enables exporting filesystem as a readonly mount for guest, by default
+ read-write access is given (currently only works for QEMU/KVM driver).
+``space_hard_limit``
+ Maximum space available to this guest's filesystem. :since:`Since 0.9.13`
+``space_soft_limit``
+ Maximum space available to this guest's filesystem. The container is
+ permitted to exceed its soft limits for a grace period of time. Afterwards
+ the hard limit is enforced. :since:`Since 0.9.13`
+
+:anchor:`<a id="elementsAddress"/>`
+
+Device Addresses
+~~~~~~~~~~~~~~~~
+
+Many devices have an optional ``<address>`` sub-element to describe where the
+device is placed on the virtual bus presented to the guest. If an address (or
+any optional attribute within an address) is omitted on input, libvirt will
+generate an appropriate address; but an explicit address is required if more
+control over layout is required. See below for device examples including an
+address element.
+
+Every address has a mandatory attribute ``type`` that describes which bus the
+device is on. The choice of which address to use for a given device is
+constrained in part by the device and the architecture of the guest. For
+example, a ``<disk>`` device uses ``type='drive'``, while a ``<console>`` device
+would use ``type='pci'`` on i686 or x86_64 guests, or ``type='spapr-vio'`` on
+PowerPC64 pseries guests. Each address type has further optional attributes that
+control where on the bus the device will be placed:
+
+``pci``
+ PCI addresses have the following additional attributes: ``domain`` (a 2-byte
+ hex integer, not currently used by qemu), ``bus`` (a hex value between 0 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
+ ``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
+ 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
+ have a ``zpci`` child element, with two attributes: ``uid`` (a hex value
+ 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
+ ``<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).
+ The relationship between the PCI addresses configured in the domain XML and
+ those seen by the guest OS can sometime seem confusing: a separate document
+ describes `how PCI addresses work <pci-addresses.html>`__ in more detail.
+``drive``
+ Drive addresses have the following additional attributes: ``controller`` (a
+ 2-digit controller number), ``bus`` (a 2-digit bus number), ``target`` (a
+ 2-digit target number), and ``unit`` (a 2-digit unit number on the bus).
+``virtio-serial``
+ Each virtio-serial address has the following additional attributes:
+ ``controller`` (a 2-digit controller number), ``bus`` (a 2-digit bus number),
+ and ``slot`` (a 2-digit slot within the bus).
+``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.`
+``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
+ four octets, such as 1.2 or 2.1.3.1).
+``spapr-vio``
+ On PowerPC pseries guests, devices can be assigned to the SPAPR-VIO bus. It
+ has a flat 32-bit address space; by convention, devices are generally
+ 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.`
+``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
+ attributes: ``cssid`` (a hex value between 0 and 0xfe, inclusive), ``ssid``
+ (a value between 0 and 3, inclusive) and ``devno`` (a hex value between 0 and
+ 0xffff, inclusive). Partially specified bus addresses are not allowed. If
+ omitted, libvirt will assign a free bus address with cssid=0xfe and ssid=0.
+ Virtio-ccw devices must have their cssid set to 0xfe. :since:`Since 1.0.4`
+``virtio-mmio``
+ This places the device on the virtio-mmio transport, which is currently only
+ available for some ``armv7l`` and ``aarch64`` virtual machines. virtio-mmio
+ addresses do not have any additional attributes. :since:`Since 1.1.3`
+ If the guest architecture is ``aarch64`` and the machine type is ``virt``,
+ libvirt will automatically assign PCI addresses to devices; however, the
+ presence of a single device with virtio-mmio address in the guest
+ configuration will cause libvirt to assign virtio-mmio addresses to all
+ further devices. :since:`Since 3.0.0`
+``isa``
+ ISA addresses have the following additional attributes: ``iobase`` and
+ ``irq``. :since:`Since 1.2.1`
+``unassigned``
+ For PCI hostdevs, ``<address type='unassigned'/>`` allows the admin to
+ include a PCI hostdev in the domain XML definition, without making it
+ available for the guest. This allows for configurations in which Libvirt
+ manages the device as a regular PCI hostdev, regardless of whether the guest
+ will have access to it. ``<address type='unassigned'/>`` is an invalid
+ address type for all other device types. :since:`Since 6.0.0`
+
+:anchor:`<a id="elementsVirtio"/>`
+
+Virtio-related options
+~~~~~~~~~~~~~~~~~~~~~~
+
+QEMU's virtio devices have some attributes related to the virtio transport under
+the ``driver`` element: The ``iommu`` attribute enables the use of emulated
+IOMMU by the device. The attribute ``ats`` controls the Address Translation
+Service support for PCIe devices. This is needed to make use of IOTLB support
+(see `IOMMU device <#elementsIommu>`__). Possible values are ``on`` or ``off``.
+:since:`Since 3.5.0`
+
+The attribute ``packed`` controls if QEMU should try to use packed virtqueues.
+Compared to regular split queues, packed queues consist of only a single
+descriptor ring replacing available and used ring, index and descriptor buffer.
+This can result in better cache utilization and performance. If packed
+virtqueues are actually used depends on the feature negotiation between QEMU,
+vhost backends and guest drivers. Possible values are ``on`` or ``off``.
+:since:`Since 6.3.0 (QEMU and KVM only)`
+
+:anchor:`<a id="elementsVirtioTransitional"/>`
+
+Virtio transitional devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+: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``
+ This device can work both with virtio 0.9 and virtio 1.0 guest drivers, so
+ it's the best choice when compatibility with older guest operating systems is
+ desired. libvirt will plug the device into a conventional PCI slot.
+``virtio-non-transitional``
+ This device can only work with virtio 1.0 guest drivers, and it's the
+ recommended option unless compatibility with older guest operating systems is
+ necessary. libvirt will plug the device into either a PCI Express slot or a
+ conventional PCI slot based on the machine type, resulting in a more
+ optimized PCI topology.
+``virtio``
+ This device will work like a ``virtio-non-transitional`` device when plugged
+ into a PCI Express slot, and like a ``virtio-transitional`` device otherwise;
+ libvirt will pick one or the other based on the machine type. This is the
+ best choice when compatibility with libvirt versions older than 5.2.0 is
+ necessary, but it's otherwise not recommended to use it.
+
+While the information outlined above applies to most virtio devices, there are a
+few exceptions:
+
+- for SCSI controllers, ``virtio-scsi`` must be used instead of ``virtio`` for
+ backwards compatibility reasons;
+- some devices, such as GPUs and input devices (keyboard, tablet and mouse),
+ are only defined in the virtio 1.0 spec and as such don't have a transitional
+ variant: the only accepted model is ``virtio``, which will result in a
+ non-transitional device.
+
+For more details see the `qemu patch
+posting <https://lists.gnu.org/archive/html/qemu-devel/2018-12/msg00923.html>`__
+and the `virtio-1.0
+spec <http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.html>`__.
+
+:anchor:`<a id="elementsControllers"/>`
+
+Controllers
+~~~~~~~~~~~
+
+Depending on the guest architecture, some device buses can appear more than
+once, with a group of virtual devices tied to a virtual controller. Normally,
+libvirt can automatically infer such controllers without requiring explicit XML
+markup, but sometimes it is necessary to provide an explicit controller element,
+notably when planning the `PCI topology <pci-hotplug.html>`__ for guests where
+device hotplug is expected.
+
+::
+
+ ...
+ <devices>
+ <controller type='ide' index='0'/>
+ <controller type='virtio-serial' index='0' ports='16' vectors='4'/>
+ <controller type='virtio-serial' index='1'>
+ <address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/>
+ </controller>
+ <controller type='scsi' index='0' model='virtio-scsi'>
+ <driver iothread='4'/>
+ <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/>
+ </controller>
+ <controller type='xenbus' maxGrantFrames='64' maxEventChannels='2047'/>
+ ...
+ </devices>
+ ...
+
+Each controller has a mandatory attribute ``type``, which must be one of 'ide',
+'fdc', 'scsi', 'sata', 'usb', 'ccid', 'virtio-serial' or 'pci', and a mandatory
+attribute ``index`` which is the decimal integer describing in which order the
+bus controller is encountered (for use in ``controller`` attributes of
+``<address>`` elements). :since:`Since 1.3.5` the index is optional; if not
+specified, it will be auto-assigned to be the lowest unused index for the given
+controller type. Some controller types have additional attributes that control
+specific features, such as:
+
+``virtio-serial``
+ The ``virtio-serial`` controller has two additional optional attributes
+ ``ports`` and ``vectors``, which control how many devices can be connected
+ through the controller. :since:`Since 5.2.0` , it supports an optional
+ attribute ``model`` which can be 'virtio', 'virtio-transitional', or
+ 'virtio-non-transitional'. See `Virtio transitional
+ devices <#elementsVirtioTransitional>`__ for more details.
+``scsi``
+ A ``scsi`` controller has an optional attribute ``model``, which is one of
+ 'auto', 'buslogic', 'ibmvscsi', 'lsilogic', 'lsisas1068', 'lsisas1078',
+ 'virtio-scsi', 'vmpvscsi', 'virtio-transitional', 'virtio-non-transitional'.
+ See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more
+ details.
+``usb``
+ A ``usb`` controller has an optional attribute ``model``, which is one of
+ "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
+ 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
+ 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
+ ``maxGrantFrames``, which specifies the maximum number of grant frames 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.
+
+Note: The PowerPC64 "spapr-vio" addresses do not have an associated controller.
+
+For controllers that are themselves devices on a PCI or USB bus, an optional
+sub-element ``<address>`` can specify the exact relationship of the controller
+to its master bus, with semantics `given above <#elementsAddress>`__.
+
+An optional sub-element ``driver`` can specify the driver specific options:
+
+``queues``
+ The optional ``queues`` attribute specifies the number of queues for the
+ controller. For best performance, it's recommended to specify a value
+ 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)`
+``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.
+ The transfer length is measured in sectors, where a sector is 512 bytes.
+ :since:`Since 1.2.7 (QEMU and KVM only)`
+``ioeventfd``
+ The optional ``ioeventfd`` attribute specifies whether the controller should
+ use `I/O asynchronous handling <https://patchwork.kernel.org/patch/43390/>`__
+ 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
+ optional ``iothread`` attribute assigns the controller to an IOThread as
+ defined by the range for the domain
+ `iothreads <#elementsIOThreadsAllocation>`__ value. Each SCSI ``disk``
+ assigned to use the specified ``controller`` will utilize the same IOThread.
+ If a specific IOThread is desired for a specific SCSI ``disk``, then multiple
+ controllers must be defined each having a specific ``iothread`` value. The
+ ``iothread`` value must be within the range 1 to the domain iothreads value.
+virtio options
+ For virtio controllers, `Virtio-specific options <#elementsVirtio>`__ can
+ also be set. ( :since:`Since 3.5.0` )
+
+USB companion controllers have an optional sub-element ``<master>`` to specify
+the exact relationship of the companion to its master controller. A companion
+controller is on the same bus as its master, so the companion ``index`` value
+should be equal. Not all controller models can be used as companion controllers
+and libvirt might provide some sensible defaults (settings of
+``master startport`` and ``function`` of an address) for some particular models.
+Preferred companion controllers are ``ich-uhci[123]``.
+
+::
+
+ ...
+ <devices>
+ <controller type='usb' index='0' model='ich9-ehci1'>
+ <address type='pci' domain='0' bus='0' slot='4' function='7'/>
+ </controller>
+ <controller type='usb' index='0' model='ich9-uhci1'>
+ <master startport='0'/>
+ <address type='pci' domain='0' bus='0' slot='4' function='0' multifunction='on'/>
+ </controller>
+ ...
+ </devices>
+ ...
+
+PCI controllers have an optional ``model`` attribute; possible values for this
+attribute are
+
+- ``pci-root``, ``pci-bridge`` ( :since:`since 1.0.5` )
+- ``pcie-root``, ``dmi-to-pci-bridge`` ( :since:`since 1.1.2` )
+- ``pcie-root-port``, ``pcie-switch-upstream-port``,
+ ``pcie-switch-downstream-port`` ( :since:`since 1.2.19` )
+- ``pci-expander-bus``, ``pcie-expander-bus`` ( :since:`since 1.3.4` )
+- ``pcie-to-pci-bridge`` ( :since:`since 4.3.0` )
+
+The root controllers (``pci-root`` and ``pcie-root``) have an optional
+``pcihole64`` element specifying how big (in kilobytes, or in the unit specified
+by ``pcihole64``'s ``unit`` attribute) the 64-bit PCI hole should be. Some
+guests (like Windows XP or Windows Server 2003) might crash when QEMU and
+Seabios are recent enough to support 64-bit PCI holes, unless this is disabled
+(set to 0). :since:`Since 1.1.2 (QEMU only)`
+
+PCI controllers also have an optional subelement ``<model>`` with an attribute
+``name``. The name attribute holds the name of the specific device that qemu is
+emulating (e.g. "i82801b11-bridge") rather than simply the class of device
+("pcie-to-pci-bridge", "pci-bridge"), which is set in the controller element's
+model **attribute**. In almost all cases, you should not manually add a
+``<model>`` subelement to a controller, nor should you modify one that is
+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)
+are visible to the guest OS so must be preserved for guest ABI compatibility,
+and 2) are usually left to default values or derived automatically by libvirt.
+In almost all cases, you should not manually add a ``<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).`
+
+``chassisNr``
+ PCI controllers that have attribute model="pci-bridge", can also have a
+ ``chassisNr`` attribute in the ``<target>`` subelement, which is used to
+ control QEMU's "chassis_nr" option for the pci-bridge device (normally
+ libvirt automatically sets this to the same value as the index attribute of
+ the pci controller). If set, chassisNr must be between 1 and 255.
+``chassis``
+ pcie-root-port and pcie-switch-downstream-port controllers can also have a
+ ``chassis`` attribute in the ``<target>`` subelement, which is used to set
+ the controller's "chassis" configuration value, which is visible to the
+ virtual machine. If set, chassis must be between 0 and 255.
+``port``
+ pcie-root-port and pcie-switch-downstream-port controllers can also have a
+ ``port`` attribute in the ``<target>`` subelement, which is used to set the
+ controller's "port" configuration value, which is visible to the virtual
+ machine. If set, port must be between 0 and 255.
+``hotplug``
+ pcie-root-port and pcie-switch-downstream-port controllers can also have a
+ ``hotplug`` attribute in the ``<target>`` subelement, which is used to
+ disable hotplug/unplug of devices on a particular controller. The default
+ setting of ``hotplug`` is ``on``; it should be set to ``off`` to disable
+ hotplug/unplug of devices on a particular controller. :since:`Since 6.3.0`
+``busNr``
+ pci-expander-bus and pcie-expander-bus controllers can have an optional
+ ``busNr`` attribute (1-254). This will be the bus number of the new bus; All
+ bus numbers between that specified and 255 will be available only for
+ assignment to PCI/PCIe controllers plugged into the hierarchy starting with
+ this expander bus, and bus numbers less than the specified value will be
+ available to the next lower expander-bus (or the root-bus if there are no
+ lower expander buses). If you do not specify a busNumber, libvirt will find
+ the lowest existing busNumber in all other expander buses (or use 256 if
+ there are no others) and auto-assign the busNr of that found bus - 2, which
+ provides one bus number for the pci-expander-bus and one for the pci-bridge
+ that is automatically attached to it (if you plan on adding more pci-bridges
+ to the hierarchy of the bus, you should manually set busNr to a lower value).
+
+ A similar algorithm is used for automatically determining the busNr attribute
+ for pcie-expander-bus, but since the pcie-expander-bus doesn't have any
+ built-in pci-bridge, the 2nd bus-number is just being reserved for the
+ pcie-root-port that must necessarily be connected to the bus in order to
+ actually plug in an endpoint device. If you intend to plug multiple devices
+ into a pcie-expander-bus, you must connect a pcie-switch-upstream-port to the
+ pcie-root-port that is plugged into the pcie-expander-bus, and multiple
+ pcie-switch-downstream-ports to the pcie-switch-upstream-port, and of course
+ for this to work properly, you will need to decrease the pcie-expander-bus'
+ busNr accordingly so that there are enough unused bus numbers above it to
+ accommodate giving out one bus number for the upstream-port and one for each
+ downstream-port (in addition to the pcie-root-port and the pcie-expander-bus
+ itself).
+
+``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` ,
+ ``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
+ all devices on that bus are a part of the specified NUMA node (it is up to
+ the user of the libvirt API to attach host devices to the correct
+ pci-expander-bus when assigning them to the domain).
+``index``
+ pci-root controllers for pSeries guests use this attribute to record the
+ order they will show up in the guest. :since:`Since 3.6.0`
+
+For machine types which provide an implicit PCI bus, the pci-root controller
+with index=0 is auto-added and required to use PCI devices. pci-root has no
+address. PCI bridges are auto-added if there are too many devices to fit on the
+one bus provided by pci-root, or a PCI bus number greater than zero was
+specified. PCI bridges can also be specified manually, but their addresses
+should only refer to PCI buses provided by already specified PCI controllers.
+Leaving gaps in the PCI controller indexes might lead to an invalid
+configuration.
+
+::
+
+ ...
+ <devices>
+ <controller type='pci' index='0' model='pci-root'/>
+ <controller type='pci' index='1' model='pci-bridge'>
+ <address type='pci' domain='0' bus='0' slot='5' function='0' multifunction='off'/>
+ </controller>
+ </devices>
+ ...
+
+For machine types which provide an implicit PCI Express (PCIe) bus (for example,
+the machine types based on the Q35 chipset), the pcie-root controller with
+index=0 is auto-added to the domain's configuration. pcie-root has also no
+address, provides 31 slots (numbered 1-31) that can be used to attach PCIe or
+PCI devices (although libvirt will never auto-assign a PCI device to a PCIe
+slot, it will allow manual specification of such an assignment). Devices
+connected to pcie-root cannot be hotplugged. If traditional PCI devices are
+present in the guest configuration, a ``pcie-to-pci-bridge`` controller will
+automatically be added: this controller, which plugs into a ``pcie-root-port``,
+provides 31 usable PCI slots (1-31) with hotplug support ( :since:`since 4.3.0`
+). If the QEMU binary doesn't support the corresponding device, then a
+``dmi-to-pci-bridge`` controller will be added instead, usually at the defacto
+standard location of slot=0x1e. A dmi-to-pci-bridge controller plugs into a PCIe
+slot (as provided by pcie-root), and itself provides 31 standard PCI slots
+(which also do not support device hotplug). In order to have hot-pluggable PCI
+slots in the guest system, a pci-bridge controller will also be automatically
+created and connected to one of the slots of the auto-created dmi-to-pci-bridge
+controller; all guest PCI devices with addresses that are auto-determined by
+libvirt will be placed on this pci-bridge device. ( :since:`since 1.1.2` ).
+
+Domains with an implicit pcie-root can also add controllers with
+``model='pcie-root-port'``, ``model='pcie-switch-upstream-port'``, and
+``model='pcie-switch-downstream-port'``. pcie-root-port is a simple type of
+bridge device that can connect only to one of the 31 slots on the pcie-root bus
+on its upstream side, and makes a single (PCIe, hotpluggable) port available on
+the downstream side (at slot='0'). pcie-root-port can be used to provide a
+single slot to later hotplug a PCIe device (but is not itself hotpluggable - it
+must be in the configuration when the domain is started). ( :since:`since
+1.2.19` )
+
+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
+upstream side (and only before the domain is started - it is not hot-pluggable),
+and provides 32 ports on the downstream side (slot='0' - slot='31') that accept
+only pcie-switch-downstream-port devices; each pcie-switch-downstream-port
+device can only plug into a pcie-switch-upstream-port on its upstream side
+(again, not hot-pluggable), and on its downstream side provides a single
+hotpluggable pcie port that can accept any standard pci or pcie device (or
+another pcie-switch-upstream-port), i.e. identical in function to a
+pcie-root-port. ( :since:`since 1.2.19` )
+
+::
+
+ ...
+ <devices>
+ <controller type='pci' index='0' model='pcie-root'/>
+ <controller type='pci' index='1' model='pcie-root-port'>
+ <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/>
+ </controller>
+ <controller type='pci' index='2' model='pcie-to-pci-bridge'>
+ <address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/>
+ </controller>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsLease"/>`
+
+Device leases
+~~~~~~~~~~~~~
+
+When using a lock manager, it may be desirable to record device leases against a
+VM. The lock manager will ensure the VM won't start unless the leases can be
+acquired.
+
+::
+
+ ...
+ <devices>
+ ...
+ <lease>
+ <lockspace>somearea</lockspace>
+ <key>somekey</key>
+ <target path='/some/lease/path' offset='1024'/>
+ </lease>
+ ...
+ </devices>
+ ...
+
+``lockspace``
+ This is an arbitrary string, identifying the lockspace within which the key
+ is held. Lock managers may impose extra restrictions on the format, or length
+ of the lockspace name.
+``key``
+ This is an arbitrary string, uniquely identifying the lease to be acquired.
+ Lock managers may impose extra restrictions on the format, or length of the
+ key.
+``target``
+ This is the fully qualified path of the file associated with the lockspace.
+ The offset specifies where the lease is stored within the file. If the lock
+ manager does not require an offset, just pass 0.
+
+:anchor:`<a id="elementsHostDev"/>`
+
+Host device assignment
+~~~~~~~~~~~~~~~~~~~~~~
+
+:anchor:`<a id="elementsHostDevSubsys"/>`
+
+USB / PCI / SCSI devices
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+USB, PCI and SCSI devices attached to the host can be passed through to the
+guest using the ``hostdev`` element. :since:`since after 0.4.4 for USB, 0.6.0
+for PCI (KVM only) and 1.0.6 for SCSI (KVM only)` :
+
+::
+
+ ...
+ <devices>
+ <hostdev mode='subsystem' type='usb'>
+ <source startupPolicy='optional'>
+ <vendor id='0x1234'/>
+ <product id='0xbeef'/>
+ </source>
+ <boot order='2'/>
+ </hostdev>
+ </devices>
+ ...
+
+or:
+
+::
+
+ ...
+ <devices>
+ <hostdev mode='subsystem' type='pci' managed='yes'>
+ <source>
+ <address domain='0x0000' bus='0x06' slot='0x02' function='0x0'/>
+ </source>
+ <boot order='1'/>
+ <rom bar='on' file='/etc/fake/boot.bin'/>
+ </hostdev>
+ </devices>
+ ...
+
+or:
+
+::
+
+ ...
+ <devices>
+ <hostdev mode='subsystem' type='scsi' sgio='filtered' rawio='yes'>
+ <source>
+ <adapter name='scsi_host0'/>
+ <address bus='0' target='0' unit='0'/>
+ </source>
+ <readonly/>
+ <address type='drive' controller='0' bus='0' target='0' unit='0'/>
+ </hostdev>
+ </devices>
+ ...
+
+or:
+
+::
+
+ ...
+ <devices>
+ <hostdev mode='subsystem' type='scsi'>
+ <source protocol='iscsi' name='iqn.2014-08.com.example:iscsi-nopool/1'>
+ <host name='example.com' port='3260'/>
+ <auth username='myuser'>
+ <secret type='iscsi' usage='libvirtiscsi'/>
+ </auth>
+ </source>
+ <address type='drive' controller='0' bus='0' target='0' unit='0'/>
+ </hostdev>
+ </devices>
+ ...
+
+or:
+
+::
+
+ ...
+ <devices>
+ <hostdev mode='subsystem' type='scsi_host'>
+ <source protocol='vhost' wwpn='naa.50014057667280d8'/>
+ </hostdev>
+ </devices>
+ ...
+
+or:
+
+::
+
+ ...
+ <devices>
+ <hostdev mode='subsystem' type='mdev' model='vfio-pci'>
+ <source>
+ <address uuid='c2177883-f1bb-47f0-914d-32a22e3a8804'/>
+ </source>
+ </hostdev>
+ <hostdev mode='subsystem' type='mdev' model='vfio-ccw'>
+ <source>
+ <address uuid='9063cba3-ecef-47b6-abcf-3fef4fdcad85'/>
+ </source>
+ <address type='ccw' cssid='0xfe' ssid='0x0' devno='0x0001'/>
+ </hostdev>
+ </devices>
+ ...
+
+``hostdev``
+ The ``hostdev`` element is the main container for describing host devices.
+ For each device, the ``mode`` is always "subsystem" and the ``type`` is one
+ of the following values with additional attributes noted.
+
+ ``usb``
+ USB devices are detached from the host on guest startup and reattached
+ after the guest exits or the device is hot-unplugged.
+ ``pci``
+ For PCI devices, when ``managed`` is "yes" it is detached from the host
+ before being passed on to the guest and reattached to the host after the
+ guest exits. If ``managed`` is omitted or "no", the user is responsible to
+ call ``virNodeDeviceDetachFlags`` (or ``virsh nodedev-detach`` before
+ starting the guest or hot-plugging the device and
+ ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-unplug
+ or stopping the guest.
+ ``scsi``
+ For SCSI devices, user is responsible to make sure the device is not used
+ by host. If supported by the hypervisor and OS, the optional ``sgio`` (
+ :since:`since 1.0.6` ) attribute indicates whether unprivileged SG_IO
+ commands are filtered for the disk. Valid settings are "filtered" or
+ "unfiltered", where the default is "filtered". The optional ``rawio`` (
+ :since:`since 1.2.9` ) attribute indicates whether the lun needs the rawio
+ capability. Valid settings are "yes" or "no". See the rawio description
+ within the `disk <#elementsDisks>`__ section. If a disk lun in the domain
+ already has the rawio capability, then this setting not required.
+ ``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
+ can be specified further with "virtio-transitional",
+ "virtio-non-transitional", or "virtio". See `Virtio transitional
+ devices <#elementsVirtioTransitional>`__ for more details.
+ ``mdev``
+ For mediated devices ( :since:`Since 3.2.0` ) the ``model`` attribute
+ specifies the device API which determines how the host's vfio driver will
+ expose the device to the guest. Currently, ``model='vfio-pci'``,
+ ``model='vfio-ccw'`` ( :since:`Since 4.4.0` ) and ``model='vfio-ap'`` (
+ :since:`Since 4.9.0` ) is supported. `MDEV <drvnodedev.html#MDEV>`__
+ section provides more information about mediated devices as well as how to
+ create mediated devices on the host. :since:`Since 4.6.0 (QEMU 2.12)` an
+ optional ``display`` attribute may be used to enable or disable support
+ for an accelerated remote desktop backed by a mediated device (such as
+ NVIDIA vGPU or Intel GVT-g) as an alternative to emulated `video
+ devices <#elementsVideo>`__. This attribute is limited to
+ ``model='vfio-pci'`` only. Supported values are either ``on`` or ``off``
+ (default is 'off'). It is required to use a `graphical
+ framebuffer <#elementsGraphics>`__ 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``
+ 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
+ be used as a boot display when a vgpu device is the primary display.
+
+ Note: There are also some implications on the usage of guest's address
+ type depending on the ``model`` attribute, see the ``address`` element
+ below.
+
+ Note: The ``managed`` attribute is only used with ``type='pci'`` and is
+ ignored by all the other device types, thus setting ``managed`` explicitly
+ with other than a PCI device has the same effect as omitting it. Similarly,
+ ``model`` attribute is only supported by mediated devices and ignored by all
+ other device types.
+
+``source``
+ The source element describes the device as seen from the host using the
+ following mechanism to describe:
+
+ ``usb``
+ The USB device can either be addressed by vendor / product id using the
+ ``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
+ ``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:
+
+ ========= =====================================================================
+ mandatory fail if missing for any reason (the default)
+ requisite fail if missing on boot up, drop if missing on migrate/restore/revert
+ optional drop if missing at any start attempt
+ ========= =====================================================================
+
+ ``pci``
+ PCI devices can only be described by their ``address``.
+ ``scsi``
+ SCSI devices are described by both the ``adapter`` and ``address``
+ elements. The ``address`` element includes a ``bus`` attribute (a 2-digit
+ bus number), a ``target`` attribute (a 10-digit target number), and a
+ ``unit`` attribute (a 20-digit unit number on the bus). Not all
+ 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
+ the ``protocol`` attribute. When the attribute is set to "iscsi", the host
+ device XML follows the network `disk <#elementsDisks>`__ device using the
+ same ``name`` attribute and optionally using the ``auth`` element to
+ provide the authentication credentials to the iSCSI server.
+
+ ``scsi_host``
+ :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.
+ ``mdev``
+ Mediated devices ( :since:`Since 3.2.0` ) are described by the ``address``
+ element. The ``address`` element contains a single mandatory attribute
+ ``uuid``.
+
+``vendor``, ``product``
+ The ``vendor`` and ``product`` elements each have an ``id`` attribute that
+ specifies the USB vendor and product id. The ids can be given in decimal,
+ hexadecimal (starting with 0x) or octal (starting with 0) form.
+``boot``
+ Specifies that the device is bootable. The ``order`` attribute determines the
+ order in which devices will be tried during boot sequence. The per-device
+ ``boot`` elements cannot be used together with general boot elements in `BIOS
+ bootloader <#elementsOSBIOS>`__ section. :since:`Since 0.8.8` for PCI
+ devices, :since:`Since 1.0.1` for USB devices.
+``rom``
+ The ``rom`` element is used to change how a PCI device's ROM is presented to
+ the guest. The optional ``bar`` attribute can be set to "on" or "off", and
+ determines whether or not the device's ROM will be visible in the guest's
+ 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
+ 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``
+ 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)` .
+``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
+ the host. The values of these attributes can be given in decimal, hexadecimal
+ (starting with 0x) or octal (starting with 0) form. For PCI devices the
+ element carries 4 attributes allowing to designate the device as can be found
+ with the ``lspci`` or with ``virsh nodedev-list``. For SCSI devices a 'drive'
+ address type must be used. For mediated devices, which are software-only
+ devices defining an allocation of resources on the physical parent device,
+ the address type used must conform to the ``model`` attribute of element
+ ``hostdev``, e.g. any address type other than PCI for ``vfio-pci`` device API
+ or any address type other than CCW for ``vfio-ccw`` device API will result in
+ an error. `See above <#elementsAddress>`__ for more details on the address
+ element.
+``driver``
+ PCI devices can have an optional ``driver`` subelement that specifies which
+ backend driver to use for PCI device assignment. Use the ``name`` attribute
+ to select either "vfio" (for the new VFIO device assignment backend, which is
+ compatible with UEFI SecureBoot) or "kvm" (the legacy device assignment
+ handled directly by the KVM kernel module) :since:`Since 1.0.5 (QEMU and KVM
+ only, requires kernel 3.6 or newer)` . When specified, device assignment will
+ fail if the requested method of device assignment isn't available on the
+ host. When not specified, the default is "vfio" on systems where the VFIO
+ driver is available and loaded, and "kvm" on older systems, or those where
+ the VFIO driver hasn't been loaded :since:`Since 1.1.3` (prior to that the
+ default was always "kvm").
+``readonly``
+ Indicates that the device is readonly, only supported by SCSI host device
+ now. :since:`Since 1.0.6 (QEMU and KVM only)`
+``shareable``
+ If present, this indicates the device is expected to be shared between
+ domains (assuming the hypervisor and OS support this). Only supported by SCSI
+ host device. :since:`Since 1.0.6`
+
+ Note: Although ``shareable`` was introduced :since:`in 1.0.6` , it did not
+ work as as expected until :since:`1.2.2` .
+
+:anchor:`<a id="elementsHostDevCaps"/>`
+
+Block / character devices
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Block / character devices from the host can be passed through to the guest using
+the ``hostdev`` element. This is only possible with container based
+virtualization. Devices are specified by a fully qualified path. :since:`since
+after 1.0.1 for LXC` :
+
+::
+
+ ...
+ <hostdev mode='capabilities' type='storage'>
+ <source>
+ <block>/dev/sdf1</block>
+ </source>
+ </hostdev>
+ ...
+
+::
+
+ ...
+ <hostdev mode='capabilities' type='misc'>
+ <source>
+ <char>/dev/input/event3</char>
+ </source>
+ </hostdev>
+ ...
+
+::
+
+ ...
+ <hostdev mode='capabilities' type='net'>
+ <source>
+ <interface>eth0</interface>
+ </source>
+ </hostdev>
+ ...
+
+``hostdev``
+ The ``hostdev`` element is the main container for describing host devices.
+ For block/character device passthrough ``mode`` is always "capabilities" and
+ ``type`` is "storage" for a block device, "misc" for a character device and
+ "net" for a host network interface.
+``source``
+ The source element describes the device as seen from the host. For block
+ devices, the path to the block device in the host OS is provided in the
+ nested "block" element, while for character devices the "char" element is
+ used. For network interfaces, the name of the interface is provided in the
+ "interface" element.
+
+:anchor:`<a id="elementsRedir"/>`
+
+Redirected devices
+~~~~~~~~~~~~~~~~~~
+
+USB device redirection through a character device is supported :since:`since
+after 0.9.5 (KVM only)` :
+
+::
+
+ ...
+ <devices>
+ <redirdev bus='usb' type='tcp'>
+ <source mode='connect' host='localhost' service='4000'/>
+ <boot order='1'/>
+ </redirdev>
+ <redirfilter>
+ <usbdev class='0x08' vendor='0x1234' product='0xbeef' version='2.56' allow='yes'/>
+ <usbdev allow='no'/>
+ </redirfilter>
+ </devices>
+ ...
+
+``redirdev``
+ The ``redirdev`` element is the main container for describing redirected
+ devices. ``bus`` must be "usb" for a USB device. An additional attribute
+ ``type`` is required, matching one of the supported `serial
+ device <#elementsConsole>`__ types, to describe the host side of the tunnel;
+ ``type='tcp'`` or ``type='spicevmc'`` (which uses the usbredir channel of a
+ `SPICE graphics device <#elementsGraphics>`__) are typical. The redirdev
+ element has an optional sub-element ``<address>`` which can tie the device to
+ a particular controller. Further sub-elements, such as ``<source>``, may be
+ required according to the given type, although a ``<target>`` sub-element is
+ not required (since the consumer of the character device is the hypervisor
+ itself, rather than a device visible in the guest).
+``boot``
+ Specifies that the device is bootable. The ``order`` attribute determines the
+ order in which devices will be tried during boot sequence. The per-device
+ ``boot`` elements cannot be used together with general boot elements in `BIOS
+ bootloader <#elementsOSBIOS>`__ section. ( :since:`Since 1.0.1` )
+``redirfilter``
+ The\ ``redirfilter``\ element is used for creating the filter rule to filter
+ out certain devices from redirection. It uses sub-element ``<usbdev>`` to
+ define each filter rule. ``class`` attribute is the USB Class code, for
+ example, 0x08 represents mass storage devices. The USB device can be
+ addressed by vendor / product id using the ``vendor`` and ``product``
+ attributes. ``version`` is the device revision from the bcdDevice field (not
+ the version of the USB protocol). These four attributes are optional and
+ ``-1`` can be used to allow any value for them. ``allow`` attribute is
+ mandatory, 'yes' means allow, 'no' for deny.
+
+:anchor:`<a id="elementsSmartcard"/>`
+
+Smartcard devices
+~~~~~~~~~~~~~~~~~
+
+A virtual smartcard device can be supplied to the guest via the ``smartcard``
+element. A USB smartcard reader device on the host cannot be used on a guest
+with simple device passthrough, since it will then not be available on the host,
+possibly locking the host computer when it is "removed". Therefore, some
+hypervisors provide a specialized virtual device that can present a smartcard
+interface to the guest, with several modes for describing how credentials are
+obtained from the host or even a from a channel created to a third-party
+smartcard provider. :since:`Since 0.8.8`
+
+::
+
+ ...
+ <devices>
+ <smartcard mode='host'/>
+ <smartcard mode='host-certificates'>
+ <certificate>cert1</certificate>
+ <certificate>cert2</certificate>
+ <certificate>cert3</certificate>
+ <database>/etc/pki/nssdb/</database>
+ </smartcard>
+ <smartcard mode='passthrough' type='tcp'>
+ <source mode='bind' host='127.0.0.1' service='2001'/>
+ <protocol type='raw'/>
+ <address type='ccid' controller='0' slot='0'/>
+ </smartcard>
+ <smartcard mode='passthrough' type='spicevmc'/>
+ </devices>
+ ...
+
+The ``<smartcard>`` element has a mandatory attribute ``mode``. The following
+modes are supported; in each mode, the guest sees a device on its USB bus that
+behaves like a physical USB CCID (Chip/Smart Card Interface Device) card.
+
+``host``
+ The simplest operation, where the hypervisor relays all requests from the
+ guest into direct access to the host's smartcard via NSS. No other attributes
+ or sub-elements are required. See below about the use of an optional
+ ``<address>`` sub-element.
+``host-certificates``
+ Rather than requiring a smartcard to be plugged into the host, it is possible
+ to provide three NSS certificate names residing in a database on the host.
+ These certificates can be generated via the command
+ ``certutil -d /etc/pki/nssdb -x -t CT,CT,CT -S -s CN=cert1 -n cert1``,
+ and the resulting three certificate names must be supplied as the content of
+ each of three ``<certificate>`` sub-elements. An additional sub-element
+ ``<database>`` can specify the absolute path to an alternate directory
+ (matching the ``-d`` option of the ``certutil`` command when creating the
+ certificates); if not present, it defaults to /etc/pki/nssdb.
+``passthrough``
+ Rather than having the hypervisor directly communicate with the host, it is
+ possible to tunnel all requests through a secondary character device to a
+ third-party provider (which may in turn be talking to a smartcard or using
+ three certificate files). In this mode of operation, an additional attribute
+ ``type`` is required, matching one of the supported `serial
+ device <#elementsConsole>`__ types, to describe the host side of the tunnel;
+ ``type='tcp'`` or ``type='spicevmc'`` (which uses the smartcard channel of a
+ `SPICE graphics device <#elementsGraphics>`__) are typical. Further
+ sub-elements, such as ``<source>``, may be required according to the given
+ type, although a ``<target>`` sub-element is not required (since the consumer
+ of the character device is the hypervisor itself, rather than a device
+ visible in the guest).
+
+Each mode supports an optional sub-element ``<address>``, which fine-tunes the
+correlation between the smartcard and a ccid bus controller, `documented
+above <#elementsAddress>`__. For now, qemu only supports at most one smartcard,
+with an address of bus=0 slot=0.
+
+:anchor:`<a id="elementsNICS"/>`
+
+Network interfaces
+~~~~~~~~~~~~~~~~~~
+
+::
+
+ ...
+ <devices>
+ <interface type='direct' trustGuestRxFilters='yes'>
+ <source dev='eth0'/>
+ <mac address='52:54:00:5d:c7:9e'/>
+ <boot order='1'/>
+ <rom bar='off'/>
+ </interface>
+ </devices>
+ ...
+
+There are several possibilities for specifying a network interface visible to
+the guest. Each subsection below provides more details about common setup
+options.
+
+:since:`Since 1.2.10` ), the ``interface`` element property
+``trustGuestRxFilters`` provides the capability for the host to detect and trust
+reports from the guest regarding changes to the interface mac address and
+receive filters by setting the attribute to ``yes``. The default setting for the
+attribute is ``no`` for security reasons and support depends on the guest
+network device model as well as the type of connection on the host - currently
+it is only supported for the virtio device model and for macvtap connections on
+the host.
+
+Each ``<interface>`` element has an optional ``<address>`` sub-element that can
+tie the interface to a particular pci slot, with attribute ``type='pci'`` as
+`documented above <#elementsAddress>`__.
+
+: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.
+
+:anchor:`<a id="elementsNICSVirtual"/>`
+
+Virtual network
+^^^^^^^^^^^^^^^
+
+**This is the recommended config for general guest connectivity on hosts with
+dynamic / wireless networking configs (or multi-host environments where the host
+hardware details are described separately in a ``<network>`` definition
+:since:`Since 0.9.4` ).**
+
+Provides a connection whose details are described by the named network
+definition. Depending on the virtual network's "forward mode" configuration, the
+network may be totally isolated (no ``<forward>`` element given), NAT'ing to an
+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` )
+
+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
+outside the scope of libvirt. In the case of isolated, nat, and routed networks,
+DHCP and DNS are provided on the virtual network by libvirt, and the IP range
+can be determined by examining the virtual network config with
+'``virsh net-dumpxml [networkname]``'. There is one virtual network called
+'default' setup out of the box which does NAT'ing to the default route and has
+an IP range of ``192.168.122.0/255.255.255.0``. Each guest will have an
+associated tun device created with a name of vnetN, which can also be overridden
+with the <target> element (see `overriding the target
+element <#elementsNICSTargetOverride>`__).
+
+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` .
+
+When a guest is running an interface of type ``network`` may include a
+``portid`` attribute. This provides the UUID of an associated virNetworkPortPtr
+object that records the association between the domain interface and the
+network. This attribute is read-only since port objects are create and deleted
+automatically during startup and shutdown. :since:`Since 5.1.0`
+
+Also, similar to ``direct`` network connections (described below), a connection
+of type ``network`` may specify a ``virtualport`` element, with configuration
+data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant switch (
+:since:`Since 0.8.2` ), or to an Open vSwitch virtual switch ( :since:`Since
+0.9.11` ).
+
+Since 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``
+attribute, and specify attributes from multiple different virtualport types (and
+also to leave out certain attributes); at domain startup time, a complete
+``<virtualport>`` element will be constructed by merging together the type and
+attributes defined in the network and the portgroup referenced by the interface.
+The newly-constructed virtualport is a combination of them. The attributes from
+lower virtualport can't make change on the ones defined in higher virtualport.
+Interface takes the highest priority, portgroup is lowest priority. (
+:since:`Since 0.10.0` ). For example, in order to work properly with both an
+802.1Qbh switch and an Open vSwitch switch, you may choose to specify no type,
+but both a ``profileid`` (in case the switch is 802.1Qbh) and an ``interfaceid``
+(in case the switch is Open vSwitch) (you may also omit the other attributes,
+such as managerid, typeid, or profileid, to be filled in from the network's
+``<virtualport>``). If you want to limit a guest to connecting only to certain
+types of switches, you can specify the virtualport type, but still omit some/all
+of the parameters - in this case if the host's network has a different type of
+virtualport, connection of the interface will fail.
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ </interface>
+ ...
+ <interface type='network'>
+ <source network='default' portgroup='engineering'/>
+ <target dev='vnet7'/>
+ <mac address="00:11:22:33:44:55"/>
+ <virtualport>
+ <parameters instanceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
+ </virtualport>
+ </interface>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsNICSBridge"/>`
+
+Bridge to LAN
+^^^^^^^^^^^^^
+
+**This is the recommended config for general guest connectivity on hosts with
+static wired networking configs.**
+
+Provides a bridge from the VM directly to the LAN. This assumes there is a
+bridge device on the host which has one or more of the hosts physical NICs
+attached. The guest VM will have an associated tun device created with a name of
+vnetN, which can also be overridden with the <target> element (see `overriding
+the target element <#elementsNICSTargetOverride>`__). The tun device will be
+attached to the bridge. The IP range / network configuration is whatever is used
+on the LAN. This provides the guest VM full incoming & outgoing net access just
+like a physical machine.
+
+On Linux systems, the bridge device is normally a standard Linux host bridge. On
+hosts that support Open vSwitch, it is also possible to connect to an Open
+vSwitch bridge device by adding a ``<virtualport type='openvswitch'/>`` to the
+interface definition. ( :since:`Since 0.9.11` ). The Open vSwitch type
+virtualport accepts two parameters in its ``<parameters>`` element - an
+``interfaceid`` which is a standard uuid used to uniquely identify this
+particular interface to Open vSwitch (if you do not specify one, a random
+interfaceid will be generated for you when you first define the interface), and
+an optional ``profileid`` which is sent to Open vSwitch as the interfaces
+"port-profile".
+
+::
+
+ ...
+ <devices>
+ ...
+ <interface type='bridge'>
+ <source bridge='br0'/>
+ </interface>
+ <interface type='bridge'>
+ <source bridge='br1'/>
+ <target dev='vnet7'/>
+ <mac address="00:11:22:33:44:55"/>
+ </interface>
+ <interface type='bridge'>
+ <source bridge='ovsbr'/>
+ <virtualport type='openvswitch'>
+ <parameters profileid='menial' interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
+ </virtualport>
+ </interface>
+ ...
+ </devices>
+ ...
+
+On hosts that support Open vSwitch on the kernel side and have the Midonet Host
+Agent configured, it is also possible to connect to the 'midonet' bridge device
+by adding a ``<virtualport type='midonet'/>`` to the interface definition. (
+:since:`Since 1.2.13` ). The Midonet virtualport type requires an
+``interfaceid`` attribute in its ``<parameters>`` element. This interface id is
+the UUID that specifies which port in the virtual network topology will be bound
+to the interface.
+
+::
+
+ ...
+ <devices>
+ ...
+ <interface type='bridge'>
+ <source bridge='br0'/>
+ </interface>
+ <interface type='bridge'>
+ <source bridge='br1'/>
+ <target dev='vnet7'/>
+ <mac address="00:11:22:33:44:55"/>
+ </interface>
+ <interface type='bridge'>
+ <source bridge='midonet'/>
+ <virtualport type='midonet'>
+ <parameters interfaceid='0b2d64da-3d0e-431e-afdd-804415d6ebbb'/>
+ </virtualport>
+ </interface>
+ ...
+ </devices>
+ ...
+
+:anchor:`<a id="elementsNICSSlirp"/>`
+
+Userspace SLIRP stack
+^^^^^^^^^^^^^^^^^^^^^
+
+Provides a virtual LAN with NAT to the outside world. The virtual network has
+DHCP & DNS services and will give the guest VM addresses starting from
+``10.0.2.15``. The default router will be ``10.0.2.2`` and the DNS server will
+be ``10.0.2.3``. This networking is the only option for unprivileged users who
+need their VMs to have outgoing access. :since:`Since 3.8.0` it is possible to
+override the default network address by including an ``ip`` element specifying
+an IPv4 address in its one mandatory attribute, ``address``. Optionally, a
+second ``ip`` element with a ``family`` attribute set to "ipv6" can be specified
+to add an IPv6 address to the interface. ``address``. Optionally, address
+``prefix`` can be specified.
+
+::
+
+ ...
+ <devices>
+ <interface type='user'/>
+ ...
+ <interface type='user'>
+ <mac address="00:11:22:33:44:55"/>
+ <ip family='ipv4' address='172.17.2.0' prefix='24'/>
+ <ip family='ipv6' address='2001:db8:ac10:fd01::' prefix='64'/>
+ </interface>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsNICSEthernet"/>`
+
+Generic ethernet connection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Provides a means to use a new or existing tap device (or veth device pair,
+depening on the needs of the hypervisor driver) that is partially or wholly
+setup external to libvirt (either prior to the guest starting, or while the
+guest is being started via an optional script specified in the config).
+
+The name of the tap device can optionally be specified with the ``dev``
+attribute of the ``<target>`` element. If no target dev is specified, libvirt
+will create a new standard tap device with a name of the pattern "vnetN", where
+"N" is replaced with a number. If a target dev is specified and that device
+doesn't exist, then a new standard tap device will be created with the exact dev
+name given. If the specified target dev does exist, then that existing device
+will be used. Usually some basic setup of the device is done by libvirt,
+including setting a MAC address, and the IFF_UP flag, but if the ``dev`` is a
+pre-existing device, and the ``managed`` attribute of the ``target`` element is
+also set to "no" (the default value is "yes"), even this basic setup will not be
+performed - libvirt will simply pass the device on to the hypervisor with no
+setup at all. :since:`Since 5.7.0` Using managed='no' with a pre-created tap
+device is useful because it permits a virtual machine managed by an unprivileged
+libvirtd to have emulated network devices based on tap devices.
+
+After creating/opening the tap device, an optional shell script (given in the
+``path`` attribute of the ``<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 5.1.0` These can be used to do whatever extra host network
+integration is required.
+
+::
+
+ ...
+ <devices>
+ <interface type='ethernet'>
+ <script path='/etc/qemu-ifup-mynet'/>
+ <downscript path='/etc/qemu-ifdown-mynet'/>
+ </interface>
+ ...
+ <interface type='ethernet'>
+ <target dev='mytap1' managed='no'/>
+ <model type='virtio'/>
+ </interface>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsNICSDirect"/>`
+
+Direct attachment to physical interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+| Provides direct attachment of the virtual machine's NIC to the given physical
+ interface of the host. :since:`Since 0.7.7 (QEMU and KVM only)`
+| This setup requires the Linux macvtap driver to be available. :since:`(Since
+ Linux 2.6.34.)` One of the modes 'vepa' ( `'Virtual Ethernet Port
+ Aggregator' <http://www.ieee802.org/1/files/public/docs2009/new-evb-congdon-vepa-modular-0709-v01.pdf>`__),
+ 'bridge' or 'private' can be chosen for the operation mode of the macvtap
+ device, 'vepa' being the default mode. The individual modes cause the delivery
+ of packets to behave as follows:
+
+If the model type is set to ``virtio`` and interface's ``trustGuestRxFilters``
+attribute is set to ``yes``, changes made to the interface mac address,
+unicast/multicast receive filters, and vlan settings in the guest will be
+monitored and propagated to the associated macvtap device on the host (
+:since:`Since 1.2.10` ). If ``trustGuestRxFilters`` is not set, or is not
+supported for the device model in use, an attempted change to the mac address
+originating from the guest side will result in a non-working network connection.
+
+``vepa``
+ All VMs' packets are sent to the external bridge. Packets whose destination
+ is a VM on the same host as where the packet originates from are sent back to
+ the host by the VEPA capable bridge (today's bridges are typically not VEPA
+ capable).
+``bridge``
+ Packets whose destination is on the same host as where they originate from
+ are directly delivered to the target macvtap device. Both origin and
+ destination devices need to be in bridge mode for direct delivery. If either
+ one of them is in ``vepa`` mode, a VEPA capable bridge is required.
+``private``
+ All packets are sent to the external bridge and will only be delivered to a
+ target VM on the same host if they are sent through an external router or
+ gateway and that device sends them back to the host. This procedure is
+ followed if either the source or destination device is in ``private`` mode.
+``passthrough``
+ This feature attaches a virtual function of a SRIOV capable NIC directly to a
+ VM without losing the migration capability. All packets are sent to the VF/IF
+ of the configured network device. Depending on the capabilities of the device
+ additional prerequisites or limitations may apply; for example, on Linux this
+ requires kernel 2.6.38 or newer. :since:`Since 0.9.2`
+
+::
+
+ ...
+ <devices>
+ ...
+ <interface type='direct' trustGuestRxFilters='no'>
+ <source dev='eth0' mode='vepa'/>
+ </interface>
+ </devices>
+ ...
+
+The network access of direct attached virtual machines can be managed by the
+hardware switch to which the physical interface of the host machine is connected
+to.
+
+The interface can have additional parameters as shown below, if the switch is
+conforming to the IEEE 802.1Qbg standard. The parameters of the virtualport
+element are documented in more detail in the IEEE 802.1Qbg standard. The values
+are network specific and should be provided by the network administrator. In
+802.1Qbg terms, the Virtual Station Interface (VSI) represents the virtual
+interface of a virtual machine. :since:`Since 0.8.2`
+
+Please note that IEEE 802.1Qbg requires a non-zero value for the VLAN ID.
+
+``managerid``
+ The VSI Manager ID identifies the database containing the VSI type and
+ instance definitions. This is an integer value and the value 0 is reserved.
+``typeid``
+ The VSI Type ID identifies a VSI type characterizing the network access. VSI
+ types are typically managed by network administrator. This is an integer
+ value.
+``typeidversion``
+ The VSI Type Version allows multiple versions of a VSI Type. This is an
+ integer value.
+``instanceid``
+ The VSI Instance ID Identifier is generated when a VSI instance (i.e. a
+ virtual interface of a virtual machine) is created. This is a globally unique
+ identifier.
+
+::
+
+ ...
+ <devices>
+ ...
+ <interface type='direct'>
+ <source dev='eth0.2' mode='vepa'/>
+ <virtualport type="802.1Qbg">
+ <parameters managerid="11" typeid="1193047" typeidversion="2" instanceid="09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f"/>
+ </virtualport>
+ </interface>
+ </devices>
+ ...
+
+The interface can have additional parameters as shown below if the switch is
+conforming to the IEEE 802.1Qbh standard. The values are network specific and
+should be provided by the network administrator. :since:`Since 0.8.2`
+
+``profileid``
+ The profile ID contains the name of the port profile that is to be applied to
+ this interface. This name is resolved by the port profile database into the
+ network parameters from the port profile, and those network parameters will
+ be applied to this interface.
+
+::
+
+ ...
+ <devices>
+ ...
+ <interface type='direct'>
+ <source dev='eth0' mode='private'/>
+ <virtualport type='802.1Qbh'>
+ <parameters profileid='finance'/>
+ </virtualport>
+ </interface>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsNICSHostdev"/>`
+
+PCI Passthrough
+^^^^^^^^^^^^^^^
+
+A PCI network device (specified by the <source> element) is directly assigned to
+the guest using generic device passthrough, after first optionally setting the
+device's MAC address to the configured value, and associating the device with an
+802.1Qbh capable switch using an optionally specified <virtualport> element (see
+the examples of virtualport given above for type='direct' network devices). Note
+that - due to limitations in standard single-port PCI ethernet card driver
+design - only SR-IOV (Single Root I/O Virtualization) virtual function (VF)
+devices can be assigned in this manner; to assign a standard single-port PCI or
+PCIe ethernet card to a guest, use the traditional <hostdev> device definition
+and :since:`Since 0.9.11`
+
+To use VFIO device assignment rather than traditional/legacy KVM device
+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``
+sub-element with a ``name`` attribute set to "vfio". To use legacy KVM device
+assignment you can set ``name`` to "kvm" (or simply omit the ``<driver>``
+element, since "kvm" is currently the default). :since:`Since 1.0.5 (QEMU and
+KVM only, requires kernel 3.6 or newer)`
+
+Note that this "intelligent passthrough" of network devices is very similar to
+the functionality of a standard <hostdev> device, the difference being that this
+method allows specifying a MAC address and <virtualport> for the passed-through
+device. If these capabilities are not required, if you have a standard
+single-port PCI, PCIe, or USB network card that doesn't support SR-IOV (and
+hence would anyway lose the configured MAC address during reset after being
+assigned to the guest domain), or if you are using a version of libvirt older
+than 0.9.11, you should use standard <hostdev> to assign the device to the guest
+instead of <interface type='hostdev'/>.
+
+Similar to the functionality of a standard <hostdev> device, when ``managed`` is
+"yes", it is detached from the host before being passed on to the guest, and
+reattached to the host after the guest exits. If ``managed`` is omitted or "no",
+the user is responsible to call ``virNodeDeviceDettach`` (or
+``virsh nodedev-detach``) before starting the guest or hot-plugging the device,
+and ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-unplug
+or stopping the guest.
+
+::
+
+ ...
+ <devices>
+ <interface type='hostdev' managed='yes'>
+ <driver name='vfio'/>
+ <source>
+ <address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/>
+ </source>
+ <mac address='52:54:00:6d:90:02'/>
+ <virtualport type='802.1Qbh'>
+ <parameters profileid='finance'/>
+ </virtualport>
+ </interface>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsTeaming"/>`
+
+Teaming a virtio/hostdev NIC pair
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:since:`Since 6.1.0 (QEMU and KVM only, requires QEMU 4.2.0 or newer and a guest
+virtio-net driver supporting the "failover" feature, such as the one included in
+Linux kernel 4.18 and newer) ` The ``<teaming>`` element of two interfaces can
+be used to connect them as a team/bond device in the guest (assuming proper
+support in the hypervisor and the guest network driver).
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='mybridge'/>
+ <mac address='00:11:22:33:44:55'/>
+ <model type='virtio'/>
+ <teaming type='persistent'/>
+ <alias name='ua-backup0'/>
+ </interface>
+ <interface type='network'>
+ <source network='hostdev-pool'/>
+ <mac address='00:11:22:33:44:55'/>
+ <model type='virtio'/>
+ <teaming type='transient' persistent='ua-backup0'/>
+ </interface>
+ </devices>
+ ...
+
+The ``<teaming>`` element required attribute ``type`` will be set to either
+``"persistent"`` to indicate a device that should always be present in the
+domain, or ``"transient"`` to indicate a device that may periodically be
+removed, then later re-added to the domain. When type="transient", there should
+be a second attribute to ``<teaming>`` called ``"persistent"`` - this attribute
+should be set to the alias name of the other device in the pair (the one that
+has ``<teaming type="persistent'/>``).
+
+In the particular case of QEMU, libvirt's ``<teaming>`` element is used to setup
+a virtio-net "failover" device pair. For this setup, the persistent device must
+be an interface with ``<model type="virtio"/>``, and the transient device
+must be ``<interface type='hostdev'/>`` (or ``<interface type='network'/>``
+where the referenced network defines a pool of SRIOV VFs). The guest will then
+have a simple network team/bond device made of the virtio NIC + hostdev NIC
+pair. In this configuration, the higher-performing hostdev NIC will normally be
+preferred for all network traffic, but when the domain is migrated, QEMU will
+automatically unplug the VF from the guest, and then hotplug a similar device
+once migration is completed; while migration is taking place, network traffic
+will use the virtio NIC. (Of course the emulated virtio NIC and the hostdev NIC
+must be connected to the same subnet for bonding to work properly).
+
+NB1: Since you must know the alias name of the virtio NIC when configuring the
+hostdev NIC, it will need to be manually set in the virtio NIC's configuration
+(as with all other manually set alias names, this means it must start with
+"ua-").
+
+NB2: Currently the only implementation of the guest OS virtio-net driver
+supporting virtio-net failover requires that the MAC addresses of the virtio and
+hostdev NIC must match. Since that may not always be a requirement in the
+future, libvirt doesn't enforce this limitation - it is up to the
+person/management application that is creating the configuration to assure the
+MAC addresses of the two devices match.
+
+NB3: Since the PCI addresses of the SRIOV VFs on the hosts that are the source
+and destination of the migration will almost certainly be different, either
+higher level management software will need to modify the ``<source>`` of the
+hostdev NIC (``<interface type='hostdev'>``) at the start of migration, or (a
+simpler solution) the configuration will need to use a libvirt "hostdev" virtual
+network that maintains a pool of such devices, as is implied in the example's
+use of the libvirt network named "hostdev-pool" - as long as the hostdev network
+pools on both hosts have the same name, libvirt itself will take care of
+allocating an appropriate device on both ends of the migration. Similarly the
+XML for the virtio interface must also either work correctly unmodified on both
+the source and destination of the migration (e.g. by connecting to the same
+bridge device on both hosts, or by using the same virtual network), or the
+management software must properly modify the interface XML during migration so
+that the virtio device remains connected to the same network segment before and
+after migration.
+
+:anchor:`<a id="elementsNICSMulticast"/>`
+
+Multicast tunnel
+^^^^^^^^^^^^^^^^
+
+A multicast group is setup to represent a virtual network. Any VMs whose network
+devices are in the same multicast group can talk to each other even across
+hosts. This mode is also available to unprivileged users. There is no default
+DNS or DHCP support and no outgoing network access. To provide outgoing network
+access, one of the VMs should have a 2nd NIC which is connected to one of the
+first 4 network types and do the appropriate routing. The multicast protocol is
+compatible with that used by user mode linux guests too. The source address used
+must be from the multicast address block.
+
+::
+
+ ...
+ <devices>
+ <interface type='mcast'>
+ <mac address='52:54:00:6d:90:01'/>
+ <source address='230.0.0.1' port='5558'/>
+ </interface>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsNICSTCP"/>`
+
+TCP tunnel
+^^^^^^^^^^
+
+A TCP client/server architecture provides a virtual network. One VM provides the
+server end of the network, all other VMS are configured as clients. All network
+traffic is routed between the VMs via the server. This mode is also available to
+unprivileged users. There is no default DNS or DHCP support and no outgoing
+network access. To provide outgoing network access, one of the VMs should have a
+2nd NIC which is connected to one of the first 4 network types and do the
+appropriate routing.
+
+::
+
+ ...
+ <devices>
+ <interface type='server'>
+ <mac address='52:54:00:22:c9:42'/>
+ <source address='192.168.0.1' port='5558'/>
+ </interface>
+ ...
+ <interface type='client'>
+ <mac address='52:54:00:8b:c9:51'/>
+ <source address='192.168.0.1' port='5558'/>
+ </interface>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsNICSUDP"/>`
+
+UDP unicast tunnel
+^^^^^^^^^^^^^^^^^^
+
+A UDP unicast architecture provides a virtual network which enables connections
+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`
+
+::
+
+ ...
+ <devices>
+ <interface type='udp'>
+ <mac address='52:54:00:22:c9:42'/>
+ <source address='127.0.0.1' port='11115'>
+ <local address='127.0.0.1' port='11116'/>
+ </source>
+ </interface>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsNICSModel"/>`
+
+Setting the NIC model
+^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <target dev='vnet1'/>
+ <model type='ne2k_pci'/>
+ </interface>
+ </devices>
+ ...
+
+For hypervisors which support this, you can set the model of emulated network
+interface card.
+
+The values for ``type`` aren't defined specifically by libvirt, but by what the
+underlying hypervisor supports (if any). For QEMU and KVM you can get a list of
+supported models with these commands:
+
+::
+
+ qemu -net nic,model=? /dev/null
+ 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` ,
+``virtio-transitional`` and ``virtio-non-transitional`` values are supported.
+See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more
+details.
+
+:anchor:`<a id="elementsDriverBackendOptions"/>`
+
+Setting NIC driver-specific options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <target dev='vnet1'/>
+ <model type='virtio'/>
+ <driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5' rx_queue_size='256' tx_queue_size='256'>
+ <host csum='off' gso='off' tso4='off' tso6='off' ecn='off' ufo='off' mrg_rxbuf='off'/>
+ <guest csum='off' tso4='off' tso6='off' ecn='off' ufo='off'/>
+ </driver>
+ </interface>
+ </devices>
+ ...
+
+Some NICs may have tunable driver-specific options. These are set as attributes
+of the ``driver`` sub-element of the interface definition. Currently the
+following attributes are available for the ``"virtio"`` NIC driver:
+
+``name``
+ The optional ``name`` attribute forces which type of backend driver to use.
+ The value can be either 'qemu' (a user-space backend) or 'vhost' (a kernel
+ 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)`
+ 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)`
+ For interfaces of type='vhostuser', the ``name`` attribute is ignored. The
+ backend driver used is always vhost-user.
+``txmode``
+ The ``txmode`` attribute specifies how to handle transmission of packets when
+ the transmit buffer is full. The value can be either 'iothread' or 'timer'.
+ :since:`Since 0.8.8 (QEMU and KVM only)`
+ If set to 'iothread', packet tx is all done in an iothread in the bottom half
+ of the driver (this option translates into adding "tx=bh" to the qemu
+ commandline -device virtio-net-pci option).
+ If set to 'timer', tx work is done in qemu, and if there is more tx data than
+ can be sent at the present time, a timer is set before qemu moves on to do
+ other things; when the timer fires, another attempt is made to send more
+ data.
+ The resulting difference, according to the qemu developer who added the
+ option is: "bh makes tx more asynchronous and reduces latency, but
+ potentially causes more processor bandwidth contention since the CPU doing
+ the tx isn't necessarily the CPU where the guest generated the packets."
+ **In general you should leave this option alone, unless you are very certain
+ you know what you are doing.**
+``ioeventfd``
+ This optional attribute allows users to set `domain I/O asynchronous
+ handling <https://patchwork.kernel.org/patch/43390/>`__ for interface device.
+ The default is left to the discretion of the hypervisor. Accepted values are
+ "on" and "off". Enabling this allows qemu to execute VM while a separate
+ thread handles I/O. Typically guests experiencing high system CPU utilization
+ during I/O will benefit from this. On the other hand, on overloaded host it
+ could increase guest I/O latency. :since:`Since 0.9.3 (QEMU and KVM only)`
+ **In general you should leave this option alone, unless you are very certain
+ you know what you are doing.**
+``event_idx``
+ The ``event_idx`` attribute controls some aspects of device event processing.
+ The value can be either 'on' or 'off' - if it is on, it will 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, unless you are very certain
+ you know what you are doing.**
+``queues``
+ The optional ``queues`` attribute controls the number of queues to be used
+ for either `Multiqueue
+ virtio-net <https://www.linux-kvm.org/page/Multiqueue>`__ or
+ `vhost-user <#elementVhostuser>`__ network interfaces. Use of multiple packet
+ 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)`
+``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)`
+ **In general you should leave this option alone, unless you are very certain
+ you know what you are doing.**
+``tx_queue_size``
+ The optional ``tx_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, QEMU v2.9 requires value to be a
+ power of two from [256, 1024] range. In addition to that, this may work only
+ for a subset of interface types, e.g. aforementioned QEMU enables this option
+ only for ``vhostuser`` type. :since:`Since 3.7.0 (QEMU and KVM only)`
+ **In general you should leave this option alone, unless you are very certain
+ you know what you are doing.**
+virtio options
+ For virtio interfaces, `Virtio-specific options <#elementsVirtio>`__ can also
+ be set. ( :since:`Since 3.5.0` )
+
+Offloading options for the host and guest can be configured using the following
+sub-elements:
+
+``host``
+ The ``csum``, ``gso``, ``tso4``, ``tso6``, ``ecn`` and ``ufo`` attributes
+ with possible values ``on`` and ``off`` can be used to turn off host
+ offloading options. By default, the supported offloads are enabled by QEMU.
+ :since:`Since 1.2.9 (QEMU only)` The ``mrg_rxbuf`` attribute can be used to
+ control mergeable rx buffers on the host side. Possible values are ``on``
+ (default) and ``off``. :since:`Since 1.2.13 (QEMU only)`
+``guest``
+ The ``csum``, ``tso4``, ``tso6``, ``ecn`` and ``ufo`` attributes with
+ possible values ``on`` and ``off`` can be used to turn off guest offloading
+ options. By default, the supported offloads are enabled by QEMU.
+ :since:`Since 1.2.9 (QEMU only)`
+
+:anchor:`<a id="elementsBackendOptions"/>`
+
+Setting network backend-specific options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <target dev='vnet1'/>
+ <model type='virtio'/>
+ <backend tap='/dev/net/tun' vhost='/dev/vhost-net'/>
+ <driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5'/>
+ <tune>
+ <sndbuf>1600</sndbuf>
+ </tune>
+ </interface>
+ </devices>
+ ...
+
+For tuning the backend of the network, the ``backend`` element can be used. The
+``vhost`` attribute can override the default vhost device path
+(``/dev/vhost-net``) for devices with ``virtio`` model. The ``tap`` attribute
+overrides the tun/tap device path (default: ``/dev/net/tun``) for network and
+bridge interfaces. This does not work in session mode. :since:`Since 1.2.9`
+
+For tap devices there is also ``sndbuf`` element which can adjust the size of
+send buffer in the host. :since:`Since 0.8.8`
+
+:anchor:`<a id="elementsNICSTargetOverride"/>`
+
+Overriding the target element
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <target dev='vnet1'/>
+ </interface>
+ </devices>
+ ...
+
+If no target is specified, certain hypervisors will automatically generate a
+name for the created tun device. This name can be manually specified, however
+the name *should not start with either 'vnet', 'vif', 'macvtap', or 'macvlan'*,
+which are prefixes reserved by libvirt and certain hypervisors. Manually
+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,
+the ``guest`` element should be used, as in the following snippet:
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <guest dev='myeth'/>
+ </interface>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsNICSBoot"/>`
+
+Specifying boot order
+^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <target dev='vnet1'/>
+ <boot order='1'/>
+ </interface>
+ </devices>
+ ...
+
+For hypervisors which support this, you can set a specific NIC to be used for
+network boot. The ``order`` attribute determines the order in which devices will
+be tried during boot sequence. The per-device ``boot`` elements cannot be used
+together with general boot elements in `BIOS bootloader <#elementsOSBIOS>`__
+section. :since:`Since 0.8.8`
+
+:anchor:`<a id="elementsNICSROM"/>`
+
+Interface ROM BIOS configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <target dev='vnet1'/>
+ <rom bar='on' file='/etc/fake/boot.bin'/>
+ </interface>
+ </devices>
+ ...
+
+For hypervisors which support this, you can change how a PCI Network device's
+ROM is presented to the guest. The ``bar`` attribute can be set to "on" or
+"off", and determines whether or not the device's ROM will be visible in the
+guest's 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"). 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)` .
+
+:anchor:`<a id="elementDomain"/>`
+
+Setting up a network backend in a driver domain
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ ...
+ <interface type='bridge'>
+ <source bridge='br0'/>
+ <backenddomain name='netvm'/>
+ </interface>
+ ...
+ </devices>
+ ...
+
+The optional ``backenddomain`` element allows specifying a backend domain (aka
+driver domain) for the interface. Use the ``name`` attribute to specify the
+backend domain name. You can use it to create a direct network link between
+domains (so data will not go through host system). Use with type 'ethernet' to
+create plain network link, or with type 'bridge' to connect to a bridge inside
+the backend domain. :since:`Since 1.2.13 (Xen only)`
+
+:anchor:`<a id="elementQoS"/>`
+
+Quality of service
+^^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <target dev='vnet0'/>
+ <bandwidth>
+ <inbound average='1000' peak='5000' floor='200' burst='1024'/>
+ <outbound average='128' peak='256' burst='256'/>
+ </bandwidth>
+ </interface>
+ </devices>
+ ...
+
+This part of interface XML provides setting quality of service. Incoming and
+outgoing traffic can be shaped independently. The ``bandwidth`` element and its
+child elements are described in the `QoS <formatnetwork.html#elementQoS>`__
+section of the Network XML.
+
+:anchor:`<a id="elementVlanTag"/>`
+
+Setting VLAN tag (on supported network types only)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='bridge'>
+ <vlan>
+ <tag id='42'/>
+ </vlan>
+ <source bridge='ovsbr0'/>
+ <virtualport type='openvswitch'>
+ <parameters interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
+ </virtualport>
+ </interface>
+ <interface type='bridge'>
+ <vlan trunk='yes'>
+ <tag id='42'/>
+ <tag id='123' nativeMode='untagged'/>
+ </vlan>
+ ...
+ </interface>
+ </devices>
+ ...
+
+If (and only if) the network connection used by the guest supports VLAN tagging
+transparent to the guest, an optional ``<vlan>`` element can specify one or more
+VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` .
+Network connections that support guest-transparent VLAN tagging include 1)
+type='bridge' interfaces connected to an Open vSwitch bridge :since:`Since
+0.10.0` , 2) SRIOV Virtual Functions (VF) used via type='hostdev' (direct device
+assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type='direct' with
+mode='passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All other
+connection types, including standard linux bridges and libvirt's own virtual
+networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
+provide their own way (outside of libvirt) to tag guest traffic onto a specific
+VLAN. Each tag is given in a separate ``<tag>`` subelement of ``<vlan>`` (for
+example: ``<tag id='42'/>``). For VLAN trunking of multiple tags (which is
+supported only on Open vSwitch connections), multiple ``<tag>`` subelements can
+be specified, which implies that the user wants to do VLAN trunking on the
+interface for all the specified tags. In the case that VLAN trunking of a single
+tag is desired, the optional attribute ``trunk='yes'`` can be added to the
+toplevel ``<vlan>`` element to differentiate trunking of a single tag from
+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
+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
+be the "native" VLAN for this interface, and the ``nativeMode`` attribute
+determines whether or not traffic for that VLAN will be tagged.
+
+:anchor:`<a id="elementPort"/>`
+
+Isolating guests's network traffic from each other
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <port isolated='yes'/>
+ </interface>
+ </devices>
+ ...
+
+: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
+emulated interface devices that use a standard tap device to connect to the
+network via a Linux host bridge. This property can be inherited from a libvirt
+network, so if all guests that will be connected to the network should be
+isolated, it is better to put the setting in the network configuration. (NB:
+this only prevents guests that have ``isolated='yes'`` from communicating with
+each other; if there is a guest on the same bridge that doesn't have
+``isolated='yes'``, even the isolated guests will be able to communicate with
+it.)
+
+:anchor:`<a id="elementLink"/>`
+
+Modifying virtual link state
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <target dev='vnet0'/>
+ <link state='down'/>
+ </interface>
+ </devices>
+ ...
+
+This element provides means of setting state of the virtual network link.
+Possible values for attribute ``state`` are ``up`` and ``down``. If ``down`` is
+specified as the value, the interface behaves as if it had the network cable
+disconnected. Default behavior if this element is unspecified is to have the
+link state ``up``. :since:`Since 0.9.5`
+
+:anchor:`<a id="mtu"/>`
+
+MTU configuration
+^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <target dev='vnet0'/>
+ <mtu size='1500'/>
+ </interface>
+ </devices>
+ ...
+
+This element provides means of setting MTU of the virtual network link.
+Currently there is just one attribute ``size`` which accepts a non-negative
+integer which specifies the MTU size for the interface. :since:`Since 3.1.0`
+
+:anchor:`<a id="coalesce"/>`
+
+Coalesce settings
+^^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <target dev='vnet0'/>
+ <coalesce>
+ <rx>
+ <frames max='7'/>
+ </rx>
+ </coalesce>
+ </interface>
+ </devices>
+ ...
+
+This element provides means of setting coalesce settings for some interface
+devices (currently only type ``network`` and ``bridge``. Currently there is just
+one attribute, ``max``, to tweak, in element ``frames`` for the ``rx`` group,
+which accepts a non-negative integer that specifies the maximum number of
+packets that will be received before an interrupt. :since:`Since 3.3.0`
+
+:anchor:`<a id="ipconfig"/>`
+
+IP configuration
+^^^^^^^^^^^^^^^^
+
+::
+
+ ...
+ <devices>
+ <interface type='network'>
+ <source network='default'/>
+ <target dev='vnet0'/>
+ <ip address='192.168.122.5' prefix='24'/>
+ <ip address='192.168.122.5' prefix='24' peer='10.0.0.10'/>
+ <route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/>
+ <route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/>
+ </interface>
+ ...
+ <hostdev mode='capabilities' type='net'>
+ <source>
+ <interface>eth0</interface>
+ </source>
+ <ip address='192.168.122.6' prefix='24'/>
+ <route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/>
+ <route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/>
+ </hostdev>
+ ...
+ </devices>
+ ...
+
+:since:`Since 1.2.12` network devices and hostdev devices with network
+capabilities can optionally be provided one or more IP addresses to set on the
+network device in the guest. Note that some hypervisors or network device types
+will simply ignore them or only use the first one. The ``family`` attribute can
+be set to either ``ipv4`` or ``ipv6``, and the ``address`` attribute contains
+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
+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)` .
+
+: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
+documentation for the ``route`` element in `network
+definitions <formatnetwork.html#elementsStaticroute>`__. This is used by the LXC
+driver.
+
+::
+
+ ...
+ <devices>
+ <interface type='ethernet'>
+ <source/>
+ <ip address='192.168.123.1' prefix='24'/>
+ <ip address='10.0.0.10' prefix='24' peer='192.168.122.5'/>
+ <route family='ipv4' address='192.168.42.0' prefix='24' gateway='192.168.123.4'/>
+ <source/>
+ ...
+ </interface>
+ ...
+ </devices>
+ ...
+
+:since:`Since 2.1.0` network devices of type "ethernet" can optionally be
+provided one or more IP addresses and one or more routes to set on the **host**
+side of the network device. These are configured as subelements of the
+``<source>`` element of the interface, and have the same attributes as the
+similarly named elements used to configure the guest side of the interface
+(described above).
+
+:anchor:`<a id="elementVhostuser"/>`
+
+vhost-user interface
+^^^^^^^^^^^^^^^^^^^^
+
+:since:`Since 1.2.7` the vhost-user enables the communication between a QEMU
+virtual machine and other userspace process using the Virtio transport protocol.
+A char dev (e.g. Unix socket) is used for the control plane, while the data
+plane is based on shared memory.
+
+::
+
+ ...
+ <devices>
+ <interface type='vhostuser'>
+ <mac address='52:54:00:3b:83:1a'/>
+ <source type='unix' path='/tmp/vhost1.sock' mode='server'/>
+ <model type='virtio'/>
+ </interface>
+ <interface type='vhostuser'>
+ <mac address='52:54:00:3b:83:1b'/>
+ <source type='unix' path='/tmp/vhost2.sock' mode='client'>
+ <reconnect enabled='yes' timeout='10'/>
+ </source>
+ <model type='virtio'/>
+ <driver queues='5'/>
+ </interface>
+ </devices>
+ ...
+
+The ``<source>`` element has to be specified along with the type of char device.
+Currently, only type='unix' is supported, where the path (the directory path of
+the socket) and mode attributes are required. Both ``mode='server'`` and
+``mode='client'`` are supported. vhost-user requires the virtio model type, thus
+the ``<model>`` element is mandatory. :since:`Since 4.1.0` the element has an
+optional child element ``reconnect`` which configures reconnect timeout if the
+connection is lost. It has two attributes ``enabled`` (which accepts ``yes`` and
+``no``) and ``timeout`` which specifies the amount of seconds after which
+hypervisor tries to reconnect.
+
+:anchor:`<a id="elementNwfilter"/>`
+
+Traffic filtering with NWFilter
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:since:`Since 0.8.0` an ``nwfilter`` profile can be assigned to a domain
+interface, which allows configuring traffic filter rules for the virtual
+machine. See the `nwfilter <formatnwfilter.html>`__ documentation for more
+complete details.
+
+::
+
+ ...
+ <devices>
+ <interface ...>
+ ...
+ <filterref filter='clean-traffic'/>
+ </interface>
+ <interface ...>
+ ...
+ <filterref filter='myfilter'>
+ <parameter name='IP' value='104.207.129.11'/>
+ <parameter name='IP6_ADDR' value='2001:19f0:300:2102::'/>
+ <parameter name='IP6_MASK' value='64'/>
+ ...
+ </filterref>
+ </interface>
+ </devices>
+ ...
+
+The ``filter`` attribute specifies the name of the nwfilter to use. Optional
+``<parameter>`` elements may be specified for passing additional info to the
+nwfilter via the ``name`` and ``value`` attributes. See the
+`nwfilter <formatnwfilter.html#nwfconceptsvars>`__ docs for info on parameters.
+
+:anchor:`<a id="elementsInput"/>`
+
+Input devices
+~~~~~~~~~~~~~
+
+Input devices allow interaction with the graphical framebuffer in the guest
+virtual machine. When enabling the framebuffer, an input device is automatically
+provided. It may be possible to add additional devices explicitly, for example,
+to provide a graphics tablet for absolute cursor movement.
+
+::
+
+ ...
+ <devices>
+ <input type='mouse' bus='usb'/>
+ <input type='keyboard' bus='usb'/>
+ <input type='mouse' bus='virtio'/>
+ <input type='keyboard' bus='virtio'/>
+ <input type='tablet' bus='virtio'/>
+ <input type='passthrough' bus='virtio'>
+ <source evdev='/dev/input/event1'/>
+ </input>
+ </devices>
+ ...
+
+``input``
+ The ``input`` element has one mandatory attribute, the ``type`` whose value
+ can be 'mouse', 'tablet', ( :since:`since 1.2.2` ) 'keyboard' or (
+ :since:`since 1.3.0` ) 'passthrough'. The tablet provides absolute cursor
+ movement, while the mouse uses relative movement. The optional ``bus``
+ attribute can be used to refine the exact device type. It takes values "xen"
+ (paravirtualized), "ps2" and "usb" or ( :since:`since 1.3.0` ) "virtio".
+
+The ``input`` element has an optional sub-element ``<address>`` which can tie
+the device to a particular PCI slot, `documented above <#elementsAddress>`__. On
+S390, ``address`` can be used to provide a CCW address for an input device (
+:since:`since 4.2.0` ). For type ``passthrough``, the mandatory sub-element
+``source`` must have an ``evdev`` attribute containing the absolute path to the
+event device passed through to guests. (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 <#elementsVirtioTransitional>`__ for more details.
+
+The subelement ``driver`` can be used to tune the virtio options of the device:
+`Virtio-specific options <#elementsVirtio>`__ can also be set. ( :since:`Since
+3.5.0` )
+
+:anchor:`<a id="elementsHub"/>`
+
+Hub devices
+~~~~~~~~~~~
+
+A hub is a device that expands a single port into several so that there are more
+ports available to connect devices to a host system.
+
+::
+
+ ...
+ <devices>
+ <hub type='usb'/>
+ </devices>
+ ...
+
+``hub``
+ The ``hub`` element has one mandatory attribute, the ``type`` whose value can
+ only be 'usb'.
+
+The ``hub`` element has an optional sub-element ``<address>`` with
+``type='usb'``\ which can tie the device to a particular controller, `documented
+above <#elementsAddress>`__.
+
+:anchor:`<a id="elementsGraphics"/>`
+
+Graphical framebuffers
+~~~~~~~~~~~~~~~~~~~~~~
+
+A graphics device allows for graphical interaction with the guest OS. A guest
+will typically have either a framebuffer or a text console configured to allow
+interaction with the admin.
+
+::
+
+ ...
+ <devices>
+ <graphics type='sdl' display=':0.0'/>
+ <graphics type='vnc' port='5904' sharePolicy='allow-exclusive'>
+ <listen type='address' address='1.2.3.4'/>
+ </graphics>
+ <graphics type='rdp' autoport='yes' multiUser='yes' />
+ <graphics type='desktop' fullscreen='yes'/>
+ <graphics type='spice'>
+ <listen type='network' network='rednet'/>
+ </graphics>
+ </devices>
+ ...
+
+``graphics``
+ The ``graphics`` element has a mandatory ``type`` attribute which takes the
+ value ``sdl``, ``vnc``, ``spice``, ``rdp``, ``desktop`` or ``egl-headless``:
+
+ ``sdl``
+ This displays a window on the host desktop, it can take 3 optional
+ arguments: a ``display`` attribute for the display to use, an ``xauth``
+ attribute for the authentication identifier, and an optional
+ ``fullscreen`` attribute accepting values ``yes`` or ``no``.
+
+ You can use a ``gl`` with the ``enable="yes"`` property to enable OpenGL
+ support in SDL. Likewise you can explicitly disable OpenGL support with
+ ``enable="no"``.
+
+ ``vnc``
+ Starts a VNC server. The ``port`` attribute specifies the TCP port number
+ (with -1 as legacy syntax indicating that it should be auto-allocated).
+ The ``autoport`` attribute is the new preferred syntax for indicating
+ auto-allocation of the TCP port to use. The ``passwd`` attribute provides
+ a VNC password in clear text. If the ``passwd`` attribute is set to an
+ empty string, then VNC access is disabled. The ``keymap`` attribute
+ specifies the keymap to use. It is possible to set a limit on the validity
+ 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
+ may not be supported by all hypervisors.
+
+ The optional ``sharePolicy`` attribute specifies vnc server display
+ sharing policy. ``allow-exclusive`` allows clients to ask for exclusive
+ access by dropping other connections. Connecting multiple clients in
+ parallel requires all clients asking for a shared session (vncviewer:
+ -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` .
+
+ Rather than using listen/port, QEMU supports a ``socket`` attribute for
+ 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` .
+
+ Although VNC doesn't support OpenGL natively, it can be paired with
+ graphics type ``egl-headless`` (see below) which will instruct QEMU to
+ open and use drm nodes for OpenGL rendering.
+
+ ``spice`` :since:`Since 0.8.6`
+ Starts a SPICE server. The ``port`` attribute specifies the TCP port
+ number (with -1 as legacy syntax indicating that it should be
+ auto-allocated), while ``tlsPort`` gives an alternative secure port
+ number. The ``autoport`` attribute is the new preferred syntax for
+ indicating auto-allocation of needed port numbers. The ``passwd``
+ attribute provides a SPICE password in clear text. If the ``passwd``
+ attribute is set to an empty string, then SPICE access is disabled. The
+ ``keymap`` attribute specifies the keymap to use. It is possible to set a
+ limit on the validity 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. SPICE accepts ``keep`` to keep client connected,
+ ``disconnect`` to disconnect client and ``fail`` to fail changing password
+ . NB, this may not be supported by all hypervisors. :since:`Since 0.9.3`
+
+ The ``defaultMode`` attribute sets the default channel security policy,
+ valid values are ``secure``, ``insecure`` and the default ``any`` (which
+ is secure if possible, but falls back to insecure rather than erroring out
+ if no secure path is available). :since:`Since 0.9.12`
+
+ When SPICE has both a normal and TLS secured TCP port configured, it can
+ be desirable to restrict what channels can be run on each port. This is
+ achieved by adding one or more ``<channel>`` elements inside the main
+ ``<graphics>`` element and setting the ``mode`` attribute to either
+ ``secure`` or ``insecure``. Setting the mode attribute overrides the
+ default value as set by the ``defaultMode`` attribute. (Note that
+ specifying ``any`` as mode discards the entry as the channel would inherit
+ the default mode anyways.) Valid channel names include ``main``,
+ ``display``, ``inputs``, ``cursor``, ``playback``, ``record`` (all
+ :since:` since 0.8.6` ); ``smartcard`` ( :since:`since 0.8.8` ); and
+ ``usbredir`` ( :since:`since 0.9.12` ).
+
+ ::
+
+ <graphics type='spice' port='-1' tlsPort='-1' autoport='yes'>
+ <channel name='main' mode='secure'/>
+ <channel name='record' mode='insecure'/>
+ <image compression='auto_glz'/>
+ <streaming mode='filter'/>
+ <clipboard copypaste='no'/>
+ <mouse mode='client'/>
+ <filetransfer enable='no'/>
+ <gl enable='yes' rendernode='/dev/dri/by-path/pci-0000:00:02.0-render'/>
+ </graphics>
+
+ Spice supports variable compression settings for audio, images and
+ streaming. These settings are accessible via the ``compression`` attribute
+ in all following elements: ``image`` to set image compression (accepts
+ ``auto_glz``, ``auto_lz``, ``quic``, ``glz``, ``lz``, ``off``), ``jpeg``
+ for JPEG compression for images over wan (accepts ``auto``, ``never``,
+ ``always``), ``zlib`` for configuring wan image compression (accepts
+ ``auto``, ``never``, ``always``) and ``playback`` for enabling audio
+ stream compression (accepts ``on`` or ``off``). :since:`Since 0.9.1`
+
+ Streaming mode is set by the ``streaming`` element, settings its ``mode``
+ attribute to one of ``filter``, ``all`` or ``off``. :since:`Since 0.9.2`
+
+ Copy & Paste functionality (via Spice agent) is set by the ``clipboard``
+ element. It is enabled by default, and can be disabled by setting the
+ ``copypaste`` property to ``no``. :since:`Since 0.9.3`
+
+ Mouse mode is set by the ``mouse`` element, setting its ``mode`` attribute
+ to one of ``server`` or ``client``. If no mode is specified, the qemu
+ default will be used (client mode). :since:`Since 0.9.11`
+
+ File transfer functionality (via Spice agent) is set using the
+ ``filetransfer`` element. It is enabled by default, and can be disabled by
+ setting the ``enable`` property to ``no``. :since:`Since 1.2.2`
+
+ Spice may provide accelerated server-side rendering with OpenGL. You can
+ enable or disable OpenGL support explicitly with the ``gl`` element, by
+ setting the ``enable`` property. (QEMU only, :since:`since 1.3.3` ). Note
+ that this only works locally, since this requires usage of UNIX sockets,
+ i.e. using ``listen`` types 'socket' or 'none'. For accelerated OpenGL
+ with remote support, consider pairing this element with type
+ ``egl-headless`` (see below). However, this will deliver weaker
+ performance compared to native Spice OpenGL support.
+
+ By default, QEMU will pick the first available GPU DRM render node. You
+ may specify a DRM render node path to use instead. (QEMU only,
+ :since:`since 3.1.0` ).
+
+ ``rdp``
+ Starts a RDP server. The ``port`` attribute specifies the TCP port number
+ (with -1 as legacy syntax indicating that it should be auto-allocated).
+ The ``autoport`` attribute is the new preferred syntax for indicating
+ auto-allocation of the TCP port to use. In the VirtualBox driver, the
+ ``autoport`` will make the hypervisor pick available port from 3389-3689
+ range when the VM is started. The chosen port will be reflected in the
+ ``port`` attribute. The ``multiUser`` attribute is a boolean deciding
+ whether multiple simultaneous connections to the VM are permitted. The
+ ``replaceUser`` attribute is a boolean deciding whether the existing
+ connection must be dropped and a new connection must be established by the
+ VRDP server, when a new client connects in single connection mode.
+
+ ``desktop``
+ This value is reserved for VirtualBox domains for the moment. It displays
+ a window on the host desktop, similarly to "sdl", but using the VirtualBox
+ viewer. Just like "sdl", it accepts the optional attributes ``display``
+ and ``fullscreen``.
+
+ ``egl-headless`` :since:`Since 4.6.0`
+ This display type provides support for an OpenGL accelerated display
+ accessible both locally and remotely (for comparison, Spice's native
+ OpenGL support only works locally using UNIX sockets at the moment, but
+ has better performance). Since this display type doesn't provide any
+ window or graphical console like the other types, for practical reasons it
+ should be paired with either ``vnc`` or ``spice`` graphics types. This
+ display type is only supported by QEMU domains (needs QEMU :since:`2.10`
+ or newer). :since:`5.0.0` this element accepts a ``<gl/>`` sub-element
+ with an optional attribute ``rendernode`` which can be used to specify an
+ absolute path to a host's DRI device to be used for OpenGL rendering.
+
+ ::
+
+ <graphics type='spice' autoport='yes'/>
+ <graphics type='egl-headless'>
+ <gl rendernode='/dev/dri/renderD128'/>
+ </graphics>
+
+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:
+
+``address``
+ Tells a graphics device to use an address specified in the ``address``
+ attribute, which will contain either an IP address or hostname (which will be
+ 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` .
+
+ The ``address`` attribute is duplicated as ``listen`` attribute in
+ ``graphics`` element for backward compatibility. If both are provided they
+ must be equal.
+
+``network``
+ This is used to specify an existing network in the ``network`` attribute from
+ libvirt's list of configured networks. The named network configuration will
+ be examined to determine an appropriate listen address and the address will
+ be stored in live XML in ``address`` attribute. For example, if the network
+ has an IPv4 address in its configuration (e.g. if it has a forward type of
+ ``route``, ``nat``, or no forward type (isolated)), the first IPv4 address
+ listed in the network's configuration will be used. If the network is
+ describing a host bridge, the first IPv4 address associated with that bridge
+ device will be used, and if the network is describing one of the 'direct'
+ (macvtap) modes, the first IPv4 address of the first forward dev will be
+ used.
+
+``socket`` :since:`since 2.0.0 (QEMU only)`
+ This listen type tells a graphics server to listen on unix socket. Attribute
+ ``socket`` contains a path to unix socket. If this attribute is omitted
+ libvirt will generate this path for you. Supported by graphics type ``vnc``
+ and ``spice``.
+
+ For ``vnc`` graphics be backward compatible the ``socket`` attribute of first
+ ``listen`` element is duplicated as ``socket`` attribute in ``graphics``
+ element. If ``graphics`` element contains a ``socket`` attribute all
+ ``listen`` elements are ignored.
+
+``none`` :since:`since 2.0.0 (QEMU only)`
+ This listen type doesn't have any other attribute. Libvirt supports passing a
+ file descriptor through our APIs virDomainOpenGraphics() and
+ virDomainOpenGraphicsFD(). No other listen types are allowed if this one is
+ used and the graphics device doesn't listen anywhere. You need to use one of
+ the two APIs to pass a FD to QEMU in order to connect to this graphics
+ device. Supported by graphics type ``vnc`` and ``spice``.
+
+:anchor:`<a id="elementsVideo"/>`
+
+Video devices
+~~~~~~~~~~~~~
+
+A video device.
+
+::
+
+ ...
+ <devices>
+ <video>
+ <model type='vga' vram='16384' heads='1'>
+ <acceleration accel3d='yes' accel2d='yes'/>
+ </model>
+ <driver name='qemu'/>
+ </video>
+ </devices>
+ ...
+
+``video``
+ The ``video`` element is the container for describing video devices. For
+ backwards compatibility, if no ``video`` is set but there is a ``graphics``
+ in domain xml, then libvirt will add a default ``video`` according to the
+ guest type.
+
+ For a guest of type "kvm", the default ``video`` is: ``type`` with value
+ "cirrus", ``vram`` with value "16384" and ``heads`` with value "1". By
+ default, the first video device in domain xml is the primary one, but the
+ optional attribute ``primary`` ( :since:`since 1.0.2` ) with value 'yes' can
+ be used to mark the primary in cases of multiple video device. The
+ non-primary must be type of "qxl" or ( :since:`since 2.4.0` ) "virtio".
+
+``model``
+ The ``model`` element has a mandatory ``type`` attribute which takes the
+ value "vga", "cirrus", "vmvga", "xen", "vbox", "qxl" ( :since:`since 0.8.6`
+ ), "virtio" ( :since:`since 1.3.0` ), "gop" ( :since:`since 3.2.0` ), "bochs"
+ ( :since:`since 5.6.0` ), "ramfb" ( :since:`since 5.9.0` ), or "none" (
+ :since:`since 4.6.0` , depending on the hypervisor features available. The
+ purpose of the type ``none`` is to instruct libvirt not to add a default
+ video device in the guest (see the paragraph above). This legacy behaviour
+ can be inconvenient in cases where GPU mediated devices are meant to be the
+ only rendering device within a guest and so specifying another ``video``
+ device along with type ``none``. Refer to Host device assignment to see how
+ to add a mediated device into a guest.
+
+ You can provide the amount of video memory in kibibytes (blocks of 1024
+ bytes) using ``vram``. This is supported only for guest type of "vz", "qemu",
+ "vbox", "vmx" and "xen". If no value is provided the default is used. If the
+ size is not a power of two it will be rounded to closest one.
+
+ The number of screen can be set using ``heads``. This is supported only for
+ guests type of "vz", "kvm", "vbox" and "vmx".
+
+ For guest type of "kvm" or "qemu" and model type "qxl" there are optional
+ attributes. Attribute ``ram`` ( :since:` since 1.0.2` ) specifies the size of
+ the primary bar, while the attribute ``vram`` specifies the secondary bar
+ size. If ``ram`` or ``vram`` are not supplied a default value is used. The
+ ``ram`` should also be rounded to power of two as ``vram``. There is also
+ optional attribute ``vgamem`` ( :since:`since 1.2.11` ) to set the size of
+ VGA framebuffer for fallback mode of QXL device. Attribute ``vram64`` (
+ :since:`since 1.3.3` ) extends secondary bar and makes it addressable as
+ 64bit memory.
+
+ :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", and "virtio".
+
+``acceleration``
+ Configure if video acceleration should be enabled.
+
+ ``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
+ :since:`since 1.3.0` )
+ ``rendernode``
+ Absolute path to a host's DRI device to be used for rendering (for
+ 'vhostuser' driver only, :since:`since 5.8.0` ). If none is specified,
+ libvirt will pick one available.
+
+``address``
+ The optional ``address`` sub-element can be used to tie the video device to a
+ particular PCI slot. On S390, ``address`` can be used to provide the CCW
+ address for the video device ( :since:` since 4.2.0` ).
+``driver``
+ The subelement ``driver`` can be used to tune the device:
+
+ ``name``
+ Specify the backend driver to use, either "qemu" or "vhostuser" depending
+ on the hypervisor features available ( :since:`since 5.8.0` ). "qemu" is
+ the default QEMU backend. "vhostuser" will use a separate vhost-user
+ process backend (for ``virtio`` device).
+ virtio options
+ `Virtio-specific options <#elementsVirtio>`__ can also be set (
+ :since:`Since 3.5.0` )
+ VGA configuration
+ Control how the video devices exposed to the guest using the ``vgaconf``
+ attribute which takes the value "io", "on" or "off". At present, it's only
+ applicable to the bhyve's "gop" video model type ( :since:`Since 3.5.0` )
+
+:anchor:`<a id="elementsConsole"/>`
+
+Consoles, serial, parallel & channel devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A character device provides a way to interact with the virtual machine.
+Paravirtualized consoles, serial ports, parallel ports and channels are all
+classed as character devices and so represented using the same syntax.
+
+::
+
+ ...
+ <devices>
+ <parallel type='pty'>
+ <source path='/dev/pts/2'/>
+ <target port='0'/>
+ </parallel>
+ <serial type='pty'>
+ <source path='/dev/pts/3'/>
+ <target port='0'/>
+ </serial>
+ <serial type='file'>
+ <source path='/tmp/file' append='on'>
+ <seclabel model='dac' relabel='no'/>
+ </source>
+ <target port='0'/>
+ </serial>
+ <console type='pty'>
+ <source path='/dev/pts/4'/>
+ <target port='0'/>
+ </console>
+ <channel type='unix'>
+ <source mode='bind' path='/tmp/guestfwd'/>
+ <target type='guestfwd' address='10.0.2.1' port='4600'/>
+ </channel>
+ </devices>
+ ...
+
+In each of these directives, the top-level element name (parallel, serial,
+console, channel) describes how the device is presented to the guest. The guest
+interface is configured by the ``target`` element.
+
+The interface presented to the host is given in the ``type`` attribute of the
+top-level element. The host interface is configured by the ``source`` element.
+
+The ``source`` element may contain an optional ``seclabel`` to override the way
+that labelling is done on the socket path. If this element is not present, the
+`security label is inherited from the per-domain setting <#seclabel>`__.
+
+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` .
+
+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` .
+
+::
+
+ ...
+ <log file="/var/log/libvirt/qemu/guestname-serial0.log" append="off"/>
+ ...
+
+Each character device element has an optional sub-element ``<address>`` which
+can tie the device to a particular `controller <#elementsControllers>`__ or PCI
+slot.
+
+For character device with type ``unix`` or ``tcp`` the ``source`` has an
+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)` .
+
+:anchor:`<a id="elementsCharGuestInterface"/>`
+
+Guest interface
+^^^^^^^^^^^^^^^
+
+A character device presents itself to the guest as one of the following types.
+
+:anchor:`<a id="elementCharParallel"/>`
+
+Parallel port
+'''''''''''''
+
+::
+
+ ...
+ <devices>
+ <parallel type='pty'>
+ <source path='/dev/pts/2'/>
+ <target port='0'/>
+ </parallel>
+ </devices>
+ ...
+
+``target`` can have a ``port`` attribute, which specifies the port number. Ports
+are numbered starting from 0. There are usually 0, 1 or 2 parallel ports.
+
+:anchor:`<a id="elementCharSerial"/>`
+
+Serial port
+'''''''''''
+
+::
+
+ ...
+ <devices>
+ <!-- Serial port -->
+ <serial type='pty'>
+ <source path='/dev/pts/3'/>
+ <target port='0'/>
+ </serial>
+ </devices>
+ ...
+
+::
+
+ ...
+ <devices>
+ <!-- USB serial port -->
+ <serial type='pty'>
+ <target type='usb-serial' port='0'>
+ <model name='usb-serial'/>
+ </target>
+ <address type='usb' bus='0' port='1'/>
+ </serial>
+ </devices>
+ ...
+
+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),
+``usb-serial`` (usable whenever USB support is available) and ``pci-serial``
+(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) and
+``sclp-serial`` (usable with s390 and s390x guests) are available as well.
+
+: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
+``system-serial`` target type); ``sclpconsole`` and ``sclplmconsole`` (usable
+with the ``sclp-serial`` target type). Providing a target model is usually
+unnecessary: libvirt will automatically pick one that's suitable for the chosen
+target type, and overriding that value is generally not recommended.
+
+If any of the attributes is not specified by the user, libvirt will choose a
+value suitable for most users.
+
+Most target types support configuring the guest-visible device address as
+`documented above <#elementsAddress>`__; more specifically, acceptable address
+types are ``isa`` (for ``isa-serial``), ``usb`` (for ``usb-serial``), ``pci``
+(for ``pci-serial``) and ``spapr-vio`` (for ``spapr-vio-serial``). The
+``system-serial`` and ``sclp-serial`` target types don't support specifying an
+address.
+
+For the relationship between serial ports and consoles, `see
+below <#elementCharSerialAndConsole>`__.
+
+:anchor:`<a id="elementCharConsole"/>`
+
+Console
+'''''''
+
+::
+
+ ...
+ <devices>
+ <!-- Serial console -->
+ <console type='pty'>
+ <source path='/dev/pts/2'/>
+ <target type='serial' port='0'/>
+ </console>
+ </devices>
+ ...
+
+::
+
+ ...
+ <devices>
+ <!-- KVM virtio console -->
+ <console type='pty'>
+ <source path='/dev/pts/5'/>
+ <target type='virtio' port='0'/>
+ </console>
+ </devices>
+ ...
+
+The ``console`` element is used to represent interactive serial consoles.
+Depending on the type of guest in use and the specifics of the configuration,
+the ``console`` element might represent the same device as an existing
+``serial`` element or a separate device.
+
+A ``target`` subelement is supported and works the same way as with the
+``serial`` element (`see above <#elementCharSerial>`__ for details). Valid
+values for the ``type`` attribute are: ``serial`` (described below); ``virtio``
+(usable whenever VirtIO support is available); ``xen``, ``lxc`` and ``openvz``
+(available when the corresponding hypervisor is in use). ``sclp`` and ``sclplm``
+(usable for s390 and s390x QEMU guests) are supported for compatibility reasons
+but should not be used for new guests: use the ``sclpconsole`` and
+``sclplmconsole`` target models, respectively, with the ``serial`` element
+instead.
+
+Of the target types listed above, ``serial`` is special in that it doesn't
+represents a separate device, but rather the same device as the first ``serial``
+element. Due to this, there can only be a single ``console`` element with target
+type ``serial`` per guest.
+
+Virtio consoles are usually accessible as ``/dev/hvc[0-7]`` from inside the
+guest; for more information, see
+http://fedoraproject.org/wiki/Features/VirtioSerial. :since:`Since 0.8.3`
+
+For the relationship between serial ports and consoles, `see
+below <#elementCharSerialAndConsole>`__.
+
+:anchor:`<a id="elementCharSerialAndConsole"/>`
+
+Relationship between serial ports and consoles
+''''''''''''''''''''''''''''''''''''''''''''''
+
+Due to hystorical reasons, the ``serial`` and ``console`` elements have
+partially overlapping scopes.
+
+In general, both elements are used to configure one or more serial consoles to
+be used for interacting with the guest. The main difference between the two is
+that ``serial`` is used for emulated, usually native, serial consoles, whereas
+``console`` is used for paravirtualized ones.
+
+Both emulated and paravirtualized serial consoles have advantages and
+disadvantages:
+
+- emulated serial consoles are usually initialized much earlier than
+ paravirtualized ones, so they can be used to control the bootloader and
+ display both firmware and early boot messages;
+- on several platforms, there can only be a single emulated serial console per
+ guest but paravirtualized consoles don't suffer from the same limitation.
+
+A configuration such as:
+
+::
+
+ ...
+ <devices>
+ <console type='pty'>
+ <target type='serial'/>
+ </console>
+ <console type='pty'>
+ <target type='virtio'/>
+ </console>
+ </devices>
+ ...
+
+will work on any platform and will result in one emulated serial console for
+early boot logging / interactive / recovery use, and one paravirtualized serial
+console to be used eg. as a side channel. Most people will be fine with having
+just the first ``console`` element in their configuration, but if a specific
+configuration is desired then both elements should be specified.
+
+Note that, due to the compatibility concerns mentioned earlier, all the
+following configurations:
+
+::
+
+ ...
+ <devices>
+ <serial type='pty'/>
+ </devices>
+ ...
+
+::
+
+ ...
+ <devices>
+ <console type='pty'/>
+ </devices>
+ ...
+
+::
+
+ ...
+ <devices>
+ <serial type='pty'/>
+ <console type='pty'/>
+ </devices>
+ ...
+
+will be treated the same and will result in a single emulated serial console
+being available to the guest.
+
+:anchor:`<a id="elementCharChannel"/>`
+
+Channel
+'''''''
+
+This represents a private communication channel between the host and the guest.
+
+::
+
+ ...
+ <devices>
+ <channel type='unix'>
+ <source mode='bind' path='/tmp/guestfwd'/>
+ <target type='guestfwd' address='10.0.2.1' port='4600'/>
+ </channel>
+
+ <!-- KVM virtio channel -->
+ <channel type='pty'>
+ <target type='virtio' name='arbitrary.virtio.serial.port.name'/>
+ </channel>
+ <channel type='unix'>
+ <source mode='bind' path='/var/lib/libvirt/qemu/f16x86_64.agent'/>
+ <target type='virtio' name='org.qemu.guest_agent.0' state='connected'/>
+ </channel>
+ <channel type='spicevmc'>
+ <target type='virtio' name='com.redhat.spice.0'/>
+ </channel>
+ </devices>
+ ...
+
+This can be implemented in a variety of ways. The specific type of channel is
+given in the ``type`` attribute of the ``target`` element. Different channel
+types have different ``target`` attributes.
+
+``guestfwd``
+ TCP traffic sent by the guest to a given IP address and port is forwarded to
+ the channel device on the host. The ``target`` element must have ``address``
+ and ``port`` attributes. :since:`Since 0.7.3`
+``virtio``
+ Paravirtualized virtio channel. Channel is exposed in the guest under
+ /dev/vport*, and if the optional element ``name`` is specified,
+ /dev/virtio-ports/$name (for more info, please see
+ http://fedoraproject.org/wiki/Features/VirtioSerial). The optional element
+ ``address`` can tie the channel to a particular ``type='virtio-serial'``
+ controller, `documented above <#elementsAddress>`__. With qemu, if ``name``
+ is "org.qemu.guest_agent.0", then libvirt can interact with a guest agent
+ installed in the guest, for actions such as guest shutdown or file system
+ quiescing. :since:`Since 0.7.7, guest agent interaction since 0.9.10`
+ Moreover, :since:`since 1.0.6` it is possible to have source path auto
+ generated for virtio unix channels. This is very useful in case of a qemu
+ guest agent, where users don't usually care about the source path since it's
+ libvirt who talks to the guest agent. In case users want to utilize this
+ feature, they should leave ``<source>`` element out. :since:`Since 1.2.11`
+ the active XML for a virtio channel may contain an optional ``state``
+ attribute that reflects whether a process in the guest is active on the
+ channel. This is an output-only attribute. Possible values for the ``state``
+ attribute are ``connected`` and ``disconnected``.
+``xen``
+ Paravirtualized Xen channel. Channel is exposed in the guest as a Xen console
+ but identified with a name. Setup and consumption of a Xen channel depends on
+ software and configuration in the guest (for more info, please see
+ http://xenbits.xen.org/docs/unstable/misc/channel.txt). Channel source path
+ semantics are the same as the virtio target type. The ``state`` attribute is
+ not supported since Xen channels lack the necessary probing mechanism.
+ :since:`Since 2.3.0`
+``spicevmc``
+ Paravirtualized SPICE channel. The domain must also have a SPICE server as a
+ `graphics device <#elementsGraphics>`__, at which point the host piggy-backs
+ messages across the ``main`` channel. The ``target`` element must be present,
+ 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`
+
+:anchor:`<a id="elementsCharHostInterface"/>`
+
+Host interface
+^^^^^^^^^^^^^^
+
+A character device presents itself to the host as one of the following types.
+
+:anchor:`<a id="elementsCharSTDIO"/>`
+
+Domain logfile
+''''''''''''''
+
+This disables all input on the character device, and sends output into the
+virtual machine's logfile
+
+::
+
+ ...
+ <devices>
+ <console type='stdio'>
+ <target port='1'/>
+ </console>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsCharFle"/>`
+
+Device logfile
+''''''''''''''
+
+A file is opened and all data sent to the character device is written to the
+file.
+
+::
+
+ ...
+ <devices>
+ <serial type="file">
+ <source path="/var/log/vm/vm-serial.log"/>
+ <target port="1"/>
+ </serial>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsCharVC"/>`
+
+Virtual console
+'''''''''''''''
+
+Connects the character device to the graphical framebuffer in a virtual console.
+This is typically accessed via a special hotkey sequence such as "ctrl+alt+3"
+
+::
+
+ ...
+ <devices>
+ <serial type='vc'>
+ <target port="1"/>
+ </serial>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsCharNull"/>`
+
+Null device
+'''''''''''
+
+Connects the character device to the void. No data is ever provided to the
+input. All data written is discarded.
+
+::
+
+ ...
+ <devices>
+ <serial type='null'>
+ <target port="1"/>
+ </serial>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsCharPTY"/>`
+
+Pseudo TTY
+''''''''''
+
+A Pseudo TTY is allocated using /dev/ptmx. A suitable client such as 'virsh
+console' can connect to interact with the serial port locally.
+
+::
+
+ ...
+ <devices>
+ <serial type="pty">
+ <source path="/dev/pts/3"/>
+ <target port="1"/>
+ </serial>
+ </devices>
+ ...
+
+NB special case if <console type='pty'>, then the TTY path is also duplicated as
+an attribute tty='/dev/pts/3' on the top level <console> tag. This provides
+compat with existing syntax for <console> tags.
+
+:anchor:`<a id="elementsCharHost"/>`
+
+Host device proxy
+'''''''''''''''''
+
+The character device is passed through to the underlying physical character
+device. The device types must match, eg the emulated serial port should only be
+connected to a host serial port - don't connect a serial port to a parallel
+port.
+
+::
+
+ ...
+ <devices>
+ <serial type="dev">
+ <source path="/dev/ttyS0"/>
+ <target port="1"/>
+ </serial>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsCharPipe"/>`
+
+Named pipe
+''''''''''
+
+The character device writes output to a named pipe. See pipe(7) for more info.
+
+::
+
+ ...
+ <devices>
+ <serial type="pipe">
+ <source path="/tmp/mypipe"/>
+ <target port="1"/>
+ </serial>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsCharTCP"/>`
+
+TCP client/server
+'''''''''''''''''
+
+The character device acts as a TCP client connecting to a remote server.
+
+::
+
+ ...
+ <devices>
+ <serial type="tcp">
+ <source mode="connect" host="0.0.0.0" service="2445"/>
+ <protocol type="raw"/>
+ <target port="1"/>
+ </serial>
+ </devices>
+ ...
+
+Or as a TCP server waiting for a client connection.
+
+::
+
+ ...
+ <devices>
+ <serial type="tcp">
+ <source mode="bind" host="127.0.0.1" service="2445"/>
+ <protocol type="raw"/>
+ <target port="1"/>
+ </serial>
+ </devices>
+ ...
+
+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
+telnet) or ``tls`` (via secure sockets layer) as the transport protocol for
+connections.
+
+::
+
+ ...
+ <devices>
+ <serial type="tcp">
+ <source mode="connect" host="0.0.0.0" service="2445"/>
+ <protocol type="telnet"/>
+ <target port="1"/>
+ </serial>
+ ...
+ <serial type="tcp">
+ <source mode="bind" host="127.0.0.1" service="2445"/>
+ <protocol type="telnet"/>
+ <target port="1"/>
+ </serial>
+ </devices>
+ ...
+
+: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
+on the host by the ``chardev_tls`` and ``chardev_tls_x509_cert_dir`` or
+``default_tls_x509_cert_dir`` settings in the file /etc/libvirt/qemu.conf. If
+``chardev_tls`` is enabled, then unless the ``tls`` attribute is set to "no",
+libvirt will use the host configured TLS environment. If ``chardev_tls`` is
+disabled, but the ``tls`` attribute is set to "yes", then libvirt will attempt
+to use the host TLS environment if either the ``chardev_tls_x509_cert_dir`` or
+``default_tls_x509_cert_dir`` TLS directory structure exists.
+
+::
+
+ ...
+ <devices>
+ <serial type="tcp">
+ <source mode='connect' host="127.0.0.1" service="5555" tls="yes"/>
+ <protocol type="raw"/>
+ <target port="0"/>
+ </serial>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsCharUDP"/>`
+
+UDP network console
+'''''''''''''''''''
+
+The character device acts as a UDP netconsole service, sending and receiving
+packets. This is a lossy service.
+
+::
+
+ ...
+ <devices>
+ <serial type="udp">
+ <source mode="bind" host="0.0.0.0" service="2445"/>
+ <source mode="connect" host="0.0.0.0" service="2445"/>
+ <target port="1"/>
+ </serial>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsCharUNIX"/>`
+
+UNIX domain socket client/server
+''''''''''''''''''''''''''''''''
+
+The character device acts as a UNIX domain socket server, accepting connections
+from local clients.
+
+::
+
+ ...
+ <devices>
+ <serial type="unix">
+ <source mode="bind" path="/tmp/foo"/>
+ <target port="1"/>
+ </serial>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsCharSpiceport"/>`
+
+Spice channel
+'''''''''''''
+
+The character device is accessible through spice connection under a channel name
+specified in the ``channel`` attribute. :since:`Since 1.2.2`
+
+Note: depending on the hypervisor, spiceports might (or might not) be enabled on
+domains with or without `spice graphics <#elementsGraphics>`__.
+
+::
+
+ ...
+ <devices>
+ <serial type="spiceport">
+ <source channel="org.qemu.console.serial.0"/>
+ <target port="1"/>
+ </serial>
+ </devices>
+ ...
+
+:anchor:`<a id="elementsNmdm"/>`
+
+Nmdm device
+'''''''''''
+
+The nmdm device driver, available on FreeBSD, provides two tty devices connected
+together by a virtual null modem cable. :since:`Since 1.2.4`
+
+::
+
+ ...
+ <devices>
+ <serial type="nmdm">
+ <source master="/dev/nmdm0A" slave="/dev/nmdm0B"/>
+ </serial>
+ </devices>
+ ...
+
+The ``source`` element has these attributes:
+
+``master``
+ Master device of the pair, that is passed to the hypervisor. Device is
+ specified by a fully qualified path.
+``slave``
+ Slave device of the pair, that is passed to the clients for connection to the
+ guest console. Device is specified by a fully qualified path.
+
+:anchor:`<a id="elementsSound"/>`
+
+Sound devices
+~~~~~~~~~~~~~
+
+A virtual sound card can be attached to the host via the ``sound`` element.
+:since:`Since 0.4.3`
+
+::
+
+ ...
+ <devices>
+ <sound model='es1370'/>
+ </devices>
+ ...
+
+``sound``
+ The ``sound`` element has one mandatory attribute, ``model``, which specifies
+ what real sound device is emulated. Valid values are specific to the
+ underlying hypervisor, though typical choices are 'es1370', 'sb16', 'ac97',
+ 'ich6' and 'usb'. ( :since:` 'ac97' only since 0.6.0, 'ich6' only since
+ 0.8.8, 'usb' only since 1.2.7` )
+
+:since:`Since 0.9.13` , a sound element with ``ich6`` model 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.
+
+Valid values are:
+
+- 'duplex' - advertise a line-in and a line-out
+- 'micro' - advertise a speaker and a microphone
+- 'output' - advertise a line-out :since:`Since 4.4.0`
+
+::
+
+ ...
+ <devices>
+ <sound model='ich6'>
+ <codec type='micro'/>
+ </sound>
+ </devices>
+ ...
+
+Each ``sound`` element has an optional sub-element ``<address>`` which can tie
+the device to a particular PCI slot, `documented above <#elementsAddress>`__.
+
+:anchor:`<a id="elementsWatchdog"/>`
+
+Watchdog device
+~~~~~~~~~~~~~~~
+
+A virtual hardware watchdog device can be added to the guest via the
+``watchdog`` element. :since:`Since 0.7.3, QEMU and KVM only`
+
+The watchdog device requires an additional driver and management daemon in the
+guest. Just enabling the watchdog in the libvirt configuration does not do
+anything useful on its own.
+
+Currently libvirt does not support notification when the watchdog fires. This
+feature is planned for a future version of libvirt.
+
+::
+
+ ...
+ <devices>
+ <watchdog model='i6300esb'/>
+ </devices>
+ ...
+
+::
+
+ ...
+ <devices>
+ <watchdog model='i6300esb' action='poweroff'/>
+ </devices>
+ </domain>
+
+``model``
+ The required ``model`` attribute specifies what real watchdog device is
+ emulated. Valid values are specific to the underlying hypervisor.
+
+ QEMU and KVM support:
+
+ - 'i6300esb' - the recommended device, emulating a PCI Intel 6300ESB
+ - 'ib700' - emulating an ISA iBase IB700
+ - 'diag288' - emulating an S390 DIAG288 device :since:`Since 1.2.17`
+
+``action``
+ The optional ``action`` attribute describes what action to take when the
+ watchdog expires. Valid values are specific to the underlying hypervisor.
+
+ QEMU and KVM support:
+
+ - 'reset' - default, forcefully reset the guest
+ - 'shutdown' - gracefully shutdown the guest (not recommended)
+ - 'poweroff' - forcefully power off the guest
+ - 'pause' - pause the guest
+ - 'none' - do nothing
+ - 'dump' - automatically dump the guest :since:`Since 0.8.7`
+ - 'inject-nmi' - inject a non-maskable interrupt into the guest
+ :since:`Since 1.2.17`
+
+ Note 1: the 'shutdown' action requires that the guest is responsive to ACPI
+ signals. In the sort of situations where the watchdog has expired, guests are
+ usually unable to respond to ACPI signals. Therefore using 'shutdown' is not
+ recommended.
+
+ Note 2: the directory to save dump files can be configured by
+ ``auto_dump_path`` in file /etc/libvirt/qemu.conf.
+
+:anchor:`<a id="elementsMemBalloon"/>`
+
+Memory balloon device
+~~~~~~~~~~~~~~~~~~~~~
+
+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
+needs to be explicitly disabled, ``model='none'`` may be used.
+
+Example: automatically added device with KVM
+
+::
+
+ ...
+ <devices>
+ <memballoon model='virtio'/>
+ </devices>
+ ...
+
+Example: manually added device with static PCI slot 2 requested
+
+::
+
+ ...
+ <devices>
+ <memballoon model='virtio'>
+ <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x0'/>
+ <stats period='10'/>
+ <driver iommu='on' ats='on'/>
+ </memballoon>
+ </devices>
+ </domain>
+
+``model``
+ The required ``model`` attribute specifies what type of balloon device is
+ provided. Valid values are specific to the virtualization platform
+
+ - 'virtio' - default with QEMU/KVM
+ - 'virtio-transitional' :since:`Since 5.2.0`
+ - 'virtio-non-transitional' :since:`Since 5.2.0`
+ - 'xen' - default with Xen
+
+ See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more
+ details.
+
+``autodeflate``
+ The optional ``autodeflate`` attribute allows to enable/disable (values
+ "on"/"off", respectively) the ability of the QEMU virtio memory balloon to
+ release some memory at the last moment before a guest's process get killed by
+ Out of Memory killer. :since:`Since 1.3.1, QEMU and KVM only`
+
+``period``
+ The optional ``period`` allows the QEMU virtio memory balloon driver to
+ provide statistics through the ``virsh dommemstat [domain]``
+ command. By default, collection is not enabled. In order to enable, use the
+ ``virsh dommemstat [domain] --period [number]`` command or
+ ``virsh edit`` command to add the option to the XML definition. The
+ ``virsh dommemstat`` will accept the options ``--live``, ``--current``, or
+ ``--config``. If an option is not provided, the change for a running domain
+ will only be made to the active guest. If the QEMU driver is not at the right
+ revision, the attempt to set the period will fail. Large values (e.g. many
+ years) might be ignored. :since:`Since 1.1.1, requires QEMU 1.5`
+
+``driver``
+ For model ``virtio`` memballoon, `Virtio-specific
+ options <#elementsVirtio>`__ can also be set. ( :since:`Since 3.5.0` )
+
+:anchor:`<a id="elementsRng"/>`
+
+Random number generator device
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The virtual random number generator device allows the host to pass through
+entropy to guest operating systems. :since:`Since 1.0.3`
+
+Example: usage of the RNG device:
+
+::
+
+ ...
+ <devices>
+ <rng model='virtio'>
+ <rate period="2000" bytes="1234"/>
+ <backend model='random'>/dev/random</backend>
+ <!-- OR -->
+ <backend model='egd' type='udp'>
+ <source mode='bind' service='1234'/>
+ <source mode='connect' host='1.2.3.4' service='1234'/>
+ </backend>
+ <!-- OR -->
+ <backend model='builtin'/>
+ </rng>
+ </devices>
+ ...
+
+``model``
+ The required ``model`` attribute specifies what type of RNG device is
+ provided. Valid values are specific to the virtualization platform:
+
+ - 'virtio' - supported by qemu and virtio-rng kernel module
+ - 'virtio-transitional' :since:`Since 5.2.0`
+ - 'virtio-non-transitional' :since:`Since 5.2.0`
+
+ See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more
+ details.
+
+``rate``
+ The optional ``rate`` element allows limiting the rate at which entropy can
+ be consumed from the source. The mandatory attribute ``bytes`` specifies how
+ many bytes are permitted to be consumed per period. An optional ``period``
+ attribute specifies the duration of a period in milliseconds; if omitted, the
+ period is taken as 1000 milliseconds (1 second). :since:`Since 1.0.4`
+
+``backend``
+ The ``backend`` element specifies the source of entropy to be used for the
+ domain. The source model is configured using the ``model`` attribute.
+ Supported source models are:
+
+ ``random``
+ This backend type expects a non-blocking character device as input. The
+ file name is specified as contents of the ``backend`` element.
+ :since:`Since 1.3.4` any path is accepted. Before that ``/dev/random`` and
+ ``/dev/hwrng`` were the only accepted paths. When no file name is
+ specified, the hypervisor default is used. For QEMU, the default is
+ ``/dev/random``. However, the recommended source of entropy is
+ ``/dev/urandom`` (as it doesn't have the limitations of ``/dev/random``).
+
+ ``egd``
+ This backend connects to a source using the EGD protocol. The source is
+ specified as a character device. Refer to `character device host
+ interface <#elementsCharHostInterface>`__ for more information.
+
+ ``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` )
+
+``driver``
+ The subelement ``driver`` can be used to tune the device:
+
+ virtio options
+ `Virtio-specific options <#elementsVirtio>`__ can also be set. (
+ :since:`Since 3.5.0` )
+
+:anchor:`<a id="elementsTpm"/>`
+
+TPM device
+~~~~~~~~~~
+
+The TPM device enables a QEMU guest to have access to TPM functionality. The TPM
+device may either be a TPM 1.2 or a TPM 2.0.
+
+The TPM passthrough device type provides access to the host's TPM for one QEMU
+guest. No other software may be using the TPM device, typically /dev/tpm0, at
+the time the QEMU guest is started. :since:`'passthrough' since 1.0.5`
+
+Example: usage of the TPM passthrough device
+
+::
+
+ ...
+ <devices>
+ <tpm model='tpm-tis'>
+ <backend type='passthrough'>
+ <device path='/dev/tpm0'/>
+ </backend>
+ </tpm>
+ </devices>
+ ...
+
+The emulator device type gives access to a TPM emulator providing TPM
+functionality for each VM. QEMU talks to it over a Unix socket. With the
+emulator device type each guest gets its own private TPM. :since:`'emulator'
+since 4.5.0` The state of the TPM emulator can be encrypted by providing an
+``encryption`` element. :since:`'encryption' since 5.6.0`
+
+Example: usage of the TPM Emulator
+
+::
+
+ ...
+ <devices>
+ <tpm model='tpm-tis'>
+ <backend type='emulator' version='2.0'>
+ <encryption secret='6dd3e4a5-1d76-44ce-961f-f119f5aad935'/>
+ </backend>
+ </tpm>
+ </devices>
+ ...
+
+``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
+ 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
+ ``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
+ ``/dev/tpmrm0``, enabling the guest to run in secure virtual machine mode
+ with the help of an Ultravisor. Adding a TPM Proxy to a pSeries guest brings
+ no security benefits unless the guest is running on a PPC64 host that has an
+ Ultravisor and a TPM Resource Manager. Only one TPM Proxy device is allowed
+ per guest, but a TPM Proxy device can be added together with other TPM
+ devices.
+
+``backend``
+ The ``backend`` element specifies the type of TPM device. The following types
+ are supported:
+
+ ``passthrough``
+ Use the host's TPM or TPM Resource Manager device.
+
+ 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` ,
+ when choosing the ``spapr-tpm-proxy`` model, the file name specified is
+ expected to be a TPM Resource Manager device, e.g. ``/dev/tpmrm0``.
+
+ ``emulator``
+ For this backend type the 'swtpm' TPM Emulator must be installed on the
+ host. Libvirt will automatically start an independent TPM emulator for
+ each QEMU guest requesting access to it.
+
+``version``
+ The ``version`` attribute indicates the version of the TPM. By default a TPM
+ 1.2 is created. This attribute only works with the ``emulator`` backend. The
+ following versions are supported:
+
+ - '1.2' : creates a TPM 1.2
+ - '2.0' : creates a TPM 2.0
+
+``encryption``
+ The ``encryption`` element allows the state of a TPM emulator to be
+ encrypted. The ``secret`` must reference a secret object that holds the
+ passphrase from which the encryption key will be derived.
+
+:anchor:`<a id="elementsNVRAM"/>`
+
+NVRAM device
+~~~~~~~~~~~~
+
+nvram device is always added to pSeries guest on PPC64, and its address is
+allowed to be changed. Element ``nvram`` (only valid for pSeries guest,
+:since:`since 1.0.5` ) is provided to enable the address setting.
+
+Example: usage of NVRAM configuration
+
+::
+
+ ...
+ <devices>
+ <nvram>
+ <address type='spapr-vio' reg='0x00003000'/>
+ </nvram>
+ </devices>
+ ...
+
+``spapr-vio``
+ VIO device address type, only valid for PPC64.
+
+``reg``
+ Device address
+
+:anchor:`<a id="elementsPanic"/>`
+
+panic device
+~~~~~~~~~~~~
+
+panic device enables libvirt to receive panic notification from a QEMU guest.
+:since:`Since 1.2.1, QEMU and KVM only`
+
+This feature is always enabled for:
+
+- pSeries guests, since it's implemented by the guest firmware
+- S390 guests, since it's an integral part of the S390 architecture
+
+For the guest types listed above, libvirt automatically adds a ``panic`` element
+to the domain XML.
+
+Example: usage of panic configuration
+
+::
+
+ ...
+ <devices>
+ <panic model='hyperv'/>
+ <panic model='isa'>
+ <address type='isa' iobase='0x505'/>
+ </panic>
+ </devices>
+ ...
+
+``model``
+ The optional ``model`` attribute specifies what type of panic device is
+ provided. The panic model used when this attribute is missing depends on the
+ hypervisor and guest arch.
+
+ - '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`
+ - 's390' - default for S390 guests. :since:`Since 1.3.5`
+
+``address``
+ address of panic. The default ioport is 0x505. Most users don't need to
+ specify an address, and doing so is forbidden altogether for s390, pseries
+ and hyperv models.
+
+:anchor:`<a id="elementsShmem"/>`
+
+Shared memory device
+~~~~~~~~~~~~~~~~~~~~
+
+A shared memory device allows to share a memory region between different virtual
+machines and the host. :since:`Since 1.2.10, QEMU and KVM only`
+
+::
+
+ ...
+ <devices>
+ <shmem name='my_shmem0'>
+ <model type='ivshmem-plain'/>
+ <size unit='M'>4</size>
+ </shmem>
+ <shmem name='shmem_server'>
+ <model type='ivshmem-doorbell'/>
+ <size unit='M'>2</size>
+ <server path='/tmp/socket-shmem'/>
+ <msi vectors='32' ioeventfd='on'/>
+ </shmem>
+ </devices>
+ ...
+
+``shmem``
+ The ``shmem`` element has one mandatory attribute, ``name`` to identify the
+ shared memory. This attribute cannot be directory specific to ``.`` or ``..``
+ as well as it cannot involve path separator ``/``.
+``model``
+ Attribute ``type`` of the optional element ``model`` specifies the model of
+ the underlying device providing the ``shmem`` device. The models currently
+ supported are ``ivshmem`` (supports both server and server-less shmem, but is
+ deprecated by newer QEMU in favour of the -plain and -doorbell variants),
+ ``ivshmem-plain`` (only for server-less shmem) and ``ivshmem-doorbell`` (only
+ for shmem with the server).
+``size``
+ The optional ``size`` element specifies the size of the shared memory. This
+ must be power of 2 and greater than or equal to 1 MiB.
+``server``
+ The optional ``server`` element can be used to configure a server socket the
+ device is supposed to connect to. The optional ``path`` attribute specifies
+ the absolute path to the unix socket and defaults to
+ ``/var/lib/libvirt/shmem/$shmem-$name-sock``.
+``msi``
+ The optional ``msi`` element enables/disables (values "on"/"off",
+ respectively) MSI interrupts. This option can currently be used only together
+ with the ``server`` element. The ``vectors`` attribute can be used to specify
+ the number of interrupt vectors. The ``ioeventd`` attribute enables/disables
+ (values "on"/"off", respectively) ioeventfd.
+
+:anchor:`<a id="elementsMemory"/>`
+
+Memory devices
+~~~~~~~~~~~~~~
+
+In addition to the initial memory assigned to the guest, memory devices allow
+additional memory to be assigned to the guest in the form of memory modules. A
+memory device can be hot-plugged or hot-unplugged depending on the guests'
+memory resource needs. Some hypervisors may require NUMA configured for the
+guest.
+
+Example: usage of the memory devices
+
+::
+
+ ...
+ <devices>
+ <memory model='dimm' access='private' discard='yes'>
+ <target>
+ <size unit='KiB'>524287</size>
+ <node>0</node>
+ </target>
+ </memory>
+ <memory model='dimm'>
+ <source>
+ <pagesize unit='KiB'>4096</pagesize>
+ <nodemask>1-3</nodemask>
+ </source>
+ <target>
+ <size unit='KiB'>524287</size>
+ <node>1</node>
+ </target>
+ </memory>
+ <memory model='nvdimm'>
+ <uuid>
+ <source>
+ <path>/tmp/nvdimm</path>
+ </source>
+ <target>
+ <size unit='KiB'>524288</size>
+ <node>1</node>
+ <label>
+ <size unit='KiB'>128</size>
+ </label>
+ <readonly/>
+ </target>
+ </memory>
+ <memory model='nvdimm' access='shared'>
+ <uuid>
+ <source>
+ <path>/dev/dax0.0</path>
+ <alignsize unit='KiB'>2048</alignsize>
+ <pmem/>
+ </source>
+ <target>
+ <size unit='KiB'>524288</size>
+ <node>1</node>
+ <label>
+ <size unit='KiB'>128</size>
+ </label>
+ </target>
+ </memory>
+ </devices>
+ ...
+
+``model``
+ Provide ``dimm`` to add a virtual DIMM module to the guest. :since:`Since
+ 1.2.14` Provide ``nvdimm`` model adds a Non-Volatile DIMM module.
+ :since:`Since 3.2.0`
+
+``access``
+ An optional attribute ``access`` ( :since:`since 3.2.0` ) that provides
+ capability to fine tune mapping of the memory on per module basis. Values are
+ the same as `Memory Backing <#elementsMemoryBacking>`__: ``shared`` and
+ ``private``. For ``nvdimm`` model, if using real NVDIMM DAX device as
+ backend, ``shared`` is required.
+
+``discard``
+ An optional attribute ``discard`` ( :since:`since 4.4.0` ) that provides
+ capability to fine tune discard of data on per module basis. Accepted values
+ are ``yes`` and ``no``. The feature is described here: `Memory
+ Backing <#elementsMemoryBacking>`__. This attribute is allowed only for
+ ``model='dimm'``.
+
+``uuid``
+ For pSeries guests, an uuid can be set to identify the nvdimm module. If
+ absent, libvirt will generate an uuid. automatically. This attribute is
+ allowed only for ``model='nvdimm'`` for pSeries guests. :since:`Since 6.2.0`
+
+``source``
+ For model ``dimm`` this element is optional and allows to fine tune the
+ source of the memory used for the given memory device. If the element is not
+ provided defaults configured via ``numatune`` are used. If ``dimm`` is
+ provided, then the following optional elements can be provided as well:
+
+ ``pagesize``
+ This element can be used to override the default host page size used for
+ backing the memory device. The configured value must correspond to a page
+ size supported by the host.
+
+ ``nodemask``
+ This element can be used to override the default set of NUMA nodes where
+ the memory would be allocated.
+
+ For model ``nvdimm`` this element is mandatory. The mandatory child element
+ ``path`` represents a path in the host that backs the nvdimm module in the
+ guest. The following optional elements may be used:
+
+ ``alignsize``
+ The ``alignsize`` element defines the page size alignment used to mmap the
+ address range for the backend ``path``. If not supplied the host page size
+ is used. For example, to mmap a real NVDIMM device a 2M-aligned page may
+ be required, and host page size is 4KB, then we need to set this element
+ to 2MB. :since:`Since 5.0.0`
+
+ ``pmem``
+ If persistent memory is supported and enabled by the hypervisor in order
+ to guarantee the persistence of writes to the vNVDIMM backend, then use
+ the ``pmem`` element in order to utilize the feature. :since:`Since 5.0.0`
+
+``target``
+ The mandatory ``target`` element configures the placement and sizing of the
+ added memory from the perspective of the guest.
+
+ The mandatory ``size`` subelement configures the size of the added memory as
+ a scaled integer.
+
+ The ``node`` subelement configures the guest NUMA node to attach the memory
+ to. The element shall be used only if the guest has NUMA nodes configured.
+
+ The following optional elements may be used:
+
+ ``label``
+ For NVDIMM type devices one can use ``label`` and its subelement ``size``
+ to configure the size of namespaces label storage within the NVDIMM
+ module. The ``size`` element has usual meaning described
+ `here <#elementsMemoryAllocation>`__. ``label`` is mandatory for pSeries
+ guests and optional for all other architectures. For QEMU domains the
+ following restrictions apply:
+
+ #. the minimum label size is 128KiB,
+ #. the remaining size (total-size - label-size) will be aligned to 4KiB as
+ default.
+
+ ``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`
+
+:anchor:`<a id="elementsIommu"/>`
+
+IOMMU devices
+~~~~~~~~~~~~~
+
+The ``iommu`` element can be used to add an IOMMU device. :since:`Since 2.1.0`
+
+Example:
+
+::
+
+ ...
+ <devices>
+ <iommu model='intel'>
+ <driver intremap='on'/>
+ </iommu>
+ </devices>
+ ...
+
+``model``
+ Supported values are ``intel`` (for Q35 guests) and, :since:`since 5.5.0` ,
+ ``smmuv3`` (for ARM virt guests).
+
+``driver``
+ The ``driver`` subelement can be used to configure additional options, some
+ of which might only be available for certain IOMMU models:
+
+ ``intremap``
+ The ``intremap`` attribute with possible values ``on`` and ``off`` can be
+ used to turn on interrupt remapping, a part of the VT-d functionality.
+ Currently this requires split I/O APIC (``<ioapic driver='qemu'/>``).
+ :since:`Since 3.4.0` (QEMU/KVM only)
+
+ ``caching_mode``
+ The ``caching_mode`` attribute with possible values ``on`` and ``off`` can
+ be used to turn on the VT-d caching mode (useful for assigned devices).
+ :since:`Since 3.4.0` (QEMU/KVM only)
+
+ ``eim``
+ The ``eim`` attribute (with possible values ``on`` and ``off``) can be
+ used to configure Extended Interrupt Mode. A q35 domain with split I/O
+ APIC (as described in `hypervisor features <#elementsFeatures>`__), and
+ both interrupt remapping and EIM turned on for the IOMMU, will be able to
+ use more than 255 vCPUs. :since:`Since 3.4.0` (QEMU/KVM only)
+
+ ``iotlb``
+ The ``iotlb`` attribute with possible values ``on`` and ``off`` can be
+ used to turn on the IOTLB used to cache address translation requests from
+ devices. :since:`Since 3.5.0` (QEMU/KVM only)
+
+ ``aw_bits``
+ The ``aw_bits`` attribute can be used to set the address width to allow
+ mapping larger iova addresses in the guest. :since:`Since 6.5.0` (QEMU/KVM
+ only)
+
+:anchor:`<a id="vsock"/>`
+
+Vsock
+-----
+
+A vsock host/guest interface. The ``model`` attribute defaults to ``virtio``.
+:since:`Since 5.2.0` ``model`` can also be 'virtio-transitional' and
+'virtio-non-transitional', see `Virtio transitional
+devices <#elementsVirtioTransitional>`__ for more details. The optional
+attribute ``address`` of the ``cid`` element specifies the CID assigned to the
+guest. If the attribute ``auto`` is set to ``yes``, libvirt will assign a free
+CID automatically on domain startup. :since:`Since 4.4.0`
+
+::
+
+ ...
+ <devices>
+ <vsock model='virtio'>
+ <cid auto='no' address='3'/>
+ </vsock>
+ </devices>
+ ...
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index bb385e4b02..3af8e21d81 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -2170,5057 +2170,7 @@ event name Description
``emulation_faults`` the count of emulation faults, that is when the kernel traps on unimplemented instrucions and emulates them for user space, by applications running on the platform ``perf.emulation_faults``
=========================== ======================================================================================================================================================================================= ================================
-:anchor:`<a id="elementsDevices"/>`
-
-Devices
--------
-
-The final set of XML elements are all used to describe devices provided to the
-guest domain. All devices occur as children of the main ``devices`` element.
-:since:`Since 0.1.3`
-
-::
-
- ...
- <devices>
- <emulator>/usr/lib/xen/bin/qemu-dm</emulator>
- </devices>
- ...
-
-``emulator``
- The contents of the ``emulator`` element specify the fully qualified path to
- the device model emulator binary. The `capabilities XML <formatcaps.html>`__
- specifies the recommended default emulator to use for each particular domain
- type / architecture combination.
-
-To help users identifying devices they care about, every device can have direct
-child ``alias`` element which then has ``name`` attribute where users can store
-identifier for the device. The identifier has to have "ua-" prefix and must be
-unique within the domain. Additionally, the identifier must consist only of the
-following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
-
-::
-
- <devices>
- <disk type='file'>
- <alias name='ua-myDisk'/>
- </disk>
- <interface type='network' trustGuestRxFilters='yes'>
- <alias name='ua-myNIC'/>
- </interface>
- ...
- </devices>
-
-:anchor:`<a id="elementsDisks"/>`
-
-Hard drives, floppy disks, CDROMs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Any device that looks like a disk, be it a floppy, harddisk, cdrom, or
-paravirtualized driver is specified via the ``disk`` element.
-
-::
-
- ...
- <devices>
- <disk type='file' snapshot='external'>
- <driver name="tap" type="aio" cache="default"/>
- <source file='/var/lib/xen/images/fv0' startupPolicy='optional'>
- <seclabel relabel='no'/>
- </source>
- <target dev='hda' bus='ide'/>
- <iotune>
- <total_bytes_sec>10000000</total_bytes_sec>
- <read_iops_sec>400000</read_iops_sec>
- <write_iops_sec>100000</write_iops_sec>
- </iotune>
- <boot order='2'/>
- <encryption type='...'>
- ...
- </encryption>
- <shareable/>
- <serial>
- ...
- </serial>
- </disk>
- ...
- <disk type='network'>
- <driver name="qemu" type="raw" io="threads" ioeventfd="on" event_idx="off"/>
- <source protocol="sheepdog" name="image_name">
- <host name="hostname" port="7000"/>
- </source>
- <target dev="hdb" bus="ide"/>
- <boot order='1'/>
- <transient/>
- <address type='drive' controller='0' bus='1' unit='0'/>
- </disk>
- <disk type='network'>
- <driver name="qemu" type="raw"/>
- <source protocol="rbd" name="image_name2">
- <host name="hostname" port="7000"/>
- <snapshot name="snapname"/>
- <config file="/path/to/file"/>
- <auth username='myuser'>
- <secret type='ceph' usage='mypassid'/>
- </auth>
- </source>
- <target dev="hdc" bus="ide"/>
- </disk>
- <disk type='block' device='cdrom'>
- <driver name='qemu' type='raw'/>
- <target dev='hdd' bus='ide' tray='open'/>
- <readonly/>
- </disk>
- <disk type='network' device='cdrom'>
- <driver name='qemu' type='raw'/>
- <source protocol="http" name="url_path" query="foo=bar&baz=flurb>
- <host name="hostname" port="80"/>
- <cookies>
- <cookie name="test">somevalue</cookie>
- </cookies>
- <readahead size='65536'/>
- <timeout seconds='6'/>
- </source>
- <target dev='hde' bus='ide' tray='open'/>
- <readonly/>
- </disk>
- <disk type='network' device='cdrom'>
- <driver name='qemu' type='raw'/>
- <source protocol="https" name="url_path">
- <host name="hostname" port="443"/>
- <ssl verify="no"/>
- </source>
- <target dev='hdf' bus='ide' tray='open'/>
- <readonly/>
- </disk>
- <disk type='network' device='cdrom'>
- <driver name='qemu' type='raw'/>
- <source protocol="ftp" name="url_path">
- <host name="hostname" port="21"/>
- </source>
- <target dev='hdg' bus='ide' tray='open'/>
- <readonly/>
- </disk>
- <disk type='network' device='cdrom'>
- <driver name='qemu' type='raw'/>
- <source protocol="ftps" name="url_path">
- <host name="hostname" port="990"/>
- </source>
- <target dev='hdh' bus='ide' tray='open'/>
- <readonly/>
- </disk>
- <disk type='network' device='cdrom'>
- <driver name='qemu' type='raw'/>
- <source protocol="tftp" name="url_path">
- <host name="hostname" port="69"/>
- </source>
- <target dev='hdi' bus='ide' tray='open'/>
- <readonly/>
- </disk>
- <disk type='block' device='lun'>
- <driver name='qemu' type='raw'/>
- <source dev='/dev/sda'>
- <slices>
- <slice type='storage' offset='12345' size='123'/>
- </slices>
- <reservations managed='no'>
- <source type='unix' path='/path/to/qemu-pr-helper' mode='client'/>
- </reservations>
- </source>
- <target dev='sda' bus='scsi'/>
- <address type='drive' controller='0' bus='0' target='3' unit='0'/>
- </disk>
- <disk type='block' device='disk'>
- <driver name='qemu' type='raw'/>
- <source dev='/dev/sda'/>
- <geometry cyls='16383' heads='16' secs='63' trans='lba'/>
- <blockio logical_block_size='512' physical_block_size='4096'/>
- <target dev='hdj' bus='ide'/>
- </disk>
- <disk type='volume' device='disk'>
- <driver name='qemu' type='raw'/>
- <source pool='blk-pool0' volume='blk-pool0-vol0'/>
- <target dev='hdk' bus='ide'/>
- </disk>
- <disk type='network' device='disk'>
- <driver name='qemu' type='raw'/>
- <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/2'>
- <host name='example.com' port='3260'/>
- <auth username='myuser'>
- <secret type='iscsi' usage='libvirtiscsi'/>
- </auth>
- </source>
- <target dev='vda' bus='virtio'/>
- </disk>
- <disk type='network' device='lun'>
- <driver name='qemu' type='raw'/>
- <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/1'>
- <host name='example.com' port='3260'/>
- <auth username='myuser'>
- <secret type='iscsi' usage='libvirtiscsi'/>
- </auth>
- </source>
- <target dev='sdb' bus='scsi'/>
- </disk>
- <disk type='network' device='lun'>
- <driver name='qemu' type='raw'/>
- <source protocol='iscsi' name='iqn.2013-07.com.example:iscsi-nopool/0'>
- <host name='example.com' port='3260'/>
- <initiator>
- <iqn name='iqn.2013-07.com.example:client'/>
- </initiator>
- </source>
- <target dev='sdb' bus='scsi'/>
- </disk>
- <disk type='volume' device='disk'>
- <driver name='qemu' type='raw'/>
- <source pool='iscsi-pool' volume='unit:0:0:1' mode='host'/>
- <target dev='vdb' bus='virtio'/>
- </disk>
- <disk type='volume' device='disk'>
- <driver name='qemu' type='raw'/>
- <source pool='iscsi-pool' volume='unit:0:0:2' mode='direct'/>
- <target dev='vdc' bus='virtio'/>
- </disk>
- <disk type='file' device='disk'>
- <driver name='qemu' type='qcow2' queues='4'/>
- <source file='/var/lib/libvirt/images/domain.qcow'/>
- <backingStore type='file'>
- <format type='qcow2'/>
- <source file='/var/lib/libvirt/images/snapshot.qcow'/>
- <backingStore type='block'>
- <format type='raw'/>
- <source dev='/dev/mapper/base'/>
- <backingStore/>
- </backingStore>
- </backingStore>
- <target dev='vdd' bus='virtio'/>
- </disk>
- <disk type='nvme' device='disk'>
- <driver name='qemu' type='raw'/>
- <source type='pci' managed='yes' namespace='1'>
- <address domain='0x0000' bus='0x01' slot='0x00' function='0x0'/>
- </source>
- <target dev='vde' bus='virtio'/>
- </disk>
- </devices>
- ...
-
-``disk``
- The ``disk`` element is the main container for describing disks and supports
- the following attributes:
-
- ``type``
- Valid values are "file", "block", "dir" ( :since:`since 0.7.5` ),
- "network" ( :since:`since 0.8.7` ), or "volume" ( :since:`since 1.0.5` ),
- or "nvme" ( :since:`since 6.0.0` ) and refer to the underlying source for
- the disk. :since:`Since 0.0.3`
- ``device``
- Indicates how the disk is to be exposed to the guest OS. Possible values
- for this attribute are "floppy", "disk", "cdrom", and "lun", defaulting to
- "disk".
-
- Using "lun" ( :since:`since 0.9.10` ) is only valid when the ``type`` is
- "block" or "network" for ``protocol='iscsi'`` or when the ``type`` is
- "volume" when using an iSCSI source ``pool`` for ``mode`` "host" or as an
- `NPIV <http://wiki.libvirt.org/page/NPIV_in_libvirt>`__ virtual Host Bus
- Adapter (vHBA) using a Fibre Channel storage pool. Configured in this
- manner, the LUN behaves identically to "disk", except that generic SCSI
- commands from the guest are accepted and passed through to the physical
- device. Also note that device='lun' will only be recognized for actual raw
- devices, but never for individual partitions or LVM partitions (in those
- cases, the kernel will reject the generic SCSI commands, making it
- identical to device='disk'). :since:`Since 0.1.4`
-
- ``model``
- Indicates the emulated device model of the disk. Typically this is
- indicated solely by the ``bus`` property but for ``bus`` "virtio" the
- model can be specified further with "virtio-transitional",
- "virtio-non-transitional", or "virtio". See `Virtio transitional
- devices <#elementsVirtioTransitional>`__ for more details. :since:`Since
- 5.2.0`
- ``rawio``
- Indicates whether the disk needs rawio capability. Valid settings are
- "yes" or "no" (default is "no"). If any one disk in a domain has
- rawio='yes', rawio capability will be enabled for all disks in the domain
- (because, in the case of QEMU, this capability can only be set on a
- per-process basis). This attribute is only valid when device is "lun". NB,
- ``rawio`` intends to confine the capability per-device, however, current
- QEMU implementation gives the domain process broader capability than that
- (per-process basis, affects all the domain disks). To confine the
- capability as much as possible for QEMU driver as this stage, ``sgio`` is
- recommended, it's more secure than ``rawio``. :since:`Since 0.9.10`
- ``sgio``
- If supported by the hypervisor and OS, indicates whether unprivileged
- SG_IO commands are filtered for the disk. Valid settings are "filtered" or
- "unfiltered" where the default is "filtered". Only available when the
- ``device`` is 'lun'. :since:`Since 1.0.2`
- ``snapshot``
- Indicates the default behavior of the disk during disk snapshots:
- "``internal``" requires a file format such as qcow2 that can store both
- the snapshot and the data changes since the snapshot; "``external``" will
- separate the snapshot from the live data; and "``no``" means the disk will
- not participate in snapshots. Read-only disks default to "``no``", while
- the default for other disks depends on the hypervisor's capabilities. Some
- hypervisors allow a per-snapshot choice as well, during `domain snapshot
- creation <formatsnapshot.html>`__. Not all snapshot modes are supported;
- for example, enabling snapshots with a transient disk generally does not
- make sense. :since:`Since 0.9.5`
-
-``source``
- Representation of the disk ``source`` depends on the disk ``type`` attribute
- value as follows:
-
- ``file``
- The ``file`` attribute specifies the fully-qualified path to the file
- holding the disk. :since:`Since 0.0.3`
- ``block``
- The ``dev`` attribute specifies the fully-qualified path to the host
- device to serve as the disk. :since:`Since 0.0.3`
- ``dir``
- The ``dir`` attribute specifies the fully-qualified path to the directory
- to use as the disk. :since:`Since 0.7.5`
- ``network``
- The ``protocol`` attribute specifies the protocol to access to the
- requested image. Possible values are "nbd", "iscsi", "rbd", "sheepdog",
- "gluster", "vxhs", "http", "https", "ftp", ftps", or "tftp".
-
- For any ``protocol`` other than ``nbd`` an additional attribute ``name``
- is mandatory to specify which volume/image will be used.
-
- For "nbd", the ``name`` attribute is optional. TLS transport for NBD can
- be enabled by setting the ``tls`` attribute to ``yes``. For the QEMU
- hypervisor, usage of a TLS environment can also be globally controlled on
- the host by the ``nbd_tls`` and ``nbd_tls_x509_cert_dir`` in
- /etc/libvirt/qemu.conf. ('tls' :since:`Since 4.5.0` )
-
- For protocols ``http`` and ``https`` an optional attribute ``query``
- specifies the query string. ( :since:`Since 6.2.0` )
-
- For "iscsi" ( :since:`since 1.0.4` ), the ``name`` attribute may include a
- logical unit number, separated from the target's name by a slash (e.g.,
- ``iqn.2013-07.com.example:iscsi-pool/1``). If not specified, the default
- LUN is zero.
-
- For "vxhs" ( :since:`since 3.8.0` ), the ``name`` is the UUID of the
- volume, assigned by the HyperScale server. Additionally, an optional
- attribute ``tls`` (QEMU only) can be used to control whether a VxHS block
- device 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 also be globally controlled on the host by
- the ``vxhs_tls`` and ``vxhs_tls_x509_cert_dir`` or
- ``default_tls_x509_cert_dir`` settings in the file /etc/libvirt/qemu.conf.
- If ``vxhs_tls`` is enabled, then unless the domain ``tls`` attribute is
- set to "no", libvirt will use the host configured TLS environment. If the
- ``tls`` attribute is set to "yes", then regardless of the qemu.conf
- setting, TLS authentication will be attempted.
-
- :since:`Since 0.8.7`
-
- ``volume``
- The underlying disk source is represented by attributes ``pool`` and
- ``volume``. Attribute ``pool`` specifies the name of the `storage
- pool <formatstorage.html>`__ (managed by libvirt) where the disk source
- resides. Attribute ``volume`` specifies the name of storage volume
- (managed by libvirt) used as the disk source. The value for the ``volume``
- attribute will be the output from the "Name" column of a
- ``virsh vol-list [pool-name]`` command.
-
- Use the attribute ``mode`` ( :since:`since 1.1.1` ) to indicate how to
- represent the LUN as the disk source. Valid values are "direct" and
- "host". If ``mode`` is not specified, the default is to use "host". Using
- "direct" as the ``mode`` value indicates to use the `storage
- pool's <formatstorage.html>`__ ``source`` element ``host`` attribute as
- the disk source to generate the libiscsi URI (e.g.
- 'file=iscsi://example.com:3260/iqn.2013-07.com.example:iscsi-pool/1').
- Using "host" as the ``mode`` value indicates to use the LUN's path as it
- shows up on host (e.g.
- 'file=/dev/disk/by-path/ip-example.com:3260-iscsi-iqn.2013-07.com.example:iscsi-pool-lun-1').
- Using a LUN from an iSCSI source pool provides the same features as a
- ``disk`` configured using ``type`` 'block' or 'network' and ``device`` of
- 'lun' with respect to how the LUN is presented to and may be used by the
- guest. :since:`Since 1.0.5`
-
- ``nvme``
- To specify disk source for NVMe disk the ``source`` element has the
- following attributes:
-
- ``type``
- The type of address specified in ``address`` sub-element. Currently,
- only ``pci`` value is accepted.
- ``managed``
- This attribute instructs libvirt to detach NVMe controller
- automatically on domain startup (``yes``) or expect the controller to
- be detached by system administrator (``no``).
- ``namespace``
- The namespace ID which should be assigned to the domain. According to
- NVMe standard, namespace numbers start from 1, including.
-
- The difference between ``<disk type='nvme'>`` and ``<hostdev/>`` is that
- the latter is plain host device assignment with all its limitations (e.g.
- no live migration), while the former makes hypervisor to run the NVMe disk
- through hypervisor's block layer thus enabling all features provided by
- the layer (e.g. snapshots, domain migration, etc.). Moreover, since the
- NVMe disk is unbinded from its PCI driver, the host kernel storage stack
- is not involved (compared to passing say ``/dev/nvme0n1`` via
- ``<disk type='block'>`` and therefore lower latencies can be achieved.
-
- With "file", "block", and "volume", one or more optional sub-elements
- ``seclabel``, `described below <#seclabel>`__ (and :since:`since 0.9.9` ),
- can be used to override the domain security labeling policy for just that
- source file. (NB, for "volume" type disk, ``seclabel`` is only valid when the
- specified storage volume is of 'file' or 'block' type).
-
- The ``source`` element may also have the ``index`` attribute with same
- semantics the `index <#elementsDiskBackingStoreIndex>`__ attribute of
- ``backingStore``
-
- The ``source`` element may contain the following sub elements:
-
- ``host``
- When the disk ``type`` is "network", the ``source`` may have zero or more
- ``host`` sub-elements used to specify the hosts to connect. The ``host``
- element supports 4 attributes, viz. "name", "port", "transport" and
- "socket", which specify the hostname, the port number, transport type and
- path to socket, respectively. The meaning of this element and the number
- of the elements depend on the protocol attribute.
-
- ======== ======================================================= ============================================================ ================
- Protocol Meaning Number of hosts Default port
- ======== ======================================================= ============================================================ ================
- nbd a server running nbd-server only one 10809
- iscsi an iSCSI server only one 3260
- rbd monitor servers of RBD one or more librados default
- sheepdog one of the sheepdog servers (default is localhost:7000) zero or one 7000
- gluster a server running glusterd daemon one or more ( :since:`Since 2.1.0` ), just one prior to that 24007
- vxhs a server running Veritas HyperScale daemon only one 9999
- ======== ======================================================= ============================================================ ================
-
- gluster supports "tcp", "rdma", "unix" as valid values for the transport
- attribute. nbd supports "tcp" and "unix". Others only support "tcp". If
- nothing is specified, "tcp" is assumed. If the transport is "unix", the
- socket attribute specifies the path to an AF_UNIX socket.
-
- ``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).`
- ``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).`
- ``auth``
- :since:`Since libvirt 3.9.0` , the ``auth`` element is supported for a
- disk ``type`` "network" that is using a ``source`` element with the
- ``protocol`` attributes "rbd" or "iscsi". If present, the ``auth`` element
- provides the authentication credentials needed to access the source. It
- includes a mandatory attribute ``username``, which identifies the username
- to use during authentication, as well as a sub-element ``secret`` with
- mandatory attribute ``type``, to tie back to a `libvirt secret
- object <formatsecret.html>`__ that holds the actual password or other
- credentials (the domain XML intentionally does not expose the password,
- only the reference to the object that does manage the password). Known
- secret types are "ceph" for Ceph RBD network sources and "iscsi" for CHAP
- authentication of iSCSI targets. Both will require either a ``uuid``
- attribute with the UUID of the secret object or a ``usage`` attribute
- matching the key that was specified in the secret object.
- ``encryption``
- :since:`Since libvirt 3.9.0` , the ``encryption`` can be a sub-element of
- the ``source`` element for encrypted storage sources. If present,
- specifies how the storage source is encrypted See the `Storage
- Encryption <formatstorageencryption.html>`__ page for more information.
- Note that the 'qcow' format of encryption is broken and thus is no longer
- supported for use with disk images. ( :since:`Since libvirt 4.5.0` )
- ``reservations``
- :since:`Since libvirt 4.4.0` , the ``reservations`` can be a sub-element
- of the ``source`` element for storage sources (QEMU driver only). If
- present it enables persistent reservations for SCSI based disks. The
- element has one mandatory attribute ``managed`` with accepted values
- ``yes`` and ``no``. If ``managed`` is enabled libvirt prepares and manages
- any resources needed. When the persistent reservations are unmanaged, then
- the hypervisor acts as a client and the path to the server socket must be
- provided in the child element ``source``, which currently accepts only the
- following attributes: ``type`` with one value ``unix``, ``path`` path to
- the socket, and finally ``mode`` which accepts one value ``client``
- specifying the role of hypervisor. It's recommended to allow libvirt
- manage the persistent reservations.
- ``initiator``
- :since:`Since libvirt 4.7.0` , the ``initiator`` element is supported for
- a disk ``type`` "network" that is using a ``source`` element with the
- ``protocol`` attribute "iscsi". If present, the ``initiator`` element
- provides the initiator IQN needed to access the source via mandatory
- attribute ``name``.
- ``address``
- For disk of type ``nvme`` this element specifies the PCI address of the
- host NVMe controller. :since:`Since 6.0.0`
- ``slices``
- The ``slices`` element using its ``slice`` sub-elements allows configuring
- offset and size of either the location of the image format
- (``slice type='storage'``) inside the storage source or the guest data
- inside the image format container (future expansion). The ``offset`` and
- ``size`` values are in bytes. :since:`Since 6.1.0`
- ``ssl``
- For ``https`` and ``ftps`` accessed storage it's possible to tweak the SSL
- transport parameters with this element. The ``verify`` attribute allows to
- turn on or off SSL certificate validation. Supported values are ``yes``
- and ``no``. :since:`Since 6.2.0`
- ``cookies``
- For ``http`` and ``https`` accessed storage it's possible to pass one or
- more cookies. The cookie name and value must conform to the HTTP
- specification. :since:`Since 6.2.0`
- ``readahead``
- Specifies the size of the readahead buffer for protocols which support it.
- (all 'curl' based drivers in qemu). The size is in bytes. Note that '0' is
- considered as if the value is not provided. :since:`Since 6.2.0`
- ``timeout``
- Specifies the connection timeout for protocols which support it. Note that
- '0' is considered as if the value is not provided. :since:`Since 6.2.0`
-
- For a "file" or "volume" disk type which represents a cdrom or floppy (the
- ``device`` attribute), it is possible to define policy what to do with the
- disk if the source file is not accessible. (NB, ``startupPolicy`` is not
- valid for "volume" disk unless the specified storage volume is of "file"
- type). This is done by the ``startupPolicy`` attribute ( :since:`since 0.9.7`
- ), accepting these values:
-
- ========= =====================================================================
- mandatory fail if missing for any reason (the default)
- requisite fail if missing on boot up, drop if missing on migrate/restore/revert
- optional drop if missing at any start attempt
- ========= =====================================================================
-
- :since:`Since 1.1.2` the ``startupPolicy`` is extended to support hard disks
- besides cdrom and floppy. On guest cold bootup, if a certain disk is not
- accessible or its disk chain is broken, with startupPolicy 'optional' the
- guest will drop this disk. This feature doesn't support migration currently.
-
-``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
- does not support the
- `backingStoreInput <formatdomaincaps.html#featureBackingStoreInput>`__ (
- :since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored on
- input and only used for output to describe the detected backing chains of
- running domains. If ``backingStoreInput`` is supported the ``backingStore``
- is used as the backing image of ``source`` or other ``backingStore``
- overriding any backing image information recorded in the image metadata. An
- empty ``backingStore`` element means the sibling source is self-contained and
- is not based on any backing store. For the detected backing chain information
- to be accurate, the backing format must be correctly specified in the
- metadata of each file of the chain (files created by libvirt satisfy this
- property, but using existing external files for snapshot or block copy
- operations requires the end user to pre-create the file correctly). The
- following attributes are supported in ``backingStore``:
-
- ``type``
- The ``type`` attribute represents the type of disk used by the backing
- store, see disk type attribute above for more details and possible values.
- ``index``
- This attribute is only valid in output (and ignored on input) and it can
- be used to refer to a specific part of the disk chain when doing block
- operations (such as via the ``virDomainBlockRebase`` API). For example,
- ``vda[2]`` refers to the backing store with ``index='2'`` of the disk with
- ``vda`` target.
-
- Moreover, ``backingStore`` supports the following sub-elements:
-
- ``format``
- The ``format`` element contains ``type`` attribute which specifies the
- internal format of the backing store, such as ``raw`` or ``qcow2``.
- ``source``
- This element has the same structure as the ``source`` element in ``disk``.
- It specifies which file, device, or network location contains the data of
- the described backing store.
- ``backingStore``
- If the backing store is not self-contained, the next element in the chain
- is described by nested ``backingStore`` element.
-
-``mirror``
- This element is present if the hypervisor has started a long-running block
- job operation, where the mirror location in the ``source`` sub-element will
- eventually have the same contents as the source, and with the file format in
- the sub-element ``format`` (which might differ from the format of the
- source). The details of the ``source`` sub-element are determined by the
- ``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
- ``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``
- 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
- include redundant information in the attributes ``file`` and ``format`` in
- the ``mirror`` element.
-``target``
- The ``target`` element controls the bus / device under which the disk is
- exposed to the guest OS. The ``dev`` attribute indicates the "logical" device
- name. The actual device name specified is not guaranteed to map to the device
- 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
- 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.
- CDROM or Floppy disk), the value can be either "open" or "closed", defaults
- to "closed". NB, the value of ``tray`` could be updated while the domain is
- running. The optional attribute ``removable`` sets the removable flag for USB
- disks, and its value can be either "on" or "off", defaulting to "off".
- :since:`Since 0.0.3; ``bus`` attribute since 0.4.3; ``tray`` attribute since
- 0.9.11; "usb" attribute value since after 0.4.4; "sata" attribute value since
- 0.9.7; "removable" attribute value since 1.1.3`
-``iotune``
- The optional ``iotune`` element provides the ability to provide additional
- per-device I/O tuning, with values that can vary for each device (contrast
- this to the `<blkiotune> <#elementsBlockTuning>`__ element, 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`
-
- ``total_bytes_sec``
- The optional ``total_bytes_sec`` element is the total throughput limit in
- bytes per second. This cannot appear with ``read_bytes_sec`` or
- ``write_bytes_sec``.
- ``read_bytes_sec``
- The optional ``read_bytes_sec`` element is the read throughput limit in
- bytes per second.
- ``write_bytes_sec``
- The optional ``write_bytes_sec`` element is the write throughput limit in
- bytes per second.
- ``total_iops_sec``
- The optional ``total_iops_sec`` element is the total I/O operations per
- second. This cannot appear with ``read_iops_sec`` or ``write_iops_sec``.
- ``read_iops_sec``
- The optional ``read_iops_sec`` element is the read I/O operations per
- second.
- ``write_iops_sec``
- The optional ``write_iops_sec`` element is the write I/O operations per
- second.
- ``total_bytes_sec_max``
- The optional ``total_bytes_sec_max`` element is the maximum total
- throughput limit in bytes per second. This cannot appear with
- ``read_bytes_sec_max`` or ``write_bytes_sec_max``.
- ``read_bytes_sec_max``
- The optional ``read_bytes_sec_max`` element is the maximum read throughput
- limit in bytes per second.
- ``write_bytes_sec_max``
- The optional ``write_bytes_sec_max`` element is the maximum write
- throughput limit in bytes per second.
- ``total_iops_sec_max``
- The optional ``total_iops_sec_max`` element is the maximum total I/O
- operations per second. This cannot appear with ``read_iops_sec_max`` or
- ``write_iops_sec_max``.
- ``read_iops_sec_max``
- The optional ``read_iops_sec_max`` element is the maximum read I/O
- operations per second.
- ``write_iops_sec_max``
- The optional ``write_iops_sec_max`` element is the maximum write I/O
- operations per second.
- ``size_iops_sec``
- The optional ``size_iops_sec`` element is the size of I/O operations per
- second.
-
- :since:`Throughput limits since 1.2.11 and QEMU 1.7`
-
- ``group_name``
- The optional ``group_name`` provides the cability to share I/O throttling
- quota between multiple drives. This prevents end-users from circumventing
- a hosting provider's throttling policy by splitting 1 large drive in N
- small drives and getting N times the normal throttling quota. Any name may
- be used.
-
- :since:`group_name since 3.0.0 and QEMU 2.4`
-
- ``total_bytes_sec_max_length``
- The optional ``total_bytes_sec_max_length`` element is the maximum
- duration in seconds for the ``total_bytes_sec_max`` burst period. Only
- valid when the ``total_bytes_sec_max`` is set.
- ``read_bytes_sec_max_length``
- The optional ``read_bytes_sec_max_length`` element is the maximum duration
- in seconds for the ``read_bytes_sec_max`` burst period. Only valid when
- the ``read_bytes_sec_max`` is set.
- ``write_bytes_sec_max``
- The optional ``write_bytes_sec_max_length`` element is the maximum
- duration in seconds for the ``write_bytes_sec_max`` burst period. Only
- valid when the ``write_bytes_sec_max`` is set.
- ``total_iops_sec_max_length``
- The optional ``total_iops_sec_max_length`` element is the maximum duration
- in seconds for the ``total_iops_sec_max`` burst period. Only valid when
- the ``total_iops_sec_max`` is set.
- ``read_iops_sec_max_length``
- The optional ``read_iops_sec_max_length`` element is the maximum duration
- in seconds for the ``read_iops_sec_max`` burst period. Only valid when the
- ``read_iops_sec_max`` is set.
- ``write_iops_sec_max``
- The optional ``write_iops_sec_max_length`` element is the maximum duration
- in seconds for the ``write_iops_sec_max`` burst period. Only valid when
- the ``write_iops_sec_max`` is set.
-
- :since:`Throughput length since 2.4.0 and QEMU 2.6`
-
-``driver``
- The optional driver element allows specifying further details related to the
- hypervisor driver used to provide the disk. :since:`Since 0.1.8`
-
- - If the hypervisor supports multiple backend drivers, then the ``name``
- attribute selects the primary backend driver name, while the optional
- ``type`` attribute provides the sub-type. For example, xen supports a name
- of "tap", "tap2", "phy", or "file", with a type of "aio", while qemu only
- supports a name of "qemu", but multiple types including "raw", "bochs",
- "qcow2", and "qed".
- - The optional ``cache`` attribute controls the cache mechanism, possible
- values are "default", "none", "writethrough", "writeback", "directsync"
- (like "writethrough", but it bypasses the host page cache) and "unsafe"
- (host may cache all disk io, and sync requests from guest are ignored).
- :since:` Since 0.6.0, "directsync" since 0.9.5, "unsafe" since 0.9.7 `
- - The optional ``error_policy`` attribute controls how the hypervisor will
- behave on a disk read or write error, possible values are "stop",
- "report", "ignore", and "enospace". :since:`Since 0.8.0, "report" since
- 0.9.7` The default is left to the discretion of the hypervisor. There is
- also an optional ``rerror_policy`` that controls behavior for read errors
- only. :since:`Since 0.9.7` . If no rerror_policy is given, error_policy is
- used for both read and write errors. If rerror_policy is given, it
- overrides the ``error_policy`` for read errors. Also note that "enospace"
- is not a valid policy for read errors, so if ``error_policy`` is set to
- "enospace" and no ``rerror_policy`` is given, the read error policy will
- be left at its default.
- - 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)` .
- - 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.
- Accepted values are "on" and "off". Enabling this allows qemu to execute
- VM while a separate thread handles I/O. Typically guests experiencing high
- system CPU utilization during I/O will benefit from this. On the other
- hand, on overloaded host it could increase guest I/O latency.
- :since:`Since 0.9.3 (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 ``event_idx`` attribute controls some aspects of device event
- processing. The value can be either 'on' or 'off' - if it is on, it will
- 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,
- 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".
- Copy-on-read avoids accessing the same backing file sectors repeatedly and
- is useful when the backing file is over a slow network. By default
- copy-on-read is off. :since:`Since 0.9.10 (QEMU and KVM only)`
- - 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)`
- - 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")
- turns the detection on and additionally tries to discard such areas from
- the image based on the value of ``discard`` above (it will act as "on" if
- ``discard`` is set to "ignore"). NB enabling the detection is a compute
- intensive operation, but can save file space and/or time on slow media.
- :since:`Since 2.0.0`
- - The optional ``iothread`` attribute assigns the disk to an IOThread as
- defined by the range for the domain
- `iothreads <#elementsIOThreadsAllocation>`__ value. 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)`
- - The optional ``queues`` attribute specifies the number of virt queues for
- virtio-blk. ( :since:`Since 3.9.0` )
- - For virtio disks, `Virtio-specific options <#elementsVirtio>`__ can also
- be set. ( :since:`Since 3.5.0` )
-
-``backenddomain``
- The optional ``backenddomain`` element allows specifying a backend domain
- (aka driver domain) hosting the disk. Use the ``name`` attribute to specify
- the backend domain name. :since:`Since 1.2.13 (Xen only)`
-``boot``
- Specifies that the disk is bootable. The ``order`` attribute determines the
- order in which devices will be tried during boot sequence. On the S390
- architecture only the first boot device is used. The optional ``loadparm``
- attribute is an 8 character string which can be queried by guests on S390 via
- sclp or diag 308. Linux guests on S390 can use ``loadparm`` to select a boot
- entry. :since:`Since 3.5.0` The per-device ``boot`` elements cannot be used
- together with general boot elements in `BIOS bootloader <#elementsOSBIOS>`__
- section. :since:`Since 0.8.8`
-``encryption``
- Starting with :since:`libvirt 3.9.0` the ``encryption`` element is preferred
- to be a sub-element of the ``source`` element. If present, specifies how the
- volume is encrypted using "qcow". See the `Storage
- Encryption <formatstorageencryption.html>`__ page for more information.
-``readonly``
- If present, this indicates the device cannot be modified by the guest. For
- now, this is the default for disks with attribute ``device='cdrom'``.
-``shareable``
- If present, this indicates the device is expected to be shared between
- domains (assuming the hypervisor and OS support this), which means that
- caching should be deactivated for that device.
-``transient``
- If present, this indicates that changes to the device contents should be
- reverted automatically when the guest exits. With some hypervisors, marking a
- disk transient prevents the domain from participating in migration or
- snapshots. :since:`Since 0.9.5`
-``serial``
- If present, this specify serial number of virtual hard drive. For example, it
- may look like ``<serial>WD-WMAP9A966149</serial>``. Not supported for
- scsi-block devices, that is those using disk ``type`` 'block' using
- ``device`` 'lun' on ``bus`` 'scsi'. :since:`Since 0.7.1`
-``wwn``
- If present, this element specifies the WWN (World Wide Name) of a virtual
- hard disk or CD-ROM drive. It must be composed of 16 hexadecimal digits.
- :since:`Since 0.10.1`
-``vendor``
- If present, this element specifies the vendor of a virtual hard disk or
- CD-ROM device. It must not be longer than 8 printable characters.
- :since:`Since 1.0.1`
-``product``
- If present, this element specifies the product of a virtual hard disk or
- CD-ROM device. It must not be longer than 16 printable characters.
- :since:`Since 1.0.1`
-``address``
- If present, the ``address`` element ties the disk to a given slot of a
- controller (the actual ``<controller>`` device can often be inferred by
- libvirt, although it can be `explicitly specified <#elementsControllers>`__).
- The ``type`` attribute is mandatory, and is typically "pci" or "drive". For a
- "pci" controller, additional attributes for ``bus``, ``slot``, and
- ``function`` must be present, as well as optional ``domain`` and
- ``multifunction``. Multifunction defaults to 'off'; any other value requires
- QEMU 0.1.3 and :since:`libvirt 0.9.7` . For a "drive" controller, additional
- attributes ``controller``, ``bus``, ``target`` ( :since:`libvirt 0.9.11` ),
- and ``unit`` are available, each defaulting to 0.
-``auth``
- Starting with :since:`libvirt 3.9.0` the ``auth`` element is preferred to be
- a sub-element of the ``source`` element. The element is still read and
- managed as a ``disk`` sub-element. It is invalid to use ``auth`` as both a
- sub-element of ``disk`` and ``source``. The ``auth`` element was introduced
- as a ``disk`` sub-element in :since:`libvirt 0.9.7.`
-``geometry``
- The optional ``geometry`` element provides the ability to override geometry
- settings. This mostly useful for S390 DASD-disks or older DOS-disks.
- :since:`0.10.0`
-
- ``cyls``
- The ``cyls`` attribute is the number of cylinders.
- ``heads``
- The ``heads`` attribute is the number of heads.
- ``secs``
- The ``secs`` attribute is the number of sectors per track.
- ``trans``
- The optional ``trans`` attribute is the BIOS-Translation-Modus (none, lba
- or auto)
-
-``blockio``
- If present, the ``blockio`` element allows to override any of the block
- device properties listed below. :since:`Since 0.10.2 (QEMU and KVM)`
-
- ``logical_block_size``
- The logical block size the disk will report to the guest OS. For Linux
- this would be the value returned by the BLKSSZGET ioctl and describes the
- smallest units for disk I/O.
- ``physical_block_size``
- The physical block size the disk will report to the guest OS. For Linux
- this would be the value returned by the BLKPBSZGET ioctl and describes the
- disk's hardware sector size which can be relevant for the alignment of
- disk data.
-
-:anchor:`<a id="elementsFilesystems"/>`
-
-Filesystems
-~~~~~~~~~~~
-
-A directory on the host that can be accessed directly from the guest.
-:since:`since 0.3.3, since 0.8.5 for QEMU/KVM`
-
-::
-
- ...
- <devices>
- <filesystem type='template'>
- <source name='my-vm-template'/>
- <target dir='/'/>
- </filesystem>
- <filesystem type='mount' accessmode='passthrough' multidevs='remap'>
- <driver type='path' wrpolicy='immediate'/>
- <source dir='/export/to/guest'/>
- <target dir='/import/from/host'/>
- <readonly/>
- </filesystem>
- <filesystem type='file' accessmode='passthrough'>
- <driver type='loop' format='raw'/>
- <driver type='path' wrpolicy='immediate'/>
- <source file='/export/to/guest.img'/>
- <target dir='/import/from/host'/>
- <readonly/>
- </filesystem>
- <filesystem type='mount' accessmode='passthrough'>
- <driver type='virtiofs' queue='1024'/>
- <binary path='/usr/libexec/virtiofsd' xattr='on'>
- <cache mode='always'/>
- <lock posix='on' flock='on'/>
- </binary>
- <source dir='/path'/>
- <target dir='mount_tag'/>
- </filesystem>
- ...
- </devices>
- ...
-
-``filesystem``
- The filesystem attribute ``type`` specifies the type of the ``source``. The
- 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``
- 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
- ``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
- virtiofs requires setting up shared memory, see the guide:
- `Virtio-FS <kbase/virtiofs.html>`__
- ``template``
- OpenVZ filesystem template. Only used by OpenVZ driver.
- ``file``
- A host file will be treated as an image and mounted in the guest. The
- 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)` .
- ``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
- KiB, unless units are specified by the ``units`` attribute. Only used by
- LXC driver. :since:` (since 0.9.13)`
- ``bind``
- A directory inside the guest will be bound to another directory inside the
- 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)` .
- 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:
-
- ``passthrough``
- The ``source`` is accessed with the permissions of the user inside the
- guest. This is the default ``accessmode`` if one is not specified. `More
- info <http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html>`__
- ``mapped``
- The ``source`` is accessed with the permissions of the hypervisor (QEMU
- process). `More
- info <http://lists.gnu.org/archive/html/qemu-devel/2010-05/msg02673.html>`__
- ``squash``
- Similar to 'passthrough', the exception is that failure of privileged
- operations like 'chown' are ignored. This makes a passthrough-like mode
- usable for people who run the hypervisor as non-root. `More
- info <http://lists.gnu.org/archive/html/qemu-devel/2010-09/msg00121.html>`__
-
- :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 <#elementsVirtioTransitional>`__ for more details.
-
- The filesystem element has an optional attribute ``multidevs`` which
- specifies how to deal with a filesystem export containing more than one
- device, in order to avoid file ID collisions on guest when using 9pfs (
- :since:`since 6.3.0, requires QEMU 4.2` ). This attribute is not available
- for virtiofs. The possible values are:
-
- ``default``
- Use QEMU's default setting (which currently is ``warn``).
- ``remap``
- This setting allows guest to access multiple devices per export without
- encountering misbehaviours. Inode numbers from host are automatically
- remapped on guest to actively prevent file ID collisions if guest accesses
- one export containing multiple devices.
- ``forbid``
- Only allow to access one device per export by guest. Attempts to access
- additional devices on the same export will cause the individual filesystem
- access by guest to fail with an error and being logged (once) as error on
- host side.
- ``warn``
- This setting resembles the behaviour of 9pfs prior to QEMU 4.2, that is no
- action is performed to prevent any potential file ID collisions if an
- export contains multiple devices, with the only exception: a warning is
- logged (once) on host side now. This setting may lead to misbehaviours on
- guest side if more than one device is exported per export, due to the
- potential file ID collisions this may cause on guest side in that case.
-
-``driver``
- The optional driver element allows specifying further details related to the
- hypervisor driver used to provide the filesystem. :since:`Since 1.0.6`
-
- - If the hypervisor supports multiple backend drivers, then the ``type``
- attribute selects the primary backend driver name, while the ``format``
- attribute provides the format type. For example, LXC supports a type of
- "loop", with a format of "raw" or "nbd" with any format. QEMU supports a
- type of "path" or "handle", but no formats. Virtuozzo driver supports a
- type of "ploop" with a format of "ploop".
- - For virtio-backed devices, `Virtio-specific options <#elementsVirtio>`__
- can also be set. ( :since:`Since 3.5.0` )
- - For ``virtiofs``, the ``queue`` attribute can be used to specify the queue
- size (i.e. how many requests can the queue fit). ( :since:`Since 6.2.0` )
-
-``binary``
- The optional ``binary`` element can tune the options for virtiofsd. All of
- the following attributes and elements are optional. The attribute ``path``
- can be used to override the path to the daemon. Attribute ``xattr`` enables
- the use of filesystem extended attributes. Caching can be tuned via the
- ``cache`` element, possible ``mode`` values being ``none`` and ``always``.
- Locking can be controlled via the ``lock`` element - attributes ``posix`` and
- ``flock`` both accepting values ``on`` or ``off``. ( :since:`Since 6.2.0` )
-``source``
- The resource on the host that is being accessed in the guest. The ``name``
- attribute must be used with ``type='template'``, and the ``dir`` attribute
- must be used with ``type='mount'``. The ``usage`` attribute is used with
- ``type='ram'`` to set the memory limit in KiB, unless units are specified by
- the ``units`` attribute.
-``target``
- Where the ``source`` can be accessed in the guest. For most drivers this is
- an automatic mount point, but for QEMU/KVM this is merely an arbitrary string
- tag that is exported to the guest as a hint for where to mount.
-``readonly``
- Enables exporting filesystem as a readonly mount for guest, by default
- read-write access is given (currently only works for QEMU/KVM driver).
-``space_hard_limit``
- Maximum space available to this guest's filesystem. :since:`Since 0.9.13`
-``space_soft_limit``
- Maximum space available to this guest's filesystem. The container is
- permitted to exceed its soft limits for a grace period of time. Afterwards
- the hard limit is enforced. :since:`Since 0.9.13`
-
-:anchor:`<a id="elementsAddress"/>`
-
-Device Addresses
-~~~~~~~~~~~~~~~~
-
-Many devices have an optional ``<address>`` sub-element to describe where the
-device is placed on the virtual bus presented to the guest. If an address (or
-any optional attribute within an address) is omitted on input, libvirt will
-generate an appropriate address; but an explicit address is required if more
-control over layout is required. See below for device examples including an
-address element.
-
-Every address has a mandatory attribute ``type`` that describes which bus the
-device is on. The choice of which address to use for a given device is
-constrained in part by the device and the architecture of the guest. For
-example, a ``<disk>`` device uses ``type='drive'``, while a ``<console>`` device
-would use ``type='pci'`` on i686 or x86_64 guests, or ``type='spapr-vio'`` on
-PowerPC64 pseries guests. Each address type has further optional attributes that
-control where on the bus the device will be placed:
-
-``pci``
- PCI addresses have the following additional attributes: ``domain`` (a 2-byte
- hex integer, not currently used by qemu), ``bus`` (a hex value between 0 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
- ``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
- 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
- have a ``zpci`` child element, with two attributes: ``uid`` (a hex value
- 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
- ``<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).
- The relationship between the PCI addresses configured in the domain XML and
- those seen by the guest OS can sometime seem confusing: a separate document
- describes `how PCI addresses work <pci-addresses.html>`__ in more detail.
-``drive``
- Drive addresses have the following additional attributes: ``controller`` (a
- 2-digit controller number), ``bus`` (a 2-digit bus number), ``target`` (a
- 2-digit target number), and ``unit`` (a 2-digit unit number on the bus).
-``virtio-serial``
- Each virtio-serial address has the following additional attributes:
- ``controller`` (a 2-digit controller number), ``bus`` (a 2-digit bus number),
- and ``slot`` (a 2-digit slot within the bus).
-``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.`
-``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
- four octets, such as 1.2 or 2.1.3.1).
-``spapr-vio``
- On PowerPC pseries guests, devices can be assigned to the SPAPR-VIO bus. It
- has a flat 32-bit address space; by convention, devices are generally
- 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.`
-``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
- attributes: ``cssid`` (a hex value between 0 and 0xfe, inclusive), ``ssid``
- (a value between 0 and 3, inclusive) and ``devno`` (a hex value between 0 and
- 0xffff, inclusive). Partially specified bus addresses are not allowed. If
- omitted, libvirt will assign a free bus address with cssid=0xfe and ssid=0.
- Virtio-ccw devices must have their cssid set to 0xfe. :since:`Since 1.0.4`
-``virtio-mmio``
- This places the device on the virtio-mmio transport, which is currently only
- available for some ``armv7l`` and ``aarch64`` virtual machines. virtio-mmio
- addresses do not have any additional attributes. :since:`Since 1.1.3`
- If the guest architecture is ``aarch64`` and the machine type is ``virt``,
- libvirt will automatically assign PCI addresses to devices; however, the
- presence of a single device with virtio-mmio address in the guest
- configuration will cause libvirt to assign virtio-mmio addresses to all
- further devices. :since:`Since 3.0.0`
-``isa``
- ISA addresses have the following additional attributes: ``iobase`` and
- ``irq``. :since:`Since 1.2.1`
-``unassigned``
- For PCI hostdevs, ``<address type='unassigned'/>`` allows the admin to
- include a PCI hostdev in the domain XML definition, without making it
- available for the guest. This allows for configurations in which Libvirt
- manages the device as a regular PCI hostdev, regardless of whether the guest
- will have access to it. ``<address type='unassigned'/>`` is an invalid
- address type for all other device types. :since:`Since 6.0.0`
-
-:anchor:`<a id="elementsVirtio"/>`
-
-Virtio-related options
-~~~~~~~~~~~~~~~~~~~~~~
-
-QEMU's virtio devices have some attributes related to the virtio transport under
-the ``driver`` element: The ``iommu`` attribute enables the use of emulated
-IOMMU by the device. The attribute ``ats`` controls the Address Translation
-Service support for PCIe devices. This is needed to make use of IOTLB support
-(see `IOMMU device <#elementsIommu>`__). Possible values are ``on`` or ``off``.
-:since:`Since 3.5.0`
-
-The attribute ``packed`` controls if QEMU should try to use packed virtqueues.
-Compared to regular split queues, packed queues consist of only a single
-descriptor ring replacing available and used ring, index and descriptor buffer.
-This can result in better cache utilization and performance. If packed
-virtqueues are actually used depends on the feature negotiation between QEMU,
-vhost backends and guest drivers. Possible values are ``on`` or ``off``.
-:since:`Since 6.3.0 (QEMU and KVM only)`
-
-:anchor:`<a id="elementsVirtioTransitional"/>`
-
-Virtio transitional devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-: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``
- This device can work both with virtio 0.9 and virtio 1.0 guest drivers, so
- it's the best choice when compatibility with older guest operating systems is
- desired. libvirt will plug the device into a conventional PCI slot.
-``virtio-non-transitional``
- This device can only work with virtio 1.0 guest drivers, and it's the
- recommended option unless compatibility with older guest operating systems is
- necessary. libvirt will plug the device into either a PCI Express slot or a
- conventional PCI slot based on the machine type, resulting in a more
- optimized PCI topology.
-``virtio``
- This device will work like a ``virtio-non-transitional`` device when plugged
- into a PCI Express slot, and like a ``virtio-transitional`` device otherwise;
- libvirt will pick one or the other based on the machine type. This is the
- best choice when compatibility with libvirt versions older than 5.2.0 is
- necessary, but it's otherwise not recommended to use it.
-
-While the information outlined above applies to most virtio devices, there are a
-few exceptions:
-
-- for SCSI controllers, ``virtio-scsi`` must be used instead of ``virtio`` for
- backwards compatibility reasons;
-- some devices, such as GPUs and input devices (keyboard, tablet and mouse),
- are only defined in the virtio 1.0 spec and as such don't have a transitional
- variant: the only accepted model is ``virtio``, which will result in a
- non-transitional device.
-
-For more details see the `qemu patch
-posting <https://lists.gnu.org/archive/html/qemu-devel/2018-12/msg00923.html>`__
-and the `virtio-1.0
-spec <http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.html>`__.
-
-:anchor:`<a id="elementsControllers"/>`
-
-Controllers
-~~~~~~~~~~~
-
-Depending on the guest architecture, some device buses can appear more than
-once, with a group of virtual devices tied to a virtual controller. Normally,
-libvirt can automatically infer such controllers without requiring explicit XML
-markup, but sometimes it is necessary to provide an explicit controller element,
-notably when planning the `PCI topology <pci-hotplug.html>`__ for guests where
-device hotplug is expected.
-
-::
-
- ...
- <devices>
- <controller type='ide' index='0'/>
- <controller type='virtio-serial' index='0' ports='16' vectors='4'/>
- <controller type='virtio-serial' index='1'>
- <address type='pci' domain='0x0000' bus='0x00' slot='0x0a' function='0x0'/>
- </controller>
- <controller type='scsi' index='0' model='virtio-scsi'>
- <driver iothread='4'/>
- <address type='pci' domain='0x0000' bus='0x00' slot='0x0b' function='0x0'/>
- </controller>
- <controller type='xenbus' maxGrantFrames='64' maxEventChannels='2047'/>
- ...
- </devices>
- ...
-
-Each controller has a mandatory attribute ``type``, which must be one of 'ide',
-'fdc', 'scsi', 'sata', 'usb', 'ccid', 'virtio-serial' or 'pci', and a mandatory
-attribute ``index`` which is the decimal integer describing in which order the
-bus controller is encountered (for use in ``controller`` attributes of
-``<address>`` elements). :since:`Since 1.3.5` the index is optional; if not
-specified, it will be auto-assigned to be the lowest unused index for the given
-controller type. Some controller types have additional attributes that control
-specific features, such as:
-
-``virtio-serial``
- The ``virtio-serial`` controller has two additional optional attributes
- ``ports`` and ``vectors``, which control how many devices can be connected
- through the controller. :since:`Since 5.2.0` , it supports an optional
- attribute ``model`` which can be 'virtio', 'virtio-transitional', or
- 'virtio-non-transitional'. See `Virtio transitional
- devices <#elementsVirtioTransitional>`__ for more details.
-``scsi``
- A ``scsi`` controller has an optional attribute ``model``, which is one of
- 'auto', 'buslogic', 'ibmvscsi', 'lsilogic', 'lsisas1068', 'lsisas1078',
- 'virtio-scsi', 'vmpvscsi', 'virtio-transitional', 'virtio-non-transitional'.
- See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more
- details.
-``usb``
- A ``usb`` controller has an optional attribute ``model``, which is one of
- "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
- 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
- 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
- ``maxGrantFrames``, which specifies the maximum number of grant frames 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.
-
-Note: The PowerPC64 "spapr-vio" addresses do not have an associated controller.
-
-For controllers that are themselves devices on a PCI or USB bus, an optional
-sub-element ``<address>`` can specify the exact relationship of the controller
-to its master bus, with semantics `given above <#elementsAddress>`__.
-
-An optional sub-element ``driver`` can specify the driver specific options:
-
-``queues``
- The optional ``queues`` attribute specifies the number of queues for the
- controller. For best performance, it's recommended to specify a value
- 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)`
-``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.
- The transfer length is measured in sectors, where a sector is 512 bytes.
- :since:`Since 1.2.7 (QEMU and KVM only)`
-``ioeventfd``
- The optional ``ioeventfd`` attribute specifies whether the controller should
- use `I/O asynchronous handling <https://patchwork.kernel.org/patch/43390/>`__
- 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
- optional ``iothread`` attribute assigns the controller to an IOThread as
- defined by the range for the domain
- `iothreads <#elementsIOThreadsAllocation>`__ value. Each SCSI ``disk``
- assigned to use the specified ``controller`` will utilize the same IOThread.
- If a specific IOThread is desired for a specific SCSI ``disk``, then multiple
- controllers must be defined each having a specific ``iothread`` value. The
- ``iothread`` value must be within the range 1 to the domain iothreads value.
-virtio options
- For virtio controllers, `Virtio-specific options <#elementsVirtio>`__ can
- also be set. ( :since:`Since 3.5.0` )
-
-USB companion controllers have an optional sub-element ``<master>`` to specify
-the exact relationship of the companion to its master controller. A companion
-controller is on the same bus as its master, so the companion ``index`` value
-should be equal. Not all controller models can be used as companion controllers
-and libvirt might provide some sensible defaults (settings of
-``master startport`` and ``function`` of an address) for some particular models.
-Preferred companion controllers are ``ich-uhci[123]``.
-
-::
-
- ...
- <devices>
- <controller type='usb' index='0' model='ich9-ehci1'>
- <address type='pci' domain='0' bus='0' slot='4' function='7'/>
- </controller>
- <controller type='usb' index='0' model='ich9-uhci1'>
- <master startport='0'/>
- <address type='pci' domain='0' bus='0' slot='4' function='0' multifunction='on'/>
- </controller>
- ...
- </devices>
- ...
-
-PCI controllers have an optional ``model`` attribute; possible values for this
-attribute are
-
-- ``pci-root``, ``pci-bridge`` ( :since:`since 1.0.5` )
-- ``pcie-root``, ``dmi-to-pci-bridge`` ( :since:`since 1.1.2` )
-- ``pcie-root-port``, ``pcie-switch-upstream-port``,
- ``pcie-switch-downstream-port`` ( :since:`since 1.2.19` )
-- ``pci-expander-bus``, ``pcie-expander-bus`` ( :since:`since 1.3.4` )
-- ``pcie-to-pci-bridge`` ( :since:`since 4.3.0` )
-
-The root controllers (``pci-root`` and ``pcie-root``) have an optional
-``pcihole64`` element specifying how big (in kilobytes, or in the unit specified
-by ``pcihole64``'s ``unit`` attribute) the 64-bit PCI hole should be. Some
-guests (like Windows XP or Windows Server 2003) might crash when QEMU and
-Seabios are recent enough to support 64-bit PCI holes, unless this is disabled
-(set to 0). :since:`Since 1.1.2 (QEMU only)`
-
-PCI controllers also have an optional subelement ``<model>`` with an attribute
-``name``. The name attribute holds the name of the specific device that qemu is
-emulating (e.g. "i82801b11-bridge") rather than simply the class of device
-("pcie-to-pci-bridge", "pci-bridge"), which is set in the controller element's
-model **attribute**. In almost all cases, you should not manually add a
-``<model>`` subelement to a controller, nor should you modify one that is
-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)
-are visible to the guest OS so must be preserved for guest ABI compatibility,
-and 2) are usually left to default values or derived automatically by libvirt.
-In almost all cases, you should not manually add a ``<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).`
-
-``chassisNr``
- PCI controllers that have attribute model="pci-bridge", can also have a
- ``chassisNr`` attribute in the ``<target>`` subelement, which is used to
- control QEMU's "chassis_nr" option for the pci-bridge device (normally
- libvirt automatically sets this to the same value as the index attribute of
- the pci controller). If set, chassisNr must be between 1 and 255.
-``chassis``
- pcie-root-port and pcie-switch-downstream-port controllers can also have a
- ``chassis`` attribute in the ``<target>`` subelement, which is used to set
- the controller's "chassis" configuration value, which is visible to the
- virtual machine. If set, chassis must be between 0 and 255.
-``port``
- pcie-root-port and pcie-switch-downstream-port controllers can also have a
- ``port`` attribute in the ``<target>`` subelement, which is used to set the
- controller's "port" configuration value, which is visible to the virtual
- machine. If set, port must be between 0 and 255.
-``hotplug``
- pcie-root-port and pcie-switch-downstream-port controllers can also have a
- ``hotplug`` attribute in the ``<target>`` subelement, which is used to
- disable hotplug/unplug of devices on a particular controller. The default
- setting of ``hotplug`` is ``on``; it should be set to ``off`` to disable
- hotplug/unplug of devices on a particular controller. :since:`Since 6.3.0`
-``busNr``
- pci-expander-bus and pcie-expander-bus controllers can have an optional
- ``busNr`` attribute (1-254). This will be the bus number of the new bus; All
- bus numbers between that specified and 255 will be available only for
- assignment to PCI/PCIe controllers plugged into the hierarchy starting with
- this expander bus, and bus numbers less than the specified value will be
- available to the next lower expander-bus (or the root-bus if there are no
- lower expander buses). If you do not specify a busNumber, libvirt will find
- the lowest existing busNumber in all other expander buses (or use 256 if
- there are no others) and auto-assign the busNr of that found bus - 2, which
- provides one bus number for the pci-expander-bus and one for the pci-bridge
- that is automatically attached to it (if you plan on adding more pci-bridges
- to the hierarchy of the bus, you should manually set busNr to a lower value).
-
- A similar algorithm is used for automatically determining the busNr attribute
- for pcie-expander-bus, but since the pcie-expander-bus doesn't have any
- built-in pci-bridge, the 2nd bus-number is just being reserved for the
- pcie-root-port that must necessarily be connected to the bus in order to
- actually plug in an endpoint device. If you intend to plug multiple devices
- into a pcie-expander-bus, you must connect a pcie-switch-upstream-port to the
- pcie-root-port that is plugged into the pcie-expander-bus, and multiple
- pcie-switch-downstream-ports to the pcie-switch-upstream-port, and of course
- for this to work properly, you will need to decrease the pcie-expander-bus'
- busNr accordingly so that there are enough unused bus numbers above it to
- accommodate giving out one bus number for the upstream-port and one for each
- downstream-port (in addition to the pcie-root-port and the pcie-expander-bus
- itself).
-
-``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` ,
- ``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
- all devices on that bus are a part of the specified NUMA node (it is up to
- the user of the libvirt API to attach host devices to the correct
- pci-expander-bus when assigning them to the domain).
-``index``
- pci-root controllers for pSeries guests use this attribute to record the
- order they will show up in the guest. :since:`Since 3.6.0`
-
-For machine types which provide an implicit PCI bus, the pci-root controller
-with index=0 is auto-added and required to use PCI devices. pci-root has no
-address. PCI bridges are auto-added if there are too many devices to fit on the
-one bus provided by pci-root, or a PCI bus number greater than zero was
-specified. PCI bridges can also be specified manually, but their addresses
-should only refer to PCI buses provided by already specified PCI controllers.
-Leaving gaps in the PCI controller indexes might lead to an invalid
-configuration.
-
-::
-
- ...
- <devices>
- <controller type='pci' index='0' model='pci-root'/>
- <controller type='pci' index='1' model='pci-bridge'>
- <address type='pci' domain='0' bus='0' slot='5' function='0' multifunction='off'/>
- </controller>
- </devices>
- ...
-
-For machine types which provide an implicit PCI Express (PCIe) bus (for example,
-the machine types based on the Q35 chipset), the pcie-root controller with
-index=0 is auto-added to the domain's configuration. pcie-root has also no
-address, provides 31 slots (numbered 1-31) that can be used to attach PCIe or
-PCI devices (although libvirt will never auto-assign a PCI device to a PCIe
-slot, it will allow manual specification of such an assignment). Devices
-connected to pcie-root cannot be hotplugged. If traditional PCI devices are
-present in the guest configuration, a ``pcie-to-pci-bridge`` controller will
-automatically be added: this controller, which plugs into a ``pcie-root-port``,
-provides 31 usable PCI slots (1-31) with hotplug support ( :since:`since 4.3.0`
-). If the QEMU binary doesn't support the corresponding device, then a
-``dmi-to-pci-bridge`` controller will be added instead, usually at the defacto
-standard location of slot=0x1e. A dmi-to-pci-bridge controller plugs into a PCIe
-slot (as provided by pcie-root), and itself provides 31 standard PCI slots
-(which also do not support device hotplug). In order to have hot-pluggable PCI
-slots in the guest system, a pci-bridge controller will also be automatically
-created and connected to one of the slots of the auto-created dmi-to-pci-bridge
-controller; all guest PCI devices with addresses that are auto-determined by
-libvirt will be placed on this pci-bridge device. ( :since:`since 1.1.2` ).
-
-Domains with an implicit pcie-root can also add controllers with
-``model='pcie-root-port'``, ``model='pcie-switch-upstream-port'``, and
-``model='pcie-switch-downstream-port'``. pcie-root-port is a simple type of
-bridge device that can connect only to one of the 31 slots on the pcie-root bus
-on its upstream side, and makes a single (PCIe, hotpluggable) port available on
-the downstream side (at slot='0'). pcie-root-port can be used to provide a
-single slot to later hotplug a PCIe device (but is not itself hotpluggable - it
-must be in the configuration when the domain is started). ( :since:`since
-1.2.19` )
-
-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
-upstream side (and only before the domain is started - it is not hot-pluggable),
-and provides 32 ports on the downstream side (slot='0' - slot='31') that accept
-only pcie-switch-downstream-port devices; each pcie-switch-downstream-port
-device can only plug into a pcie-switch-upstream-port on its upstream side
-(again, not hot-pluggable), and on its downstream side provides a single
-hotpluggable pcie port that can accept any standard pci or pcie device (or
-another pcie-switch-upstream-port), i.e. identical in function to a
-pcie-root-port. ( :since:`since 1.2.19` )
-
-::
-
- ...
- <devices>
- <controller type='pci' index='0' model='pcie-root'/>
- <controller type='pci' index='1' model='pcie-root-port'>
- <address type='pci' domain='0x0000' bus='0x00' slot='0x01' function='0x0'/>
- </controller>
- <controller type='pci' index='2' model='pcie-to-pci-bridge'>
- <address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/>
- </controller>
- </devices>
- ...
-
-:anchor:`<a id="elementsLease"/>`
-
-Device leases
-~~~~~~~~~~~~~
-
-When using a lock manager, it may be desirable to record device leases against a
-VM. The lock manager will ensure the VM won't start unless the leases can be
-acquired.
-
-::
-
- ...
- <devices>
- ...
- <lease>
- <lockspace>somearea</lockspace>
- <key>somekey</key>
- <target path='/some/lease/path' offset='1024'/>
- </lease>
- ...
- </devices>
- ...
-
-``lockspace``
- This is an arbitrary string, identifying the lockspace within which the key
- is held. Lock managers may impose extra restrictions on the format, or length
- of the lockspace name.
-``key``
- This is an arbitrary string, uniquely identifying the lease to be acquired.
- Lock managers may impose extra restrictions on the format, or length of the
- key.
-``target``
- This is the fully qualified path of the file associated with the lockspace.
- The offset specifies where the lease is stored within the file. If the lock
- manager does not require an offset, just pass 0.
-
-:anchor:`<a id="elementsHostDev"/>`
-
-Host device assignment
-~~~~~~~~~~~~~~~~~~~~~~
-
-:anchor:`<a id="elementsHostDevSubsys"/>`
-
-USB / PCI / SCSI devices
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-USB, PCI and SCSI devices attached to the host can be passed through to the
-guest using the ``hostdev`` element. :since:`since after 0.4.4 for USB, 0.6.0
-for PCI (KVM only) and 1.0.6 for SCSI (KVM only)` :
-
-::
-
- ...
- <devices>
- <hostdev mode='subsystem' type='usb'>
- <source startupPolicy='optional'>
- <vendor id='0x1234'/>
- <product id='0xbeef'/>
- </source>
- <boot order='2'/>
- </hostdev>
- </devices>
- ...
-
-or:
-
-::
-
- ...
- <devices>
- <hostdev mode='subsystem' type='pci' managed='yes'>
- <source>
- <address domain='0x0000' bus='0x06' slot='0x02' function='0x0'/>
- </source>
- <boot order='1'/>
- <rom bar='on' file='/etc/fake/boot.bin'/>
- </hostdev>
- </devices>
- ...
-
-or:
-
-::
-
- ...
- <devices>
- <hostdev mode='subsystem' type='scsi' sgio='filtered' rawio='yes'>
- <source>
- <adapter name='scsi_host0'/>
- <address bus='0' target='0' unit='0'/>
- </source>
- <readonly/>
- <address type='drive' controller='0' bus='0' target='0' unit='0'/>
- </hostdev>
- </devices>
- ...
-
-or:
-
-::
-
- ...
- <devices>
- <hostdev mode='subsystem' type='scsi'>
- <source protocol='iscsi' name='iqn.2014-08.com.example:iscsi-nopool/1'>
- <host name='example.com' port='3260'/>
- <auth username='myuser'>
- <secret type='iscsi' usage='libvirtiscsi'/>
- </auth>
- </source>
- <address type='drive' controller='0' bus='0' target='0' unit='0'/>
- </hostdev>
- </devices>
- ...
-
-or:
-
-::
-
- ...
- <devices>
- <hostdev mode='subsystem' type='scsi_host'>
- <source protocol='vhost' wwpn='naa.50014057667280d8'/>
- </hostdev>
- </devices>
- ...
-
-or:
-
-::
-
- ...
- <devices>
- <hostdev mode='subsystem' type='mdev' model='vfio-pci'>
- <source>
- <address uuid='c2177883-f1bb-47f0-914d-32a22e3a8804'/>
- </source>
- </hostdev>
- <hostdev mode='subsystem' type='mdev' model='vfio-ccw'>
- <source>
- <address uuid='9063cba3-ecef-47b6-abcf-3fef4fdcad85'/>
- </source>
- <address type='ccw' cssid='0xfe' ssid='0x0' devno='0x0001'/>
- </hostdev>
- </devices>
- ...
-
-``hostdev``
- The ``hostdev`` element is the main container for describing host devices.
- For each device, the ``mode`` is always "subsystem" and the ``type`` is one
- of the following values with additional attributes noted.
-
- ``usb``
- USB devices are detached from the host on guest startup and reattached
- after the guest exits or the device is hot-unplugged.
- ``pci``
- For PCI devices, when ``managed`` is "yes" it is detached from the host
- before being passed on to the guest and reattached to the host after the
- guest exits. If ``managed`` is omitted or "no", the user is responsible to
- call ``virNodeDeviceDetachFlags`` (or ``virsh nodedev-detach`` before
- starting the guest or hot-plugging the device and
- ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-unplug
- or stopping the guest.
- ``scsi``
- For SCSI devices, user is responsible to make sure the device is not used
- by host. If supported by the hypervisor and OS, the optional ``sgio`` (
- :since:`since 1.0.6` ) attribute indicates whether unprivileged SG_IO
- commands are filtered for the disk. Valid settings are "filtered" or
- "unfiltered", where the default is "filtered". The optional ``rawio`` (
- :since:`since 1.2.9` ) attribute indicates whether the lun needs the rawio
- capability. Valid settings are "yes" or "no". See the rawio description
- within the `disk <#elementsDisks>`__ section. If a disk lun in the domain
- already has the rawio capability, then this setting not required.
- ``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
- can be specified further with "virtio-transitional",
- "virtio-non-transitional", or "virtio". See `Virtio transitional
- devices <#elementsVirtioTransitional>`__ for more details.
- ``mdev``
- For mediated devices ( :since:`Since 3.2.0` ) the ``model`` attribute
- specifies the device API which determines how the host's vfio driver will
- expose the device to the guest. Currently, ``model='vfio-pci'``,
- ``model='vfio-ccw'`` ( :since:`Since 4.4.0` ) and ``model='vfio-ap'`` (
- :since:`Since 4.9.0` ) is supported. `MDEV <drvnodedev.html#MDEV>`__
- section provides more information about mediated devices as well as how to
- create mediated devices on the host. :since:`Since 4.6.0 (QEMU 2.12)` an
- optional ``display`` attribute may be used to enable or disable support
- for an accelerated remote desktop backed by a mediated device (such as
- NVIDIA vGPU or Intel GVT-g) as an alternative to emulated `video
- devices <#elementsVideo>`__. This attribute is limited to
- ``model='vfio-pci'`` only. Supported values are either ``on`` or ``off``
- (default is 'off'). It is required to use a `graphical
- framebuffer <#elementsGraphics>`__ 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``
- 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
- be used as a boot display when a vgpu device is the primary display.
-
- Note: There are also some implications on the usage of guest's address
- type depending on the ``model`` attribute, see the ``address`` element
- below.
-
- Note: The ``managed`` attribute is only used with ``type='pci'`` and is
- ignored by all the other device types, thus setting ``managed`` explicitly
- with other than a PCI device has the same effect as omitting it. Similarly,
- ``model`` attribute is only supported by mediated devices and ignored by all
- other device types.
-
-``source``
- The source element describes the device as seen from the host using the
- following mechanism to describe:
-
- ``usb``
- The USB device can either be addressed by vendor / product id using the
- ``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
- ``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:
-
- ========= =====================================================================
- mandatory fail if missing for any reason (the default)
- requisite fail if missing on boot up, drop if missing on migrate/restore/revert
- optional drop if missing at any start attempt
- ========= =====================================================================
-
- ``pci``
- PCI devices can only be described by their ``address``.
- ``scsi``
- SCSI devices are described by both the ``adapter`` and ``address``
- elements. The ``address`` element includes a ``bus`` attribute (a 2-digit
- bus number), a ``target`` attribute (a 10-digit target number), and a
- ``unit`` attribute (a 20-digit unit number on the bus). Not all
- 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
- the ``protocol`` attribute. When the attribute is set to "iscsi", the host
- device XML follows the network `disk <#elementsDisks>`__ device using the
- same ``name`` attribute and optionally using the ``auth`` element to
- provide the authentication credentials to the iSCSI server.
-
- ``scsi_host``
- :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.
- ``mdev``
- Mediated devices ( :since:`Since 3.2.0` ) are described by the ``address``
- element. The ``address`` element contains a single mandatory attribute
- ``uuid``.
-
-``vendor``, ``product``
- The ``vendor`` and ``product`` elements each have an ``id`` attribute that
- specifies the USB vendor and product id. The ids can be given in decimal,
- hexadecimal (starting with 0x) or octal (starting with 0) form.
-``boot``
- Specifies that the device is bootable. The ``order`` attribute determines the
- order in which devices will be tried during boot sequence. The per-device
- ``boot`` elements cannot be used together with general boot elements in `BIOS
- bootloader <#elementsOSBIOS>`__ section. :since:`Since 0.8.8` for PCI
- devices, :since:`Since 1.0.1` for USB devices.
-``rom``
- The ``rom`` element is used to change how a PCI device's ROM is presented to
- the guest. The optional ``bar`` attribute can be set to "on" or "off", and
- determines whether or not the device's ROM will be visible in the guest's
- 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
- 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``
- 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)` .
-``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
- the host. The values of these attributes can be given in decimal, hexadecimal
- (starting with 0x) or octal (starting with 0) form. For PCI devices the
- element carries 4 attributes allowing to designate the device as can be found
- with the ``lspci`` or with ``virsh nodedev-list``. For SCSI devices a 'drive'
- address type must be used. For mediated devices, which are software-only
- devices defining an allocation of resources on the physical parent device,
- the address type used must conform to the ``model`` attribute of element
- ``hostdev``, e.g. any address type other than PCI for ``vfio-pci`` device API
- or any address type other than CCW for ``vfio-ccw`` device API will result in
- an error. `See above <#elementsAddress>`__ for more details on the address
- element.
-``driver``
- PCI devices can have an optional ``driver`` subelement that specifies which
- backend driver to use for PCI device assignment. Use the ``name`` attribute
- to select either "vfio" (for the new VFIO device assignment backend, which is
- compatible with UEFI SecureBoot) or "kvm" (the legacy device assignment
- handled directly by the KVM kernel module) :since:`Since 1.0.5 (QEMU and KVM
- only, requires kernel 3.6 or newer)` . When specified, device assignment will
- fail if the requested method of device assignment isn't available on the
- host. When not specified, the default is "vfio" on systems where the VFIO
- driver is available and loaded, and "kvm" on older systems, or those where
- the VFIO driver hasn't been loaded :since:`Since 1.1.3` (prior to that the
- default was always "kvm").
-``readonly``
- Indicates that the device is readonly, only supported by SCSI host device
- now. :since:`Since 1.0.6 (QEMU and KVM only)`
-``shareable``
- If present, this indicates the device is expected to be shared between
- domains (assuming the hypervisor and OS support this). Only supported by SCSI
- host device. :since:`Since 1.0.6`
-
- Note: Although ``shareable`` was introduced :since:`in 1.0.6` , it did not
- work as as expected until :since:`1.2.2` .
-
-:anchor:`<a id="elementsHostDevCaps"/>`
-
-Block / character devices
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Block / character devices from the host can be passed through to the guest using
-the ``hostdev`` element. This is only possible with container based
-virtualization. Devices are specified by a fully qualified path. :since:`since
-after 1.0.1 for LXC` :
-
-::
-
- ...
- <hostdev mode='capabilities' type='storage'>
- <source>
- <block>/dev/sdf1</block>
- </source>
- </hostdev>
- ...
-
-::
-
- ...
- <hostdev mode='capabilities' type='misc'>
- <source>
- <char>/dev/input/event3</char>
- </source>
- </hostdev>
- ...
-
-::
-
- ...
- <hostdev mode='capabilities' type='net'>
- <source>
- <interface>eth0</interface>
- </source>
- </hostdev>
- ...
-
-``hostdev``
- The ``hostdev`` element is the main container for describing host devices.
- For block/character device passthrough ``mode`` is always "capabilities" and
- ``type`` is "storage" for a block device, "misc" for a character device and
- "net" for a host network interface.
-``source``
- The source element describes the device as seen from the host. For block
- devices, the path to the block device in the host OS is provided in the
- nested "block" element, while for character devices the "char" element is
- used. For network interfaces, the name of the interface is provided in the
- "interface" element.
-
-:anchor:`<a id="elementsRedir"/>`
-
-Redirected devices
-~~~~~~~~~~~~~~~~~~
-
-USB device redirection through a character device is supported :since:`since
-after 0.9.5 (KVM only)` :
-
-::
-
- ...
- <devices>
- <redirdev bus='usb' type='tcp'>
- <source mode='connect' host='localhost' service='4000'/>
- <boot order='1'/>
- </redirdev>
- <redirfilter>
- <usbdev class='0x08' vendor='0x1234' product='0xbeef' version='2.56' allow='yes'/>
- <usbdev allow='no'/>
- </redirfilter>
- </devices>
- ...
-
-``redirdev``
- The ``redirdev`` element is the main container for describing redirected
- devices. ``bus`` must be "usb" for a USB device. An additional attribute
- ``type`` is required, matching one of the supported `serial
- device <#elementsConsole>`__ types, to describe the host side of the tunnel;
- ``type='tcp'`` or ``type='spicevmc'`` (which uses the usbredir channel of a
- `SPICE graphics device <#elementsGraphics>`__) are typical. The redirdev
- element has an optional sub-element ``<address>`` which can tie the device to
- a particular controller. Further sub-elements, such as ``<source>``, may be
- required according to the given type, although a ``<target>`` sub-element is
- not required (since the consumer of the character device is the hypervisor
- itself, rather than a device visible in the guest).
-``boot``
- Specifies that the device is bootable. The ``order`` attribute determines the
- order in which devices will be tried during boot sequence. The per-device
- ``boot`` elements cannot be used together with general boot elements in `BIOS
- bootloader <#elementsOSBIOS>`__ section. ( :since:`Since 1.0.1` )
-``redirfilter``
- The\ ``redirfilter``\ element is used for creating the filter rule to filter
- out certain devices from redirection. It uses sub-element ``<usbdev>`` to
- define each filter rule. ``class`` attribute is the USB Class code, for
- example, 0x08 represents mass storage devices. The USB device can be
- addressed by vendor / product id using the ``vendor`` and ``product``
- attributes. ``version`` is the device revision from the bcdDevice field (not
- the version of the USB protocol). These four attributes are optional and
- ``-1`` can be used to allow any value for them. ``allow`` attribute is
- mandatory, 'yes' means allow, 'no' for deny.
-
-:anchor:`<a id="elementsSmartcard"/>`
-
-Smartcard devices
-~~~~~~~~~~~~~~~~~
-
-A virtual smartcard device can be supplied to the guest via the ``smartcard``
-element. A USB smartcard reader device on the host cannot be used on a guest
-with simple device passthrough, since it will then not be available on the host,
-possibly locking the host computer when it is "removed". Therefore, some
-hypervisors provide a specialized virtual device that can present a smartcard
-interface to the guest, with several modes for describing how credentials are
-obtained from the host or even a from a channel created to a third-party
-smartcard provider. :since:`Since 0.8.8`
-
-::
-
- ...
- <devices>
- <smartcard mode='host'/>
- <smartcard mode='host-certificates'>
- <certificate>cert1</certificate>
- <certificate>cert2</certificate>
- <certificate>cert3</certificate>
- <database>/etc/pki/nssdb/</database>
- </smartcard>
- <smartcard mode='passthrough' type='tcp'>
- <source mode='bind' host='127.0.0.1' service='2001'/>
- <protocol type='raw'/>
- <address type='ccid' controller='0' slot='0'/>
- </smartcard>
- <smartcard mode='passthrough' type='spicevmc'/>
- </devices>
- ...
-
-The ``<smartcard>`` element has a mandatory attribute ``mode``. The following
-modes are supported; in each mode, the guest sees a device on its USB bus that
-behaves like a physical USB CCID (Chip/Smart Card Interface Device) card.
-
-``host``
- The simplest operation, where the hypervisor relays all requests from the
- guest into direct access to the host's smartcard via NSS. No other attributes
- or sub-elements are required. See below about the use of an optional
- ``<address>`` sub-element.
-``host-certificates``
- Rather than requiring a smartcard to be plugged into the host, it is possible
- to provide three NSS certificate names residing in a database on the host.
- These certificates can be generated via the command
- ``certutil -d /etc/pki/nssdb -x -t CT,CT,CT -S -s CN=cert1 -n cert1``,
- and the resulting three certificate names must be supplied as the content of
- each of three ``<certificate>`` sub-elements. An additional sub-element
- ``<database>`` can specify the absolute path to an alternate directory
- (matching the ``-d`` option of the ``certutil`` command when creating the
- certificates); if not present, it defaults to /etc/pki/nssdb.
-``passthrough``
- Rather than having the hypervisor directly communicate with the host, it is
- possible to tunnel all requests through a secondary character device to a
- third-party provider (which may in turn be talking to a smartcard or using
- three certificate files). In this mode of operation, an additional attribute
- ``type`` is required, matching one of the supported `serial
- device <#elementsConsole>`__ types, to describe the host side of the tunnel;
- ``type='tcp'`` or ``type='spicevmc'`` (which uses the smartcard channel of a
- `SPICE graphics device <#elementsGraphics>`__) are typical. Further
- sub-elements, such as ``<source>``, may be required according to the given
- type, although a ``<target>`` sub-element is not required (since the consumer
- of the character device is the hypervisor itself, rather than a device
- visible in the guest).
-
-Each mode supports an optional sub-element ``<address>``, which fine-tunes the
-correlation between the smartcard and a ccid bus controller, `documented
-above <#elementsAddress>`__. For now, qemu only supports at most one smartcard,
-with an address of bus=0 slot=0.
-
-:anchor:`<a id="elementsNICS"/>`
-
-Network interfaces
-~~~~~~~~~~~~~~~~~~
-
-::
-
- ...
- <devices>
- <interface type='direct' trustGuestRxFilters='yes'>
- <source dev='eth0'/>
- <mac address='52:54:00:5d:c7:9e'/>
- <boot order='1'/>
- <rom bar='off'/>
- </interface>
- </devices>
- ...
-
-There are several possibilities for specifying a network interface visible to
-the guest. Each subsection below provides more details about common setup
-options.
-
-:since:`Since 1.2.10` ), the ``interface`` element property
-``trustGuestRxFilters`` provides the capability for the host to detect and trust
-reports from the guest regarding changes to the interface mac address and
-receive filters by setting the attribute to ``yes``. The default setting for the
-attribute is ``no`` for security reasons and support depends on the guest
-network device model as well as the type of connection on the host - currently
-it is only supported for the virtio device model and for macvtap connections on
-the host.
-
-Each ``<interface>`` element has an optional ``<address>`` sub-element that can
-tie the interface to a particular pci slot, with attribute ``type='pci'`` as
-`documented above <#elementsAddress>`__.
-
-: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.
-
-:anchor:`<a id="elementsNICSVirtual"/>`
-
-Virtual network
-^^^^^^^^^^^^^^^
-
-**This is the recommended config for general guest connectivity on hosts with
-dynamic / wireless networking configs (or multi-host environments where the host
-hardware details are described separately in a ``<network>`` definition
-:since:`Since 0.9.4` ).**
-
-Provides a connection whose details are described by the named network
-definition. Depending on the virtual network's "forward mode" configuration, the
-network may be totally isolated (no ``<forward>`` element given), NAT'ing to an
-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` )
-
-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
-outside the scope of libvirt. In the case of isolated, nat, and routed networks,
-DHCP and DNS are provided on the virtual network by libvirt, and the IP range
-can be determined by examining the virtual network config with
-'``virsh net-dumpxml [networkname]``'. There is one virtual network called
-'default' setup out of the box which does NAT'ing to the default route and has
-an IP range of ``192.168.122.0/255.255.255.0``. Each guest will have an
-associated tun device created with a name of vnetN, which can also be overridden
-with the <target> element (see `overriding the target
-element <#elementsNICSTargetOverride>`__).
-
-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` .
-
-When a guest is running an interface of type ``network`` may include a
-``portid`` attribute. This provides the UUID of an associated virNetworkPortPtr
-object that records the association between the domain interface and the
-network. This attribute is read-only since port objects are create and deleted
-automatically during startup and shutdown. :since:`Since 5.1.0`
-
-Also, similar to ``direct`` network connections (described below), a connection
-of type ``network`` may specify a ``virtualport`` element, with configuration
-data to be forwarded to a vepa (802.1Qbg) or 802.1Qbh compliant switch (
-:since:`Since 0.8.2` ), or to an Open vSwitch virtual switch ( :since:`Since
-0.9.11` ).
-
-Since 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``
-attribute, and specify attributes from multiple different virtualport types (and
-also to leave out certain attributes); at domain startup time, a complete
-``<virtualport>`` element will be constructed by merging together the type and
-attributes defined in the network and the portgroup referenced by the interface.
-The newly-constructed virtualport is a combination of them. The attributes from
-lower virtualport can't make change on the ones defined in higher virtualport.
-Interface takes the highest priority, portgroup is lowest priority. (
-:since:`Since 0.10.0` ). For example, in order to work properly with both an
-802.1Qbh switch and an Open vSwitch switch, you may choose to specify no type,
-but both a ``profileid`` (in case the switch is 802.1Qbh) and an ``interfaceid``
-(in case the switch is Open vSwitch) (you may also omit the other attributes,
-such as managerid, typeid, or profileid, to be filled in from the network's
-``<virtualport>``). If you want to limit a guest to connecting only to certain
-types of switches, you can specify the virtualport type, but still omit some/all
-of the parameters - in this case if the host's network has a different type of
-virtualport, connection of the interface will fail.
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- </interface>
- ...
- <interface type='network'>
- <source network='default' portgroup='engineering'/>
- <target dev='vnet7'/>
- <mac address="00:11:22:33:44:55"/>
- <virtualport>
- <parameters instanceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
- </virtualport>
- </interface>
- </devices>
- ...
-
-:anchor:`<a id="elementsNICSBridge"/>`
-
-Bridge to LAN
-^^^^^^^^^^^^^
-
-**This is the recommended config for general guest connectivity on hosts with
-static wired networking configs.**
-
-Provides a bridge from the VM directly to the LAN. This assumes there is a
-bridge device on the host which has one or more of the hosts physical NICs
-attached. The guest VM will have an associated tun device created with a name of
-vnetN, which can also be overridden with the <target> element (see `overriding
-the target element <#elementsNICSTargetOverride>`__). The tun device will be
-attached to the bridge. The IP range / network configuration is whatever is used
-on the LAN. This provides the guest VM full incoming & outgoing net access just
-like a physical machine.
-
-On Linux systems, the bridge device is normally a standard Linux host bridge. On
-hosts that support Open vSwitch, it is also possible to connect to an Open
-vSwitch bridge device by adding a ``<virtualport type='openvswitch'/>`` to the
-interface definition. ( :since:`Since 0.9.11` ). The Open vSwitch type
-virtualport accepts two parameters in its ``<parameters>`` element - an
-``interfaceid`` which is a standard uuid used to uniquely identify this
-particular interface to Open vSwitch (if you do not specify one, a random
-interfaceid will be generated for you when you first define the interface), and
-an optional ``profileid`` which is sent to Open vSwitch as the interfaces
-"port-profile".
-
-::
-
- ...
- <devices>
- ...
- <interface type='bridge'>
- <source bridge='br0'/>
- </interface>
- <interface type='bridge'>
- <source bridge='br1'/>
- <target dev='vnet7'/>
- <mac address="00:11:22:33:44:55"/>
- </interface>
- <interface type='bridge'>
- <source bridge='ovsbr'/>
- <virtualport type='openvswitch'>
- <parameters profileid='menial' interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
- </virtualport>
- </interface>
- ...
- </devices>
- ...
-
-On hosts that support Open vSwitch on the kernel side and have the Midonet Host
-Agent configured, it is also possible to connect to the 'midonet' bridge device
-by adding a ``<virtualport type='midonet'/>`` to the interface definition. (
-:since:`Since 1.2.13` ). The Midonet virtualport type requires an
-``interfaceid`` attribute in its ``<parameters>`` element. This interface id is
-the UUID that specifies which port in the virtual network topology will be bound
-to the interface.
-
-::
-
- ...
- <devices>
- ...
- <interface type='bridge'>
- <source bridge='br0'/>
- </interface>
- <interface type='bridge'>
- <source bridge='br1'/>
- <target dev='vnet7'/>
- <mac address="00:11:22:33:44:55"/>
- </interface>
- <interface type='bridge'>
- <source bridge='midonet'/>
- <virtualport type='midonet'>
- <parameters interfaceid='0b2d64da-3d0e-431e-afdd-804415d6ebbb'/>
- </virtualport>
- </interface>
- ...
- </devices>
- ...
-
-:anchor:`<a id="elementsNICSSlirp"/>`
-
-Userspace SLIRP stack
-^^^^^^^^^^^^^^^^^^^^^
-
-Provides a virtual LAN with NAT to the outside world. The virtual network has
-DHCP & DNS services and will give the guest VM addresses starting from
-``10.0.2.15``. The default router will be ``10.0.2.2`` and the DNS server will
-be ``10.0.2.3``. This networking is the only option for unprivileged users who
-need their VMs to have outgoing access. :since:`Since 3.8.0` it is possible to
-override the default network address by including an ``ip`` element specifying
-an IPv4 address in its one mandatory attribute, ``address``. Optionally, a
-second ``ip`` element with a ``family`` attribute set to "ipv6" can be specified
-to add an IPv6 address to the interface. ``address``. Optionally, address
-``prefix`` can be specified.
-
-::
-
- ...
- <devices>
- <interface type='user'/>
- ...
- <interface type='user'>
- <mac address="00:11:22:33:44:55"/>
- <ip family='ipv4' address='172.17.2.0' prefix='24'/>
- <ip family='ipv6' address='2001:db8:ac10:fd01::' prefix='64'/>
- </interface>
- </devices>
- ...
-
-:anchor:`<a id="elementsNICSEthernet"/>`
-
-Generic ethernet connection
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Provides a means to use a new or existing tap device (or veth device pair,
-depening on the needs of the hypervisor driver) that is partially or wholly
-setup external to libvirt (either prior to the guest starting, or while the
-guest is being started via an optional script specified in the config).
-
-The name of the tap device can optionally be specified with the ``dev``
-attribute of the ``<target>`` element. If no target dev is specified, libvirt
-will create a new standard tap device with a name of the pattern "vnetN", where
-"N" is replaced with a number. If a target dev is specified and that device
-doesn't exist, then a new standard tap device will be created with the exact dev
-name given. If the specified target dev does exist, then that existing device
-will be used. Usually some basic setup of the device is done by libvirt,
-including setting a MAC address, and the IFF_UP flag, but if the ``dev`` is a
-pre-existing device, and the ``managed`` attribute of the ``target`` element is
-also set to "no" (the default value is "yes"), even this basic setup will not be
-performed - libvirt will simply pass the device on to the hypervisor with no
-setup at all. :since:`Since 5.7.0` Using managed='no' with a pre-created tap
-device is useful because it permits a virtual machine managed by an unprivileged
-libvirtd to have emulated network devices based on tap devices.
-
-After creating/opening the tap device, an optional shell script (given in the
-``path`` attribute of the ``<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 5.1.0` These can be used to do whatever extra host network
-integration is required.
-
-::
-
- ...
- <devices>
- <interface type='ethernet'>
- <script path='/etc/qemu-ifup-mynet'/>
- <downscript path='/etc/qemu-ifdown-mynet'/>
- </interface>
- ...
- <interface type='ethernet'>
- <target dev='mytap1' managed='no'/>
- <model type='virtio'/>
- </interface>
- </devices>
- ...
-
-:anchor:`<a id="elementsNICSDirect"/>`
-
-Direct attachment to physical interface
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-| Provides direct attachment of the virtual machine's NIC to the given physical
- interface of the host. :since:`Since 0.7.7 (QEMU and KVM only)`
-| This setup requires the Linux macvtap driver to be available. :since:`(Since
- Linux 2.6.34.)` One of the modes 'vepa' ( `'Virtual Ethernet Port
- Aggregator' <http://www.ieee802.org/1/files/public/docs2009/new-evb-congdon-vepa-modular-0709-v01.pdf>`__),
- 'bridge' or 'private' can be chosen for the operation mode of the macvtap
- device, 'vepa' being the default mode. The individual modes cause the delivery
- of packets to behave as follows:
-
-If the model type is set to ``virtio`` and interface's ``trustGuestRxFilters``
-attribute is set to ``yes``, changes made to the interface mac address,
-unicast/multicast receive filters, and vlan settings in the guest will be
-monitored and propagated to the associated macvtap device on the host (
-:since:`Since 1.2.10` ). If ``trustGuestRxFilters`` is not set, or is not
-supported for the device model in use, an attempted change to the mac address
-originating from the guest side will result in a non-working network connection.
-
-``vepa``
- All VMs' packets are sent to the external bridge. Packets whose destination
- is a VM on the same host as where the packet originates from are sent back to
- the host by the VEPA capable bridge (today's bridges are typically not VEPA
- capable).
-``bridge``
- Packets whose destination is on the same host as where they originate from
- are directly delivered to the target macvtap device. Both origin and
- destination devices need to be in bridge mode for direct delivery. If either
- one of them is in ``vepa`` mode, a VEPA capable bridge is required.
-``private``
- All packets are sent to the external bridge and will only be delivered to a
- target VM on the same host if they are sent through an external router or
- gateway and that device sends them back to the host. This procedure is
- followed if either the source or destination device is in ``private`` mode.
-``passthrough``
- This feature attaches a virtual function of a SRIOV capable NIC directly to a
- VM without losing the migration capability. All packets are sent to the VF/IF
- of the configured network device. Depending on the capabilities of the device
- additional prerequisites or limitations may apply; for example, on Linux this
- requires kernel 2.6.38 or newer. :since:`Since 0.9.2`
-
-::
-
- ...
- <devices>
- ...
- <interface type='direct' trustGuestRxFilters='no'>
- <source dev='eth0' mode='vepa'/>
- </interface>
- </devices>
- ...
-
-The network access of direct attached virtual machines can be managed by the
-hardware switch to which the physical interface of the host machine is connected
-to.
-
-The interface can have additional parameters as shown below, if the switch is
-conforming to the IEEE 802.1Qbg standard. The parameters of the virtualport
-element are documented in more detail in the IEEE 802.1Qbg standard. The values
-are network specific and should be provided by the network administrator. In
-802.1Qbg terms, the Virtual Station Interface (VSI) represents the virtual
-interface of a virtual machine. :since:`Since 0.8.2`
-
-Please note that IEEE 802.1Qbg requires a non-zero value for the VLAN ID.
-
-``managerid``
- The VSI Manager ID identifies the database containing the VSI type and
- instance definitions. This is an integer value and the value 0 is reserved.
-``typeid``
- The VSI Type ID identifies a VSI type characterizing the network access. VSI
- types are typically managed by network administrator. This is an integer
- value.
-``typeidversion``
- The VSI Type Version allows multiple versions of a VSI Type. This is an
- integer value.
-``instanceid``
- The VSI Instance ID Identifier is generated when a VSI instance (i.e. a
- virtual interface of a virtual machine) is created. This is a globally unique
- identifier.
-
-::
-
- ...
- <devices>
- ...
- <interface type='direct'>
- <source dev='eth0.2' mode='vepa'/>
- <virtualport type="802.1Qbg">
- <parameters managerid="11" typeid="1193047" typeidversion="2" instanceid="09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f"/>
- </virtualport>
- </interface>
- </devices>
- ...
-
-The interface can have additional parameters as shown below if the switch is
-conforming to the IEEE 802.1Qbh standard. The values are network specific and
-should be provided by the network administrator. :since:`Since 0.8.2`
-
-``profileid``
- The profile ID contains the name of the port profile that is to be applied to
- this interface. This name is resolved by the port profile database into the
- network parameters from the port profile, and those network parameters will
- be applied to this interface.
-
-::
-
- ...
- <devices>
- ...
- <interface type='direct'>
- <source dev='eth0' mode='private'/>
- <virtualport type='802.1Qbh'>
- <parameters profileid='finance'/>
- </virtualport>
- </interface>
- </devices>
- ...
-
-:anchor:`<a id="elementsNICSHostdev"/>`
-
-PCI Passthrough
-^^^^^^^^^^^^^^^
-
-A PCI network device (specified by the <source> element) is directly assigned to
-the guest using generic device passthrough, after first optionally setting the
-device's MAC address to the configured value, and associating the device with an
-802.1Qbh capable switch using an optionally specified <virtualport> element (see
-the examples of virtualport given above for type='direct' network devices). Note
-that - due to limitations in standard single-port PCI ethernet card driver
-design - only SR-IOV (Single Root I/O Virtualization) virtual function (VF)
-devices can be assigned in this manner; to assign a standard single-port PCI or
-PCIe ethernet card to a guest, use the traditional <hostdev> device definition
-and :since:`Since 0.9.11`
-
-To use VFIO device assignment rather than traditional/legacy KVM device
-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``
-sub-element with a ``name`` attribute set to "vfio". To use legacy KVM device
-assignment you can set ``name`` to "kvm" (or simply omit the ``<driver>``
-element, since "kvm" is currently the default). :since:`Since 1.0.5 (QEMU and
-KVM only, requires kernel 3.6 or newer)`
-
-Note that this "intelligent passthrough" of network devices is very similar to
-the functionality of a standard <hostdev> device, the difference being that this
-method allows specifying a MAC address and <virtualport> for the passed-through
-device. If these capabilities are not required, if you have a standard
-single-port PCI, PCIe, or USB network card that doesn't support SR-IOV (and
-hence would anyway lose the configured MAC address during reset after being
-assigned to the guest domain), or if you are using a version of libvirt older
-than 0.9.11, you should use standard <hostdev> to assign the device to the guest
-instead of <interface type='hostdev'/>.
-
-Similar to the functionality of a standard <hostdev> device, when ``managed`` is
-"yes", it is detached from the host before being passed on to the guest, and
-reattached to the host after the guest exits. If ``managed`` is omitted or "no",
-the user is responsible to call ``virNodeDeviceDettach`` (or
-``virsh nodedev-detach``) before starting the guest or hot-plugging the device,
-and ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-unplug
-or stopping the guest.
-
-::
-
- ...
- <devices>
- <interface type='hostdev' managed='yes'>
- <driver name='vfio'/>
- <source>
- <address type='pci' domain='0x0000' bus='0x00' slot='0x07' function='0x0'/>
- </source>
- <mac address='52:54:00:6d:90:02'/>
- <virtualport type='802.1Qbh'>
- <parameters profileid='finance'/>
- </virtualport>
- </interface>
- </devices>
- ...
-
-:anchor:`<a id="elementsTeaming"/>`
-
-Teaming a virtio/hostdev NIC pair
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-:since:`Since 6.1.0 (QEMU and KVM only, requires QEMU 4.2.0 or newer and a guest
-virtio-net driver supporting the "failover" feature, such as the one included in
-Linux kernel 4.18 and newer) ` The ``<teaming>`` element of two interfaces can
-be used to connect them as a team/bond device in the guest (assuming proper
-support in the hypervisor and the guest network driver).
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='mybridge'/>
- <mac address='00:11:22:33:44:55'/>
- <model type='virtio'/>
- <teaming type='persistent'/>
- <alias name='ua-backup0'/>
- </interface>
- <interface type='network'>
- <source network='hostdev-pool'/>
- <mac address='00:11:22:33:44:55'/>
- <model type='virtio'/>
- <teaming type='transient' persistent='ua-backup0'/>
- </interface>
- </devices>
- ...
-
-The ``<teaming>`` element required attribute ``type`` will be set to either
-``"persistent"`` to indicate a device that should always be present in the
-domain, or ``"transient"`` to indicate a device that may periodically be
-removed, then later re-added to the domain. When type="transient", there should
-be a second attribute to ``<teaming>`` called ``"persistent"`` - this attribute
-should be set to the alias name of the other device in the pair (the one that
-has ``<teaming type="persistent'/>``).
-
-In the particular case of QEMU, libvirt's ``<teaming>`` element is used to setup
-a virtio-net "failover" device pair. For this setup, the persistent device must
-be an interface with ``<model type="virtio"/>``, and the transient device
-must be ``<interface type='hostdev'/>`` (or ``<interface type='network'/>``
-where the referenced network defines a pool of SRIOV VFs). The guest will then
-have a simple network team/bond device made of the virtio NIC + hostdev NIC
-pair. In this configuration, the higher-performing hostdev NIC will normally be
-preferred for all network traffic, but when the domain is migrated, QEMU will
-automatically unplug the VF from the guest, and then hotplug a similar device
-once migration is completed; while migration is taking place, network traffic
-will use the virtio NIC. (Of course the emulated virtio NIC and the hostdev NIC
-must be connected to the same subnet for bonding to work properly).
-
-NB1: Since you must know the alias name of the virtio NIC when configuring the
-hostdev NIC, it will need to be manually set in the virtio NIC's configuration
-(as with all other manually set alias names, this means it must start with
-"ua-").
-
-NB2: Currently the only implementation of the guest OS virtio-net driver
-supporting virtio-net failover requires that the MAC addresses of the virtio and
-hostdev NIC must match. Since that may not always be a requirement in the
-future, libvirt doesn't enforce this limitation - it is up to the
-person/management application that is creating the configuration to assure the
-MAC addresses of the two devices match.
-
-NB3: Since the PCI addresses of the SRIOV VFs on the hosts that are the source
-and destination of the migration will almost certainly be different, either
-higher level management software will need to modify the ``<source>`` of the
-hostdev NIC (``<interface type='hostdev'>``) at the start of migration, or (a
-simpler solution) the configuration will need to use a libvirt "hostdev" virtual
-network that maintains a pool of such devices, as is implied in the example's
-use of the libvirt network named "hostdev-pool" - as long as the hostdev network
-pools on both hosts have the same name, libvirt itself will take care of
-allocating an appropriate device on both ends of the migration. Similarly the
-XML for the virtio interface must also either work correctly unmodified on both
-the source and destination of the migration (e.g. by connecting to the same
-bridge device on both hosts, or by using the same virtual network), or the
-management software must properly modify the interface XML during migration so
-that the virtio device remains connected to the same network segment before and
-after migration.
-
-:anchor:`<a id="elementsNICSMulticast"/>`
-
-Multicast tunnel
-^^^^^^^^^^^^^^^^
-
-A multicast group is setup to represent a virtual network. Any VMs whose network
-devices are in the same multicast group can talk to each other even across
-hosts. This mode is also available to unprivileged users. There is no default
-DNS or DHCP support and no outgoing network access. To provide outgoing network
-access, one of the VMs should have a 2nd NIC which is connected to one of the
-first 4 network types and do the appropriate routing. The multicast protocol is
-compatible with that used by user mode linux guests too. The source address used
-must be from the multicast address block.
-
-::
-
- ...
- <devices>
- <interface type='mcast'>
- <mac address='52:54:00:6d:90:01'/>
- <source address='230.0.0.1' port='5558'/>
- </interface>
- </devices>
- ...
-
-:anchor:`<a id="elementsNICSTCP"/>`
-
-TCP tunnel
-^^^^^^^^^^
-
-A TCP client/server architecture provides a virtual network. One VM provides the
-server end of the network, all other VMS are configured as clients. All network
-traffic is routed between the VMs via the server. This mode is also available to
-unprivileged users. There is no default DNS or DHCP support and no outgoing
-network access. To provide outgoing network access, one of the VMs should have a
-2nd NIC which is connected to one of the first 4 network types and do the
-appropriate routing.
-
-::
-
- ...
- <devices>
- <interface type='server'>
- <mac address='52:54:00:22:c9:42'/>
- <source address='192.168.0.1' port='5558'/>
- </interface>
- ...
- <interface type='client'>
- <mac address='52:54:00:8b:c9:51'/>
- <source address='192.168.0.1' port='5558'/>
- </interface>
- </devices>
- ...
-
-:anchor:`<a id="elementsNICSUDP"/>`
-
-UDP unicast tunnel
-^^^^^^^^^^^^^^^^^^
-
-A UDP unicast architecture provides a virtual network which enables connections
-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`
-
-::
-
- ...
- <devices>
- <interface type='udp'>
- <mac address='52:54:00:22:c9:42'/>
- <source address='127.0.0.1' port='11115'>
- <local address='127.0.0.1' port='11116'/>
- </source>
- </interface>
- </devices>
- ...
-
-:anchor:`<a id="elementsNICSModel"/>`
-
-Setting the NIC model
-^^^^^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <target dev='vnet1'/>
- <model type='ne2k_pci'/>
- </interface>
- </devices>
- ...
-
-For hypervisors which support this, you can set the model of emulated network
-interface card.
-
-The values for ``type`` aren't defined specifically by libvirt, but by what the
-underlying hypervisor supports (if any). For QEMU and KVM you can get a list of
-supported models with these commands:
-
-::
-
- qemu -net nic,model=? /dev/null
- 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` ,
-``virtio-transitional`` and ``virtio-non-transitional`` values are supported.
-See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more
-details.
-
-:anchor:`<a id="elementsDriverBackendOptions"/>`
-
-Setting NIC driver-specific options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <target dev='vnet1'/>
- <model type='virtio'/>
- <driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5' rx_queue_size='256' tx_queue_size='256'>
- <host csum='off' gso='off' tso4='off' tso6='off' ecn='off' ufo='off' mrg_rxbuf='off'/>
- <guest csum='off' tso4='off' tso6='off' ecn='off' ufo='off'/>
- </driver>
- </interface>
- </devices>
- ...
-
-Some NICs may have tunable driver-specific options. These are set as attributes
-of the ``driver`` sub-element of the interface definition. Currently the
-following attributes are available for the ``"virtio"`` NIC driver:
-
-``name``
- The optional ``name`` attribute forces which type of backend driver to use.
- The value can be either 'qemu' (a user-space backend) or 'vhost' (a kernel
- 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)`
- 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)`
- For interfaces of type='vhostuser', the ``name`` attribute is ignored. The
- backend driver used is always vhost-user.
-``txmode``
- The ``txmode`` attribute specifies how to handle transmission of packets when
- the transmit buffer is full. The value can be either 'iothread' or 'timer'.
- :since:`Since 0.8.8 (QEMU and KVM only)`
- If set to 'iothread', packet tx is all done in an iothread in the bottom half
- of the driver (this option translates into adding "tx=bh" to the qemu
- commandline -device virtio-net-pci option).
- If set to 'timer', tx work is done in qemu, and if there is more tx data than
- can be sent at the present time, a timer is set before qemu moves on to do
- other things; when the timer fires, another attempt is made to send more
- data.
- The resulting difference, according to the qemu developer who added the
- option is: "bh makes tx more asynchronous and reduces latency, but
- potentially causes more processor bandwidth contention since the CPU doing
- the tx isn't necessarily the CPU where the guest generated the packets."
- **In general you should leave this option alone, unless you are very certain
- you know what you are doing.**
-``ioeventfd``
- This optional attribute allows users to set `domain I/O asynchronous
- handling <https://patchwork.kernel.org/patch/43390/>`__ for interface device.
- The default is left to the discretion of the hypervisor. Accepted values are
- "on" and "off". Enabling this allows qemu to execute VM while a separate
- thread handles I/O. Typically guests experiencing high system CPU utilization
- during I/O will benefit from this. On the other hand, on overloaded host it
- could increase guest I/O latency. :since:`Since 0.9.3 (QEMU and KVM only)`
- **In general you should leave this option alone, unless you are very certain
- you know what you are doing.**
-``event_idx``
- The ``event_idx`` attribute controls some aspects of device event processing.
- The value can be either 'on' or 'off' - if it is on, it will 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, unless you are very certain
- you know what you are doing.**
-``queues``
- The optional ``queues`` attribute controls the number of queues to be used
- for either `Multiqueue
- virtio-net <https://www.linux-kvm.org/page/Multiqueue>`__ or
- `vhost-user <#elementVhostuser>`__ network interfaces. Use of multiple packet
- 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)`
-``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)`
- **In general you should leave this option alone, unless you are very certain
- you know what you are doing.**
-``tx_queue_size``
- The optional ``tx_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, QEMU v2.9 requires value to be a
- power of two from [256, 1024] range. In addition to that, this may work only
- for a subset of interface types, e.g. aforementioned QEMU enables this option
- only for ``vhostuser`` type. :since:`Since 3.7.0 (QEMU and KVM only)`
- **In general you should leave this option alone, unless you are very certain
- you know what you are doing.**
-virtio options
- For virtio interfaces, `Virtio-specific options <#elementsVirtio>`__ can also
- be set. ( :since:`Since 3.5.0` )
-
-Offloading options for the host and guest can be configured using the following
-sub-elements:
-
-``host``
- The ``csum``, ``gso``, ``tso4``, ``tso6``, ``ecn`` and ``ufo`` attributes
- with possible values ``on`` and ``off`` can be used to turn off host
- offloading options. By default, the supported offloads are enabled by QEMU.
- :since:`Since 1.2.9 (QEMU only)` The ``mrg_rxbuf`` attribute can be used to
- control mergeable rx buffers on the host side. Possible values are ``on``
- (default) and ``off``. :since:`Since 1.2.13 (QEMU only)`
-``guest``
- The ``csum``, ``tso4``, ``tso6``, ``ecn`` and ``ufo`` attributes with
- possible values ``on`` and ``off`` can be used to turn off guest offloading
- options. By default, the supported offloads are enabled by QEMU.
- :since:`Since 1.2.9 (QEMU only)`
-
-:anchor:`<a id="elementsBackendOptions"/>`
-
-Setting network backend-specific options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <target dev='vnet1'/>
- <model type='virtio'/>
- <backend tap='/dev/net/tun' vhost='/dev/vhost-net'/>
- <driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5'/>
- <tune>
- <sndbuf>1600</sndbuf>
- </tune>
- </interface>
- </devices>
- ...
-
-For tuning the backend of the network, the ``backend`` element can be used. The
-``vhost`` attribute can override the default vhost device path
-(``/dev/vhost-net``) for devices with ``virtio`` model. The ``tap`` attribute
-overrides the tun/tap device path (default: ``/dev/net/tun``) for network and
-bridge interfaces. This does not work in session mode. :since:`Since 1.2.9`
-
-For tap devices there is also ``sndbuf`` element which can adjust the size of
-send buffer in the host. :since:`Since 0.8.8`
-
-:anchor:`<a id="elementsNICSTargetOverride"/>`
-
-Overriding the target element
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <target dev='vnet1'/>
- </interface>
- </devices>
- ...
-
-If no target is specified, certain hypervisors will automatically generate a
-name for the created tun device. This name can be manually specified, however
-the name *should not start with either 'vnet', 'vif', 'macvtap', or 'macvlan'*,
-which are prefixes reserved by libvirt and certain hypervisors. Manually
-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,
-the ``guest`` element should be used, as in the following snippet:
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <guest dev='myeth'/>
- </interface>
- </devices>
- ...
-
-:anchor:`<a id="elementsNICSBoot"/>`
-
-Specifying boot order
-^^^^^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <target dev='vnet1'/>
- <boot order='1'/>
- </interface>
- </devices>
- ...
-
-For hypervisors which support this, you can set a specific NIC to be used for
-network boot. The ``order`` attribute determines the order in which devices will
-be tried during boot sequence. The per-device ``boot`` elements cannot be used
-together with general boot elements in `BIOS bootloader <#elementsOSBIOS>`__
-section. :since:`Since 0.8.8`
-
-:anchor:`<a id="elementsNICSROM"/>`
-
-Interface ROM BIOS configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <target dev='vnet1'/>
- <rom bar='on' file='/etc/fake/boot.bin'/>
- </interface>
- </devices>
- ...
-
-For hypervisors which support this, you can change how a PCI Network device's
-ROM is presented to the guest. The ``bar`` attribute can be set to "on" or
-"off", and determines whether or not the device's ROM will be visible in the
-guest's 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"). 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)` .
-
-:anchor:`<a id="elementDomain"/>`
-
-Setting up a network backend in a driver domain
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- ...
- <interface type='bridge'>
- <source bridge='br0'/>
- <backenddomain name='netvm'/>
- </interface>
- ...
- </devices>
- ...
-
-The optional ``backenddomain`` element allows specifying a backend domain (aka
-driver domain) for the interface. Use the ``name`` attribute to specify the
-backend domain name. You can use it to create a direct network link between
-domains (so data will not go through host system). Use with type 'ethernet' to
-create plain network link, or with type 'bridge' to connect to a bridge inside
-the backend domain. :since:`Since 1.2.13 (Xen only)`
-
-:anchor:`<a id="elementQoS"/>`
-
-Quality of service
-^^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <target dev='vnet0'/>
- <bandwidth>
- <inbound average='1000' peak='5000' floor='200' burst='1024'/>
- <outbound average='128' peak='256' burst='256'/>
- </bandwidth>
- </interface>
- </devices>
- ...
-
-This part of interface XML provides setting quality of service. Incoming and
-outgoing traffic can be shaped independently. The ``bandwidth`` element and its
-child elements are described in the `QoS <formatnetwork.html#elementQoS>`__
-section of the Network XML.
-
-:anchor:`<a id="elementVlanTag"/>`
-
-Setting VLAN tag (on supported network types only)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='bridge'>
- <vlan>
- <tag id='42'/>
- </vlan>
- <source bridge='ovsbr0'/>
- <virtualport type='openvswitch'>
- <parameters interfaceid='09b11c53-8b5c-4eeb-8f00-d84eaa0aaa4f'/>
- </virtualport>
- </interface>
- <interface type='bridge'>
- <vlan trunk='yes'>
- <tag id='42'/>
- <tag id='123' nativeMode='untagged'/>
- </vlan>
- ...
- </interface>
- </devices>
- ...
-
-If (and only if) the network connection used by the guest supports VLAN tagging
-transparent to the guest, an optional ``<vlan>`` element can specify one or more
-VLAN tags to apply to the guest's network traffic :since:`Since 0.10.0` .
-Network connections that support guest-transparent VLAN tagging include 1)
-type='bridge' interfaces connected to an Open vSwitch bridge :since:`Since
-0.10.0` , 2) SRIOV Virtual Functions (VF) used via type='hostdev' (direct device
-assignment) :since:`Since 0.10.0` , and 3) SRIOV VFs used via type='direct' with
-mode='passthrough' (macvtap "passthru" mode) :since:`Since 1.3.5` . All other
-connection types, including standard linux bridges and libvirt's own virtual
-networks, **do not** support it. 802.1Qbh (vn-link) and 802.1Qbg (VEPA) switches
-provide their own way (outside of libvirt) to tag guest traffic onto a specific
-VLAN. Each tag is given in a separate ``<tag>`` subelement of ``<vlan>`` (for
-example: ``<tag id='42'/>``). For VLAN trunking of multiple tags (which is
-supported only on Open vSwitch connections), multiple ``<tag>`` subelements can
-be specified, which implies that the user wants to do VLAN trunking on the
-interface for all the specified tags. In the case that VLAN trunking of a single
-tag is desired, the optional attribute ``trunk='yes'`` can be added to the
-toplevel ``<vlan>`` element to differentiate trunking of a single tag from
-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
-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
-be the "native" VLAN for this interface, and the ``nativeMode`` attribute
-determines whether or not traffic for that VLAN will be tagged.
-
-:anchor:`<a id="elementPort"/>`
-
-Isolating guests's network traffic from each other
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <port isolated='yes'/>
- </interface>
- </devices>
- ...
-
-: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
-emulated interface devices that use a standard tap device to connect to the
-network via a Linux host bridge. This property can be inherited from a libvirt
-network, so if all guests that will be connected to the network should be
-isolated, it is better to put the setting in the network configuration. (NB:
-this only prevents guests that have ``isolated='yes'`` from communicating with
-each other; if there is a guest on the same bridge that doesn't have
-``isolated='yes'``, even the isolated guests will be able to communicate with
-it.)
-
-:anchor:`<a id="elementLink"/>`
-
-Modifying virtual link state
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <target dev='vnet0'/>
- <link state='down'/>
- </interface>
- </devices>
- ...
-
-This element provides means of setting state of the virtual network link.
-Possible values for attribute ``state`` are ``up`` and ``down``. If ``down`` is
-specified as the value, the interface behaves as if it had the network cable
-disconnected. Default behavior if this element is unspecified is to have the
-link state ``up``. :since:`Since 0.9.5`
-
-:anchor:`<a id="mtu"/>`
-
-MTU configuration
-^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <target dev='vnet0'/>
- <mtu size='1500'/>
- </interface>
- </devices>
- ...
-
-This element provides means of setting MTU of the virtual network link.
-Currently there is just one attribute ``size`` which accepts a non-negative
-integer which specifies the MTU size for the interface. :since:`Since 3.1.0`
-
-:anchor:`<a id="coalesce"/>`
-
-Coalesce settings
-^^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <target dev='vnet0'/>
- <coalesce>
- <rx>
- <frames max='7'/>
- </rx>
- </coalesce>
- </interface>
- </devices>
- ...
-
-This element provides means of setting coalesce settings for some interface
-devices (currently only type ``network`` and ``bridge``. Currently there is just
-one attribute, ``max``, to tweak, in element ``frames`` for the ``rx`` group,
-which accepts a non-negative integer that specifies the maximum number of
-packets that will be received before an interrupt. :since:`Since 3.3.0`
-
-:anchor:`<a id="ipconfig"/>`
-
-IP configuration
-^^^^^^^^^^^^^^^^
-
-::
-
- ...
- <devices>
- <interface type='network'>
- <source network='default'/>
- <target dev='vnet0'/>
- <ip address='192.168.122.5' prefix='24'/>
- <ip address='192.168.122.5' prefix='24' peer='10.0.0.10'/>
- <route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/>
- <route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/>
- </interface>
- ...
- <hostdev mode='capabilities' type='net'>
- <source>
- <interface>eth0</interface>
- </source>
- <ip address='192.168.122.6' prefix='24'/>
- <route family='ipv4' address='192.168.122.0' prefix='24' gateway='192.168.122.1'/>
- <route family='ipv4' address='192.168.122.8' gateway='192.168.122.1'/>
- </hostdev>
- ...
- </devices>
- ...
-
-:since:`Since 1.2.12` network devices and hostdev devices with network
-capabilities can optionally be provided one or more IP addresses to set on the
-network device in the guest. Note that some hypervisors or network device types
-will simply ignore them or only use the first one. The ``family`` attribute can
-be set to either ``ipv4`` or ``ipv6``, and the ``address`` attribute contains
-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
-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)` .
-
-: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
-documentation for the ``route`` element in `network
-definitions <formatnetwork.html#elementsStaticroute>`__. This is used by the LXC
-driver.
-
-::
-
- ...
- <devices>
- <interface type='ethernet'>
- <source/>
- <ip address='192.168.123.1' prefix='24'/>
- <ip address='10.0.0.10' prefix='24' peer='192.168.122.5'/>
- <route family='ipv4' address='192.168.42.0' prefix='24' gateway='192.168.123.4'/>
- <source/>
- ...
- </interface>
- ...
- </devices>
- ...
-
-:since:`Since 2.1.0` network devices of type "ethernet" can optionally be
-provided one or more IP addresses and one or more routes to set on the **host**
-side of the network device. These are configured as subelements of the
-``<source>`` element of the interface, and have the same attributes as the
-similarly named elements used to configure the guest side of the interface
-(described above).
-
-:anchor:`<a id="elementVhostuser"/>`
-
-vhost-user interface
-^^^^^^^^^^^^^^^^^^^^
-
-:since:`Since 1.2.7` the vhost-user enables the communication between a QEMU
-virtual machine and other userspace process using the Virtio transport protocol.
-A char dev (e.g. Unix socket) is used for the control plane, while the data
-plane is based on shared memory.
-
-::
-
- ...
- <devices>
- <interface type='vhostuser'>
- <mac address='52:54:00:3b:83:1a'/>
- <source type='unix' path='/tmp/vhost1.sock' mode='server'/>
- <model type='virtio'/>
- </interface>
- <interface type='vhostuser'>
- <mac address='52:54:00:3b:83:1b'/>
- <source type='unix' path='/tmp/vhost2.sock' mode='client'>
- <reconnect enabled='yes' timeout='10'/>
- </source>
- <model type='virtio'/>
- <driver queues='5'/>
- </interface>
- </devices>
- ...
-
-The ``<source>`` element has to be specified along with the type of char device.
-Currently, only type='unix' is supported, where the path (the directory path of
-the socket) and mode attributes are required. Both ``mode='server'`` and
-``mode='client'`` are supported. vhost-user requires the virtio model type, thus
-the ``<model>`` element is mandatory. :since:`Since 4.1.0` the element has an
-optional child element ``reconnect`` which configures reconnect timeout if the
-connection is lost. It has two attributes ``enabled`` (which accepts ``yes`` and
-``no``) and ``timeout`` which specifies the amount of seconds after which
-hypervisor tries to reconnect.
-
-:anchor:`<a id="elementNwfilter"/>`
-
-Traffic filtering with NWFilter
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-:since:`Since 0.8.0` an ``nwfilter`` profile can be assigned to a domain
-interface, which allows configuring traffic filter rules for the virtual
-machine. See the `nwfilter <formatnwfilter.html>`__ documentation for more
-complete details.
-
-::
-
- ...
- <devices>
- <interface ...>
- ...
- <filterref filter='clean-traffic'/>
- </interface>
- <interface ...>
- ...
- <filterref filter='myfilter'>
- <parameter name='IP' value='104.207.129.11'/>
- <parameter name='IP6_ADDR' value='2001:19f0:300:2102::'/>
- <parameter name='IP6_MASK' value='64'/>
- ...
- </filterref>
- </interface>
- </devices>
- ...
-
-The ``filter`` attribute specifies the name of the nwfilter to use. Optional
-``<parameter>`` elements may be specified for passing additional info to the
-nwfilter via the ``name`` and ``value`` attributes. See the
-`nwfilter <formatnwfilter.html#nwfconceptsvars>`__ docs for info on parameters.
-
-:anchor:`<a id="elementsInput"/>`
-
-Input devices
-~~~~~~~~~~~~~
-
-Input devices allow interaction with the graphical framebuffer in the guest
-virtual machine. When enabling the framebuffer, an input device is automatically
-provided. It may be possible to add additional devices explicitly, for example,
-to provide a graphics tablet for absolute cursor movement.
-
-::
-
- ...
- <devices>
- <input type='mouse' bus='usb'/>
- <input type='keyboard' bus='usb'/>
- <input type='mouse' bus='virtio'/>
- <input type='keyboard' bus='virtio'/>
- <input type='tablet' bus='virtio'/>
- <input type='passthrough' bus='virtio'>
- <source evdev='/dev/input/event1'/>
- </input>
- </devices>
- ...
-
-``input``
- The ``input`` element has one mandatory attribute, the ``type`` whose value
- can be 'mouse', 'tablet', ( :since:`since 1.2.2` ) 'keyboard' or (
- :since:`since 1.3.0` ) 'passthrough'. The tablet provides absolute cursor
- movement, while the mouse uses relative movement. The optional ``bus``
- attribute can be used to refine the exact device type. It takes values "xen"
- (paravirtualized), "ps2" and "usb" or ( :since:`since 1.3.0` ) "virtio".
-
-The ``input`` element has an optional sub-element ``<address>`` which can tie
-the device to a particular PCI slot, `documented above <#elementsAddress>`__. On
-S390, ``address`` can be used to provide a CCW address for an input device (
-:since:`since 4.2.0` ). For type ``passthrough``, the mandatory sub-element
-``source`` must have an ``evdev`` attribute containing the absolute path to the
-event device passed through to guests. (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 <#elementsVirtioTransitional>`__ for more details.
-
-The subelement ``driver`` can be used to tune the virtio options of the device:
-`Virtio-specific options <#elementsVirtio>`__ can also be set. ( :since:`Since
-3.5.0` )
-
-:anchor:`<a id="elementsHub"/>`
-
-Hub devices
-~~~~~~~~~~~
-
-A hub is a device that expands a single port into several so that there are more
-ports available to connect devices to a host system.
-
-::
-
- ...
- <devices>
- <hub type='usb'/>
- </devices>
- ...
-
-``hub``
- The ``hub`` element has one mandatory attribute, the ``type`` whose value can
- only be 'usb'.
-
-The ``hub`` element has an optional sub-element ``<address>`` with
-``type='usb'``\ which can tie the device to a particular controller, `documented
-above <#elementsAddress>`__.
-
-:anchor:`<a id="elementsGraphics"/>`
-
-Graphical framebuffers
-~~~~~~~~~~~~~~~~~~~~~~
-
-A graphics device allows for graphical interaction with the guest OS. A guest
-will typically have either a framebuffer or a text console configured to allow
-interaction with the admin.
-
-::
-
- ...
- <devices>
- <graphics type='sdl' display=':0.0'/>
- <graphics type='vnc' port='5904' sharePolicy='allow-exclusive'>
- <listen type='address' address='1.2.3.4'/>
- </graphics>
- <graphics type='rdp' autoport='yes' multiUser='yes' />
- <graphics type='desktop' fullscreen='yes'/>
- <graphics type='spice'>
- <listen type='network' network='rednet'/>
- </graphics>
- </devices>
- ...
-
-``graphics``
- The ``graphics`` element has a mandatory ``type`` attribute which takes the
- value ``sdl``, ``vnc``, ``spice``, ``rdp``, ``desktop`` or ``egl-headless``:
-
- ``sdl``
- This displays a window on the host desktop, it can take 3 optional
- arguments: a ``display`` attribute for the display to use, an ``xauth``
- attribute for the authentication identifier, and an optional
- ``fullscreen`` attribute accepting values ``yes`` or ``no``.
-
- You can use a ``gl`` with the ``enable="yes"`` property to enable OpenGL
- support in SDL. Likewise you can explicitly disable OpenGL support with
- ``enable="no"``.
-
- ``vnc``
- Starts a VNC server. The ``port`` attribute specifies the TCP port number
- (with -1 as legacy syntax indicating that it should be auto-allocated).
- The ``autoport`` attribute is the new preferred syntax for indicating
- auto-allocation of the TCP port to use. The ``passwd`` attribute provides
- a VNC password in clear text. If the ``passwd`` attribute is set to an
- empty string, then VNC access is disabled. The ``keymap`` attribute
- specifies the keymap to use. It is possible to set a limit on the validity
- 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
- may not be supported by all hypervisors.
-
- The optional ``sharePolicy`` attribute specifies vnc server display
- sharing policy. ``allow-exclusive`` allows clients to ask for exclusive
- access by dropping other connections. Connecting multiple clients in
- parallel requires all clients asking for a shared session (vncviewer:
- -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` .
-
- Rather than using listen/port, QEMU supports a ``socket`` attribute for
- 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` .
-
- Although VNC doesn't support OpenGL natively, it can be paired with
- graphics type ``egl-headless`` (see below) which will instruct QEMU to
- open and use drm nodes for OpenGL rendering.
-
- ``spice`` :since:`Since 0.8.6`
- Starts a SPICE server. The ``port`` attribute specifies the TCP port
- number (with -1 as legacy syntax indicating that it should be
- auto-allocated), while ``tlsPort`` gives an alternative secure port
- number. The ``autoport`` attribute is the new preferred syntax for
- indicating auto-allocation of needed port numbers. The ``passwd``
- attribute provides a SPICE password in clear text. If the ``passwd``
- attribute is set to an empty string, then SPICE access is disabled. The
- ``keymap`` attribute specifies the keymap to use. It is possible to set a
- limit on the validity 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. SPICE accepts ``keep`` to keep client connected,
- ``disconnect`` to disconnect client and ``fail`` to fail changing password
- . NB, this may not be supported by all hypervisors. :since:`Since 0.9.3`
-
- The ``defaultMode`` attribute sets the default channel security policy,
- valid values are ``secure``, ``insecure`` and the default ``any`` (which
- is secure if possible, but falls back to insecure rather than erroring out
- if no secure path is available). :since:`Since 0.9.12`
-
- When SPICE has both a normal and TLS secured TCP port configured, it can
- be desirable to restrict what channels can be run on each port. This is
- achieved by adding one or more ``<channel>`` elements inside the main
- ``<graphics>`` element and setting the ``mode`` attribute to either
- ``secure`` or ``insecure``. Setting the mode attribute overrides the
- default value as set by the ``defaultMode`` attribute. (Note that
- specifying ``any`` as mode discards the entry as the channel would inherit
- the default mode anyways.) Valid channel names include ``main``,
- ``display``, ``inputs``, ``cursor``, ``playback``, ``record`` (all
- :since:` since 0.8.6` ); ``smartcard`` ( :since:`since 0.8.8` ); and
- ``usbredir`` ( :since:`since 0.9.12` ).
-
- ::
-
- <graphics type='spice' port='-1' tlsPort='-1' autoport='yes'>
- <channel name='main' mode='secure'/>
- <channel name='record' mode='insecure'/>
- <image compression='auto_glz'/>
- <streaming mode='filter'/>
- <clipboard copypaste='no'/>
- <mouse mode='client'/>
- <filetransfer enable='no'/>
- <gl enable='yes' rendernode='/dev/dri/by-path/pci-0000:00:02.0-render'/>
- </graphics>
-
- Spice supports variable compression settings for audio, images and
- streaming. These settings are accessible via the ``compression`` attribute
- in all following elements: ``image`` to set image compression (accepts
- ``auto_glz``, ``auto_lz``, ``quic``, ``glz``, ``lz``, ``off``), ``jpeg``
- for JPEG compression for images over wan (accepts ``auto``, ``never``,
- ``always``), ``zlib`` for configuring wan image compression (accepts
- ``auto``, ``never``, ``always``) and ``playback`` for enabling audio
- stream compression (accepts ``on`` or ``off``). :since:`Since 0.9.1`
-
- Streaming mode is set by the ``streaming`` element, settings its ``mode``
- attribute to one of ``filter``, ``all`` or ``off``. :since:`Since 0.9.2`
-
- Copy & Paste functionality (via Spice agent) is set by the ``clipboard``
- element. It is enabled by default, and can be disabled by setting the
- ``copypaste`` property to ``no``. :since:`Since 0.9.3`
-
- Mouse mode is set by the ``mouse`` element, setting its ``mode`` attribute
- to one of ``server`` or ``client``. If no mode is specified, the qemu
- default will be used (client mode). :since:`Since 0.9.11`
-
- File transfer functionality (via Spice agent) is set using the
- ``filetransfer`` element. It is enabled by default, and can be disabled by
- setting the ``enable`` property to ``no``. :since:`Since 1.2.2`
-
- Spice may provide accelerated server-side rendering with OpenGL. You can
- enable or disable OpenGL support explicitly with the ``gl`` element, by
- setting the ``enable`` property. (QEMU only, :since:`since 1.3.3` ). Note
- that this only works locally, since this requires usage of UNIX sockets,
- i.e. using ``listen`` types 'socket' or 'none'. For accelerated OpenGL
- with remote support, consider pairing this element with type
- ``egl-headless`` (see below). However, this will deliver weaker
- performance compared to native Spice OpenGL support.
-
- By default, QEMU will pick the first available GPU DRM render node. You
- may specify a DRM render node path to use instead. (QEMU only,
- :since:`since 3.1.0` ).
-
- ``rdp``
- Starts a RDP server. The ``port`` attribute specifies the TCP port number
- (with -1 as legacy syntax indicating that it should be auto-allocated).
- The ``autoport`` attribute is the new preferred syntax for indicating
- auto-allocation of the TCP port to use. In the VirtualBox driver, the
- ``autoport`` will make the hypervisor pick available port from 3389-3689
- range when the VM is started. The chosen port will be reflected in the
- ``port`` attribute. The ``multiUser`` attribute is a boolean deciding
- whether multiple simultaneous connections to the VM are permitted. The
- ``replaceUser`` attribute is a boolean deciding whether the existing
- connection must be dropped and a new connection must be established by the
- VRDP server, when a new client connects in single connection mode.
-
- ``desktop``
- This value is reserved for VirtualBox domains for the moment. It displays
- a window on the host desktop, similarly to "sdl", but using the VirtualBox
- viewer. Just like "sdl", it accepts the optional attributes ``display``
- and ``fullscreen``.
-
- ``egl-headless`` :since:`Since 4.6.0`
- This display type provides support for an OpenGL accelerated display
- accessible both locally and remotely (for comparison, Spice's native
- OpenGL support only works locally using UNIX sockets at the moment, but
- has better performance). Since this display type doesn't provide any
- window or graphical console like the other types, for practical reasons it
- should be paired with either ``vnc`` or ``spice`` graphics types. This
- display type is only supported by QEMU domains (needs QEMU :since:`2.10`
- or newer). :since:`5.0.0` this element accepts a ``<gl/>`` sub-element
- with an optional attribute ``rendernode`` which can be used to specify an
- absolute path to a host's DRI device to be used for OpenGL rendering.
-
- ::
-
- <graphics type='spice' autoport='yes'/>
- <graphics type='egl-headless'>
- <gl rendernode='/dev/dri/renderD128'/>
- </graphics>
-
-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:
-
-``address``
- Tells a graphics device to use an address specified in the ``address``
- attribute, which will contain either an IP address or hostname (which will be
- 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` .
-
- The ``address`` attribute is duplicated as ``listen`` attribute in
- ``graphics`` element for backward compatibility. If both are provided they
- must be equal.
-
-``network``
- This is used to specify an existing network in the ``network`` attribute from
- libvirt's list of configured networks. The named network configuration will
- be examined to determine an appropriate listen address and the address will
- be stored in live XML in ``address`` attribute. For example, if the network
- has an IPv4 address in its configuration (e.g. if it has a forward type of
- ``route``, ``nat``, or no forward type (isolated)), the first IPv4 address
- listed in the network's configuration will be used. If the network is
- describing a host bridge, the first IPv4 address associated with that bridge
- device will be used, and if the network is describing one of the 'direct'
- (macvtap) modes, the first IPv4 address of the first forward dev will be
- used.
-
-``socket`` :since:`since 2.0.0 (QEMU only)`
- This listen type tells a graphics server to listen on unix socket. Attribute
- ``socket`` contains a path to unix socket. If this attribute is omitted
- libvirt will generate this path for you. Supported by graphics type ``vnc``
- and ``spice``.
-
- For ``vnc`` graphics be backward compatible the ``socket`` attribute of first
- ``listen`` element is duplicated as ``socket`` attribute in ``graphics``
- element. If ``graphics`` element contains a ``socket`` attribute all
- ``listen`` elements are ignored.
-
-``none`` :since:`since 2.0.0 (QEMU only)`
- This listen type doesn't have any other attribute. Libvirt supports passing a
- file descriptor through our APIs virDomainOpenGraphics() and
- virDomainOpenGraphicsFD(). No other listen types are allowed if this one is
- used and the graphics device doesn't listen anywhere. You need to use one of
- the two APIs to pass a FD to QEMU in order to connect to this graphics
- device. Supported by graphics type ``vnc`` and ``spice``.
-
-:anchor:`<a id="elementsVideo"/>`
-
-Video devices
-~~~~~~~~~~~~~
-
-A video device.
-
-::
-
- ...
- <devices>
- <video>
- <model type='vga' vram='16384' heads='1'>
- <acceleration accel3d='yes' accel2d='yes'/>
- </model>
- <driver name='qemu'/>
- </video>
- </devices>
- ...
-
-``video``
- The ``video`` element is the container for describing video devices. For
- backwards compatibility, if no ``video`` is set but there is a ``graphics``
- in domain xml, then libvirt will add a default ``video`` according to the
- guest type.
-
- For a guest of type "kvm", the default ``video`` is: ``type`` with value
- "cirrus", ``vram`` with value "16384" and ``heads`` with value "1". By
- default, the first video device in domain xml is the primary one, but the
- optional attribute ``primary`` ( :since:`since 1.0.2` ) with value 'yes' can
- be used to mark the primary in cases of multiple video device. The
- non-primary must be type of "qxl" or ( :since:`since 2.4.0` ) "virtio".
-
-``model``
- The ``model`` element has a mandatory ``type`` attribute which takes the
- value "vga", "cirrus", "vmvga", "xen", "vbox", "qxl" ( :since:`since 0.8.6`
- ), "virtio" ( :since:`since 1.3.0` ), "gop" ( :since:`since 3.2.0` ), "bochs"
- ( :since:`since 5.6.0` ), "ramfb" ( :since:`since 5.9.0` ), or "none" (
- :since:`since 4.6.0` , depending on the hypervisor features available. The
- purpose of the type ``none`` is to instruct libvirt not to add a default
- video device in the guest (see the paragraph above). This legacy behaviour
- can be inconvenient in cases where GPU mediated devices are meant to be the
- only rendering device within a guest and so specifying another ``video``
- device along with type ``none``. Refer to Host device assignment to see how
- to add a mediated device into a guest.
-
- You can provide the amount of video memory in kibibytes (blocks of 1024
- bytes) using ``vram``. This is supported only for guest type of "vz", "qemu",
- "vbox", "vmx" and "xen". If no value is provided the default is used. If the
- size is not a power of two it will be rounded to closest one.
-
- The number of screen can be set using ``heads``. This is supported only for
- guests type of "vz", "kvm", "vbox" and "vmx".
-
- For guest type of "kvm" or "qemu" and model type "qxl" there are optional
- attributes. Attribute ``ram`` ( :since:` since 1.0.2` ) specifies the size of
- the primary bar, while the attribute ``vram`` specifies the secondary bar
- size. If ``ram`` or ``vram`` are not supplied a default value is used. The
- ``ram`` should also be rounded to power of two as ``vram``. There is also
- optional attribute ``vgamem`` ( :since:`since 1.2.11` ) to set the size of
- VGA framebuffer for fallback mode of QXL device. Attribute ``vram64`` (
- :since:`since 1.3.3` ) extends secondary bar and makes it addressable as
- 64bit memory.
-
- :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", and "virtio".
-
-``acceleration``
- Configure if video acceleration should be enabled.
-
- ``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
- :since:`since 1.3.0` )
- ``rendernode``
- Absolute path to a host's DRI device to be used for rendering (for
- 'vhostuser' driver only, :since:`since 5.8.0` ). If none is specified,
- libvirt will pick one available.
-
-``address``
- The optional ``address`` sub-element can be used to tie the video device to a
- particular PCI slot. On S390, ``address`` can be used to provide the CCW
- address for the video device ( :since:` since 4.2.0` ).
-``driver``
- The subelement ``driver`` can be used to tune the device:
-
- ``name``
- Specify the backend driver to use, either "qemu" or "vhostuser" depending
- on the hypervisor features available ( :since:`since 5.8.0` ). "qemu" is
- the default QEMU backend. "vhostuser" will use a separate vhost-user
- process backend (for ``virtio`` device).
- virtio options
- `Virtio-specific options <#elementsVirtio>`__ can also be set (
- :since:`Since 3.5.0` )
- VGA configuration
- Control how the video devices exposed to the guest using the ``vgaconf``
- attribute which takes the value "io", "on" or "off". At present, it's only
- applicable to the bhyve's "gop" video model type ( :since:`Since 3.5.0` )
-
-:anchor:`<a id="elementsConsole"/>`
-
-Consoles, serial, parallel & channel devices
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A character device provides a way to interact with the virtual machine.
-Paravirtualized consoles, serial ports, parallel ports and channels are all
-classed as character devices and so represented using the same syntax.
-
-::
-
- ...
- <devices>
- <parallel type='pty'>
- <source path='/dev/pts/2'/>
- <target port='0'/>
- </parallel>
- <serial type='pty'>
- <source path='/dev/pts/3'/>
- <target port='0'/>
- </serial>
- <serial type='file'>
- <source path='/tmp/file' append='on'>
- <seclabel model='dac' relabel='no'/>
- </source>
- <target port='0'/>
- </serial>
- <console type='pty'>
- <source path='/dev/pts/4'/>
- <target port='0'/>
- </console>
- <channel type='unix'>
- <source mode='bind' path='/tmp/guestfwd'/>
- <target type='guestfwd' address='10.0.2.1' port='4600'/>
- </channel>
- </devices>
- ...
-
-In each of these directives, the top-level element name (parallel, serial,
-console, channel) describes how the device is presented to the guest. The guest
-interface is configured by the ``target`` element.
-
-The interface presented to the host is given in the ``type`` attribute of the
-top-level element. The host interface is configured by the ``source`` element.
-
-The ``source`` element may contain an optional ``seclabel`` to override the way
-that labelling is done on the socket path. If this element is not present, the
-`security label is inherited from the per-domain setting <#seclabel>`__.
-
-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` .
-
-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` .
-
-::
-
- ...
- <log file="/var/log/libvirt/qemu/guestname-serial0.log" append="off"/>
- ...
-
-Each character device element has an optional sub-element ``<address>`` which
-can tie the device to a particular `controller <#elementsControllers>`__ or PCI
-slot.
-
-For character device with type ``unix`` or ``tcp`` the ``source`` has an
-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)` .
-
-:anchor:`<a id="elementsCharGuestInterface"/>`
-
-Guest interface
-^^^^^^^^^^^^^^^
-
-A character device presents itself to the guest as one of the following types.
-
-:anchor:`<a id="elementCharParallel"/>`
-
-Parallel port
-'''''''''''''
-
-::
-
- ...
- <devices>
- <parallel type='pty'>
- <source path='/dev/pts/2'/>
- <target port='0'/>
- </parallel>
- </devices>
- ...
-
-``target`` can have a ``port`` attribute, which specifies the port number. Ports
-are numbered starting from 0. There are usually 0, 1 or 2 parallel ports.
-
-:anchor:`<a id="elementCharSerial"/>`
-
-Serial port
-'''''''''''
-
-::
-
- ...
- <devices>
- <!-- Serial port -->
- <serial type='pty'>
- <source path='/dev/pts/3'/>
- <target port='0'/>
- </serial>
- </devices>
- ...
-
-::
-
- ...
- <devices>
- <!-- USB serial port -->
- <serial type='pty'>
- <target type='usb-serial' port='0'>
- <model name='usb-serial'/>
- </target>
- <address type='usb' bus='0' port='1'/>
- </serial>
- </devices>
- ...
-
-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),
-``usb-serial`` (usable whenever USB support is available) and ``pci-serial``
-(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) and
-``sclp-serial`` (usable with s390 and s390x guests) are available as well.
-
-: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
-``system-serial`` target type); ``sclpconsole`` and ``sclplmconsole`` (usable
-with the ``sclp-serial`` target type). Providing a target model is usually
-unnecessary: libvirt will automatically pick one that's suitable for the chosen
-target type, and overriding that value is generally not recommended.
-
-If any of the attributes is not specified by the user, libvirt will choose a
-value suitable for most users.
-
-Most target types support configuring the guest-visible device address as
-`documented above <#elementsAddress>`__; more specifically, acceptable address
-types are ``isa`` (for ``isa-serial``), ``usb`` (for ``usb-serial``), ``pci``
-(for ``pci-serial``) and ``spapr-vio`` (for ``spapr-vio-serial``). The
-``system-serial`` and ``sclp-serial`` target types don't support specifying an
-address.
-
-For the relationship between serial ports and consoles, `see
-below <#elementCharSerialAndConsole>`__.
-
-:anchor:`<a id="elementCharConsole"/>`
-
-Console
-'''''''
-
-::
-
- ...
- <devices>
- <!-- Serial console -->
- <console type='pty'>
- <source path='/dev/pts/2'/>
- <target type='serial' port='0'/>
- </console>
- </devices>
- ...
-
-::
-
- ...
- <devices>
- <!-- KVM virtio console -->
- <console type='pty'>
- <source path='/dev/pts/5'/>
- <target type='virtio' port='0'/>
- </console>
- </devices>
- ...
-
-The ``console`` element is used to represent interactive serial consoles.
-Depending on the type of guest in use and the specifics of the configuration,
-the ``console`` element might represent the same device as an existing
-``serial`` element or a separate device.
-
-A ``target`` subelement is supported and works the same way as with the
-``serial`` element (`see above <#elementCharSerial>`__ for details). Valid
-values for the ``type`` attribute are: ``serial`` (described below); ``virtio``
-(usable whenever VirtIO support is available); ``xen``, ``lxc`` and ``openvz``
-(available when the corresponding hypervisor is in use). ``sclp`` and ``sclplm``
-(usable for s390 and s390x QEMU guests) are supported for compatibility reasons
-but should not be used for new guests: use the ``sclpconsole`` and
-``sclplmconsole`` target models, respectively, with the ``serial`` element
-instead.
-
-Of the target types listed above, ``serial`` is special in that it doesn't
-represents a separate device, but rather the same device as the first ``serial``
-element. Due to this, there can only be a single ``console`` element with target
-type ``serial`` per guest.
-
-Virtio consoles are usually accessible as ``/dev/hvc[0-7]`` from inside the
-guest; for more information, see
-http://fedoraproject.org/wiki/Features/VirtioSerial. :since:`Since 0.8.3`
-
-For the relationship between serial ports and consoles, `see
-below <#elementCharSerialAndConsole>`__.
-
-:anchor:`<a id="elementCharSerialAndConsole"/>`
-
-Relationship between serial ports and consoles
-''''''''''''''''''''''''''''''''''''''''''''''
-
-Due to hystorical reasons, the ``serial`` and ``console`` elements have
-partially overlapping scopes.
-
-In general, both elements are used to configure one or more serial consoles to
-be used for interacting with the guest. The main difference between the two is
-that ``serial`` is used for emulated, usually native, serial consoles, whereas
-``console`` is used for paravirtualized ones.
-
-Both emulated and paravirtualized serial consoles have advantages and
-disadvantages:
-
-- emulated serial consoles are usually initialized much earlier than
- paravirtualized ones, so they can be used to control the bootloader and
- display both firmware and early boot messages;
-- on several platforms, there can only be a single emulated serial console per
- guest but paravirtualized consoles don't suffer from the same limitation.
-
-A configuration such as:
-
-::
-
- ...
- <devices>
- <console type='pty'>
- <target type='serial'/>
- </console>
- <console type='pty'>
- <target type='virtio'/>
- </console>
- </devices>
- ...
-
-will work on any platform and will result in one emulated serial console for
-early boot logging / interactive / recovery use, and one paravirtualized serial
-console to be used eg. as a side channel. Most people will be fine with having
-just the first ``console`` element in their configuration, but if a specific
-configuration is desired then both elements should be specified.
-
-Note that, due to the compatibility concerns mentioned earlier, all the
-following configurations:
-
-::
-
- ...
- <devices>
- <serial type='pty'/>
- </devices>
- ...
-
-::
-
- ...
- <devices>
- <console type='pty'/>
- </devices>
- ...
-
-::
-
- ...
- <devices>
- <serial type='pty'/>
- <console type='pty'/>
- </devices>
- ...
-
-will be treated the same and will result in a single emulated serial console
-being available to the guest.
-
-:anchor:`<a id="elementCharChannel"/>`
-
-Channel
-'''''''
-
-This represents a private communication channel between the host and the guest.
-
-::
-
- ...
- <devices>
- <channel type='unix'>
- <source mode='bind' path='/tmp/guestfwd'/>
- <target type='guestfwd' address='10.0.2.1' port='4600'/>
- </channel>
-
- <!-- KVM virtio channel -->
- <channel type='pty'>
- <target type='virtio' name='arbitrary.virtio.serial.port.name'/>
- </channel>
- <channel type='unix'>
- <source mode='bind' path='/var/lib/libvirt/qemu/f16x86_64.agent'/>
- <target type='virtio' name='org.qemu.guest_agent.0' state='connected'/>
- </channel>
- <channel type='spicevmc'>
- <target type='virtio' name='com.redhat.spice.0'/>
- </channel>
- </devices>
- ...
-
-This can be implemented in a variety of ways. The specific type of channel is
-given in the ``type`` attribute of the ``target`` element. Different channel
-types have different ``target`` attributes.
-
-``guestfwd``
- TCP traffic sent by the guest to a given IP address and port is forwarded to
- the channel device on the host. The ``target`` element must have ``address``
- and ``port`` attributes. :since:`Since 0.7.3`
-``virtio``
- Paravirtualized virtio channel. Channel is exposed in the guest under
- /dev/vport*, and if the optional element ``name`` is specified,
- /dev/virtio-ports/$name (for more info, please see
- http://fedoraproject.org/wiki/Features/VirtioSerial). The optional element
- ``address`` can tie the channel to a particular ``type='virtio-serial'``
- controller, `documented above <#elementsAddress>`__. With qemu, if ``name``
- is "org.qemu.guest_agent.0", then libvirt can interact with a guest agent
- installed in the guest, for actions such as guest shutdown or file system
- quiescing. :since:`Since 0.7.7, guest agent interaction since 0.9.10`
- Moreover, :since:`since 1.0.6` it is possible to have source path auto
- generated for virtio unix channels. This is very useful in case of a qemu
- guest agent, where users don't usually care about the source path since it's
- libvirt who talks to the guest agent. In case users want to utilize this
- feature, they should leave ``<source>`` element out. :since:`Since 1.2.11`
- the active XML for a virtio channel may contain an optional ``state``
- attribute that reflects whether a process in the guest is active on the
- channel. This is an output-only attribute. Possible values for the ``state``
- attribute are ``connected`` and ``disconnected``.
-``xen``
- Paravirtualized Xen channel. Channel is exposed in the guest as a Xen console
- but identified with a name. Setup and consumption of a Xen channel depends on
- software and configuration in the guest (for more info, please see
- http://xenbits.xen.org/docs/unstable/misc/channel.txt). Channel source path
- semantics are the same as the virtio target type. The ``state`` attribute is
- not supported since Xen channels lack the necessary probing mechanism.
- :since:`Since 2.3.0`
-``spicevmc``
- Paravirtualized SPICE channel. The domain must also have a SPICE server as a
- `graphics device <#elementsGraphics>`__, at which point the host piggy-backs
- messages across the ``main`` channel. The ``target`` element must be present,
- 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`
-
-:anchor:`<a id="elementsCharHostInterface"/>`
-
-Host interface
-^^^^^^^^^^^^^^
-
-A character device presents itself to the host as one of the following types.
-
-:anchor:`<a id="elementsCharSTDIO"/>`
-
-Domain logfile
-''''''''''''''
-
-This disables all input on the character device, and sends output into the
-virtual machine's logfile
-
-::
-
- ...
- <devices>
- <console type='stdio'>
- <target port='1'/>
- </console>
- </devices>
- ...
-
-:anchor:`<a id="elementsCharFle"/>`
-
-Device logfile
-''''''''''''''
-
-A file is opened and all data sent to the character device is written to the
-file.
-
-::
-
- ...
- <devices>
- <serial type="file">
- <source path="/var/log/vm/vm-serial.log"/>
- <target port="1"/>
- </serial>
- </devices>
- ...
-
-:anchor:`<a id="elementsCharVC"/>`
-
-Virtual console
-'''''''''''''''
-
-Connects the character device to the graphical framebuffer in a virtual console.
-This is typically accessed via a special hotkey sequence such as "ctrl+alt+3"
-
-::
-
- ...
- <devices>
- <serial type='vc'>
- <target port="1"/>
- </serial>
- </devices>
- ...
-
-:anchor:`<a id="elementsCharNull"/>`
-
-Null device
-'''''''''''
-
-Connects the character device to the void. No data is ever provided to the
-input. All data written is discarded.
-
-::
-
- ...
- <devices>
- <serial type='null'>
- <target port="1"/>
- </serial>
- </devices>
- ...
-
-:anchor:`<a id="elementsCharPTY"/>`
-
-Pseudo TTY
-''''''''''
-
-A Pseudo TTY is allocated using /dev/ptmx. A suitable client such as 'virsh
-console' can connect to interact with the serial port locally.
-
-::
-
- ...
- <devices>
- <serial type="pty">
- <source path="/dev/pts/3"/>
- <target port="1"/>
- </serial>
- </devices>
- ...
-
-NB special case if <console type='pty'>, then the TTY path is also duplicated as
-an attribute tty='/dev/pts/3' on the top level <console> tag. This provides
-compat with existing syntax for <console> tags.
-
-:anchor:`<a id="elementsCharHost"/>`
-
-Host device proxy
-'''''''''''''''''
-
-The character device is passed through to the underlying physical character
-device. The device types must match, eg the emulated serial port should only be
-connected to a host serial port - don't connect a serial port to a parallel
-port.
-
-::
-
- ...
- <devices>
- <serial type="dev">
- <source path="/dev/ttyS0"/>
- <target port="1"/>
- </serial>
- </devices>
- ...
-
-:anchor:`<a id="elementsCharPipe"/>`
-
-Named pipe
-''''''''''
-
-The character device writes output to a named pipe. See pipe(7) for more info.
-
-::
-
- ...
- <devices>
- <serial type="pipe">
- <source path="/tmp/mypipe"/>
- <target port="1"/>
- </serial>
- </devices>
- ...
-
-:anchor:`<a id="elementsCharTCP"/>`
-
-TCP client/server
-'''''''''''''''''
-
-The character device acts as a TCP client connecting to a remote server.
-
-::
-
- ...
- <devices>
- <serial type="tcp">
- <source mode="connect" host="0.0.0.0" service="2445"/>
- <protocol type="raw"/>
- <target port="1"/>
- </serial>
- </devices>
- ...
-
-Or as a TCP server waiting for a client connection.
-
-::
-
- ...
- <devices>
- <serial type="tcp">
- <source mode="bind" host="127.0.0.1" service="2445"/>
- <protocol type="raw"/>
- <target port="1"/>
- </serial>
- </devices>
- ...
-
-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
-telnet) or ``tls`` (via secure sockets layer) as the transport protocol for
-connections.
-
-::
-
- ...
- <devices>
- <serial type="tcp">
- <source mode="connect" host="0.0.0.0" service="2445"/>
- <protocol type="telnet"/>
- <target port="1"/>
- </serial>
- ...
- <serial type="tcp">
- <source mode="bind" host="127.0.0.1" service="2445"/>
- <protocol type="telnet"/>
- <target port="1"/>
- </serial>
- </devices>
- ...
-
-: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
-on the host by the ``chardev_tls`` and ``chardev_tls_x509_cert_dir`` or
-``default_tls_x509_cert_dir`` settings in the file /etc/libvirt/qemu.conf. If
-``chardev_tls`` is enabled, then unless the ``tls`` attribute is set to "no",
-libvirt will use the host configured TLS environment. If ``chardev_tls`` is
-disabled, but the ``tls`` attribute is set to "yes", then libvirt will attempt
-to use the host TLS environment if either the ``chardev_tls_x509_cert_dir`` or
-``default_tls_x509_cert_dir`` TLS directory structure exists.
-
-::
-
- ...
- <devices>
- <serial type="tcp">
- <source mode='connect' host="127.0.0.1" service="5555" tls="yes"/>
- <protocol type="raw"/>
- <target port="0"/>
- </serial>
- </devices>
- ...
-
-:anchor:`<a id="elementsCharUDP"/>`
-
-UDP network console
-'''''''''''''''''''
-
-The character device acts as a UDP netconsole service, sending and receiving
-packets. This is a lossy service.
-
-::
-
- ...
- <devices>
- <serial type="udp">
- <source mode="bind" host="0.0.0.0" service="2445"/>
- <source mode="connect" host="0.0.0.0" service="2445"/>
- <target port="1"/>
- </serial>
- </devices>
- ...
-
-:anchor:`<a id="elementsCharUNIX"/>`
-
-UNIX domain socket client/server
-''''''''''''''''''''''''''''''''
-
-The character device acts as a UNIX domain socket server, accepting connections
-from local clients.
-
-::
-
- ...
- <devices>
- <serial type="unix">
- <source mode="bind" path="/tmp/foo"/>
- <target port="1"/>
- </serial>
- </devices>
- ...
-
-:anchor:`<a id="elementsCharSpiceport"/>`
-
-Spice channel
-'''''''''''''
-
-The character device is accessible through spice connection under a channel name
-specified in the ``channel`` attribute. :since:`Since 1.2.2`
-
-Note: depending on the hypervisor, spiceports might (or might not) be enabled on
-domains with or without `spice graphics <#elementsGraphics>`__.
-
-::
-
- ...
- <devices>
- <serial type="spiceport">
- <source channel="org.qemu.console.serial.0"/>
- <target port="1"/>
- </serial>
- </devices>
- ...
-
-:anchor:`<a id="elementsNmdm"/>`
-
-Nmdm device
-'''''''''''
-
-The nmdm device driver, available on FreeBSD, provides two tty devices connected
-together by a virtual null modem cable. :since:`Since 1.2.4`
-
-::
-
- ...
- <devices>
- <serial type="nmdm">
- <source master="/dev/nmdm0A" slave="/dev/nmdm0B"/>
- </serial>
- </devices>
- ...
-
-The ``source`` element has these attributes:
-
-``master``
- Master device of the pair, that is passed to the hypervisor. Device is
- specified by a fully qualified path.
-``slave``
- Slave device of the pair, that is passed to the clients for connection to the
- guest console. Device is specified by a fully qualified path.
-
-:anchor:`<a id="elementsSound"/>`
-
-Sound devices
-~~~~~~~~~~~~~
-
-A virtual sound card can be attached to the host via the ``sound`` element.
-:since:`Since 0.4.3`
-
-::
-
- ...
- <devices>
- <sound model='es1370'/>
- </devices>
- ...
-
-``sound``
- The ``sound`` element has one mandatory attribute, ``model``, which specifies
- what real sound device is emulated. Valid values are specific to the
- underlying hypervisor, though typical choices are 'es1370', 'sb16', 'ac97',
- 'ich6' and 'usb'. ( :since:` 'ac97' only since 0.6.0, 'ich6' only since
- 0.8.8, 'usb' only since 1.2.7` )
-
-:since:`Since 0.9.13` , a sound element with ``ich6`` model 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.
-
-Valid values are:
-
-- 'duplex' - advertise a line-in and a line-out
-- 'micro' - advertise a speaker and a microphone
-- 'output' - advertise a line-out :since:`Since 4.4.0`
-
-::
-
- ...
- <devices>
- <sound model='ich6'>
- <codec type='micro'/>
- </sound>
- </devices>
- ...
-
-Each ``sound`` element has an optional sub-element ``<address>`` which can tie
-the device to a particular PCI slot, `documented above <#elementsAddress>`__.
-
-:anchor:`<a id="elementsWatchdog"/>`
-
-Watchdog device
-~~~~~~~~~~~~~~~
-
-A virtual hardware watchdog device can be added to the guest via the
-``watchdog`` element. :since:`Since 0.7.3, QEMU and KVM only`
-
-The watchdog device requires an additional driver and management daemon in the
-guest. Just enabling the watchdog in the libvirt configuration does not do
-anything useful on its own.
-
-Currently libvirt does not support notification when the watchdog fires. This
-feature is planned for a future version of libvirt.
-
-::
-
- ...
- <devices>
- <watchdog model='i6300esb'/>
- </devices>
- ...
-
-::
-
- ...
- <devices>
- <watchdog model='i6300esb' action='poweroff'/>
- </devices>
- </domain>
-
-``model``
- The required ``model`` attribute specifies what real watchdog device is
- emulated. Valid values are specific to the underlying hypervisor.
-
- QEMU and KVM support:
-
- - 'i6300esb' - the recommended device, emulating a PCI Intel 6300ESB
- - 'ib700' - emulating an ISA iBase IB700
- - 'diag288' - emulating an S390 DIAG288 device :since:`Since 1.2.17`
-
-``action``
- The optional ``action`` attribute describes what action to take when the
- watchdog expires. Valid values are specific to the underlying hypervisor.
-
- QEMU and KVM support:
-
- - 'reset' - default, forcefully reset the guest
- - 'shutdown' - gracefully shutdown the guest (not recommended)
- - 'poweroff' - forcefully power off the guest
- - 'pause' - pause the guest
- - 'none' - do nothing
- - 'dump' - automatically dump the guest :since:`Since 0.8.7`
- - 'inject-nmi' - inject a non-maskable interrupt into the guest
- :since:`Since 1.2.17`
-
- Note 1: the 'shutdown' action requires that the guest is responsive to ACPI
- signals. In the sort of situations where the watchdog has expired, guests are
- usually unable to respond to ACPI signals. Therefore using 'shutdown' is not
- recommended.
-
- Note 2: the directory to save dump files can be configured by
- ``auto_dump_path`` in file /etc/libvirt/qemu.conf.
-
-:anchor:`<a id="elementsMemBalloon"/>`
-
-Memory balloon device
-~~~~~~~~~~~~~~~~~~~~~
-
-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
-needs to be explicitly disabled, ``model='none'`` may be used.
-
-Example: automatically added device with KVM
-
-::
-
- ...
- <devices>
- <memballoon model='virtio'/>
- </devices>
- ...
-
-Example: manually added device with static PCI slot 2 requested
-
-::
-
- ...
- <devices>
- <memballoon model='virtio'>
- <address type='pci' domain='0x0000' bus='0x00' slot='0x02' function='0x0'/>
- <stats period='10'/>
- <driver iommu='on' ats='on'/>
- </memballoon>
- </devices>
- </domain>
-
-``model``
- The required ``model`` attribute specifies what type of balloon device is
- provided. Valid values are specific to the virtualization platform
-
- - 'virtio' - default with QEMU/KVM
- - 'virtio-transitional' :since:`Since 5.2.0`
- - 'virtio-non-transitional' :since:`Since 5.2.0`
- - 'xen' - default with Xen
-
- See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more
- details.
-
-``autodeflate``
- The optional ``autodeflate`` attribute allows to enable/disable (values
- "on"/"off", respectively) the ability of the QEMU virtio memory balloon to
- release some memory at the last moment before a guest's process get killed by
- Out of Memory killer. :since:`Since 1.3.1, QEMU and KVM only`
-
-``period``
- The optional ``period`` allows the QEMU virtio memory balloon driver to
- provide statistics through the ``virsh dommemstat [domain]``
- command. By default, collection is not enabled. In order to enable, use the
- ``virsh dommemstat [domain] --period [number]`` command or
- ``virsh edit`` command to add the option to the XML definition. The
- ``virsh dommemstat`` will accept the options ``--live``, ``--current``, or
- ``--config``. If an option is not provided, the change for a running domain
- will only be made to the active guest. If the QEMU driver is not at the right
- revision, the attempt to set the period will fail. Large values (e.g. many
- years) might be ignored. :since:`Since 1.1.1, requires QEMU 1.5`
-
-``driver``
- For model ``virtio`` memballoon, `Virtio-specific
- options <#elementsVirtio>`__ can also be set. ( :since:`Since 3.5.0` )
-
-:anchor:`<a id="elementsRng"/>`
-
-Random number generator device
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The virtual random number generator device allows the host to pass through
-entropy to guest operating systems. :since:`Since 1.0.3`
-
-Example: usage of the RNG device:
-
-::
-
- ...
- <devices>
- <rng model='virtio'>
- <rate period="2000" bytes="1234"/>
- <backend model='random'>/dev/random</backend>
- <!-- OR -->
- <backend model='egd' type='udp'>
- <source mode='bind' service='1234'/>
- <source mode='connect' host='1.2.3.4' service='1234'/>
- </backend>
- <!-- OR -->
- <backend model='builtin'/>
- </rng>
- </devices>
- ...
-
-``model``
- The required ``model`` attribute specifies what type of RNG device is
- provided. Valid values are specific to the virtualization platform:
-
- - 'virtio' - supported by qemu and virtio-rng kernel module
- - 'virtio-transitional' :since:`Since 5.2.0`
- - 'virtio-non-transitional' :since:`Since 5.2.0`
-
- See `Virtio transitional devices <#elementsVirtioTransitional>`__ for more
- details.
-
-``rate``
- The optional ``rate`` element allows limiting the rate at which entropy can
- be consumed from the source. The mandatory attribute ``bytes`` specifies how
- many bytes are permitted to be consumed per period. An optional ``period``
- attribute specifies the duration of a period in milliseconds; if omitted, the
- period is taken as 1000 milliseconds (1 second). :since:`Since 1.0.4`
-
-``backend``
- The ``backend`` element specifies the source of entropy to be used for the
- domain. The source model is configured using the ``model`` attribute.
- Supported source models are:
-
- ``random``
- This backend type expects a non-blocking character device as input. The
- file name is specified as contents of the ``backend`` element.
- :since:`Since 1.3.4` any path is accepted. Before that ``/dev/random`` and
- ``/dev/hwrng`` were the only accepted paths. When no file name is
- specified, the hypervisor default is used. For QEMU, the default is
- ``/dev/random``. However, the recommended source of entropy is
- ``/dev/urandom`` (as it doesn't have the limitations of ``/dev/random``).
-
- ``egd``
- This backend connects to a source using the EGD protocol. The source is
- specified as a character device. Refer to `character device host
- interface <#elementsCharHostInterface>`__ for more information.
-
- ``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` )
-
-``driver``
- The subelement ``driver`` can be used to tune the device:
-
- virtio options
- `Virtio-specific options <#elementsVirtio>`__ can also be set. (
- :since:`Since 3.5.0` )
-
-:anchor:`<a id="elementsTpm"/>`
-
-TPM device
-~~~~~~~~~~
-
-The TPM device enables a QEMU guest to have access to TPM functionality. The TPM
-device may either be a TPM 1.2 or a TPM 2.0.
-
-The TPM passthrough device type provides access to the host's TPM for one QEMU
-guest. No other software may be using the TPM device, typically /dev/tpm0, at
-the time the QEMU guest is started. :since:`'passthrough' since 1.0.5`
-
-Example: usage of the TPM passthrough device
-
-::
-
- ...
- <devices>
- <tpm model='tpm-tis'>
- <backend type='passthrough'>
- <device path='/dev/tpm0'/>
- </backend>
- </tpm>
- </devices>
- ...
-
-The emulator device type gives access to a TPM emulator providing TPM
-functionality for each VM. QEMU talks to it over a Unix socket. With the
-emulator device type each guest gets its own private TPM. :since:`'emulator'
-since 4.5.0` The state of the TPM emulator can be encrypted by providing an
-``encryption`` element. :since:`'encryption' since 5.6.0`
-
-Example: usage of the TPM Emulator
-
-::
-
- ...
- <devices>
- <tpm model='tpm-tis'>
- <backend type='emulator' version='2.0'>
- <encryption secret='6dd3e4a5-1d76-44ce-961f-f119f5aad935'/>
- </backend>
- </tpm>
- </devices>
- ...
-
-``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
- 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
- ``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
- ``/dev/tpmrm0``, enabling the guest to run in secure virtual machine mode
- with the help of an Ultravisor. Adding a TPM Proxy to a pSeries guest brings
- no security benefits unless the guest is running on a PPC64 host that has an
- Ultravisor and a TPM Resource Manager. Only one TPM Proxy device is allowed
- per guest, but a TPM Proxy device can be added together with other TPM
- devices.
-
-``backend``
- The ``backend`` element specifies the type of TPM device. The following types
- are supported:
-
- ``passthrough``
- Use the host's TPM or TPM Resource Manager device.
-
- 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` ,
- when choosing the ``spapr-tpm-proxy`` model, the file name specified is
- expected to be a TPM Resource Manager device, e.g. ``/dev/tpmrm0``.
-
- ``emulator``
- For this backend type the 'swtpm' TPM Emulator must be installed on the
- host. Libvirt will automatically start an independent TPM emulator for
- each QEMU guest requesting access to it.
-
-``version``
- The ``version`` attribute indicates the version of the TPM. By default a TPM
- 1.2 is created. This attribute only works with the ``emulator`` backend. The
- following versions are supported:
-
- - '1.2' : creates a TPM 1.2
- - '2.0' : creates a TPM 2.0
-
-``encryption``
- The ``encryption`` element allows the state of a TPM emulator to be
- encrypted. The ``secret`` must reference a secret object that holds the
- passphrase from which the encryption key will be derived.
-
-:anchor:`<a id="elementsNVRAM"/>`
-
-NVRAM device
-~~~~~~~~~~~~
-
-nvram device is always added to pSeries guest on PPC64, and its address is
-allowed to be changed. Element ``nvram`` (only valid for pSeries guest,
-:since:`since 1.0.5` ) is provided to enable the address setting.
-
-Example: usage of NVRAM configuration
-
-::
-
- ...
- <devices>
- <nvram>
- <address type='spapr-vio' reg='0x00003000'/>
- </nvram>
- </devices>
- ...
-
-``spapr-vio``
- VIO device address type, only valid for PPC64.
-
-``reg``
- Device address
-
-:anchor:`<a id="elementsPanic"/>`
-
-panic device
-~~~~~~~~~~~~
-
-panic device enables libvirt to receive panic notification from a QEMU guest.
-:since:`Since 1.2.1, QEMU and KVM only`
-
-This feature is always enabled for:
-
-- pSeries guests, since it's implemented by the guest firmware
-- S390 guests, since it's an integral part of the S390 architecture
-
-For the guest types listed above, libvirt automatically adds a ``panic`` element
-to the domain XML.
-
-Example: usage of panic configuration
-
-::
-
- ...
- <devices>
- <panic model='hyperv'/>
- <panic model='isa'>
- <address type='isa' iobase='0x505'/>
- </panic>
- </devices>
- ...
-
-``model``
- The optional ``model`` attribute specifies what type of panic device is
- provided. The panic model used when this attribute is missing depends on the
- hypervisor and guest arch.
-
- - '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`
- - 's390' - default for S390 guests. :since:`Since 1.3.5`
-
-``address``
- address of panic. The default ioport is 0x505. Most users don't need to
- specify an address, and doing so is forbidden altogether for s390, pseries
- and hyperv models.
-
-:anchor:`<a id="elementsShmem"/>`
-
-Shared memory device
-~~~~~~~~~~~~~~~~~~~~
-
-A shared memory device allows to share a memory region between different virtual
-machines and the host. :since:`Since 1.2.10, QEMU and KVM only`
-
-::
-
- ...
- <devices>
- <shmem name='my_shmem0'>
- <model type='ivshmem-plain'/>
- <size unit='M'>4</size>
- </shmem>
- <shmem name='shmem_server'>
- <model type='ivshmem-doorbell'/>
- <size unit='M'>2</size>
- <server path='/tmp/socket-shmem'/>
- <msi vectors='32' ioeventfd='on'/>
- </shmem>
- </devices>
- ...
-
-``shmem``
- The ``shmem`` element has one mandatory attribute, ``name`` to identify the
- shared memory. This attribute cannot be directory specific to ``.`` or ``..``
- as well as it cannot involve path separator ``/``.
-``model``
- Attribute ``type`` of the optional element ``model`` specifies the model of
- the underlying device providing the ``shmem`` device. The models currently
- supported are ``ivshmem`` (supports both server and server-less shmem, but is
- deprecated by newer QEMU in favour of the -plain and -doorbell variants),
- ``ivshmem-plain`` (only for server-less shmem) and ``ivshmem-doorbell`` (only
- for shmem with the server).
-``size``
- The optional ``size`` element specifies the size of the shared memory. This
- must be power of 2 and greater than or equal to 1 MiB.
-``server``
- The optional ``server`` element can be used to configure a server socket the
- device is supposed to connect to. The optional ``path`` attribute specifies
- the absolute path to the unix socket and defaults to
- ``/var/lib/libvirt/shmem/$shmem-$name-sock``.
-``msi``
- The optional ``msi`` element enables/disables (values "on"/"off",
- respectively) MSI interrupts. This option can currently be used only together
- with the ``server`` element. The ``vectors`` attribute can be used to specify
- the number of interrupt vectors. The ``ioeventd`` attribute enables/disables
- (values "on"/"off", respectively) ioeventfd.
-
-:anchor:`<a id="elementsMemory"/>`
-
-Memory devices
-~~~~~~~~~~~~~~
-
-In addition to the initial memory assigned to the guest, memory devices allow
-additional memory to be assigned to the guest in the form of memory modules. A
-memory device can be hot-plugged or hot-unplugged depending on the guests'
-memory resource needs. Some hypervisors may require NUMA configured for the
-guest.
-
-Example: usage of the memory devices
-
-::
-
- ...
- <devices>
- <memory model='dimm' access='private' discard='yes'>
- <target>
- <size unit='KiB'>524287</size>
- <node>0</node>
- </target>
- </memory>
- <memory model='dimm'>
- <source>
- <pagesize unit='KiB'>4096</pagesize>
- <nodemask>1-3</nodemask>
- </source>
- <target>
- <size unit='KiB'>524287</size>
- <node>1</node>
- </target>
- </memory>
- <memory model='nvdimm'>
- <uuid>
- <source>
- <path>/tmp/nvdimm</path>
- </source>
- <target>
- <size unit='KiB'>524288</size>
- <node>1</node>
- <label>
- <size unit='KiB'>128</size>
- </label>
- <readonly/>
- </target>
- </memory>
- <memory model='nvdimm' access='shared'>
- <uuid>
- <source>
- <path>/dev/dax0.0</path>
- <alignsize unit='KiB'>2048</alignsize>
- <pmem/>
- </source>
- <target>
- <size unit='KiB'>524288</size>
- <node>1</node>
- <label>
- <size unit='KiB'>128</size>
- </label>
- </target>
- </memory>
- </devices>
- ...
-
-``model``
- Provide ``dimm`` to add a virtual DIMM module to the guest. :since:`Since
- 1.2.14` Provide ``nvdimm`` model adds a Non-Volatile DIMM module.
- :since:`Since 3.2.0`
-
-``access``
- An optional attribute ``access`` ( :since:`since 3.2.0` ) that provides
- capability to fine tune mapping of the memory on per module basis. Values are
- the same as `Memory Backing <#elementsMemoryBacking>`__: ``shared`` and
- ``private``. For ``nvdimm`` model, if using real NVDIMM DAX device as
- backend, ``shared`` is required.
-
-``discard``
- An optional attribute ``discard`` ( :since:`since 4.4.0` ) that provides
- capability to fine tune discard of data on per module basis. Accepted values
- are ``yes`` and ``no``. The feature is described here: `Memory
- Backing <#elementsMemoryBacking>`__. This attribute is allowed only for
- ``model='dimm'``.
-
-``uuid``
- For pSeries guests, an uuid can be set to identify the nvdimm module. If
- absent, libvirt will generate an uuid. automatically. This attribute is
- allowed only for ``model='nvdimm'`` for pSeries guests. :since:`Since 6.2.0`
-
-``source``
- For model ``dimm`` this element is optional and allows to fine tune the
- source of the memory used for the given memory device. If the element is not
- provided defaults configured via ``numatune`` are used. If ``dimm`` is
- provided, then the following optional elements can be provided as well:
-
- ``pagesize``
- This element can be used to override the default host page size used for
- backing the memory device. The configured value must correspond to a page
- size supported by the host.
-
- ``nodemask``
- This element can be used to override the default set of NUMA nodes where
- the memory would be allocated.
-
- For model ``nvdimm`` this element is mandatory. The mandatory child element
- ``path`` represents a path in the host that backs the nvdimm module in the
- guest. The following optional elements may be used:
-
- ``alignsize``
- The ``alignsize`` element defines the page size alignment used to mmap the
- address range for the backend ``path``. If not supplied the host page size
- is used. For example, to mmap a real NVDIMM device a 2M-aligned page may
- be required, and host page size is 4KB, then we need to set this element
- to 2MB. :since:`Since 5.0.0`
-
- ``pmem``
- If persistent memory is supported and enabled by the hypervisor in order
- to guarantee the persistence of writes to the vNVDIMM backend, then use
- the ``pmem`` element in order to utilize the feature. :since:`Since 5.0.0`
-
-``target``
- The mandatory ``target`` element configures the placement and sizing of the
- added memory from the perspective of the guest.
-
- The mandatory ``size`` subelement configures the size of the added memory as
- a scaled integer.
-
- The ``node`` subelement configures the guest NUMA node to attach the memory
- to. The element shall be used only if the guest has NUMA nodes configured.
-
- The following optional elements may be used:
-
- ``label``
- For NVDIMM type devices one can use ``label`` and its subelement ``size``
- to configure the size of namespaces label storage within the NVDIMM
- module. The ``size`` element has usual meaning described
- `here <#elementsMemoryAllocation>`__. ``label`` is mandatory for pSeries
- guests and optional for all other architectures. For QEMU domains the
- following restrictions apply:
-
- #. the minimum label size is 128KiB,
- #. the remaining size (total-size - label-size) will be aligned to 4KiB as
- default.
-
- ``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`
-
-:anchor:`<a id="elementsIommu"/>`
-
-IOMMU devices
-~~~~~~~~~~~~~
-
-The ``iommu`` element can be used to add an IOMMU device. :since:`Since 2.1.0`
-
-Example:
-
-::
-
- ...
- <devices>
- <iommu model='intel'>
- <driver intremap='on'/>
- </iommu>
- </devices>
- ...
-
-``model``
- Supported values are ``intel`` (for Q35 guests) and, :since:`since 5.5.0` ,
- ``smmuv3`` (for ARM virt guests).
-
-``driver``
- The ``driver`` subelement can be used to configure additional options, some
- of which might only be available for certain IOMMU models:
-
- ``intremap``
- The ``intremap`` attribute with possible values ``on`` and ``off`` can be
- used to turn on interrupt remapping, a part of the VT-d functionality.
- Currently this requires split I/O APIC (``<ioapic driver='qemu'/>``).
- :since:`Since 3.4.0` (QEMU/KVM only)
-
- ``caching_mode``
- The ``caching_mode`` attribute with possible values ``on`` and ``off`` can
- be used to turn on the VT-d caching mode (useful for assigned devices).
- :since:`Since 3.4.0` (QEMU/KVM only)
-
- ``eim``
- The ``eim`` attribute (with possible values ``on`` and ``off``) can be
- used to configure Extended Interrupt Mode. A q35 domain with split I/O
- APIC (as described in `hypervisor features <#elementsFeatures>`__), and
- both interrupt remapping and EIM turned on for the IOMMU, will be able to
- use more than 255 vCPUs. :since:`Since 3.4.0` (QEMU/KVM only)
-
- ``iotlb``
- The ``iotlb`` attribute with possible values ``on`` and ``off`` can be
- used to turn on the IOTLB used to cache address translation requests from
- devices. :since:`Since 3.5.0` (QEMU/KVM only)
-
- ``aw_bits``
- The ``aw_bits`` attribute can be used to set the address width to allow
- mapping larger iova addresses in the guest. :since:`Since 6.5.0` (QEMU/KVM
- only)
-
-:anchor:`<a id="vsock"/>`
-
-Vsock
------
-
-A vsock host/guest interface. The ``model`` attribute defaults to ``virtio``.
-:since:`Since 5.2.0` ``model`` can also be 'virtio-transitional' and
-'virtio-non-transitional', see `Virtio transitional
-devices <#elementsVirtioTransitional>`__ for more details. The optional
-attribute ``address`` of the ``cid`` element specifies the CID assigned to the
-guest. If the attribute ``auto`` is set to ``yes``, libvirt will assign a free
-CID automatically on domain startup. :since:`Since 4.4.0`
-
-::
-
- ...
- <devices>
- <vsock model='virtio'>
- <cid auto='no' address='3'/>
- </vsock>
- </devices>
- ...
+.. include:: formatdomain-devices.rst.in
:anchor:`<a id="seclabel"/>`
--
2.26.2
More information about the libvir-list
mailing list