[libvirt] [PATCH 0/2] Update find-storage-pool-source[-as] man page
https://bugzilla.redhat.com/show_bug.cgi?id=921426 The first patch is just a change to the error message. As it turns out only the host is necessary to find iSCSI targets. I have to assume over time adjustments to the code made the need to provide the name obsolete, but I did not research exactly which change may have done that... The second patch is a virsh man page change to describe the functionality based on how the code works today. It's perhaps "of interest" that the rbd and sheepdog backends provide to means to find all possible sources. I also suppose zfs could use something, but I don't build with zfs. John Ferlan (2): iscsi: Adjust error message for findStorageSources backend virsh.pod: Update find-storage-pool-sources[-as] man page src/storage/storage_backend_iscsi.c | 5 ++--- tools/virsh.pod | 45 ++++++++++++++++++++++++++++++++----- 2 files changed, 41 insertions(+), 9 deletions(-) -- 2.1.0
The virStorageBackendISCSIFindPoolSources API only needs the 'host' name in order to discover iSCSI pools, it returns the various device paths. On input, it's also possible to further restrict a search by providing the port attribute for the host element and the (undocumented) initiator element. For example: $ virsh find-storage-pool-sources-as iscsi error: Failed to find any iscsi pool sources error: invalid argument: hostname and device path must be specified for iscsi sources $ virsh find-storage-pool-sources-as iscsi 192.168.122.1 <sources> <source> <host name='192.168.122.1' port='3260'/> <device path='iqn.2013-12.com.example:iscsi-chap-lclpool'/> </source> </sources> Signed-off-by: John Ferlan <jferlan@redhat.com> --- src/storage/storage_backend_iscsi.c | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/storage/storage_backend_iscsi.c b/src/storage/storage_backend_iscsi.c index 1d0cf73..079c767 100644 --- a/src/storage/storage_backend_iscsi.c +++ b/src/storage/storage_backend_iscsi.c @@ -178,9 +178,8 @@ virStorageBackendISCSIFindPoolSources(virConnectPtr conn ATTRIBUTE_UNUSED, virCheckFlags(0, NULL); if (!srcSpec) { - virReportError(VIR_ERR_INVALID_ARG, - "%s", _("hostname and device path " - "must be specified for iscsi sources")); + virReportError(VIR_ERR_INVALID_ARG, "%s", + _("hostname must be specified for iscsi sources")); return NULL; } -- 2.1.0
On Thu, Feb 26, 2015 at 04:43:53PM -0500, John Ferlan wrote:
The virStorageBackendISCSIFindPoolSources API only needs the 'host' name in order to discover iSCSI pools, it returns the various device paths. On input, it's also possible to further restrict a search by providing the port attribute for the host element and the (undocumented) initiator element.
For example:
$ virsh find-storage-pool-sources-as iscsi error: Failed to find any iscsi pool sources error: invalid argument: hostname and device path must be specified for iscsi sources
$ virsh find-storage-pool-sources-as iscsi 192.168.122.1 <sources> <source> <host name='192.168.122.1' port='3260'/> <device path='iqn.2013-12.com.example:iscsi-chap-lclpool'/> </source> </sources>
Signed-off-by: John Ferlan <jferlan@redhat.com> --- src/storage/storage_backend_iscsi.c | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-)
ACK
diff --git a/src/storage/storage_backend_iscsi.c b/src/storage/storage_backend_iscsi.c index 1d0cf73..079c767 100644 --- a/src/storage/storage_backend_iscsi.c +++ b/src/storage/storage_backend_iscsi.c @@ -178,9 +178,8 @@ virStorageBackendISCSIFindPoolSources(virConnectPtr conn ATTRIBUTE_UNUSED, virCheckFlags(0, NULL);
if (!srcSpec) { - virReportError(VIR_ERR_INVALID_ARG, - "%s", _("hostname and device path " - "must be specified for iscsi sources")); + virReportError(VIR_ERR_INVALID_ARG, "%s", + _("hostname must be specified for iscsi sources")); return NULL; }
-- 2.1.0
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
https://bugzilla.redhat.com/show_bug.cgi?id=921426 Add to the man page a more complete description of what exactly the command expects on input and will return on output based on what is currently supported. Perhaps missing findPoolSources implementations are backends for sheepdog and rbd. Also missing any backend is zfs. Signed-off-by: John Ferlan <jferlan@redhat.com> --- tools/virsh.pod | 45 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index 343f26f..915fab0 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -2940,16 +2940,49 @@ pools are similar to the ones used for domains. =item B<find-storage-pool-sources> I<type> [I<srcSpec>] -Returns XML describing all storage pools of a given I<type> that could -be found. If I<srcSpec> is provided, it is a file that contains XML -to further restrict the query for pools. +Returns XML describing all possible available storage pool sources that +could be used to create or define a storage pool of a given I<type>. If +I<srcSpec> is provided, it is a file that contains XML to further restrict +the query for pools. + +Not all storage pools support discovery in this manner. Furthermore, for +those that do support discovery, only specific XML elements are required +in order to return valid data, while other elements and even attributes +of some elements are ignored since they are not necessary to find the pool +based on the search criteria. The following lists the supported I<type> +options and the expected minimal XML elements used to perform the search. + +For a "netfs" or "gluster" pool, the minimal expected XML required is the +<host> element with a "name" attribute describing the IP address or hostname +to be used to find the pool. The "port" attribute will be ignored as will +any other provided XML elements in I<srcSpec>. + +For a "logical" pool, the contents of the I<srcSpec> file are ignored, +although if provided the file must at least exist. + +For an "iscsi" pool, the minimal expect XML required is the <host> element +with a "name" attribute describing the IP address or hostname to be used to +find the pool (the iSCSI server address). Optionally, the "port" attribute +may be provided, although it will default to 3260. Optionally, an <initiator> +XML element with a "name" attribute may be provided to further restrict the +iSCSI target search to a specific initiator for multi-iqn iSCSI storage pools. =item B<find-storage-pool-sources-as> I<type> [I<host>] [I<port>] [I<initiator>] -Returns XML describing all storage pools of a given I<type> that could -be found. If I<host>, I<port>, or I<initiator> are provided, they control -where the query is performed. +Rather than providing I<srcSpec> XML file for B<find-storage-pool-sources> +use this command option in order to have virsh generate the query XML file +using the optional arguments. The command will return the same output +XML as B<find-storage-pool-sources>. + +Use I<host> to describe a specific host to use for networked storage, such +as netfs, gluster, and iscsi I<type> pools. + +Use I<port> to further restrict which networked port to utilize for the +connection if required by the specific storage backend, such as iscsi. + +Use I<initiator> to further restrict the iscsi I<type> pool searches to +specific target initiators. =item B<pool-autostart> I<pool-or-uuid> [I<--disable>] -- 2.1.0
On Thu, Feb 26, 2015 at 04:43:54PM -0500, John Ferlan wrote:
https://bugzilla.redhat.com/show_bug.cgi?id=921426
Add to the man page a more complete description of what exactly the command expects on input and will return on output based on what is currently supported.
Perhaps missing findPoolSources implementations are backends for sheepdog and rbd. Also missing any backend is zfs.
Signed-off-by: John Ferlan <jferlan@redhat.com> --- tools/virsh.pod | 45 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 39 insertions(+), 6 deletions(-)
diff --git a/tools/virsh.pod b/tools/virsh.pod index 343f26f..915fab0 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -2940,16 +2940,49 @@ pools are similar to the ones used for domains.
=item B<find-storage-pool-sources> I<type> [I<srcSpec>]
-Returns XML describing all storage pools of a given I<type> that could -be found. If I<srcSpec> is provided, it is a file that contains XML -to further restrict the query for pools. +Returns XML describing all possible available storage pool sources that +could be used to create or define a storage pool of a given I<type>. If +I<srcSpec> is provided, it is a file that contains XML to further restrict +the query for pools. + +Not all storage pools support discovery in this manner. Furthermore, for +those that do support discovery, only specific XML elements are required +in order to return valid data, while other elements and even attributes +of some elements are ignored since they are not necessary to find the pool +based on the search criteria. The following lists the supported I<type> +options and the expected minimal XML elements used to perform the search. + +For a "netfs" or "gluster" pool, the minimal expected XML required is the +<host> element with a "name" attribute describing the IP address or hostname +to be used to find the pool. The "port" attribute will be ignored as will +any other provided XML elements in I<srcSpec>. + +For a "logical" pool, the contents of the I<srcSpec> file are ignored, +although if provided the file must at least exist. + +For an "iscsi" pool, the minimal expect XML required is the <host> element +with a "name" attribute describing the IP address or hostname to be used to +find the pool (the iSCSI server address). Optionally, the "port" attribute +may be provided, although it will default to 3260. Optionally, an <initiator> +XML element with a "name" attribute may be provided to further restrict the +iSCSI target search to a specific initiator for multi-iqn iSCSI storage pools.
=item B<find-storage-pool-sources-as> I<type> [I<host>] [I<port>] [I<initiator>]
-Returns XML describing all storage pools of a given I<type> that could -be found. If I<host>, I<port>, or I<initiator> are provided, they control -where the query is performed. +Rather than providing I<srcSpec> XML file for B<find-storage-pool-sources> +use this command option in order to have virsh generate the query XML file +using the optional arguments. The command will return the same output +XML as B<find-storage-pool-sources>. + +Use I<host> to describe a specific host to use for networked storage, such +as netfs, gluster, and iscsi I<type> pools. + +Use I<port> to further restrict which networked port to utilize for the +connection if required by the specific storage backend, such as iscsi. +
This sounds like iscsi requires @port, although it may just be my imperfect English skill ;)
+Use I<initiator> to further restrict the iscsi I<type> pool searches to +specific target initiators.
ACK to the meaning, and I leave it to you whether you want another ACK for grammar (although it seems perfect from my POV).
=item B<pool-autostart> I<pool-or-uuid> [I<--disable>]
-- 2.1.0
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On 03/02/2015 09:52 AM, Martin Kletzander wrote:
On Thu, Feb 26, 2015 at 04:43:54PM -0500, John Ferlan wrote:
https://bugzilla.redhat.com/show_bug.cgi?id=921426
Add to the man page a more complete description of what exactly the command expects on input and will return on output based on what is currently supported.
Perhaps missing findPoolSources implementations are backends for sheepdog and rbd. Also missing any backend is zfs.
Signed-off-by: John Ferlan <jferlan@redhat.com> --- tools/virsh.pod | 45 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 39 insertions(+), 6 deletions(-)
diff --git a/tools/virsh.pod b/tools/virsh.pod index 343f26f..915fab0 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -2940,16 +2940,49 @@ pools are similar to the ones used for domains.
=item B<find-storage-pool-sources> I<type> [I<srcSpec>]
-Returns XML describing all storage pools of a given I<type> that could -be found. If I<srcSpec> is provided, it is a file that contains XML -to further restrict the query for pools. +Returns XML describing all possible available storage pool sources that +could be used to create or define a storage pool of a given I<type>. If +I<srcSpec> is provided, it is a file that contains XML to further restrict +the query for pools. + +Not all storage pools support discovery in this manner. Furthermore, for +those that do support discovery, only specific XML elements are required +in order to return valid data, while other elements and even attributes +of some elements are ignored since they are not necessary to find the pool +based on the search criteria. The following lists the supported I<type> +options and the expected minimal XML elements used to perform the search. + +For a "netfs" or "gluster" pool, the minimal expected XML required is the +<host> element with a "name" attribute describing the IP address or hostname +to be used to find the pool. The "port" attribute will be ignored as will +any other provided XML elements in I<srcSpec>. + +For a "logical" pool, the contents of the I<srcSpec> file are ignored, +although if provided the file must at least exist. + +For an "iscsi" pool, the minimal expect XML required is the <host> element +with a "name" attribute describing the IP address or hostname to be used to +find the pool (the iSCSI server address). Optionally, the "port" attribute +may be provided, although it will default to 3260. Optionally, an <initiator> +XML element with a "name" attribute may be provided to further restrict the +iSCSI target search to a specific initiator for multi-iqn iSCSI storage pools.
=item B<find-storage-pool-sources-as> I<type> [I<host>] [I<port>] [I<initiator>]
-Returns XML describing all storage pools of a given I<type> that could -be found. If I<host>, I<port>, or I<initiator> are provided, they control -where the query is performed. +Rather than providing I<srcSpec> XML file for B<find-storage-pool-sources> +use this command option in order to have virsh generate the query XML file +using the optional arguments. The command will return the same output +XML as B<find-storage-pool-sources>. + +Use I<host> to describe a specific host to use for networked storage, such +as netfs, gluster, and iscsi I<type> pools. + +Use I<port> to further restrict which networked port to utilize for the +connection if required by the specific storage backend, such as iscsi. +
This sounds like iscsi requires @port, although it may just be my imperfect English skill ;)
It's meant to point out that "for now" the only protocol that cares about the port is the iSCSI backend. It's not required to have the port since the default of 3260 is "assumed" by much of the code. But if provided as say 3261 which is an alternate port some servers use, then it would be found...
+Use I<initiator> to further restrict the iscsi I<type> pool searches to +specific target initiators.
I'm somewhat surprised that this one didn't cause an extra question or two as multi initiators isn't something documented. Think I tried once, but gave up trying to explain it so I could understand it! John
ACK to the meaning, and I leave it to you whether you want another ACK for grammar (although it seems perfect from my POV).
=item B<pool-autostart> I<pool-or-uuid> [I<--disable>]
-- 2.1.0
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
participants (2)
-
John Ferlan -
Martin Kletzander