2008-04-23 17:08:31 +00:00
|
|
|
<?xml version="1.0" encoding="ISO-8859-1"?>
|
|
|
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
|
|
<!--
|
|
|
|
|
This file is autogenerated from formatstorage.html.in
|
|
|
|
|
Do not edit this file. Changes will be lost.
|
|
|
|
|
-->
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
|
|
|
|
|
<link rel="stylesheet" type="text/css" href="main.css" />
|
|
|
|
|
<link rel="SHORTCUT ICON" href="32favicon.png" />
|
|
|
|
|
<title>libvirt: Storage pool and volume XML format</title>
|
|
|
|
|
<meta name="description" content="libvirt, virtualization, virtualization API" />
|
|
|
|
|
</head>
|
|
|
|
|
<body>
|
|
|
|
|
<div id="header">
|
|
|
|
|
<div id="headerLogo"></div>
|
|
|
|
|
<div id="headerSearch">
|
|
|
|
|
<form action="search.php" enctype="application/x-www-form-urlencoded" method="get">
|
|
|
|
|
<input id="query" name="query" type="text" size="12" value="" />
|
|
|
|
|
<input id="submit" name="submit" type="submit" value="Search" />
|
|
|
|
|
</form>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
<div id="body">
|
|
|
|
|
<div id="content">
|
|
|
|
|
<h1>Storage pool and volume XML format</h1>
|
|
|
|
|
<ul><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></ul>
|
|
|
|
|
<h3>
|
|
|
|
|
<a name="StoragePool" id="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" id="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 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.</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" id="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.</code></code></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" id="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 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.
|
|
|
|
|
</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" id="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 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.
|
|
|
|
|
</p>
|
|
|
|
|
<h3>
|
|
|
|
|
<a name="StorageVol" id="StorageVol">Storage volume XML</a>
|
|
|
|
|
</h3>
|
|
|
|
|
<p>
|
|
|
|
|
A storage volume will be either a file or a device node.
|
|
|
|
|
</p>
|
|
|
|
|
<h4>
|
|
|
|
|
<a name="StorageVolFirst" id="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" id="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 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
|
2008-04-24 09:17:29 +00:00
|
|
|
demand. It is preferable to use a stable location such as one
|
2008-04-23 17:08:31 +00:00
|
|
|
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>
|
|
|
|
|
</div>
|
|
|
|
|
<div id="menu">
|
|
|
|
|
<ul class="l0"><li>
|
|
|
|
|
<a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="Information for users, administrators and developers" class="active" href="docs.html">Documentation</a>
|
|
|
|
|
<ul class="l1"><li>
|
|
|
|
|
<a title="Information about deploying and using libvirt" class="inactive" href="deployment.html">Deployment</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="Overview of the logical subsystems in the libvirt API" class="inactive" href="intro.html">Architecture</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="Description of the XML formats used in libvirt" class="active" href="format.html">XML format</a>
|
|
|
|
|
<ul class="l2"><li>
|
|
|
|
|
<a title="The domain XML format" class="inactive" href="formatdomain.html">Domains</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="The virtual network XML format" class="inactive" href="formatnetwork.html">Networks</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<span class="active">Storage</span>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="The driver capabilities XML format" class="inactive" href="formatcaps.html">Capabilities</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="The host device XML format" class="inactive" href="formatnode.html">Node Devices</a>
|
|
|
|
|
</li></ul>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="Hypervisor specific driver information" class="inactive" href="drivers.html">Drivers</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="Reference manual for the C public API" class="inactive" href="html/index.html">API reference</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="Bindings of the libvirt API for other languages" class="inactive" href="bindings.html">Language bindings</a>
|
|
|
|
|
</li></ul>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="Frequently asked questions" class="inactive" href="FAQ.html">FAQ</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
|
|
|
|
|
</li><li>
|
|
|
|
|
<a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
|
|
|
|
|
</li></ul>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
<div id="footer">
|
|
|
|
|
<div id="projects">
|
|
|
|
|
<dl id="p1"><dt>
|
|
|
|
|
<a href="http://augeas.net/">Augeas</a>
|
|
|
|
|
</dt><dd>
|
|
|
|
|
<span>A configuration editing tool and API</span>
|
|
|
|
|
</dd><dt>
|
|
|
|
|
<a href="http://libvirt.org/">libvirt</a>
|
|
|
|
|
</dt><dd>
|
|
|
|
|
<span>The open source virtualization API</span>
|
|
|
|
|
</dd></dl>
|
|
|
|
|
<dl id="p2"><dt>
|
|
|
|
|
<a href="http://cobbler.et.redhat.com/">Cobbler</a>
|
|
|
|
|
</dt><dd>
|
|
|
|
|
<span>OS provisioning and profile management</span>
|
|
|
|
|
</dd><dt>
|
|
|
|
|
<a href="http://ovirt.org/">oVirt</a>
|
|
|
|
|
</dt><dd>
|
|
|
|
|
<span>Virtualization management across the data center</span>
|
|
|
|
|
</dd></dl>
|
|
|
|
|
<dl id="p3"><dt>
|
|
|
|
|
<a href="http://freeipa.org/">FreeIPA</a>
|
|
|
|
|
</dt><dd>
|
|
|
|
|
<span>Identity, policy and audit management</span>
|
|
|
|
|
</dd><dt>
|
|
|
|
|
<a href="http://virt-manager.org/">Virtual Machine Manager</a>
|
|
|
|
|
</dt><dd>
|
|
|
|
|
<span>Virtualization management from the desktop</span>
|
|
|
|
|
</dd></dl>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
