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) or vstorage (since
3.1.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="iqn.2013-06.com.example:iscsi-pool"/>
<auth type='chap' username='myname'>
<secret usage='mycluster_myname'/>
</auth>
<vendor name="Acme"/>
<product name="model"/>
</source>
...
... <source> <device path='/dev/mapper/mpatha' part_separator='no'/> <format type='gpt'/> </source> ...
... <source> <adapter type='scsi_host' name='scsi_host1'/> </source> ...
...
<source>
<adapter type='scsi_host'>
<parentaddr unique_id='1'>
<address domain='0x0000' bus='0x00' slot='0x1f' addr='0x2'/>
</parentaddr>
</adapter>
</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,zfs,vstorage). May be repeated multiple times depending on backend driver. Contains a required attributepathwhich is either the fully qualified path to the block device node or foriscsithe iSCSI Qualified Name (IQN). Since 0.4.1An optional attribute
part_separatorfor eachpathmay be supplied. Valid values for the attribute may be either "yes" or "no". This attribute is to be used for adiskpool type using apathto 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 typegluster). May only occur once. Contains a single attributepathwhich is the fully qualified path to the backing directory or for anetfspool type usingformattype "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_hostcommand followed by a combination oflspciandvirsh nodedev-dumpxml scsi_hostNcommands to find thescsi_hostNto be used. Since 0.6.2It is further recommended to utilize the
parentaddrelement 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
nameattribute 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" adapter. Since 1.0.5 A "fc_host" capable scsi_hostN can be determined by usingvirsh nodedev-list --cap fc_host. Since 1.2.8Note: Regardless of whether a "scsi_host" adapter type is defined using a
nameor aparentaddr, it should refer to a real scsi_host adapter as found through avirsh nodedev-list scsi_hostandvirsh nodedev-dumpxml scsi_hostNon 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 thenodedev-dumpxmloutput 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'snodedev-dumpxmloutput parent field is generally "computer". This is a libvirt created parent value indicating no parent was defined for the node device.
wwnnandwwpn- 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"typepool instead. Thewwnnandwwpnhave 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. 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 order to ensure a new definition doesn't duplicate using the scsi_hostN of some existing storage pool. Since 1.0.4
parent_wwnnandparent_wwpn- Instead of the
parentto 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
parentto specify which scsi_host to use by name, it's possible to provide the fabric_wwn on which 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 device 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
nameattribute to more uniquely identify the SCSI host. Using a combination of theunique_idattribute and theaddresselement to formulate a PCI address, a search will be performed of the/sys/class/scsi_host/hostNNlinks for a matching PCI address with a matchingunique_idvalue in the/sys/class/scsi_host/hostNN/unique_idfile. The value in the "unique_id" file will be unique enough for the specific PCI address. ThehostNNwill be used by libvirt as the basis to define which SCSI host is to be used for the currently booted system. Since 1.2.7address- The PCI address of the scsi_host device to be used. Using
a PCI address provides consistent naming across system reboots
and kernel reloads. The address will have four attributes:
domain(a 2-byte hex integer, not currently used by qemu),bus(a hex value between 0 and 0xff, inclusive),slot(a hex value between 0x0 and 0x1f, inclusive), andfunction(a value between 0 and 7, inclusive). The PCI address can be determined by listing the/sys/bus/pci/devicesand the/sys/class/scsi_hostdirectories 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='0x0000' bus='0x00' slot='0x1f' function='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 resultingpathelement as the basis to formulate the correctly formatted PCI address.
unique_id- Required
parentaddrattribute used to determine which of the scsi_host adapters for the provided PCI address should be used. The value is determine by contents of theunique_idfile for the specific scsi_host adapter. For a PCI address of "0000:00:1f:2", the unique identifer files can be found using the commandfind -H /sys/class/scsi_host/host*/unique_id | xargs grep '[0-9]'. Optionally, thevirsh nodedev-dumpxml scsi_hostN' of a specific scsi_hostN list entry will list theunique_idvalue.
-
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 adirectoryordeviceelement. Contains an attributenamewhich is the hostname or IP address of the server. May optionally contain aportattribute 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 thedirectoryordeviceelement. 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 for any restrictions for specific storage backends. Since 0.4.1 -
auth - If present, the
authelement provides the authentication credentials needed to access the source by the setting of thetypeattribute (pool typesiscsi,rbd). Thetypemust 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 attributeusernameidentifies the username to use during authentication as well as a sub-elementsecretwith a mandatory attributetype, 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. Thesecretelement requires either auuidattribute with the UUID of the secret object or ausageattribute 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 attributetypewhose 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
namewhose value is backend specific. Since 0.8.4 -
product - Provides an optional product name of the storage device.
This contains a single attribute
namewhose 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, zfs).
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>
</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 pools
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. Forlogicalandzfspool types, a provided value is ignored and a default path generated. For a Multipath pool (typempath), 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 for the
final directory when the pool is built. There are 4 child elements.
The
modeelement contains the octal permission set. Themodedefaults to 0711 when not provided. Theownerelement contains the numeric user ID. Thegroupelement contains the numeric group ID. Ifownerorgrouparen't specified when creating a directory, the values are inherited from the parent directory. Thelabelelement 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 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, netdir or ploop), 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. For a disk pool, the
name must be combination of the
sourcedevice path device and next partition number to be created. For example, if thesourcedevice 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 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
logicalpool 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 attributeunitcan 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-characterunitsince 0.9.11 -
capacity - Providing the logical capacity for the volume. This value is
in bytes by default, but a
unitattribute can be specified with the same semantics as forallocationThis 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
unitwill 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 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>
<timestamps>
<atime>1341933637.273190990</atime>
<mtime>1341930622.047245868</mtime>
<ctime>1341930622.047245868</ctime>
</timestamps>
<encryption type='...'>
...
</encryption>
<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 table format type, but is
not preserved after a pool refresh or libvirtd restart. Use extended
in order to create an extended disk extent partition. 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
typeattribute. Consult the storage driver page for the list of valid volume format type values for each specific pool. Theformatwill 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
modeelement contains the octal permission set. Themodedefaults to 0600 when not provided. Theownerelement contains the numeric user ID. Thegroupelement contains the numeric group ID. Ifownerorgrouparen't specified when creating a supported volume, the values are inherited from the parent directory. Thelabelelement contains the MAC (eg SELinux) 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,ctimeandmtimehold 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='qcow2'volumes. Valid values are0.10and1.1so far, specifying QEMU version the images should be compatible with. If thefeatureelement 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 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
qcow2now. Valid sub-elements are:<lazy_refcounts/>- allow delayed reference counter updates. Since 1.1.0
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.
See volume
permissionsdocumentation 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 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>
Storage volume using LUKS ¶
<volume>
<name>MyLuks.img</name>
<capacity unit="G">5</capacity>
<target>
<path>/var/lib/virt/images/MyLuks.img</path>
<format type='raw'/>
<encryption format='luks'>
<secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
</encryption>
</target>
</volume>