Proxmox QEMU Guest Agent: Fix IP, Backups, Shutdown

If your Proxmox VE 9.2 VM shows no IP address, fails a quiesced backup, or ignores a graceful shutdown, the guest agent is usually the missing link. This checklist walks through the VM option, guest package, service state, and backup command needed to make the QEMU Guest Agent report IPs, freeze filesystems, and shut down cleanly.

Key Takeaways

Enable first: The VM option must be turned on before the host will trust agent data.
Install separately: The guest still needs the QEMU Guest Agent package and a running service.
Verify from the host: A successful agent check is the quickest way to separate guest problems from Proxmox display problems.
Quiesce carefully: Quiesced snapshots improve Linux and Windows backup consistency, but they briefly pause guest I/O.
Test shutdowns: Graceful shutdown depends on the same agent channel, so fixing backups often fixes shutdowns too.

Why the Guest Agent Matters in Proxmox VE 9.2

The QEMU Guest Agent is a small service inside the VM and a control channel on the host. Proxmox uses it for three everyday tasks: IP reporting, quiesced snapshots, and graceful shutdown or reboot. Without it, Proxmox can still run the VM, but many convenience features fall back to less reliable methods.

The host-side option is easy to miss. Enabling it does not install anything inside the guest. It only adds the virtio-serial channel and tells Proxmox to ask the guest for information. That is why a VM can look healthy and still report no IP address.

If you are working through a fresh install, this is the part I would add to the Proxmox VE 9.2 VM checklist before moving a VM to production.

How to Confirm the Agent Is Actually Enabled on the VM

Check the Proxmox VM option

The VM configuration file is the fastest place to check. Replace 100 with your VM ID.

grep -E '^agent:' /etc/pve/qemu-server/100.conf

A working line should look like this:

agent: enabled=1

If nothing is printed, enable it from the host:

qm set 100 --agent enabled=1

After changing this option, stop and start the VM. A soft reboot may not add the virtio-serial channel, and the host will keep failing agent checks until the next cold boot.

Ask the host whether the agent responds

Once the VM is running, ask Proxmox to talk to the guest. These two checks are enough for most cases:

qm agent 100 ping

qm agent 100 info

If the option is disabled, the first check usually fails before the guest is even consulted. If the option is enabled but the guest service is missing, the error points to the agent not running. A third check gives a broader status view:

qm agent 100 get-status

Check the guest service on Linux

On Debian or Ubuntu, install and enable the package:

apt-get update && apt-get install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent.service

On Rocky, AlmaLinux, or RHEL, use the DNF equivalent:

dnf install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent.service

Confirm the service is active and inspect recent errors:

systemctl status qemu-guest-agent.service
journalctl -u qemu-guest-agent.service -n 30 --no-pager

Check the guest service on Windows

Windows needs the QEMU Guest Agent MSI from the VirtIO driver media, not just the VirtIO drivers themselves. After installation, make sure the main agent and the VSS provider are present and set to start automatically:

Get-Service -DisplayName 'QEMU Guest Agent'
Get-Service -DisplayName 'QEMU Guest Agent VSS Provider'

Get-Service -DisplayName 'QEMU Guest Agent' | Set-Service -StartupType Automatic
Get-Service -DisplayName 'QEMU Guest Agent' | Start-Service
Get-Service -DisplayName 'QEMU Guest Agent VSS Provider' | Start-Service

If the VSS provider is missing, IP reporting may work while Windows backups still fail. That mismatch is one of the most confusing guest agent states I have seen.

How to Fix Missing IP Addresses in the Proxmox Summary

Proxmox shows IP addresses from the guest agent, not from a DHCP lease or ARP table. If the agent is absent, the summary may stay blank even though the VM has a perfectly working IP address.

From the host, ask the agent what interfaces it sees:

qm agent 100 get-network-information

If this returns data, the host and guest are talking, and the missing IP is usually a guest-side interface problem. If it returns an error, go back to the service checks above.

Inside a Linux guest, verify that the interface actually has an address:

ip -br addr

Inside Windows, use PowerShell:

Get-NetIPAddress -AddressFamily IPv4 | Select-Object InterfaceAlias, IPAddress

A common gotcha is a cloud image that starts with the package installed but the service disabled. Another is a network interface that is up only after a delayed DHCP client starts. In both cases, the agent reports exactly what it sees, so Proxmox is not lying; it is simply reporting an empty guest view.

If you recently changed SDN zones, bridge names, or firewall rules, do not assume the agent is broken until the network itself has been reviewed. A Proxmox VE 9.2 SDN audit is a good way to rule out address assignment problems before restarting guest services.

