How to use the command 'qm shutdown' (with examples)

The qm shutdown command is an essential utility for administrators managing virtual machines (VMs) utilizing QEMU/KVM through the Proxmox Virtual Environment. This command allows you to safely shut down virtual machines, ensuring that any ongoing processes are properly terminated and that the systems are taken offline gracefully. It’s a part of the qm command set, which is extensively documented in the Proxmox official documentation. By leveraging this command with various options, administrators can customize how and when the virtual machines are shut down, providing flexibility and control over system resources.

Use case 1: Shutdown a virtual machine

Code:

qm shutdown VM_ID

Motivation:
In routine maintenance or resource optimization, an administrator may need to shut down a VM without performing a forceful or abrupt action. This command is beneficial when the VM is running unnecessary processes consuming resources or when preparing for an upgrade or patch application. The straightforward qm shutdown ensures that the machine halts operations properly.

Explanation:

• qm: The main Proxmox utility responsible for managing virtual machines.
• shutdown: Instructs the utility to initiate a shutdown process for the specified VM.
• VM_ID: Represents the unique identifier assigned to a virtual machine during its creation. This placeholder should be replaced with the actual ID of the VM you intend to shut down.

Example output:

Trying to gracefully shutdown VM 100 ...

Use case 2: Shutdown a virtual machine after wait for at most 10 seconds

Code:

qm shutdown --timeout 10 VM_ID

Motivation:
There could be instances where a VM needs to be shutdown quickly within a specific timeframe—perhaps due to performance issues or to deploy an urgent security patch. The --timeout option allows for a controlled timeframe to wait for processes to terminate before forcing a shutdown.

Explanation:

• --timeout 10: Sets a maximum wait time (in seconds) for the VM to gracefully shut down. If the VM has not shut down within this window, it will proceed with a forceful shutdown.
• VM_ID: As previously mentioned, it indicates the target virtual machine to be shut down.

Example output:

Trying to gracefully shutdown VM 101 with a timeout of 10 seconds...

Use case 3: Shutdown a virtual machine and do not deactivate storage volumes

Code:

qm shutdown --keepActive true VM_ID

Motivation:
There are scenarios where the storage volumes of a virtual machine need to remain active, such as when conducting maintenance on compute resources while ensuring that storage operations are uninterrupted. By choosing to keepActive storage, administrators can ensure other processes that depend solely on the storage aren’t halted.

Explanation:

• --keepActive true: Indicates that the shutdown process should not deactivate the associated storage volumes, keeping them operational.
• VM_ID: The identifier of the VM on which this specific shutdown operation will be executed.

Example output:

Trying to gracefully shutdown VM 102 while keeping storage volumes active...

Use case 4: Shutdown a virtual machine and skip lock (only root can use this option)

Code:

qm shutdown --skiplock true VM_ID

Motivation:
In specific administrative tasks, a VM might be locked for certain operations, preventing alterations or shutdowns. When an immediate shutdown is required, and there’s assurance that skipping the lock will not cause problems, this option can be utilized—granted that the operation is executed with root privileges.

Explanation:

• --skiplock true: Overrides any existing locks on the VM, permitting a shutdown operation. Given the sensitive nature of this operation, only users with root permissions can execute this safely.
• VM_ID: The VM that needs to be unlocked and shut down.

Example output:

Lock on VM 103 is bypassed; attempting graceful shutdown...

Use case 5: Stop and shutdown a virtual machine

Code:

qm shutdown --forceStop true VM_ID

Motivation:
In critical situations where a VM is unresponsive or consuming excessive system resources abruptly hindering other operations, the --forceStop option acts as an immediate control mechanism. It ceases all VM processes decisively, ensuring swift resource release.

Explanation:

• --forceStop true: This argument ensures a forceful stop of the VM irrespective of its operational state, thereby executing a shutdown.
• VM_ID: Again, represents the unique ID of the VM subject to immediate shutdown.

Example output:

Failed to gracefully shutdown VM 104, forcing stop...

Conclusion:

The qm shutdown command offers various options tailored for different scenarios one might face when managing virtual machines in the Proxmox Virtual Environment. From the basic need of shutting down a single VM to more complex operations involving storage considerations and locked states, this command provides a comprehensive approach to VM management. Understanding these options allows system administrators to perform shutdowns safely and efficiently, ensuring minimal impact on operational workflows.