Storage pool and volume XML format
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 is 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. This corresponds to the storage backend drivers
listed further along in this document.
- name
- Providing a name for the pool which is unique to the host.
This is mandatory when defining a pool
- 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
- 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.
- 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.
- 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.
- source
- Provides information about the source of the pool, such as
the underlying host devices, or remote server
- target
- Provides information about the representation of the pool
on the local host.
- device
- Provides the source for pools backed by physical devices.
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.
- directory
- Provides the source for pools backed by directories. May
only occur once. Contains a single attribute
path
which is the fully qualified path to the block device node.
- host
- Provides the source for pools backed by storage from a
remote server. 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.
- format
- Provides information about the format of the pool. 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.
- 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.
- 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.
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.
A storage volume will be either a file or a device node.
- name
- Providing a name for the pool which is unique to the host.
This is mandatory when defining a pool
- 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
- 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.
- capacity
- Providing the logical capacity for the volume. This value is
in bytes. This is compulsory when creating a volume
- source
- Provides information about the underlying storage allocation
of the volume. This may not be available for some pool types.
- target
- Provides information about the representation of the volume
on the local host.
- 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.
- 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. Consult the pool-specific docs for the
list of valid values.
- 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.