Workflow Overview

ProxSave follows a mostly sequential pipeline for backup creation and distribution. Each phase completes before the next begins; some internal operations (e.g., cloud upload parallelism) may run concurrently depending on configuration.

Backup Workflow

Phase 0: Initialization and cleanup

Before starting a new run, ProxSave prepares a temporary workspace under /tmp/proxsave, initializes logging, and performs unified cleanup of artifacts from previous executions (e.g., old JSON stats and orphaned temp directories).

Phase 1: Collection

The collector gathers files from configured sources:

/etc/pve/                    → Cluster config, VM/CT configs
/var/lib/pve-cluster/        → config.db (cluster database)
/etc/proxmox-backup/         → PBS configuration
/etc/network/                → Network interfaces
/etc/pve/firewall/           → Firewall rules
/etc/ssl/                    → SSL certificates
/root/.ssh/                  → SSH keys
/etc/cron.d/                 → Cron jobs
/etc/systemd/system/         → Custom services

Files are validated for existence and readability. Missing optional files are skipped.

Phase 2: Archiving (compression, optional encryption)

Collected files are packaged into a compressed tar archive:
<hostname>-backup-YYYYMMDD-HHMMSS.tar.<algo>

Compression runs with configurable algorithm and level.

If AGE encryption is enabled, the archive is written directly as an encrypted file (streaming mode):
<hostname>-backup-YYYYMMDD-HHMMSS.tar.<algo>.age

Phase 3: Verification and metadata

After the archive is created, ProxSave generates:

A SHA256 checksum file: <archive>.sha256
A JSON manifest: <archive>.manifest.json
A legacy-compatible metadata alias: <archive>.metadata (copy of the manifest)

Note: for encrypted archives, verification is limited (the archiver skips plaintext verification), but checksum and manifest are still generated.

Phase 4: Optional bundling

If BUNDLE_ASSOCIATED_FILES=true, ProxSave creates a single tar bundle and removes the raw artifacts:
<archive>.bundle.tar

The bundle contains the archive plus its companion files (.sha256, .metadata, and optionally .metadata.sha256 when present).

Phase 5: Primary (local) storage and retention

The archive (or bundle) is created in BACKUP_PATH (primary storage). Retention is then applied according to your configured policy (simple or GFS).

Typical outputs in BACKUP_PATH depend on bundling:

Without bundling:

<archive>
<archive>.sha256
<archive>.manifest.json
<archive>.metadata
(optional) <archive>.metadata.sha256

With bundling:

<archive>.bundle.tar

Phase 6: Secondary storage (optional)

If secondary storage is enabled, ProxSave copies the final artifact (raw archive or bundle) and applies retention independently for that tier.

Phase 7: Cloud storage (optional)

If cloud storage is enabled, rclone uploads files:
CLOUD_REMOTE:CLOUD_REMOTE_PATH/
└── <final artifact> (raw archive or bundle)

Upload modes: parallel (faster) or sequential (lower resource usage).

Phase 8: Notifications

Backup status is sent to configured channels (Telegram, Email, Gotify, Webhook).
Notifications are dispatched only in real runs (not in --dry-run).

Phase 9: Logs and stats report

At the end of the run, ProxSave writes a JSON stats report under LOG_PATH:
LOG_PATH/backup-stats-YYYYMMDD-HHMMSS.json
It also closes the active log and may copy logs to secondary/cloud destinations if configured.

Failure Handling

Phase	On Failure
Collection / config validation	Abort on errors returned by the collector or invalid configuration (missing optional files are typically skipped with warnings)
Archiving / compression / encryption	Abort backup
Verification / manifest	Abort backup
Primary (local) storage	Abort backup (primary storage is critical)
Secondary storage	Warning only, continue
Cloud storage	Warning only, continue
Notifications	Warning only, complete

Primary (local) storage is the only critical tier. Secondary and cloud failures do not prevent the backup from completing, but they can contribute to a warning exit code.

Dry-run behavior

When --dry-run (or DRY_RUN=true) is enabled, ProxSave validates configuration and simulates the workflow, but it does not create archives, does not dispatch to storage targets, and does not send notifications.

Restore Workflow

Select backup source (local, secondary, or cloud)
Download if from remote storage
Decrypt if encrypted (using configured key/passphrase as applicable)
Select restore mode (Full, Storage, Base, Custom)
Create safety backup of files to be overwritten
Extract selected categories to filesystem
Restart affected services if needed