Signed-off-by: John Ferlan <jferlan@redhat.com>
---
docs/docs.html.in | 1 +
docs/format.html.in | 1 +
docs/formatstoragecaps.html.in | 108 +++++++++++++++++++++++++++++++++
docs/index.html.in | 1 +
4 files changed, 111 insertions(+)
create mode 100644 docs/formatstoragecaps.html.in
diff --git a/docs/docs.html.in b/docs/docs.html.in
index 40e0e3b82e..d0ff844d0c 100644
--- a/docs/docs.html.in
+++ b/docs/docs.html.in
@@ -77,6 +77,7 @@
<a href="formatstorageencryption.html">storage encryption</a>,
<a href="formatcaps.html">capabilities</a>,
<a href="formatdomaincaps.html">domain capabilities</a>,
+ <a href="formatstoragecaps.html">storage pool capabilities</a>,
<a href="formatnode.html">node devices</a>,
<a href="formatsecret.html">secrets</a>,
<a href="formatsnapshot.html">snapshots</a></dd>
diff --git a/docs/format.html.in b/docs/format.html.in
index 22b23e3fc7..640a9957ee 100644
--- a/docs/format.html.in
+++ b/docs/format.html.in
@@ -21,6 +21,7 @@
<li><a href="formatstorageencryption.html">Storage encryption</a></li>
<li><a href="formatcaps.html">Capabilities</a></li>
<li><a href="formatdomaincaps.html">Domain capabilities</a></li>
+ <li><a href="formatstoragecaps.html">Storage Pool capabilities</a></li>
<li><a href="formatnode.html">Node devices</a></li>
<li><a href="formatsecret.html">Secrets</a></li>
<li><a href="formatsnapshot.html">Snapshots</a></li>
diff --git a/docs/formatstoragecaps.html.in b/docs/formatstoragecaps.html.in
new file mode 100644
index 0000000000..7f0641a3a8
--- /dev/null
+++ b/docs/formatstoragecaps.html.in
@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <body>
+ <h1>Storage Pool Capabilities XML format</h1>
+
+ <ul id="toc"></ul>
+
+ <h2><a id="Overview">Overview</a></h2>
+
+ <p>The Storage Pool Capabilities XML will provide the information
+ to determine what types of Storage Pools exist, whether the pool is
+ supported, and if relevant the source format types, the required
+ source elements, and the target volume format types. </p>
+
+ <p>The Storage Pool Capabilities XML provides more information than the
+ <a href="/html/libvirt-libvirt-host.html#virConnectGetCapabilities">
+ <code>virConnectGetCapabilities</code>
+ </a>
+ which only provides an enumerated list of supported pool types.</p>
+
+ <h2><a id="elements">Element and attribute overview</a></h2>
+
+ <p>A query interface was added to the virConnect API's to retrieve the
+ XML listing of the set of Storage Pool Capabilities
+ (<span class="since">Since 5.1.0</span>):</p>
+
+<pre>
+<a href="/html/libvirt-libvirt-domain.html#virConnectGetStoragePoolCapabilities">virConnectGetStoragePoolCapabilities</a>
+</pre>
+
+ <p>The root element that emulator capability XML document starts with is
+ named <code>storagepoolCapabilities</code>. There will be any number of
+ <code>pool</code> child elements with two attributes <code>type</code>
+ and <code>supported</code>. Each <code>pool</code> element may have
+ a <code>poolOptions</code> or <code>volOptions</code> subelements to
+ describe the available features. Sample XML output is:</p>
+
+<pre>
+<storagepoolCapabilities>
+ <pool type='dir' supported='yes'>
+ <volOptions>
+ <defaultFormat type='raw'</>
+ <enum name='targetFormatType'>
+ <value>none</value>
+ <value>raw</value>
+ ...
+ </enum>
+ </volOptions>
+ </pool>
+ <pool type='fs' supported='yes'>
+ <poolOptions>
+ <defaultFormat type='auto'</>
+ <enum name='sourceFormatType'>
+ <value>auto</value>
+ <value>ext2</value>
+ ...
+ </enum>
+ <enum name='requiredSourceElements'>
+ <value>device</value>
+ </enum>
+ </poolOptions>
+ <volOptions>
+ <defaultFormat type='raw'</>
+ <enum name='targetFormatType'>
+ <value>none</value>
+ <value>raw</value>
+ ...
+ </enum>
+ </volOptions>
+ </pool>
+ ...
+</storagepoolCapabilities>
+</pre>
+
+ <p>The following section decribes subelements of the
+ <code>poolOptions</code> and <code>volOptions</code> subelements </p>:
+
+ <dl>
+ <dt><code>defaultFormat</code></dt>
+ <dd>For the <code>poolOptions</code>, the <code>type</code> attribute
+ describes the default format name used for the pool source. For the
+ <code>volOptions</code>, the <code>type</code> attribute describes
+ the default volume name used for each volume.
+ </dd>
+ <dl>
+ <dt><code>enum</code></dt>
+ <dd>Each enum uses a name from the list below with any number of
+ <code>value</code> value subelements describing the valid values.
+ <dl>
+ <dt><code>sourceFormatType</code></dt>
+ <dd>Lists all the possible <code>poolOptions</code> source
+ pool format types.
+ </dd>
+ <dt><code>requiredSourceElements</code></dt>
+ <dd>Lists all the required <code>poolOptions</code> source
+ subelements required for a valid source pool element.
+ </dd>
+ <dt><code>targetFormatType</code></dt>
+ <dd>Lists all the possible <code>volOptions</code> target volume
+ format types.
+ </dd>
+ </dl>
+ </dd>
+ </dl>
+ </dl>
+ </body>
+</html>
diff --git a/docs/index.html.in b/docs/index.html.in
index 1f9f448399..f593445d06 100644
--- a/docs/index.html.in
+++ b/docs/index.html.in
@@ -66,6 +66,7 @@
<a href="formatstorageencryption.html">storage encryption</a>,
<a href="formatcaps.html">capabilities</a>,
<a href="formatdomaincaps.html">domain capabilities</a>,
+ <a href="formatstoragecaps.html">storage pool capabilities</a>,
<a href="formatnode.html">node devices</a>,
<a href="formatsecret.html">secrets</a>,
<a href="formatsnapshot.html">snapshots</a></dd>
--
2.20.1
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
On Tue, Feb 12, 2019 at 10:28:12AM -0500, John Ferlan wrote: > Signed-off-by: John Ferlan <jferlan@redhat.com> > --- > docs/docs.html.in | 1 + > docs/format.html.in | 1 + > docs/formatstoragecaps.html.in | 108 +++++++++++++++++++++++++++++++++ > docs/index.html.in | 1 + > 4 files changed, 111 insertions(+) > create mode 100644 docs/formatstoragecaps.html.in > > diff --git a/docs/docs.html.in b/docs/docs.html.in > index 40e0e3b82e..d0ff844d0c 100644 > --- a/docs/docs.html.in > +++ b/docs/docs.html.in > @@ -77,6 +77,7 @@ > <a href="formatstorageencryption.html">storage encryption</a>, > <a href="formatcaps.html">capabilities</a>, > <a href="formatdomaincaps.html">domain capabilities</a>, > + <a href="formatstoragecaps.html">storage pool capabilities</a>, > <a href="formatnode.html">node devices</a>, > <a href="formatsecret.html">secrets</a>, > <a href="formatsnapshot.html">snapshots</a></dd> > diff --git a/docs/format.html.in b/docs/format.html.in > index 22b23e3fc7..640a9957ee 100644 > --- a/docs/format.html.in > +++ b/docs/format.html.in > @@ -21,6 +21,7 @@ > <li><a href="formatstorageencryption.html">Storage encryption</a></li> > <li><a href="formatcaps.html">Capabilities</a></li> > <li><a href="formatdomaincaps.html">Domain capabilities</a></li> > + <li><a href="formatstoragecaps.html">Storage Pool capabilities</a></li> > <li><a href="formatnode.html">Node devices</a></li> > <li><a href="formatsecret.html">Secrets</a></li> > <li><a href="formatsnapshot.html">Snapshots</a></li> > diff --git a/docs/formatstoragecaps.html.in b/docs/formatstoragecaps.html.in > new file mode 100644 > index 0000000000..7f0641a3a8 > --- /dev/null > +++ b/docs/formatstoragecaps.html.in > @@ -0,0 +1,108 @@ > +<?xml version="1.0" encoding="UTF-8"?> > +<!DOCTYPE html> > +<html xmlns="http://www.w3.org/1999/xhtml"> > + <body> > + <h1>Storage Pool Capabilities XML format</h1> > + > + <ul id="toc"></ul> > + > + <h2><a id="Overview">Overview</a></h2> > + > + <p>The Storage Pool Capabilities XML will provide the information > + to determine what types of Storage Pools exist, whether the pool is > + supported, and if relevant the source format types, the required > + source elements, and the target volume format types. </p> > + > + <p>The Storage Pool Capabilities XML provides more information than the > + <a href="/html/libvirt-libvirt-host.html#virConnectGetCapabilities"> > + <code>virConnectGetCapabilities</code> > + </a> > + which only provides an enumerated list of supported pool types.</p> > + > + <h2><a id="elements">Element and attribute overview</a></h2> > + > + <p>A query interface was added to the virConnect API's to retrieve the > + XML listing of the set of Storage Pool Capabilities > + (<span class="since">Since 5.1.0</span>):</p> > + > +<pre> > +<a href="/html/libvirt-libvirt-domain.html#virConnectGetStoragePoolCapabilities">virConnectGetStoragePoolCapabilities</a> > +</pre> > + > + <p>The root element that emulator capability XML document starts with is > + named <code>storagepoolCapabilities</code>. There will be any number of > + <code>pool</code> child elements with two attributes <code>type</code> > + and <code>supported</code>. Each <code>pool</code> element may have > + a <code>poolOptions</code> or <code>volOptions</code> subelements to > + describe the available features. Sample XML output is:</p> > + > +<pre> > +<storagepoolCapabilities> > + <pool type='dir' supported='yes'> > + <volOptions> > + <defaultFormat type='raw'</> > + <enum name='targetFormatType'> > + <value>none</value> > + <value>raw</value> > + ... > + </enum> > + </volOptions> > + </pool> > + <pool type='fs' supported='yes'> > + <poolOptions> > + <defaultFormat type='auto'</> > + <enum name='sourceFormatType'> > + <value>auto</value> > + <value>ext2</value> > + ... > + </enum> > + <enum name='requiredSourceElements'> > + <value>device</value> > + </enum> > + </poolOptions> > + <volOptions> > + <defaultFormat type='raw'</> > + <enum name='targetFormatType'> > + <value>none</value> > + <value>raw</value> > + ... > + </enum> > + </volOptions> > + </pool> > + ... > +</storagepoolCapabilities> > +</pre> > + > + <p>The following section decribes subelements of the > + <code>poolOptions</code> and <code>volOptions</code> subelements </p>: > + > + <dl> > + <dt><code>defaultFormat</code></dt> > + <dd>For the <code>poolOptions</code>, the <code>type</code> attribute > + describes the default format name used for the pool source. For the > + <code>volOptions</code>, the <code>type</code> attribute describes > + the default volume name used for each volume. > + </dd> > + <dl> > + <dt><code>enum</code></dt> > + <dd>Each enum uses a name from the list below with any number of > + <code>value</code> value subelements describing the valid values. > + <dl> > + <dt><code>sourceFormatType</code></dt> > + <dd>Lists all the possible <code>poolOptions</code> source > + pool format types. > + </dd> > + <dt><code>requiredSourceElements</code></dt> > + <dd>Lists all the required <code>poolOptions</code> source > + subelements required for a valid source pool element. > + </dd> I know that this is now pushed and I just noticed that in the relevant BZ where you posted the output of storage capabilities. Why do we export <requiredSourceElements> in storage capabilities? It doesn't make any sense to have it there. Management applications using libvirt have to have some knowledge of libvirt and they have to know what elements are required for each storage pool type in order to create some sensible UI. In addition this is something that will most likely never change and will not depend on what packages are installed or how libvirt/qemu were compiled. IMHO we should drop this element from storage capabilities unless there was some motivation to include this information. Pavel > + <dt><code>targetFormatType</code></dt> > + <dd>Lists all the possible <code>volOptions</code> target volume > + format types. > + </dd> > + </dl> > + </dd> > + </dl> > + </dl> > + </body> > +</html> > diff --git a/docs/index.html.in b/docs/index.html.in > index 1f9f448399..f593445d06 100644 > --- a/docs/index.html.in > +++ b/docs/index.html.in > @@ -66,6 +66,7 @@ > <a href="formatstorageencryption.html">storage encryption</a>, > <a href="formatcaps.html">capabilities</a>, > <a href="formatdomaincaps.html">domain capabilities</a>, > + <a href="formatstoragecaps.html">storage pool capabilities</a>, > <a href="formatnode.html">node devices</a>, > <a href="formatsecret.html">secrets</a>, > <a href="formatsnapshot.html">snapshots</a></dd> > -- > 2.20.1 > > -- > libvir-list mailing list > libvir-list@redhat.com > https://www.redhat.com/mailman/listinfo/libvir-list -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
[...] >> + >> + <p>The following section decribes subelements of the >> + <code>poolOptions</code> and <code>volOptions</code> subelements </p>: >> + >> + <dl> >> + <dt><code>defaultFormat</code></dt> >> + <dd>For the <code>poolOptions</code>, the <code>type</code> attribute >> + describes the default format name used for the pool source. For the >> + <code>volOptions</code>, the <code>type</code> attribute describes >> + the default volume name used for each volume. >> + </dd> >> + <dl> >> + <dt><code>enum</code></dt> >> + <dd>Each enum uses a name from the list below with any number of >> + <code>value</code> value subelements describing the valid values. >> + <dl> >> + <dt><code>sourceFormatType</code></dt> >> + <dd>Lists all the possible <code>poolOptions</code> source >> + pool format types. >> + </dd> >> + <dt><code>requiredSourceElements</code></dt> >> + <dd>Lists all the required <code>poolOptions</code> source >> + subelements required for a valid source pool element. >> + </dd> > > I know that this is now pushed and I just noticed that in the relevant > BZ where you posted the output of storage capabilities. > > Why do we export <requiredSourceElements> in storage capabilities? > It doesn't make any sense to have it there. Management applications > using libvirt have to have some knowledge of libvirt and they have to > know what elements are required for each storage pool type in order to > create some sensible UI. In addition this is something that will most > likely never change and will not depend on what packages are installed > or how libvirt/qemu were compiled. Because it was data that perhaps someone would find useful when formulating XML for a storage pool. Each pool has different "required" elements that are hidden in the bowels of storage_conf and I figured it could be useful to have. Creating/defining a pool of a type that doesn't have a required element would cause a failure. > > IMHO we should drop this element from storage capabilities unless there > was some motivation to include this information. > IDC either way and am fine with dropping that element. The patches themselves were posted since 2/12, pinged on twice, sorry if you missed the details before I ended up pushing them. We have plenty of time before the 5.2.0 release to make a decision at least! John > Pavel > >> + <dt><code>targetFormatType</code></dt> >> + <dd>Lists all the possible <code>volOptions</code> target volume >> + format types. >> + </dd> >> + </dl> >> + </dd> >> + </dl> >> + </dl> >> + </body> >> +</html> [..] -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On Wed, Mar 06, 2019 at 12:21:02PM -0500, John Ferlan wrote: > > [...] > > >> + > >> + <p>The following section decribes subelements of the > >> + <code>poolOptions</code> and <code>volOptions</code> subelements </p>: > >> + > >> + <dl> > >> + <dt><code>defaultFormat</code></dt> > >> + <dd>For the <code>poolOptions</code>, the <code>type</code> attribute > >> + describes the default format name used for the pool source. For the > >> + <code>volOptions</code>, the <code>type</code> attribute describes > >> + the default volume name used for each volume. > >> + </dd> > >> + <dl> > >> + <dt><code>enum</code></dt> > >> + <dd>Each enum uses a name from the list below with any number of > >> + <code>value</code> value subelements describing the valid values. > >> + <dl> > >> + <dt><code>sourceFormatType</code></dt> > >> + <dd>Lists all the possible <code>poolOptions</code> source > >> + pool format types. > >> + </dd> > >> + <dt><code>requiredSourceElements</code></dt> > >> + <dd>Lists all the required <code>poolOptions</code> source > >> + subelements required for a valid source pool element. > >> + </dd> > > > > I know that this is now pushed and I just noticed that in the relevant > > BZ where you posted the output of storage capabilities. > > > > Why do we export <requiredSourceElements> in storage capabilities? > > It doesn't make any sense to have it there. Management applications > > using libvirt have to have some knowledge of libvirt and they have to > > know what elements are required for each storage pool type in order to > > create some sensible UI. In addition this is something that will most > > likely never change and will not depend on what packages are installed > > or how libvirt/qemu were compiled. > > Because it was data that perhaps someone would find useful when > formulating XML for a storage pool. Each pool has different "required" > elements that are hidden in the bowels of storage_conf and I figured it > could be useful to have. Creating/defining a pool of a type that doesn't > have a required element would cause a failure. > > > > IMHO we should drop this element from storage capabilities unless there > > was some motivation to include this information. > > > > IDC either way and am fine with dropping that element. The patches > themselves were posted since 2/12, pinged on twice, sorry if you missed > the details before I ended up pushing them. We have plenty of time > before the 5.2.0 release to make a decision at least! NP, my fault that I didn't notice that sooner, I just skimmed the patches telling myself that I'll review it later since I was working on virt-manager patches. Anyway, I'll send a patch to remove it from capabilities where we can decide what whether to keep it there or not. Pavel -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
© 2016 - 2026 Red Hat, Inc.