[libvirt] [PATCH 2/2] virsh.pod: Update find-storage-pool-sources[-as] man page

John Ferlan jferlan at redhat.com
Tue Mar 3 04:08:08 UTC 2015



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 at 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 at redhat.com
>> https://www.redhat.com/mailman/listinfo/libvir-list




More information about the libvir-list mailing list