3f8f1f7899
Replaced the two-step setup code process with a simpler token-in-URL approach: - Auth token is now embedded directly in the setup URL - No more prompting users for setup codes - Same security level with better UX - Backwards compatible with old setupCode field The new flow generates a command like: curl -sSL "http://pulse/api/setup-script?...&auth_token=TOKEN" | bash This makes it much easier for users, especially in Proxmox shell where interactive prompts can be problematic.
4.3 KiB
VM Disk Usage Monitoring
Pulse can show actual disk usage for VMs (just like containers) when the QEMU Guest Agent is installed and configured properly.
What You See
Without QEMU Guest Agent:
- VMs show allocated disk size only (e.g., 32GB allocated)
- No visibility into actual disk usage inside the VM
With QEMU Guest Agent:
- VMs show real disk usage like containers do (e.g., 5.2GB used of 32GB)
- Accurate threshold alerts based on actual usage
- Better capacity planning with real data
Requirements
1. Install QEMU Guest Agent in Your VMs
Linux VMs:
# Debian/Ubuntu
apt-get install qemu-guest-agent
systemctl enable --now qemu-guest-agent
# RHEL/Rocky/AlmaLinux
yum install qemu-guest-agent
systemctl enable --now qemu-guest-agent
# Alpine
apk add qemu-guest-agent
rc-update add qemu-guest-agent
rc-service qemu-guest-agent start
Windows VMs:
- Download virtio-win guest tools from: https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/
- Install the guest tools package which includes the QEMU Guest Agent
- The service starts automatically after installation
2. Enable Guest Agent in VM Options
In Proxmox web UI:
- Select your VM
- Go to Options → QEMU Guest Agent
- Check Enabled
- Start/restart the VM
Or via CLI:
qm set <vmid> --agent enabled=1
3. Verify Guest Agent is Working
Check if the agent is responding:
qm agent <vmid> ping
Get filesystem info (what Pulse uses):
qm agent <vmid> get-fsinfo
4. Pulse Permissions
Pulse needs the right permissions to query the guest agent:
Proxmox 8 and below: Requires VM.Monitor permission
Proxmox 9+: Requires VM.GuestAgent.Audit permission
When you run the Pulse setup script, it automatically detects your Proxmox version and sets the correct permissions. If setting up manually:
# Proxmox 9+
pveum aclmod / -user pulse-monitor@pam -role PVEAuditor
# PVEAuditor includes VM.GuestAgent.Audit in PVE 9+
# Proxmox 8 and below
pveum role add PulseMonitor -privs VM.Monitor
pveum aclmod / -user pulse-monitor@pam -role PulseMonitor
Troubleshooting
Guest Agent Not Responding
Check if agent is running inside VM:
# Linux
systemctl status qemu-guest-agent
# Windows
Get-Service QEMU-GA
Check VM configuration:
# Should show "agent: 1"
qm config <vmid> | grep agent
Check agent communication:
# Should return without error
qm agent <vmid> ping
Disk Usage Not Showing
If the agent is working but Pulse still shows allocated size:
- Check Pulse permissions - Ensure the Pulse user has VM.Monitor (PVE 8) or VM.GuestAgent.Audit (PVE 9+)
- Check agent version - Older agents might not support filesystem info
- Windows VMs - Ensure virtio-win drivers are up to date
- Check Pulse logs - Look for "GetVMFSInfo" errors
Network Filesystems
The agent reports all mounted filesystems. Pulse automatically filters out:
- Network mounts (NFS, CIFS, SMB)
- Special filesystems (proc, sys, tmpfs, etc.)
- Bind mounts and overlays
Only local disk usage is counted toward the VM's total.
Best Practices
- Install guest agent in VM templates - New VMs will have it ready
- Monitor agent status - Set up alerts if critical VMs lose agent connectivity
- Keep agents updated - Update guest agents when updating VM operating systems
- Test after VM migrations - Verify agent still works after moving VMs between nodes
Platform-Specific Notes
Cloud-Init Images
Most cloud images include qemu-guest-agent pre-installed but may need to be enabled:
systemctl enable --now qemu-guest-agent
Docker/Kubernetes VMs
Container workloads can show high disk usage due to container layers. Consider:
- Using separate disks for container storage
- Monitoring container disk usage separately
- Setting appropriate thresholds for container hosts
Database VMs
Databases often pre-allocate space. The guest agent shows actual usage, which might be less than what the database reports internally.
Benefits
With QEMU Guest Agent disk monitoring:
- Accurate alerts - Alert on real usage, not allocated space
- Better planning - See actual growth trends
- Prevent surprises - Know when VMs are actually running out of space
- Optimize storage - Identify over-provisioned VMs