From nobody Sat May 4 23:03:20 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 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=1639753509; cv=none; d=zohomail.com; s=zohoarc; b=CbVnQpdMulTcYGxKszmMNwJTHYzXCZayBdrL9FmXyQRXUGbBbB9eU+YFeTDeeITtFbANyKtKKCTiLCu6DDe7e/fOpDBArnIYYLuyS9+umH22gdp9Ek50/qWMOgmgVUgeQ645cfFkoIyJdrg9OVT1H87IxUlgfdHj+Jh9OdISevQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1639753509; 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=Yv1KyfcjUcQrLLMFyrC7HE/w3mND9Nm33Th1v8RU5rs=; b=dJC5ASj5BWc539ZTyqo1vIOVDkptcDdevtr7e1mDO2Fw09jAZzlfZWtJL9J31EWOxeB4X02LR4K4cHacuJiosrmtwBLhoykRBb1BkDgWqBjId8f1qijehKnPpz8ISVw1+k8YR2Vfy9Y/3JNzI5t2B1VShUTHf0yThNyEUXH69Nw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1639753509700941.2279974980815; Fri, 17 Dec 2021 07:05:09 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-669-EBXPNXF8N0ORu-kEBRMFUg-1; Fri, 17 Dec 2021 10:05:04 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 81643804152; Fri, 17 Dec 2021 15:04:57 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 586345BD1A; Fri, 17 Dec 2021 15:04:57 +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 267C01806D2B; Fri, 17 Dec 2021 15:04:56 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 1BHF4sYp025174 for ; Fri, 17 Dec 2021 10:04:54 -0500 Received: by smtp.corp.redhat.com (Postfix) id 2CACB5F939; Fri, 17 Dec 2021 15:04:54 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3FB235F91A for ; Fri, 17 Dec 2021 15:04:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1639753508; 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=Yv1KyfcjUcQrLLMFyrC7HE/w3mND9Nm33Th1v8RU5rs=; b=Fk/D8DAG0FVt1lF9mzOQ+j8VPAAG2bODJnLiT9+skJpKtgtamdGvYHXeQge7eO4hiJ5Vub FuJWa5ApJrKPDOlXLu8e9+BBD1CNXkCiqinFuJ8B8l7OGPFPE0ha5SAc9YlIWU+SdOoBhc I/oX55ZHEx89/1MKpnSTttc8PfqRR98= X-MC-Unique: EBXPNXF8N0ORu-kEBRMFUg-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 1/7] docs: formatstorage: Convert to RST Date: Fri, 17 Dec 2021 16:04:29 +0100 Message-Id: <3925871a280b414c0e4cf599c0186c2dc6618aca.1639753439.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 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.11 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1639753510582100001 Content-Type: text/plain; charset="utf-8" Apart from the bulk conversion itself, the section names 'general metadata' and 'target elements' were duplicated between the storage pool and storage volume sections. To prevent heading name clashes they were renamed appropriately. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/formatstorage.html.in | 1000 ------------------------------------ docs/formatstorage.rst | 823 +++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 824 insertions(+), 1001 deletions(-) delete mode 100644 docs/formatstorage.html.in create mode 100644 docs/formatstorage.rst diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in deleted file mode 100644 index 9ee5b89ee6..0000000000 --- a/docs/formatstorage.html.in +++ /dev/null @@ -1,1000 +0,0 @@ - - - - -

Storage pool and volume XML format

- -
    - -

    Storage pool XML

    - -

    - Although all storage pool backends share the same public APIs and - XML format, they have varying levels of capabilities. Some may - allow creation of volumes, others may only allow use of pre-existing - volumes. Some may have constraints on volume size, or placement. -

    -

    - The top level tag for a storage pool document is 'pool'. It has - a single attribute type, which is one of dir, - fs, netfs, disk, - iscsi, logical, scsi - (all since 0.4.1), - mpath (since 0.7.1), - rbd (since 0.9.13), - sheepdog (since 0.10.0), - gluster (since 1.2.0), - zfs (since 1.2.8), - vstorage (since 3.1.0), - or iscsi-direct (since 4.7.0). - This corresponds to the - storage backend drivers listed further along in this document. -

    -

    General metadata

    - - 
    -<pool type=3D"iscsi">
-  <name>virtimages</name>
-  <uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
-  <allocation>10000000</allocation>
-  <capacity>50000000</capacity>
-  <available>40000000</available>
-  ...
    - -
    -
    name
    -
    Providing a name for the pool which is unique to the host. - This is mandatory when defining a pool. Sinc= e 0.4.1
    -
    uuid
    -
    Providing an identifier for the pool which is globally unique. - This is optional when defining a pool, a UUID will be generated if - omitted. Since 0.4.1
    -
    allocation
    -
    Providing the total storage allocation for the pool. This may - be larger than the sum of the allocation of all volumes due to - metadata overhead. This value is in bytes. This is not applicable - when creating a pool. Since 0.4.1
    -
    capacity
    -
    Providing the total storage capacity for the pool. Due to - underlying device constraints it may not be possible to use the - full capacity for storage volumes. This value is in bytes. This - is not applicable when creating a pool. Sinc= e 0.4.1
    -
    available
    -
    Providing the free space available for allocating new volumes - in the pool. Due to underlying device constraints it may not be - possible to allocate the entire free space to a single volume. - This value is in bytes. This is not applicable when creating a - pool. Since 0.4.1
    -
    - -

    Features

    - -

    - Some pools support optional features: -

    - - 
    -...
-<features>
-  <cow state=3D'no'>
-</features>
-...
    - -

    - Valid features are: -

    -
      -
      cow
      -
      Controls whether the filesystem performs copy-on-write (COW) for - images in the pool. This may only be set for directory / filesystem - pools on the btrfs filesystem. If not set then libvirt - will attempt to disable COW on any btrfs filesystems. - Since 6.6.0.
      -
    - -

    Source elements

    - -

    - A single source element is contained within the top lev= el - pool element. This tag is used to describe the source of - the storage pool. The set of child elements that it will contain - depend on the pool type, but come from the following child elements: -

    - - 
    -...
-<source>
-  <host name=3D"iscsi.example.com"/>
-  <device path=3D"iqn.2013-06.com.example:iscsi-pool"/>
-  <auth type=3D'chap' username=3D'myname'>
-    <secret usage=3D'mycluster_myname'/>
-  </auth>
-  <vendor name=3D"Acme"/>
-  <product name=3D"model"/>
-</source>
-...
    - - 
    -...
-<source>
-  <device path=3D'/dev/mapper/mpatha' part_separator=3D'no'/>
-  <format type=3D'gpt'/>
-</source>
-...
    - - 
    -...
-<source>
-  <adapter type=3D'scsi_host' name=3D'scsi_host1'/>
-</source>
-...
    - - 
    -...
-<source>
-  <adapter type=3D'scsi_host'>
-    <parentaddr unique_id=3D'1'>
-      <address domain=3D'0x0000' bus=3D'0x00' slot=3D'0x1f' addr=3D'0x2=
'/>
-    </parentaddr>
-  </adapter>
-</source>
-...
    - - 
    -...
-<source>
-  <adapter type=3D'fc_host' parent=3D'scsi_host5' wwnn=3D'20000000c9831=
b4b' wwpn=3D'10000000c9831b4b'/>
-</source>
-...
    - - 
    -...
