mirror of
https://github.com/libvirt/libvirt.git
synced 2025-02-25 18:55:26 -06:00
Added docs on storage management capabilities
This commit is contained in:
Daniel P. Berrange
576
docs/libvir.html
576
docs/libvir.html
@@ -3914,5 +3914,581 @@ first appeared in libvirt 0.2.0.
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h2><a name="Storage" id="Storage">Storage Management</a></h2>
|
||||
|
||||
<p>
|
||||
This page describes the storage management capabilities in
|
||||
libvirt.
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li><a href="#StorageCore">Core concepts</a></li>
|
||||
<li><a href="#StoragePool">Storage pool XML</a>
|
||||
<ul>
|
||||
<li><a href="#StoragePoolFirst">First level elements</a></li>
|
||||
<li><a href="#StoragePoolSource">Source elements</a></li>
|
||||
<li><a href="#StoragePoolTarget">Target elements</a></li>
|
||||
<li><a href="#StoragePoolExtents">Device extents</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#StorageVol">Storage volume XML</a>
|
||||
<ul>
|
||||
<li><a href="#StorageVolFirst">First level elements</a></li>
|
||||
<li><a href="#StorageVolSource">Source elements</a></li>
|
||||
<li><a href="#StorageVolTarget">Target elements</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#StorageBackend">Storage backend drivers</a>
|
||||
<ul>
|
||||
<li><a href="#StorageBackendDir">Directory backend</a></li>
|
||||
<li><a href="#StorageBackendFS">Local filesystem backend</a></li>
|
||||
<li><a href="#StorageBackendNetFS">Network filesystem backend</a></li>
|
||||
<li><a href="#StorageBackendLogical">Logical backend</a></li>
|
||||
<li><a href="#StorageBackendDisk">Disk backend</a></li>
|
||||
<li><a href="#StorageBackendISCSI">iSCSI backend</a></li>
|
||||
</ul>
|
||||
|
||||
<h3><a name="StorageCore">Core concepts</a></h3>
|
||||
|
||||
<p>
|
||||
The storage management APIs are based around 2 core concepts
|
||||
</p>
|
||||
|
||||
<ol>
|
||||
<li><strong>Volume</strong> - a single storage volume which can
|
||||
be assigned to a guest, or used for creating further pools. A
|
||||
volume is either a block device, a raw file, or a special format
|
||||
file.</li>
|
||||
<li><strong>Pool</strong> - provides a means for taking a chunk
|
||||
of storage and carving it up into volumes. A pool can be used to
|
||||
manage things such as a physical disk, a NFS server, a iSCSI target,
|
||||
a host adapter, an LVM group.</li>
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
These two concepts are mapped through to two libvirt objects, a
|
||||
<code>virStorageVolPtr</code> and a <code>virStoragePoolPtr</code>,
|
||||
each with a collection of APIs for their management.
|
||||
</p>
|
||||
|
||||
|
||||
<h3><a name="StoragePool">Storage pool XML</a></h3>
|
||||
|
||||
<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>The is the top level tag for a storage pool document is 'pool'. It has
|
||||
a single attribute <code>type</code>, which is one of <code>dir</code>,
|
||||
<code>fs</code>,<code>netfs</code>,<code>disk</code>,<code>iscsi</code>,
|
||||
<code>logical</code>. This corresponds to the storage backend drivers
|
||||
listed further along in this document.
|
||||
</p>
|
||||
|
||||
|
||||
<h4><a name="StoragePoolFirst">First level elements</a></h4>
|
||||
|
||||
<dl>
|
||||
<dt>name</dt>
|
||||
<dd>Providing a name for the pool which is unique to the host.
|
||||
This is mandatory when defining a pool</dd>
|
||||
|
||||
<dt>uuid</dt>
|
||||
<dd>Providing an identifier for the pool which is globally unique.
|
||||
This is optional when defining a pool, a UUID will be generated if
|
||||
omitted</dd>
|
||||
|
||||
<dt>allocation</dt>
|
||||
<dd>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.</dd>
|
||||
|
||||
<dt>capacity</dt>
|
||||
<dd>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.</dd>
|
||||
|
||||
<dt>available</dt>
|
||||
<dd>Providing the free space available for allocating new volums
|
||||
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.</dd>
|
||||
|
||||
<dt>source</dt>
|
||||
<dd>Provides information about the source of the pool, such as
|
||||
the underlying host devices, or remote server</dd>
|
||||
|
||||
<dt>target</dt>
|
||||
<dd>Provides information about the representation of the pool
|
||||
on the local host.</dd>
|
||||
</dl>
|
||||
|
||||
<h4><a name="StoragePoolSource">Source elements</a></h4>
|
||||
|
||||
<dl>
|
||||
<dt>device</dt>
|
||||
<dd>Provides the source for pools backed by physical devices.
|
||||
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.</dd>
|
||||
<dt>directory</dt>
|
||||
<dd>Provides the source for pools backed by directories. May
|
||||
only occur once. Contains a single attribute <code>path</code>
|
||||
which is the fully qualified path to the block device node.</dd>
|
||||
<dt>host</dt>
|
||||
<dd>Provides the source for pools backed by storage from a
|
||||
remote server. Will be used in combination with a <code>directory</code>
|
||||
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.</dd>
|
||||
<dt>format</dt>
|
||||
<dd>Provides information about the format of the pool. This
|
||||
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.</dd>
|
||||
</dl>
|
||||
|
||||
<h4><a name="StoragePoolTarget">Target elements</a></h4>
|
||||
|
||||
<dl>
|
||||
<dt>path</dt>
|
||||
<dd>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 tbe directory in which
|
||||
devices nodes exist. For the latter <code>/dev/</code> may seem
|
||||
like the logical choice, however, devices nodes there are not
|
||||
guarenteed stable across reboots, since they are allocated on
|
||||
demand. It is preferrable to use a stable location such as one
|
||||
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
|
||||
</dd>
|
||||
<dt>permissions<dt>
|
||||
<dd>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
|
||||
<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.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<h4><a name="StoragePoolExtents">Device extents</a></h4>
|
||||
|
||||
<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 avilable 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.
|
||||
</p>
|
||||
|
||||
<h3><a name="StorageVol">Storage volume XML</a></h3>
|
||||
|
||||
<p>
|
||||
A storage volume will be either a file or a device node.
|
||||
</p>
|
||||
|
||||
<h4><a name="StorageVolFirst">First level elements</a></h4>
|
||||
|
||||
<dl>
|
||||
<dt>name</dt>
|
||||
<dd>Providing a name for the pool which is unique to the host.
|
||||
This is mandatory when defining a pool</dd>
|
||||
|
||||
<dt>uuid</dt>
|
||||
<dd>Providing an identifier for the pool which is globally unique.
|
||||
This is optional when defining a pool, a UUID will be generated if
|
||||
omitted</dd>
|
||||
|
||||
<dt>allocation</dt>
|
||||
<dd>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 <strong>option</strong> of deciding
|
||||
to sparsely allocate a volume. It does not have to honour requests
|
||||
for sparse allocation though.</dd>
|
||||
|
||||
<dt>capacity</dt>
|
||||
<dd>Providing the logical capacity for the volume. This value is
|
||||
in bytes. This is compulsory when creating a volume</dd>
|
||||
|
||||
<dt>source</dt>
|
||||
<dd>Provides information about the underlying storage allocation
|
||||
of the volume. This may not be available for some pool types.</dd>
|
||||
|
||||
<dt>target</dt>
|
||||
<dd>Provides information about the representation of the volume
|
||||
on the local host.</dd>
|
||||
</dl>
|
||||
|
||||
<h4><a name="StorageVolTarget">Target elements</a></h4>
|
||||
|
||||
<dl>
|
||||
<dt>path</dt>
|
||||
<dd>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 tbe directory in which
|
||||
devices nodes exist. For the latter <code>/dev/</code> may seem
|
||||
like the logical choice, however, devices nodes there are not
|
||||
guarenteed stable across reboots, since they are allocated on
|
||||
demand. It is preferrable to use a stable location such as one
|
||||
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
|
||||
</dd>
|
||||
<dt>format</dt>
|
||||
<dd>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 <code>type</code>. Consult the pool-specific docs for the
|
||||
list of valid values.</dd>
|
||||
<dt>permissions<dt>
|
||||
<dd>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
|
||||
<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.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
|
||||
|
||||
<h3><a name="StorageBackend">Storage backend drivers</a></h3>
|
||||
|
||||
<p>
|
||||
This section illustrates the capabilities / format for each of
|
||||
the different backend storage pool drivers
|
||||
</p>
|
||||
|
||||
<h4><a name="StorageBackendDir">Directory pool</a></h4>
|
||||
|
||||
<p>
|
||||
A pool with a type of <code>dir</code> provides the means to manage
|
||||
files within a directory. The files can be fully allocated raw files,
|
||||
sparsely allocated raw files, or one of the special disk formats
|
||||
such as <code>qcow</code>,<code>qcow2</code>,<code>vmdk</code>,
|
||||
<code>cow</code>, etc as supported by the <code>qemu-img</code>
|
||||
program. If the directory does not exist at the time the pool is
|
||||
defined, the <code>build</code> operation can be used to create it.
|
||||
</p>
|
||||
|
||||
<h5>Example pool input definition</h5>
|
||||
|
||||
<pre>
|
||||
<pool type="dir">
|
||||
<name>virtimages</name>
|
||||
<target>
|
||||
<path>/var/lib/virt/images</path>
|
||||
</target>
|
||||
</pool>
|
||||
</pre>
|
||||
|
||||
<h5>Valid pool format types</h5>
|
||||
|
||||
<p>
|
||||
The directory pool does not use the pool format type element.
|
||||
</p>
|
||||
|
||||
<h5>Valid volume format types</h5>
|
||||
|
||||
<p>
|
||||
One of the following options:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li><code>raw</code>: a plain file</li>
|
||||
<li><code>bochs</code>: Bochs disk image format</li>
|
||||
<li><code>cloop</code>: compressed loopback disk image format</li>
|
||||
<li><code>cow</code>: User Mode Linux disk image format</li>
|
||||
<li><code>dmg</code>: Mac disk image format</li>
|
||||
<li><code>iso</code>: CDROM disk image format</li>
|
||||
<li><code>qcow</code>: QEMU v1 disk image format</li>
|
||||
<li><code>qcow2</code>: QEMU v2 disk image format</li>
|
||||
<li><code>vmdk</code>: VMWare disk image format</li>
|
||||
<li><code>vpc</code>: VirtualPC disk image format</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
When listing existing volumes all these formats are supported
|
||||
natively. When creating new volumes, only a subset may be
|
||||
available. The <code>raw</code> type is guarenteed always
|
||||
available. The <code>qcow2</code> type can be created if
|
||||
either <code>qemu-img</code> or <code>qcow-create</code> tools
|
||||
are present. The others are dependant on support of the
|
||||
<code>qemu-img</code> tool.
|
||||
|
||||
<h4><a name="StorageBackendFS">Filesystem pool</a></h4>
|
||||
|
||||
<p>
|
||||
This is a variant of the directory pool. Instead of creating a
|
||||
directory on an existing mounted filesystem though, it expects
|
||||
a source block device to be named. This block device will be
|
||||
mounted and files managed in the directory of its mount point.
|
||||
It will default to allowing the kernel to automatically discover
|
||||
the filesystem type, though it can be specified manually if
|
||||
required.
|
||||
</p>
|
||||
|
||||
<h5>Example pool input</h5>
|
||||
|
||||
<pre>
|
||||
<pool type="fs">
|
||||
<name>virtimages</name>
|
||||
<source>
|
||||
<device path="/dev/VolGroup00/VirtImages"/>
|
||||
</source>
|
||||
<target>
|
||||
<path>/var/lib/virt/images</path>
|
||||
</target>
|
||||
</pool>
|
||||
</pre>
|
||||
|
||||
<h5>Valid pool format types</h5>
|
||||
|
||||
<p>
|
||||
The fileystem pool supports the following formats:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li><code>auto</code> - automatically determine format</li>
|
||||
<li><code>ext2</code></li>
|
||||
<li><code>ext3</code></li>
|
||||
<li><code>ext4</code></li>
|
||||
<li><code>ufs</code></li>
|
||||
<li><code>iso9660</code></li>
|
||||
<li><code>udf</code></li>
|
||||
<li><code>gfs</code></li>
|
||||
<li><code>gfs2</code></li>
|
||||
<li><code>vfat</code></li>
|
||||
<li><code>hfs+</code></li>
|
||||
<li><code>xfs</code></li>
|
||||
</ul>
|
||||
|
||||
<h5>Valid volume format types</h5>
|
||||
|
||||
<p>
|
||||
The valid volume types are the same as for the <code>directory</code>
|
||||
pool type.
|
||||
</p>
|
||||
|
||||
<h4><a name="StorageBackendNetFS">Network filesystem pool</a></h4>
|
||||
|
||||
<p>
|
||||
This is a variant of the filesystem pool. Instead of requiring
|
||||
a local block device as the source, it requires the name of a
|
||||
host and path of an exported directory. It will mount this network
|
||||
filesystem and manage files within the directory of its mount
|
||||
point. It will default to using NFS as the protocol.
|
||||
</p>
|
||||
|
||||
<h5>Example pool input</h5>
|
||||
|
||||
<pre>
|
||||
<pool type="netfs">
|
||||
<name>virtimages</name>
|
||||
<source>
|
||||
<host name="nfs.example.com"/>
|
||||
<dir path="/var/lib/virt/images"/>
|
||||
</source>
|
||||
<target>
|
||||
<path>/var/lib/virt/images</path>
|
||||
</target>
|
||||
</pool>
|
||||
</pre>
|
||||
|
||||
<h5>Valid pool format types</h5>
|
||||
|
||||
<p>
|
||||
The network fileystem pool supports the following formats:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li><code>auto</code> - automatically determine format</li>
|
||||
<li><code>nfs</code></li>
|
||||
</ul>
|
||||
|
||||
<h5>Valid volume format types</h5>
|
||||
|
||||
<p>
|
||||
The valid volume types are the same as for the <code>directory</code>
|
||||
pool type.
|
||||
</p>
|
||||
|
||||
<h4><a name="StorageBackendLogical">Logical volume pools</a></h4>
|
||||
|
||||
<p>
|
||||
This provides a pool based on an LVM volume group. For a
|
||||
pre-defined LVM volume group, simply providing the group
|
||||
name is sufficient, while to build a new group requires
|
||||
providing a list of source devices to serve as physical
|
||||
volumes. Volumes will be allocated by carving out chunks
|
||||
of storage from the volume group.
|
||||
</p>
|
||||
|
||||
<h5>Example pool input</h5>
|
||||
|
||||
<pre>
|
||||
<pool type="logical">
|
||||
<name>HostVG</name>
|
||||
<source>
|
||||
<device path="/dev/sda1"/>
|
||||
<device path="/dev/sdb1"/>
|
||||
<device path="/dev/sdc1"/>
|
||||
</source>
|
||||
<target>
|
||||
<path>/dev/HostVG</path>
|
||||
</target>
|
||||
</pool>
|
||||
</pre>
|
||||
|
||||
<h5>Valid pool format types</h5>
|
||||
|
||||
<p>
|
||||
The logical volume pool does not use the pool format type element.
|
||||
</p>
|
||||
|
||||
<h5>Valid volume format types</h5>
|
||||
|
||||
<p>
|
||||
The logical volume pool does not use the volume format type element.
|
||||
</p>
|
||||
|
||||
|
||||
<h4><a name="StorageBackendDisk">Disk volume pools</a></h4>
|
||||
|
||||
<p>
|
||||
This provides a pool based on a physical disk. Volumes are created
|
||||
by adding partitions to the disk. Disk pools are have constraints
|
||||
on the size and placement of volumes. The 'free extents'
|
||||
information will detail the regions which are available for creating
|
||||
new volumes. A volume cannot span across 2 different free extents.
|
||||
</p>
|
||||
|
||||
<h5>Example pool input</h5>
|
||||
|
||||
<pre>
|
||||
<pool type="disk">
|
||||
<name>sda</name>
|
||||
<source>
|
||||
<device path='/dev/sda'/>
|
||||
</source>
|
||||
<target>
|
||||
<path>/dev</path>
|
||||
</target>
|
||||
</pool>
|
||||
</pre>
|
||||
|
||||
<h5>Valid pool format types</h5>
|
||||
|
||||
<p>
|
||||
The disk volume pool accepts the following pool format types, representing
|
||||
the common partition table types:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li><code>dos</code></li>
|
||||
<li><code>dvh</code></li>
|
||||
<li><code>gpt</code></li>
|
||||
<li><code>mac</code></li>
|
||||
<li><code>bsd</code></li>
|
||||
<li><code>pc98</code></li>
|
||||
<li><code>sun</code></li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
The <code>dos</code> or <code>gpt</code> formats are recommended for
|
||||
best portability - the latter is needed for disks larger than 2TB.
|
||||
</p>
|
||||
|
||||
<h5>Valid volume format types</h5>
|
||||
|
||||
<p>
|
||||
The disk volume pool accepts the following volume format types, representing
|
||||
the common partition entry types:
|
||||
</p>
|
||||
|
||||
<ul>
|
||||
<li><code>none</code></li>
|
||||
<li><code>linux</code></li>
|
||||
<li><code>fat16</code></li>
|
||||
<li><code>fat32</code></li>
|
||||
<li><code>linux-swap</code></li>
|
||||
<li><code>linux-lvm</code></li>
|
||||
<li><code>linux-raid</code></li>
|
||||
<li><code>extended</code></li>
|
||||
</ul>
|
||||
|
||||
|
||||
<h4><a name="StorageBackendISCSI">iSCSI volume pools</a></h4>
|
||||
|
||||
<p>
|
||||
This provides a pool based on an iSCSI target. Volumes must be
|
||||
pre-allocated on the iSCSI server, and cannot be created via
|
||||
the libvirt APIs. Since /dev/XXX names may change each time libvirt
|
||||
logs into the iSCSI target, it is recommended to configure the pool
|
||||
to use <code>/dev/disk/by-path</code> or <code>/dev/disk/by-id</code>
|
||||
for the target path. These provide persistent stable naming for LUNs
|
||||
</p>
|
||||
|
||||
<h5>Example pool input</h5>
|
||||
|
||||
<pre>
|
||||
<pool type="iscsi">
|
||||
<name>virtimages</name>
|
||||
<source>
|
||||
<host name="iscsi.example.com"/>
|
||||
<device path="demo-target"/>
|
||||
</source>
|
||||
<target>
|
||||
<path>/dev/disk/by-path</path>
|
||||
</target>
|
||||
</pool>
|
||||
</pre>
|
||||
|
||||
<h5>Valid pool format types</h5>
|
||||
|
||||
<p>
|
||||
The logical volume pool does not use the pool format type element.
|
||||
</p>
|
||||
|
||||
<h5>Valid volume format types</h5>
|
||||
|
||||
<p>
|
||||
The logical volume pool does not use the volume format type element.
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Reference in New Issue
Block a user