mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-07-11 04:15:49 +00:00
eda3af2488
The XML allows <encryption format='unencrypted'/>, this implementation canonicalizes the internal representation so that "vol->encryption" is non-NULL iff the volume is encrypted. Note that partial encryption information (e.g. specifying an encryption format, but not the key/passphrase) is valid, libvirt will automatically choose value for the missing information during volume creation. The user can read the volume XML, and use the unmodified <encryption> tag in future operations (without having to be able to understand) its contents. * docs/formatstorage.html, docs/formatstorage.html.in: Document storage volume encryption options * src/storage_conf.c, src/storage_conf.h: Hook up storage encryption XML handling * tests/storagevolschemadata/vol-qcow2.xml: Test case for encryption schema changes
475 lines
24 KiB
HTML
475 lines
24 KiB
HTML
<?xml version="1.0" encoding="ISO-8859-1"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.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"><div>
|
|
<input id="query" name="query" type="text" size="12" value="" />
|
|
<input id="submit" name="submit" type="submit" value="Search" />
|
|
</div></form>
|
|
</div>
|
|
</div>
|
|
<div id="body">
|
|
<div id="menu">
|
|
<ul class="l0"><li>
|
|
<div>
|
|
<a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Information for users, administrators and developers" class="active" href="docs.html">Documentation</a>
|
|
<ul class="l1"><li>
|
|
<div>
|
|
<a title="Information about deploying and using libvirt" class="inactive" href="deployment.html">Deployment</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Overview of the logical subsystems in the libvirt API" class="inactive" href="intro.html">Architecture</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Description of the XML formats used in libvirt" class="active" href="format.html">XML format</a>
|
|
<ul class="l2"><li>
|
|
<div>
|
|
<a title="The domain XML format" class="inactive" href="formatdomain.html">Domains</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="The virtual network XML format" class="inactive" href="formatnetwork.html">Networks</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<span class="active">Storage</span>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Storage volume encryption XML format" class="inactive" href="formatstorageencryption.html">Storage Encryption</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="The driver capabilities XML format" class="inactive" href="formatcaps.html">Capabilities</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="The host device XML format" class="inactive" href="formatnode.html">Node Devices</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="The secret XML format" class="inactive" href="formatsecret.html">Secrets</a>
|
|
</div>
|
|
</li></ul>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Hypervisor specific driver information" class="inactive" href="drivers.html">Drivers</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Reference manual for the C public API" class="inactive" href="html/index.html">API reference</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Bindings of the libvirt API for other languages" class="inactive" href="bindings.html">Language bindings</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Working on the internals of libvirt API, driver and daemon code" class="inactive" href="internals.html">Internals</a>
|
|
</div>
|
|
</li></ul>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Frequently asked questions" class="inactive" href="FAQ.html">FAQ</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
|
|
</div>
|
|
</li><li>
|
|
<div>
|
|
<a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
|
|
</div>
|
|
</li></ul>
|
|
</div>
|
|
<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">General metadata</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">General metadata</a>
|
|
</li><li>
|
|
<a href="#StorageVolTarget">Target elements</a>
|
|
</li><li>
|
|
<a href="#StorageVolBacking">Backing store elements</a>
|
|
</li></ul>
|
|
</li><li>
|
|
<a href="#examples">Example configuration</a>
|
|
<ul><li>
|
|
<a href="#exampleFile">File based storage pool</a>
|
|
</li><li>
|
|
<a href="#exampleISCSI">iSCSI based storage pool</a>
|
|
</li><li>
|
|
<a href="#exampleVol">Storage volume</a>
|
|
</li></ul>
|
|
</li></ul>
|
|
<h2>
|
|
<a name="StoragePool" id="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>
|
|
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.
|
|
The storage pool XML format is available <span class="since">since 0.4.1</span>
|
|
</p>
|
|
<h3>
|
|
<a name="StoragePoolFirst" id="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.
|
|
This is mandatory when defining a pool. <span class="since">Since 0.4.1</span></dd><dt><code>uuid</code></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. <span class="since">Since 0.4.1</span></dd><dt><code>allocation</code></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. <span class="since">Since 0.4.1</span></dd><dt><code>capacity</code></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. <span class="since">Since 0.4.1</span></dd><dt><code>available</code></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. <span class="since">Since 0.4.1</span></dd></dl>
|
|
<h3>
|
|
<a name="StoragePoolSource" id="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
|
|
the storage pool. It can contain the following child elements:
|
|
</p>
|
|
<pre>
|
|
...
|
|
<source>
|
|
<host name="iscsi.example.com"/>
|
|
<device path="demo-target"/>
|
|
</source>
|
|
...</pre>
|
|
<dl><dt><code>device</code></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. <span class="since">Since 0.4.1</span></dd><dt><code>directory</code></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.
|
|
<span class="since">Since 0.4.1</span></dd><dt><code>host</code></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. <span class="since">Since 0.4.1</span></dd><dt><code>name</code></dt><dd>Provides the source for pools backed by storage from a
|
|
named element (e.g., a logical volume group name).
|
|
remote server. Contains a string identifier.
|
|
<span class="since">Since 0.4.5</span></dd><dt><code>format</code></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. <span class="since">Since 0.4.1</span></dd></dl>
|
|
<h3>
|
|
<a name="StoragePoolTarget" id="StoragePoolTarget">Target elements</a>
|
|
</h3>
|
|
<p>
|
|
A single <code>target</code> element is contained within the top level
|
|
<code>pool</code> element. This tag is used to describe the mapping of
|
|
the storage pool into the host filesystem. It can contain the following
|
|
child elements:
|
|
</p>
|
|
<pre>
|
|
...
|
|
<target>
|
|
<path>/dev/disk/by-path</path>
|
|
<permissions>
|
|
<owner>0744</owner>
|
|
<group>0744</group>
|
|
<mode>0744</mode>
|
|
<label>virt_image_t</label>
|
|
</permissions>
|
|
<encryption type='...'>
|
|
...
|
|
</encryption>
|
|
</target>
|
|
</pool></pre>
|
|
<dl><dt><code>path</code></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.
|
|
<span class="since">Since 0.4.1</span>
|
|
</dd><dt><code>permissions</code></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.
|
|
<span class="since">Since 0.4.1</span>
|
|
</dd><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></dl>
|
|
<h3>
|
|
<a name="StoragePoolExtents" id="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" id="StorageVol">Storage volume XML</a>
|
|
</h2>
|
|
<p>
|
|
A storage volume will be either a file or a device node.
|
|
The storage volume XML format is available <span class="since">since 0.4.1</span>
|
|
</p>
|
|
<h3>
|
|
<a name="StorageVolFirst" id="StorageVolFirst">General metadata</a>
|
|
</h3>
|
|
<pre>
|
|
<volume>
|
|
<name>sparse.img</name>
|
|
<key>/var/lib/xen/images/sparse.img</key>
|
|
<allocation>0</allocation>
|
|
<capacity unit="T">1</capacity>
|
|
...</pre>
|
|
<dl><dt><code>name</code></dt><dd>Providing a name for the volume which is unique to the pool.
|
|
This is mandatory when defining a volume. <span class="since">Since 0.4.1</span></dd><dt><code>key</code></dt><dd>Providing an identifier for the volume which is globally unique.
|
|
This is optional when defining a volume, a key will be generated if
|
|
omitted. <span class="since">Since 0.4.1</span></dd><dt><code>allocation</code></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. <span class="since">Since 0.4.1</span></dd><dt><code>capacity</code></dt><dd>Providing the logical capacity for the volume. This value is
|
|
in bytes. This is compulsory when creating a volume.
|
|
<span class="since">Since 0.4.1</span></dd><dt><code>source</code></dt><dd>Provides information about the underlying storage allocation
|
|
of the volume. This may not be available for some pool types.
|
|
<span class="since">Since 0.4.1</span></dd><dt><code>target</code></dt><dd>Provides information about the representation of the volume
|
|
on the local host. <span class="since">Since 0.4.1</span></dd></dl>
|
|
<h3>
|
|
<a name="StorageVolTarget" id="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>
|
|
...
|
|
<target>
|
|
<path>/var/lib/virt/images/sparse.img</path>
|
|
<format type='qcow2'/>
|
|
<permissions>
|
|
<owner>0744</owner>
|
|
<group>0744</group>
|
|
<mode>0744</mode>
|
|
<label>virt_image_t</label>
|
|
</permissions>
|
|
</target></pre>
|
|
<dl><dt><code>path</code></dt><dd>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.
|
|
<span class="since">Since 0.4.1</span></dd><dt><code>format</code></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> attribute. Consult the pool-specific docs for
|
|
the list of valid values. <span class="since">Since 0.4.1</span></dd><dt><code>permissions</code></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.
|
|
<span class="since">Since 0.4.1</span>
|
|
</dd></dl>
|
|
<h3>
|
|
<a name="StorageVolBacking" id="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>
|
|
<format>raw</format>
|
|
<permissions>
|
|
<owner>0744</owner>
|
|
<group>0744</group>
|
|
<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
|
|
the local filesystem, as an absolute path. If omitted, there is no
|
|
backing store for this volume.
|
|
<span class="since">Since 0.6.0</span></dd><dt><code>format</code></dt><dd>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. 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.
|
|
<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
|
|
<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>
|
|
</dd></dl>
|
|
<h2>
|
|
<a name="examples" id="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" id="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" id="exampleISCSI">iSCSI based storage pool</a>
|
|
</h3>
|
|
<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>
|
|
<h3>
|
|
<a name="exampleVol" id="exampleVol">Storage volume</a>
|
|
</h3>
|
|
<pre>
|
|
<volume>
|
|
<name>sparse.img</name>
|
|
<allocation>0</allocation>
|
|
<capacity unit="T">1</capacity>
|
|
<target>
|
|
<path>/var/lib/virt/images/sparse.img</path>
|
|
<permissions>
|
|
<owner>0744</owner>
|
|
<group>0744</group>
|
|
<mode>0744</mode>
|
|
<label>virt_image_t</label>
|
|
</permissions>
|
|
</target>
|
|
</volume></pre>
|
|
</div>
|
|
</div>
|
|
<div id="footer">
|
|
<p id="sponsor">
|
|
Sponsored by:<br /><a href="http://et.redhat.com/"><img src="et.png" alt="Project sponsored by Red Hat Emerging Technology" /></a></p>
|
|
</div>
|
|
</body>
|
|
</html>
|