Pulse/docs/PBS.md

Proxmox Backup Server (PBS) Integration

This guide explains how to connect Pulse to your Proxmox Backup Server for comprehensive backup monitoring.

Two Ways to Monitor PBS Backups

Pulse can monitor PBS backups in two ways:

1. Direct PBS Connection (Recommended)

Connect to the PBS API with a dedicated read-only token. An agent is not required for these API-backed readings:

Benefits:

• ✅ Deduplication factor and storage efficiency stats
• ✅ PBS server health monitoring (CPU, memory, uptime)
• ✅ Datastore usage and namespace hierarchy
• ✅ Sync, verify, prune, and GC job status
• ✅ Backup owner information
• ✅ Faster queries (no PVE proxy overhead)

2. PVE Passthrough (Automatic)

If your PVE cluster has PBS storage configured, Pulse automatically fetches backup data through the PVE API.

Limitations:

• ❌ No deduplication stats
• ❌ No PBS server health data
• ❌ No job monitoring
• ❌ Can be slow for encrypted PBS storage
• ❌ Limited metadata per backup

Recommendation: Start with a direct API connection when you need PBS datastore, job or server status beyond the PVE passthrough. Add a host agent only for extra local telemetry such as SMART and temperatures; see Agent Security.

---

Setting Up Direct PBS Connection

Method 1: API-Only Connection (Recommended)

Use a dedicated PBS monitoring user and token, not a root password. On a new setup, run these commands in an administrator shell on the PBS server:

proxmox-backup-manager user create pulse-monitor@pbs --comment "Pulse monitoring"
proxmox-backup-manager user generate-token pulse-monitor@pbs pulse-token
proxmox-backup-manager acl update / Audit --auth-id pulse-monitor@pbs
proxmox-backup-manager acl update / Audit --auth-id 'pulse-monitor@pbs!pulse-token'

PBS tokens have their own permissions, limited by their owning user's permissions. Grant Audit to both the user and the token. If either already exists, inspect and reuse it instead of deleting it or rerunning token creation. Do not disable privilege separation or grant Admin to work around a missing permission.

The token secret is shown once. Save it privately and enter it only in Pulse's Token Value field; do not paste it into a shell command, URL, screenshot or issue report. Keep any terminal recording containing that output private.

In Pulse:

1. Open Settings → Infrastructure → Add infrastructure and choose Proxmox Backup Server.
2. Enter the PBS HTTPS URL, normally https://pbs.example.com:8007.
3. Select API Token and Manual Token Setup.
4. Enter Token ID pulse-monitor@pbs!pulse-token and its secret in Token Value.
5. Keep certificate verification enabled. For a self-signed certificate, use an independently verified SSL Fingerprint; see the TLS guidance below.
6. Test and save the connection. Check that the expected datastores and backups are visible, not just that the connection test succeeds.

Method 2: Optional Host Agent

Use this only when you also need host-local telemetry. The Linux agent normally runs as root; it is not required to fix API authentication or missing backup permissions. Review Agent Security first.

Create a separate Pulse token in API Access, using the Agent host preset for reporting, configuration reads and agent management. This is a Pulse token, not the PBS token used above. Do not enable command execution just for monitoring.

On the PBS host, enter an administrator root shell before preparing the private file below. In the editor, save only the Pulse agent token, with no header or quotes; never put the secret in a command argument:

umask 077
mkdir -p "$HOME/.config/pulse"
chmod 700 "$HOME/.config/pulse"
touch "$HOME/.config/pulse/pbs-agent-token"
chmod 600 "$HOME/.config/pulse/pbs-agent-token"
vi "$HOME/.config/pulse/pbs-agent-token"

Download the agent installer from your Pulse server's HTTPS address, then inspect the saved script before running it. Replace the example Pulse URL in both commands. Stop if the download fails; run the next command only after a successful download and inspection. Do not substitute GitHub's top-level install.sh: that installs the Pulse server, not the agent.

curl --fail --silent --show-error \
  --output "$HOME/.config/pulse/pbs-agent-install.sh" \
  https://pulse.example.com/install.sh

bash "$HOME/.config/pulse/pbs-agent-install.sh" \
  --url https://pulse.example.com \
  --token-file "$HOME/.config/pulse/pbs-agent-token" \
  --enable-proxmox --proxmox-type pbs --enable-docker=false