How to Make Quiesced Backups Stop Failing

Quiesced backups are where the guest agent earns its keep. Proxmox takes a snapshot, then asks the guest to freeze filesystems or create a VSS snapshot so the backup sees a consistent state. If the agent cannot respond, the backup may fail outright or complete without the consistency you expected.

From the Proxmox host, test a single quiesced backup like this:

vzdump 100 --storage local --mode snapshot --qga 1

Replace local with your backup storage name. The command is deliberately narrow: one VM, one storage backend, snapshot mode, and guest-agent quiescing. That makes the failure message much easier to read. In the GUI, this is the checkbox labeled Quiesce guest file system.

Linux guests

On Linux, the agent uses filesystem freeze and thaw operations. You can test the same path manually:

qm agent 100 fsfreeze
qm agent 100 fsthaw

Run the thaw immediately after the freeze. If the freeze step hangs or returns an error, the backup will likely fail at the same point. In my experience, the most common causes are a stopped service, a kernel without the needed filesystem support, or a guest that is so busy that the freeze takes longer than expected.

Windows guests

On Windows, the agent relies on VSS. That means the QEMU Guest Agent service alone is not enough. The VSS Provider service must also be present and running. If you see a backup task that starts normally, then fails during snapshot creation, check the VSS provider before blaming storage.

A realistic timing note: on a 40 GB Windows VM backed by NVMe, a quiesced snapshot backup may finish in about 90 seconds. On a slow HDD pool, the same job can stretch into several minutes, especially if VSS writers are busy. That difference is normal, but a multi-minute stall on fast storage often points to a guest-side freeze problem rather than a backup target problem.

The honest tradeoff is that quiescing is not free. It briefly pauses guest I/O, and on a busy application server that pause can be visible. If your application cannot tolerate any freeze, you may prefer a snapshot backup without quiescing and rely on application-aware backups instead.

Finally, a quiesced snapshot is only useful if the restore works. After changing backup modes, run a PBS 4.2 S3 restore test so you know the guest agent actually produced a usable backup.

How to Fix Shutdown and Reboot Issues

Graceful shutdown is the third feature that depends on the same agent channel. When the agent is available, Proxmox can ask the guest to shut down cleanly instead of relying on ACPI alone.

Test the normal path from the host:

qm shutdown 100

If that does not work, check whether the agent itself is responsive. A quick way is to look at the status check again:

qm agent 100 get-status

If the agent responds but the VM still does not shut down, inspect the guest service logs on Linux or the Windows Event Viewer. Sometimes the agent is running, but the guest is configured to prompt for driver installation, hold on a shutdown screen, or block shutdown with a pending update.

On Linux guests, a minimal image without a full init system can also cause confusing results. The agent may respond to queries but still fail to shut the system down cleanly if the rest of the guest is not in a normal state.

Linux and Windows Differences at a Glance

Area	Linux guests	Windows guests
Install source	qemu-guest-agent package	QEMU Guest Agent MSI from VirtIO driver media
Service model	systemd unit	QEMU Guest Agent and VSS Provider services
Backup quiesce	Filesystem freeze and thaw	VSS snapshot
Shutdown path	systemd shutdown via agent	Windows shutdown via agent
Common failure	Service installed but disabled	VSS Provider stopped after updates

Gotchas That Make a Good Guest Agent Look Broken

The guest agent is usually not broken; it is simply being asked to do something it cannot see. These are the cases that waste the most time.

First, the VM option can be enabled while the guest service is stopped. The host may show the agent as enabled in the GUI, but backup tasks still fail. That mismatch is the single most common source of confusion.

Second, Windows updates can leave the VSS Provider service stopped even though the main agent service is running. I have seen backups fail with a generic QGA timeout after a reboot, and the fix was simply starting the VSS provider again.

Third, enabling the agent option on a running VM may not take effect until the VM is stopped and started. If you enable the option and immediately test backups, you may be chasing a problem that a cold boot would solve.

Fourth, the agent reports only what the guest sees. If the interface is down, if DHCP has not assigned an address, or if the guest is using a network namespace that the agent does not understand, the IP summary can remain empty even though the VM is reachable from the outside.

Fifth, quiesced backups can fail when the guest has many snapshots or the backup storage is slow. The guest agent may be fine, but the snapshot operation itself is slow. In those cases, the task log often tells you more than the agent status does.

Conclusion

Once the VM option, guest package, and service state all line up, missing IP addresses disappear, quiesced backups become reliable, and graceful shutdowns stop falling back to slower methods. Your next step is to pick one test VM, enable the agent from the host, install the guest package, and run a single quiesced backup before changing production backup jobs.