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

[Emmanuel Kasper]

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 ?

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.