[pve-devel] [PATCH qemu-server] Document shutdown behaviour when qemu-guest-agent is running

[Fabian Grünbichler]

On Mon, Oct 17, 2016 at 11:38:15AM +0200, Emmanuel Kasper wrote:
> On 10/17/2016 11:05 AM, Fabian Grünbichler wrote:
> > On Mon, Oct 17, 2016 at 10:52:26AM +0200, Emmanuel Kasper wrote:
> >> ---
> >>  PVE/API2/Qemu.pm | 6 ++++--
> >>  1 file changed, 4 insertions(+), 2 deletions(-)
> >>
> >> diff --git a/PVE/API2/Qemu.pm b/PVE/API2/Qemu.pm
> >> index ad7a0c0..f64a77c 100644
> >> --- a/PVE/API2/Qemu.pm
> >> +++ b/PVE/API2/Qemu.pm
> >> @@ -1858,8 +1858,10 @@ __PACKAGE__->register_method({
> >>      method => 'POST',
> >>      protected => 1,
> >>      proxyto => 'node',
> >> -    description => "Shutdown virtual machine. This is similar to pressing the power button on a physical machine." .
> >> -	"This will send an ACPI event for the guest OS, which should then proceed to a clean shutdown.",
> >> +    description => "Shutdown virtual machine. The default behaviour is to send an ACPI event for the guest OS, similar " .
> >> +    "to pressing the power button on a physical machine. The guest OS should then proceed to a clean shutdown. " .
> >> +    "If the Qemu GuestAgent is configured and running in the VM, the shutdown will be initiated by the guest OS himself, " .
> >> +    "calling the OS ExWindowsEx() function on Windows guests, or the 'shutdown -P' command on posix guests.",
> >>      permissions => {
> >>  	check => ['perm', '/vms/{vmid}', [ 'VM.PowerMgmt' ]],
> >>      },
> > 
> > I'd keep it shorter and OS agnostic:
> > "If the Qemu GuestAgent is configured and running in the VM, the regular shutdown mechanism of the guest OS itself is used instead." (or "is triggered"?)
> 
> I found writing "the regular shutdown mechanism of the guest OS itself
> is used instead." not specific enough.
> 
> One could say shutting down via ACPI is also using the regular shutdown
> mechanism of the OS, or am I missing something ?

yes/no/depends ;) it just triggers a (emulated) hardware event, which
can be handled by the OS in various ways. usually it should cause the OS
to do a regular shutdown, but it could also be ignored, or do whatever
else the OS was configured/written to do.

> 
> What about:
> 
> Shutdown virtual machine. The default behaviour is to send an ACPI event
> to the guest OS, similar " .
>     "to pressing the power button on a physical machine. The guest OS
> should then proceed to a clean shutdown. " .
>     "If the Qemu Guest Agent is configured and running in the VM, the
> shutdown will be initiated by the guest OS himself, " .
>     "similar to entering a 'shutdown' command inside the VM.

sounds good (with s/himself/itself/)