ProxSave restore is category-based. Each category represents a set of files/directories that can be restored together. During restore, ProxSave scans the chosen backup bundle, detects which categories are present, and (in CUSTOM mode) lets you select which ones to apply.
This document focuses on what can be restored, how categories are classified, and the important safety rules (especially for PVE).
How categories work
- Categories are defined in code (see internal/orchestrator/categories.go).
- During restore, ProxSave reads the archive entries and marks a category as “available” when at least one of its paths is present.
- A category can be:
- System-write: files are written back to their original paths under
/. - Export-only: files are extracted to an export directory and never written to system paths.
Category classes
System scope
Each category has a scope (used to filter what you see on the current host):
- PVE (CategoryTypePVE): only meaningful on Proxmox VE nodes.
- PBS (CategoryTypePBS): only meaningful on Proxmox Backup Server nodes.
- Common (CategoryTypeCommon): applies to both PVE and PBS.
Restore behavior class
- Export-only:
ExportOnly=true(for example pve_config_export). - System-write: extracted back to /… when selected.
Service impact class
Some selections trigger extra safety handling:
- PVE cluster DB restore (pve_cluster, RECOVERY): ProxSave stops PVE services and attempts to unmount /etc/pve before restoring.
- PBS restore (any PBS category selected): ProxSave attempts to stop proxmox-backup services before applying configuration changes.
PVE safety rule: /etc/pve is never overwritten
When restoring to the system root (/), ProxSave intentionally never writes to /etc/pve. This is a hard safety guard in the restore extractor.
Implications:
- To get /etc/pve content from a backup you must use the export-only category pve_config_export.
- Categories that reference files under /etc/pve (for example pve_jobs) will not overwrite those paths on disk; those entries are effectively skipped during system restore.
Category reference
PVE categories
| ID | What it contains (paths) | Class | Notes |
|---|---|---|---|
| pve_config_export | /etc/pve/** (export) | Export-only | Extracted to a directory like pve-config-export-YYYYMMDD-HHMMSS under your base directory; never written to /etc/pve. |
| pve_cluster | /var/lib/pve-cluster/** | System-write (or export in SAFE) | If the backup is marked as a cluster backup and you selected this category, ProxSave prompts SAFE vs RECOVERY. SAFE exports (no DB write); RECOVERY restores the cluster DB. |
| storage_pve | /etc/vzdump.conf | System-write | Restores vzdump configuration. If /etc/pve/storage.cfg exists on the node, ProxSave can also attempt to recreate storage directory structures; storage definitions themselves are typically handled via exported /etc/pve data. |
| pve_jobs | /etc/pve/jobs.cfg, /etc/pve/vzdump.cron | System-write (but /etc/pve is blocked) | These paths are under /etc/pve and are not overwritten directly; use the exported /etc/pve to review/apply. |
| corosync | /etc/corosync/** | System-write | Restore with care; changing corosync on a live cluster can break quorum/networking. |
| ceph | /etc/ceph/** | System-write | Restore with care; it can affect Ceph services and cluster connectivity. |
PBS categories
| ID | What it contains (paths) | Class | Notes |
|---|---|---|---|
| pbs_config | /etc/proxmox-backup/** | System-write | Selecting any PBS category triggers an attempt to stop proxmox-backup services first. |
| datastore_pbs | /etc/proxmox-backup/datastore.cfg | System-write | If selected, ProxSave also attempts to recreate datastore directories based on the restored datastore.cfg. |
| pbs_jobs | /etc/proxmox-backup/{sync,verification,prune}.cfg | System-write | Restores PBS job configuration (sync/verify/prune). |
If ProxSave cannot stop PBS services:
- TUI mode asks whether to continue.
- CLI mode logs a warning and continues the restore.
Common categories (PVE + PBS)
| ID | What it contains (paths) | Class | Notes |
|---|---|---|---|
| network | /etc/network/**, plus hostname/DNS files | System-write | Includes /etc/hosts, /etc/hostname, /etc/resolv.conf, and related network config paths. |
| ssl | /etc/proxmox-backup/proxy.pem | System-write | Primarily relevant to PBS. PVE certificates typically live under /etc/pve and are therefore handled via pve_config_export. |
| ssh | /root/.ssh/**, /etc/ssh/** | System-write | Can affect remote access. Make sure you keep a working login path. |
| scripts | /usr/local/bin/**, /usr/local/sbin/** | System-write | Restores user scripts/tools under /usr/local. |
| crontabs | /etc/cron.d/**, /etc/crontab, /var/spool/cron/** | System-write | Restores system cron configuration. |
| services | /etc/systemd/system/**, /etc/default/**, /etc/udev/rules.d/** | System-write | Restores service overrides/units and related system config. |
| zfs | /etc/zfs/**, /etc/hostid | System-write | On PBS, if this category is restored, ProxSave also runs a post-restore check to show pools that may require zpool import. |
Selecting categories (CUSTOM mode)
TUI:
proxsave --restoreCLI:
proxsave --restore --cliIn CLI selection, ProxSave supports:
- a select all, n deselect all
- numbers to toggle items
- c continue
- 0 cancel
If you need deeper troubleshooting output:
proxsave --restore --cli --log-level debugNote: “base directory” is the ProxSave working directory (BASE_DIR in configuration). If not explicitly set, it typically defaults to /opt/proxsave.
What is not restored
ProxSave restores configuration and metadata that were collected into the backup bundle. It does not restore:
- VM/CT disk images (use Proxmox backup mechanisms like vzdump or PBS backups)
- VM/CT filesystem contents (user data inside guests)
- Random runtime state, caches, or temporary files not captured by the bundle