Proxmox Backup Server — Reference
Links
- Website: https://www.proxmox.com/en/proxmox-backup-server
- Docs: https://pbs.proxmox.com/docs/
- CLI reference: https://pbs.proxmox.com/docs/command-line-tools.html
- API viewer: https://pbs.proxmox.com/docs/api-viewer/index.html
- Client docs: https://pbs.proxmox.com/docs/backup-client.html
Infrastructure
| Host | Internal | URL |
|---|---|---|
| cajita-elite (bare metal) | 192.168.1.196:8007 | https://pbs.eva-00.network |
Datastore: pbs-local on nvme1 (~880 GB).
API
PBS exposes a REST API at https://192.168.1.196:8007/api2/json/. Authentication uses API tokens.
Get an API ticket (session auth)
# Get ticket + CSRF token
RESPONSE=$(curl -sk -X POST https://192.168.1.196:8007/api2/json/access/ticket \
-d "username=root@pam&password=<password>")
TICKET=$(echo $RESPONSE | python3 -c "import json,sys; print(json.load(sys.stdin)['data']['ticket'])")
CSRF=$(echo $RESPONSE | python3 -c "import json,sys; print(json.load(sys.stdin)['data']['CSRFPreventionToken'])")
List datastores
curl -sk -H "Authorization: PBSAPIToken=user@pam!tokenname:TOKEN_UUID" \
https://192.168.1.196:8007/api2/json/admin/datastore
List backups in a datastore
curl -sk -H "Authorization: PBSAPIToken=user@pam!tokenname:TOKEN_UUID" \
https://192.168.1.196:8007/api2/json/admin/datastore/pbs-local/snapshots
Get datastore status (usage, GC info)
curl -sk -H "Authorization: PBSAPIToken=user@pam!tokenname:TOKEN_UUID" \
https://192.168.1.196:8007/api2/json/admin/datastore/pbs-local/status
Trigger garbage collection
curl -sk -X POST -H "Authorization: PBSAPIToken=user@pam!tokenname:TOKEN_UUID" \
-H "CSRFPreventionToken: $CSRF" \
https://192.168.1.196:8007/api2/json/admin/datastore/pbs-local/gc
CLI — proxmox-backup-client
Run from chizuru (Proxmox host) or any machine with the client installed.
export PBS_REPOSITORY="root@[email protected]:pbs-local"
# or: export PBS_REPOSITORY="localhost:pbs-local" (from cajita-elite itself)
List all snapshots
proxmox-backup-client list --repository localhost:pbs-local
Create a manual backup (from Proxmox host)
vzdump <VMID> --storage cajita-elite --mode snapshot --compress zstd
Restore a backup
# List available backups
proxmox-backup-client list --repository localhost:pbs-local
# Restore to a new LXC
pct restore <new-id> <backup-path> --storage <target-pool>
Mount a backup for file-level access
proxmox-backup-client mount <snapshot> --repository localhost:pbs-local /mnt/restore
# Browse: ls /mnt/restore/
# Unmount: umount /mnt/restore
CLI — proxmox-backup-manager
Run from cajita-elite directly (ssh -i ~/.ssh/id_ed25519_cajita [email protected]).
# List datastores
proxmox-backup-manager datastore list
# Datastore status
proxmox-backup-manager datastore show pbs-local
# Start garbage collection
proxmox-backup-manager garbage-collection start pbs-local
# List recent tasks
proxmox-backup-manager task list
# View task log
proxmox-backup-manager task log <UPID>
# Manage sync jobs
proxmox-backup-manager sync-job list
proxmox-backup-manager sync-job create <id> --store pbs-local --remote <remote> --remote-store <store>
# Verify backup integrity
proxmox-backup-manager verify pbs-local
Proxmox Integration (vzdump)
PBS is configured as a Proxmox storage target. Nightly backups run via Proxmox scheduled jobs.
# Check PBS storage config on Proxmox
ssh [email protected] "cat /etc/pve/storage.cfg" | grep -A5 cajita
# List scheduled backup jobs
ssh [email protected] "cat /etc/pve/jobs.cfg"
# Manual backup of a specific LXC
ssh [email protected] "vzdump 119 --storage cajita-elite --mode snapshot --compress zstd"
What the API/CLI Cannot Do
| Gap | Workaround |
|---|---|
| Cannot configure backup schedules via API | Use Proxmox web UI (Datacenter → Backup) or edit /etc/pve/jobs.cfg |
| Cannot add/remove datastores via API easily | Use proxmox-backup-manager datastore create/remove CLI |
| No built-in alerting for failed backups | Gatus monitors PBS; Backrest hooks send ntfy notifications |
| Cannot restore directly to a running LXC | Must restore to a new ID, then swap (or stop + restore over) |
| PBS web UI requires HTTPS (self-signed cert by default) | Browser certificate exception required; Caddy terminates TLS for pbs.eva-00.network |
proxmox-backup-client not installed on LXCs by default |
Run from chizuru (Proxmox host) or cajita-elite |
| Cannot selectively restore individual files from LXC backups via API | Use proxmox-backup-client mount to browse and copy files |
| No API for viewing/downloading task logs | Use proxmox-backup-manager task log <UPID> CLI |