1
<?xml version="1.0" encoding="ISO-8859-1"?>
2
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3
<html xmlns="http://www.w3.org/1999/xhtml">
5
This file is autogenerated from formatstorage.html.in
6
Do not edit this file. Changes will be lost.
9
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
10
<link rel="stylesheet" type="text/css" href="main.css" />
11
<link rel="SHORTCUT ICON" href="32favicon.png" />
12
<title>libvirt: Storage pool and volume XML format</title>
13
<meta name="description" content="libvirt, virtualization, virtualization API" />
17
<div id="headerLogo"></div>
18
<div id="headerSearch">
19
<form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><div>
20
<input id="query" name="query" type="text" size="12" value="" />
21
<input id="submit" name="submit" type="submit" value="Search" />
29
<a title="Front page of the libvirt website" class="inactive" href="index.html">Home</a>
33
<a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a>
37
<a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a>
41
<a title="Information for users, administrators and developers" class="active" href="docs.html">Documentation</a>
44
<a title="Information about deploying and using libvirt" class="inactive" href="deployment.html">Deployment</a>
48
<a title="Overview of the logical subsystems in the libvirt API" class="inactive" href="intro.html">Architecture</a>
52
<a title="Description of the XML formats used in libvirt" class="active" href="format.html">XML format</a>
55
<a title="The domain XML format" class="inactive" href="formatdomain.html">Domains</a>
59
<a title="The virtual network XML format" class="inactive" href="formatnetwork.html">Networks</a>
63
<span class="active">Storage</span>
67
<a title="The driver capabilities XML format" class="inactive" href="formatcaps.html">Capabilities</a>
71
<a title="The host device XML format" class="inactive" href="formatnode.html">Node Devices</a>
77
<a title="Hypervisor specific driver information" class="inactive" href="drivers.html">Drivers</a>
81
<a title="Reference manual for the C public API" class="inactive" href="html/index.html">API reference</a>
85
<a title="Bindings of the libvirt API for other languages" class="inactive" href="bindings.html">Language bindings</a>
91
<a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a>
95
<a title="Frequently asked questions" class="inactive" href="FAQ.html">FAQ</a>
99
<a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a>
103
<a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a>
107
<a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a>
111
<a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a>
116
<h1>Storage pool and volume XML format</h1>
118
<a href="#StoragePool">Storage pool XML</a>
120
<a href="#StoragePoolFirst">General metadata</a>
122
<a href="#StoragePoolSource">Source elements</a>
124
<a href="#StoragePoolTarget">Target elements</a>
126
<a href="#StoragePoolExtents">Device extents</a>
129
<a href="#StorageVol">Storage volume XML</a>
131
<a href="#StorageVolFirst">General metadata</a>
133
<a href="#StorageVolTarget">Target elements</a>
136
<a href="#examples">Example configuration</a>
138
<a href="#exampleFile">File based storage pool</a>
140
<a href="#exampleISCSI">iSCSI based storage pool</a>
142
<a href="#exampleVol">Storage volume</a>
146
<a name="StoragePool" id="StoragePool">Storage pool XML</a>
149
Although all storage pool backends share the same public APIs and
150
XML format, they have varying levels of capabilities. Some may
151
allow creation of volumes, others may only allow use of pre-existing
152
volumes. Some may have constraints on volume size, or placement.
155
The is the top level tag for a storage pool document is 'pool'. It has
156
a single attribute <code>type</code>, which is one of <code>dir</code>,
157
<code>fs</code>,<code>netfs</code>,<code>disk</code>,<code>iscsi</code>,
158
<code>logical</code>. This corresponds to the storage backend drivers
159
listed further along in this document.
160
The storage pool XML format is available <span class="since">since 0.4.1</span>
163
<a name="StoragePoolFirst" id="StoragePoolFirst">General metadata</a>
166
<pool type="iscsi">
167
<name>virtimages</name>
168
<uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
169
<allocation>10000000</allocation>
170
<capacity>50000000</capacity>
171
<available>40000000</available>
173
<dl><dt><code>name</code></dt><dd>Providing a name for the pool which is unique to the host.
174
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.
175
This is optional when defining a pool, a UUID will be generated if
176
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
177
be larger than the sum of the allocation of all volumes due to
178
metadata overhead. This value is in bytes. This is not applicable
179
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
180
underlying device constraints it may not be possible to use the
181
full capacity for storage volumes. This value is in bytes. This
182
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
183
in the pool. Due to underlying device constraints it may not be
184
possible to allocate the entire free space to a single volume.
185
This value is in bytes. This is not applicable when creating a
186
pool. <span class="since">Since 0.4.1</span></dd></dl>
188
<a name="StoragePoolSource" id="StoragePoolSource">Source elements</a>
191
A single <code>source</code> element is contained within the top level
192
<code>pool</code> element. This tag is used to describe the source of
193
the storage pool. It can contain the following child elements:
198
<host name="iscsi.example.com"/>
199
<device path="demo-target"/>
202
<dl><dt><code>device</code></dt><dd>Provides the source for pools backed by physical devices.
203
May be repeated multiple times depending on backend driver. Contains
204
a single attribute <code>path</code> which is the fully qualified
205
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
206
only occur once. Contains a single attribute <code>path</code>
207
which is the fully qualified path to the block device node.
208
<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
209
remote server. Will be used in combination with a <code>directory</code>
210
or <code>device</code> element. Contains an attribute <code>name</code>
211
which is the hostname or IP address of the server. May optionally
212
contain a <code>port</code> attribute for the protocol specific
213
port number. <span class="since">Since 0.4.1</span></dd><dt><code>format</code></dt><dd>Provides information about the format of the pool. This
214
contains a single attribute <code>type</code> whose value is
215
backend specific. This is typically used to indicate filesystem
216
type, or network filesystem type, or partition table type, or
217
LVM metadata type. All drivers are required to have a default
218
value for this, so it is optional. <span class="since">Since 0.4.1</span></dd></dl>
220
<a name="StoragePoolTarget" id="StoragePoolTarget">Target elements</a>
223
A single <code>target</code> element is contained within the top level
224
<code>pool</code> element. This tag is used to describe the mapping of
225
the storage pool into the host filesystem. It can contain the following
231
<path>/dev/disk/by-path</path>
233
<owner>0744</owner>
234
<group>0744</group>
235
<mode>0744</mode>
236
<label>virt_image_t</label>
240
<dl><dt><code>path</code></dt><dd>Provides the location at which the pool will be mapped into
241
the local filesystem namespace. For a filesystem/directory based
242
pool it will be the name of the directory in which volumes will
243
be created. For device based pools it will be the name of the directory in which
244
devices nodes exist. For the latter <code>/dev/</code> may seem
245
like the logical choice, however, devices nodes there are not
246
guaranteed stable across reboots, since they are allocated on
247
demand. It is preferable to use a stable location such as one
248
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
249
<span class="since">Since 0.4.1</span>
250
</dd><dt><code>permissions</code></dt><dd>Provides information about the default permissions to use
251
when creating volumes. This is currently only useful for directory
252
or filesystem based pools, where the volumes allocated are simple
253
files. For pools where the volumes are device nodes, the hotplug
254
scripts determine permissions. It contains 4 child elements. The
255
<code>mode</code> element contains the octal permission set. The
256
<code>owner</code> element contains the numeric user ID. The <code>group</code>
257
element contains the numeric group ID. The <code>label</code> element
258
contains the MAC (eg SELinux) label string.
259
<span class="since">Since 0.4.1</span>
262
<a name="StoragePoolExtents" id="StoragePoolExtents">Device extents</a>
265
If a storage pool exposes information about its underlying
266
placement / allocation scheme, the <code>device</code> element
267
within the <code>source</code> element may contain information
268
about its available extents. Some pools have a constraint that
269
a volume must be allocated entirely within a single constraint
270
(eg disk partition pools). Thus the extent information allows an
271
application to determine the maximum possible size for a new
275
For storage pools supporting extent information, within each
276
<code>device</code> element there will be zero or more <code>freeExtent</code>
277
elements. Each of these elements contains two attributes, <code>start</code>
278
and <code>end</code> which provide the boundaries of the extent on the
279
device, measured in bytes. <span class="since">Since 0.4.1</span>
282
<a name="StorageVol" id="StorageVol">Storage volume XML</a>
285
A storage volume will be either a file or a device node.
286
The storage volume XML format is available <span class="since">since 0.4.1</span>
289
<a name="StorageVolFirst" id="StorageVolFirst">General metadata</a>
292
<volume type="file">
293
<name>sparse.img</name>
294
<key>/var/lib/xen/images/sparse.img</key>
295
<allocation>0</allocation>
296
<capacity unit="T">1</capacity>
298
<dl><dt><code>name</code></dt><dd>Providing a name for the volume which is unique to the pool.
299
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.
300
This is optional when defining a volume, a key will be generated if
301
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
302
may be smaller than the logical capacity if the volume is sparsely
303
allocated. It may also be larger than the logical capacity if the
304
volume has substantial metadata overhead. This value is in bytes.
305
If omitted when creating a volume, the volume will be fully
306
allocated at time of creation. If set to a value smaller than the
307
capacity, the pool has the <strong>option</strong> of deciding
308
to sparsely allocate a volume. It does not have to honour requests
309
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
310
in bytes. This is compulsory when creating a volume.
311
<span class="since">Since 0.4.1</span></dd><dt><code>source</code></dt><dd>Provides information about the underlying storage allocation
312
of the volume. This may not be available for some pool types.
313
<span class="since">Since 0.4.1</span></dd><dt><code>target</code></dt><dd>Provides information about the representation of the volume
314
on the local host. <span class="since">Since 0.4.1</span></dd></dl>
316
<a name="StorageVolTarget" id="StorageVolTarget">Target elements</a>
319
A single <code>target</code> element is contained within the top level
320
<code>volume</code> element. This tag is used to describe the mapping of
321
the storage volume into the host filesystem. It can contain the following
327
<path>/var/lib/virt/images/sparse.img</path>
329
<owner>0744</owner>
330
<group>0744</group>
331
<mode>0744</mode>
332
<label>virt_image_t</label>
335
</volume></pre>
336
<dl><dt><code>path</code></dt><dd>Provides the location at which the pool will be mapped into
337
the local filesystem namespace. For a filesystem/directory based
338
pool it will be the name of the directory in which volumes will
339
be created. For device based pools it will be the name of the directory in which
340
devices nodes exist. For the latter <code>/dev/</code> may seem
341
like the logical choice, however, devices nodes there are not
342
guaranteed stable across reboots, since they are allocated on
343
demand. It is preferable to use a stable location such as one
344
of the <code>/dev/disk/by-{path,id,uuid,label</code> locations.
345
<span class="since">Since 0.4.1</span>
346
</dd><dt><code>format</code></dt><dd>Provides information about the pool specific volume format.
347
For disk pools it will provide the partition type. For filesystem
348
or directory pools it will provide the file format type, eg cow,
349
qcow, vmdk, raw. If omitted when creating a volume, the pool's
350
default format will be used. The actual format is specified via
351
the <code>type</code>. Consult the pool-specific docs for the
352
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
353
when creating volumes. This is currently only useful for directory
354
or filesystem based pools, where the volumes allocated are simple
355
files. For pools where the volumes are device nodes, the hotplug
356
scripts determine permissions. It contains 4 child elements. The
357
<code>mode</code> element contains the octal permission set. The
358
<code>owner</code> element contains the numeric user ID. The <code>group</code>
359
element contains the numeric group ID. The <code>label</code> element
360
contains the MAC (eg SELinux) label string.
361
<span class="since">Since 0.4.1</span>
364
<a name="examples" id="examples">Example configuration</a>
367
Here are a couple of examples, for a more complete set demonstrating
368
every type of storage pool, consult the <a href="storage.html">storage driver page</a>
371
<a name="exampleFile" id="exampleFile">File based storage pool</a>
374
<pool type="dir">
375
<name>virtimages</name>
377
<path>/var/lib/virt/images</path>
381
<a name="exampleISCSI" id="exampleISCSI">iSCSI based storage pool</a>
384
<pool type="iscsi">
385
<name>virtimages</name>
387
<host name="iscsi.example.com"/>
388
<device path="demo-target"/>
391
<path>/dev/disk/by-path</path>
395
<a name="exampleVol" id="exampleVol">Storage volume</a>
398
<volume type="file">
399
<name>sparse.img</name>
400
<allocation>0</allocation>
401
<capacity unit="T">1</capacity>
403
<path>/var/lib/virt/images/sparse.img</path>
405
<owner>0744</owner>
406
<group>0744</group>
407
<mode>0744</mode>
408
<label>virt_image_t</label>
411
</volume></pre>
416
Sponsored by:<br /><a href="http://et.redhat.com/"><img src="et.png" alt="Project sponsored by Red Hat Emerging Technology" /></a></p>
added
removed
docs/formatstorage.html
