[RFC PATCH 4/5] docs: formatdomain: Split out <devices> section

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Start splitting the massive document into smaller pieces using the
.. include:: directive.

Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
 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&amp;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&amp;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





[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux