Proxmox QEMU Guest Agent: Installation, Configuration, and Troubleshooting

What the QEMU Guest Agent Does

The QEMU Guest Agent (QGA) is a small daemon that runs inside your virtual machines and communicates with the Proxmox host through a virtio serial channel. It enables features that are impossible without guest cooperation: proper shutdown commands, filesystem quiescing for consistent backups, IP address reporting, and time synchronization after resume.

Without the guest agent, Proxmox can only see your VM as an opaque black box. With it, you get visibility into the guest OS and safer backup operations. If you use ProxmoxR to monitor your VMs, the guest agent provides the IP address data that makes remote management much easier.

Installing on Linux Guests

The guest agent is available in the default repositories of most Linux distributions.

# Debian/Ubuntu
sudo apt update
sudo apt install qemu-guest-agent
sudo systemctl enable qemu-guest-agent
sudo systemctl start qemu-guest-agent

# RHEL/CentOS/AlmaLinux/Rocky
sudo dnf install qemu-guest-agent
sudo systemctl enable qemu-guest-agent
sudo systemctl start qemu-guest-agent

# Arch Linux
sudo pacman -S qemu-guest-agent
sudo systemctl enable qemu-guest-agent
sudo systemctl start qemu-guest-agent

# Alpine Linux
apk add qemu-guest-agent
rc-update add qemu-guest-agent
service qemu-guest-agent start

# Verify the agent is running
systemctl status qemu-guest-agent

Installing on Windows Guests

For Windows VMs, the guest agent is included in the VirtIO drivers ISO.

# Step 1: Download the VirtIO drivers ISO to Proxmox
# Upload to a storage accessible by the VM, or use:
wget https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/stable-virtio/virtio-win.iso \
    -O /var/lib/vz/template/iso/virtio-win.iso

# Step 2: Attach the ISO to the Windows VM as a CD-ROM
qm set 100 -cdrom local:iso/virtio-win.iso

# Step 3: Inside Windows, open the ISO and run:
# D:\guest-agent\qemu-ga-x86_64.msi  (for 64-bit)
# or
# D:\guest-agent\qemu-ga-i386.msi    (for 32-bit)

# Step 4: Verify in Windows Services:
# Service name: "QEMU Guest Agent VSS Provider" should be Running

Enabling the Guest Agent in VM Configuration

Installing the agent inside the guest is only half the setup. You must also enable it in the Proxmox VM configuration.

# Enable guest agent for a VM (requires VM restart)
qm set 100 --agent enabled=1

# Enable with additional options
qm set 100 --agent enabled=1,fstrim_cloned_disks=1

# The fstrim_cloned_disks option automatically runs fstrim
# after cloning, which reclaims space on thin-provisioned storage

# Verify the setting
qm config 100 | grep agent

# After enabling, restart the VM for the channel to be created
qm reboot 100

Using qm agent Commands

Once the agent is running and enabled, you can query the guest from the Proxmox host.

# Get network information (IP addresses)
qm agent 100 network-get-interfaces

# Ping the agent to check if it is responsive
qm agent 100 ping

# Get OS information
qm agent 100 get-osinfo

# Get filesystem information
qm agent 100 get-fsinfo

# Execute a command inside the guest
qm agent 100 exec -- ls /tmp

# Freeze filesystems (for consistent snapshots)
qm agent 100 fsfreeze-freeze

# Thaw filesystems after snapshot
qm agent 100 fsfreeze-thaw

# Check freeze status
qm agent 100 fsfreeze-status

Fixing: IP Address Not Showing in Proxmox UI

One of the most common complaints is that VM IP addresses do not appear in the Proxmox web interface summary panel. There are several causes.

# Cause 1: Guest agent not enabled in VM config
qm config 100 | grep agent
# Fix: qm set 100 --agent enabled=1 (then reboot VM)

# Cause 2: Guest agent not running inside the VM
# SSH into the VM and check:
systemctl status qemu-guest-agent
# Fix: install and start the agent

# Cause 3: VM was not rebooted after enabling the agent
# The virtio serial channel is created at boot time
# Fix: fully stop and start (not just reboot in some cases)
qm stop 100
qm start 100

# Cause 4: Virtio serial device not present
qm config 100 | grep serial
# The agent channel should be automatically added when agent is enabled
# If missing, check your VM hardware configuration

# Cause 5: Proxmox cache delay
# IP information updates periodically, not instantly
# Wait 30-60 seconds after VM boot before checking

Fixing fsfreeze Issues During Backups

When Proxmox takes a backup of a VM with the guest agent enabled, it attempts to freeze the guest filesystems for a consistent snapshot. This can fail for several reasons.

# Error: "QEMU Guest Agent is not responding"
# The agent may have crashed or the channel is broken
# Inside the VM:
sudo systemctl restart qemu-guest-agent

# Error: "guest-fsfreeze-freeze timed out"
# A process is holding a filesystem lock
# Check for heavy I/O operations and retry

# Error: "fsfreeze failed on some filesystems"
# Some filesystem types cannot be frozen
# In VM config, exclude problematic mount points:
# Edit /etc/qemu/fsfreeze-hook.d/ to skip certain mounts

# Workaround: disable fsfreeze for backups
# In vzdump.conf or per-job:
# freeze-fs-on-backup: 0

# Or disable guest agent interaction for backups only
# In the backup job configuration:
# --mode snapshot (instead of suspend)

# Check which filesystems are currently frozen
qm agent 100 fsfreeze-status
# If stuck in "frozen" state:
qm agent 100 fsfreeze-thaw

Guest Agent Best Practices

• Always install the guest agent in every VM, even if you do not need it immediately
• Enable fstrim_cloned_disks when using thin provisioning
• Test fsfreeze before relying on it for production backups
• Keep VirtIO drivers updated in Windows guests
• Include guest agent installation in your VM templates for automatic deployment
• Monitor agent responsiveness as part of your regular health checks

The QEMU Guest Agent is a small addition that significantly improves your Proxmox management experience. A few minutes of setup per VM pays dividends in backup reliability, visibility, and operational control.