qm-guest-exec-status

Print the status of a specific PID

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

qm-guest-exec-status <vmid> <cmdid>

vmid
    The unique identifier (ID) of the virtual machine on which the command was executed.

cmdid
    The unique ID returned by the qm-guest-exec command when the task was initially submitted to the guest agent.

This command retrieves the status of a previously executed command within a QEMU/KVM guest virtual machine, managed by the qemu-guest-agent. It's typically used in conjunction with qm-guest-exec (or similar commands) which submits the command to the guest.

The guest agent executes the command and reports its status back to the host. qm-guest-exec-status allows the host to query if the command succeeded, failed, or is still running, and often provides the command's standard output and error streams, as well as its exit code. This is crucial for automation and orchestrating operations within virtual machines from the hypervisor host. It significantly aids in validating the success or failure of tasks like software installations, configuration changes, or script executions initiated from the host side.

Requires the qemu-guest-agent to be installed, running, and enabled within the guest VM.
Network or communication issues between the host and guest agent can lead to timeouts or failed status retrieval.
The cmdid is a transient identifier, valid only for the specific command execution it represents.

The command typically returns a JSON object containing details about the executed command, including its status (e.g., 'running', 'succeeded', 'failed'), the exit-code, and captured stdout and stderr streams if available.

This command is an integral part of the Proxmox VE virtualization management suite, which builds upon QEMU/KVM technologies.

Its development is closely tied to the evolution of the QEMU Guest Agent functionality, which introduced a robust channel for host-guest communication. Proxmox VE leverages these capabilities to offer advanced VM management features, including the ability to execute commands remotely and query their status. This command, along with qm-guest-exec, enables powerful automation and orchestration workflows for virtual machines managed by Proxmox VE.

qm-guest-exec(1), qemu-ga(8), qm(1)