+++ This bug was initially created as a clone of Bug #514532 +++ 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 $? --- Additional comment from lhh on 2009-07-29 10:55:10 EDT --- libvirt-0.6.3-14.el5 --------------------------------------------------------------------------- The same problem exists in the "xm" man page (where this text was lifted from). The xm migrate, xm save, xm restore commands (at least) are synchronous, and possibly some others. We should explicitly say which ones are synchronous and which ones aren't.
Created attachment 418980 [details] Patch to fix the man page paragraph about asynchronous operations This is patch to fix the man page paragraph about the asynchronous operations of the commands which is not true. Many commands in xm acts synchronously with some exceptions, like create, shutdown, mem-set and vcpu-set commands. Michal
QA verify this bug on xen-3.0.3-115.el5: # man xm Got the following Notes: NOTES All xm operations rely upon the Xen control daemon, aka xend. For any xm commands to run xend must also be running. For this reason you should start xend as a service when your system first boots using xen. Most xm commands require root privileges to run due to the communications channels used to talk to the hypervisor. Running as non root will return an error. Most xm commands act synchronously, except maybe create, shutdown, mem-set and vcpu-set. The fact that the xm command returned doesn’t neces- sarily mean that the action is complete and you must poll through xm list periodically to detect that the operation completed. So change this bug to VERIFIED.
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-2011-0031.html