The agent works over its own channel — a virtual virtio-serial port — not over the network. So it takes two
parts: the port on the Proxmox side (the VM option) and the service on the guest side (the package).
What the agent gives you:
| Without the agent | With the agent |
|---|---|
shutdown is an ACPI button; a guest without acpid or with a hung process doesn’t hear it |
shutdown is a command to the agent, like poweroff from inside |
| the backup captures the disk mid-write, as in a sudden power loss | the file system is frozen for the snapshot: fs-freeze, snapshot, fs-thaw |
| the VM’s address isn’t shown in the UI | the VM’s Summary shows its addresses; qm guest cmd 101 network-get-interfaces |
| a command in the guest — over SSH only | qm guest exec 101 -- systemctl status nginx from the host |
How to turn it on
In the guest (Ubuntu and Debian):
sudo apt install -y qemu-guest-agent
sudo systemctl start qemu-guest-agent
On the VM — Options › QEMU Guest Agent › Use QEMU Guest Agent, or:
qm set 101 --agent enabled=1
If the option was enabled on a running VM, the channel appears only after its process restarts: qm reboot 101
or power off and on from Proxmox — a reboot from inside the guest won’t do. In the cloud-init template the agent
and the option are on from the start, once for all clones (VM template with cloud-init).
On Windows the agent comes from the VirtIO driver disk (virtio-win.iso): the qemu-ga-x86_64.msi installer in
the guest-agent directory, along with the VirtIO drivers.
If it doesn’t work
qm shutdown 101 fails: QEMU guest agent is not running
- Cause
- The agent option is on for the VM, but the agent isn’t installed or running in the guest. Proxmox shuts down through the agent and waits for an answer.
- Fix
- Install and start the agent in the guest. If the VM has to be off right now, shut it down from inside,
sudo poweroffover SSH, orqm stop 101if nothing is writing in the guest.
The backup log says: skipping guest-agent 'fs-freeze', agent configured but not running?
- Cause
- The agent option is on, but the agent in the guest doesn’t answer: the backup runs without a freeze, and a database inside may be caught mid-write.
- Fix
systemctl status qemu-guest-agentin the guest; after installing the package on an older guest, restart the VM from Proxmox so the agent channel appears.
How to check
qm guest cmd 101 ping # empty output and exit code 0
qm guest cmd 101 get-osinfo # name and version of the guest OS
qm guest cmd 101 fsfreeze-status # thawed — the file system isn't frozen
The VM’s next backup log shows issuing guest-agent 'fs-freeze' command followed by fs-thaw
(Backups in Proxmox).