From nobody Mon Feb 9 01:22:01 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) client-ip=205.139.110.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1595510557; cv=none; d=zohomail.com; s=zohoarc; b=ethAi2AirEsR67GS+YRmPrO9aG261eeICNYeI737cWt+RAPyReCUgJ304J60BsW+2qXRhCxgB4NnxDeN+ba5vIgwwQM/RNVEAmZ+FUXHsbT2wJ7z4ymS9VthToxP8KblFvcsa286QD0MrS6s3sWDseCaqmUBXK8/y2rJsQCbeus= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1595510557; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=8YdNHvDVSqKmgJUl2GYaVomVQq0VFhYBie1jNTBDmT8=; b=UWuKVXSxYD9Npzdy/9mjh9+udo/EI8Jmm1dAZDgYvWgFBweVxFNaeGhKTPuq+6W66PZXnKtMxkk1qkjPqguEUN3NedpXAmXdD3rE+CQZaUAG6BkGyCPWv57p7gH1iv/TRhdRRpN5NMwqGvBIbWfs/RZKet6iq6IfE2sPJlkoO90= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [205.139.110.120]) by mx.zohomail.com with SMTPS id 1595510557305497.6094707302842; Thu, 23 Jul 2020 06:22:37 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-168-VotAsExqM-OGyDPoAjp-hQ-1; Thu, 23 Jul 2020 09:22:12 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id A85DDE929; Thu, 23 Jul 2020 13:22:06 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 83D6E5F7D8; Thu, 23 Jul 2020 13:22:06 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 52AF09A15A; Thu, 23 Jul 2020 13:22:06 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 06NDM5N2028479 for ; Thu, 23 Jul 2020 09:22:05 -0400 Received: by smtp.corp.redhat.com (Postfix) id 2BF401A922; Thu, 23 Jul 2020 13:22:05 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.37]) by smtp.corp.redhat.com (Postfix) with ESMTP id 06D911A91F for ; Thu, 23 Jul 2020 13:22:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1595510555; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=8YdNHvDVSqKmgJUl2GYaVomVQq0VFhYBie1jNTBDmT8=; b=JvzwDoC1d2AQeI6JCPIxR7gCFomA4xHqn+QiyHoCB3uwtFVBUHUFJ5Nu/XFBTnCB593hHI CXQkfaso5YfnLHX7ZUL/3ULzFn5CDWmbCd9WGlbTN5RbzoNi3FiQabYRK8NcW56OQzQMXo 5tDhxEWAQmIWKpPOcixvuMDfM/j15H0= X-MC-Unique: VotAsExqM-OGyDPoAjp-hQ-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 07/32] docs: formatdomain-devices: Split out Date: Thu, 23 Jul 2020 15:21:12 +0200 Message-Id: <664904b3d2faa8405e2641d91271dede35508eee.1595510131.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Start splitting out part of into smaller sections. Signed-off-by: Peter Krempa --- 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:`` + +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. + +:: + + ... + + + + + + + + + 10000000 + 400000 + 100000 + + + + ... + + + + ... + + + ... + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + somevalue + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + ... + +``disk`` + The ``disk`` element is the main container for describing disks and sup= ports + 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 sourc= e for + the disk. :since:`Since 0.0.3` + ``device`` + Indicates how the disk is to be exposed to the guest OS. Possible va= lues + for this attribute are "floppy", "disk", "cdrom", and "lun", default= ing to + "disk". + + Using "lun" ( :since:`since 0.9.10` ) is only valid when the ``type`= ` is + "block" or "network" for ``protocol=3D'iscsi'`` or when the ``type``= is + "volume" when using an iSCSI source ``pool`` for ``mode`` "host" or = as an + `NPIV `__ virtual Host= Bus + Adapter (vHBA) using a Fibre Channel storage pool. Configured in this + manner, the LUN behaves identically to "disk", except that generic S= CSI + commands from the guest are accepted and passed through to the physi= cal + device. Also note that device=3D'lun' will only be recognized for ac= tual raw + devices, but never for individual partitions or LVM partitions (in t= hose + cases, the kernel will reject the generic SCSI commands, making it + identical to device=3D'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:`S= ince + 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=3D'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, cur= rent + 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 "filter= ed" 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 b= oth + the snapshot and the data changes since the snapshot; "``external``"= will + separate the snapshot from the live data; and "``no``" means the dis= k will + not participate in snapshots. Read-only disks default to "``no``", w= hile + the default for other disks depends on the hypervisor's capabilities= . Some + hypervisors allow a per-snapshot choice as well, during `domain snap= shot + creation `__. Not all snapshot modes are suppor= ted; + 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`` attr= ibute + 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 dire= ctory + 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", "sheepdo= g", + "gluster", "vxhs", "http", "https", "ftp", ftps", or "tftp". + + For any ``protocol`` other than ``nbd`` an additional attribute ``na= me`` + 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 controll= ed 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 inc= lude 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 def= ault + 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 hyper= visor, + usage of a TLS environment can also be globally controlled on the ho= st 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. I= f 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 `__ (managed by libvirt) where the disk sou= rce + resides. Attribute ``volume`` specifies the name of storage volume + (managed by libvirt) used as the disk source. The value for the ``vo= lume`` + 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 `__ ``source`` element ``host`` attribute= as + the disk source to generate the libiscsi URI (e.g. + 'file=3Discsi://example.com:3260/iqn.2013-07.com.example:iscsi-pool/= 1'). + Using "host" as the ``mode`` value indicates to use the LUN's path a= s it + shows up on host (e.g. + 'file=3D/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. Current= ly, + only ``pci`` value is accepted. + ``managed`` + This attribute instructs libvirt to detach NVMe controller + automatically on domain startup (``yes``) or expect the controlle= r to + be detached by system administrator (``no``). + ``namespace`` + The namespace ID which should be assigned to the domain. Accordin= g to + NVMe standard, namespace numbers start from 1, including. + + The difference between ```` and ```` i= s 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 NVM= e 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 s= tack + is not involved (compared to passing say ``/dev/nvme0n1`` via + ```` and therefore lower latencies can be achie= ved. + + 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 th= at + source file. (NB, for "volume" type disk, ``seclabel`` is only valid wh= en 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 ``ho= st`` + element supports 4 attributes, viz. "name", "port", "transport" and + "socket", which specify the hostname, the port number, transport typ= e and + path to socket, respectively. The meaning of this element and the nu= mber + of the elements depend on the protocol attribute. + + =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + Protocol Meaning Num= ber of hosts Default port + =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + nbd a server running nbd-server onl= y one 10809 + iscsi an iSCSI server onl= y one 3260 + rbd monitor servers of RBD one= or more librados default + sheepdog one of the sheepdog servers (default is localhost:7000) zer= o 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 onl= y one 9999 + =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + + gluster supports "tcp", "rdma", "unix" as valid values for the trans= port + 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 specif= y an + internal snapshot name to be used as the source for storage protocol= s. + 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`` e= lement + provides the authentication credentials needed to access the source.= It + includes a mandatory attribute ``username``, which identifies the us= ername + to use during authentication, as well as a sub-element ``secret`` wi= th + mandatory attribute ``type``, to tie back to a `libvirt secret + object `__ that holds the actual password or other + credentials (the domain XML intentionally does not expose the passwo= rd, + only the reference to the object that does manage the password). Kno= wn + 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-eleme= nt of + the ``source`` element for encrypted storage sources. If present, + specifies how the storage source is encrypted See the `Storage + Encryption `__ page for more informati= on. + Note that the 'qcow' format of encryption is broken and thus is no l= onger + 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-ele= ment + 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 m= anages + any resources needed. When the persistent reservations are unmanaged= , then + the hypervisor acts as a client and the path to the server socket mu= st be + provided in the child element ``source``, which currently accepts on= ly the + following attributes: ``type`` with one value ``unix``, ``path`` pat= h 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 supporte= d 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 confi= guring + offset and size of either the location of the image format + (``slice type=3D'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 t= he SSL + transport parameters with this element. The ``verify`` attribute all= ows to + turn on or off SSL certificate validation. Supported values are ``ye= s`` + and ``no``. :since:`Since 6.2.0` + ``cookies`` + For ``http`` and ``https`` accessed storage it's possible to pass on= e 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 suppo= rt 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. Not= e 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: + + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D + mandatory fail if missing for any reason (the default) + requisite fail if missing on boot up, drop if missing on migrate/restor= e/revert + optional drop if missing at any start attempt + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D + + :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' t= he + guest will drop this disk. This feature doesn't support migration curre= ntly. + +``backingStore`` + This element describes the backing store used by the disk specified by + sibling ``source`` element. :since:`Since 1.2.4.` If the hypervisor dri= ver + does not support the + `backingStoreInput `__ ( + :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 ``backingSto= re`` + 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-contain= ed and + is not based on any backing store. For the detected backing chain infor= mation + to be accurate, the backing format must be correctly specified in the + metadata of each file of the chain (files created by libvirt satisfy th= is + 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 backi= ng + store, see disk type attribute above for more details and possible v= alues. + ``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 blo= ck + operations (such as via the ``virDomainBlockRebase`` API). For examp= le, + ``vda[2]`` refers to the backing store with ``index=3D'2'`` of the d= isk with + ``vda`` target. + + Moreover, ``backingStore`` supports the following sub-elements: + + ``format`` + The ``format`` element contains ``type`` attribute which specifies t= he + internal format of the backing store, such as ``raw`` or ``qcow2``. + ``source`` + This element has the same structure as the ``source`` element in ``d= isk``. + It specifies which file, device, or network location contains the da= ta 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 bl= ock + job operation, where the mirror location in the ``source`` sub-element = will + eventually have the same contents as the source, and with the file form= at 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 overa= ll + ``disk`` device element. The ``job`` attribute mentions which API start= ed the + operation ("copy" for the ``virDomainBlockRebase`` API, or "active-comm= it" + for the ``virDomainBlockCommit`` API), :since:`since 1.2.7` . The attri= bute + ``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 ``p= ivot`` + 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 out= put; + it is ignored on input. The ``source`` sub-element exists for all two-p= hase + 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, suc= h 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 op= tional + attribute ``tray`` indicates the tray status of the removable disks (i.= e. + CDROM or Floppy disk), the value can be either "open" or "closed", defa= ults + to "closed". NB, the value of ``tray`` could be updated while the domai= n is + running. The optional attribute ``removable`` sets the removable flag f= or 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 additio= nal + per-device I/O tuning, with values that can vary for each device (contr= ast + this to the ` <#elementsBlockTuning>`__ element, which appli= es + globally to the domain). Currently, the only tuning available is Block = I/O + throttling for qemu. This element has optional sub-elements; any sub-el= ement + 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 lim= it 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 lim= it 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_se= c``. + ``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 thro= ughput + 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 throt= tling + quota between multiple drives. This prevents end-users from circumve= nting + a hosting provider's throttling policy by splitting 1 large drive in= N + small drives and getting N times the normal throttling quota. Any na= me 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. On= ly + 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 du= ration + in seconds for the ``read_bytes_sec_max`` burst period. Only valid w= hen + 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. On= ly + 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 du= ration + in seconds for the ``total_iops_sec_max`` burst period. Only valid w= hen + the ``total_iops_sec_max`` is set. + ``read_iops_sec_max_length`` + The optional ``read_iops_sec_max_length`` element is the maximum dur= ation + in seconds for the ``read_iops_sec_max`` burst period. Only valid wh= en the + ``read_iops_sec_max`` is set. + ``write_iops_sec_max`` + The optional ``write_iops_sec_max_length`` element is the maximum du= ration + in seconds for the ``write_iops_sec_max`` burst period. Only valid w= hen + 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 t= o 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", "boch= s", + "qcow2", and "qed". + - The optional ``cache`` attribute controls the cache mechanism, possi= ble + values are "default", "none", "writethrough", "writeback", "directsy= nc" + (like "writethrough", but it bypasses the host page cache) and "unsa= fe" + (host may cache all disk io, and sync requests from guest are ignore= d). + :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" si= nce + 0.9.7` The default is left to the discretion of the hypervisor. Ther= e is + also an optional ``rerror_policy`` that controls behavior for read e= rrors + only. :since:`Since 0.9.7` . If no rerror_policy is given, error_pol= icy is + used for both read and write errors. If rerror_policy is given, it + overrides the ``error_policy`` for read errors. Also note that "enos= pace" + 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 `__= for + disk device. The default is left to the discretion of the hypervisor. + Accepted values are "on" and "off". Enabling this allows qemu to exe= cute + VM while a separate thread handles I/O. Typically guests experiencin= g high + system CPU utilization during I/O will benefit from this. On the oth= er + hand, on overloaded host it could increase guest I/O latency. + :since:`Since 0.9.3 (QEMU and KVM only)` **In general you should lea= ve + 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 "o= ff". + Copy-on-read avoids accessing the same backing file sectors repeated= ly 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 v= alues + 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 "o= n" if + ``discard`` is set to "ignore"). NB enabling the detection is a comp= ute + intensive operation, but can save file space and/or time on slow med= ia. + :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 m= ay be + assigned to the same IOThread and are numbered from 1 to the domain + iothreads value. Available for a disk device ``target`` configured t= o 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 queue= s 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 doma= in + (aka driver domain) hosting the disk. Use the ``name`` attribute to spe= cify + 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 ``loadpar= m`` + attribute is an 8 character string which can be queried by guests on S3= 90 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 <#elementsOSBIO= S>`__ + section. :since:`Since 0.8.8` +``encryption`` + Starting with :since:`libvirt 3.9.0` the ``encryption`` element is pref= erred + to be a sub-element of the ``source`` element. If present, specifies ho= w the + volume is encrypted using "qcow". See the `Storage + Encryption `__ 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=3D'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, mar= king 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 examp= le, it + may look like ``WD-WMAP9A966149``. 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 virtu= al + 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 ```` 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 req= uires + QEMU 0.1.3 and :since:`libvirt 0.9.7` . For a "drive" controller, addit= ional + 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 bot= h a + sub-element of ``disk`` and ``source``. The ``auth`` element was introd= uced + as a ``disk`` sub-element in :since:`libvirt 0.9.7.` +``geometry`` + The optional ``geometry`` element provides the ability to override geom= etry + 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 Lin= ux + this would be the value returned by the BLKSSZGET ioctl and describe= s the + smallest units for disk I/O. + ``physical_block_size`` + The physical block size the disk will report to the guest OS. For Li= nux + this would be the value returned by the BLKPBSZGET ioctl and describ= es 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` ... -:anchor:`` - -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. - -:: - - ... - - - - - - - - - 10000000 - 400000 - 100000 - - - - ... - - - - ... - - - ... - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - somevalue - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - ... - -``disk`` - The ``disk`` element is the main container for describing disks and sup= ports - 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 sourc= e for - the disk. :since:`Since 0.0.3` - ``device`` - Indicates how the disk is to be exposed to the guest OS. Possible va= lues - for this attribute are "floppy", "disk", "cdrom", and "lun", default= ing to - "disk". - - Using "lun" ( :since:`since 0.9.10` ) is only valid when the ``type`= ` is - "block" or "network" for ``protocol=3D'iscsi'`` or when the ``type``= is - "volume" when using an iSCSI source ``pool`` for ``mode`` "host" or = as an - `NPIV `__ virtual Host= Bus - Adapter (vHBA) using a Fibre Channel storage pool. Configured in this - manner, the LUN behaves identically to "disk", except that generic S= CSI - commands from the guest are accepted and passed through to the physi= cal - device. Also note that device=3D'lun' will only be recognized for ac= tual raw - devices, but never for individual partitions or LVM partitions (in t= hose - cases, the kernel will reject the generic SCSI commands, making it - identical to device=3D'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:`S= ince - 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=3D'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, cur= rent - 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 "filter= ed" 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 b= oth - the snapshot and the data changes since the snapshot; "``external``"= will - separate the snapshot from the live data; and "``no``" means the dis= k will - not participate in snapshots. Read-only disks default to "``no``", w= hile - the default for other disks depends on the hypervisor's capabilities= . Some - hypervisors allow a per-snapshot choice as well, during `domain snap= shot - creation `__. Not all snapshot modes are suppor= ted; - 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`` attr= ibute - 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 dire= ctory - 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", "sheepdo= g", - "gluster", "vxhs", "http", "https", "ftp", ftps", or "tftp". - - For any ``protocol`` other than ``nbd`` an additional attribute ``na= me`` - 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 controll= ed 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 inc= lude 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 def= ault - 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 hyper= visor, - usage of a TLS environment can also be globally controlled on the ho= st 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. I= f 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 `__ (managed by libvirt) where the disk sou= rce - resides. Attribute ``volume`` specifies the name of storage volume - (managed by libvirt) used as the disk source. The value for the ``vo= lume`` - 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 `__ ``source`` element ``host`` attribute= as - the disk source to generate the libiscsi URI (e.g. - 'file=3Discsi://example.com:3260/iqn.2013-07.com.example:iscsi-pool/= 1'). - Using "host" as the ``mode`` value indicates to use the LUN's path a= s it - shows up on host (e.g. - 'file=3D/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. Current= ly, - only ``pci`` value is accepted. - ``managed`` - This attribute instructs libvirt to detach NVMe controller - automatically on domain startup (``yes``) or expect the controlle= r to - be detached by system administrator (``no``). - ``namespace`` - The namespace ID which should be assigned to the domain. Accordin= g to - NVMe standard, namespace numbers start from 1, including. - - The difference between ```` and ```` i= s 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 NVM= e 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 s= tack - is not involved (compared to passing say ``/dev/nvme0n1`` via - ```` and therefore lower latencies can be achie= ved. - - 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 th= at - source file. (NB, for "volume" type disk, ``seclabel`` is only valid wh= en 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 ``ho= st`` - element supports 4 attributes, viz. "name", "port", "transport" and - "socket", which specify the hostname, the port number, transport typ= e and - path to socket, respectively. The meaning of this element and the nu= mber - of the elements depend on the protocol attribute. - - =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - Protocol Meaning Num= ber of hosts Default port - =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - nbd a server running nbd-server onl= y one 10809 - iscsi an iSCSI server onl= y one 3260 - rbd monitor servers of RBD one= or more librados default - sheepdog one of the sheepdog servers (default is localhost:7000) zer= o 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 onl= y one 9999 - =3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - - gluster supports "tcp", "rdma", "unix" as valid values for the trans= port - 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 specif= y an - internal snapshot name to be used as the source for storage protocol= s. - 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`` e= lement - provides the authentication credentials needed to access the source.= It - includes a mandatory attribute ``username``, which identifies the us= ername - to use during authentication, as well as a sub-element ``secret`` wi= th - mandatory attribute ``type``, to tie back to a `libvirt secret - object `__ that holds the actual password or other - credentials (the domain XML intentionally does not expose the passwo= rd, - only the reference to the object that does manage the password). Kno= wn - 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-eleme= nt of - the ``source`` element for encrypted storage sources. If present, - specifies how the storage source is encrypted See the `Storage - Encryption `__ page for more informati= on. - Note that the 'qcow' format of encryption is broken and thus is no l= onger - 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-ele= ment - 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 m= anages - any resources needed. When the persistent reservations are unmanaged= , then - the hypervisor acts as a client and the path to the server socket mu= st be - provided in the child element ``source``, which currently accepts on= ly the - following attributes: ``type`` with one value ``unix``, ``path`` pat= h 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 supporte= d 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 confi= guring - offset and size of either the location of the image format - (``slice type=3D'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 t= he SSL - transport parameters with this element. The ``verify`` attribute all= ows to - turn on or off SSL certificate validation. Supported values are ``ye= s`` - and ``no``. :since:`Since 6.2.0` - ``cookies`` - For ``http`` and ``https`` accessed storage it's possible to pass on= e 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 suppo= rt 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. Not= e 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: - - =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D - mandatory fail if missing for any reason (the default) - requisite fail if missing on boot up, drop if missing on migrate/restor= e/revert - optional drop if missing at any start attempt - =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D - - :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' t= he - guest will drop this disk. This feature doesn't support migration curre= ntly. - -``backingStore`` - This element describes the backing store used by the disk specified by - sibling ``source`` element. :since:`Since 1.2.4.` If the hypervisor dri= ver - does not support the - `backingStoreInput `__ ( - :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 ``backingSto= re`` - 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-contain= ed and - is not based on any backing store. For the detected backing chain infor= mation - to be accurate, the backing format must be correctly specified in the - metadata of each file of the chain (files created by libvirt satisfy th= is - 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 backi= ng - store, see disk type attribute above for more details and possible v= alues. - ``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 blo= ck - operations (such as via the ``virDomainBlockRebase`` API). For examp= le, - ``vda[2]`` refers to the backing store with ``index=3D'2'`` of the d= isk with - ``vda`` target. - - Moreover, ``backingStore`` supports the following sub-elements: - - ``format`` - The ``format`` element contains ``type`` attribute which specifies t= he - internal format of the backing store, such as ``raw`` or ``qcow2``. - ``source`` - This element has the same structure as the ``source`` element in ``d= isk``. - It specifies which file, device, or network location contains the da= ta 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 bl= ock - job operation, where the mirror location in the ``source`` sub-element = will - eventually have the same contents as the source, and with the file form= at 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 overa= ll - ``disk`` device element. The ``job`` attribute mentions which API start= ed the - operation ("copy" for the ``virDomainBlockRebase`` API, or "active-comm= it" - for the ``virDomainBlockCommit`` API), :since:`since 1.2.7` . The attri= bute - ``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 ``p= ivot`` - 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 out= put; - it is ignored on input. The ``source`` sub-element exists for all two-p= hase - 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, suc= h 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 op= tional - attribute ``tray`` indicates the tray status of the removable disks (i.= e. - CDROM or Floppy disk), the value can be either "open" or "closed", defa= ults - to "closed". NB, the value of ``tray`` could be updated while the domai= n is - running. The optional attribute ``removable`` sets the removable flag f= or 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 additio= nal - per-device I/O tuning, with values that can vary for each device (contr= ast - this to the ` <#elementsBlockTuning>`__ element, which appli= es - globally to the domain). Currently, the only tuning available is Block = I/O - throttling for qemu. This element has optional sub-elements; any sub-el= ement - 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 lim= it 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 lim= it 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_se= c``. - ``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 thro= ughput - 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 throt= tling - quota between multiple drives. This prevents end-users from circumve= nting - a hosting provider's throttling policy by splitting 1 large drive in= N - small drives and getting N times the normal throttling quota. Any na= me 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. On= ly - 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 du= ration - in seconds for the ``read_bytes_sec_max`` burst period. Only valid w= hen - 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. On= ly - 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 du= ration - in seconds for the ``total_iops_sec_max`` burst period. Only valid w= hen - the ``total_iops_sec_max`` is set. - ``read_iops_sec_max_length`` - The optional ``read_iops_sec_max_length`` element is the maximum dur= ation - in seconds for the ``read_iops_sec_max`` burst period. Only valid wh= en the - ``read_iops_sec_max`` is set. - ``write_iops_sec_max`` - The optional ``write_iops_sec_max_length`` element is the maximum du= ration - in seconds for the ``write_iops_sec_max`` burst period. Only valid w= hen - 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 t= o 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", "boch= s", - "qcow2", and "qed". - - The optional ``cache`` attribute controls the cache mechanism, possi= ble - values are "default", "none", "writethrough", "writeback", "directsy= nc" - (like "writethrough", but it bypasses the host page cache) and "unsa= fe" - (host may cache all disk io, and sync requests from guest are ignore= d). - :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" si= nce - 0.9.7` The default is left to the discretion of the hypervisor. Ther= e is - also an optional ``rerror_policy`` that controls behavior for read e= rrors - only. :since:`Since 0.9.7` . If no rerror_policy is given, error_pol= icy is - used for both read and write errors. If rerror_policy is given, it - overrides the ``error_policy`` for read errors. Also note that "enos= pace" - 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 `__= for - disk device. The default is left to the discretion of the hypervisor. - Accepted values are "on" and "off". Enabling this allows qemu to exe= cute - VM while a separate thread handles I/O. Typically guests experiencin= g high - system CPU utilization during I/O will benefit from this. On the oth= er - hand, on overloaded host it could increase guest I/O latency. - :since:`Since 0.9.3 (QEMU and KVM only)` **In general you should lea= ve - 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 "o= ff". - Copy-on-read avoids accessing the same backing file sectors repeated= ly 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 v= alues - 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 "o= n" if - ``discard`` is set to "ignore"). NB enabling the detection is a comp= ute - intensive operation, but can save file space and/or time on slow med= ia. - :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 m= ay be - assigned to the same IOThread and are numbered from 1 to the domain - iothreads value. Available for a disk device ``target`` configured t= o 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 queue= s 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 doma= in - (aka driver domain) hosting the disk. Use the ``name`` attribute to spe= cify - 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 ``loadpar= m`` - attribute is an 8 character string which can be queried by guests on S3= 90 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 <#elementsOSBIO= S>`__ - section. :since:`Since 0.8.8` -``encryption`` - Starting with :since:`libvirt 3.9.0` the ``encryption`` element is pref= erred - to be a sub-element of the ``source`` element. If present, specifies ho= w the - volume is encrypted using "qcow". See the `Storage - Encryption `__ 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=3D'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, mar= king 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 examp= le, it - may look like ``WD-WMAP9A966149``. 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 virtu= al - 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 ```` 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 req= uires - QEMU 0.1.3 and :since:`libvirt 0.9.7` . For a "drive" controller, addit= ional - 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 bot= h a - sub-element of ``disk`` and ``source``. The ``auth`` element was introd= uced - as a ``disk`` sub-element in :since:`libvirt 0.9.7.` -``geometry`` - The optional ``geometry`` element provides the ability to override geom= etry - 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 Lin= ux - this would be the value returned by the BLKSSZGET ioctl and describe= s the - smallest units for disk I/O. - ``physical_block_size`` - The physical block size the disk will report to the guest OS. For Li= nux - this would be the value returned by the BLKPBSZGET ioctl and describ= es the - disk's hardware sector size which can be relevant for the alignment = of - disk data. +.. include:: formatdomain-devices-disk.rst :anchor:`` 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 =3D [ { 'name': 'formatcheckpoint' }, { 'name': 'formatdomain', 'includes': [ 'formatdomain-devices.rst', + 'formatdomain-devices-disk.rst', ] }, { 'name': 'hacking' }, --=20 2.26.2