Bug 609044 - virsh help pool-define-as information not inconsistency
virsh help pool-define-as information not inconsistency
Status: CLOSED CURRENTRELEASE
Product: Red Hat Enterprise Linux 6
Classification: Red Hat
Component: libvirt (Show other bugs)
6.0
All Linux
low Severity low
: rc
: 6.0
Assigned To: Eric Blake
Virtualization Bugs
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2010-06-29 05:43 EDT by LiZhang Li
Modified: 2010-11-11 09:50 EST (History)
7 users (show)

See Also:
Fixed In Version: libvirt-0_8_1-12_el6
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2010-11-11 09:50:09 EST
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description LiZhang Li 2010-06-29 05:43:26 EDT
Description of problem:
#virsh help pool-define-as
NAME
    pool-define-as - define a pool from a set of args

  SYNOPSIS
    pool-define-as <name> [--print-xml] <type> [<source-host>] [<source-path>] [<source-dev>] [<source-name>] [<target>]

  DESCRIPTION
    Define a pool.

  OPTIONS
    <name>           name of the pool
    --print-xml      print XML document, but don't define/create
    <type>           type of the pool
    <source-host>    source-host for underlying storage
    <source-path>    source path for underlying storage
    <source-dev>     source device for underlying storage
    <source-name>    source name for underlying storage
    <target>         target for underlying storage


not easy way to finger out how to construct the optional parameters. pool-create-as is the same. Should look like [--target <target>].


vol-create-as is good.
# virsh help vol-create-as
  NAME
    vol-create-as - create a volume from a set of args

  SYNOPSIS
    vol-create-as <pool> <name> <capacity> [--allocation <string>] [--format <string>]

  DESCRIPTION
    Create a vol.

  OPTIONS
    <pool>           pool name
    <name>           name of the volume
    <capacity>       size of the vol with optional k,M,G,T suffix
    --allocation <string>  initial allocation size with optional k,M,G,T suffix
    --format <string>  file format type raw,bochs,qcow,qcow2,vmdk


Version-Release number of selected component (if applicable):
libvirt-client-0.8.1-10.el6

How reproducible:
100%

Steps to Reproduce:
1. virsh help pool-define-as
2. virsh help pool-create-as
3.
Comment 2 RHEL Product and Program Management 2010-06-29 06:03:22 EDT
This request was evaluated by Red Hat Product Management for inclusion in a Red
Hat Enterprise Linux major release.  Product Management has requested further
review of this request by Red Hat Engineering, for potential inclusion in a Red
Hat Enterprise Linux Major release.  This request is not yet committed for
inclusion.
Comment 3 Eric Blake 2010-06-29 14:09:21 EDT
I'm not sure this is a bug.  The two commands currently have different syntax, where pool-define-as is positionally dependent (if there is one string, you specified <source-host>; if there are 2 strings, you specified <source-host> and <source-path>, etc), where vol-create-as is position independent (either option can be specified without the other, so the leading option string is mandatory).

For example,

$ virsh -c test:///default pool-define-as sample --print-xml dir localhost
<pool type='dir'>
  <name>sample</name>
  <source>
    <host name='localhost'/>
  </source>
</pool>

$ virsh -c test:///default pool-define-as sample --print-xml dir localhost /opt
<pool type='dir'>
  <name>sample</name>
  <source>
    <host name='localhost'/>
    <dir path='/opt'/>
  </source>
</pool>

compared to vol-create-as, where the '--format' is required:

$ virsh -c test:///default vol-create-as default-pool sample 1k raw
error: unexpected data 'raw'
$ virsh -c test:///default vol-create-as default-pool sample 1k --format raw
Vol sample created


Then, since it is possible to have XML that describes the target but not the source...
$ virsh -c test:///default pool-dumpxml default-pool
<pool type='dir'>
  <name>default-pool</name>
  <uuid>3302c3eb-a532-81f5-4957-11de4ffffecc</uuid>
  <capacity>107374182400</capacity>
  <allocation>0</allocation>
  <available>107374182400</available>
  <source>
  </source>
  <target>
    <path>/default-pool</path>
    <permissions>
      <mode>0700</mode>
      <owner>-1</owner>
      <group>-1</group>
    </permissions>
  </target>
</pool>


...virsh implemented the shortcut that any option that does not call out a leading --option designator may nevertheless provide one:


$ virsh -c test:///default pool-define-as sample --print-xml dir --target target
<pool type='dir'>
  <name>sample</name>
  <target>
    <path>target</path>
  </target>
</pool>

So with pool-define-as, you can provide <target> by two methods:
pool-define-as $name $type $host $path $dev $name $target
pool-define-as $name $type --target $target

But with vol-create-as, you only have one option for specifying <format>:
vol-create-as $pool $name $capacity --format $format

The two semantics are intentional, and consistently documented (in the code, it is the difference between VSH_OT_DATA and VSH_OT_STRING).  The only question now is whether there's anything we can do visually to make VSH_OT_DATA more obvious that the leading --target is available for use.

Maybe:
    [--target] <target>  target for underlying storage

would make this better?
Comment 6 Dave Allan 2010-06-29 22:12:13 EDT
libvirt-0_8_1-12_el6 has been built in RHEL-6-candidate with the fix.

Dave
Comment 7 dyuan 2010-07-01 04:13:01 EDT
Verified PASSED with libvirt-0.8.1-13.el6.
Comment 8 dyuan 2010-07-01 04:13:15 EDT
Verified PASSED with libvirt-0.8.1-13.el6.
Comment 9 Nan Zhang 2010-09-09 07:07:16 EDT
Verified with libvirt-0.8.1-27.el6.x86_64 & qemu-kvm-0.12.1.2-2.113.el6.x86_64.
Comment 10 releng-rhel@redhat.com 2010-11-11 09:50:09 EST
Red Hat Enterprise Linux 6.0 is now available and should resolve
the problem described in this bug report. This report is therefore being closed
with a resolution of CURRENTRELEASE. You may reopen this bug report if the
solution does not work for you.

Note You need to log in before you can comment on or make changes to this bug.