The QEMU guest agent in depth · Proxmox VE

The QEMU guest agent is a small daemon inside the guest that listens on a virtual serial channel and answers requests from the hypervisor. It is the only supported way for Proxmox VE to know anything about what is happening inside a virtual machine, and it converts several operations from “hope” to “know”.

It is also the feature most commonly half-configured. Enabling it on the VM and installing it in the guest are two independent acts, and a cluster where one has been done without the other looks correct from the interface while being wrong everywhere it matters.

What the agent enables

Capability	Without the agent	With the agent
Backup consistency	Crash consistent	Filesystem consistent, via `fsfreeze-freeze` and `fsfreeze-thaw`
Shutdown	ACPI power button, and hope the guest is listening	A real shutdown request to the guest OS
IP address in the interface	Read from the VM configuration only	Actual addresses as configured inside the guest
Guest OS and hostname	Not available	Reported by the guest
Trim after a disk move	Freed blocks stay allocated on thin storage	`fstrim` can be issued automatically
Running a command in a guest	Not possible	`qm guest exec`

The first row is the one that carries the most consequence, and it is covered in xiii-pbs-backup-modes. The rest are conveniences that become important at scale: an estate where the interface shows real guest IP addresses is one where you can find a machine from a network alert in ten seconds.

The four sub-options

agent: [enabled=]<1|0> [,freeze-fs=<1|0>]
       [,fstrim_cloned_disks=<1|0>] [,type=<virtio|isa>]

Sub-option	Default	What it does
`enabled`	`0`	Whether PVE talks to the agent at all
`freeze-fs`	`1`	Whether the filesystems are frozen for a backup
`fstrim_cloned_disks`	`0`	Whether `fstrim` runs after moving a disk or migrating the VM
`type`	`virtio`	The channel transport. `virtio` for everything modern; `isa` exists for guests that cannot do virtio

The two defaults worth changing deliberately

freeze-fs defaults to on, which is correct — so check it is still on. It gets turned off by people troubleshooting a guest whose application does not tolerate a freeze, and then never turned back on. A VM with agent: enabled=1,freeze-fs=0 gives you every convenience of the agent and none of the backup consistency, and nothing in the backup report says so.

fstrim_cloned_disks defaults to off, and on thin storage you usually want it on. Moving a disk between storages, or migrating a VM with local disks, copies allocated blocks — including blocks the guest freed long ago. Without a trim afterwards, the destination is fatter than the source, permanently, until something else triggers a trim. On LVM-thin or a thin-provisioned SAN that is capacity you paid for and cannot see.

Configuration changethe settings, stated explicitly— Writing all four out means the next person sees a decision instead of a default. The channel device appears at the next cold start, not at a reboot.

set -euo pipefail
VMID=118

qm set "$VMID" --agent enabled=1,freeze-fs=1,fstrim_cloned_disks=1,type=virtio

# The virtio-serial channel is added to the machine definition, so the guest
# only sees it after the QEMU process is replaced.
qm shutdown "$VMID" --timeout 300
qm start "$VMID"

Installing it in the guest

Configuration changeguest-side installation— Run inside the guest, not on the host. The service must be enabled as well as installed - a stopped service is the commonest half-configuration.

set -euo pipefail

# Debian and Ubuntu
apt update && apt install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent

# RHEL, Rocky, Alma
# dnf install -y qemu-guest-agent && systemctl enable --now qemu-guest-agent

# Verify from inside the guest that the channel device exists at all. If this
# path is missing, the VM was never cold started after enabling the agent.
ls -l /dev/virtio-ports/org.qemu.guest_agent.0

systemctl is-active qemu-guest-agent

On Windows the agent comes from the VirtIO driver ISO and installs as a service. It is a separate component from the VirtIO storage and network drivers, and installing the drivers does not install the agent — which is why a Windows guest can have perfect VirtIO performance and no agent at all.

Talking to the agent

qm guest cmd sends a single guest-agent command; qm guest exec runs a program inside the guest.

Read-only / Safethe liveness check— An empty JSON object is success. An error here means the agent is not answering, whatever the VM configuration claims.

# qm guest cmd 118 ping

{}

Illustrative output

Read-only / Safethe read-only agent commands worth knowing— All of these inspect the guest and change nothing. They are the fastest way to answer questions about a guest you do not have a shell on.

set -euo pipefail
VMID=118

qm guest cmd "$VMID" ping                     # is it answering at all
qm guest cmd "$VMID" get-osinfo               # distribution, version, kernel
qm guest cmd "$VMID" get-host-name            # hostname as the guest knows it
qm guest cmd "$VMID" get-fsinfo               # mounted filesystems and usage
qm guest cmd "$VMID" network-get-interfaces   # real addresses, per interface
qm guest cmd "$VMID" get-time                 # clock, for drift investigations
qm guest cmd "$VMID" fsfreeze-status          # thawed, or stuck frozen

Service impact possiblerunning a command inside the guest— Executes as root inside the guest. This is a real administrative action taken without SSH and without an audit trail inside the guest.

set -euo pipefail
VMID=118

# Synchronous by default: PVE waits for the command and prints its output.
qm guest exec "$VMID" -- /bin/df -h /var

# Give a slow command more room than the default timeout allows.
qm guest exec "$VMID" --timeout 60 -- /usr/bin/systemctl is-active nginx

# Fire and forget, then collect the result by PID with qm guest exec-status.
qm guest exec "$VMID" --synchronous 0 -- /usr/sbin/logrotate -f /etc/logrotate.conf

qm guest exec is root inside the guest, from the host, with no guest-side authentication

