Pulse/docs/VM_DISK_MONITORING.md

💾 VM Disk Monitoring

Monitor actual disk usage inside your VMs using the QEMU Guest Agent.

🚀 Quick Start

1. Install Guest Agent:
   • Linux: apt install qemu-guest-agent (Debian/Ubuntu) or yum install qemu-guest-agent (RHEL).
   • Windows: Install virtio-win drivers.
2. Enable in Proxmox:
   • VM Options → QEMU Guest Agent → Enabled.
   • Restart the VM.
3. Verify:
   • Run qm agent <vmid> ping on the Proxmox host.
   • Check Pulse dashboard for disk usage (e.g., "5.2GB used of 32GB").

⚙️ Requirements

• QEMU Guest Agent: Must be installed and running inside the VM.
• Proxmox Permissions: VM.Monitor (Proxmox 8) or VM.GuestAgent.Audit + VM.GuestAgent.FileRead (Proxmox 9+). Note: PVEAuditor is a built-in read-only role that cannot be modified — create a custom role instead.

🔧 Troubleshooting

Issue	Solution
Disk shows "-"	Hover over the dash for details. Common causes: Agent not running, disabled in config, or permission denied.
Permission Denied	Ensure your Proxmox token/user has VM.GuestAgent.Audit + VM.GuestAgent.FileRead (PVE 9+) or VM.Monitor (PVE 8).
Rocky Linux / RHEL: memory or disk data missing	The default qemu-guest-agent config may block file-read RPCs. Check /etc/sysconfig/qemu-ga and ensure guest-file-open, guest-file-read, and guest-file-close are not blocked, then restart the agent. See your distro's qemu-guest-agent docs for exact syntax.
Agent Timeout	Increase timeouts via env vars if network is slow: GUEST_AGENT_FSINFO_TIMEOUT=10s.
Windows VMs	Ensure the QEMU Guest Agent service is running in Windows Services.

Diagnostic Script

Run this on your Proxmox host to debug specific VMs:

curl -sSL https://raw.githubusercontent.com/rcourtman/Pulse/main/scripts/test-vm-disk.sh | bash

📝 Notes

• Network Mounts: NFS/SMB mounts are automatically excluded.
• Databases: Usage reflects filesystem usage, which may differ from database-internal metrics.
• Containers: LXC containers are monitored natively without the guest agent.