[PATCH 07/32] docs: formatdomain-devices: Split out <disk>

Start splitting out part of <devices> into smaller sections. Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/formatdomain-devices-disk.rst | 821 ++++++++++++++++++++++++++++ docs/formatdomain-devices.rst | 822 +---------------------------- docs/meson.build | 1 + 3 files changed, 823 insertions(+), 821 deletions(-) create mode 100644 docs/formatdomain-devices-disk.rst diff --git a/docs/formatdomain-devices-disk.rst b/docs/formatdomain-devices-disk.rst new file mode 100644 index 0000000000..557db4edec --- /dev/null +++ b/docs/formatdomain-devices-disk.rst @@ -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 b/docs/formatdomain-devices.rst index fef2bffef7..a004ad42f9 100644 --- a/docs/formatdomain-devices.rst +++ b/docs/formatdomain-devices.rst @@ -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 :anchor:`<a id="elementsFilesystems"/>` diff --git a/docs/meson.build b/docs/meson.build index 4c6f7179e5..fb9bd18ee3 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -124,6 +124,7 @@ docs_rst_files = [ { 'name': 'formatcheckpoint' }, { 'name': 'formatdomain', 'includes': [ 'formatdomain-devices.rst', + 'formatdomain-devices-disk.rst', ] }, { 'name': 'hacking' }, -- 2.26.2