External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-11-09 23:10:08 +00:00
Code Issues Packages Projects Releases Wiki Activity
b8e6021e7b
libvirt/docs/formatstorage.html.in

419 lines
19 KiB
HTML
Raw Normal View History

Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
<html>
<body>
<h1>Storage pool and volume XML format</h1>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<ul id="toc"></ul>
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<h2><a name="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>
Fix typo in storage pool documentation Remove 2 words that shouldn't be here.
2011-12-19 14:19:56 +00:00
The top level tag for a storage pool document is 'pool'. It has
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
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">General metadata</a></h3>
<pre>
&lt;pool type="iscsi"&gt;
&lt;name&gt;virtimages&lt;/name&gt;
&lt;uuid&gt;3e3fce45-4f53-4fa7-bb32-11f34168b82b&lt;/uuid&gt;
&lt;allocation&gt;10000000&lt;/allocation&gt;
&lt;capacity&gt;50000000&lt;/capacity&gt;
&lt;available&gt;40000000&lt;/available&gt;
...</pre>
<dl>
<dt><code>name</code></dt>
<dd>Providing a name for the pool which is unique to the host.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
This is mandatory when defining a pool. <span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>uuid</code></dt>
<dd>Providing an identifier for the pool which is globally unique.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
This is optional when defining a pool, a UUID will be generated if
omitted. <span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>allocation</code></dt>
<dd>Providing the total storage allocation for the pool. This may
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>capacity</code></dt>
<dd>Providing the total storage capacity for the pool. Due to
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>available</code></dt>
<dd>Providing the free space available for allocating new volumes
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dl>
<h3><a name="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>
...
&lt;source&gt;
&lt;host name="iscsi.example.com"/&gt;
&lt;device path="demo-target"/&gt;
storage: add support for Vendor and Model in XML I wrote a patch to add support for listing the Vendor and Model of a storage pool in the storage pool XML. This would allow vendor extensions of specific devices. The patch includes a test for the new attributes as well. Patrick Dignan
2010-08-17 17:44:27 +00:00
&lt;vendor name="Acme"/&gt;
Fix broken XML entity for '>' Add missing 'g' to '&gt;' of '<product />' source-element. Signed-off-by: Philipp Hahn <hahn@univention.de>
2010-11-25 09:40:07 +00:00
&lt;product name="model"/&gt;
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
&lt;/source&gt;
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
...</pre>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dl>
<dt><code>device</code></dt>
<dd>Provides the source for pools backed by physical devices.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>directory</code></dt>
<dd>Provides the source for pools backed by directories. May
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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>
docs: storage: Document SCSI pools
2010-02-22 21:50:04 +00:00
<dt><code>adapter</code></dt>
<dd>Provides the source for pools backed by SCSI adapters. May
only occur once. Contains a single attribute <code>name</code>
which is the SCSI adapter name (ex. "host1").
<span class="since">Since 0.6.2</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>host</code></dt>
<dd>Provides the source for pools backed by storage from a
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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>
Adds storage source element for pools * src/storage_backend.h src/storage_backend_logical.c src/storage_conf.c src/storage_conf.h src/virsh.c: Applied patches from David Lively to add storage source elements needed for storage pool * docs/formatstorage.html docs/formatstorage.html.in: associated documentation Daniel
2008-09-02 14:15:42 +00:00
<dt><code>name</code></dt>
<dd>Provides the source for pools backed by storage from a
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
named element (e.g., a logical volume group name).
remote server. Contains a string identifier.
<span class="since">Since 0.4.5</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>format</code></dt>
<dd>Provides information about the format of the pool. This
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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>
storage: add support for Vendor and Model in XML I wrote a patch to add support for listing the Vendor and Model of a storage pool in the storage pool XML. This would allow vendor extensions of specific devices. The patch includes a test for the new attributes as well. Patrick Dignan
2010-08-17 17:44:27 +00:00
<dt><code>vendor</code></dt>
<dd>Provides optional information about the vendor of the
storage device. This contains a single
attribute <code>name</code> whose value is backend
specific. <span class="since">Since 0.8.4</span></dd>
<dt><code>product</code></dt>
<dd>Provides an optional product name of the storage device.
This contains a single attribute <code>name</code> whose value
is backend specific. <span class="since">Since 0.8.4</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dl>
<h3><a name="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>
...
&lt;target&gt;
&lt;path&gt;/dev/disk/by-path&lt;/path&gt;
&lt;permissions&gt;
Fix owner and group in example volume XML The owner and group in the documentation examples were confusingly given as '0744'. They should be numeric uid and gid. Changed the examples to use the default uid and gid assigned to qemu in F12. * docs/formatstorage.html.in: Change example owner and group in volume XML
2009-12-14 15:23:26 +00:00
&lt;owner&gt;107&lt;/owner&gt;
&lt;group&gt;107&lt;/group&gt;
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
&lt;mode&gt;0744&lt;/mode&gt;
&lt;label&gt;virt_image_t&lt;/label&gt;
&lt;/permissions&gt;
Attach encryption information to virStorageVolDef. 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
2009-07-20 22:28:11 +00:00
&lt;encryption type='...'&gt;
...
&lt;/encryption&gt;
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
&lt;/target&gt;
&lt;/pool&gt;</pre>
<dl>
<dt><code>path</code></dt>
<dd>Provides the location at which the pool will be mapped into
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dd>
<dt><code>permissions</code></dt>
<dd>Provides information about the default permissions to use
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dd>
Attach encryption information to virStorageVolDef. 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
2009-07-20 22:28:11 +00:00
<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>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dl>
<h3><a name="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">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">General metadata</a></h3>
<pre>
fix storage volume inconsistencies in schema and doc * docs/schemas/storagevol.rng docs/formatstorage.html[.in] tests/storagevolschemadata/vol-qcow2.xml: fix storage volume inconsistencies in schema and document, patch by Ryota Ozaki daniel
2009-05-29 12:27:45 +00:00
&lt;volume&gt;
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
&lt;name&gt;sparse.img&lt;/name&gt;
&lt;key&gt;/var/lib/xen/images/sparse.img&lt;/key&gt;
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
&lt;allocation&gt;0&lt;/allocation&gt;
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
&lt;capacity unit="T"&gt;1&lt;/capacity&gt;
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
...</pre>
<dl>
<dt><code>name</code></dt>
<dd>Providing a name for the volume which is unique to the pool.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
This is mandatory when defining a volume. <span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>key</code></dt>
<dd>Providing an identifier for the volume which is globally unique.
docs: storage: Fix backingStore <format> docs
2010-02-22 21:01:12 +00:00
This cannot be set when creating a volume: it is always generated.
docs: storage: <volume><key> is always generated.
2010-02-22 20:54:06 +00:00
<span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>allocation</code></dt>
<dd>Providing the total storage allocation for the volume. This
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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
docs: storage: Document capacity/alloc 'unit'
2010-02-22 20:52:14 +00:00
for sparse allocation though.<br/>
<br/>
docs: use correct terminology for 1024 bytes Yes, I like kilobytes better than kibibytes (when I say kilobytes, I generally mean 1024). But since the term is ambiguous, it can't hurt to say what we mean, by using both the correct name and calling out the numeric equivalent. * src/libvirt.c (virDomainGetMaxMemory, virDomainSetMaxMemory) (virDomainSetMemory, virDomainSetMemoryFlags) (virNodeGetFreeMemory): Tweak wording. * docs/formatdomain.html.in: Likewise. * docs/formatstorage.html.in: Likewise.
2012-03-02 15:23:07 +00:00
By default this is specified in bytes, but an optional attribute
docs: storage: Document capacity/alloc 'unit'
2010-02-22 20:52:14 +00:00
<code>unit</code> can be specified to adjust the passed value.
storage: support more scaling suffixes Disk manufacturers are fond of quoting sizes in powers of 10, rather than powers of 2 (after all, 2.1 GB sounds larger than 2.0 GiB, even though the exact opposite is true). So, we might as well follow coreutils' lead in supporting three types of suffix: single letter ${u} (which we already had) and ${u}iB for the power of 2, and ${u}B for power of 10. Additionally, it is impossible to create a file with more than 2**63 bytes, since off_t is signed (if you have enough storage to even create one 8EiB file, I'm jealous). This now reports failure up front rather than down the road when the kernel finally refuses an impossible size. * docs/schemas/basictypes.rng (unit): Add suffixes. * src/conf/storage_conf.c (virStorageSize): Use new function. * docs/formatstorage.html.in: Document it. * tests/storagevolxml2xmlin/vol-file-backing.xml: Test it. * tests/storagevolxml2xmlin/vol-file.xml: Likewise.
2012-03-05 21:06:33 +00:00
Values can be: 'B' or 'bytes' for bytes, 'KB' (kilobytes,
10<sup>3</sup> or 1000 bytes), 'K' or 'KiB' (kibibytes,
2<sup>10</sup> or 1024 bytes), 'MB' (megabytes, 10<sup>6</sup>
or 1,000,000 bytes), 'M' or 'MiB' (mebibytes, 2<sup>20</sup>
or 1,048,576 bytes), 'GB' (gigabytes, 10<sup>9</sup> or
1,000,000,000 bytes), 'G' or 'GiB' (gibibytes, 2<sup>30</sup>
or 1,073,741,824 bytes), 'TB' (terabytes, 10<sup>12</sup> or
1,000,000,000,000 bytes), 'T' or 'TiB' (tebibytes,
2<sup>40</sup> or 1,099,511,627,776 bytes), 'PB' (petabytes,
10<sup>15</sup> or 1,000,000,000,000,000 bytes), 'P' or 'PiB'
(pebibytes, 2<sup>50</sup> or 1,125,899,906,842,624 bytes),
'EB' (exabytes, 10<sup>18</sup> or 1,000,000,000,000,000,000
bytes), or 'E' or 'EiB' (exbibytes, 2<sup>60</sup> or
1,152,921,504,606,846,976 bytes). <span class="since">Since
0.4.1, multi-character <code>unit</code> since
0.9.11</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>capacity</code></dt>
<dd>Providing the logical capacity for the volume. This value is
docs: storage: Document capacity/alloc 'unit'
2010-02-22 20:52:14 +00:00
in bytes by default, but a <code>unit</code> attribute can be
specified with the same semantics as for <code>allocation</code>
This is compulsory when creating a volume.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>source</code></dt>
<dd>Provides information about the underlying storage allocation
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
of the volume. This may not be available for some pool types.
<span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>target</code></dt>
<dd>Provides information about the representation of the volume
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
on the local host. <span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dl>
<h3><a name="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>
...
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
&lt;target&gt;
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
&lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
* docs/formatstorage.html[.in]: fix a error in format type example pointed out by Ryota Ozaki Daniel
2009-05-21 08:03:13 +00:00
&lt;format type='qcow2'/&gt;
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
&lt;permissions&gt;
Fix owner and group in example volume XML The owner and group in the documentation examples were confusingly given as '0744'. They should be numeric uid and gid. Changed the examples to use the default uid and gid assigned to qemu in F12. * docs/formatstorage.html.in: Change example owner and group in volume XML
2009-12-14 15:23:26 +00:00
&lt;owner&gt;107&lt;/owner&gt;
&lt;group&gt;107&lt;/group&gt;
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
&lt;mode&gt;0744&lt;/mode&gt;
&lt;label&gt;virt_image_t&lt;/label&gt;
&lt;/permissions&gt;
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
&lt;/target&gt;</pre>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dl>
<dt><code>path</code></dt>
Fix documentation cut and paste errors, and a virsh typo.
2008-12-04 14:51:57 +00:00
<dd>Provides the location at which the volume can be accessed on
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>format</code></dt>
<dd>Provides information about the pool specific volume format.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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
* docs/formatstorage.html[.in]: fix a error in format type example pointed out by Ryota Ozaki Daniel
2009-05-21 08:03:13 +00:00
the list of valid values. <span class="since">Since 0.4.1</span></dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<dt><code>permissions</code></dt>
<dd>Provides information about the default permissions to use
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
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>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dd>
</dl>
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
<h3><a name="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>
...
&lt;backingStore&gt;
&lt;path&gt;/var/lib/virt/images/master.img&lt;/path&gt;
docs: storage: Fix backingStore <format> docs
2010-02-22 21:01:12 +00:00
&lt;format type='raw'/&gt;
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
&lt;permissions&gt;
Fix owner and group in example volume XML The owner and group in the documentation examples were confusingly given as '0744'. They should be numeric uid and gid. Changed the examples to use the default uid and gid assigned to qemu in F12. * docs/formatstorage.html.in: Change example owner and group in volume XML
2009-12-14 15:23:26 +00:00
&lt;owner&gt;107&lt;/owner&gt;
&lt;group&gt;107&lt;/group&gt;
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
&lt;mode&gt;0744&lt;/mode&gt;
&lt;label&gt;virt_image_t&lt;/label&gt;
&lt;/permissions&gt;
&lt;/backingStore&gt;
&lt;/volume&gt;</pre>
<dl>
<dt><code>path</code></dt>
<dd>Provides the location at which the backing store can be accessed on
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
the local filesystem, as an absolute path. If omitted, there is no
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
backing store for this volume.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<span class="since">Since 0.6.0</span></dd>
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
<dt><code>format</code></dt>
<dd>Provides information about the pool specific backing store format.
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
For disk pools it will provide the partition type. For filesystem
or directory pools it will provide the file format type, eg cow,
docs: storage: Fix backingStore <format> docs
2010-02-22 21:01:12 +00:00
qcow, vmdk, raw. The actual format is specified via the type attribute.
Consult the pool-specific docs for the list of valid
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
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
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
<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>
Add support for copy-on-write storage volumes
2009-01-27 18:30:03 +00:00
</dd>
</dl>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
<h2><a name="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">File based storage pool</a></h3>
<pre>
&lt;pool type="dir"&gt;
&lt;name&gt;virtimages&lt;/name&gt;
&lt;target&gt;
&lt;path&gt;/var/lib/virt/images&lt;/path&gt;
&lt;/target&gt;
&lt;/pool&gt;</pre>
<h3><a name="exampleISCSI">iSCSI based storage pool</a></h3>
<pre>
&lt;pool type="iscsi"&gt;
&lt;name&gt;virtimages&lt;/name&gt;
&lt;source&gt;
&lt;host name="iscsi.example.com"/&gt;
&lt;device path="demo-target"/&gt;
&lt;/source&gt;
&lt;target&gt;
&lt;path&gt;/dev/disk/by-path&lt;/path&gt;
&lt;/target&gt;
&lt;/pool&gt;</pre>
<h3><a name="exampleVol">Storage volume</a></h3>
<pre>
fix storage volume inconsistencies in schema and doc * docs/schemas/storagevol.rng docs/formatstorage.html[.in] tests/storagevolschemadata/vol-qcow2.xml: fix storage volume inconsistencies in schema and document, patch by Ryota Ozaki daniel
2009-05-29 12:27:45 +00:00
&lt;volume&gt;
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
&lt;name&gt;sparse.img&lt;/name&gt;
&lt;allocation&gt;0&lt;/allocation&gt;
&lt;capacity unit="T"&gt;1&lt;/capacity&gt;
&lt;target&gt;
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
&lt;path&gt;/var/lib/virt/images/sparse.img&lt;/path&gt;
&lt;permissions&gt;
Fix owner and group in example volume XML The owner and group in the documentation examples were confusingly given as '0744'. They should be numeric uid and gid. Changed the examples to use the default uid and gid assigned to qemu in F12. * docs/formatstorage.html.in: Change example owner and group in volume XML
2009-12-14 15:23:26 +00:00
&lt;owner&gt;107&lt;/owner&gt;
&lt;group&gt;107&lt;/group&gt;
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
&lt;mode&gt;0744&lt;/mode&gt;
&lt;label&gt;virt_image_t&lt;/label&gt;
&lt;/permissions&gt;
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
&lt;/target&gt;
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
&lt;/volume&gt;</pre>
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
</body>
</html>
Reference in New Issue Copy Permalink