Customize Settings

ProxSave is configured through configs/backup.env. The file is intentionally verbose so you can tune what gets collected, how archives are built, and how distribution behaves.

If you upgraded and your backup.env is missing new keys, run:

proxsave --upgrade-config

Collector toggles

You can enable/disable individual collection sources in backup.env. A few common examples:

# PVE-specific
BACKUP_CLUSTER_CONFIG=true      # Cluster config (/etc/pve, config.db, corosync)
BACKUP_PVE_FIREWALL=true        # Firewall rules under /etc/pve/firewall

# PBS-specific
BACKUP_DATASTORE_CONFIGS=true   # /etc/proxmox-backup (datastores, jobs, etc.)
BACKUP_USER_CONFIGS=true        # PBS users/tokens/ACLs (where applicable)

# System (common)
BACKUP_NETWORK_CONFIGS=true     # /etc/network (interfaces, DNS)
BACKUP_APT_SOURCES=true         # /etc/apt sources
BACKUP_CRON_JOBS=true           # /etc/cron.d and user/system crontabs
BACKUP_SYSTEMD_SERVICES=true    # /etc/systemd/system
BACKUP_SSL_CERTS=true           # SSL certificates
BACKUP_SSH_KEYS=true            # SSH configuration and keys
BACKUP_ZFS_CONFIG=true          # ZFS pool/dataset configuration
BACKUP_ROOT_HOME=true           # /root dotfiles (when enabled)
BACKUP_CRITICAL_FILES=true      # Selected critical system files

The default template contains many more toggles (PVE jobs/schedules/replication, PBS sync/prune/verify jobs, inventories, scripts, etc.). Use it as the authoritative reference for available options.

Custom backup paths

Add arbitrary files or directories to the backup:

# One entry per line inside the quotes
CUSTOM_BACKUP_PATHS="
/root/.config/rclone/rclone.conf
/opt/myapp/config.json
/etc/custom-app/
/var/lib/myservice/data.db
"

Each path is collected if it exists. Missing paths are skipped with a warning.

Exclusions (patterns and blacklist)

There are two complementary mechanisms:

BACKUP_EXCLUDE_PATTERNS: glob patterns (applied while collecting files).
BACKUP_BLACKLIST: explicit paths/patterns you never want to collect (one per line).

Patterns support standard globs (*, ?, []) and also ** for “any directories” matching.

# Comma/newline separated patterns
BACKUP_EXCLUDE_PATTERNS=*.log, *.tmp, **/cache/**, **/.git/**, **/__pycache__/**

# One entry per line inside the quotes
BACKUP_BLACKLIST="
/root/.cache
/var/tmp
"

Compression

Compression is controlled by these keys:

# Supported values: none | gz | pigz | bz2 | xz | lzma | zst
# zst = zstd compression (creates .tar.zst archives)
COMPRESSION_TYPE=xz

# gzip/pigz/bz2: 1-9, xz/lzma: 0-9, zst: 1-22
COMPRESSION_LEVEL=6

# fast | standard | maximum | ultra
COMPRESSION_MODE=standard

# 0 = auto, >0 forces a fixed number of threads (format-dependent)
COMPRESSION_THREADS=0

Practical defaults:

Daily runs: COMPRESSION_TYPE=zst with a moderate level (e.g. 3–6)
Long-term archiving: COMPRESSION_TYPE=xz with a moderate level (e.g. 6)

Some formats rely on external binaries being installed (for example xz, zstd, pigz, lzma).

Bundle mode

If you want a single file to move across tiers, enable bundling:

BUNDLE_ASSOCIATED_FILES=true

This creates <archive>.bundle.tar which contains:

The archive (.tar.* or .tar.*.age)
<archive>.sha256
<archive>.metadata (legacy-compatible manifest alias)
Optional <archive>.metadata.sha256 when present

Bundling is convenient for cloud storage targets because you upload/copy a single file.

System root prefix

For testing or chroot environments, redirect all collection paths:

SYSTEM_ROOT_PREFIX=/mnt/snapshot-root

This prepends the prefix to all collection paths (e.g. /etc/pve becomes /mnt/snapshot-root/etc/pve).

Archive naming

Archives are named automatically using the system hostname:

<hostname>-backup-YYYYMMDD-HHMMSS.tar.<ext>

If you need a different prefix, change the system hostname (recommended) or rename the output artifact after creation.

After changing settings

Validate configuration first:

proxsave --dry-run

If troubleshooting, rerun with debug logging:

proxsave --log-level debug