Bug 769506

Summary:	Need to improve virsh domxml-*-native command docs
Product:	Red Hat Enterprise Linux 6	Reporter:	Alex Jia <ajia>
Component:	libvirt	Assignee:	Alex Jia <ajia>
Status:	CLOSED ERRATA	QA Contact:	Virtualization Bugs <virt-bugs>
Severity:	medium	Docs Contact:
Priority:	medium
Version:	6.3	CC:	acathrow, byount, dallan, dyuan, eblake, mzhan, rwu, tzheng, veillard, yupzhang
Target Milestone:	rc
Target Release:	---
Hardware:	x86_64
OS:	Linux
Whiteboard:
Fixed In Version:	libvirt-0.9.9-1.el6	Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:
Clones:	783001 783240 (view as bug list)		Environment:
Last Closed:	2012-06-20 06:39:44 UTC	Type:	---
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:
Bug Depends On:
Bug Blocks:	783001, 783240, 818039, 852442, 869585, 878463

Description Alex Jia 2011-12-21 05:19:09 UTC

Description of problem:
As usual, users are very confused for what's the 'format' argument for 'domxml-from-native' and 'domxml-to-native' commands, then they often try some obvious values of 'xen' or 'xm' for a xen domain, 'qemu' for a qemu domain, however, they don't work. 

Because libvirt defines some internal 'format' value, but virsh help or virsh man page doesn't tell users these, so we need to improve virsh document, this bug is used for tracing the issue.

Version-Release number of selected component (if applicable):
# rpm -q libvirt-client
libvirt-client-0.9.8-1.el6.x86_64

How reproducible:
always

Steps to Reproduce:
1. virsh help virsh domxml-[from|to]-native
2. man virsh and see 'domxml-from-native' and 'domxml-to-native' section
3.
  
Actual results:
Users can't understand what's the 'format' argument.

Expected results:
Tell users value of 'format' for different hypervisor.


Additional info:

Comment 1 Alex Jia 2011-12-21 05:20:07 UTC

In POST:

commit fbdfda14a1128b114dbdb608b60d6caf24c2489a
Author: Alex Jia <ajia>
Date:   Tue Dec 20 18:59:01 2011 +0800

    docs: improve virsh domxml-*-native command docs
    
    * tools/virsh.pod: improve virsh man page for domxml-from-native and
    domxml-to-native commands.
    
    Signed-off-by: Alex Jia <ajia>

Comment 2 Eric Blake 2011-12-21 13:27:44 UTC

Also suggested on the mailing list:
https://www.redhat.com/archives/libvir-list/2011-December/msg00899.html

Someday, I'd like an API that allows introspection; something like:

int virConnectDomainXMLNativeFormats(virConnectPtr conn, char **names,
int *nnames, unsigned int flags)

where nnames of 0 queries the number of formats, and otherwise tells the
size of *names on input and tells how many entries in *names were
allocated on output.

Comment 4 tingting zheng 2012-01-10 03:20:39 UTC

Verified the bug with：
libvirt-0.9.9-1.el6.x86_64
libvirt-client-0.9.9-1.el6.x86_64

# man virsh
       domxml-from-native format config
           Convert the file config in the native guest configuration
           format named by format to a domain XML format. For QEMU/KVM
           hypervisor, the format argument must be qemu-argv. For Xen
           hypervisor, the format argument may be xen-xm or xen-sxpr.

       domxml-to-native format xml
           Convert the file xml in domain XML format to the native
           guest configuration format named by format. For QEMU/KVM
           hypervisor, the format argument must be qemu-argv. For Xen
           hypervisor, the format argument may be xen-xm or xen-sxpr.

Comment 5 Eric Blake 2012-01-18 21:48:04 UTC

*** Bug 782935 has been marked as a duplicate of this bug. ***

Comment 6 Eric Blake 2012-01-18 21:50:37 UTC

An additional upstream patch idea was proposed for further improving things:

https://www.redhat.com/archives/libvir-list/2012-January/msg00604.html

This would add the 'virsh domxml-formats' command to list the formats supported by each hypervisor.  The v1 proposal added a new API, but comments on that thread suggested that using hypervisor capability xml would be sufficient instead, and I am still working on a v2 proposal.  Should we reopen this bug to include those improvements?

Comment 8 Dave Allan 2012-01-19 02:42:25 UTC

(In reply to comment #6)
> An additional upstream patch idea was proposed for further improving things:
> 
> https://www.redhat.com/archives/libvir-list/2012-January/msg00604.html
> 
> This would add the 'virsh domxml-formats' command to list the formats supported
> by each hypervisor.  The v1 proposal added a new API, but comments on that
> thread suggested that using hypervisor capability xml would be sufficient
> instead, and I am still working on a v2 proposal.  Should we reopen this bug to
> include those improvements?

No, open a separate BZ.

Comment 10 Eric Blake 2012-01-19 18:19:40 UTC

(In reply to comment #8)
> > instead, and I am still working on a v2 proposal.  Should we reopen this bug to
> > include those improvements?
> 
> No, open a separate BZ.

Done: bug 783240

Comment 12 errata-xmlrpc 2012-06-20 06:39:44 UTC

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

http://rhn.redhat.com/errata/RHSA-2012-0748.html