This is a genuine privilege boundary and it is easy to forget it exists.

Anyone who can run qm on a PVE node — which includes anyone with the VM.Monitor privilege on that guest, and certainly anyone with root on the node — can execute arbitrary commands as root inside every guest that has the agent enabled. There is no password, no SSH key, no sudo rule and no guest-side log of who did it.

That is not a defect: the hypervisor already has complete control of the guest’s memory and disks, so the agent adds convenience rather than capability. But it changes two things you should be explicit about:

A VM is not a security boundary against its own hypervisor. If a guest belongs to a different trust domain from the host — a customer workload, a DMZ appliance, a compliance-scoped system — that has to be reflected in who gets PVE permissions, not in guest hardening.
Guest-side audit is incomplete by construction. If somebody needs to be able to prove what was run on a machine, qm guest exec is a gap in that proof, and the compensating control is on the PVE side: restrict VM.Monitor, and rely on the PVE task log, which does record it.

Diagnosing an agent that is not answering

This is the practical core of the lesson, because “agent configured but not answering” is a silent state that survives for months.

Read-only / Safethe diagnostic ladder, host side first— Read-only throughout. Each rung rules out one cause, in order of how cheap it is to check.

set -euo pipefail
VMID=118

# 1. Is the agent enabled in the configuration at all?
qm config "$VMID" | grep -E '^agent:' || echo 'agent not configured'

# 2. Does the running QEMU process actually have the channel? If the agent was
#    enabled without a cold start, the configuration says yes and the machine
#    says no.
qm showcmd "$VMID" | tr ' ' '\n' | grep -A1 'org.qemu.guest_agent' || \
echo 'no guest agent channel in the running machine: cold start needed'

# 3. Does it answer?
qm guest cmd "$VMID" ping && echo 'agent OK'

# 4. Is it wedged in a freeze? A guest whose filesystems are frozen will
#    appear hung and will not answer most commands.
qm guest cmd "$VMID" fsfreeze-status

Symptom	Cause	Fix
`agent` absent from `qm config`	Never enabled	`qm set --agent enabled=1`, then cold start
`agent` present, no channel in `qm showcmd`	Enabled but never cold started	`qm shutdown` then `qm start`. A reboot is not enough
Channel present, `ping` fails	Package missing or service stopped in the guest	Install and `systemctl enable --now qemu-guest-agent`
`ping` fails, guest appears hung, disks idle	Filesystems left frozen by an interrupted backup	`qm guest cmd VMID fsfreeze-thaw`
Works, then stops after a guest upgrade	Service masked or package removed by the upgrade	Re-enable; add it to the guest configuration baseline

A guest stuck frozen looks exactly like a guest that has crashed

fsfreeze-freeze suspends all filesystem activity in the guest. If a backup is interrupted between the freeze and the thaw — a cancelled task, a killed process, a network partition to the backup target at the wrong moment — the guest can be left frozen.

From the outside this is indistinguishable from a hang: the VM is running, the console does not respond, disk I/O is zero, and CPU is idle. The reflex is to reset the VM, which throws away whatever was in flight.

The correct first move costs one command:

qm guest cmd 118 fsfreeze-status
qm guest cmd 118 fsfreeze-thaw

If the status says frozen, thawing it usually returns the guest to normal service with nothing lost. Put this in the “VM is hung” runbook above the reset step, because the ordering is the whole value.

Why the channel needs a cold start, and what qm showcmd proves

The agent talks over a virtio-serial device. That device is part of the machine definition — the argument list QEMU is launched with — and QEMU builds its device tree once, at process start.

So qm set --agent enabled=1 writes a line into /etc/pve/qemu-server/<vmid>.conf and changes nothing about the machine that is currently running. A reboot issued inside the guest restarts the operating system within the same QEMU process, so the device is still absent. Only replacing the process — qm shutdown then qm start, a migration, or a host reboot — rebuilds the device tree with the channel in it.

qm showcmd is the tool that settles the argument, because it prints the command line PVE would use to start the VM, showing the actual device list rather than the configuration file’s intent. When someone insists the agent is enabled and it is not answering, comparing qm config against qm showcmd is the thirty-second way to find out which of the two is lying.

The same reasoning applies to every device-shaped change: adding a serial port, changing the machine version, adding virtio-fs. Configuration is not state, and the gap between them is always closed by a cold start.

What happens if the agent is enabled on the VM but never installed in the guest?

Everything appears configured and four things quietly break.

Backups become crash consistent without saying so. Covered in xiii-pbs-backup-modes; it is the most consequential item and the least visible.

Shutdown becomes unreliable. PVE prefers the agent for guest shutdown. With the agent enabled but absent, shutdown requests can hang until the timeout expires, and an operator watching a shutdown sit at “in progress” for 180 seconds usually reaches for qm stop — which is a hard power cut.

Migration and maintenance get slower. Node evacuation shuts guests down or migrates them, and a fleet where every shutdown waits out a timeout turns a ten-minute maintenance window into an hour.

The interface reports stale information. IP addresses shown in the guest summary come from the agent. Without it you get nothing, and the estate loses the ability to answer “which VM is 192.0.2.47?” quickly.

The fix is a fleet sweep rather than vigilance, because this state is created by cloning a template that lacked the package, and it therefore arrives in batches. Build the agent into the template, and run the check from xiii-pbs-backup-modes weekly so a batch of forty new clones cannot sit half-configured for a quarter.

What the agent enables

The four sub-options

Installing it in the guest

Talking to the agent

Diagnosing an agent that is not answering

Knowledge check