-  <source>
-    <host name=3D'localhost'/>
-    <dir path=3D'/var/lib/libvirt/images'/>
-    <format type=3D'nfs'/>
-    <protocol ver=3D'3'/>
-  </source>
-...
    - -
    -
    device
    -
    Provides the source for pools backed by physical devices - (pool types fs, logical, disk, - iscsi, iscsi-direct, zfs, - vstorage). - May be repeated multiple times depending on backend driver. Contai= ns - a required attribute path which is either the fully - qualified path to the block device node or for iscsi - or iscsi-direct the iSCSI Qualified Name (IQN). - Since 0.4.1 -

    An optional attribute part_separator for each - path may be supplied. Valid values for the attribute - may be either "yes" or "no". This attribute is to be used for a - disk pool type using a path to a - device mapper multipath device. Setting the attribute to "yes" - causes libvirt to attempt to generate and find target volume path's - using a "p" separator. The default algorithm used by device mapper - is to add the "p" separator only when the source device path ends - with a number; however, it's possible to configure the devmapper - device to not use 'user_friendly_names' thus creating partitions - with the "p" separator even when the device source path does not - end with a number. - Since 1.3.1

    -
    dir
    -
    Provides the source for pools backed by directories (pool - types dir, netfs, gluster), - or optionally to select a subdirectory - within a pool that resembles a filesystem (pool - type gluster). May - only occur once. Contains a single attribute path - which is the fully qualified path to the backing directory or - for a netfs pool type using format - type "cifs", the path to the Samba share without the leading slash. - Since 0.4.1
    -
    adapter
    -
    Provides the source for pools backed by SCSI adapters (pool - type scsi). May only occur once. -
    -
    name
    -
    The SCSI adapter name (e.g. "scsi_host1", although a name - such as "host1" is still supported for backwards compatibility, - it is not recommended). The scsi_host name to be used can be - determined from the output of a virsh nodedev-list - scsi_host command followed by a combination of - lspci and virsh nodedev-dumpxml - scsi_hostN commands to find the scsi_hostN - to be used. Since 0.6.2 -

    - It is further recommended to utilize the - parentaddr element since it's possible to have - the path to which the scsi_hostN uses change between system - reboots. Since 1.2.7 -

    -
    -
    -
    -
    type
    -
    Specifies the adapter type. Valid values are "scsi_host" or - "fc_host". If omitted and the name attribute is - specified, then it defaults to "scsi_host". To keep backwards - compatibility, this attribute is optional only for the - "scsi_host" adapter, but is mandatory for the "fc_host" adapte= r. - Since 1.0.5 - A "fc_host" capable scsi_hostN can be determined by using - virsh nodedev-list --cap fc_host. - Since 1.2.8 -

    - Note: Regardless of whether a "scsi_host" adapter type is defi= ned - using a name or a parentaddr, it - should refer to a real scsi_host adapter as found through a - virsh nodedev-list scsi_host and virsh - nodedev-dumpxml scsi_hostN on one of the scsi_host's - displayed. It should not refer to a "fc_host" capable scsi_hos= tN - nor should it refer to the vHBA created for some "fc_host" - adapter. For a vHBA the nodedev-dumpxml - output parent setting will be the "fc_host" capable scsi_hostN - value. Additionally, do not refer to an iSCSI scsi_hostN for t= he - "scsi_host" source. An iSCSI scsi_hostN's - nodedev-dumpxml output parent field is generally - "computer". This is a libvirt created parent value indicating - no parent was defined for the node device. -

    -
    -
    -
    -
    wwnn and wwpn
    -
    The required "World Wide Node Name" (wwnn) and - "World Wide Port Name" (wwpn) are used by the - "fc_host" adapter to uniquely identify the vHBA device in the - Fibre Channel storage fabric. If the vHBA device already exists - as a Node Device, then libvirt will use it; otherwise, the vHBA - will be created using the provided values. It is considered a - configuration error use the values from the HBA as those would - be for a "scsi_host" type pool instead. The - wwnn and wwpn have very specific - format requirements based on the hypervisor being used, thus - care should be taken if you decide to generate your own to - follow the standards; otherwise, the pool will fail to start - with an opaque error message indicating failure to write to - the vport_create file during vport create/delete due to - "No such file or directory". - Since 1.0.4 -
    -
    -
    -
    parent
    -
    Used by the "fc_host" adapter type to optionally specify the - parent scsi_host device defined in the - Node Device database as the - NPIV= - virtual Host Bus Adapter (vHBA). The value provided must be - a vport capable scsi_host. The value is not the scsi_host of - the vHBA created by 'virsh nodedev-create', rather it is - the parent of that vHBA. If the value is not provided, libvirt - will determine the parent based either finding the wwnn,wwpn - defined for an existing scsi_host or by creating a vHBA. Provi= ding - the parent attribute is also useful for the duplicate pool - definition checks. This is more important in environments where - both the "fc_host" and "scsi_host" source adapter pools are be= ing - used in order to ensure a new definition doesn't duplicate usi= ng - the scsi_hostN of some existing storage pool. - Since 1.0.4 -
    -
    parent_wwnn and parent_wwpn
    -
    Instead of the parent to specify which scsi_host - to use by name, it's possible to provide the wwnn and wwpn of - the parent to be used for the vHBA in order to ensure that - between reboots or after a hardware configuration change that - the scsi_host parent name doesn't change. Both the parent_wwnn - and parent_wwpn must be provided. - Since 3.0.0 -
    -
    parent_fabric_wwn
    -
    Instead of the parent to specify which scsi_host - to use by name, it's possible to provide the fabric_wwn on whi= ch - the scsi_host exists. This provides flexibility for choosing - a scsi_host that may be available on the fabric rather than - requiring a specific parent by wwnn or wwpn to be available. - Since 3.0.0 -
    -
    managed
    -
    An optional attribute to instruct the SCSI storage backend to - manage destroying the vHBA when the pool is destroyed. For - configurations that do not provide an already created vHBA - from a 'virsh nodedev-create', libvirt will set this property - to "yes". For configurations that have already created a vHBA - via 'virsh nodedev-create' and are using the wwnn/wwpn from - that vHBA and optionally the scsi_host parent, setting this - attribute to "yes" will allow libvirt to destroy the node devi= ce - when the pool is destroyed. If this attribute is set to "no" or - not defined in the XML, then libvirt will not destroy the vHBA. - Since 1.2.11 -
    -
    -
    -
    parentaddr
    -
    Used by the "scsi_host" adapter type instead of the - name attribute to more uniquely identify the - SCSI host. Using a combination of the unique_id - attribute and the address element to formulate - a PCI address, a search will be performed of the - /sys/class/scsi_host/hostNN links for a - matching PCI address with a matching unique_id - value in the /sys/class/scsi_host/hostNN/unique_id - file. The value in the "unique_id" file will be unique enough - for the specific PCI address. The hostNN will be - used by libvirt as the basis to define which SCSI host is to - be used for the currently booted system. - Since 1.2.7 -
    -
    address
    -
    The PCI address of the scsi_host device to be used. Using - a PCI address provides consistent naming across system reb= oots - and kernel reloads. The address will have four attributes: - domain (a 2-byte hex integer, not currently u= sed - by qemu), bus (a hex value between 0 and 0xff, - inclusive), slot (a hex value between 0x0 and - 0x1f, inclusive), and function (a value betwe= en - 0 and 7, inclusive). The PCI address can be determined by - listing the /sys/bus/pci/devices and the - /sys/class/scsi_host directories in order to - find the expected scsi_host device. The address will be - provided in a format such as "0000:00:1f:2" which can be - used to generate the expected PCI address - "domain=3D'0x0000' bus=3D'0x00' slot=3D'0x1f' function=3D'= 0x0'". - Optionally, using the combination of the commands 'virsh - nodedev-list scsi_host' and 'virsh nodedev-dumpxml' for a - specific list entry and converting the resulting - path element as the basis to formulate the - correctly formatted PCI address. -
    -
    -
    -
    unique_id
    -
    Required parentaddr attribute used to deter= mine - which of the scsi_host adapters for the provided PCI addre= ss - should be used. The value is determine by contents of the - unique_id file for the specific scsi_host ada= pter. - For a PCI address of "0000:00:1f:2", the unique identifier= files - can be found using the command - find -H /sys/class/scsi_host/host*/unique_id | - xargs grep '[0-9]'. Optionally, the - virsh nodedev-dumpxml scsi_hostN' of a - specific scsi_hostN list entry will list the - unique_id value. -
    -
    -
    -
    -
    -
    host
    -
    Provides the source for pools backed by storage from a - remote server (pool types netfs, iscsi, - iscsi-direct, - rbd, sheepdog, gluster). Wi= ll be - used in combination with a directory - or device element. Contains an attribute name - which is the hostname or IP address of the server. May optionally - contain a port attribute for the protocol specific - port number. Duplicate storage pool definition checks may perform - a cursory check that the same host name by string comparison in the - new pool does not match an existing pool's source host name when - combined with the directory or device - element. Name resolution of the provided hostname or IP address - is left to the storage driver backend interactions with the remote - server. See the storage driver page f= or - any restrictions for specific storage backends. - Since 0.4.1
    -
    initiator
    -
    Required by the iscsi-direct pool in order to provi= de - the iSCSI Qualified Name (IQN) to communicate with the pool's - device target IQN. There is one sub-element - iqn with the name attribute to describe - the IQN for the initiator. - Since 4.7.0
    -
    auth
    -
    If present, the auth element provides the - authentication credentials needed to access the source by the - setting of the type attribute (pool - types iscsi, iscsi-direct, rbd). - The type - must be either "chap" or "ceph". Use "ceph" for - Ceph RBD (Rados Block Device) network sources and use "iscsi" for = CHAP - (Challenge-Handshake Authentication Protocol) iSCSI - targets. Additionally a mandatory attribute - username identifies the username to use during - authentication as well as a sub-element secret with - a 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 password, only the reference - to the object that manages the password. - The secret element requires 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. Since 0.9.7 for "ceph" and - 1.1.1 for "chap" -
    -
    name
    -
    Provides the source for pools backed by storage from a - named element (pool types logical, rbd, - sheepdog, gluster). Contains a - string identifier. - Since 0.4.5
    -
    format
    -
    Provides information about the format of the pool (pool - types fs, netfs, disk, - logical). This - contains a single attribute type whose value is - backend specific. This is typically used to indicate filesystem - type, or network filesystem type, or partition table type, or - LVM metadata type. All drivers are required to have a default - value for this, so it is optional. Since 0.4= .1
    - -
    protocol
    -
    For a netfs Storage Pool provide a mechanism to - define which NFS protocol version number will be used to contact - the server's NFS service. The attribute ver accepts - an unsigned integer as the version number to use. - Since 5.1.0
    -
    vendor
    -
    Provides optional information about the vendor of the - storage device. This contains a single - attribute name whose value is backend - specific. Since 0.8.4
    -
    product
    -
    Provides an optional product name of the storage device. - This contains a single attribute name whose value - is backend specific. Since 0.8.4
    -
    - -

    Target elements

    - -

    - A single target element is contained within the top lev= el - pool element for some types of pools (pool - types dir, fs, netfs, - logical, disk, iscsi, - scsi, mpath, zfs). - This tag is used to describe the mapping of - the storage pool into the host filesystem. It can contain the follow= ing - child elements: -

    - - 
    -  ...
-  <target>
-    <path>/dev/disk/by-path</path>
-    <permissions>
-      <owner>107</owner>
-      <group>107</group>
-      <mode>0744</mode>
-      <label>virt_image_t</label>
-    </permissions>
-  </target>
-</pool>
    - -
    -
    path
    -
    Provides the location at which the pool will be mapped into - the local filesystem namespace, as an absolute path. For a - filesystem/directory based pool it will be a fully qualified name = of - the directory in which volumes will be created. For device based p= ools - it will be a fully qualified name of the directory in which - devices nodes exist. For the latter /dev/ may seem - like the logical choice, however, devices nodes there are not - guaranteed stable across reboots, since they are allocated on - demand. It is preferable to use a stable location such as one - of the /dev/disk/by-{path|id|uuid|label} locations. - For logical and zfs pool types, a - provided value is ignored and a default path generated. - For a Multipath pool (type mpath), the provided - value is ignored and the default value of "/dev/mapper" is used. - Since 0.4.1 -
    -
    permissions
    -
    This is currently only useful for directory or filesystem based - pools, which are mapped as a directory into the local filesystem - namespace. It provides information about the permissions to use fo= r the - final directory when the pool is built. There are 4 child elements. - The mode element contains the octal permission set. - The mode defaults to 0711 when not provided. - The owner element contains the numeric user ID. - The group element contains the numeric group ID. - If owner or group aren't specified when - creating a directory, the UID and GID of the libvirtd process are = used. - The label element contains the MAC (eg SELinux) - label string. - Since 0.4.1 - For running directory or filesystem based pools, these fields - will be filled with the values used by the existing directory. - Since 1.2.16 -
    -
    - -

    Device extents

    - -

    - If a storage pool exposes information about its underlying - placement / allocation scheme, the device element - within the source element may contain information - about its available extents. Some pools have a constraint that - a volume must be allocated entirely within a single constraint - (eg disk partition pools). Thus the extent information allows an - application to determine the maximum possible size for a new - volume -

    -

    - For storage pools supporting extent information, within each - device element there will be zero or more freeExt= ent - elements. Each of these elements contains two attributes, star= t - and end which provide the boundaries of the extent on t= he - device, measured in bytes. Since 0.4.1 -

    - -

    Refresh overrides

    - -

    - The optional refresh element can control how the pool a= nd - associated volumes are refreshed (pool type rbd). The - allocation attribute of the volume child e= lement - controls the method used for computing the allocation of a volume. T= he - valid attribute values are default to compute the actual - usage or capacity to use the logical capacity for cases= where - computing the allocation is too expensive. The following XML snippet - shows the syntax: - 

    -<pool type=3D"rbd">
-  <name>myrbdpool</name>
-...
-  <source/>
-...
-  <refresh>
-    <volume allocation=3D'capacity'/>
-  </refresh>
-...
-</pool>
-
    - Since 5.2.0 -

    - -

    Storage Pool Namespaces

    - -

    - Usage of Storage Pool Namespaces provides a mechanism to provide - pool type specific data in a free form or arbitrary manner via - XML syntax targeted solely for the needs of the specific pool type - which is not otherwise supported in standard XML. For the "fs" and - "netfs" pool types this provides a mechanism to provide additional - mount options on the command line. For the "rbd" pool this provides - a mechanism to override default settings for RBD configuration optio= ns. -

    -

    - Usage of namespaces comes with no support guarantees. It is intended - for developers testing out a concept prior to requesting an explicit= ly - supported XML option in libvirt, and thus should never be used in - production. -

    -
    -
    fs:mount_opts
    -
    Provides an XML namespace mechanism to optionally utilize - specifically named options for the mount command via the "-o" - option for the fs or netfs type storage - pools. In order to designate that the Storage Pool will be using - the mechanism, the pool element must be modified to - provide the XML namespace attribute syntax as follows: - -

    - xmlns:fs=3D'http://libvirt.org/schemas/storagepool/fs/1.0' -

    - -

    - The fs:mount_opts defines the mount options by - specifying multiple fs:option subelements with - the attribute name specifying the mount option to - be added. The value of the named option is not checked since - it's possible options don't exist on all distributions. It is - expected that proper and valid options will be supplied for the - target host. -

    - - The following XML snippet shows the syntax required in order to - utilize for a netfs pool: - 
    -<pool type=3D"netfs" xmlns:fs=3D'http://libvirt.org/schemas/storagepool=
/fs/1.0'>
-  <name>nfsimages</name>
-...
-  <source>
-...
-  </source>
-...
-  <target>
-...
-  </target>
-  <fs:mount_opts>
-    <fs:option name=3D'sync'/>
-    <fs:option name=3D'lazytime'/>
-  </fs:mount_opts>
-</pool>
-...
    - - Since 5.1.0.
    - -
    rbd:config_opts
    -
    Provides an XML namespace mechanism to optionally utilize - specifically named options for the RBD configuration options - via the rados_conf_set API for the rbd type - storage pools. In order to designate that the Storage Pool - will be using the mechanism, the pool element - must be modified to provide the XML namespace attribute - syntax as follows: - -

    - xmlns:rbd=3D'http://libvirt.org/schemas/storagepool/rbd/1.0' -

    - -

    - The rbd:config_opts defines the configuration options - by specifying multiple rbd:option subelements with - the attribute name specifying the configuration option - to be added and value specifying the configuration - option value. The name and value for each option is only checked - to be not empty. The name and value provided are not checked since - it's possible options don't exist on all distributions. It is - expected that proper and valid options will be supplied for the - target host. -

    - - The following XML snippet shows the syntax required in order to - utilize - 
    -<pool type=3D"rbd" xmlns:rbd=3D'http://libvirt.org/schemas/storagepool/=
