From 6fd96d7bed57b079e09c511007dde4c6122da474 Mon Sep 17 00:00:00 2001
From: Pulse Monitor <pulse@pulse-monitor.dev>
Date: Mon, 25 Aug 2025 14:59:37 +0000
Subject: [PATCH] fix: remove misleading root@pam authentication advice

The root@pam suggestion doesn't actually work since it requires the Linux system root password, not a Proxmox-specific password. Most users don't know or have disabled their Linux root password for security.

Updated all documentation and error messages to correctly advise users to grant VM.Monitor permission to their API token user instead.
---
 docs/FAQ.md                     | 8 ++++----
 internal/api/config_handlers.go | 4 ++--
 internal/monitoring/monitor.go  | 4 ++--
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/FAQ.md b/docs/FAQ.md
index d4a166c59..4084e6f40 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -91,9 +91,9 @@ Reduce `metricsRetentionDays` in settings and restart
 ### Why do VMs show 0% disk usage?
 This is usually one of these issues:
 
-**Proxmox 9**: API tokens cannot access guest agent data due to a Proxmox bug (#1373). Even with correct permissions, tokens are blocked from accessing VM disk info. Workarounds:
-- Use root@pam credentials instead of API tokens
-- Accept that VM disk will show 0% until Proxmox fixes this upstream
+**Proxmox 9**: API tokens may have issues accessing guest agent data in some configurations. Workarounds:
+- Ensure your API token has VM.Monitor permission (re-run setup script if needed)
+- Accept that VM disk will show 0% if permissions aren't sufficient
 - Note: Container (LXC) disk usage works fine
 
 **Proxmox 8**: Check that:
@@ -111,7 +111,7 @@ This is usually one of these issues:
   - Alternative check: `ps aux | grep qemu-ga`
 - Restart the VM after installing/enabling in Proxmox options
 
-**Still showing 0% with root@pam?**
+**Still showing 0%?**
 - Verify from Proxmox host: `qm agent <VMID> get-fsinfo`
 - If that works but Pulse doesn't show it, check Pulse logs for errors
 - Some VMs may need: `systemctl restart qemu-guest-agent` inside the VM
diff --git a/internal/api/config_handlers.go b/internal/api/config_handlers.go
index 1cf66d471..731a2e90a 100644
--- a/internal/api/config_handlers.go
+++ b/internal/api/config_handlers.go
@@ -2173,9 +2173,9 @@ else
     echo "Proxmox's own web UI also shows 0% for VM disk usage (bug #1373)."
     echo ""
     echo "Workarounds:"
-    echo "  1. Use root@pam credentials instead of API tokens (full access)"
+    echo "  1. Ensure VM.Monitor permission is granted (should be done by this script)"
     echo "  2. Container (LXC) disk usage works correctly with tokens"
-    echo "  3. Wait for Proxmox to fix this upstream"
+    echo "  3. If still not working, check Pulse logs for specific errors"
     echo ""
     echo "Note: qemu-guest-agent must be installed in VMs for any disk"
     echo "monitoring to work. The data exists but token access is restricted."
diff --git a/internal/monitoring/monitor.go b/internal/monitoring/monitor.go
index 7771a04d2..c30750b64 100644
--- a/internal/monitoring/monitor.go
+++ b/internal/monitoring/monitor.go
@@ -996,7 +996,7 @@ func (m *Monitor) pollVMsAndContainersEfficient(ctx context.Context, instanceNam
 								log.Info().
 									Str("instance", instanceName).
 									Str("vm", res.Name).
-									Msg("Workaround: Use root@pam credentials or accept that VM disk usage will show 0%")
+									Msg("Workaround: Grant VM.Monitor permission to your API token user or accept that VM disk usage will show 0%")
 							} else {
 								log.Debug().
 									Err(err).
@@ -1378,7 +1378,7 @@ func (m *Monitor) pollVMsWithNodes(ctx context.Context, instanceName string, cli
 						log.Info().
 							Str("instance", instanceName).
 							Str("vm", vm.Name).
-							Msg("Workaround: Use root@pam credentials or accept that VM disk usage will show 0%")
+							Msg("Workaround: Grant VM.Monitor permission to your API token user or accept that VM disk usage will show 0%")
 					} else {
 						log.Debug().
 							Err(err).