Do not bypass certificate checks to fetch or run the installer. Use a trusted Pulse certificate or a CA file you verified separately. See Unified Agent Setup for installer trust and other profiles. After installation, check a fresh agent report and the host's pulse-agent --version; installation or hardware capacity alone does not prove that every CPU, memory or History reading is available. Keep the token file private and remove the bootstrap copy when no longer needed; do not remove the installed agent's runtime credential.

---

PBS Permissions

The Pulse monitoring user needs minimal permissions:

Role	Path	Purpose
Audit	/	Read-only access to all datastores, backups, and server status

The Audit role provides:

• List datastores and their usage
• View backup groups and snapshots
• Read server status (CPU, memory, uptime)
• View job history and status

It does not allow:

• Creating, modifying, or deleting backups
• Running backup/restore operations
• Changing server configuration

---

Multiple PBS Servers

If you have multiple PBS servers, add each one separately in Settings. Pulse will:

• Monitor each server independently
• Show backups from all servers in the unified Recovery view
• Deduplicate if the same backup appears via both PVE passthrough and direct PBS

---

Troubleshooting

"Connection Failed" Error

Check from the Pulse host or container's network, if possible. A request from another machine does not prove that Pulse can reach PBS.

• Address/network: use the PBS HTTPS URL and port 8007; check DNS, routing and the firewall before changing credentials.

• TLS: keep verification enabled. Use a certificate trusted by the Pulse runtime, or set its SSL Fingerprint after verifying the SHA-256 value through the PBS console or another already-trusted administrative channel. Do not accept a fingerprint solely from the failed connection. For example, on the PBS server you can inspect its public certificate (not its private key):

  openssl x509 -in /etc/proxmox-backup/proxy.pem -noout -fingerprint -sha256
  

• Authentication/permissions: test a datastore request, not just /version. Prepare a private header file on the machine running curl:

  umask 077
  mkdir -p "$HOME/.config/pulse"
  chmod 700 "$HOME/.config/pulse"
  touch "$HOME/.config/pulse/pbs-header"
  chmod 600 "$HOME/.config/pulse/pbs-header"
  vi "$HOME/.config/pulse/pbs-header"
  

  In the editor, save this line, replacing <pbs-token-secret> with the secret for the PBS token being tested:

  Authorization: PBSAPIToken=pulse-monitor@pbs!pulse-token:<pbs-token-secret>
  

  Then use curl 7.76 or later, with your PBS hostname:

  curl --fail-with-body --silent --show-error --connect-timeout 5 --max-time 15 \
    --header "@$HOME/.config/pulse/pbs-header" \
    https://pbs.example.com:8007/api2/json/admin/datastore
  

  For curl with a private CA or self-signed certificate, add --cacert "$HOME/.config/pulse/pbs-ca.pem" using a public certificate obtained and verified through a trusted channel. Its hostname must still match. Do not use --insecure or -k.

  401 means authentication was rejected; 403 means the requested access was refused. Both return a non-zero curl exit while retaining the error body. Inspect the existing token and both Audit grants before replacing anything. A 200 response listing the expected datastore establishes access to that list, not successful collection of every backup, job or History graph. An empty list is not proof that all permissions are correct.

Keep the header file outside shared repositories and diagnostics. Do not share verbose/trace curl output, full infrastructure responses, token values or private keys. If help is needed, provide only the HTTP status, relevant redacted error and which expected reading is missing. Do not clear History or recreate a working connection to make missing data look resolved.

Slow Backup Loading

If you notice slow loading for PBS storage accessed via PVE:

• This often happens with encrypted PBS datastores
• The fix is to add PBS directly (this guide)
• Direct PBS connections bypass the slow PVE content listing

Duplicate Backups

Check the source, datastore, namespace, guest type/ID and backup time on each entry. Independent PVE installations can reuse a guest ID; matching VMIDs alone are not proof of a duplicate. Keep both records while checking their origin. If the same backup remains listed twice, report those redacted distinctions and whether each entry came from direct PBS or PVE passthrough. Do not delete backups or change retention to hide a display problem.

---

Data Source Indicator

In the Recovery view, PBS backups show a data source indicator:

• "PBS" badge alone = Direct PBS connection (full data)
• "PBS via PVE" = Passthrough via PVE storage (limited data)

When the same backup is reconciled across both sources, Pulse prefers the direct PBS observation. Check the actual source and expected readings after adding the connection; the presence of a badge alone is not collection proof.

---

Related Documentation

• Unified Agent Setup - Installing agents on PBS/PVE/PMG hosts
• Configuration Reference - Environment variables including PBS settings
• Troubleshooting - General troubleshooting guide