qm-monitor

Enter the QEMU Monitor interface of a specific virtual machine

$ qm [[mo|monitor]] [vm_id]

qm monitor vmid [OPTIONS]

vmid
    Required. The unique numeric identifier (e.g., 100, 101) of the virtual machine whose QEMU monitor console you wish to access.

--path path
    Optional. Specifies an alternative Unix socket path for the QEMU monitor. This is rarely used in standard Proxmox setups as the path is automatically derived from the VMID.

--pretty
    Optional. When interacting with the QEMU Machine Protocol (QMP), this option formats the JSON output for improved readability, making it easier to parse.

--raw
    Optional. Prevents any pretty-printing of output, showing the raw QEMU monitor or QMP output directly. This is particularly useful for scripting purposes or when piping output to other tools.

-h, --help
    Optional. Displays a concise help message for the qm monitor subcommand, outlining its syntax and available options.

The qm monitor command (part of the Proxmox VE qm utility) provides direct access to the QEMU monitor console of a running virtual machine. This powerful tool allows administrators to execute low-level QEMU commands, offering granular control and detailed insight into the VM's internal state. It's invaluable for advanced diagnostics, debugging, and performing specific operations not typically exposed through the higher-level Proxmox management interface. Users can inspect device status, manage virtual hardware, pause or resume the VM, and even send ACPI signals directly to the guest operating system. Understanding QEMU monitor commands is crucial for effective use.

Connecting to the QEMU monitor requires the VM to be running. Direct interaction with the QEMU monitor involves low-level commands that, if misused, can potentially corrupt the VM state or cause unexpected behavior. It is essential to have a solid understanding of QEMU monitor commands before using this utility for critical operations. This command bypasses higher-level Proxmox safeguards, so exercise caution.

Once connected via qm monitor, you will be presented with a QEMU monitor prompt (e.g., (qemu)). You can then type various QEMU monitor commands (Human Monitor Protocol - HMP). Common commands include:
info status (VM power state)
info block (disk images)
info network (network devices)
stop (pause VM)
cont (resume VM)
system_powerdown (graceful shutdown)
quit (exit monitor, but VM keeps running)

For programmatic interaction, you can also issue QEMU Machine Protocol (QMP) commands, which communicate using JSON. These are typically prefixed with {'execute': ...}.

qm monitor is frequently used for:
Troubleshooting guest OS boot issues or unresponsive VMs.
Inspecting virtual hardware configuration details.
Injecting commands or events that are not available through standard qm commands.
Debugging device passthrough configurations.
Performing live migrations or complex storage operations at a low level.

The qm monitor command is an integral part of the Proxmox Virtual Environment (PVE) management suite, which began its development around 2007. As a core component for advanced VM administration and debugging, it was integrated early into the qm utility to provide administrators with direct, low-level access to the underlying QEMU processes, leveraging QEMU's built-in monitor capabilities for diagnostics and control.

qm(1), qemu-system-x86_64(1), pve-qemu-kvm(1)