External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-12-23 22:25:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
5028160523
libvirt/docs/formatstorage.html.in

546 lines
26 KiB
HTML
Raw Normal View History

Fix multiple formatting problems in HTML docs The rule generating the HTML docs passing the --html flag to xsltproc. This makes it use the legacy HTML parser, which either ignores or tries to fix all sorts of broken XML tags. There's no reason why we should be writing broken XML in the first place, so removing --html and adding the XHTML doctype to all files forces us to create good XML. This adds the XHTML doc type and fixes many, many XML tag problems it exposes. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-05-03 14:25:37 +00:00
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
Split website out into one file per page. APply new layout and styling
2008-04-23 17:08:31 +00:00
<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>,
docs: add spaces to formatstorage.html Let the pool types breathe.
2013-06-04 13:20:51 +00:00
<code>fs</code>, <code>netfs</code>, <code>disk</code>,
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
<code>iscsi</code>, <code>logical</code>, <code>scsi</code>
(all <span class="since">since 0.4.1</span>), <code>mpath</code>
(<span class="since">since 0.7.1</span>), <code>rbd</code>
storage: document gluster pool Add support for a new <pool type='gluster'>, similar to RBD and Sheepdog. Terminology wise, a gluster volume forms a libvirt storage pool, within the gluster volume, individual files are treated as libvirt storage volumes. * docs/schemas/storagepool.rng (poolgluster): New pool type. * docs/formatstorage.html.in: Document gluster. * docs/storage.html.in: Likewise, and contrast it with netfs. * tests/storagepoolxml2xmlin/pool-gluster.xml: New test. * tests/storagepoolxml2xmlout/pool-gluster.xml: Likewise. * tests/storagepoolxml2xmltest.c (mymain): Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 23:06:18 +00:00
(<span class="since">since 0.9.13</span>), <code>sheepdog</code>
(<span class="since">since 0.10.0</span>),
or <code>gluster</code> (<span class="since">since
1.2.0</span>). This corresponds to the
docs: add spaces to formatstorage.html Let the pool types breathe.
2013-06-04 13:20:51 +00:00
storage backend drivers listed further along in this document.
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</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
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
the storage pool. The set of child elements that it will contain
depend on the pool type, but come from the following child elements:
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</p>
<pre>
...
&lt;source&gt;
&lt;host name="iscsi.example.com"/&gt;
&lt;device path="demo-target"/&gt;
storage_pool: Rework chap XML to mimic ceph The existing 'chap' XML logic was never used - just defined. Rather than try to insert a square peg into a round hole, blow it up and rewrite the logic to follow the 'ceph' format. Remove the former "chap.login" and "chap.passwd" fields and replace with "chap.username" and "chap.secret" in _virStoragePoolAuthChap. Adjust the virStoragePoolDefParseAuthChap() to process. Change the rng file to describe the new layout Update the formatstorage.html to describe the usage of the secret element to mention that the secret type "iscsi" and "ceph" can be used to storage pool too. Update the formatsecret.html to include a reference to the storage pool Update tests to handle the changes from 'login' and 'passwd' to 'username' and '<secret>' format
2013-07-13 18:29:55 +00:00
&lt;auth type='chap' username='myname'&gt;
&lt;secret type='iscsi' usage='mycluster_myname'/&gt;
&lt;/auth&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
New XML attributes for storage pool source adapter This introduces 4 new attributes for storage pool source adapter. E.g. <adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/> Attribute 'type' can be either 'scsi_host' or 'fc_host', and defaults to 'scsi_host' if attribute 'name' is specified. I.e. It's optional for 'scsi_host' adapter, for back-compat reason. However, mandatory for 'fc_host' adapter and any new future adapter types. Attribute 'parent' is to specify the parent for the fc_host adapter. * docs/formatstorage.html.in: - Add documents for the 4 new attrs * docs/schemas/storagepool.rng: - Add RNG schema * src/conf/storage_conf.c: - Parse and format the new XMLs * src/conf/storage_conf.h: - New struct virStoragePoolSourceAdapter, replace "char *adapter" with it; - New enum virStoragePoolSourceAdapterType * src/libvirt_private.syms: - Export TypeToString and TypeFromString * src/phyp/phyp_driver.c: - Replace "adapter" with "adapter.data.name", which is member of the union of the new struct virStoragePoolSourceAdapter now. Later patch will add the checking, as "adapter.data.name" is only valid for "scsi_host" adapter. * src/storage/storage_backend_scsi.c: - Like above * tests/storagepoolxml2xmlin/pool-scsi-type-scsi-host.xml: * tests/storagepoolxml2xmlin/pool-scsi-type-fc-host.xml: - New test for 'fc_host' and "scsi_host" adapter * tests/storagepoolxml2xmlout/pool-scsi.xml: - Change the expected output, as the 'type' defaults to 'scsi_host' if 'name" specified now * tests/storagepoolxml2xmlout/pool-scsi-type-scsi-host.xml: * tests/storagepoolxml2xmlout/pool-scsi-type-fc-host.xml: - New test * tests/storagepoolxml2xmltest.c: - Include the test
2013-03-25 16:43:36 +00:00
<pre>
...
&lt;source&gt;
&lt;adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/&gt;
&lt;/source&gt;
...</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>
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
<dd>Provides the source for pools backed by physical devices
(pool types <code>fs</code>, <code>logical</code>, <code>disk</code>,
<code>iscsi</code>).
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>
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
<dt><code>dir</code></dt>
<dd>Provides the source for pools backed by directories (pool
storage: document gluster pool Add support for a new <pool type='gluster'>, similar to RBD and Sheepdog. Terminology wise, a gluster volume forms a libvirt storage pool, within the gluster volume, individual files are treated as libvirt storage volumes. * docs/schemas/storagepool.rng (poolgluster): New pool type. * docs/formatstorage.html.in: Document gluster. * docs/storage.html.in: Likewise, and contrast it with netfs. * tests/storagepoolxml2xmlin/pool-gluster.xml: New test. * tests/storagepoolxml2xmlout/pool-gluster.xml: Likewise. * tests/storagepoolxml2xmltest.c (mymain): Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 23:06:18 +00:00
type <code>dir</code>), or optionally to select a subdirectory
within a pool that resembles a filesystem (pool
type <code>gluster</code>). 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>
Fix /pool/storage/directory@path documentation Because of a wrong copy and paste, the documentation was saying that 'path' is the path to a block device node while it's a path to a directory.
2013-03-19 11:43:20 +00:00
which is the fully qualified path to the backing directory.
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>
docs: storage: Document SCSI pools
2010-02-22 21:50:04 +00:00
<dt><code>adapter</code></dt>
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
<dd>Provides the source for pools backed by SCSI adapters (pool
type <code>scsi</code>). May
New XML attributes for storage pool source adapter This introduces 4 new attributes for storage pool source adapter. E.g. <adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/> Attribute 'type' can be either 'scsi_host' or 'fc_host', and defaults to 'scsi_host' if attribute 'name' is specified. I.e. It's optional for 'scsi_host' adapter, for back-compat reason. However, mandatory for 'fc_host' adapter and any new future adapter types. Attribute 'parent' is to specify the parent for the fc_host adapter. * docs/formatstorage.html.in: - Add documents for the 4 new attrs * docs/schemas/storagepool.rng: - Add RNG schema * src/conf/storage_conf.c: - Parse and format the new XMLs * src/conf/storage_conf.h: - New struct virStoragePoolSourceAdapter, replace "char *adapter" with it; - New enum virStoragePoolSourceAdapterType * src/libvirt_private.syms: - Export TypeToString and TypeFromString * src/phyp/phyp_driver.c: - Replace "adapter" with "adapter.data.name", which is member of the union of the new struct virStoragePoolSourceAdapter now. Later patch will add the checking, as "adapter.data.name" is only valid for "scsi_host" adapter. * src/storage/storage_backend_scsi.c: - Like above * tests/storagepoolxml2xmlin/pool-scsi-type-scsi-host.xml: * tests/storagepoolxml2xmlin/pool-scsi-type-fc-host.xml: - New test for 'fc_host' and "scsi_host" adapter * tests/storagepoolxml2xmlout/pool-scsi.xml: - Change the expected output, as the 'type' defaults to 'scsi_host' if 'name" specified now * tests/storagepoolxml2xmlout/pool-scsi-type-scsi-host.xml: * tests/storagepoolxml2xmlout/pool-scsi-type-fc-host.xml: - New test * tests/storagepoolxml2xmltest.c: - Include the test
2013-03-25 16:43:36 +00:00
only occur once. Attribute <code>name</code> is the SCSI adapter
storage: Make the adapter name be consistent with node device driver node device driver names the HBA like "scsi_host5", but storage driver uses "host5", which could make the user confused. This changes them to be consistent. However, for back-compat reason, adapter name like "host5" is still supported.
2013-03-25 16:43:37 +00:00
name (ex. "scsi_host1". NB, although a name such as "host1" is
still supported for backwards compatibility, it is not recommended).
Attribute <code>type</code> (<span class="since">1.0.5</span>)
specifies the adapter type. Valid values are "fc_host" and "scsi_host".
If omitted and the <code>name</code> attribute is specified, then it
defaults to "scsi_host". To keep backwards compatibility, the attribute
New XML attributes for storage pool source adapter This introduces 4 new attributes for storage pool source adapter. E.g. <adapter type='fc_host' parent='scsi_host5' wwnn='20000000c9831b4b' wwpn='10000000c9831b4b'/> Attribute 'type' can be either 'scsi_host' or 'fc_host', and defaults to 'scsi_host' if attribute 'name' is specified. I.e. It's optional for 'scsi_host' adapter, for back-compat reason. However, mandatory for 'fc_host' adapter and any new future adapter types. Attribute 'parent' is to specify the parent for the fc_host adapter. * docs/formatstorage.html.in: - Add documents for the 4 new attrs * docs/schemas/storagepool.rng: - Add RNG schema * src/conf/storage_conf.c: - Parse and format the new XMLs * src/conf/storage_conf.h: - New struct virStoragePoolSourceAdapter, replace "char *adapter" with it; - New enum virStoragePoolSourceAdapterType * src/libvirt_private.syms: - Export TypeToString and TypeFromString * src/phyp/phyp_driver.c: - Replace "adapter" with "adapter.data.name", which is member of the union of the new struct virStoragePoolSourceAdapter now. Later patch will add the checking, as "adapter.data.name" is only valid for "scsi_host" adapter. * src/storage/storage_backend_scsi.c: - Like above * tests/storagepoolxml2xmlin/pool-scsi-type-scsi-host.xml: * tests/storagepoolxml2xmlin/pool-scsi-type-fc-host.xml: - New test for 'fc_host' and "scsi_host" adapter * tests/storagepoolxml2xmlout/pool-scsi.xml: - Change the expected output, as the 'type' defaults to 'scsi_host' if 'name" specified now * tests/storagepoolxml2xmlout/pool-scsi-type-scsi-host.xml: * tests/storagepoolxml2xmlout/pool-scsi-type-fc-host.xml: - New test * tests/storagepoolxml2xmltest.c: - Include the test
2013-03-25 16:43:36 +00:00
<code>type</code> is optional for the "scsi_host" adapter, but
mandatory for the "fc_host" adapter. Attributes <code>wwnn</code>
(Word Wide Node Name) and <code>wwpn</code> (Word Wide Port Name)
(<span class="since">1.0.4</span>) are used by the "fc_host" adapter
to uniquely identify the device in the Fibre Channel storage fabric
(the device can be either a HBA or vHBA). Both wwnn and wwpn should
be specified (See command 'virsh nodedev-dumpxml' to known how to get
wwnn/wwpn of a (v)HBA). The optional attribute <code>parent</code>
(<span class="since">1.0.4</span>) specifies the parent device for
the "fc_host" adapter.
docs: storage: Document SCSI pools
2010-02-22 21:50:04 +00:00
<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
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
remote server (pool types <code>netfs</code>, <code>iscsi</code>,
storage: document gluster pool Add support for a new <pool type='gluster'>, similar to RBD and Sheepdog. Terminology wise, a gluster volume forms a libvirt storage pool, within the gluster volume, individual files are treated as libvirt storage volumes. * docs/schemas/storagepool.rng (poolgluster): New pool type. * docs/formatstorage.html.in: Document gluster. * docs/storage.html.in: Likewise, and contrast it with netfs. * tests/storagepoolxml2xmlin/pool-gluster.xml: New test. * tests/storagepoolxml2xmlout/pool-gluster.xml: Likewise. * tests/storagepoolxml2xmltest.c (mymain): Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 23:06:18 +00:00
<code>rbd</code>, <code>sheepdog</code>, <code>gluster</code>). Will be
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
used in combination with a <code>directory</code>
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
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>
storage_pool: Rework chap XML to mimic ceph The existing 'chap' XML logic was never used - just defined. Rather than try to insert a square peg into a round hole, blow it up and rewrite the logic to follow the 'ceph' format. Remove the former "chap.login" and "chap.passwd" fields and replace with "chap.username" and "chap.secret" in _virStoragePoolAuthChap. Adjust the virStoragePoolDefParseAuthChap() to process. Change the rng file to describe the new layout Update the formatstorage.html to describe the usage of the secret element to mention that the secret type "iscsi" and "ceph" can be used to storage pool too. Update the formatsecret.html to include a reference to the storage pool Update tests to handle the changes from 'login' and 'passwd' to 'username' and '<secret>' format
2013-07-13 18:29:55 +00:00
<dt><code>auth</code></dt>
<dd>If present, the <code>auth</code> element provides the
authentication credentials needed to access the source by the
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
setting of the <code>type</code> attribute (pool
types <code>iscsi</code>, <code>rbd</code>). The <code>type</code>
must be either "chap" or "ceph". Use "ceph" for
Ceph RBD (Rados Block Device) network sources and use "iscsi" for CHAP
(Challenge-Handshake Authentication Protocol) iSCSI
targets. Additionally a mandatory attribute
storage_pool: Rework chap XML to mimic ceph The existing 'chap' XML logic was never used - just defined. Rather than try to insert a square peg into a round hole, blow it up and rewrite the logic to follow the 'ceph' format. Remove the former "chap.login" and "chap.passwd" fields and replace with "chap.username" and "chap.secret" in _virStoragePoolAuthChap. Adjust the virStoragePoolDefParseAuthChap() to process. Change the rng file to describe the new layout Update the formatstorage.html to describe the usage of the secret element to mention that the secret type "iscsi" and "ceph" can be used to storage pool too. Update the formatsecret.html to include a reference to the storage pool Update tests to handle the changes from 'login' and 'passwd' to 'username' and '<secret>' format
2013-07-13 18:29:55 +00:00
<code>username</code> identifies the username to use during
authentication as well as a sub-element <code>secret</code> with
a mandatory attribute <code>type</code>, to tie back to a
<a href="formatsecret.html">libvirt secret object</a> that
holds the actual password or other credentials. The domain XML
intentionally does not expose the password, only the reference
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
to the object that manages the password.
storage_pool: Rework chap XML to mimic ceph The existing 'chap' XML logic was never used - just defined. Rather than try to insert a square peg into a round hole, blow it up and rewrite the logic to follow the 'ceph' format. Remove the former "chap.login" and "chap.passwd" fields and replace with "chap.username" and "chap.secret" in _virStoragePoolAuthChap. Adjust the virStoragePoolDefParseAuthChap() to process. Change the rng file to describe the new layout Update the formatstorage.html to describe the usage of the secret element to mention that the secret type "iscsi" and "ceph" can be used to storage pool too. Update the formatsecret.html to include a reference to the storage pool Update tests to handle the changes from 'login' and 'passwd' to 'username' and '<secret>' format
2013-07-13 18:29:55 +00:00
The <code>secret</code> element requires either a <code>uuid</code>
attribute with the UUID of the secret object or a <code>usage</code>
attribute matching the key that was specified in the
secret object. <span class="since">Since 0.9.7 for "ceph" and
1.1.1 for "chap"</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
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
named element (pool types <code>logical</code>, <code>rbd</code>,
storage: document gluster pool Add support for a new <pool type='gluster'>, similar to RBD and Sheepdog. Terminology wise, a gluster volume forms a libvirt storage pool, within the gluster volume, individual files are treated as libvirt storage volumes. * docs/schemas/storagepool.rng (poolgluster): New pool type. * docs/formatstorage.html.in: Document gluster. * docs/storage.html.in: Likewise, and contrast it with netfs. * tests/storagepoolxml2xmlin/pool-gluster.xml: New test. * tests/storagepoolxml2xmlout/pool-gluster.xml: Likewise. * tests/storagepoolxml2xmltest.c (mymain): Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 23:06:18 +00:00
<code>sheepdog</code>, <code>gluster</code>). Contains a
string identifier.
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.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>
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
<dd>Provides information about the format of the pool (pool
types <code>fs</code>, <code>netfs</code>, <code>disk</code>,
<code>logical</code>). 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
storage: document existing pools We forgot to document several pool types. * docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and sheepdog. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-10-15 22:59:48 +00:00
<code>pool</code> element for some types of pools (pool
types <code>dir</code>, <code>fs</code>, <code>netfs</code>,
<code>logical</code>, <code>disk</code>, <code>iscsi</code>,
<code>scsi</code>, <code>mpath</code>). This tag is used to
describe the mapping of
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
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;
Added timestamps to storage volumes The access, birth, modification and change times are added to storage volumes and corresponding xml representations. This shows up in the XML in this format: <timestamps> <atime>1341933637.027319099</atime> <mtime>1341933637.027319099</mtime> </timestamps> Signed-off-by: Eric Blake <eblake@redhat.com>
2012-07-25 07:43:37 +00:00
&lt;timestamps&gt;
&lt;atime&gt;1341933637.273190990&lt;/atime&gt;
&lt;mtime&gt;1341930622.047245868&lt;/mtime&gt;
&lt;ctime&gt;1341930622.047245868&lt;/ctime&gt;
&lt;/timestamps&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>
doc: storage pool permission copy-paste fix The description for <permissions> was copied from the storage volume section to the storage pool section, but the semantics are different: 1. Currently only the "dir", "fs" and "netfs" storage pools use it. 2. They use it only to build the final directory. 3. A default for the storage volumes can't be set. Signed-off-by: Philipp Hahn <hahn@univention.de>
2013-08-13 12:38:33 +00:00
<dd>This is currently only useful for directory or filesystem based
pools, which are mapped as a directory into the local filesystem
namespace. It provides information about the permissions to use for the
final directory when the pool is built. 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.4.1</span>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</dd>
Added timestamps to storage volumes The access, birth, modification and change times are added to storage volumes and corresponding xml representations. This shows up in the XML in this format: <timestamps> <atime>1341933637.027319099</atime> <mtime>1341933637.027319099</mtime> </timestamps> Signed-off-by: Eric Blake <eblake@redhat.com>
2012-07-25 07:43:37 +00:00
<dt><code>timestamps</code></dt>
<dd>Provides timing information about the volume. Up to four
sub-elements are present,
where <code>atime</code>, <code>btime</code>, <code>ctime</code>
and <code>mtime</code> hold the access, birth, change and
modification time of the volume, where known. The used time
format is &lt;seconds&gt;.&lt;nanoseconds&gt; since the
beginning of the epoch (1 Jan 1970). If nanosecond resolution
is 0 or otherwise unsupported by the host OS or filesystem,
then the nanoseconds part is omitted. This is a readonly
attribute and is ignored when creating a volume.
<span class="since">Since 0.10.0</span>
</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>
storage: expose volume meta-type in XML I got annoyed at having to use both 'virsh vol-list $pool --details' AND 'virsh vol-dumpxml $vol $pool' to learn if I had populated the volume correctly. Since two-thirds of the data present in virStorageVolGetInfo() already appears in virStorageVolGetXMLDesc(), this just adds the remaining piece of information, as: <volume type='...'> ... </volume> * docs/formatstorage.html.in: Document new <volume type=...>. * docs/schemas/storagevol.rng (vol): Add it to RelaxNG. * src/conf/storage_conf.h (virStorageVolTypeToString): Declare. * src/conf/storage_conf.c (virStorageVolTargetDefFormat): Output the metatype. (virStorageVolDefParseXML): Parse it, for unit tests. * tests/storagevolxml2xmlout/vol-*.xml: Update tests to match. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-11-19 20:14:54 +00:00
A storage volume will generally be either a file or a device
node; <span class="since">since 1.2.0</span>, an optional
output-only attribute <code>type</code> lists the actual type
storage: add network-dir as new storage volume type In the 'directory' and 'netfs' storage pools, a user can see both 'file' and 'dir' storage volume types, to know when they can descend into a subdirectory. But in a network-based storage pool, such as the upcoming 'gluster' pool, we use 'network' instead of 'file', and did not have any counterpart for a directory until this patch. Adding a new volume type 'network-dir' is better than reusing 'dir', because it makes it clear that the only way to access 'network' volumes within that container is through the network mounting (leaving 'dir' for something accessible in the local file system). * include/libvirt/libvirt.h.in (virStorageVolType): Expand enum. * docs/formatstorage.html.in: Document it. * docs/schemasa/storagevol.rng (vol): Allow new value. * src/conf/storage_conf.c (virStorageVol): Use new value. * src/qemu/qemu_command.c (qemuBuildVolumeString): Fix client. * src/qemu/qemu_conf.c (qemuTranslateDiskSourcePool): Likewise. * tools/virsh-volume.c (vshVolumeTypeToString): Likewise. * src/storage/storage_backend_fs.c (virStorageBackendFileSystemVolDelete): Likewise. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-11-18 23:43:06 +00:00
(file, block, dir, network, or netdir), which is also available
storage: expose volume meta-type in XML I got annoyed at having to use both 'virsh vol-list $pool --details' AND 'virsh vol-dumpxml $vol $pool' to learn if I had populated the volume correctly. Since two-thirds of the data present in virStorageVolGetInfo() already appears in virStorageVolGetXMLDesc(), this just adds the remaining piece of information, as: <volume type='...'> ... </volume> * docs/formatstorage.html.in: Document new <volume type=...>. * docs/schemas/storagevol.rng (vol): Add it to RelaxNG. * src/conf/storage_conf.h (virStorageVolTypeToString): Declare. * src/conf/storage_conf.c (virStorageVolTargetDefFormat): Output the metatype. (virStorageVolDefParseXML): Parse it, for unit tests. * tests/storagevolxml2xmlout/vol-*.xml: Update tests to match. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-11-19 20:14:54 +00:00
from <code>virStorageVolGetInfo()</code>. The storage volume
XML format is available <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
</p>
<h3><a name="StorageVolFirst">General metadata</a></h3>
<pre>
storage: expose volume meta-type in XML I got annoyed at having to use both 'virsh vol-list $pool --details' AND 'virsh vol-dumpxml $vol $pool' to learn if I had populated the volume correctly. Since two-thirds of the data present in virStorageVolGetInfo() already appears in virStorageVolGetXMLDesc(), this just adds the remaining piece of information, as: <volume type='...'> ... </volume> * docs/formatstorage.html.in: Document new <volume type=...>. * docs/schemas/storagevol.rng (vol): Add it to RelaxNG. * src/conf/storage_conf.h (virStorageVolTypeToString): Declare. * src/conf/storage_conf.c (virStorageVolTargetDefFormat): Output the metatype. (virStorageVolDefParseXML): Parse it, for unit tests. * tests/storagevolxml2xmlout/vol-*.xml: Update tests to match. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-11-19 20:14:54 +00:00
&lt;volume type='file'&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>
doc: storage: Explicitly state that it's possible to have non-unique key With most of our storage backends it's possible to have two separate volume keys to point to a single volume. (By creating sym/hard-links to local files or by mounting remote filesystems to two different locations and creating pools on top of them) Document this possibility.
2014-03-03 15:39:40 +00:00
<dd>Providing an identifier for the volume which identifies a
single volume. In some cases it's possible to have two distinct keys
identifying a single volume. This field 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: Clarify semantics of sparse storage volumes Sparse LVM volumes do not behave in the way one would naively expect. The allocation does not automatically increase (which is different from how sparse files work).
2013-03-11 13:42:40 +00:00
for sparse allocation though. Different types of pools may treat
sparse volumes differently. For example, the <code>logical</code>
pool will not automatically expand volume's allocation when it
gets full; the user is responsible for doing that or configuring
dmeventd to do so automatically.<br/>
docs: storage: Document capacity/alloc 'unit'
2010-02-22 20:52:14 +00:00
<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;
conf: add features to volume target XML Add <features> and <compat> elements to volume target XML. <compat> is a string which for qcow2 represents the QEMU version it should be compatible with. Valid values are 0.10 and 1.1. 1.1 is implicit if the <features> element is present, otherwise qemu-img default is used. 0.10 can be specified to explicitly create older images after the qemu-img default changes. <features> contains optional features, so far <lazy_refcounts/> is available, which enables caching of reference counters, improving performance for snapshots.
2013-05-16 10:38:26 +00:00
&lt;compat&gt;1.1&lt;/compat&gt;
storagevol: add nocow to vol xml Add 'nocow' to storage volume xml so that user can have an option to set NOCOW flag to the newly created volume. It's useful on btrfs file system to enhance performance. Btrfs has low performance when hosting VM images, even more when the guest in those VM are also using btrfs as file system. One way to mitigate this bad performance is to turn off COW attributes on VM files. Generally, there are two ways to turn off COW on btrfs: a) by mounting fs with nodatacow, then all newly created files will be NOCOW. b) per file. Add the NOCOW file attribute. It could only be done to empty or new files. This patch tries the second way, according to 'nocow' option, it could set NOCOW flag per file: for raw file images, handle 'nocow' in libvirt code; for non-raw file images, pass 'nocow=on' option to qemu-img, and let qemu-img to handle that (requires qemu-img version >= 2.1). Signed-off-by: Chunyan Liu <cyliu@suse.com>
2014-07-15 08:49:46 +00:00
&lt;nocow/&gt;
conf: add features to volume target XML Add <features> and <compat> elements to volume target XML. <compat> is a string which for qcow2 represents the QEMU version it should be compatible with. Valid values are 0.10 and 1.1. 1.1 is implicit if the <features> element is present, otherwise qemu-img default is used. 0.10 can be specified to explicitly create older images after the qemu-img default changes. <features> contains optional features, so far <lazy_refcounts/> is available, which enables caching of reference counters, improving performance for snapshots.
2013-05-16 10:38:26 +00:00
&lt;features&gt;
&lt;lazy_refcounts/&gt;
&lt;/features&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>
conf: add features to volume target XML Add <features> and <compat> elements to volume target XML. <compat> is a string which for qcow2 represents the QEMU version it should be compatible with. Valid values are 0.10 and 1.1. 1.1 is implicit if the <features> element is present, otherwise qemu-img default is used. 0.10 can be specified to explicitly create older images after the qemu-img default changes. <features> contains optional features, so far <lazy_refcounts/> is available, which enables caching of reference counters, improving performance for snapshots.
2013-05-16 10:38:26 +00:00
<dt><code>compat</code></dt>
<dd>Specify compatibility level. So far, this is only used for
<code>type='qcow2'</code> volumes. Valid values are <code>0.10</code>
and <code>1.1</code> so far, specifying QEMU version the images should
be compatible with. If the <code>feature</code> element is present,
1.1 is used. If omitted, qemu-img default is used.
Use 1.1.0 everywhere in the documentation Since we already have the v1.1.0-rc1 tag in git.
2013-06-25 13:25:29 +00:00
<span class="since">Since 1.1.0</span>
conf: add features to volume target XML Add <features> and <compat> elements to volume target XML. <compat> is a string which for qcow2 represents the QEMU version it should be compatible with. Valid values are 0.10 and 1.1. 1.1 is implicit if the <features> element is present, otherwise qemu-img default is used. 0.10 can be specified to explicitly create older images after the qemu-img default changes. <features> contains optional features, so far <lazy_refcounts/> is available, which enables caching of reference counters, improving performance for snapshots.
2013-05-16 10:38:26 +00:00
</dd>
storagevol: add nocow to vol xml Add 'nocow' to storage volume xml so that user can have an option to set NOCOW flag to the newly created volume. It's useful on btrfs file system to enhance performance. Btrfs has low performance when hosting VM images, even more when the guest in those VM are also using btrfs as file system. One way to mitigate this bad performance is to turn off COW attributes on VM files. Generally, there are two ways to turn off COW on btrfs: a) by mounting fs with nodatacow, then all newly created files will be NOCOW. b) per file. Add the NOCOW file attribute. It could only be done to empty or new files. This patch tries the second way, according to 'nocow' option, it could set NOCOW flag per file: for raw file images, handle 'nocow' in libvirt code; for non-raw file images, pass 'nocow=on' option to qemu-img, and let qemu-img to handle that (requires qemu-img version >= 2.1). Signed-off-by: Chunyan Liu <cyliu@suse.com>
2014-07-15 08:49:46 +00:00
<dt><code>nocow</code></dt>
<dd>Turn off COW of the newly created volume. So far, this is only valid
for a file image in btrfs file system. It will improve performance when
the file image is used in VM. To create non-raw file images, it
requires QEMU version since 2.1. <span class="since">Since 1.2.7</span>
</dd>
conf: add features to volume target XML Add <features> and <compat> elements to volume target XML. <compat> is a string which for qcow2 represents the QEMU version it should be compatible with. Valid values are 0.10 and 1.1. 1.1 is implicit if the <features> element is present, otherwise qemu-img default is used. 0.10 can be specified to explicitly create older images after the qemu-img default changes. <features> contains optional features, so far <lazy_refcounts/> is available, which enables caching of reference counters, improving performance for snapshots.
2013-05-16 10:38:26 +00:00
<dt><code>features</code></dt>
<dd>Format-specific features. Only used for <code>qcow2</code> now.
Valid sub-elements are:
<ul>
<li><code>&lt;lazy_refcounts/&gt;</code> - allow delayed reference
Use 1.1.0 everywhere in the documentation Since we already have the v1.1.0-rc1 tag in git.
2013-06-25 13:25:29 +00:00
counter updates. <span class="since">Since 1.1.0</span></li>
conf: add features to volume target XML Add <features> and <compat> elements to volume target XML. <compat> is a string which for qcow2 represents the QEMU version it should be compatible with. Valid values are 0.10 and 1.1. 1.1 is implicit if the <features> element is present, otherwise qemu-img default is used. 0.10 can be specified to explicitly create older images after the qemu-img default changes. <features> contains optional features, so far <lazy_refcounts/> is available, which enables caching of reference counters, improving performance for snapshots.
2013-05-16 10:38:26 +00:00
</ul>
</dd>
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
</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;
docs: Update iSCSI storage pool example Update the iSCSI storage pool example to include the secret
2013-08-07 13:32:54 +00:00
&lt;device path="iqn.2013-06.com.example:iscsi-pool"/&gt;
&lt;auth type='chap' username='myuser'&gt;
&lt;secret usage='libvirtiscsi'/&gt;
&lt;/auth&gt;
Added autogenerated TOC for network and storage XML reference docs
2008-05-06 23:23:55 +00:00
&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