[RFC PATCH 5/5] docs: formatdomain-devices: Split out split <disk>

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

 



Start splitting out part of <devices> into smaller sections.

Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
 docs/formatdomain-devices-disk.rst.in | 821 +++++++++++++++++++++++++
 docs/formatdomain-devices.rst.in      | 822 +-------------------------
 2 files changed, 822 insertions(+), 821 deletions(-)
 create mode 100644 docs/formatdomain-devices-disk.rst.in

diff --git a/docs/formatdomain-devices-disk.rst.in b/docs/formatdomain-devices-disk.rst.in
new file mode 100644
index 0000000000..557db4edec
--- /dev/null
+++ b/docs/formatdomain-devices-disk.rst.in
@@ -0,0 +1,821 @@
+: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.
diff --git a/docs/formatdomain-devices.rst.in b/docs/formatdomain-devices.rst.in
index 935794980c..c7cc190918 100644
--- a/docs/formatdomain-devices.rst.in
+++ b/docs/formatdomain-devices.rst.in
@@ -39,827 +39,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
      ...
    </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.
+.. include:: formatdomain-devices-disk.rst.in

 :anchor:`<a id="elementsFilesystems"/>`

-- 
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