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

[Fabian Grünbichler]

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"?)

Also, I'd change "send an ACPI event for the guest OS" to "send an ACPI
event to the guest OS".