[libvirt] [PATCH] storage: document existing pools
Eric Blake
eblake at redhat.com
Tue Oct 15 23:18:54 UTC 2013
We forgot to document several pool types. Furthermore, the
RNG grammar did not allow arbitrary interleaving, which makes
it harder than necessary to create a new pool from XML.
* docs/formatstorage.html.in: Add docs for scsi, mpath, rbd, and
sheepdog.
* docs/schemas/storagepool.rng: Allow interleaving.
* tests/storagepoolxml2xmlin/pool-sheepdog.xml: Test interleave.
* tests/storagepoolxml2xmlin/pool-iscsi-auth.xml: Likewise.
Signed-off-by: Eric Blake <eblake at redhat.com>
---
docs/formatstorage.html.in | 44 +--
docs/schemas/storagepool.rng | 356 ++++++++++++++-----------
tests/storagepoolxml2xmlin/pool-iscsi-auth.xml | 12 +-
tests/storagepoolxml2xmlin/pool-sheepdog.xml | 6 +-
4 files changed, 238 insertions(+), 180 deletions(-)
diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in
index 3300d67..6f79b0c 100644
--- a/docs/formatstorage.html.in
+++ b/docs/formatstorage.html.in
@@ -18,9 +18,12 @@
The top level tag for a storage pool document is 'pool'. It has
a single attribute <code>type</code>, which is one of <code>dir</code>,
<code>fs</code>, <code>netfs</code>, <code>disk</code>,
- <code>iscsi</code>, <code>logical</code>. This corresponds to the
+ <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>
+ (<span class="since">since 0.9.13</span>), or <code>sheepdog</code>
+ (<span class="since">since 0.10.0</span>). 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>
@@ -64,7 +67,8 @@
<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:
+ the storage pool. The set of child elements that it will contain
+ depend on the pool type, but come from the following child elements:
</p>
<pre>
@@ -89,17 +93,18 @@
<dl>
<dt><code>device</code></dt>
- <dd>Provides the source for pools backed by physical devices.
+ <dd>Provides the source for pools backed by physical devices
+ (fs, logical, disk, iscsi).
May be repeated multiple times depending on backend driver. Contains
a single attribute <code>path</code> which is the fully qualified
path to the block device node. <span class="since">Since 0.4.1</span></dd>
- <dt><code>directory</code></dt>
- <dd>Provides the source for pools backed by directories. May
+ <dt><code>dir</code></dt>
+ <dd>Provides the source for pools backed by directories (dir). May
only occur once. Contains a single attribute <code>path</code>
which is the fully qualified path to the backing directory.
<span class="since">Since 0.4.1</span></dd>
<dt><code>adapter</code></dt>
- <dd>Provides the source for pools backed by SCSI adapters. May
+ <dd>Provides the source for pools backed by SCSI adapters (scsi). May
only occur once. Attribute <code>name</code> is the SCSI adapter
name (ex. "scsi_host1". NB, although a name such as "host1" is
still supported for backwards compatibility, it is not recommended).
@@ -120,7 +125,8 @@
<span class="since">Since 0.6.2</span></dd>
<dt><code>host</code></dt>
<dd>Provides the source for pools backed by storage from a
- remote server. Will be used in combination with a <code>directory</code>
+ remote server (netfs, iscsi, rbd, sheepdog). 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
@@ -128,18 +134,19 @@
<dt><code>auth</code></dt>
<dd>If present, the <code>auth</code> element provides the
authentication credentials needed to access the source by the
- setting of the <code>type</code> attribute. The <code>type</code>
- must be either "chap" or "ceph". Additionally a mandatory attribute
+ setting of the <code>type</code> attribute (iscsi,
+ rbd). 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
<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
- to the object that manages the password. The secret element
- <code>type</code> must be either "ceph" or "iscsi". Use "ceph" for
- Ceph RBD (Rados Block Device) network sources and use "iscsi" for CHAP
- (Challenge-Handshake Authentication Protocol) iSCSI targets.
+ to the object that manages the password.
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
@@ -148,11 +155,12 @@
</dd>
<dt><code>name</code></dt>
<dd>Provides the source for pools backed by storage from a
- named element (e.g., a logical volume group name).
+ named element (logical, rbd, sheepdog).
Contains a string identifier.
<span class="since">Since 0.4.5</span></dd>
<dt><code>format</code></dt>
- <dd>Provides information about the format of the pool. This
+ <dd>Provides information about the format of the pool (fs,
+ netfs, disk, logical). This
contains a single attribute <code>type</code> whose value is
backend specific. This is typically used to indicate filesystem
type, or network filesystem type, or partition table type, or
@@ -174,7 +182,9 @@
<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
+ <code>pool</code> element for some types of pools (dir, fs,
+ netfs, logical, disk, iscsi, scsi, mpath). This tag is used to
+ describe the mapping of
the storage pool into the host filesystem. It can contain the following
child elements:
</p>
diff --git a/docs/schemas/storagepool.rng b/docs/schemas/storagepool.rng
index a4ef5af..66d3c22 100644
--- a/docs/schemas/storagepool.rng
+++ b/docs/schemas/storagepool.rng
@@ -29,192 +29,224 @@
<attribute name='type'>
<value>dir</value>
</attribute>
- <ref name='commonmetadata'/>
- <ref name='sizing'/>
- <ref name='sourcedir'/>
- <ref name='target'/>
+ <interleave>
+ <ref name='commonmetadata'/>
+ <ref name='sizing'/>
+ <ref name='sourcedir'/>
+ <ref name='target'/>
+ </interleave>
</define>
<define name='poolfs'>
<attribute name='type'>
<value>fs</value>
</attribute>
- <ref name='commonmetadata'/>
- <ref name='sizing'/>
- <ref name='sourcefs'/>
- <ref name='target'/>
+ <interleave>
+ <ref name='commonmetadata'/>
+ <ref name='sizing'/>
+ <ref name='sourcefs'/>
+ <ref name='target'/>
+ </interleave>
</define>
<define name='poolnetfs'>
<attribute name='type'>
<value>netfs</value>
</attribute>
- <ref name='commonmetadata'/>
- <ref name='sizing'/>
- <ref name='sourcenetfs'/>
- <ref name='target'/>
+ <interleave>
+ <ref name='commonmetadata'/>
+ <ref name='sizing'/>
+ <ref name='sourcenetfs'/>
+ <ref name='target'/>
+ </interleave>
</define>
<define name='poollogical'>
<attribute name='type'>
<value>logical</value>
</attribute>
- <ref name='commonmetadata'/>
- <ref name='sizing'/>
- <ref name='sourcelogical'/>
- <ref name='targetlogical'/>
+ <interleave>
+ <ref name='commonmetadata'/>
+ <ref name='sizing'/>
+ <ref name='sourcelogical'/>
+ <ref name='targetlogical'/>
+ </interleave>
</define>
<define name='pooldisk'>
<attribute name='type'>
<value>disk</value>
</attribute>
- <ref name='commonmetadata'/>
- <ref name='sizing'/>
- <ref name='sourcedisk'/>
- <ref name='target'/>
+ <interleave>
+ <ref name='commonmetadata'/>
+ <ref name='sizing'/>
+ <ref name='sourcedisk'/>
+ <ref name='target'/>
+ </interleave>
</define>
<define name='pooliscsi'>
<attribute name='type'>
<value>iscsi</value>
</attribute>
- <ref name='commonmetadata'/>
- <ref name='sizing'/>
- <ref name='sourceiscsi'/>
- <ref name='target'/>
+ <interleave>
+ <ref name='commonmetadata'/>
+ <ref name='sizing'/>
+ <ref name='sourceiscsi'/>
+ <ref name='target'/>
+ </interleave>
</define>
<define name='poolscsi'>
<attribute name='type'>
<value>scsi</value>
</attribute>
- <ref name='commonmetadata'/>
- <ref name='sizing'/>
- <ref name='sourcescsi'/>
- <ref name='target'/>
+ <interleave>
+ <ref name='commonmetadata'/>
+ <ref name='sizing'/>
+ <ref name='sourcescsi'/>
+ <ref name='target'/>
+ </interleave>
</define>
<define name='poolmpath'>
<attribute name='type'>
<value>mpath</value>
</attribute>
- <ref name='commonmetadata'/>
- <ref name='sizing'/>
- <optional>
- <ref name='sourcempath'/>
- </optional>
- <ref name='target'/>
+ <interleave>
+ <ref name='commonmetadata'/>
+ <ref name='sizing'/>
+ <optional>
+ <ref name='sourcempath'/>
+ </optional>
+ <ref name='target'/>
+ </interleave>
</define>
<define name='poolrbd'>
<attribute name='type'>
<value>rbd</value>
</attribute>
- <ref name='commonmetadata'/>
- <ref name='sizing'/>
- <ref name='sourcerbd'/>
+ <interleave>
+ <ref name='commonmetadata'/>
+ <ref name='sizing'/>
+ <ref name='sourcerbd'/>
+ </interleave>
</define>
<define name='poolsheepdog'>
<attribute name='type'>
<value>sheepdog</value>
</attribute>
- <ref name='commonmetadata'/>
- <ref name='sizing'/>
- <ref name='sourcesheepdog'/>
+ <interleave>
+ <ref name='commonmetadata'/>
+ <ref name='sizing'/>
+ <ref name='sourcesheepdog'/>
+ </interleave>
</define>
<define name='sourceinfovendor'>
- <optional>
- <element name='vendor'>
- <attribute name='name'>
- <text/>
- </attribute>
- </element>
- </optional>
- <optional>
- <element name='product'>
- <attribute name='name'>
- <text/>
- </attribute>
- </element>
- </optional>
+ <interleave>
+ <optional>
+ <element name='vendor'>
+ <attribute name='name'>
+ <text/>
+ </attribute>
+ </element>
+ </optional>
+ <optional>
+ <element name='product'>
+ <attribute name='name'>
+ <text/>
+ </attribute>
+ </element>
+ </optional>
+ </interleave>
</define>
<define name='commonmetadata'>
- <element name='name'>
- <ref name='genericName'/>
- </element>
- <optional>
- <element name='uuid'>
- <ref name='UUID'/>
+ <interleave>
+ <element name='name'>
+ <ref name='genericName'/>
</element>
- </optional>
+ <optional>
+ <element name='uuid'>
+ <ref name='UUID'/>
+ </element>
+ </optional>
+ </interleave>
</define>
<define name='sizing'>
- <optional>
- <element name='capacity'>
- <ref name='scaledInteger'/>
- </element>
- </optional>
- <optional>
- <element name='allocation'>
- <ref name='scaledInteger'/>
- </element>
- </optional>
- <optional>
- <element name='available'>
- <ref name='scaledInteger'/>
- </element>
- </optional>
+ <interleave>
+ <optional>
+ <element name='capacity'>
+ <ref name='scaledInteger'/>
+ </element>
+ </optional>
+ <optional>
+ <element name='allocation'>
+ <ref name='scaledInteger'/>
+ </element>
+ </optional>
+ <optional>
+ <element name='available'>
+ <ref name='scaledInteger'/>
+ </element>
+ </optional>
+ </interleave>
</define>
<define name='permissions'>
<optional>
<element name='permissions'>
- <element name='mode'>
- <ref name='octalMode'/>
- </element>
- <element name='owner'>
- <choice>
- <ref name='unsignedInt'/>
- <value>-1</value>
- </choice>
- </element>
- <element name='group'>
- <choice>
- <ref name='unsignedInt'/>
- <value>-1</value>
- </choice>
- </element>
- <optional>
- <element name='label'>
- <text/>
- </element>
- </optional>
+ <interleave>
+ <element name='mode'>
+ <ref name='octalMode'/>
+ </element>
+ <element name='owner'>
+ <choice>
+ <ref name='unsignedInt'/>
+ <value>-1</value>
+ </choice>
+ </element>
+ <element name='group'>
+ <choice>
+ <ref name='unsignedInt'/>
+ <value>-1</value>
+ </choice>
+ </element>
+ <optional>
+ <element name='label'>
+ <text/>
+ </element>
+ </optional>
+ </interleave>
</element>
</optional>
</define>
<define name='target'>
<element name='target'>
- <element name='path'>
- <ref name='absFilePath'/>
- </element>
- <ref name='permissions'/>
+ <interleave>
+ <element name='path'>
+ <ref name='absFilePath'/>
+ </element>
+ <ref name='permissions'/>
+ </interleave>
</element>
</define>
<define name='targetlogical'>
<element name='target'>
- <optional>
- <element name='path'>
- <ref name='absFilePath'/>
- </element>
- </optional>
- <ref name='permissions'/>
+ <interleave>
+ <optional>
+ <element name='path'>
+ <ref name='absFilePath'/>
+ </element>
+ </optional>
+ <ref name='permissions'/>
+ </interleave>
</element>
</define>
@@ -413,74 +445,86 @@
<define name='sourcefs'>
<element name='source'>
- <ref name='sourceinfodev'/>
- <ref name='sourcefmtfs'/>
- <optional>
- <ref name='sourceinfovendor'/>
- </optional>
+ <interleave>
+ <ref name='sourceinfodev'/>
+ <ref name='sourcefmtfs'/>
+ <optional>
+ <ref name='sourceinfovendor'/>
+ </optional>
+ </interleave>
</element>
</define>
<define name='sourcenetfs'>
<element name='source'>
- <ref name='sourceinfohost'/>
- <ref name='sourceinfodir'/>
- <ref name='sourcefmtnetfs'/>
- <optional>
- <ref name='sourceinfovendor'/>
- </optional>
+ <interleave>
+ <ref name='sourceinfohost'/>
+ <ref name='sourceinfodir'/>
+ <ref name='sourcefmtnetfs'/>
+ <optional>
+ <ref name='sourceinfovendor'/>
+ </optional>
+ </interleave>
</element>
</define>
<define name='sourcelogical'>
<element name='source'>
- <oneOrMore>
+ <interleave>
+ <oneOrMore>
+ <optional>
+ <ref name='sourceinfoname'/>
+ </optional>
+ <optional>
+ <ref name='sourceinfodev'/>
+ </optional>
+ </oneOrMore>
+ <ref name='sourcefmtlogical'/>
<optional>
- <ref name='sourceinfoname'/>
- </optional>
- <optional>
- <ref name='sourceinfodev'/>
+ <ref name='sourceinfovendor'/>
</optional>
- </oneOrMore>
- <ref name='sourcefmtlogical'/>
- <optional>
- <ref name='sourceinfovendor'/>
- </optional>
+ </interleave>
</element>
</define>
<define name='sourcedisk'>
<element name='source'>
- <ref name='sourceinfodev'/>
- <ref name='sourcefmtdisk'/>
- <optional>
- <ref name='sourceinfovendor'/>
- </optional>
+ <interleave>
+ <ref name='sourceinfodev'/>
+ <ref name='sourcefmtdisk'/>
+ <optional>
+ <ref name='sourceinfovendor'/>
+ </optional>
+ </interleave>
</element>
</define>
<define name='sourceiscsi'>
<element name='source'>
- <ref name='sourceinfohost'/>
- <ref name='sourceinfodev'/>
- <optional>
- <ref name='initiatorinfo'/>
- </optional>
- <optional>
- <ref name='sourceinfoauth'/>
- </optional>
- <optional>
- <ref name='sourceinfovendor'/>
- </optional>
+ <interleave>
+ <ref name='sourceinfohost'/>
+ <ref name='sourceinfodev'/>
+ <optional>
+ <ref name='initiatorinfo'/>
+ </optional>
+ <optional>
+ <ref name='sourceinfoauth'/>
+ </optional>
+ <optional>
+ <ref name='sourceinfovendor'/>
+ </optional>
+ </interleave>
</element>
</define>
<define name='sourcescsi'>
<element name='source'>
- <ref name='sourceinfoadapter'/>
- <optional>
- <ref name='sourceinfovendor'/>
- </optional>
+ <interleave>
+ <ref name='sourceinfoadapter'/>
+ <optional>
+ <ref name='sourceinfovendor'/>
+ </optional>
+ </interleave>
</element>
</define>
@@ -492,18 +536,22 @@
<define name='sourcerbd'>
<element name='source'>
- <ref name='sourceinfoname'/>
- <ref name='sourceinfohost'/>
- <optional>
- <ref name='sourceinfoauth'/>
- </optional>
+ <interleave>
+ <ref name='sourceinfoname'/>
+ <ref name='sourceinfohost'/>
+ <optional>
+ <ref name='sourceinfoauth'/>
+ </optional>
+ </interleave>
</element>
</define>
<define name='sourcesheepdog'>
<element name='source'>
- <ref name='sourceinfohost'/>
- <ref name='sourceinfoname'/>
+ <interleave>
+ <ref name='sourceinfohost'/>
+ <ref name='sourceinfoname'/>
+ </interleave>
</element>
</define>
diff --git a/tests/storagepoolxml2xmlin/pool-iscsi-auth.xml b/tests/storagepoolxml2xmlin/pool-iscsi-auth.xml
index c81eb60..5e5d336 100644
--- a/tests/storagepoolxml2xmlin/pool-iscsi-auth.xml
+++ b/tests/storagepoolxml2xmlin/pool-iscsi-auth.xml
@@ -1,19 +1,19 @@
<pool type='iscsi'>
- <name>virtimages</name>
- <uuid>e9392370-2917-565e-692b-d057f46512d6</uuid>
<source>
- <host name="iscsi.example.com"/>
- <device path="demo-target"/>
<auth type='chap' username='admin'>
<secret uuid='2ec115d7-3a88-3ceb-bc12-0ac909a6fd87'/>
</auth>
+ <device path="demo-target"/>
+ <host name="iscsi.example.com"/>
</source>
+ <uuid>e9392370-2917-565e-692b-d057f46512d6</uuid>
<target>
- <path>/dev/disk/by-path</path>
<permissions>
- <mode>0700</mode>
<owner>0</owner>
+ <mode>0700</mode>
<group>0</group>
</permissions>
+ <path>/dev/disk/by-path</path>
</target>
+ <name>virtimages</name>
</pool>
diff --git a/tests/storagepoolxml2xmlin/pool-sheepdog.xml b/tests/storagepoolxml2xmlin/pool-sheepdog.xml
index 1287047..49b6baf 100644
--- a/tests/storagepoolxml2xmlin/pool-sheepdog.xml
+++ b/tests/storagepoolxml2xmlin/pool-sheepdog.xml
@@ -1,8 +1,8 @@
<pool type='sheepdog'>
- <name>sheepdog</name>
- <uuid>65fcba04-5b13-bd93-cff3-52ce48e11ad7</uuid>
<source>
- <host name='localhost' port='7000'/>
<name>sheepdog</name>
+ <host name='localhost' port='7000'/>
</source>
+ <uuid>65fcba04-5b13-bd93-cff3-52ce48e11ad7</uuid>
+ <name>sheepdog</name>
</pool>
--
1.8.3.1
More information about the libvir-list
mailing list