2013-05-03 18:25:37 +04:00
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
< html xmlns = "http://www.w3.org/1999/xhtml" >
2008-04-23 21:08:31 +04:00
< body >
< h1 > Storage pool and volume XML format< / h1 >
2008-05-07 03:23:55 +04:00
< ul id = "toc" > < / ul >
2008-04-23 21:08:31 +04:00
2008-05-07 03:23:55 +04:00
< h2 > < a name = "StoragePool" > Storage pool XML< / a > < / h2 >
< p >
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.
< / p >
< p >
2011-12-19 18:19:56 +04:00
The top level tag for a storage pool document is 'pool'. It has
2008-05-07 03:23:55 +04:00
a single attribute < code > type< / code > , which is one of < code > dir< / code > ,
2013-06-04 17:20:51 +04:00
< code > fs< / code > , < code > netfs< / code > , < code > disk< / code > ,
2013-10-16 02:59:48 +04:00
< code > iscsi< / code > , < code > logical< / code > , < code > scsi< / code >
(all < span class = "since" > since 0.4.1< / span > ), < code > mpath< / code >
(< span class = "since" > since 0.7.1< / span > ), < code > rbd< / code >
2013-10-16 03:06:18 +04:00
(< span class = "since" > since 0.9.13< / span > ), < code > sheepdog< / code >
(< span class = "since" > since 0.10.0< / span > ),
2014-09-14 09:17:54 +04:00
< code > gluster< / code > (< span class = "since" > since
1.2.0< / span > ) or < code > zfs< / code > (< span class = "since" > since
1.2.8< / span > ). This corresponds to the
2013-06-04 17:20:51 +04:00
storage backend drivers listed further along in this document.
2008-05-07 03:23:55 +04:00
< / p >
< h3 > < a name = "StoragePoolFirst" > General metadata< / a > < / h3 >
< pre >
< pool type="iscsi">
< name> virtimages< /name>
< uuid> 3e3fce45-4f53-4fa7-bb32-11f34168b82b< /uuid>
< allocation> 10000000< /allocation>
< capacity> 50000000< /capacity>
< available> 40000000< /available>
...< / pre >
< dl >
< dt > < code > name< / code > < / dt >
< dd > Providing a name for the pool which is unique to the host.
2009-11-06 18:04:19 +03:00
This is mandatory when defining a pool. < span class = "since" > Since 0.4.1< / span > < / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > uuid< / code > < / dt >
< dd > Providing an identifier for the pool which is globally unique.
2009-11-06 18:04:19 +03:00
This is optional when defining a pool, a UUID will be generated if
omitted. < span class = "since" > Since 0.4.1< / span > < / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > allocation< / code > < / dt >
< dd > Providing the total storage allocation for the pool. This may
2009-11-06 18:04:19 +03:00
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. < span class = "since" > Since 0.4.1< / span > < / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > capacity< / code > < / dt >
< dd > Providing the total storage capacity for the pool. Due to
2009-11-06 18:04:19 +03:00
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. < span class = "since" > Since 0.4.1< / span > < / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > available< / code > < / dt >
< dd > Providing the free space available for allocating new volumes
2009-11-06 18:04:19 +03:00
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. < span class = "since" > Since 0.4.1< / span > < / dd >
2008-05-07 03:23:55 +04:00
< / dl >
< h3 > < a name = "StoragePoolSource" > Source elements< / a > < / h3 >
< p >
A single < code > source< / code > element is contained within the top level
< code > pool< / code > element. This tag is used to describe the source of
2013-10-16 02:59:48 +04:00
the storage pool. The set of child elements that it will contain
depend on the pool type, but come from the following child elements:
2008-05-07 03:23:55 +04:00
< / p >
< pre >
...
< source>
< host name="iscsi.example.com"/>
< device path="demo-target"/>
2013-07-13 22:29:55 +04:00
< auth type='chap' username='myname'>
< secret type='iscsi' usage='mycluster_myname'/>
< /auth>
2010-08-17 21:44:27 +04:00
< vendor name="Acme"/>
2010-11-25 12:40:07 +03:00
< product name="model"/>
2008-05-07 03:23:55 +04:00
< /source>
2009-11-06 18:04:19 +03:00
...< / pre >
2008-05-07 03:23:55 +04:00
2014-03-04 07:15:13 +04:00
< pre >
...
< source>
< adapter type='scsi_host' name='scsi_host1'/>
< /source>
...< / pre >
< pre >
...
< source>
< adapter type='scsi_host'>
< parentaddr unique_id='1'>
< address domain='0x0000' bus='0x00' slot='0x1f' addr='0x2'/>
< /parentaddr>
< /adapter>
< /source>
...< / pre >
2013-03-25 20:43:36 +04:00
< pre >
...
< source>
< adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/>
< /source>
...< / pre >
2008-05-07 03:23:55 +04:00
< dl >
< dt > < code > device< / code > < / dt >
2013-10-16 02:59:48 +04:00
< dd > Provides the source for pools backed by physical devices
(pool types < code > fs< / code > , < code > logical< / code > , < code > disk< / code > ,
2014-09-14 09:17:54 +04:00
< code > iscsi< / code > , < code > zfs< / code > ).
2009-11-06 18:04:19 +03:00
May be repeated multiple times depending on backend driver. Contains
a single attribute < code > path< / code > which is the fully qualified
path to the block device node. < span class = "since" > Since 0.4.1< / span > < / dd >
2013-10-16 02:59:48 +04:00
< dt > < code > dir< / code > < / dt >
< dd > Provides the source for pools backed by directories (pool
2013-10-16 03:06:18 +04:00
type < code > dir< / code > ), or optionally to select a subdirectory
within a pool that resembles a filesystem (pool
type < code > gluster< / code > ). May
2009-11-06 18:04:19 +03:00
only occur once. Contains a single attribute < code > path< / code >
2013-03-19 15:43:20 +04:00
which is the fully qualified path to the backing directory.
2009-11-06 18:04:19 +03:00
< span class = "since" > Since 0.4.1< / span > < / dd >
2010-02-23 00:50:04 +03:00
< dt > < code > adapter< / code > < / dt >
2013-10-16 02:59:48 +04:00
< dd > Provides the source for pools backed by SCSI adapters (pool
2014-03-04 07:15:13 +04:00
type < code > scsi< / code > ). May only occur once.
< dl >
< dt > < code > name< / code > < / dt >
< dd > 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 < code > virsh nodedev-list
scsi_host< / code > command followed by a combination of
< code > lspci< / code > and < code > virsh nodedev-dumpxml
scsi_hostN< / code > commands to find the < code > scsi_hostN< / code >
to be used. < span class = "since" > Since 0.6.2< / span >
< p >
It is further recommended to utilize the
< code > parentaddr< / code > element since it's possible to have
the path to which the scsi_hostN uses change between system
reboots. < span class = "since" > Since 1.2.7< / span >
< / p >
< / dd >
< / dl >
< dl >
< dt > < code > type< / code > < / dt >
< dd > Specifies the adapter type. Valid values are "scsi_host" or
"fc_host". If omitted and the < code > name< / code > attribute is
specified, then it defaults to "scsi_host". To keep backwards
compatibility, this attribute is optional < b > only< / b > for the
"scsi_host" adapter, but is mandatory for the "fc_host" adapter.
< span class = "since" > Since 1.0.5< / span >
< / dd >
< / dl >
< dl >
< dt > < code > wwwn< / code > and < code > wwpn< / code > < / dt >
< dd > The "World Wide Node Name" (< code > wwnn< / code > ) and "World Wide
Port Name" (< code > wwpn< / code > ) 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. Use the command 'virsh nodedev-dumpxml' to determine
2014-11-06 20:22:58 +03:00
how to set the values for the wwnn/wwpn of a (v)HBA. The wwnn and
wwpn have very specific numerical 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".
2014-03-04 07:15:13 +04:00
< span class = "since" > Since 1.0.4< / span >
< / dd >
< / dl >
< dl >
< dt > < code > parent< / code > < / dt >
< dd > Used by the "fc_host" adapter type to optionally specify the
parent scsi_host device defined in the
< a href = "formatnode.html" > Node Device< / a > database as the
< a href = "http://wiki.libvirt.org/page/NPIV_in_libvirt" > NPIV< / a >
2014-11-06 20:22:58 +03:00
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.
2014-03-04 07:15:13 +04:00
< span class = "since" > Since 1.0.4< / span >
< / dd >
storage: Introduce 'managed' for the fchost parent
https://bugzilla.redhat.com/show_bug.cgi?id=1160926
Introduce a 'managed' attribute to allow libvirt to decide whether to
delete a vHBA vport created via external means such as nodedev-create.
The code currently decides whether to delete the vHBA based solely on
whether the parent was provided at creation time. However, that may not
be the desired action, so rather than delete and force someone to create
another vHBA via an additional nodedev-create allow the configuration of
the storage pool to decide the desired action.
During createVport when libvirt does the VPORT_CREATE, set the managed
value to YES if not already set to indicate to the deleteVport code that
it should delete the vHBA when the pool is destroyed.
If libvirtd is restarted all the memory only state was lost, so for a
persistent storage pool, use the virStoragePoolSaveConfig in order to
write out the managed value.
Because we're now saving the current configuration, we need to be sure
to not save the parent in the output XML if it was undefined at start.
Saving the name would cause future starts to always use the same parent
which is not the expected result when not providing a parent. By not
providing a parent, libvirt is expected to find the best available
vHBA port for each subsequent (re)start.
At deleteVport, use the new managed value to decide whether to execute
the VPORT_DELETE. Since we no longer save the parent in memory or in
XML when provided, if it was not provided, then we have to look it up.
2014-11-10 19:19:51 +03:00
< dt > < code > managed< / code > < / dt >
< dd > 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.
< span class = "since" > Since 1.2.11< / span >
< / dd >
2014-03-04 07:15:13 +04:00
< / dl >
< dl >
< dt > < code > parentaddr< / code > < / dt >
< dd > Used by the "scsi_host" adapter type instead of the
< code > name< / code > attribute to more uniquely identify the
SCSI host. Using a combination of the < code > unique_id< / code >
attribute and the < code > address< / code > element to formulate
a PCI address, a search will be performed of the
< code > /sys/class/scsi_host/hostNN< / code > links for a
matching PCI address with a matching < code > unique_id< / code >
value in the < code > /sys/class/scsi_host/hostNN/unique_id< / code >
file. The value in the "unique_id" file will be unique enough
for the specific PCI address. The < code > hostNN< / code > will be
used by libvirt as the basis to define which SCSI host is to
be used for the currently booted system.
< span class = "since" > Since 1.2.7< / span >
< dl >
< dt > < code > address< / code > < / dt >
< dd > 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:
< code > domain< / code > (a 2-byte hex integer, not currently used
by qemu), < code > bus< / code > (a hex value between 0 and 0xff,
inclusive), < code > slot< / code > (a hex value between 0x0 and
0x1f, inclusive), and < code > function< / code > (a value between
0 and 7, inclusive). The PCI address can be determined by
listing the < code > /sys/bus/pci/devices< / code > and the
< code > /sys/class/scsi_host< / code > 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='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 resulting
< code > path< / code > element as the basis to formulate the
correctly formatted PCI address.
< / dd >
< / dl >
< dl >
< dt > < code > unique_id< / code > < / dt >
< dd > Required < code > parentaddr< / code > attribute used to determine
which of the scsi_host adapters for the provided PCI address
should be used. The value is determine by contents of the
< code > unique_id< / code > file for the specific scsi_host adapter.
For a PCI address of "0000:00:1f:2", the unique identifer files
can be found using the command
< code > find -H /sys/class/scsi_host/host*/unique_id |
2014-06-10 15:47:12 +04:00
xargs grep '[0-9]'< / code > . Optionally, the
< code > virsh nodedev-dumpxml scsi_hostN< / code > ' of a
specific scsi_hostN list entry will list the
< code > unique_id< / code > value.
2014-03-04 07:15:13 +04:00
< / dd >
< / dl >
< / dd >
< / dl >
< / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > host< / code > < / dt >
< dd > Provides the source for pools backed by storage from a
2013-10-16 02:59:48 +04:00
remote server (pool types < code > netfs< / code > , < code > iscsi< / code > ,
2013-10-16 03:06:18 +04:00
< code > rbd< / code > , < code > sheepdog< / code > , < code > gluster< / code > ). Will be
2013-10-16 02:59:48 +04:00
used in combination with a < code > directory< / code >
2009-11-06 18:04:19 +03:00
or < code > device< / code > element. Contains an attribute < code > name< / code >
which is the hostname or IP address of the server. May optionally
contain a < code > port< / code > attribute for the protocol specific
port number. < span class = "since" > Since 0.4.1< / span > < / dd >
2013-07-13 22:29:55 +04:00
< dt > < code > auth< / code > < / dt >
< dd > If present, the < code > auth< / code > element provides the
authentication credentials needed to access the source by the
2013-10-16 02:59:48 +04:00
setting of the < code > type< / code > attribute (pool
types < code > iscsi< / code > , < code > rbd< / code > ). The < code > type< / code >
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
2013-07-13 22:29:55 +04:00
< code > username< / code > identifies the username to use during
authentication as well as a sub-element < code > secret< / code > with
a mandatory attribute < code > type< / code > , to tie back to a
< a href = "formatsecret.html" > libvirt secret object< / a > that
holds the actual password or other credentials. The domain XML
intentionally does not expose the password, only the reference
2013-10-16 02:59:48 +04:00
to the object that manages the password.
2013-07-13 22:29:55 +04:00
The < code > secret< / code > element requires either a < code > uuid< / code >
attribute with the UUID of the secret object or a < code > usage< / code >
attribute matching the key that was specified in the
secret object. < span class = "since" > Since 0.9.7 for "ceph" and
1.1.1 for "chap"< / span >
< / dd >
2008-09-02 18:15:42 +04:00
< dt > < code > name< / code > < / dt >
< dd > Provides the source for pools backed by storage from a
2013-10-16 02:59:48 +04:00
named element (pool types < code > logical< / code > , < code > rbd< / code > ,
2013-10-16 03:06:18 +04:00
< code > sheepdog< / code > , < code > gluster< / code > ). Contains a
string identifier.
2009-11-06 18:04:19 +03:00
< span class = "since" > Since 0.4.5< / span > < / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > format< / code > < / dt >
2013-10-16 02:59:48 +04:00
< dd > Provides information about the format of the pool (pool
types < code > fs< / code > , < code > netfs< / code > , < code > disk< / code > ,
< code > logical< / code > ). This
2009-11-06 18:04:19 +03:00
contains a single attribute < code > type< / code > 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. < span class = "since" > Since 0.4.1< / span > < / dd >
2010-08-17 21:44:27 +04:00
< dt > < code > vendor< / code > < / dt >
< dd > Provides optional information about the vendor of the
storage device. This contains a single
attribute < code > name< / code > whose value is backend
specific. < span class = "since" > Since 0.8.4< / span > < / dd >
< dt > < code > product< / code > < / dt >
< dd > Provides an optional product name of the storage device.
This contains a single attribute < code > name< / code > whose value
is backend specific. < span class = "since" > Since 0.8.4< / span > < / dd >
2008-05-07 03:23:55 +04:00
< / dl >
< h3 > < a name = "StoragePoolTarget" > Target elements< / a > < / h3 >
< p >
A single < code > target< / code > element is contained within the top level
2013-10-16 02:59:48 +04:00
< code > pool< / code > element for some types of pools (pool
types < code > dir< / code > , < code > fs< / code > , < code > netfs< / code > ,
< code > logical< / code > , < code > disk< / code > , < code > iscsi< / code > ,
< code > scsi< / code > , < code > mpath< / code > ). This tag is used to
describe the mapping of
2008-05-07 03:23:55 +04:00
the storage pool into the host filesystem. It can contain the following
child elements:
< / p >
< pre >
...
< target>
< path> /dev/disk/by-path< /path>
< permissions>
2009-12-14 18:23:26 +03:00
< owner> 107< /owner>
< group> 107< /group>
2008-05-07 03:23:55 +04:00
< mode> 0744< /mode>
< label> virt_image_t< /label>
< /permissions>
2012-07-25 11:43:37 +04:00
< timestamps>
< atime> 1341933637.273190990< /atime>
< mtime> 1341930622.047245868< /mtime>
< ctime> 1341930622.047245868< /ctime>
< /timestamps>
2009-07-21 02:28:11 +04:00
< encryption type='...'>
...
< /encryption>
2008-05-07 03:23:55 +04:00
< /target>
< /pool> < / pre >
< dl >
< dt > < code > path< / code > < / dt >
< dd > Provides the location at which the pool will be mapped into
2009-11-06 18:04:19 +03:00
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 < code > /dev/< / code > 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 < code > /dev/disk/by-{path,id,uuid,label< / code > locations.
< span class = "since" > Since 0.4.1< / span >
2008-05-07 03:23:55 +04:00
< / dd >
< dt > < code > permissions< / code > < / dt >
2013-08-13 16:38:33 +04:00
< dd > 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
2009-11-06 18:04:19 +03:00
< code > mode< / code > element contains the octal permission set. The
< code > owner< / code > element contains the numeric user ID. The < code > group< / code >
element contains the numeric group ID. The < code > label< / code > element
contains the MAC (eg SELinux) label string.
< span class = "since" > Since 0.4.1< / span >
2008-05-07 03:23:55 +04:00
< / dd >
2012-07-25 11:43:37 +04:00
< dt > < code > timestamps< / code > < / dt >
< dd > Provides timing information about the volume. Up to four
sub-elements are present,
where < code > atime< / code > , < code > btime< / code > , < code > ctime< / code >
and < code > mtime< / code > 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.
< span class = "since" > Since 0.10.0< / span >
< / dd >
2009-07-21 02:28:11 +04:00
< dt > < code > encryption< / code > < / dt >
< dd > If present, specifies how the volume is encrypted. See
the < a href = "formatstorageencryption.html" > Storage Encryption< / a > page
for more information.
< / dd >
2008-05-07 03:23:55 +04:00
< / dl >
< h3 > < a name = "StoragePoolExtents" > Device extents< / a > < / h3 >
< p >
If a storage pool exposes information about its underlying
placement / allocation scheme, the < code > device< / code > element
within the < code > source< / code > 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
< / p >
< p >
For storage pools supporting extent information, within each
< code > device< / code > element there will be zero or more < code > freeExtent< / code >
elements. Each of these elements contains two attributes, < code > start< / code >
and < code > end< / code > which provide the boundaries of the extent on the
device, measured in bytes. < span class = "since" > Since 0.4.1< / span >
< / p >
< h2 > < a name = "StorageVol" > Storage volume XML< / a > < / h2 >
< p >
2013-11-20 00:14:54 +04:00
A storage volume will generally be either a file or a device
node; < span class = "since" > since 1.2.0< / span > , an optional
output-only attribute < code > type< / code > lists the actual type
2013-11-19 03:43:06 +04:00
(file, block, dir, network, or netdir), which is also available
2013-11-20 00:14:54 +04:00
from < code > virStorageVolGetInfo()< / code > . The storage volume
XML format is available < span class = "since" > since 0.4.1< / span >
2008-05-07 03:23:55 +04:00
< / p >
< h3 > < a name = "StorageVolFirst" > General metadata< / a > < / h3 >
< pre >
2013-11-20 00:14:54 +04:00
< volume type='file'>
2009-11-06 18:04:19 +03:00
< name> sparse.img< /name>
< key> /var/lib/xen/images/sparse.img< /key>
2008-05-07 03:23:55 +04:00
< allocation> 0< /allocation>
2009-11-06 18:04:19 +03:00
< capacity unit="T"> 1< /capacity>
2008-05-07 03:23:55 +04:00
...< / pre >
< dl >
< dt > < code > name< / code > < / dt >
< dd > Providing a name for the volume which is unique to the pool.
2009-11-06 18:04:19 +03:00
This is mandatory when defining a volume. < span class = "since" > Since 0.4.1< / span > < / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > key< / code > < / dt >
2014-03-03 19:39:40 +04:00
< dd > 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.
2010-02-22 23:54:06 +03:00
< span class = "since" > Since 0.4.1< / span > < / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > allocation< / code > < / dt >
< dd > Providing the total storage allocation for the volume. This
2009-11-06 18:04:19 +03:00
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 < strong > option< / strong > of deciding
to sparsely allocate a volume. It does not have to honour requests
2013-03-11 17:42:40 +04:00
for sparse allocation though. Different types of pools may treat
sparse volumes differently. For example, the < code > logical< / code >
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.< br / >
2010-02-22 23:52:14 +03:00
< br / >
2012-03-02 19:23:07 +04:00
By default this is specified in bytes, but an optional attribute
2010-02-22 23:52:14 +03:00
< code > unit< / code > can be specified to adjust the passed value.
2012-03-06 01:06:33 +04:00
Values can be: 'B' or 'bytes' for bytes, 'KB' (kilobytes,
10< sup > 3< / sup > or 1000 bytes), 'K' or 'KiB' (kibibytes,
2< sup > 10< / sup > or 1024 bytes), 'MB' (megabytes, 10< sup > 6< / sup >
or 1,000,000 bytes), 'M' or 'MiB' (mebibytes, 2< sup > 20< / sup >
or 1,048,576 bytes), 'GB' (gigabytes, 10< sup > 9< / sup > or
1,000,000,000 bytes), 'G' or 'GiB' (gibibytes, 2< sup > 30< / sup >
or 1,073,741,824 bytes), 'TB' (terabytes, 10< sup > 12< / sup > or
1,000,000,000,000 bytes), 'T' or 'TiB' (tebibytes,
2< sup > 40< / sup > or 1,099,511,627,776 bytes), 'PB' (petabytes,
10< sup > 15< / sup > or 1,000,000,000,000,000 bytes), 'P' or 'PiB'
(pebibytes, 2< sup > 50< / sup > or 1,125,899,906,842,624 bytes),
'EB' (exabytes, 10< sup > 18< / sup > or 1,000,000,000,000,000,000
bytes), or 'E' or 'EiB' (exbibytes, 2< sup > 60< / sup > or
1,152,921,504,606,846,976 bytes). < span class = "since" > Since
0.4.1, multi-character < code > unit< / code > since
0.9.11< / span > < / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > capacity< / code > < / dt >
< dd > Providing the logical capacity for the volume. This value is
2010-02-22 23:52:14 +03:00
in bytes by default, but a < code > unit< / code > attribute can be
specified with the same semantics as for < code > allocation< / code >
This is compulsory when creating a volume.
2009-11-06 18:04:19 +03:00
< span class = "since" > Since 0.4.1< / span > < / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > source< / code > < / dt >
< dd > Provides information about the underlying storage allocation
2009-11-06 18:04:19 +03:00
of the volume. This may not be available for some pool types.
< span class = "since" > Since 0.4.1< / span > < / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > target< / code > < / dt >
< dd > Provides information about the representation of the volume
2009-11-06 18:04:19 +03:00
on the local host. < span class = "since" > Since 0.4.1< / span > < / dd >
2008-05-07 03:23:55 +04:00
< / dl >
< h3 > < a name = "StorageVolTarget" > Target elements< / a > < / h3 >
< p >
A single < code > target< / code > element is contained within the top level
< code > volume< / code > element. This tag is used to describe the mapping of
the storage volume into the host filesystem. It can contain the following
child elements:
< / p >
< pre >
...
2009-11-06 18:04:19 +03:00
< target>
2008-05-07 03:23:55 +04:00
< path> /var/lib/virt/images/sparse.img< /path>
2009-05-21 12:03:13 +04:00
< format type='qcow2'/>
2008-05-07 03:23:55 +04:00
< permissions>
2009-12-14 18:23:26 +03:00
< owner> 107< /owner>
< group> 107< /group>
2008-05-07 03:23:55 +04:00
< mode> 0744< /mode>
< label> virt_image_t< /label>
< /permissions>
2013-05-16 14:38:26 +04:00
< compat> 1.1< /compat>
2014-07-15 12:49:46 +04:00
< nocow/>
2013-05-16 14:38:26 +04:00
< features>
< lazy_refcounts/>
< /features>
2009-11-06 18:04:19 +03:00
< /target> < / pre >
2008-05-07 03:23:55 +04:00
< dl >
< dt > < code > path< / code > < / dt >
2008-12-04 17:51:57 +03:00
< dd > Provides the location at which the volume can be accessed on
2009-11-06 18:04:19 +03:00
the local filesystem, as an absolute path. This is a readonly
attribute, so shouldn't be specified when creating a volume.
< span class = "since" > Since 0.4.1< / span > < / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > format< / code > < / dt >
< dd > Provides information about the pool specific volume format.
2009-11-06 18:04:19 +03:00
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
2014-07-23 16:36:50 +04:00
the < code > type< / code > attribute. Consult the
< a href = "storage.html" > storage driver page< / a > for the list of valid
volume format type values for each specific pool. The
< code > format< / code > will be ignored on input for pools without a
volume format type value and the default pool format will be used.
< span class = "since" > Since 0.4.1< / span > < / dd >
2008-05-07 03:23:55 +04:00
< dt > < code > permissions< / code > < / dt >
< dd > Provides information about the default permissions to use
2009-11-06 18:04:19 +03:00
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
< code > mode< / code > element contains the octal permission set. The
< code > owner< / code > element contains the numeric user ID. The < code > group< / code >
element contains the numeric group ID. The < code > label< / code > element
contains the MAC (eg SELinux) label string.
< span class = "since" > Since 0.4.1< / span >
2008-05-07 03:23:55 +04:00
< / dd >
2013-05-16 14:38:26 +04:00
< dt > < code > compat< / code > < / dt >
< dd > Specify compatibility level. So far, this is only used for
< code > type='qcow2'< / code > volumes. Valid values are < code > 0.10< / code >
and < code > 1.1< / code > so far, specifying QEMU version the images should
be compatible with. If the < code > feature< / code > element is present,
1.1 is used. If omitted, qemu-img default is used.
2013-06-25 17:25:29 +04:00
< span class = "since" > Since 1.1.0< / span >
2013-05-16 14:38:26 +04:00
< / dd >
2014-07-15 12:49:46 +04:00
< dt > < code > nocow< / code > < / dt >
< dd > 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. < span class = "since" > Since 1.2.7< / span >
< / dd >
2013-05-16 14:38:26 +04:00
< dt > < code > features< / code > < / dt >
< dd > Format-specific features. Only used for < code > qcow2< / code > now.
Valid sub-elements are:
< ul >
< li > < code > < lazy_refcounts/> < / code > - allow delayed reference
2013-06-25 17:25:29 +04:00
counter updates. < span class = "since" > Since 1.1.0< / span > < / li >
2013-05-16 14:38:26 +04:00
< / ul >
< / dd >
2008-05-07 03:23:55 +04:00
< / dl >
2009-01-27 21:30:03 +03:00
< h3 > < a name = "StorageVolBacking" > Backing store elements< / a > < / h3 >
< p >
A single < code > backingStore< / code > element is contained within the top level
< code > volume< / code > 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:
< / p >
< pre >
...
< backingStore>
< path> /var/lib/virt/images/master.img< /path>
2010-02-23 00:01:12 +03:00
< format type='raw'/>
2009-01-27 21:30:03 +03:00
< permissions>
2009-12-14 18:23:26 +03:00
< owner> 107< /owner>
< group> 107< /group>
2009-01-27 21:30:03 +03:00
< mode> 0744< /mode>
< label> virt_image_t< /label>
< /permissions>
< /backingStore>
< /volume> < / pre >
< dl >
< dt > < code > path< / code > < / dt >
< dd > Provides the location at which the backing store can be accessed on
2009-11-06 18:04:19 +03:00
the local filesystem, as an absolute path. If omitted, there is no
2009-01-27 21:30:03 +03:00
backing store for this volume.
2009-11-06 18:04:19 +03:00
< span class = "since" > Since 0.6.0< / span > < / dd >
2009-01-27 21:30:03 +03:00
< dt > < code > format< / code > < / dt >
< dd > Provides information about the pool specific backing store format.
2009-11-06 18:04:19 +03:00
For disk pools it will provide the partition type. For filesystem
or directory pools it will provide the file format type, eg cow,
2010-02-23 00:01:12 +03:00
qcow, vmdk, raw. The actual format is specified via the type attribute.
Consult the pool-specific docs for the list of valid
2009-01-27 21:30:03 +03:00
values. Most file formats require a backing store of the same format,
however, the qcow2 format allows a different backing store format.
< span class = "since" > Since 0.6.0< / span > < / dd >
< dt > < code > permissions< / code > < / dt >
< dd > Provides information about the permissions of the backing file.
It contains 4 child elements. The
2009-11-06 18:04:19 +03:00
< code > mode< / code > element contains the octal permission set. The
< code > owner< / code > element contains the numeric user ID. The < code > group< / code >
element contains the numeric group ID. The < code > label< / code > element
contains the MAC (eg SELinux) label string.
< span class = "since" > Since 0.6.0< / span >
2009-01-27 21:30:03 +03:00
< / dd >
< / dl >
2008-05-07 03:23:55 +04:00
< h2 > < a name = "examples" > Example configuration< / a > < / h2 >
< p >
Here are a couple of examples, for a more complete set demonstrating
every type of storage pool, consult the < a href = "storage.html" > storage driver page< / a >
< / p >
< h3 > < a name = "exampleFile" > File based storage pool< / a > < / h3 >
< pre >
< pool type="dir">
< name> virtimages< /name>
< target>
< path> /var/lib/virt/images< /path>
< /target>
< /pool> < / pre >
< h3 > < a name = "exampleISCSI" > iSCSI based storage pool< / a > < / h3 >
< pre >
< pool type="iscsi">
< name> virtimages< /name>
< source>
< host name="iscsi.example.com"/>
2013-08-07 17:32:54 +04:00
< device path="iqn.2013-06.com.example:iscsi-pool"/>
< auth type='chap' username='myuser'>
< secret usage='libvirtiscsi'/>
< /auth>
2008-05-07 03:23:55 +04:00
< /source>
< target>
< path> /dev/disk/by-path< /path>
< /target>
< /pool> < / pre >
< h3 > < a name = "exampleVol" > Storage volume< / a > < / h3 >
< pre >
2009-05-29 16:27:45 +04:00
< volume>
2009-11-06 18:04:19 +03:00
< name> sparse.img< /name>
< allocation> 0< /allocation>
< capacity unit="T"> 1< /capacity>
< target>
2008-05-07 03:23:55 +04:00
< path> /var/lib/virt/images/sparse.img< /path>
< permissions>
2009-12-14 18:23:26 +03:00
< owner> 107< /owner>
< group> 107< /group>
2008-05-07 03:23:55 +04:00
< mode> 0744< /mode>
< label> virt_image_t< /label>
< /permissions>
2009-11-06 18:04:19 +03:00
< /target>
2008-05-07 03:23:55 +04:00
< /volume> < / pre >
2008-04-23 21:08:31 +04:00
< / body >
< / html >
