mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-05-10 20:25:41 +00:00
1d987efcc9
Corrected widespread misinformation claiming API tokens cannot access guest agent data on Proxmox 9. Changes: - Rewrote VM_DISK_MONITORING.md with accurate technical explanation - Deleted VM_DISK_STATS_TROUBLESHOOTING.md (contained false information) - Updated FAQ.md with correct quick reference and troubleshooting link - Added comprehensive VM disk troubleshooting section to TROUBLESHOOTING.md - Fixed README.md troubleshooting reference - Updated frontend tooltip to show accurate permission requirements - Corrected backend log messages to remove "known limitation" language - Updated test-vm-disk.sh diagnostic script with accurate guidance Key corrections: - API tokens work fine for guest agent queries on both PVE 8 and 9 - Proxmox API returning disk=0 is normal behavior, not a bug - Both tokens and passwords work equally well - Only requirements: guest agent installed + proper permissions - Permission issues are config problems, not authentication method limitations Documentation now provides clear user journey: FAQ → Troubleshooting → Full Guide 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
155 lines
No EOL
5.6 KiB
Markdown
155 lines
No EOL
5.6 KiB
Markdown
# FAQ
|
|
|
|
## Installation
|
|
|
|
### What's the easiest way to install?
|
|
```bash
|
|
curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/install.sh | bash
|
|
```
|
|
|
|
### 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](PORT_CONFIGURATION.md) 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: `PVEAuditor` minimum (includes VM.GuestAgent.Audit for disk usage in PVE 9+)
|
|
- PVE 8: Also needs `VM.Monitor` permission for VM disk usage via QEMU agent
|
|
- PBS: `DatastoreReader` minimum
|
|
|
|
### API tokens vs passwords?
|
|
API tokens are more secure. Create in Proxmox: Datacenter → Permissions → API Tokens
|
|
|
|
### Where are settings stored?
|
|
See [Configuration Guide](CONFIGURATION.md) 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_ORIGINS` environment variable for cross-origin access
|
|
- Example: `ALLOWED_ORIGINS=https://app.example.com`
|
|
- Never use `*` in production
|
|
|
|
### Authentication issues?
|
|
- Password auth: Check `PULSE_AUTH_USER` and `PULSE_AUTH_PASS` environment variables
|
|
- API token: Verify `API_TOKEN` is 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 "-" for disk usage?
|
|
|
|
VMs show "-" because the QEMU Guest Agent is not installed or not working. This is normal and expected.
|
|
|
|
**How VM disk monitoring works:**
|
|
- Proxmox API always returns `disk=0` for VMs (this is normal, not a bug)
|
|
- To get real disk usage, Pulse queries the QEMU Guest Agent inside each VM
|
|
- Both API tokens and passwords work fine for this (no authentication method limitation)
|
|
- If guest agent is missing or not responding, Pulse shows "-" with a tooltip explaining why
|
|
|
|
**To get VM disk usage showing:**
|
|
|
|
1. **Install QEMU Guest Agent in the VM:**
|
|
- Linux: `apt install qemu-guest-agent && systemctl enable --now qemu-guest-agent`
|
|
- Windows: Install virtio-win guest tools
|
|
|
|
2. **Enable in VM config:**
|
|
- Proxmox UI: VM → Options → QEMU Guest Agent → Enable
|
|
- Or CLI: `qm set <VMID> --agent enabled=1`
|
|
|
|
3. **Restart the VM** for changes to take effect
|
|
|
|
4. **Verify it works:**
|
|
```bash
|
|
qm agent <VMID> ping
|
|
qm agent <VMID> get-fsinfo
|
|
```
|
|
|
|
5. **Check Pulse has permissions:**
|
|
- Proxmox 9: `PVEAuditor` role (includes `VM.GuestAgent.Audit`)
|
|
- Proxmox 8: `VM.Monitor` permission
|
|
- The setup script adds these automatically
|
|
|
|
**Note:** Container (LXC) disk usage always works without guest agent because containers share the host kernel.
|
|
|
|
**Still not working?** See [Troubleshooting Guide - VM Disk Monitoring](TROUBLESHOOTING.md#vm-disk-monitoring-issues) for detailed diagnostics.
|
|
|
|
### How do I see real disk usage for VMs?
|
|
See the previous question "Why do VMs show '-' for disk usage?" or the [VM Disk Monitoring Guide](VM_DISK_MONITORING.md) for full 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?
|
|
- **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 |