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), or gluster (since 1.2.0). This corresponds to the storage backend drivers listed further along in this document.

General metadata

      <pool type="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. 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 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. Since 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

Source elements

A single source element is contained within the top level 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="iscsi.example.com"/>
          <device path="demo-target"/>
          <auth type='chap' username='myname'>
            <secret type='iscsi' usage='mycluster_myname'/>
          </auth>
          <vendor name="Acme"/>
          <product name="model"/>
        </source>
        ...
        ...
        <source>
          <adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/>
        </source>
        ...
device
Provides the source for pools backed by physical devices (pool types fs, logical, disk, iscsi). May be repeated multiple times depending on backend driver. Contains a single attribute path which is the fully qualified path to the block device node. Since 0.4.1
dir
Provides the source for pools backed by directories (pool type dir), 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. Since 0.4.1
adapter
Provides the source for pools backed by SCSI adapters (pool type scsi). May only occur once. Attribute name is the SCSI adapter name (ex. "scsi_host1". NB, although a name such as "host1" is still supported for backwards compatibility, it is not recommended). Attribute type (1.0.5) specifies the adapter type. Valid values are "fc_host" and "scsi_host". If omitted and the name attribute is specified, then it defaults to "scsi_host". To keep backwards compatibility, the attribute type is optional for the "scsi_host" adapter, but mandatory for the "fc_host" adapter. Attributes wwnn (Word Wide Node Name) and wwpn (Word Wide Port Name) (1.0.4) are used by the "fc_host" adapter to uniquely identify the device in the Fibre Channel storage fabric (the device can be either a HBA or vHBA). Both wwnn and wwpn should be specified (See command 'virsh nodedev-dumpxml' to known how to get wwnn/wwpn of a (v)HBA). The optional attribute parent (1.0.4) specifies the parent device for the "fc_host" adapter. Since 0.6.2
host
Provides the source for pools backed by storage from a remote server (pool types netfs, iscsi, rbd, sheepdog, gluster). Will 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. Since 0.4.1
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, 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
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 level pool element for some types of pools (pool types dir, fs, netfs, logical, disk, iscsi, scsi, mpath). This tag is used to describe the mapping of the storage pool into the host filesystem. It can contain the following 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>
          <timestamps>
            <atime>1341933637.273190990</atime>
            <mtime>1341930622.047245868</mtime>
            <ctime>1341930622.047245868</ctime>
          </timestamps>
          <encryption type='...'>
            ...
          </encryption>
        </target>
      </pool>
path
Provides the location at which the pool will be mapped into the local filesystem namespace. For a filesystem/directory based pool it will be the name of the directory in which volumes will be created. For device based pools it will be the 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. 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 for the final directory when the pool is built. The mode element contains the octal permission set. The owner element contains the numeric user ID. The group element contains the numeric group ID. The label element contains the MAC (eg SELinux) label string. 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.

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 freeExtent elements. Each of these elements contains two attributes, start and end which provide the boundaries of the extent on the device, measured in bytes. Since 0.4.1

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, or netdir), which is also available from virStorageVolGetInfo(). The storage volume XML format is available since 0.4.1

General metadata

      <volume type='file'>
        <name>sparse.img</name>
        <key>/var/lib/xen/images/sparse.img</key>
        <allocation>0</allocation>
        <capacity unit="T">1</capacity>
        ...
name
Providing a name for the volume which is unique to the pool. This is mandatory when defining a volume. 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 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
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 level volume element. This tag is used to describe the mapping of the storage volume into the host filesystem. It can contain the following child elements: 

        ...
        <target>
          <path>/var/lib/virt/images/sparse.img</path>
          <format type='qcow2'/>
          <permissions>
            <owner>107</owner>
            <group>107</group>
            <mode>0744</mode>
            <label>virt_image_t</label>
          </permissions>
          <compat>1.1</compat>
          <nocow/>
          <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 type. For filesystem 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 pool-specific docs for the list of valid values. Since 0.4.1
permissions
Provides information about the default 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. It contains 4 child elements. The mode element contains the octal permission set. The owner element contains the numeric user ID. The group element contains the numeric group ID. The label element contains the MAC (eg SELinux) label string. Since 0.4.1
compat
Specify compatibility level. So far, this is only used for type='qcow2' volumes. Valid values are 0.10 and 1.1 so far, specifying QEMU version the images should be compatible with. If the feature element is present, 1.1 is used. If omitted, qemu-img default is used. Since 1.1.0
nocow
Turn off COW of the newly created volume. So far, this is only valid 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
features
Format-specific features. Only used for qcow2 now. Valid sub-elements are:

Backing store elements

A single backingStore element is contained within the top level volume 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: 

        ...
        <backingStore>
          <path>/var/lib/virt/images/master.img</path>
          <format type='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 format. 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 attribute. Consult the pool-specific docs 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 store format. Since 0.6.0
permissions
Provides information about the permissions of the backing file. It contains 4 child elements. The mode element contains the octal permission set. The owner element contains the numeric user ID. The group element contains the numeric group ID. The label element contains the MAC (eg SELinux) label string. 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

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

iSCSI based storage pool

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

Storage volume

      <volume>
        <name>sparse.img</name>
        <allocation>0</allocation>
        <capacity unit="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>