[libvirt] [PATCH] storage: document existing pools

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(a)redhat.com&gt; --- 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