rbd/1.0'>
-  <name>myrbdpool</name>
-...
-  <source>
-...
-  </source>
-...
-  <target>
-...
-  </target>
-...
-  <rbd:config_opts>
-    <rbd:option name=3D'client_mount_timeout' value=3D'45'/>
-    <rbd:option name=3D'rados_mon_op_timeout' value=3D'20'/>
-    <rbd:option name=3D'rados_osd_op_timeout' value=3D'10'/>
-  </rbd:config_opts>
-</pool>
-
    - - Since 5.1.0.
    - -
    - -

    Storage volume XML

    -

    - A storage volume will generally be either a file or a device - node; since 1.2.0, an optional - output-only attribute type lists the actual type - (file, block, dir, network, netdir or ploop), which is also available - from virStorageVolGetInfo(). The storage volume - XML format is available since 0.4.1 -

    - -

    General metadata

    - - 
    -<volume type=3D'file'>
-  <name>sparse.img</name>
-  <key>/var/lib/xen/images/sparse.img</key>
-  <allocation>0</allocation>
-  <capacity unit=3D"T">1</capacity>
-  ...
    - -
    -
    name
    -
    Providing a name for the volume which is unique to the pool. - This is mandatory when defining a volume. For a disk pool, the - name must be combination of the source device path - device and next partition number to be created. For example, if - the source device path is /dev/sdb and there are no - partitions on the disk, then the name must be sdb1 with the next - name being sdb2 and so on. - Since 0.4.1
    -
    key
    -
    Providing an identifier for the volume which identifies a - single volume. In some cases it's possible to have two distinct = keys - identifying a single volume. This field cannot be set when creat= ing - a volume: it is always generated. - Since 0.4.1
    -
    allocation
    -
    Providing the total storage allocation for the volume. This - may be smaller than the logical capacity if the volume is sparsely - allocated. It may also be larger than the logical capacity if the - volume has substantial metadata overhead. This value is in bytes. - If omitted when creating a volume, the volume will be fully - allocated at time of creation. If set to a value smaller than the - capacity, the pool has the option of deciding - to sparsely allocate a volume. It does not have to honour requests - for sparse allocation though. Different types of pools may treat - sparse volumes differently. For example, the logical - pool will not automatically expand volume's allocation when it - gets full; the user is responsible for doing that or configuring - dmeventd to do so automatically.
    -
    - By default this is specified in bytes, but an optional attribute - unit can be specified to adjust the passed value. - Values can be: 'B' or 'bytes' for bytes, 'KB' (kilobytes, - 103 or 1000 bytes), 'K' or 'KiB' (kibibytes, - 210 or 1024 bytes), 'MB' (megabytes, 106 - or 1,000,000 bytes), 'M' or 'MiB' (mebibytes, 220 - or 1,048,576 bytes), 'GB' (gigabytes, 109 or - 1,000,000,000 bytes), 'G' or 'GiB' (gibibytes, 230 - or 1,073,741,824 bytes), 'TB' (terabytes, 1012 or - 1,000,000,000,000 bytes), 'T' or 'TiB' (tebibytes, - 240 or 1,099,511,627,776 bytes), 'PB' (petabytes, - 1015 or 1,000,000,000,000,000 bytes), 'P' or 'PiB' - (pebibytes, 250 or 1,125,899,906,842,624 bytes), - 'EB' (exabytes, 1018 or 1,000,000,000,000,000,000 - bytes), or 'E' or 'EiB' (exbibytes, 260 or - 1,152,921,504,606,846,976 bytes). Since - 0.4.1, multi-character unit since - 0.9.11
    -
    capacity
    -
    Providing the logical capacity for the volume. This value is - in bytes by default, but a unit attribute can be - specified with the same semantics as for allocation - This is compulsory when creating a volume. - Since 0.4.1
    -
    physical
    -
    This output only element provides the host physical size of - the target storage volume. The default output unit - will be in bytes. - Since 3.0.0
    -
    source
    -
    Provides information about the underlying storage allocation - of the volume. This may not be available for some pool types. - Since 0.4.1
    -
    target
    -
    Provides information about the representation of the volume - on the local host. Since 0.4.1
    -
    - -

    Target elements

    - -

    - A single target element is contained within the top lev= el - volume element. This tag is used to describe the mappin= g of - the storage volume into the host filesystem. It can contain the foll= owing - child elements: -

    - - 
    -...
-<target>
-  <path>/var/lib/virt/images/sparse.img</path>
-  <format type=3D'qcow2'/>
-  <permissions>
-    <owner>107</owner>
-    <group>107</group>
-    <mode>0744</mode>
-    <label>virt_image_t</label>
-  </permissions>
-  <timestamps>
-    <atime>1341933637.273190990</atime>
-    <mtime>1341930622.047245868</mtime>
-    <ctime>1341930622.047245868</ctime>
-  </timestamps>
-  <encryption type=3D'...'>
-    ...
-  </encryption>
-  <compat>1.1</compat>
-  <nocow/>
-  <clusterSize unit=3D'KiB'>64</clusterSize>
-  <features>
-    <lazy_refcounts/>
-  </features>
-</target>
    - -
    -
    path
    -
    Provides the location at which the volume can be accessed on - the local filesystem, as an absolute path. This is a readonly - attribute, so shouldn't be specified when creating a volume. - Since 0.4.1
    -
    format
    -
    Provides information about the pool specific volume format. - For disk pools it will provide the partition table format type, bu= t is - not preserved after a pool refresh or libvirtd restart. Use extend= ed - in order to create an extended disk extent partition. For filesyst= em - or directory pools it will provide the file format type, eg cow, - qcow, vmdk, raw. If omitted when creating a volume, the pool's - default format will be used. The actual format is specified via - the type attribute. Consult the - storage driver page for the list of v= alid - volume format type values for each specific pool. The - format will be ignored on input for pools without a - volume format type value and the default pool format will be used. - Since 0.4.1
    -
    permissions
    -
    Provides information about the permissions to use - when creating volumes. This is currently only useful for directory - or filesystem based pools, where the volumes allocated are simple - files. For pools where the volumes are device nodes, the hotplug - scripts determine permissions. There are 4 child elements. - The mode element contains the octal permission set. - The mode defaults to 0600 when not provided. - The owner element contains the numeric user ID. - The group element contains the numeric group ID. - If owner or group aren't specified when - creating a supported volume, the UID and GID of the libvirtd proce= ss - are used. The label element contains the MAC (eg SELi= nux) - label string. - For existing directory or filesystem based volumes, these fields - will be filled with the values used by the existing file. - Since 0.4.1 -
    -
    timestamps
    -
    Provides timing information about the volume. Up to four - sub-elements are present, - where atime, btime, ctime - and mtime hold the access, birth, change and - modification time of the volume, where known. The used time - format is <seconds>.<nanoseconds> since the - beginning of the epoch (1 Jan 1970). If nanosecond resolution - is 0 or otherwise unsupported by the host OS or filesystem, - then the nanoseconds part is omitted. This is a readonly - attribute and is ignored when creating a volume. - Since 0.10.0 -
    -
    encryption
    -
    If present, specifies how the volume is encrypted. See - the Storage Encryption page - for more information. -
    -
    compat
    -
    Specify compatibility level. So far, this is only used for - type=3D'qcow2' volumes. Valid values are 0.10 - and 1.1 so far, specifying QEMU version the images sh= ould - be compatible with. If the feature element is present, - 1.1 is used. - Since 1.1.0 If omitted, 0.10 is used. - Since 1.1.2 -
    -
    nocow
    -
    Turn off COW of the newly created volume. So far, this is only v= alid - for a file image in btrfs file system. It will improve performance= when - the file image is used in VM. To create non-raw file images, it - requires QEMU version since 2.1. Since 1.2.7= -
    -
    clusterSize
    -
    Changes the qcow2 cluster size which can affect image file size - and performance. - Since 7.4.0 -
    -
    features
    -
    Format-specific features. Only used for qcow2 now. - Valid sub-elements are: -
      -
    • <lazy_refcounts/> - allow delayed referen= ce - counter updates. Since 1.1.0
      • -
    -
    -
    - -

    Backing store elements

    - -

    - A single backingStore element is contained within the t= op level - volume element. This tag is used to describe the option= al copy - on write, backing store for the storage volume. It can contain the f= ollowing - child elements: -

    - - 
    -  ...
-  <backingStore>
-    <path>/var/lib/virt/images/master.img</path>
-    <format type=3D'raw'/>
-    <permissions>
-      <owner>107</owner>
-      <group>107</group>
-      <mode>0744</mode>
-      <label>virt_image_t</label>
-    </permissions>
-  </backingStore>
-</volume>
    - -
    -
    path
    -
    Provides the location at which the backing store can be accessed= on - the local filesystem, as an absolute path. If omitted, there is no - backing store for this volume. - Since 0.6.0
    -
    format
    -
    Provides information about the pool specific backing store forma= t. - For disk pools it will provide the partition type. For filesystem - or directory pools it will provide the file format type, eg cow, - qcow, vmdk, raw. The actual format is specified via the type attri= bute. - Consult the pool-specific docs for the list of valid - values. Most file formats require a backing store of the same form= at, - however, the qcow2 format allows a different backing store format. - Since 0.6.0
    -
    permissions
    -
    Provides information about the permissions of the backing file. - See volume permissions documentation for explanation - of individual fields. - Since 0.6.0 -
    -
    - -

    Example configuration

    - -

    - Here are a couple of examples, for a more complete set demonstrating - every type of storage pool, consult the sto= rage driver page -

    - -

    File based storage pool

    - - 
    -<pool type=3D"dir">
-  <name>virtimages</name>
-  <target>
-    <path>/var/lib/virt/images</path>
-  </target>
-</pool>
    - -

    iSCSI based storage pool

    - - 
    -<pool type=3D"iscsi">
-  <name>virtimages</name>
-  <source>
-    <host name=3D"iscsi.example.com"/>
-    <device path=3D"iqn.2013-06.com.example:iscsi-pool"/>
-    <auth type=3D'chap' username=3D'myuser'>
-      <secret usage=3D'libvirtiscsi'/>
-    </auth>
-  </source>
-  <target>
-    <path>/dev/disk/by-path</path>
-  </target>
-</pool>
    - -

    Storage volume

    - - 
    -<volume>
-  <name>sparse.img</name>
-  <allocation>0</allocation>
-  <capacity unit=3D"T">1</capacity>
-  <target>
-    <path>/var/lib/virt/images/sparse.img</path>
-    <permissions>
-      <owner>107</owner>
-      <group>107</group>
-      <mode>0744</mode>
-      <label>virt_image_t</label>
-    </permissions>
-  </target>
-</volume>
    - -

    Storage volume using LUKS

    - - 
    -<volume>
