[RFC PATCH 5/5] docs: formatdomain-devices: Split out split <disk>
Peter Krempa
pkrempa at redhat.com
Tue Jul 14 15:07:40 UTC 2020
Start splitting out part of <devices> into smaller sections.
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
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&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&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
More information about the libvir-list
mailing list