ProxSave is built on a modular architecture with six main components that work together to provide reliable backup and restore operations.
Collector
The Collector module gathers configuration (and optional system inventories) from your Proxmox system. It supports multiple collection sources and can be tuned via configuration toggles and custom paths.
- PVE Cluster: /etc/pve/, cluster configuration, VM/CT configs
- PBS Configuration: /etc/proxmox-backup/, datastores/users/jobs (depending on enabled toggles)
- Network: /etc/network/, DNS, hostname settings
- SSL Certificates: Node certificates, custom CA certificates
- SSH Keys: Host keys and authorized keys
- ZFS: Pool configurations, dataset properties
- Cron Jobs: System and user crontabs
- Systemd Services: Custom service units
- Scripts and inventory: /usr/local/bin, /usr/local/sbin, package and hardware inventory (when enabled)
Each collector can be individually enabled or disabled via configuration. You can also include arbitrary files/directories via CUSTOM_BACKUP_PATHS.
Archiver
The Archiver creates compressed tar archives from collected files. Supported compression algorithms:
| Algorithm | Extension | Speed | Ratio | Best For |
|---|---|---|---|---|
| None | .tar | Fastest | Largest | Debug/testing |
| XZ | .tar.xz | Slow | Best | Storage efficiency |
| Zstd | .tar.zst | Fast | Good | Daily backups |
| Gzip | .tar.gz | Medium | Medium | Compatibility |
| Pigz | .tar.gz | Fast | Medium | Faster gzip (multi-core) |
| Bzip2 | .tar.bz2 | Slow | Good | Legacy systems |
| LZMA | .tar.lzma | Slow | Good | Legacy systems |
Compression level and mode (fast/standard/slow) are configurable. Some algorithms rely on external binaries being available on the host (e.g., xz, zstd, pigz, lzma).
If AGE encryption is enabled, the final archive filename includes .age (streaming encryption).
Orchestrator
The Orchestrator coordinates the entire backup and restore workflow:
- Executes collection, compression, encryption, and storage phases
- Generates checksum and manifest metadata (and can bundle associated artifacts)
- Manages service start/stop during restore operations
- Implements retention policies (simple count or GFS)
- Handles errors and provides detailed logging
- Creates safety backups before restore operations
- Writes an end-of-run JSON stats report under
LOG_PATH
Storage
The Storage module manages backup distribution across multiple tiers:
- Primary (Local): Required. Backup is created here first
- Secondary: Optional. Copies to NAS or network mount
- Cloud: Optional. Uploads via rclone to any supported provider
Each tier has independent retention settings. Local storage failures are critical (abort backup), while secondary and cloud failures are non-critical (logged as warnings and reflected in status/exit code when applicable).
Encryption
The Encryption module provides AGE-based encryption:
- Algorithm: ChaCha20-Poly1305 (AEAD) with X25519 key exchange
- Streaming archive encryption: no unencrypted archive is left behind when encryption is enabled
- Multiple recipients: backup decryptable by any configured key
- Public-key recipients or passphrase-derived recipients are supported (configured via wizard /
AGE_RECIPIENT_FILE)
Notifications
The Notifications module sends backup status alerts:
- Telegram: Bot messages with backup summary (centralized or personal mode)
- Email: HTTPS relay or local sendmail (optional fallback supported)
- Gotify: Self-hosted push notifications
- Webhook: Custom endpoints (generic, discord, slack, teams formats; optional auth and headers)
Multiple channels can be enabled simultaneously for redundancy.