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|...]

The functionality implied by "qm-guest-cmd" is typically accessed via the `qm guest` subcommands. Here are common usage patterns:

For executing arbitrary shell commands inside the guest:
   qm guest exec <vmid> <command> [ <arg1> ... ] [--timeout <N>] [--input <filename>] [--env <ENVVAR=VALUE>]

For sending specific QEMU Guest Agent API commands:
   qm guest cmd <vmid> <guest-agent-command> [ <arg1> ... ] [--timeout <N>]

Examples of other common guest operations:
   qm guest info <vmid>
   qm guest fsinfo <vmid>
   qm guest ping <vmid>
   qm guest shutdown <vmid> [--force] [--timeout <N>]
   qm guest reboot <vmid> [--timeout <N>]

<vmid>
    The unique ID of the virtual machine on the Proxmox host.

<command>
    The shell command to execute inside the guest (used with `qm guest exec`).

<arg1> ...
    Optional arguments to pass to the shell command or guest agent command.

--timeout <N>
    Maximum time in seconds to wait for the command to complete. Defaults to 10 seconds.

--input <filename>
    Reads standard input for the guest command from the specified file on the host (used with `qm guest exec`).

--env <ENVVAR=VALUE>
    Sets an environment variable for the executed command (used with `qm guest exec`). Can be specified multiple times.

<guest-agent-command>
    A specific command directly supported by the QEMU Guest Agent API (used with `qm guest cmd`). Common examples include: `get-osinfo`, `get-fsinfo`, `get-ip-addresses`, `guest-ping`, `guest-shutdown`, `guest-reboot`.

The `qm-guest-cmd` functionality, primarily accessed through the `qm guest` subcommand in Proxmox Virtual Environment (PVE), enables a Proxmox host to execute commands and retrieve information directly from a running QEMU/KVM virtual machine's guest operating system. This powerful feature relies on the `qemu-guest-agent` package being installed and operational within the guest VM. It establishes a communication channel (typically via virtio-serial) that allows the host to send API calls and receive responses from the agent.

Common uses include: retrieving guest IP addresses (`qm guest info`), querying filesystem information (`qm guest fsinfo`), executing arbitrary shell commands (`qm guest exec`), gracefully shutting down or rebooting the guest (`qm guest shutdown`, `qm guest reboot`), and synchronizing guest filesystem caches (`qm guest sync`). This capability is invaluable for automation, monitoring, and remote administration of guest VMs without needing direct network access or SSH, making it a cornerstone for managing a Proxmox cluster.

The `qemu-guest-agent` package must be installed and running inside the target virtual machine for any `qm guest` commands to function. Without it, commands will fail.
The term "qm-guest-cmd" itself is often a conceptual shorthand for using the `qm guest` subcommands within Proxmox VE, as `qm-guest-cmd` is not a standalone executable or commonly documented command.
Executing commands with `qm guest exec` means they run with root privileges inside the guest by default, which can be a security risk if not used carefully.

The most critical dependency for `qm guest` functionality is the `qemu-guest-agent` software package, which must be installed and actively running within the guest virtual machine. Without it, the host cannot communicate with the guest OS via this mechanism.

- Automated VM Shutdown/Reboot: Gracefully power down or restart VMs from the Proxmox host, ensuring data integrity.
- IP Address Retrieval: Easily get the IP address(es) of a guest without needing to log in to the VM.
- Filesystem Information: Query disk usage, available space, and mounted filesystems within the guest.
- Monitoring and Scripting: Execute custom scripts or commands inside the guest for monitoring, configuration, or data collection purposes from host-side automation.

The QEMU Guest Agent (QGA) was developed as an integral part of the QEMU virtualization project to improve communication and integration between the host and guest operating systems. Proxmox Virtual Environment (PVE) adopted and deeply integrated the QGA functionality, making it a cornerstone for advanced VM management capabilities. Over time, the `qm guest` subcommands evolved to expose a rich set of guest agent features directly through the Proxmox CLI, simplifying operations like graceful shutdowns, IP address retrieval, and command execution, which previously required direct SSH or other network-based access to the guest.

qm(1), qemu-guest-agent(8), virsh(1), ssh(1)