-  <name>MyLuks.img</name>
-  <capacity unit=3D"G">5</capacity>
-  <target>
-    <path>/var/lib/virt/images/MyLuks.img</path>
-    <format type=3D'raw'/>
-    <encryption format=3D'luks'>
-      <secret type=3D'passphrase' uuid=3D'f52a81b2-424e-490c-823d-6bd42=
35bc572'/>
-    </encryption>
-  </target>
-</volume>
-
    - - diff --git a/docs/formatstorage.rst b/docs/formatstorage.rst new file mode 100644 index 0000000000..ae700fef4d --- /dev/null +++ b/docs/formatstorage.rst @@ -0,0 +1,823 @@ +.. role:: since + +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Storage pool and volume XML format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +Storage pool XML +---------------- + +Although all storage pool backends share the same public APIs and XML form= at, +they have varying levels of capabilities. Some may allow creation of volum= es, +others may only allow use of pre-existing volumes. Some may have constrain= ts on +volume size, or placement. + +The top level tag for a storage pool document is 'pool'. It has a single +attribute ``type``, which is one of ``dir``, ``fs``, ``netfs``, ``disk``, +``iscsi``, ``logical``, ``scsi`` (all :since:`since 0.4.1` ), ``mpath`` ( +:since:`since 0.7.1` ), ``rbd`` ( :since:`since 0.9.13` ), ``sheepdog`` ( +:since:`since 0.10.0` ), ``gluster`` ( :since:`since 1.2.0` ), ``zfs`` ( +:since:`since 1.2.8` ), ``vstorage`` ( :since:`since 3.1.0` ), or +``iscsi-direct`` ( :since:`since 4.7.0` ). This corresponds to the storage +backend drivers listed further along in this document. + +Storage pool general metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + + virtimages + 3e3fce45-4f53-4fa7-bb32-11f34168b82b + 10000000 + 50000000 + 40000000 + ... + +``name`` + Providing a name for the pool which is unique to the host. This is mand= atory + when defining a pool. :since:`Since 0.4.1` +``uuid`` + Providing an identifier for the pool which is globally unique. This is + optional when defining a pool, a UUID will be generated if omitted. + :since:`Since 0.4.1` +``allocation`` + Providing the total storage allocation for the pool. This may be larger= than + the sum of the allocation of all volumes due to metadata overhead. This= value + is in bytes. This is not applicable when creating a pool. :since:`Since + 0.4.1` +``capacity`` + Providing the total storage capacity for the pool. Due to underlying de= vice + constraints it may not be possible to use the full capacity for storage + volumes. This value is in bytes. This is not applicable when creating a= pool. + :since:`Since 0.4.1` +``available`` + Providing the free space available for allocating new volumes in the po= ol. + Due to underlying device constraints it may not be possible to allocate= the + entire free space to a single volume. This value is in bytes. This is n= ot + applicable when creating a pool. :since:`Since 0.4.1` + +Features +~~~~~~~~ + +Some pools support optional features: + +:: + + ... + + + + ... + +Valid features are: + +Source elements +~~~~~~~~~~~~~~~ + +A single ``source`` element is contained within the top level ``pool`` ele= ment. +This tag is used to describe the source of the storage pool. The set of ch= ild +elements that it will contain depend on the pool type, but come from the +following child elements: + +:: + + ... + + + + + + + + + + ... + +:: + + ... + + + + + ... + +:: + + ... + + + + ... + +:: + + ... + + + +
    + + + + ... + +:: + + ... + + + + ... + +:: + + ... + + + + + + + ... + +``device`` + Provides the source for pools backed by physical devices (pool types ``= fs``, + ``logical``, ``disk``, ``iscsi``, ``iscsi-direct``, ``zfs``, ``vstorage= ``). + May be repeated multiple times depending on backend driver. Contains a + required attribute ``path`` which is either the fully qualified path to= the + block device node or for ``iscsi`` or ``iscsi-direct`` the iSCSI Qualif= ied + Name (IQN). :since:`Since 0.4.1` + + An optional attribute ``part_separator`` for each ``path`` may be suppl= ied. + Valid values for the attribute may be either "yes" or "no". This attrib= ute is + to be used for a ``disk`` pool type using a ``path`` to a device mapper + multipath device. Setting the attribute to "yes" causes libvirt to atte= mpt to + generate and find target volume path's using a "p" separator. The defau= lt + algorithm used by device mapper is to add the "p" separator only when t= he + source device path ends with a number; however, it's possible to config= ure + the devmapper device to not use 'user_friendly_names' thus creating + partitions with the "p" separator even when the device source path does= not + end with a number. :since:`Since 1.3.1` + +``dir`` + Provides the source for pools backed by directories (pool types ``dir``, + ``netfs``, ``gluster``), or optionally to select a subdirectory within = a pool + that resembles a filesystem (pool type ``gluster``). May only occur onc= e. + Contains a single attribute ``path`` which is the fully qualified path = to the + backing directory or for a ``netfs`` pool type using ``format`` type "c= ifs", + the path to the Samba share without the leading slash. :since:`Since 0.= 4.1` +``adapter`` + Provides the source for pools backed by SCSI adapters (pool type ``scsi= ``). + May only occur once. + + ``name`` + The SCSI adapter name (e.g. "scsi_host1", although a name such as "h= ost1" + is still supported for backwards compatibility, it is not recommende= d). + The scsi_host name to be used can be determined from the output of a + ``virsh nodedev-list scsi_host`` command followed by a + combination of ``lspci`` and + ``virsh nodedev-dumpxml scsi_hostN`` commands to find the + ``scsi_hostN`` to be used. :since:`Since 0.6.2` + + It is further recommended to utilize the ``parentaddr`` element sinc= e it's + possible to have the path to which the scsi_hostN uses change between + system reboots. :since:`Since 1.2.7` + + ``type`` + Specifies the adapter type. Valid values are "scsi_host" or "fc_host= ". If + omitted and the ``name`` attribute is specified, then it defaults to + "scsi_host". To keep backwards compatibility, this attribute is opti= onal + **only** for the "scsi_host" adapter, but is mandatory for the "fc_h= ost" + adapter. :since:`Since 1.0.5` A "fc_host" capable scsi_hostN can be + determined by using ``virsh nodedev-list --cap fc_host``. :since:`Si= nce + 1.2.8` + + Note: Regardless of whether a "scsi_host" adapter type is defined us= ing a + ``name`` or a ``parentaddr``, it should refer to a real scsi_host ad= apter + as found through a ``virsh nodedev-list scsi_host`` and + ``virsh nodedev-dumpxml scsi_hostN`` on one of the scsi_= host's + displayed. It should not refer to a "fc_host" capable scsi_hostN nor + should it refer to the vHBA created for some "fc_host" adapter. For = a vHBA + the ``nodedev-dumpxml`` output parent setting will be the "fc_host" + capable scsi_hostN value. Additionally, do not refer to an iSCSI + scsi_hostN for the "scsi_host" source. An iSCSI scsi_hostN's + ``nodedev-dumpxml`` output parent field is generally "computer". Thi= s is a + libvirt created parent value indicating no parent was defined for th= e node + device. + + ``wwnn`` and ``wwpn`` + The required "World Wide Node Name" (``wwnn``) and "World Wide Port = Name" + (``wwpn``) are used by the "fc_host" adapter to uniquely identify th= e vHBA + device in the Fibre Channel storage fabric. If the vHBA device alrea= dy + exists as a Node Device, then libvirt will use it; otherwise, the vH= BA + will be created using the provided values. It is considered a + configuration error use the values from the HBA as those would be fo= r a + "scsi_host" ``type`` pool instead. The ``wwnn`` and ``wwpn`` have ve= ry + specific format requirements based on the hypervisor being used, thu= s care + should be taken if you decide to generate your own to follow the + standards; otherwise, the pool will fail to start with an opaque err= or + message indicating failure to write to the vport_create file during = vport + create/delete due to "No such file or directory". :since:`Since 1.0.= 4` + + ``parent`` + Used by the "fc_host" adapter type to optionally specify the parent + scsi_host device defined in the `Node Device `__ da= tabase + as the `NPIV `__ virt= ual + Host Bus Adapter (vHBA). The value provided must be a vport capable + scsi_host. The value is not the scsi_host of the vHBA created by 'vi= rsh + nodedev-create', rather it is the parent of that vHBA. If the value = is not + provided, libvirt will determine the parent based either finding the + wwnn,wwpn defined for an existing scsi_host or by creating a vHBA. + Providing the parent attribute is also useful for the duplicate pool + definition checks. This is more important in environments where both= the + "fc_host" and "scsi_host" source adapter pools are being used in ord= er to + ensure a new definition doesn't duplicate using the scsi_hostN of so= me + existing storage pool. :since:`Since 1.0.4` + ``parent_wwnn`` and ``parent_wwpn`` + Instead of the ``parent`` to specify which scsi_host to use by name,= it's + possible to provide the wwnn and wwpn of the parent to be used for t= he + vHBA in order to ensure that between reboots or after a hardware + configuration change that the scsi_host parent name doesn't change. = Both + the parent_wwnn and parent_wwpn must be provided. :since:`Since 3.0.= 0` + ``parent_fabric_wwn`` + Instead of the ``parent`` to specify which scsi_host to use by name,= it's + possible to provide the fabric_wwn on which the scsi_host exists. Th= is + provides flexibility for choosing a scsi_host that may be available = on the + fabric rather than requiring a specific parent by wwnn or wwpn to be + available. :since:`Since 3.0.0` + ``managed`` + An optional attribute to instruct the SCSI storage backend to manage + destroying the vHBA when the pool is destroyed. For configurations t= hat do + not provide an already created vHBA from a 'virsh nodedev-create', l= ibvirt + will set this property to "yes". For configurations that have already + created a vHBA via 'virsh nodedev-create' and are using the wwnn/wwp= n from + that vHBA and optionally the scsi_host parent, setting this attribut= e to + "yes" will allow libvirt to destroy the node device when the pool is + destroyed. If this attribute is set to "no" or not defined in the XM= L, + then libvirt will not destroy the vHBA. :since:`Since 1.2.11` + + ``parentaddr`` + Used by the "scsi_host" adapter type instead of the ``name`` attribu= te to + more uniquely identify the SCSI host. Using a combination of the + ``unique_id`` attribute and the ``address`` element to formulate a P= CI + address, a search will be performed of the ``/sys/class/scsi_host/ho= stNN`` + links for a matching PCI address with a matching ``unique_id`` value= in + the ``/sys/class/scsi_host/hostNN/unique_id`` file. The value in the + "unique_id" file will be unique enough for the specific PCI address.= The + ``hostNN`` will be used by libvirt as the basis to define which SCSI= host + is to be used for the currently booted system. :since:`Since 1.2.7` + + ``address`` + The PCI address of the scsi_host device to be used. Using a PCI a= ddress + provides consistent naming across system reboots and kernel reloa= ds. + The address will have four attributes: ``domain`` (a 2-byte hex + integer, not currently used by qemu), ``bus`` (a hex value betwee= n 0 + and 0xff, inclusive), ``slot`` (a hex value between 0x0 and 0x1f, + inclusive), and ``function`` (a value between 0 and 7, inclusive)= . The + PCI address can be determined by listing the ``/sys/bus/pci/devic= es`` + and the ``/sys/class/scsi_host`` directories in order to find the + expected scsi_host device. The address will be provided in a form= at + such as "0000:00:1f:2" which can be used to generate the expected= PCI + address "domain=3D'0x0000' bus=3D'0x00' slot=3D'0x1f' function=3D= '0x0'". + Optionally, using the combination of the commands 'virsh nodedev-= list + scsi_host' and 'virsh nodedev-dumpxml' for a specific list entry = and + converting the resulting ``path`` element as the basis to formula= te the + correctly formatted PCI address. + + ``unique_id`` + Required ``parentaddr`` attribute used to determine which of the + scsi_host adapters for the provided PCI address should be used. T= he + value is determine by contents of the ``unique_id`` file for the + specific scsi_host adapter. For a PCI address of "0000:00:1f:2", = the + unique identifier files can be found using the command + ``find -H /sys/class/scsi_host/host*/unique_id | = xargs grep '[0-9]'``. + Optionally, the ``virsh nodedev-dumpxml scsi_hostN``' of a specif= ic + scsi_hostN list entry will list the ``unique_id`` value. +``host`` + Provides the source for pools backed by storage from a remote server (p= ool + types ``netfs``, ``iscsi``, ``iscsi-direct``, ``rbd``, ``sheepdog``, + ``gluster``). Will be used in combination with a ``directory`` or ``dev= ice`` + element. Contains an attribute ``name`` which is the hostname or IP add= ress + of the server. May optionally contain a ``port`` attribute for the prot= ocol + specific port number. Duplicate storage pool definition checks may perf= orm a + cursory check that the same host name by string comparison in the new p= ool + does not match an existing pool's source host name when combined with t= he + ``directory`` or ``device`` element. Name resolution of the provided ho= stname + or IP address is left to the storage driver backend interactions with t= he + remote server. See the `storage driver page `__ for any + restrictions for specific storage backends. :since:`Since 0.4.1` +``initiator`` + Required by the ``iscsi-direct`` pool in order to provide the iSCSI Qua= lified + Name (IQN) to communicate with the pool's ``device`` target IQN. There = is one + sub-element ``iqn`` with the ``name`` attribute to describe the IQN for= the + initiator. :since:`Since 4.7.0` +``auth`` + If present, the ``auth`` element provides the authentication credentials + needed to access the source by the setting of the ``type`` attribute (p= ool + types ``iscsi``, ``iscsi-direct``, ``rbd``). The ``type`` must be either + "chap" or "ceph". Use "ceph" for Ceph RBD (Rados Block Device) network + sources and use "iscsi" for CHAP (Challenge-Handshake Authentication + Protocol) iSCSI targets. Additionally a mandatory attribute ``username`` + identifies the username to use during authentication as well as a sub-e= lement + ``secret`` with a mandatory attribute ``type``, to tie back to a `libvi= rt + secret object `__ that holds the actual password or = other + credentials. The domain XML intentionally does not expose the password,= only + the reference to the object that manages the password. The ``secret`` e= lement + requires either a ``uuid`` attribute with the UUID of the secret object= or a + ``usage`` attribute matching the key that was specified in the secret o= bject. + :since:`Since 0.9.7 for "ceph" and 1.1.1 for "chap"` +``name`` + Provides the source for pools backed by storage from a named element (p= ool + types ``logical``, ``rbd``, ``sheepdog``, ``gluster``). Contains a stri= ng + identifier. :since:`Since 0.4.5` +``format`` + Provides information about the format of the pool (pool types ``fs``, + ``netfs``, ``disk``, ``logical``). This contains a single attribute ``t= ype`` + whose value is backend specific. This is typically used to indicate + filesystem type, or network filesystem type, or partition table type, o= r LVM + metadata type. All drivers are required to have a default value for thi= s, so + it is optional. :since:`Since 0.4.1` +``protocol`` + For a ``netfs`` Storage Pool provide a mechanism to define which NFS pr= otocol + version number will be used to contact the server's NFS service. The + attribute ``ver`` accepts an unsigned integer as the version number to = use. + :since:`Since 5.1.0` +``vendor`` + Provides optional information about the vendor of the storage device. T= his + contains a single attribute ``name`` whose value is backend specific. + :since:`Since 0.8.4` +``product`` + Provides an optional product name of the storage device. This contains a + single attribute ``name`` whose value is backend specific. :since:`Since + 0.8.4` + +Storage pool target elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A single ``target`` element is contained within the top level ``pool`` ele= ment +for some types of pools (pool types ``dir``, ``fs``, ``netfs``, ``logical`= `, +``disk``, ``iscsi``, ``scsi``, ``mpath``, ``zfs``). This tag is used to de= scribe +the mapping of the storage pool into the host filesystem. It can contain t= he +following child elements: + +:: + + ... + + /dev/disk/by-path + + 107 + 107 + 0744 + + + + + +``path`` + Provides the location at which the pool will be mapped into the local + filesystem namespace, as an absolute path. For a filesystem/directory b= ased + pool it will be a fully qualified name of the directory in which volume= s will + be created. For device based pools it will be a fully qualified name of= the + directory in which devices nodes exist. For the latter ``/dev/`` may se= em + like the logical choice, however, devices nodes there are not guaranteed + stable across reboots, since they are allocated on demand. It is prefer= able + to use a stable location such as one of the + ``/dev/disk/by-{path|id|uuid|label}`` locations. For ``logical`` and ``= zfs`` + pool types, a provided value is ignored and a default path generated. F= or a + Multipath pool (type ``mpath``), the provided value is ignored and the + default value of "/dev/mapper" is used. :since:`Since 0.4.1` +``permissions`` + This is currently only useful for directory or filesystem based pools, = which + are mapped as a directory into the local filesystem namespace. It provi= des + information about the permissions to use for the final directory when t= he + pool is built. There are 4 child elements. The ``mode`` element contain= s the + octal permission set. The ``mode`` defaults to 0711 when not provided. = The + ``owner`` element contains the numeric user ID. The ``group`` element + contains the numeric group ID. If ``owner`` or ``group`` aren't specifi= ed + when creating a directory, the UID and GID of the libvirtd process are = used. + The ``label`` element contains the MAC (eg SELinux) label string. + :since:`Since 0.4.1` For running directory or filesystem based pools, t= hese + fields will be filled with the values used by the existing directory. + :since:`Since 1.2.16` + +Device extents +~~~~~~~~~~~~~~ + +If a storage pool exposes information about its underlying placement / +allocation scheme, the ``device`` element within the ``source`` element may +contain information about its available extents. Some pools have a constra= int +that a volume must be allocated entirely within a single constraint (eg di= sk +partition pools). Thus the extent information allows an application to det= ermine +the maximum possible size for a new volume + +For storage pools supporting extent information, within each ``device`` el= ement +there will be zero or more ``freeExtent`` elements. Each of these elements +contains two attributes, ``start`` and ``end`` which provide the boundarie= s of +the extent on the device, measured in bytes. :since:`Since 0.4.1` + +Refresh overrides +~~~~~~~~~~~~~~~~~ + +The optional ``refresh`` element can control how the pool and associated v= olumes +are refreshed (pool type ``rbd``). The ``allocation`` attribute of the +``volume`` child element controls the method used for computing the alloca= tion +of a volume. The valid attribute values are ``default`` to compute the act= ual +usage or ``capacity`` to use the logical capacity for cases where computin= g the +allocation is too expensive. The following XML snippet shows the syntax: + +:: + + + myrbdpool + ... + + ... + + + + ... + + +:since:`Since 5.2.0` + +Storage Pool Namespaces +~~~~~~~~~~~~~~~~~~~~~~~ + +Usage of Storage Pool Namespaces provides a mechanism to provide pool type +specific data in a free form or arbitrary manner via XML syntax targeted s= olely +for the needs of the specific pool type which is not otherwise supported in +standard XML. For the "fs" and "netfs" pool types this provides a mechanis= m to +provide additional mount options on the command line. For the "rbd" pool t= his +provides a mechanism to override default settings for RBD configuration op= tions. + +Usage of namespaces comes with no support guarantees. It is intended for +developers testing out a concept prior to requesting an explicitly support= ed XML +option in libvirt, and thus should never be used in production. + +``fs:mount_opts`` + Provides an XML namespace mechanism to optionally utilize specifically = named + options for the mount command via the "-o" option for the ``fs`` or ``n= etfs`` + type storage pools. In order to designate that the Storage Pool will be= using + the mechanism, the ``pool`` element must be modified to provide the XML + namespace attribute syntax as follows: + + xmlns:fs=3D'http://libvirt.org/schemas/storagepool/fs/1.0' + + The ``fs:mount_opts`` defines the mount options by specifying multiple + ``fs:option`` subelements with the attribute ``name`` specifying the mo= unt + option to be added. The value of the named option is not checked since = it's + possible options don't exist on all distributions. It is expected that = proper + and valid options will be supplied for the target host. + + The following XML snippet shows the syntax required in order to utilize= for a + netfs pool: + + :: + + + nfsimages + ... + + ... + + ... + + ... + + + + + + + ... + + :since:`Since 5.1.0.` + +``rbd:config_opts`` + Provides an XML namespace mechanism to optionally utilize specifically = named + options for the RBD configuration options via the rados_conf_set API fo= r the + ``rbd`` type storage pools. In order to designate that the Storage Pool= will + be using the mechanism, the ``pool`` element must be modified to provid= e the + XML namespace attribute syntax as follows: + + xmlns:rbd=3D'http://libvirt.org/schemas/storagepool/rbd/1.0' + + The ``rbd:config_opts`` defines the configuration options by specifying + multiple ``rbd:option`` subelements with the attribute ``name`` specify= ing + the configuration option to be added and ``value`` specifying the + configuration option value. The name and value for each option is only + checked to be not empty. The name and value provided are not checked si= nce + it's possible options don't exist on all distributions. It is expected = that + proper and valid options will be supplied for the target host. + + The following XML snippet shows the syntax required in order to utilize + + :: + + + myrbdpool + ... + + ... + + ... + + ... + + ... + + + + + + + + :since:`Since 5.1.0.` + +Storage volume XML +------------------ + +A storage volume will generally be either a file or a device node; :since:= `since +1.2.0` , an optional output-only attribute ``type`` lists the actual type = (file, +block, dir, network, netdir or ploop), which is also available from +``virStorageVolGetInfo()``. The storage volume XML format is available +:since:`since 0.4.1` + +Storage volume general metadata +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + + sparse.img + /var/lib/xen/images/sparse.img + 0 + 1 + ... + +``name`` + Providing a name for the volume which is unique to the pool. This is + mandatory when defining a volume. For a disk pool, the name must be + combination of the ``source`` device path device and next partition num= ber to + be created. For example, if the ``source`` device path is /dev/sdb and = there + are no partitions on the disk, then the name must be sdb1 with the next= name + being sdb2 and so on. :since:`Since 0.4.1` +``key`` + Providing an identifier for the volume which identifies a single volume= . In + some cases it's possible to have two distinct keys identifying a single + volume. This field cannot be set when creating a volume: it is always + generated. :since:`Since 0.4.1` +``allocation`` + Providing the total storage allocation for the volume. This may be smal= ler + than the logical capacity if the volume is sparsely allocated. It may a= lso be + larger than the logical capacity if the volume has substantial metadata + overhead. This value is in bytes. If omitted when creating a volume, the + volume will be fully allocated at time of creation. If set to a value s= maller + than the capacity, the pool has the **option** of deciding to sparsely + allocate a volume. It does not have to honour requests for sparse alloc= ation + though. Different types of pools may treat sparse volumes differently. = For + example, the ``logical`` pool will not automatically expand volume's + allocation when it gets full; the user is responsible for doing that or + configuring dmeventd to do so automatically. + By default this is specified in bytes, but an optional attribute ``unit= `` can + be specified to adjust the passed value. Values can be: 'B' or 'bytes' = for + bytes, 'KB' (kilobytes, 10\ :sup:`3` or 1000 bytes), 'K' or 'KiB' (kibi= bytes, + 2\ :sup:`10` or 1024 bytes), 'MB' (megabytes, 10\ :sup:`6` or 1,000,000 + bytes), 'M' or 'MiB' (mebibytes, 2\ :sup:`20` or 1,048,576 bytes), 'GB' + (gigabytes, 10\ :sup:`9` or 1,000,000,000 bytes), 'G' or 'GiB' (gibibyt= es, + 2\ :sup:`30` or 1,073,741,824 bytes), 'TB' (terabytes, 10\ :sup:`12` or + 1,000,000,000,000 bytes), 'T' or 'TiB' (tebibytes, 2\ :sup:`40` or + 1,099,511,627,776 bytes), 'PB' (petabytes, 10\ :sup:`15` or + 1,000,000,000,000,000 bytes), 'P' or 'PiB' (pebibytes, 2\ :sup:`50` or + 1,125,899,906,842,624 bytes), 'EB' (exabytes, 10\ :sup:`18` or + 1,000,000,000,000,000,000 bytes), or 'E' or 'EiB' (exbibytes, 2\ :sup:`= 60` or + 1,152,921,504,606,846,976 bytes). :since:`Since 0.4.1, multi-character + ``unit`` since 0.9.11` +``capacity`` + Providing the logical capacity for the volume. This value is in bytes by + default, but a ``unit`` attribute can be specified with the same semant= ics as + for ``allocation`` This is compulsory when creating a volume. :since:`S= ince + 0.4.1` +``physical`` + This output only element provides the host physical size of the target + storage volume. The default output ``unit`` will be in bytes. :since:`S= ince + 3.0.0` +``source`` + Provides information about the underlying storage allocation of the vol= ume. + This may not be available for some pool types. :since:`Since 0.4.1` +``target`` + Provides information about the representation of the volume on the local + host. :since:`Since 0.4.1` + +Storage volume target elements +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A single ``target`` element is contained within the top level ``volume`` +element. This tag is used to describe the mapping of the storage volume in= to the +host filesystem. It can contain the following child elements: + +:: + + ... + + /var/lib/virt/images/sparse.img + + + 107 + 107 + 0744 + + + + 1341933637.273190990 + 1341930622.047245868 + 1341930622.047245868 + + + ... + + 1.1 + + 64 + + + + + +``path`` + Provides the location at which the volume can be accessed on the local + filesystem, as an absolute path. This is a readonly attribute, so shoul= dn't + be specified when creating a volume. :since:`Since 0.4.1` +``format`` + Provides information about the pool specific volume format. For disk po= ols it + will provide the partition table format type, but is not preserved afte= r a + pool refresh or libvirtd restart. Use extended in order to create an ex= tended + disk extent partition. For filesystem or directory pools it will provid= e the + file format type, eg cow, qcow, vmdk, raw. If omitted when creating a v= olume, + the pool's default format will be used. The actual format is specified = via + the ``type`` attribute. Consult the `storage driver page = `__ + for the list of valid volume format type values for each specific pool.= The + ``format`` will be ignored on input for pools without a volume format t= ype + value and the default pool format will be used. :since:`Since 0.4.1` +``permissions`` + Provides information about the permissions to use when creating volumes= . This + is currently only useful for directory or filesystem based pools, where= the + volumes allocated are simple files. For pools where the volumes are dev= ice + nodes, the hotplug scripts determine permissions. There are 4 child ele= ments. + The ``mode`` element contains the octal permission set. The ``mode`` de= faults + to 0600 when not provided. The ``owner`` element contains the numeric u= ser + ID. The ``group`` element contains the numeric group ID. If ``owner`` or + ``group`` aren't specified when creating a supported volume, the UID an= d GID + of the libvirtd process are used. The ``label`` element contains the MA= C (eg + SELinux) label string. For existing directory or filesystem based volum= es, + these fields will be filled with the values used by the existing file. + :since:`Since 0.4.1` +``timestamps`` + Provides timing information about the volume. Up to four sub-elements a= re + present, where ``atime``, ``btime``, ``ctime`` and ``mtime`` hold the a= ccess, + birth, change and modification time of the volume, where known. The use= d time + format is . since the beginning of the epoch (1 J= an + 1970). If nanosecond resolution is 0 or otherwise unsupported by the ho= st OS + or filesystem, then the nanoseconds part is omitted. This is a readonly + attribute and is ignored when creating a volume. :since:`Since 0.10.0` +``encryption`` + If present, specifies how the volume is encrypted. See the `Storage + Encryption `__ page for more information. +``compat`` + Specify compatibility level. So far, this is only used for ``type=3D'qc= ow2'`` + volumes. Valid values are ``0.10`` and ``1.1`` so far, specifying QEMU + version the images should be compatible with. If the ``feature`` elemen= t is + present, 1.1 is used. :since:`Since 1.1.0` If omitted, 0.10 is used. + :since:`Since 1.1.2` +``nocow`` + Turn off COW of the newly created volume. So far, this is only valid fo= r a + file image in btrfs file system. It will improve performance when the f= ile + image is used in VM. To create non-raw file images, it requires QEMU ve= rsion + since 2.1. :since:`Since 1.2.7` +``clusterSize`` + Changes the qcow2 cluster size which can affect image file size and + performance. :since:`Since 7.4.0` +``features`` + Format-specific features. Only used for ``qcow2`` now. Valid sub-elemen= ts + are: + + - ```` - allow delayed reference counter updates. + :since:`Since 1.1.0` + +Backing store elements +~~~~~~~~~~~~~~~~~~~~~~ + +A single ``backingStore`` element is contained within the top level ``volu= me`` +element. This tag is used to describe the optional copy on write, backing = store +for the storage volume. It can contain the following child elements: + +:: + + ... + + /var/lib/virt/images/master.img + + + 107 + 107 + 0744 + + + + + +``path`` + Provides the location at which the backing store can be accessed on the= local + filesystem, as an absolute path. If omitted, there is no backing store = for + this volume. :since:`Since 0.6.0` +``format`` + Provides information about the pool specific backing store format. For = disk + pools it will provide the partition type. For filesystem or directory p= ools + it will provide the file format type, eg cow, qcow, vmdk, raw. The actu= al + format is specified via the type attribute. Consult the pool-specific d= ocs + for the list of valid values. Most file formats require a backing store= of + the same format, however, the qcow2 format allows a different backing s= tore + format. :since:`Since 0.6.0` +``permissions`` + Provides information about the permissions of the backing file. See vol= ume + ``permissions`` documentation for explanation of individual fields. + :since:`Since 0.6.0` + +Example configuration +--------------------- + +Here are a couple of examples, for a more complete set demonstrating every= type +of storage pool, consult the `storage driver page `__ + +File based storage pool +~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + + virtimages + + /var/lib/virt/images + + + +iSCSI based storage pool +~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + + virtimages + + + + + + + + + /dev/disk/by-path + + + +Storage volume +~~~~~~~~~~~~~~ + +:: + + + sparse.img + 0 + 1 + + /var/lib/virt/images/sparse.img + + 107 + 107 + 0744 + + + + + +Storage volume using LUKS +~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + + MyLuks.img + 5 + + /var/lib/virt/images/MyLuks.img + + + + + + diff --git a/docs/meson.build b/docs/meson.build index 3aabb52950..3c496cb33a 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -69,7 +69,6 @@ docs_html_in_files =3D [ 'formatsnapshot', 'formatstoragecaps', 'formatstorageencryption', - 'formatstorage', 'goals', 'governance', 'hooks', @@ -116,6 +115,7 @@ docs_rst_files =3D [ 'formatbackup', 'formatcheckpoint', 'formatdomain', + 'formatstorage', 'glib-adoption', 'hacking', 'libvirt-go', --=20 2.31.1 From nobody Sat May 4 23:03:20 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 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=1639753510; cv=none; d=zohomail.com; s=zohoarc; b=ekB9q9AQwFzmR6GB7ReJZhO+68uCN3cAb+wXtX0675cmTkJZdC8bc7Ykg4kwZZtwbA8vh7EjjcVwhocG1PP3fvYsNUSG4aD6uTC+XAR6jrPU39DWu4PUpIAYUt198jEGelk5IKmT7Ez8Qa4GWP4BWC6QfHl+gFO3Cr181EsRhrg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1639753510; 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=1VdUv0H4YB/raJQzB8ck5X0bLGQFTocS6j2K0fHI9Zw=; b=ZNlMrcgF9gBlQ/yXfPSarfNdcWffBiTeq0pwPl4FZcbXUKQIJIWk9ozZDi/SuM5j8gaxx+h02bp7pvSnMnUjyHIen0hU/jsbsPjmpJeQ1f8h6oQWDWX9J5iyqPnCHHVc1HAeR453VmDyVcteTj4QKyYXXduiXLhE9fHfMoWZZNI= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1639753510570100.91613617247356; Fri, 17 Dec 2021 07:05:10 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-245-BXE5TRMJPRux4j1fwXhoDg-1; Fri, 17 Dec 2021 10:05:06 -0500 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.phx2.redhat.com [10.5.11.15]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id F375E80417F; Fri, 17 Dec 2021 15:04:57 +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 C60E554510; Fri, 17 Dec 2021 15:04:57 +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 82EE24A7CB; Fri, 17 Dec 2021 15:04:57 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 1BHF4uQr025192 for ; Fri, 17 Dec 2021 10:04:56 -0500 Received: by smtp.corp.redhat.com (Postfix) id 03CD65ED40; Fri, 17 Dec 2021 15:04:56 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 5FB8A78A9E for ; Fri, 17 Dec 2021 15:04:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1639753509; 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=1VdUv0H4YB/raJQzB8ck5X0bLGQFTocS6j2K0fHI9Zw=; b=XJU/O7Ow9oG72XKOL1rFTH3LTbLS9M1DEQSkJ/dSGNAIo/+Yyee1QZsupOvBPEN5otHH+r x/gI09XqyyBYovJXAcbNGA+EZ7Ys8JOAitIk+AhYHiV2eJ1iwW12dfW62HhM6SRoddKdcD ihVX6p5B75in9yy+80Mq6bI6rFQwzeI= X-MC-Unique: BXE5TRMJPRux4j1fwXhoDg-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 2/7] storage: Introduce 'extended_l2' feature for storage volume Date: Fri, 17 Dec 2021 16:04:30 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 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.15 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1639753511172100003 Content-Type: text/plain; charset="utf-8" QCOW2 images now support 'extended_l2' which splits the default clusters into 32 subcluster allocation units. This allows the allocation units to be smaller without increasing the size of L2 table too much and thus also the cache requirements for holding the full L2 table in memory. Unfortunately it's incompatible with qemu versions older than 5.2 thus can't be used as default. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- docs/formatstorage.rst | 4 ++++ docs/schemas/storagecommon.rng | 5 +++++ src/conf/storage_source_conf.c | 1 + src/conf/storage_source_conf.h | 1 + src/storage/storage_util.c | 11 +++++++++++ tests/storagevolxml2argvdata/qcow2-clusterSize.argv | 2 +- tests/storagevolxml2xmlin/vol-qcow2-clusterSize.xml | 3 +++ tests/storagevolxml2xmlout/vol-qcow2-clusterSize.xml | 4 ++++ 8 files changed, 30 insertions(+), 1 deletion(-) diff --git a/docs/formatstorage.rst b/docs/formatstorage.rst index ae700fef4d..838b00de75 100644 --- a/docs/formatstorage.rst +++ b/docs/formatstorage.rst @@ -646,6 +646,7 @@ host filesystem. It can contain the following child ele= ments: 64 + @@ -708,6 +709,9 @@ host filesystem. It can contain the following child ele= ments: - ```` - allow delayed reference counter updates. :since:`Since 1.1.0` + - ```` - enables subcluster allocation for qcow2 images. = QCOW2 + clusters are split into 32 subclusters decreasing the size of L2 cache + needed. It's recommended to increase ``clusterSize``. Backing store elements ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/schemas/storagecommon.rng b/docs/schemas/storagecommon.rng index 591a158209..10f1bc6a15 100644 --- a/docs/schemas/storagecommon.rng +++ b/docs/schemas/storagecommon.rng @@ -134,6 +134,11 @@ + + + + + diff --git a/src/conf/storage_source_conf.c b/src/conf/storage_source_conf.c index c0acee189a..d42f715f26 100644 --- a/src/conf/storage_source_conf.c +++ b/src/conf/storage_source_conf.c @@ -66,6 +66,7 @@ VIR_ENUM_IMPL(virStorageFileFormat, VIR_ENUM_IMPL(virStorageFileFeature, VIR_STORAGE_FILE_FEATURE_LAST, "lazy_refcounts", + "extended_l2", ); diff --git a/src/conf/storage_source_conf.h b/src/conf/storage_source_conf.h index 40db29c418..c4a026881c 100644 --- a/src/conf/storage_source_conf.h +++ b/src/conf/storage_source_conf.h @@ -86,6 +86,7 @@ VIR_ENUM_DECL(virStorageFileFormat); typedef enum { VIR_STORAGE_FILE_FEATURE_LAZY_REFCOUNTS =3D 0, + VIR_STORAGE_FILE_FEATURE_EXTENDED_L2, VIR_STORAGE_FILE_FEATURE_LAST } virStorageFileFeature; diff --git a/src/storage/storage_util.c b/src/storage/storage_util.c index bfc3edb1fd..03874d6ca3 100644 --- a/src/storage/storage_util.c +++ b/src/storage/storage_util.c @@ -796,6 +796,17 @@ storageBackendCreateQemuImgOpts(virStorageEncryptionIn= foDef *encinfo, } virBufferAddLit(&buf, "lazy_refcounts,"); } + + if (virBitmapIsBitSet(info->features, + VIR_STORAGE_FILE_FEATURE_EXTENDED_L2)) { + if (STREQ_NULLABLE(info->compat, "0.10")) { + virReportError(VIR_ERR_CONFIG_UNSUPPORTED, + _("'extended_l2' not supported with compat = level %s"), + info->compat); + return -1; + } + virBufferAddLit(&buf, "extended_l2=3Don,"); + } } virBufferTrim(&buf, ","); diff --git a/tests/storagevolxml2argvdata/qcow2-clusterSize.argv b/tests/st= oragevolxml2argvdata/qcow2-clusterSize.argv index 8878a26818..c84fc8c47a 100644 --- a/tests/storagevolxml2argvdata/qcow2-clusterSize.argv +++ b/tests/storagevolxml2argvdata/qcow2-clusterSize.argv @@ -1,6 +1,6 @@ qemu-img \ create \ -f qcow2 \ --o compat=3D0.10,cluster_size=3D131072 \ +-o compat=3D1.1,cluster_size=3D131072,extended_l2=3Don \ /var/lib/libvirt/images/OtherDemo.img \ 5242880K diff --git a/tests/storagevolxml2xmlin/vol-qcow2-clusterSize.xml b/tests/st= oragevolxml2xmlin/vol-qcow2-clusterSize.xml index 22534982a1..2152a1f280 100644 --- a/tests/storagevolxml2xmlin/vol-qcow2-clusterSize.xml +++ b/tests/storagevolxml2xmlin/vol-qcow2-clusterSize.xml @@ -13,5 +13,8 @@ 128 + + + diff --git a/tests/storagevolxml2xmlout/vol-qcow2-clusterSize.xml b/tests/s= toragevolxml2xmlout/vol-qcow2-clusterSize.xml index 393a492536..40acb21ff8 100644 --- a/tests/storagevolxml2xmlout/vol-qcow2-clusterSize.xml +++ b/tests/storagevolxml2xmlout/vol-qcow2-clusterSize.xml @@ -12,6 +12,10 @@ 0 + 1.1 131072 + + + --=20 2.31.1 From nobody Sat May 4 23:03:20 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 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=1639753512; cv=none; d=zohomail.com; s=zohoarc; b=IT65ZtDYfXFSjt2xH3kKnuqlk8dP2sxU+bf+BGWAXwaud6FydSHwn2MmY4wJiQ3UwqSW/t237hrHgk57+6Ata0kvKTuSefoLC9VpbPH7JrqWZdASGEBbcZltHmBpDTyrBezWFeB2La3AQL8AbuJobO2fzsC+fUcZSjLUMMAEUkw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1639753512; 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=+QZ6+10/8RoVLUyvm81bLJoc6r6ku3LHcnfMLCjSl8M=; b=Dwevp2LLPJn0RqDmQ267FNk/NVwkCpY1CESyuk3bTD1c3wptgri2JWKAzN4OFVvvoq5qc4uHMdzpiHjzq5uNhAnNmLyB9PNnR7HoLHb0cadip4tPV2B6hTzAB+C2Iwb/qeoebxPB4/T0zQIVbIUKXB330RLl4bYBi+Nxf8PkxZs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1639753512537578.2134857043148; Fri, 17 Dec 2021 07:05:12 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-197-D6JZQROZN9mWWCbj5xuugg-1; Fri, 17 Dec 2021 10:05:07 -0500 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 B139387111D; Fri, 17 Dec 2021 15:05:00 +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 01C1284A23; Fri, 17 Dec 2021 15:04:59 +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 C03BE4A7CA; Fri, 17 Dec 2021 15:04:59 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 1BHF4vKL025203 for ; Fri, 17 Dec 2021 10:04:57 -0500 Received: by smtp.corp.redhat.com (Postfix) id 1322B5E26D; Fri, 17 Dec 2021 15:04:57 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6A1785ED54 for ; Fri, 17 Dec 2021 15:04:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1639753511; 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=+QZ6+10/8RoVLUyvm81bLJoc6r6ku3LHcnfMLCjSl8M=; b=O1jqW2d5g6zNXeZeNTjuQmHBlljAeUCrnNfbTlVxItbqqcbDPaPctzScY5gu3ajAWPzWFe Garlq07CY1XsPsU10LaNEjPISWWkkyUhLUcmI08k5xjXtpR9O9H8fmmsSKiYArA5zxQcma fRrd3ZqcIk4fesWj/hTJYwJIXnNO6Bg= X-MC-Unique: D6JZQROZN9mWWCbj5xuugg-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 3/7] qcow2GetFeatures: Extract population of features bitmap Date: Fri, 17 Dec 2021 16:04:31 +0100 Message-Id: <65f50f556df8dc095ef29c1c82e6add176a2c4a7.1639753439.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 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 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1639753513961100002 Content-Type: text/plain; charset="utf-8" Prepare for extraction of features from the 'incompatible features' group. This is done by moving the extraction loop into a new function called qcow2GetFeaturesProcessGroup. The new function also allows to ingore features we don't care about by passing VIR_STORAGE_FILE_FEATURE_LAST as the target flag. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- src/storage_file/storage_file_probe.c | 33 ++++++++++++++++++--------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/src/storage_file/storage_file_probe.c b/src/storage_file/stora= ge_file_probe.c index dc438a5e5d..f403e50938 100644 --- a/src/storage_file/storage_file_probe.c +++ b/src/storage_file/storage_file_probe.c @@ -344,7 +344,7 @@ enum qcow2CompatibleFeature { }; /* conversion to virStorageFileFeature */ -static const int qcow2CompatibleFeatureArray[] =3D { +static const virStorageFileFeature qcow2CompatibleFeatureArray[] =3D { VIR_STORAGE_FILE_FEATURE_LAZY_REFCOUNTS, }; G_STATIC_ASSERT(G_N_ELEMENTS(qcow2CompatibleFeatureArray) =3D=3D @@ -748,6 +748,22 @@ virStorageFileProbeFormatFromBuf(const char *path, } +static void +qcow2GetFeaturesProcessGroup(uint64_t bits, + const virStorageFileFeature *featuremap, + size_t nfeatures, + virBitmap *features) +{ + size_t i; + + for (i =3D 0; i < nfeatures; i++) { + if ((bits & ((uint64_t) 1 << i)) && + featuremap[i] !=3D VIR_STORAGE_FILE_FEATURE_LAST) + ignore_value(virBitmapSetBit(features, featuremap[i])); + } +} + + static int qcow2GetFeatures(virBitmap **features, int format, @@ -755,9 +771,6 @@ qcow2GetFeatures(virBitmap **features, ssize_t len) { int version =3D -1; - virBitmap *feat =3D NULL; - uint64_t bits; - size_t i; version =3D virReadBufInt32BE(buf + fileTypeInfo[format].versionOffset= ); @@ -767,16 +780,14 @@ qcow2GetFeatures(virBitmap **features, if (len < QCOW2v3_HDR_SIZE) return -1; - feat =3D virBitmapNew(VIR_STORAGE_FILE_FEATURE_LAST); + *features =3D virBitmapNew(VIR_STORAGE_FILE_FEATURE_LAST); /* todo: check for incompatible or autoclear features? */ - bits =3D virReadBufInt64BE(buf + QCOW2v3_HDR_FEATURES_COMPATIBLE); - for (i =3D 0; i < QCOW2_COMPATIBLE_FEATURE_LAST; i++) { - if (bits & ((uint64_t) 1 << i)) - ignore_value(virBitmapSetBit(feat, qcow2CompatibleFeatureArray= [i])); - } + qcow2GetFeaturesProcessGroup(virReadBufInt64BE(buf + QCOW2v3_HDR_FEATU= RES_COMPATIBLE), + qcow2CompatibleFeatureArray, + G_N_ELEMENTS(qcow2CompatibleFeatureArray), + *features); - *features =3D feat; return 0; } --=20 2.31.1 From nobody Sat May 4 23:03:20 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 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=1639753512; cv=none; d=zohomail.com; s=zohoarc; b=aAco5ZWZJKG80cVLDQl93JQkUcIczgRUXQ3Dd1ofETeNWkShqNsJo2Oe7btel3mHFJHNvEqp8Jm96aSwT9cPoObEWA7P6iaTrGCDZzGm6bWsZKhtP0Xq1FPHET/O7P1Wqag1aVpEeLqHjv4sj36DpQ6uxbUrQhX1wUB5OuUb95A= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1639753512; 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=kgKv0clQDu7SCaNxqlDnszDN469I1J/Vb54LsO9g2b4=; b=JUFvXNv0XaBZkSFtPZRRt1CfBb72+yTM2HlK+C7jB1ZK9i80aZNfAyTcFqHDfM3EqQG6ak6q7SLytMWhPeQPwUe7YizXI5Cmi3qzBcLTBP3bLc/jbNDNiMOt7c2RjzZLdEMEXlgjd+f8nBSioZcEUYRe9T687CceNzv0OOlYsnI= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1639753512337398.682256683173; Fri, 17 Dec 2021 07:05:12 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-282-twBztnfZMC2wYBIze49cYw-1; Fri, 17 Dec 2021 10:05:07 -0500 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 853D15A07E; Fri, 17 Dec 2021 15:05:01 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 28AB95E498; Fri, 17 Dec 2021 15:05:01 +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 DF42B1806D2D; Fri, 17 Dec 2021 15:05:00 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 1BHF4w8v025218 for ; Fri, 17 Dec 2021 10:04:58 -0500 Received: by smtp.corp.redhat.com (Postfix) id 1EDDE5ED40; Fri, 17 Dec 2021 15:04:58 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 7F4E25E26D for ; Fri, 17 Dec 2021 15:04:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1639753511; 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=kgKv0clQDu7SCaNxqlDnszDN469I1J/Vb54LsO9g2b4=; b=KK1nlQjSN5F3TbMMa/vY9z5pJzumO9gRjIiiYJ0ImSwkG6ZVkV3/XByru1mi8og4CjWfB8 loAn03UVfTrKnhAZfEZ9f67tQXU2PZzer57zz80aqzAF2nJjJDPX4fTY/grdd+5/vMPeJV 3Kofqv8BaAFSEGQBYjaNiqOdEMYXjDk= X-MC-Unique: twBztnfZMC2wYBIze49cYw-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 4/7] storage_file_probe: Add support for probing qcow2's incompatible features Date: Fri, 17 Dec 2021 16:04:32 +0100 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 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 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1639753513917100001 Content-Type: text/plain; charset="utf-8" Add machinery for probing the incompatible feature flags field and specifically extract whether the extended l2 feature (1 << 4) is present. For now we don't care abot the other features. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- src/storage_file/storage_file_probe.c | 28 ++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/src/storage_file/storage_file_probe.c b/src/storage_file/stora= ge_file_probe.c index f403e50938..effd9aaa7d 100644 --- a/src/storage_file/storage_file_probe.c +++ b/src/storage_file/storage_file_probe.c @@ -350,6 +350,28 @@ static const virStorageFileFeature qcow2CompatibleFeat= ureArray[] =3D { G_STATIC_ASSERT(G_N_ELEMENTS(qcow2CompatibleFeatureArray) =3D=3D QCOW2_COMPATIBLE_FEATURE_LAST); +/* qcow2 incompatible features in the order they appear on-disk */ +enum qcow2IncompatibleFeature { + QCOW2_INCOMPATIBLE_FEATURE_DIRTY =3D 0, + QCOW2_INCOMPATIBLE_FEATURE_CORRUPT, + QCOW2_INCOMPATIBLE_FEATURE_DATA_FILE, + QCOW2_INCOMPATIBLE_FEATURE_COMPRESSION, + QCOW2_INCOMPATIBLE_FEATURE_EXTL2, + + QCOW2_INCOMPATIBLE_FEATURE_LAST +}; + +/* conversion to virStorageFileFeature */ +static const virStorageFileFeature qcow2IncompatibleFeatureArray[] =3D { + VIR_STORAGE_FILE_FEATURE_LAST, /* QCOW2_INCOMPATIBLE_FEATURE_DIRTY */ + VIR_STORAGE_FILE_FEATURE_LAST, /* QCOW2_INCOMPATIBLE_FEATURE_CORRUPT */ + VIR_STORAGE_FILE_FEATURE_LAST, /* QCOW2_INCOMPATIBLE_FEATURE_DATA_FILE= */ + VIR_STORAGE_FILE_FEATURE_LAST, /* QCOW2_INCOMPATIBLE_FEATURE_COMPRESSI= ON */ + VIR_STORAGE_FILE_FEATURE_EXTENDED_L2, /* QCOW2_INCOMPATIBLE_FEATURE_EX= TL2 */ +}; +G_STATIC_ASSERT(G_N_ELEMENTS(qcow2IncompatibleFeatureArray) =3D=3D QCOW2_I= NCOMPATIBLE_FEATURE_LAST); + + static int cowGetBackingStore(char **res, int *format, @@ -782,12 +804,16 @@ qcow2GetFeatures(virBitmap **features, *features =3D virBitmapNew(VIR_STORAGE_FILE_FEATURE_LAST); - /* todo: check for incompatible or autoclear features? */ qcow2GetFeaturesProcessGroup(virReadBufInt64BE(buf + QCOW2v3_HDR_FEATU= RES_COMPATIBLE), qcow2CompatibleFeatureArray, G_N_ELEMENTS(qcow2CompatibleFeatureArray), *features); + qcow2GetFeaturesProcessGroup(virReadBufInt64BE(buf + QCOW2v3_HDR_FEATU= RES_INCOMPATIBLE), + qcow2IncompatibleFeatureArray, + G_N_ELEMENTS(qcow2IncompatibleFeatureArra= y), + *features); + return 0; } --=20 2.31.1 From nobody Sat May 4 23:03:20 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 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=1639753513; cv=none; d=zohomail.com; s=zohoarc; b=eIre3x+nsBAGtOKFGcNGdhuqnwxLMwrrcH82cID5j6Xi+KJjsSAnQM7mtUdtt8yf2w/+SlDu5x93RKHKNT/oMTrExnincwaYS5Wk9UUMOP9ix4CCOlzSEra8BTdBxcWScm8jputCxACPfdsgYuD4QQC8nYWETdj5gD3ZPIdFTYE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1639753513; 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=6lG7yG0B9EPtIYIg+86XoXCZ9rc0+Una7f8hBI416I0=; b=J1WoxXaI7A6NFhWpsmzXPIaPfDMHMnqhM/ajkFQPZgXnklMzgZftc7rg7+j/1EXijUxJnfIXKdo0R77APpYAOO+lzzuWQ3f0ApJLG87xaIKkS0qAqo5bHrGUuNwSB1NT9l4AzXCH/O5fbmMSyqdySiNDfTjx8vrHfaEK8/dJdlw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 163975351375191.99960929671784; Fri, 17 Dec 2021 07:05:13 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-98-4lnD2DALN_2g6mIGnUuhVQ-1; Fri, 17 Dec 2021 10:05:09 -0500 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 51BC2100F950; Fri, 17 Dec 2021 15:05:01 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id BC9C75E49C; Fri, 17 Dec 2021 15:05:00 +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 8A41C1806D1C; Fri, 17 Dec 2021 15:05:00 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 1BHF4xlP025228 for ; Fri, 17 Dec 2021 10:04:59 -0500 Received: by smtp.corp.redhat.com (Postfix) id 3041C5E26D; Fri, 17 Dec 2021 15:04:59 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 820AE5F906 for ; Fri, 17 Dec 2021 15:04:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1639753512; 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=6lG7yG0B9EPtIYIg+86XoXCZ9rc0+Una7f8hBI416I0=; b=JiX0kqDl2heTNB3HrjnZsDKTXNDgucD6zUzlnwHW9ipbblSfDS90sFcfMeeg5EysL1lUS1 hsE7d+oCVbz023+Ngbv1shd4gudouM4nrPPf8O204w6ohbljoYreUJ/r8zbA3a/ZDQbd+S Y6G2nPWKO1muxpgu8897o3LBlYQozHc= X-MC-Unique: 4lnD2DALN_2g6mIGnUuhVQ-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 5/7] qemuBlockStorageSourceCreateGetFormatPropsQcow2: Add support for 'extended-l2' feature Date: Fri, 17 Dec 2021 16:04:33 +0100 Message-Id: <71b627b8bdd5daae1bdb64d81b1c775dff02a2b7.1639753439.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 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 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1639753514900100005 Content-Type: text/plain; charset="utf-8" Allow creating the qcow2 with the new subcluster format if required. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- src/qemu/qemu_block.c | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/qemu/qemu_block.c b/src/qemu/qemu_block.c index 87dca40179..bff93e96ee 100644 --- a/src/qemu/qemu_block.c +++ b/src/qemu/qemu_block.c @@ -2441,18 +2441,23 @@ qemuBlockStorageSourceCreateGetFormatPropsQcow2(vir= StorageSource *src, { g_autoptr(virJSONValue) qcow2props =3D NULL; const char *qcow2version =3D NULL; + bool extendedL2 =3D false; if (STREQ_NULLABLE(src->compat, "0.10")) qcow2version =3D "v2"; else if (STREQ_NULLABLE(src->compat, "1.1")) qcow2version =3D "v3"; + if (src->features) + extendedL2 =3D virBitmapIsBitSet(src->features, VIR_STORAGE_FILE_F= EATURE_EXTENDED_L2); + if (virJSONValueObjectAdd(&qcow2props, "s:driver", "qcow2", "s:file", src->nodestorage, "U:size", src->capacity, "S:version", qcow2version, "P:cluster-size", src->clusterSize, + "B:extended-l2", extendedL2, NULL) < 0) return -1; --=20 2.31.1 From nobody Sat May 4 23:03:20 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 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=1639753568; cv=none; d=zohomail.com; s=zohoarc; b=TDCdH8ju/JYHq3csZ2Vtdoh7Z9v5gcSod38nDLE2qgIJXdVD4wxz07Px9wxO6BQvjniMODOUSI37gO9kW+/CLW/WPbXjeQ/k3RkmTRzKqW+hYew7vlIPNEdlJppdabgxr49grTkyLzUXJPEX9jCJRVe82cdSoh9fEfRrhVv4FgE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1639753568; 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=cIu+eAPqDI5WXW/m2b8+oWXfPGCbth9GwBQHS77C3JM=; b=YnH0izTHHlUduJjnjFec3KYOQga3r5FD8W/AGxbeSl+6+rHfPS/ffUaEtkRuFVsXSftkOSSLVdBWB4kK33d1NJa6hs1WMiKdmxNfRzYhSekrE/cpX1ZMvU5qwd9O1wPXcSRtEE5BXJ4xXdZmr9QvH7LE+mndzLsh9VJpfw3v8qA= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1639753568933960.8507681059008; Fri, 17 Dec 2021 07:06:08 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-546-nJ2KBnJXP3yRJtlDG1apXg-1; Fri, 17 Dec 2021 10:05:12 -0500 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 41131100F943; Fri, 17 Dec 2021 15:05:04 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 144604E2DB; Fri, 17 Dec 2021 15:05:04 +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 CA58E18095C9; Fri, 17 Dec 2021 15:05:03 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 1BHF50Td025241 for ; Fri, 17 Dec 2021 10:05:00 -0500 Received: by smtp.corp.redhat.com (Postfix) id 49DD35ED54; Fri, 17 Dec 2021 15:05:00 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9C5AC5E26D for ; Fri, 17 Dec 2021 15:04:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1639753567; 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=cIu+eAPqDI5WXW/m2b8+oWXfPGCbth9GwBQHS77C3JM=; b=QF8pC1svCysXsJFyX7MrwOB/xNlTZ2xy1kNxS77EkHDi0UKBj9oomca7ls8yqHCIu+6WJi jHM2P6jKFrXzIQS4ZP6KlZuj1f4+uyWQV7n+TG4590dRX9wrrmnaUriDqzelxpiOMMHoGw Rj0LlLtfmabAuLMgPI/zYP1E3x/JXZ0= X-MC-Unique: nJ2KBnJXP3yRJtlDG1apXg-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 6/7] qemu: monitor: Extract whether qcow2 image uses extended L2 allocation data Date: Fri, 17 Dec 2021 16:04:34 +0100 Message-Id: <432a7d354e1a53edc8c2e2313f0570d00353db24.1639753439.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 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 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1639753570060100001 Content-Type: text/plain; charset="utf-8" In order to be able to propagate image configuration to newly formatted images we need to be able to query it. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- src/qemu/qemu_monitor.h | 3 +++ src/qemu/qemu_monitor_json.c | 10 +++++++--- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/src/qemu/qemu_monitor.h b/src/qemu/qemu_monitor.h index 29746f0b8e..850e01f026 100644 --- a/src/qemu/qemu_monitor.h +++ b/src/qemu/qemu_monitor.h @@ -784,6 +784,9 @@ struct _qemuBlockNamedNodeData { /* image version */ bool qcow2v2; + + /* qcow2 subcluster allocation -> extended_l2 */ + bool qcow2extendedL2; }; GHashTable * diff --git a/src/qemu/qemu_monitor_json.c b/src/qemu/qemu_monitor_json.c index a3d6eca569..6eedc925c4 100644 --- a/src/qemu/qemu_monitor_json.c +++ b/src/qemu/qemu_monitor_json.c @@ -2806,9 +2806,13 @@ qemuMonitorJSONBlockGetNamedNodeDataWorker(size_t po= s G_GNUC_UNUSED, STREQ_NULLABLE(virJSONValueObjectGetString(format_specific, "type"= ), "qcow2")) { virJSONValue *qcow2props =3D virJSONValueObjectGetObject(format_sp= ecific, "data"); - if (qcow2props && - STREQ_NULLABLE(virJSONValueObjectGetString(qcow2props, "compat= "), "0.10")) - ent->qcow2v2 =3D true; + if (qcow2props) { + if (STREQ_NULLABLE(virJSONValueObjectGetString(qcow2props, "co= mpat"), "0.10")) + ent->qcow2v2 =3D true; + + ignore_value(virJSONValueObjectGetBoolean(qcow2props, "extende= d-l2", + &ent->qcow2extendedL= 2)); + } } if (virHashAddEntry(nodes, nodename, ent) < 0) --=20 2.31.1 From nobody Sat May 4 23:03:20 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 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=1639753518; cv=none; d=zohomail.com; s=zohoarc; b=EzbDOX4sXkrDmQ4NL23BRrw/w7Qx4be+UewwdJ2zSyT4jIl4OK9h59M6neeVGg+NJ/FWU2k+2jNYyL5uGTT1xlCESNi4x2Di6z7ZEJwSH/V+sQqYuSSuQstSbmSyHoI8oBg4LdHor9FBwXxDdHX/9WfiNdBB+8X4nLYfzdBVPAc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1639753518; 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=855T8HFrfGxSuIziDip4dd7TuBegAikjaqycZmdxKEs=; b=hus4X31UQNlHy+A+2LZ0TmfgEBp6g8sQjPqSbbY5QNEVcaAu9H0O8B43ZBdUl59lphm5zPmXt84dScxzBIIFF/+olwIdvmgdzC4apdC7aBAWvVxIpZNcH77WvSL2ljeiQ5SI4Iok6l+tduSPiqdW54ZNStvGpKBvm2AgzMRdSXs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1639753518268127.75594040272506; Fri, 17 Dec 2021 07:05:18 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-641-EzoG8zPHOGeY98zFCh_uZg-1; Fri, 17 Dec 2021 10:05:13 -0500 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 092B010A8B7A; Fri, 17 Dec 2021 15:05:04 +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 D059A5E49B; Fri, 17 Dec 2021 15:05:03 +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 91B684A7C9; Fri, 17 Dec 2021 15:05:03 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 1BHF510d025251 for ; Fri, 17 Dec 2021 10:05:01 -0500 Received: by smtp.corp.redhat.com (Postfix) id 557555ED40; Fri, 17 Dec 2021 15:05:01 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.10]) by smtp.corp.redhat.com (Postfix) with ESMTP id AC10A5F920 for ; Fri, 17 Dec 2021 15:05:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1639753517; 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=855T8HFrfGxSuIziDip4dd7TuBegAikjaqycZmdxKEs=; b=Mx+3Na+iWhty0tfmjeJwGC9LWKHHcb0CIYVNBHgljzLkGT0k+ityAJuzMULV2iJdTtOZM8 iQkQSmyMDV+9Nz+lm3EEQ+ldnoFaMl/WDQfv+HezrAqry2c8BkX5CNyvUEOSrqgZLEbkKo voUbHzu5IFet3zAEn3z+l/ol8NoXdVk= X-MC-Unique: EzoG8zPHOGeY98zFCh_uZg-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 7/7] qemuBlockStorageSourceCreateDetectSize: Propagate 'extended_l2' feature to new overlays Date: Fri, 17 Dec 2021 16:04:35 +0100 Message-Id: <768f86be46a57391447bfc497b3586de2c704888.1639753439.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 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 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1639753519124100001 Content-Type: text/plain; charset="utf-8" In cases where the qcow2 image is using subclusters/extended_l2 entries we should propagate them to the new images which are based on such images. Signed-off-by: Peter Krempa Reviewed-by: J=C3=A1n Tomko --- src/qemu/qemu_block.c | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/src/qemu/qemu_block.c b/src/qemu/qemu_block.c index bff93e96ee..2e606e99b4 100644 --- a/src/qemu/qemu_block.c +++ b/src/qemu/qemu_block.c @@ -2941,11 +2941,18 @@ qemuBlockStorageSourceCreateDetectSize(GHashTable *= blockNamedNodeData, return -1; } - /* propagate cluster size if the images are compatible */ + /* propagate properties of qcow2 images if possible*/ if (templ->format =3D=3D VIR_STORAGE_FILE_QCOW2 && - src->format =3D=3D VIR_STORAGE_FILE_QCOW2 && - src->clusterSize =3D=3D 0) - src->clusterSize =3D entry->clusterSize; + src->format =3D=3D VIR_STORAGE_FILE_QCOW2) { + if (src->clusterSize =3D=3D 0) + src->clusterSize =3D entry->clusterSize; + + if (entry->qcow2extendedL2) { + if (!src->features) + src->features =3D virBitmapNew(VIR_STORAGE_FILE_FEATURE_LA= ST); + ignore_value(virBitmapSetBit(src->features, VIR_STORAGE_FILE_F= EATURE_EXTENDED_L2)); + } + } if (src->format =3D=3D VIR_STORAGE_FILE_RAW) { src->physical =3D entry->capacity; --=20 2.31.1