[libvirt] [PATCH] virsh: add aliases 'boot', 'stop', and 'restart'

[Eric Blake]

On 11/06/2012 02:01 AM, Peter Krempa wrote:
>>>   =item B<reboot> I<domain> [I<--mode acpi|agent>]
>>> +=item B<restart> I<domain> [I<--mode acpi|agent>]
>>>
>>>   Reboot a domain.  This acts just as if the domain had the B<reboot>
>>>   command run from the console.  The command returns as soon as it has
>> Now it would be a good time to correct the documentation. In reality the
>> restart/reboot is a combination of stop/shutdown followed by an in-place
>> reset of the domain (at least for QEMU/KVM). Which can behave the same
>> as a reboot but doesn't have to. This is one area of confusion for users
>> I have observed. Restart seems to raise a lower expectation level ;-).
>> For that reason I would also vote to exchange the order of appearance
>> (restart first).
> 
> I agree on this point.

I'm not going to switch the order of the synopsis (the older command
should be listed first, since that is the more portable version if you
are coding for older virsh); but I do agree that the help text needs
improvement (it is NOT the same as 'reboot' from within the guest).
This is what I squashed in before pushing:

diff --git i/tools/virsh.pod w/tools/virsh.pod
index 7a3835b..7a46ffd 100644
--- i/tools/virsh.pod
+++ w/tools/virsh.pod
@@ -1126,10 +1126,12 @@ If I<--current> is specified, affect the current
guest state.
 =item B<reboot> I<domain> [I<--mode acpi|agent>]
 =item B<restart> I<domain> [I<--mode acpi|agent>]

-Reboot a domain.  This acts just as if the domain had the B<reboot>
-command run from the console.  The command returns as soon as it has
-executed the reboot action, which may be significantly before the
-domain actually reboots.
+Restart a domain.  Depending on the hypervisor, this may request a
+shutdown followed by a fresh boot, rather than triggering a software
+reboot.  The command returns as soon as it has requested the reboot
+action, and depending on the guest, there may be a significant delay
+before the domain actually reboots, or the request might even be
+ignored.

 The exact behavior of a domain when it reboots is set by the
 I<on_reboot> parameter in the domain's XML definition.


-- 
Eric Blake   eblake at redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 617 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20121106/60d698ef/attachment-0001.sig>