Bug 514532 - virsh man page is inaccurate
Summary: virsh man page is inaccurate
Keywords:
Status: CLOSED ERRATA
Alias: None
Product: Red Hat Enterprise Linux 5
Classification: Red Hat
Component: libvirt
Version: 5.4
Hardware: All
OS: Linux
low
low
Target Milestone: rc
: ---
Assignee: Daniel Veillard
QA Contact: Virtualization Bugs
URL:
Whiteboard:
Depends On:
Blocks: 529380
TreeView+ depends on / blocked
 
Reported: 2009-07-29 14:53 UTC by Lon Hohberger
Modified: 2010-03-30 08:11 UTC (History)
5 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
: 529380 (view as bug list)
Environment:
Last Closed: 2010-03-30 08:11:22 UTC
Target Upstream Version:
Embargoed:


Attachments (Terms of Use)
patch frixing the man page source and result (1.96 KB, patch)
2009-11-18 13:33 UTC, Daniel Veillard
no flags Details | Diff


Links
System ID Private Priority Status Summary Last Updated
Red Hat Product Errata RHBA-2010:0205 0 normal SHIPPED_LIVE libvirt bug fix and enhancement update 2010-03-29 12:27:37 UTC

Description Lon Hohberger 2009-07-29 14:53:39 UTC
Description of problem:

Quote (virsh man page) ---
 Most virsh commands act asynchronously, so just because the virsh pro-
 gram returned, doesn’t mean the action is complete.  This is important,
 as many operations on domains, like create and shutdown, can take con-
 siderable time (30 seconds or more) to bring the machine into a fully
 compliant state.  If you want to know when one of these actions has
 finished you must poll through virsh list periodically.
---

The virsh man page describes 'most operations' as being 'asynchronous', which is not the case.  The virsh commands are tied in to the libvirt APIs which are synchronous.  It looks like the paragraph in question was lifted directly from the 'xm' man page without being updated:


Quote (xm man page) ---
 Most xm commands act asynchronously, so just because the xm command
 returned, doesn’t mean the action is complete.  This is important, as
 many operations on domains, like create and shutdown, can take consid-
 erable time (30 seconds or more) to bring the machine into a fully com-
 pliant state.  If you want to know when one of these actions has fin-
 ished you must poll through xm list periodically.
---


In practice, the implementation of shell scripts using
'virsh', following the man page as it is documented must
do:

   virsh [command]
   if [ $? -eq 0 ]; then
     # per virsh man page...
     # operation was started, now poll to see
     # if it completed
     # if a timeout occurs, give up.
     while ...; do
       ...
       if [ $complete ]; then
         return 0
       fi
     done
   fi
   return 1




Expected results:

It would be nice to either:
(a) remove the above paragraph from the virsh man page, or
(b) explicitly define which virsh commands, if any, are
    actually asynchronous

It is my understanding based on talks with libvirt developers that none of the commands are asynchronous today and that the paragraph is simply wrong.

Either way, clarifying the man page will allow administrators and developers who write scripts around 'virsh' have a reasonable expectation about whether the return code reflects the completion of the operation.  For example:

   virsh [command]
   return $?

Comment 1 Lon Hohberger 2009-07-29 14:55:10 UTC
libvirt-0.6.3-14.el5

Comment 2 Daniel Veillard 2009-11-18 13:33:34 UTC
Created attachment 370080 [details]
patch frixing the man page source and result

State that most operations are synchronous except create and shutdown of domains.

I guess that should be good enough

Comment 3 Daniel Veillard 2009-11-18 13:34:32 UTC
https://www.redhat.com/archives/libvir-list/2009-November/msg00626.html

patch posted upstream as this still applied :-\

Daniel

Comment 4 Daniel Veillard 2009-11-25 16:09:34 UTC
libvirt-0.6.3-22.el5 has been built in dist-5E-qu-candidate with
the fixes,

Daniel

Comment 6 Gunannan Ren 2009-12-28 08:08:35 UTC
The bus has been fixed in libvirt-0.6.3-22.el5

Comment 11 errata-xmlrpc 2010-03-30 08:11:22 UTC
An advisory has been issued which should help the problem
described in this bug report. This report is therefore being
closed with a resolution of ERRATA. For more information
on therefore solution and/or where to find the updated files,
please follow the link below. You may reopen this bug report
if the solution does not work for you.

http://rhn.redhat.com/errata/RHBA-2010-0205.html


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