How to use the command 'qm guest cmd' (with examples)

The qm guest cmd is a versatile command-line tool used in the Proxmox Virtual Environment to execute specific QEMU Guest Agent commands directly on virtual machines (VMs). This tool is crucial for managing VM features like filesystem freezing, trimming, and more. It acts as a bridge for sending commands from the host to the guest OS through the QEMU Guest Agent, enabling various low-level operations inside the VM.

Use case 1: Executing a filesystem freeze on a virtual machine

Code:

qm guest cmd 102 fsfreeze-freeze

Motivation:
Executing a filesystem freeze on a virtual machine is vital for creating consistent backups without the risk of data corruption. When you freeze the filesystem, the disk writes are momentarily halted, ensuring that the snapshotting process does not capture data in an inconsistent state. This is particularly critical for databases or applications that perform frequent writes, where any discrepancies could lead to significant data issues.

Explanation:

• qm guest cmd: This is the base command used to interact with the QEMU Guest Agent.
• 102: This is the ID of the virtual machine on which the command is being executed. Each virtual machine has a unique identifier.
• fsfreeze-freeze: This command requests the guest to freeze its filesystems, pausing any write operations.

Example output:
If the command succeeds, there usually isn’t any output, but in verbose mode, you might see:

{
  "return": {}
}

Use case 2: Checking the freeze status of a virtual machine filesystem

Code:

qm guest cmd 102 fsfreeze-status

Motivation:
Knowing the current freeze status of a filesystem is essential, especially if you are managing multiple VMs and need to verify whether a filesystem is still frozen from previous operations. This check helps in ensuring that no disruptions occur in service availability due to a forgotten freeze state, thereby maintaining operational integrity.

Explanation:

• qm guest cmd: Again, this is the base command to issue QEMU Guest Agent tasks.
• 102: This represents the virtual machine ID that is being queried.
• fsfreeze-status: This command checks and returns the current freeze state of the guest’s filesystems.

Example output:
The expected output, indicating the status, could be:

{
  "return": "thawed"
}

Use case 3: Thawing a previously frozen filesystem

Code:

qm guest cmd 102 fsfreeze-thaw

Motivation:
Thawing a frozen filesystem is crucial to resume normal write operations after ensuring that a backup or snapshot operation has been completed accurately. Without thawing, the applications and services within the VM can become unresponsive, potentially leading to downtime. Thus, timely thawing is necessary to revert the system to operational mode.

Explanation:

• qm guest cmd: Base command for executing guest agent operations.
• 102: The specific ID of the target virtual machine.
• fsfreeze-thaw: This command resumes normal write operations on the guest’s filesystems by unfreezing it.

Example output:
You might see output like:

{
  "return": {}
}

Use case 4: Performing a filesystem trim on a virtual machine

Code:

qm guest cmd 102 fstrim

Motivation:
Running a filesystem trim within a VM is beneficial for reclaiming unused space on thin-provisioned storage deployments, thereby optimizing storage utilization and performance. This action aids in maintaining efficiency by notifying the storage which blocks can be reused, leading to better overall storage health and potentially reduced costs.

Explanation:

• qm guest cmd: This executes a command within the guest OS using the QEMU Guest Agent.
• 102: This identifies the specific virtual machine on which to perform the operation.
• fstrim: This command advises the guest OS to perform a trimming operation on the file system, optimizing storage use.

Example output:
An example JSON output might appear as:

{
  "return": {}
}

Use case 5: Retrieving detailed filesystem information

Code:

qm guest cmd 102 get-fsinfo

Motivation:
Fetching detailed information about the filesystems within a VM is critical for monitoring system health and understanding storage allocation. IT administrators use this data to make informed decisions about capacity planning, maintenance, and performance optimization, ensuring that the VM environments run effectively.

Explanation:

• qm guest cmd: Initiates the guest agent command for filesystem operations.
• 102: Specifies the ID of the VM to extract filesystem data from.
• get-fsinfo: This command retrieves comprehensive filesystem data from the guest OS, including details like mount points, device information, and usage statistics.

Example output:
A typical output might include various fields detailing the filesystems:

{
  "return": [
    {
      "name": "/dev/sda1",
      "mountpoint": "/",
      "type": "ext4",
      "used-bytes": 5000000000,
      "total-bytes": 10000000000
    },
    ...
  ]
}

Conclusion:

The qm guest cmd command line tool is an indispensable utility for efficiently managing and interacting with virtual machines in the Proxmox Virtual Environment. By executing commands directly through the QEMU Guest Agent, users can effectively manage filesystem operations and retrieve vital VM information, all of which are crucial for maintaining a healthy and efficient virtualized infrastructure.