[PATCH] storage: document existing pools

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxx>
---
 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

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]