23.19. Storage Pools

Although all storage pool back-ends 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 element for a storage pool document is <pool>. It has a single attribute type, which can take the following values: dir, fs, netfs, disk, iscsi, logical, scsi, mpath, rbd, sheepdog, or gluster.

23.19.1. Providing Metadata for the Storage Pool

The following XML example, shows the metadata tags that can be added to a storage pool. In this example, the pool is an iSCSI storage pool.
         
     <pool type="iscsi">
        <name>virtimages</name>
        <uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
        <allocation>10000000</allocation>
        <capacity>50000000</capacity>
        <available>40000000</available>
        ...
     </pool>
         

Figure 23.81. General metadata tags

The elements that are used in this example are explained in the Table 23.27, “virt-sysprep commands”.

Table 23.27. virt-sysprep commands

Element Description
<name> Provides a name for the storage pool which must be unique to the host physical machine. This is mandatory when defining a storage pool.
<uuid> Provides an identifier for the storage pool which must be globally unique. Although supplying the UUID is optional, if the UUID is not provided at the time the storage pool is created, a UUID will be automatically generated.
<allocation> Provides the total storage allocation for the storage pool. This may be larger than the sum of the total allocation across all storage volumes due to the metadata overhead. This value is expressed in bytes. This element is read-only and the value should not be changed.
<capacity> Provides 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 element is read-only and the value should not be changed.
<available> Provides the free space available for allocating new storage volumes in the storage pool. Due to underlying device constraints, it may not be possible to allocate the all of the free space to a single storage volume. This value is in bytes. This element is read-only and the value should not be changed.

23.19.2. Source Elements

Within the <pool> element there can be a single <source> element defined (only one). The child elements of <source> depend on the storage pool type. Some examples of the XML that can be used are as follows:
         
           ...
        <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>
        ...
         

Figure 23.82. Source element option 1

         
         ...
        <source>
          <adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/>
        </source>
        ...
         

Figure 23.83. Source element option 2

The child elements that are accepted by <source> are explained in Table 23.28, “Source child elements commands”.

Table 23.28. Source child elements commands

Element Description
<device> Provides the source for storage pools backed by host physical machine devices (based on <pool type=> (as shown in Section 23.19, “Storage Pools” )). May be repeated multiple times depending on back-end driver. Contains a single attribute path which is the fully qualified path to the block device node.
<dir> Provides the source for storage pools backed by directories (<pool type='dir'>), or optionally to select a subdirectory within a storage pool that is based on a filesystem (<pool type='gluster'>). This element may only occur once per (<pool>). This element accepts a single attribute (<path>) which is the full path to the backing directory.
<adapter> Provides the source for storage pools backed by SCSI adapters (<pool type='scsi'>). This element may only occur once per (<pool>). Attribute name is the SCSI adapter name (ex. "scsi_host1". Although "host1" is still supported for backwards compatibility, it is not recommended. Attribute type specifies the adapter type. Valid values are 'fc_host'| 'scsi_host'. If omitted and the name attribute is specified, then it defaults to type='scsi_host'. To keep backwards compatibility, the attribute type is optional for the type='scsi_host' adapter, but mandatory for the type='fc_host' adapter. Attributes wwnn (Word Wide Node Name) and wwpn (Word Wide Port Name) are used by the type='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. For instructions on how to get wwnn/wwpn of a (v)HBA, see Section 20.27.12, “Collect Device Configuration Settings”. The optional attribute parent specifies the parent device for the type='fc_host' adapter.
<host> Provides the source for storage pools backed by storage from a remote server (type='netfs'|'iscsi'|'rbd'|'sheepdog'|'gluster'). This element should be used in combination with a <directory> or <device> element. Contains an attribute name which is the host name or IP address of the server. May optionally contain a port attribute for the protocol specific port number.
<auth> If present, the <auth> element provides the authentication credentials needed to access the source by the setting of the type attribute (pool type='iscsi'|'rbd'). The type must be either type='chap' or type='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 user name 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.
<name> Provides the source for storage pools backed by a storage device from a named element <type> which can take the values: (type='logical'|'rbd'|'sheepdog','gluster').
<format> Provides information about the format of the storage pool <type> which can take the following values: type='logical'|'disk'|'fs'|'netfs'). Note that this value is back-end specific. This is typically used to indicate a filesystem type, or a network filesystem type, or a partition table type, or an LVM metadata type. As all drivers are required to have a default value for this, the element is optional.
<vendor> Provides optional information about the vendor of the storage device. This contains a single attribute <name> whose value is back-end specific.
<product> Provides optional information about the product name of the storage device. This contains a single attribute <name> whose value is back-end specific.

23.19.3. Creating Target Elements

A single <target> element is contained within the top level <pool> element for the following types: (type='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:
         
     <pool>
        ...
        <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>
         

Figure 23.84. Target elements XML example

The table (Table 23.29, “Target child elements”) explains the child elements that are valid for the parent <target> element:

Table 23.29. Target child elements

Element Description
<path> Provides the location at which the storage pool will be mapped into the local filesystem namespace. For a filesystem or directory-based storage pool it will be the name of the directory in which storage volumes will be created. For device-based storage pools it will be the name of the directory in which the device's nodes exist. For the latter, /dev/may seem like the logical choice, however, the device's nodes there are not guaranteed to be 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.
<permissions> This is currently only useful for directory- or filesystem-based storage 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 storage 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 (for example, SELinux) label string.
<timestamps> Provides timing information about the storage volume. Up to four sub-elements are present, where timestamps='atime'|'btime|'ctime'|'mtime' holds the access, birth, change, and modification time of the storage 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 operating system or filesystem, then the nanoseconds part is omitted. This is a read-only attribute and is ignored when creating a storage volume.
<encryption> If present, specifies how the storage volume is encrypted. For more information, see libvirt upstream pages.

23.19.4. Setting Device Extents

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