ProxSave
Star on GitHub, it's really important Star on GitHub

Storage Backends

ProxSave supports up to three storage tiers. Backups are always created on primary (local) storage first. If enabled, ProxSave then copies/uploads the final artifact to secondary storage and/or cloud storage. Each tier has its own retention settings.

Tiers (overview)

Primary (local) #required
Secondary (mounted path) #optional
Cloud (rclone) #optional

Notes:

  • Primary storage is the only critical tier. If primary fails, the backup fails.
  • Secondary and cloud failures are non-fatal: the backup continues, and the run may end in warning status (exit code 1) depending on what failed.
  • When BUNDLE_ASSOCIATED_FILES=true, ProxSave can also create a single .bundle.tar artifact for easier copying/uploading.

Primary storage (local)

Primary storage is where archives are created.

BACKUP_PATH=/opt/proxsave/backup
LOG_PATH=/opt/proxsave/log

Disk thresholds (in GB):

MIN_DISK_SPACE_PRIMARY_GB=1

Retention (simple)

Simple retention keeps the most recent N backups in each tier:

RETENTION_POLICY=simple
MAX_LOCAL_BACKUPS=15

Local retention also attempts to delete associated local logs (when present under LOG_PATH) according to the same retention decisions.

Secondary storage (mounted filesystem)

Secondary storage is a filesystem path (commonly an NFS/CIFS/SMB mount). ProxSave will create the directory if missing, but it cannot mount it for you.

SECONDARY_ENABLED=true
SECONDARY_PATH=/mnt/nas/proxsave-backup
SECONDARY_LOG_PATH=/mnt/nas/proxsave-logs
MIN_DISK_SPACE_SECONDARY_GB=1

Important:

  • SECONDARY_PATH must be a mounted filesystem path (for example /mnt/nas/…), not a network address like 192.168.1.100/folder.
  • SECONDARY_LOG_PATH is optional. If empty, secondary log copy/cleanup is disabled for that run.

Retention (simple)

RETENTION_POLICY=simple
MAX_SECONDARY_BACKUPS=15

Cloud storage (rclone)

Cloud storage uploads backups via rclone to any supported provider.

CLOUD_ENABLED=true
CLOUD_REMOTE=gdrive                  # remote name or remote:path
CLOUD_REMOTE_PATH=proxsave/backups   # optional extra subdirectory
MIN_DISK_SPACE_CLOUD_GB=1

How the final remote path is built is explained in docs/docs_file/rclone_cloud_path.md.

Cloud logs (CLOUD_LOG_PATH)

You can optionally upload logs to cloud:

# New style: path-only, remote name taken from CLOUD_REMOTE
CLOUD_LOG_PATH=/proxsave/log

# Legacy style: explicit remote:path
# CLOUD_LOG_PATH=gdrive:/proxsave/log

If CLOUD_ENABLED=true but CLOUD_LOG_PATH is empty, cloud log copy/cleanup is disabled for that run.

Upload behavior (high level)

CLOUD_UPLOAD_MODE=parallel            # sequential | parallel
CLOUD_PARALLEL_MAX_JOBS=2
CLOUD_PARALLEL_VERIFICATION=true
RCLONE_TIMEOUT_CONNECTION=30
RCLONE_TIMEOUT_OPERATION=300
RCLONE_TRANSFERS=4
RCLONE_RETRIES=3
RCLONE_BANDWIDTH_LIMIT=
RCLONE_FLAGS=

Disk-space checks for cloud storage apply only when CLOUD_REMOTE is a local mount path. If it is an rclone remote (e.g. gdrive:), ProxSave skips the cloud disk-space check because there is no local filesystem to inspect.

Retention policy (GFS)

GFS (Grandfather-Father-Son) retention is enabled only when:

RETENTION_POLICY=gfs

Then configure how many backups to keep per tier:

RETENTION_DAILY=7
RETENTION_WEEKLY=4
RETENTION_MONTHLY=12
RETENTION_YEARLY=3

GFS is applied to all tiers uniformly. In this mode the MAX_*_BACKUPS limits are not used.

What gets stored per tier

Depending on bundling, ProxSave will store/copy/upload:

  • Without bundling (BUNDLE_ASSOCIATED_FILES=false): archive plus companion files when present (.sha256, .metadata, optional .metadata.sha256).
  • With bundling (BUNDLE_ASSOCIATED_FILES=true): a single .bundle.tar file (and ProxSave may still handle legacy raw files when present).

Listing operations show only “backup entries” and hide associated sidecar files.

Failure behavior (summary)

  • Primary failures abort the run and result in failure.
  • Secondary/cloud failures are non-fatal; they are logged and the run continues. They may still contribute to a warning outcome (exit code 1), which is reflected in notifications.

Disk-space checks

ProxSave checks free space before the run starts, and may also validate disk space against the estimated data size after collection. It does not run retention “first” to free space for the current run: if primary storage fails the disk-space checks, the backup aborts.