Re: [PATCH pve-docs v2 2/8] qm: add reboot behavior information

[David Riley <d.riley@proxmox.com>]

nit: The original text is very thorough, but it might be a bit dense for a
quick lookup. I've drafted a slightly more concise version below that
focuses directly on the operational impact (like pending configs and
hookscripts) to make it easier for admins to scan.

[[qm_reboot_behavior]]
Reboot Behavior
~~~~~~~~~~~~~~

By default, when a guest operating system reboots, a "warm" reset in
place is performed. This is fast, but it means the QEMU process never
actually stops. As a result, pending configuration changes and
`pve-qemu-kvm` updates are not applied during a normal guest reboot.

The `reboot` option allows you to change this behavior using two
properties:

`powercycle` (default: `0`)::
When enabled, an in-guest reboot triggers a full stop and start of the
virtual machine. This automatically applies pending configuration
changes (including machine version updates), runs `post-stop` and
`pre-start` hookscripts, and picks up newly installed `pve-qemu-kvm`
versions, all without requiring a manual shutdown from the host.
(Ignored if `enabled` is `0`).

`enabled` (default: `1`)::
Whether the VM is allowed to reboot at all. If set to `0`, any reboot
requested by the guest or the `qm reboot` command will instead shut
the VM down completely.

Note: Explicit resets via `qm reset` or the web interface will still
restart the VM, and HA-managed VMs will still be revived by the
xref:chapter_ha_manager[HA stack].

----
# qm set <vmid> --reboot 1,powercycle=1
----

On 10/22/26 2:51 PM, Jakob Klocker wrote:
> Add information about the newly created `Reboot behavior` option in PVE.
>
> Signed-off-by: Jakob Klocker<j.klocker@proxmox.com>
> ---
>   qm.adoc | 40 ++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 40 insertions(+)
>
> diff --git a/qm.adoc b/qm.adoc
> index 18a4fbe..04193e8 100644
> --- a/qm.adoc
> +++ b/qm.adoc
> @@ -1558,6 +1558,46 @@ cluster-wide.
>   If you require a delay between the host boot and the booting of the first VM,
>   see the section on xref:first_guest_boot_delay[Proxmox VE Node Management].
>   
> +[[qm_reboot_behavior]]
> +Reboot Behavior
> +~~~~~~~~~~~~~~~
> +
> +When a guest reboots itself from inside the operating system, {pve} does not
> +need to restart the virtual machine to service the request. By default the
> +machine is reset in place: the QEMU process keeps running and only the guest
> +operating system boots again.
> +
> +This is fast and transparent to the guest, but it means the VM keeps running
> +with everything it was started with - its configuration, its machine version
> +and the host resources assigned to it. Configuration changes that are marked as
> +*pending* in the *Options* and hardware panels therefore stay pending, and a
> +newer `pve-qemu-kvm` package installed in the meantime is not picked up. A
> +reboot triggered through the web interface, `qm` or the API is not affected by
> +this, as it always stops and starts the virtual machine, unless rebooting is
> +disabled entirely.
> +
> +The `reboot` option has two properties:
> +
> +`enabled` (default: `1`)::
> +Whether the virtual machine may reboot at all. If disabled, a reboot requested
> +from inside the guest or through `qm reboot` or the API shuts the VM down
> +instead, and it stays off. The exception is an explicit reset (`qm reset`, the
> +API or the web interface), which still restarts the VM. Note that guests managed
> +by the xref:chapter_ha_manager[HA stack] with the requested state `started` are
> +started again by the HA manager.
> +
> +`powercycle` (default: `0`)::
> +Stop and start the virtual machine on a reset instead of resetting it in place.
> +A reset is what a reboot from inside the guest looks like to QEMU, and it is
> +also what `qm reset` and the corresponding API call and web interface action
> +trigger. Because this is a full start, pending configuration changes take
> +effect and the VM is launched with the currently installed QEMU version, and
> +the `post-stop` and `pre-start` hookscript phases run again. This property is
> +ignored when `enabled` is `0`.
> +
> +----
> +# qm set <vmid> --reboot 1,powercycle=1
> +----
>   
>   [[qm_qemu_agent]]
>   QEMU Guest Agent