4675b5bf92
- Add detailed logging when VM disk monitoring fails due to permissions - Explain Proxmox 9 limitation: API tokens cannot access guest agent data (PVE bug #1373) - Explain Proxmox 8 requirements: VM.Monitor permission and privsep=0 for tokens - Update setup script to show appropriate warnings for each PVE version - Update FAQ with troubleshooting steps for 0% disk usage on VMs - Log messages now clearly indicate workarounds for each scenario The core issue: Proxmox 9 removed VM.Monitor permission and the replacement permissions don't allow API tokens to access guest agent filesystem info. This is a Proxmox upstream bug that affects their own web UI as well. For users experiencing this issue: - PVE 9: Use root@pam credentials or wait for Proxmox to fix upstream - PVE 8: Ensure token has VM.Monitor and privsep=0 - All versions: QEMU guest agent must be installed in VMs
5.3 KiB
FAQ
Installation
What's the easiest way to install?
bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/pulse.sh)"
System requirements?
- 1 vCPU, 512MB RAM (1GB recommended), 1GB disk
- Network access to Proxmox API
Configuration
How do I add a node?
Auto-discovery (Easiest): Settings → Nodes → Click "Setup Script" on discovered node → Run on Proxmox Manual: Settings → Nodes → Add Node → Enter credentials → Save
How do I disable network discovery?
Settings → System → Network Settings → Toggle "Enable Discovery" off → Save
Or set environment variable DISCOVERY_ENABLED=false
How do I change the port?
Systemd: sudo systemctl edit pulse, add Environment="FRONTEND_PORT=8080", restart
Docker: Use -e FRONTEND_PORT=8080 -p 8080:8080 in your run command
See Port Configuration Guide for details
Why can't I change settings in the UI?
If a setting is disabled with an amber warning, it's being overridden by an environment variable.
Remove the env var (check sudo systemctl show pulse | grep Environment) and restart to enable UI configuration.
What permissions needed?
- PVE:
PVEAuditorminimum (includes VM.GuestAgent.Audit for disk usage in PVE 9+) - PVE 8: Also needs
VM.Monitorpermission for VM disk usage via QEMU agent - PBS:
DatastoreReaderminimum
API tokens vs passwords?
API tokens are more secure. Create in Proxmox: Datacenter → Permissions → API Tokens
Where are settings stored?
See Configuration Guide for details
How do I backup my configuration?
Settings → Security → Backup & Restore → Export Backup
- If logged in with password: Just enter your password or a custom passphrase
- If using API token only: Provide the API token when prompted
- Includes all settings, nodes, credentials (encrypted), and custom console URLs
Can Pulse detect Proxmox clusters?
Yes! When you add one cluster node, Pulse automatically discovers and monitors all nodes
Troubleshooting
No data showing?
- Check Proxmox API is reachable (port 8006/8007)
- Verify credentials
- Check logs:
journalctl -u pulse -f
Connection refused?
- Check port 7655 is open
- Verify Pulse is running:
systemctl status pulse
PBS connection issues?
- PBS requires HTTPS (not HTTP) - use
https://your-pbs:8007 - Default PBS port is 8007 (not 8006)
- Check firewall allows port 8007
Invalid credentials?
- Check username includes realm (@pam, @pve)
- Verify API token not expired
- Confirm user has required permissions
CORS errors in browser?
- By default, Pulse only allows same-origin requests
- Set
ALLOWED_ORIGINSenvironment variable for cross-origin access - Example:
ALLOWED_ORIGINS=https://app.example.com - Never use
*in production
Authentication issues?
- Password auth: Check
PULSE_AUTH_USERandPULSE_AUTH_PASSenvironment variables - API token: Verify
API_TOKENis set correctly - Session expired: Log in again via web UI
- Account locked: Wait 15 minutes after 5 failed attempts
High memory usage?
Reduce metricsRetentionDays in settings and restart
Features
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
- Note: Container (LXC) disk usage works fine
Proxmox 8: Check that:
- QEMU Guest Agent is installed and running in the VM
- Your API token has
VM.Monitorpermission - Token has privilege separation disabled (
privsep=0)- Check with:
pveum user token list pulse-monitor@pam | grep pulse-token - If privsep=1, recreate:
pveum user token add pulse-monitor@pam pulse-token --privsep 0
- Check with:
All versions:
- Guest agent must be installed:
apt install qemu-guest-agent(Linux) or virtio-win tools (Windows) - Enable in VM Options → QEMU Guest Agent
- Restart the VM after installing
How do I see real disk usage for VMs?
Install QEMU Guest Agent in your VMs:
- Linux:
apt install qemu-guest-agentoryum install qemu-guest-agent - Windows: Install virtio-win guest tools
- Enable in VM Options → QEMU Guest Agent
- Restart the VM for changes to take effect See VM Disk Monitoring Guide for details.
Multiple clusters?
Yes, add multiple nodes in Settings
PBS push mode?
No, PBS push mode is not currently supported. PBS monitoring requires network connectivity from Pulse to the PBS server.
Webhook providers?
Discord, Slack, Gotify, Telegram, ntfy.sh, Teams, generic JSON
Works with reverse proxy?
Yes, ensure WebSocket support is enabled
Updates
How to update?
- ProxmoxVE LXC: Type
updatein the LXC console - Docker: Pull latest image, recreate container
- Manual/systemd: Run the install script again:
curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/install.sh | bash
Why can't I update from the UI?
For security reasons, Pulse cannot self-update. The UI will notify you when updates are available and show the appropriate update command for your deployment type.
Will updates break config?
No, configuration is preserved