qm-guest

Print the status of a specific PID

$ qm [[g|guest]] [[exec-s|exec-status]] [vm_id] [pid]

$ qm [[g|guest]] [[p|passwd]] [vm_id] [username]

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

$ qm [[g|guest]] exec [vm_id] [command] [argument1 argument2 ...]

qm guest <vmid> <command> [<args>...]

<vmid>
    The unique ID (e.g., 100, 101) of the virtual machine to interact with.

ping
    Checks if the QEMU Guest Agent is running and responsive inside the VM.

info
    Retrieves general information about the QEMU Guest Agent and its capabilities.

ip-addresses
    Lists the IP addresses configured on the guest OS, including IPv4 and IPv6.

network-get-interfaces
    Provides detailed information about all network interfaces found in the guest, including MAC addresses, IP addresses, and status.

exec <command> [<args>...]
    Executes an arbitrary command inside the guest VM. The command's output (stdout/stderr) and exit code are returned. Requires the command to be available in the guest's PATH or provided with a full path.

fsfreeze-freeze
    Requests the guest agent to freeze the guest's filesystems. This is crucial for creating consistent backups (snapshots) of the VM.

fsfreeze-thaw
    Requests the guest agent to thaw previously frozen filesystems, resuming normal I/O operations.

set-user-password <username> <password>
    Sets or changes the password for a specified user account within the guest OS. This command should be used with caution.

shutdown
    Requests a graceful shutdown of the guest operating system. The VM will power off after the OS shuts down.

reboot
    Requests a graceful reboot of the guest operating system.

file-read <path>
    Reads the content of a specified file from the guest filesystem and returns it. Path must be absolute.

file-write <path> <content>
    Writes the provided content to a specified file on the guest filesystem. Path must be absolute.

get-fsinfo
    Retrieves information about the filesystems mounted within the guest, including mount points and total/used space.

get-osinfo
    Retrieves general operating system information from the guest, such as OS name, version, and architecture.

The term 'qm-guest' refers to the set of functionalities within Proxmox VE for interacting with the QEMU Guest Agent (qemu-ga) running inside a virtual machine.

While 'qm-guest' is not a standalone command, its capabilities are primarily accessed via the qm guest sub-command of the main qm (Proxmox Virtual Machine) utility. This interface allows administrators to perform various operations on the guest OS without direct network access, such as retrieving network configurations, querying OS information, executing commands, or managing filesystem freezes for backups. It is an essential tool for advanced VM management, automation, and backup consistency within a Proxmox environment, requiring qemu-ga to be installed and running in the guest.

Prerequisites: The QEMU Guest Agent (qemu-ga) must be installed and running inside the guest VM. Additionally, the 'QEMU Guest Agent' device must be enabled in the VM's hardware settings within Proxmox VE.

Security: The exec and set-user-password commands grant significant control over the guest OS and should be used responsibly. Ensure that access to the Proxmox host and qm guest command is restricted.

Compatibility: Filesystem freezing (fsfreeze-freeze/thaw) relies on guest OS support and typically works with common Linux filesystems (e.g., ext4, XFS) and Windows NTFS. Not all guest commands are supported on every operating system or qemu-ga version.

For Linux guests, install the qemu-guest-agent package using your distribution's package manager (e.g., apt install qemu-guest-agent on Debian/Ubuntu, yum install qemu-guest-agent on RHEL/CentOS). For Windows guests, the agent can be installed via the VirtIO drivers ISO. After installation, ensure the service is running.

In Proxmox VE, ensure the 'QEMU Guest Agent' device is added to the VM's hardware configuration (VM Options -> QEMU Guest Agent -> Check 'Enabled').

• Automated IP Address Retrieval: Easily get a VM's IP without logging in.
• Consistent Backups: Use fsfreeze-freeze/thaw with vzdump to ensure data integrity during backups.
• Guest OS Management: Gracefully shut down or reboot VMs, or execute maintenance scripts remotely.
• Automation: Script various guest operations for deployment or monitoring purposes.

The QEMU Guest Agent (qemu-ga) was developed to improve interaction between the QEMU hypervisor and the guest operating system, bridging the gap for tasks like graceful shutdowns, network information retrieval, and filesystem freezing. Proxmox VE integrated this functionality deeply into its qm command-line utility, providing the qm guest sub-command suite. This integration evolved over Proxmox versions, adding more specific guest agent commands to enhance management capabilities and automation, especially for consistent backups.

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