RHEL Engineering is moving the tracking of its product development work on RHEL 6 through RHEL 9 to Red Hat Jira (issues.redhat.com). If you're a Red Hat customer, please continue to file support cases via the Red Hat customer portal. If you're not, please head to the "RHEL project" in Red Hat Jira and file new tickets here. Individual Bugzilla bugs in the statuses "NEW", "ASSIGNED", and "POST" are being migrated throughout September 2023. Bugs of Red Hat partners with an assigned Engineering Partner Manager (EPM) are migrated in late September as per pre-agreed dates. Bugs against components "kernel", "kernel-rt", and "kpatch" are only migrated if still in "NEW" or "ASSIGNED". If you cannot log in to RH Jira, please consult article #7032570. That failing, please send an e-mail to the RH Jira admins at rh-issues@redhat.com to troubleshoot your issue as a user management inquiry. The email creates a ServiceNow ticket with Red Hat. Individual Bugzilla bugs that are migrated will be moved to status "CLOSED", resolution "MIGRATED", and set with "MigratedToJIRA" in "Keywords". The link to the successor Jira issue will be found under "Links", have a little "two-footprint" icon next to it, and direct you to the "RHEL project" in Red Hat Jira (issue links are of type "https://issues.redhat.com/browse/RHEL-XXXX", where "X" is a digit). This same link will be available in a blue banner at the top of the page informing you that that bug has been migrated.
Bug 609044 - virsh help pool-define-as information not inconsistency
Summary: virsh help pool-define-as information not inconsistency
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Red Hat Enterprise Linux 6
Classification: Red Hat
Component: libvirt
Version: 6.0
Hardware: All
OS: Linux
low
low
Target Milestone: rc
: 6.0
Assignee: Eric Blake
QA Contact: Virtualization Bugs
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2010-06-29 09:43 UTC by LiZhang Li
Modified: 2010-11-11 14:50 UTC (History)
7 users (show)

Fixed In Version: libvirt-0_8_1-12_el6
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Last Closed: 2010-11-11 14:50:09 UTC
Target Upstream Version:
Embargoed:

Attachments (Terms of Use)

Description LiZhang Li 2010-06-29 09:43:26 UTC 
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 Program Management 2010-06-29 10:03:22 UTC 
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 18:09:21 UTC 
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-30 02:12:13 UTC 
libvirt-0_8_1-12_el6 has been built in RHEL-6-candidate with the fix.

Dave
Comment 7 dyuan 2010-07-01 08:13:01 UTC 
Verified PASSED with libvirt-0.8.1-13.el6.
Comment 8 dyuan 2010-07-01 08:13:15 UTC 
Verified PASSED with libvirt-0.8.1-13.el6.
Comment 9 Nan Zhang 2010-09-09 11:07:16 UTC 
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 14:50:09 UTC 
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.