qm-shutdown

Shutdown a virtual machine

$ qm [[shu|shutdown]] [VM_ID]

$ qm [[shu|shutdown]] --timeout [10] [VM_ID]

$ qm [[shu|shutdown]] --keepActive [true] [VM_ID]

$ qm [[shu|shutdown]] --skiplock [true] [VM_ID]

$ qm [[shu|shutdown]] --forceStop [true] [VM_ID]

qm shutdown <vmid> [--timeout <integer>] [--keep-active <boolean>]

<vmid>
    The unique numeric ID of the virtual machine or container to be shut down. This is a mandatory argument.

--timeout <integer>
    Specifies the maximum time in seconds to wait for the guest operating system to perform its graceful shutdown. If the guest does not shut down within this period, a forceful stop will be executed. The default value is typically 60 or 120 seconds, depending on the Proxmox VE version.

--keep-active <boolean>
    When set to 1 or true, this option prevents the VM/CT from being forcibly stopped even if the ACPI shutdown fails or times out. The guest will remain active, which can be useful for debugging unresponsive systems without immediately killing them. Defaults to 0 or false.

qm-shutdown is a crucial command within the Proxmox Virtual Environment (PVE) for managing virtual machines (VMs) and containers (CTs).
Its primary function is to initiate a controlled and graceful shutdown process for a running guest operating system. Unlike a forceful stop, qm-shutdown first attempts to send an ACPI (Advanced Configuration and Power Interface) shutdown signal to the guest.
This allows the guest OS to perform its standard shutdown routines, such as flushing disk caches, closing applications, and safely unmounting filesystems, thereby minimizing the risk of data corruption.
If the guest does not respond to the ACPI signal or fails to shut down within a specified timeout period, qm-shutdown will then proceed to forcibly stop the VM/CT.
This command is highly recommended over immediate forceful stops (like qm stop) for maintaining the integrity and consistency of data within your virtualized environments.

The effectiveness of qm-shutdown relies on the guest operating system's ability to respond to ACPI signals. If the guest OS is frozen, lacks ACPI support, or if the QEMU Guest Agent is not properly installed and running (especially important for Windows VMs), the graceful shutdown may fail, leading to a timeout and subsequent forceful termination.
It is not an instantaneous kill command; it involves a waiting period.

It's crucial to understand the distinction between qm-shutdown and qm stop. qm-shutdown prioritizes data integrity by giving the guest OS time to clean up. qm stop, in contrast, immediately kills the VM/CT process, which can lead to data corruption or loss if the guest OS was writing data or had open files. Always prefer qm-shutdown unless an immediate, ungraceful halt is absolutely necessary.

For optimal performance and reliable graceful shutdowns, especially with Windows guests, it is highly recommended to install and run the QEMU Guest Agent within the virtual machine. The guest agent facilitates communication between the Proxmox host and the guest OS, enabling features like proper ACPI shutdown handling, accurate IP address reporting, and file system freezing for backups.

qm-shutdown has been an integral part of Proxmox VE since its early versions, evolving alongside the platform to offer robust VM and container lifecycle management. Its design reflects a balance between system stability and data integrity, with options like --timeout and --keep-active being introduced to provide more granular control over the shutdown process.

qm(1), qm start(1), qm stop(1), qm reset(1), qm status(1), pct(1)