qm-agent

View documentation for the original command

$ tldr qm guest cmd

qm agent <vmid> <command> [options]

<vmid>
    The numeric ID of the virtual machine to interact with.

<command>
    The specific guest agent command to execute. This can be one of many operations supported by the QEMU Guest Agent. Common commands include ping, network-get-interfaces, get-fsinfo, fstrim, fsfreeze-freeze, fsfreeze-thaw, exec, and set-password.

ping
    Checks connectivity to the QEMU Guest Agent within the VM. Useful for verifying the agent's status.

network-get-interfaces
    Retrieves detailed information about the network interfaces configured within the guest OS, including IP addresses.

get-fsinfo
    Obtains information about the filesystems mounted inside the guest VM.

fstrim
    Sends an fstrim command to the guest, useful for SSDs and thin-provisioned storage to reclaim unused blocks.

fsfreeze-freeze
    Freezes the filesystems inside the guest, preparing them for a consistent snapshot. This is crucial for application-consistent backups.

fsfreeze-thaw
    Thaws previously frozen filesystems inside the guest, resuming normal I/O operations.

exec --command <cmd> [--input <data>] [--timeout <sec>]
    Executes a specified command within the guest OS. Output, error streams, and exit codes can be retrieved. Requires careful use due to security implications.

set-password --user <username> --password <pass>
    Changes the password for a specified user account within the guest OS. Highly useful for password management and automation.

The qm-agent command, part of the Proxmox VE command-line interface, facilitates communication between the Proxmox host and the QEMU Guest Agent daemon running inside a virtual machine. This powerful tool allows administrators to perform various operations within the guest OS without direct network access or SSH, provided the QEMU Guest Agent is installed and actively running within the VM. It is essential for advanced VM management, enabling features such as querying guest IP addresses, gracefully freezing/thawing filesystems for consistent backups, executing commands inside the guest, and managing user passwords. Its capabilities significantly enhance automation and reliability for virtualized environments, especially in scenarios requiring precise interaction with the guest's internal state.

For qm-agent commands to function, the QEMU Guest Agent must be installed and running inside the virtual machine, and the 'Qemu Agent' option must be enabled in the VM's configuration on the Proxmox host. Without the agent, host-guest communication via this command is not possible. Not all guest OSes fully support all agent commands, and some commands (like exec) require appropriate permissions and security considerations within the guest.

To enable qm-agent functionality, install the QEMU Guest Agent inside your VM:

For Debian/Ubuntu/Proxmox LXC: sudo apt update && sudo apt install qemu-guest-agent
For RHEL/CentOS/Fedora: sudo dnf install qemu-guest-agent or sudo yum install qemu-guest-agent
For Windows: Download the MSI installer from the virtio-win ISO (typically mounted as a CD-ROM in Windows VMs) and run qemu-ga-x86_64.msi. Ensure the service starts automatically.

After installing the agent in the guest, ensure it's enabled in the VM's Proxmox configuration. This can be done via the web UI (VM -> Options -> Qemu Agent) or via CLI:
qm set <vmid> --agent 1
A reboot of the VM is often recommended after these changes for the agent to fully initialize and communicate with the host.

The QEMU Guest Agent and its integration via tools like qm-agent are integral parts of the Proxmox Virtual Environment's evolution. As Proxmox VE grew in features and stability, the need for robust host-guest communication became paramount for advanced functionalities like live migration, consistent backups, and enhanced monitoring. The qm-agent utility emerged as a CLI-driven method to leverage these capabilities, continuously refined with new agent features and improved reliability across various guest operating systems.

qm(1), qemu-ga(8), vzdump(1)