qm-guest-cmd

Execute a specific QEMU Guest Agent command

$ qm guest cmd [virtual_machine_id] [fsfreeze-freeze|fsfreeze-status|fsfreeze-thaw|fstrim|get-fsinfo|...]

qm guest cmd

    Required.
The virtual machine ID of the guest you want to execute the command on.


    Required.
The command string to execute within the guest OS. This string is passed directly to the guest agent.

--timeout
    Optional.
Specify the timeout in seconds. The default timeout is set in guest agent configuration.

--verbose
    Optional.
Verbose output.

The `qm-guest-cmd` command provides a way to execute commands directly within a QEMU guest operating system from the host. This is achieved by using the QEMU Guest Agent (qemu-ga), which needs to be running inside the guest. The command securely transmits the command string to the guest, executes it, and returns the output (stdout and stderr) along with the return code. This allows for automated configuration, monitoring, and management tasks to be performed on the guest OS without requiring direct SSH access or other network connections. It's particularly useful in virtualized environments where remote access might be restricted or unavailable. Authentication and authorization are managed by the QEMU Guest Agent within the guest system. The usefulness of this command depends on the functionality and security policy enforced by the guest agent, so the security depends on the proper hardening of it. The command can be used to create scripts to automatize tasks with Proxmox environment.

Requires the QEMU Guest Agent to be installed and running inside the guest operating system. Security depends heavily on the security policy configured in the guest agent. If the guest agent is compromised, this command could be exploited. The user running the command on the host machine must have sufficient permissions to execute commands on the specified VM. The command runs inside the guest as the user configured inside the guest agent configuration. Ensure proper escaping of special characters in the command string.

If the command fails, ensure that the QEMU Guest Agent is running inside the guest. Check the guest agent logs for any errors. Verify that the `` is correct and that the user running the command on the host has appropriate permissions. Network access is needed only in the VM. Host network is not needed, as the communication happens with a virtio serial interface

The `qm-guest-cmd` command was introduced as part of the Proxmox Virtual Environment (PVE) to provide a standardized way to interact with QEMU guests. Its development was driven by the need to automate guest configuration and management tasks. Early versions may have had limited functionality or security features, which have been improved over time through updates to both the command and the QEMU Guest Agent. Today, it's an integral part of the PVE ecosystem for performing operations inside VMs without requiring a traditional network connection from the host.

qm(1), qemu-ga(8)