Show Table of Contents
23.18. 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
23.18.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.
The elements that are used in this example are explained in the Table 23.27, “
| ||Provides a name for the storage pool which must be unique to the host physical machine. This is mandatory when defining a storage pool.|
| ||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.|
| ||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.|
| ||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.|
| ||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.18.2. Source Elements
<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.80. Source element option 1
... <source> <adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/> </source> ...
Figure 23.81. 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
| || Provides the source for storage pools backed by host physical machine devices (based on |
| || Provides the source for storage pools backed by directories (|
| || Provides the source for storage pools backed by SCSI adapters (|
| || Provides the source for storage pools backed by storage from a remote server (|
| || If present, the |
| || Provides the source for storage pools backed by a storage device from a named element |
| || Provides information about the format of the storage pool |
| || Provides optional information about the vendor of the storage device. This contains a single attribute |
| || Provides optional information about the product name of the storage device. This contains a single attribute |
23.18.3. Creating Target Elements
<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.82. Target elements XML example
The table (Table 23.29, “Target child elements”) explains the child elements that are valid for the parent
Table 23.29. Target child elements
| || 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, |
| || 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 |
| || Provides timing information about the storage volume. Up to four sub-elements are present, where |
| ||If present, specifies how the storage volume is encrypted. For more information, see libvirt upstream pages.|
23.18.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,
<end>which provide the boundaries of the extent on the device, measured in bytes.