Red Hat Bugzilla – Bug 769506
Need to improve virsh domxml-*-native command docs
Last modified: 2012-11-20 08:45:03 EST
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:
In POST: commit fbdfda14a1128b114dbdb608b60d6caf24c2489a Author: Alex Jia <ajia@redhat.com> 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@redhat.com>
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.
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.
*** Bug 782935 has been marked as a duplicate of this bug. ***
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?
(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.
(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
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