qm-guest-exec

Execute a specific command via a guest agent

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

$ qm [[g|guest]] exec [vm_id] [argument1 argument2 ...] --synchronous 0

$ qm [[g|guest]] exec [vm_id] [argument1 argument2...] --timeout [10]

$ qm [[g|guest]] exec [vm_id] [argument1 argument2 ...] --pass-stdin 1

qm guest exec <vmid> --command <string> [--args <array>] [--input <string>] [--timeout <integer>] [--verbose <boolean>]

vmid
    The unique ID of the virtual machine where the command will be executed.

--command
    The full path to the command or executable to run inside the guest, e.g., /usr/bin/ls.

--args
    A list of arguments to pass to the specified command. Each argument should be provided as a separate item, e.g., '--args', '/tmp', '-l'.

--input
    Base64 encoded data that will be piped to the standard input (stdin) of the executed command.

--timeout
    Sets a timeout (in seconds) for the command execution. If the command does not complete within this period, it will be terminated. The default is 60 seconds.

--verbose
    If set to true, the command's standard output (stdout) and standard error (stderr) will be included in the qm-guest-exec's output on the host. By default, only the exit status is returned.

qm-guest-exec is a powerful command-line utility provided by Proxmox VE that allows the execution of arbitrary commands directly inside a running virtual machine's guest operating system from the Proxmox host. It leverages the QEMU Guest Agent (qemu-guest-agent) service, which must be installed and active within the guest VM. This command is invaluable for automation, scripting routine maintenance tasks, or retrieving information without needing network access or SSH credentials to the guest. It streamlines VM management by providing a direct communication channel, enabling administrators to manage guest OS functionalities, install software, or check system status remotely and efficiently.

• QEMU Guest Agent Requirement: The qemu-guest-agent package must be installed and actively running within the target guest VM. Without it, qm-guest-exec cannot communicate with the guest.


• Guest Status: The virtual machine must be powered on and running for the command to execute successfully.


• Permissions: Commands executed via qm-guest-exec typically run with elevated privileges (e.g., as root on Linux or SYSTEM on Windows) within the guest OS, depending on the guest agent's configuration. Exercise caution when executing commands.


• Output Handling: By default, qm-guest-exec only returns the command's exit status. To see the standard output and standard error, the --verbose true option must be used.


• Timeout Behavior: Commands exceeding the specified or default timeout will be terminated. Ensure the timeout is sufficient for long-running tasks.

The qm-guest-exec command returns the exit status of the command executed within the guest. A status of 0 generally indicates success, while a non-zero value indicates an error.

When using the --input option, the data must be supplied in Base64 encoded format. For example, to pass 'Hello, World!' to a command, you would first encode it: echo "Hello, World!" | base64, then use the resulting Base64 string with --input.

To check the uptime of a VM with ID 101:
qm guest exec 101 --command /usr/bin/uptime --verbose true

To create a file named /tmp/testfile.txt with content 'This is content' in VM 102:
qm guest exec 102 --command /usr/bin/tee --args /tmp/testfile.txt --input $(echo 'This is content' | base64) --verbose true

The capability to interact directly with guest operating systems via the QEMU Guest Agent has been a significant enhancement in virtualization platforms like Proxmox VE. While the QEMU Guest Agent itself has evolved over time, qm-guest-exec and similar functionalities were integrated into Proxmox VE to provide a robust, out-of-band management channel. This feature aims to improve automation, simplify guest maintenance, and enhance the overall manageability of virtualized environments without relying on traditional network-based access methods like SSH or WinRM, thereby increasing security and efficiency.

qm(1), pvesh(1), qemu-guest-agent