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

Migration Tool

ProxSave includes a built-in environment migration tool that helps you move from a legacy Bash backup.env to the current Go backup.env template.

It works by merging legacy key/value pairs into a target configuration:

  • if the target file exists, it uses it as the base and updates only known keys
  • otherwise, it uses the embedded default template

Full mapping/background: docs/MIGRATION_GUIDE.md.

Commands (dry-run vs apply)

Dry-run (no files modified):

proxsave --env-migration-dry-run

Apply migration (writes the target config):

proxsave --env-migration

If the command proxsave is not available directly in your terminal, use the full path to the binary (example: /opt/proxsave/build/proxsave).

Selecting the target config

The migration tool writes to the config path provided by --config/-c (default is ./configs/backup.env, resolved relative to ProxSave base directory).

Example:

proxsave --env-migration --config ./configs/backup.env

Selecting the legacy source (--old-env)

If you don’t pass --old-env, ProxSave prompts for the legacy path (this requires an interactive terminal).

To run without prompts, always specify:

proxsave --env-migration --old-env /path/to/legacy/backup.env

When prompting, ProxSave tries common defaults like:

  • /opt/proxsave/env/backup.env
  • /opt/proxmox-backup/env/backup.env

What the dry-run prints

The dry-run output is a mapping-oriented summary:

  • target file path
  • mapped legacy keys (shown as NEW_KEY <- LEGACY_KEY)
  • legacy keys that were not mapped and require manual review
  • whether Ceph collection would be automatically disabled

How keys are migrated (behavior)

The migrator processes legacy KEY=VALUE pairs (comments are ignored).

Then, for each key in the target template/config:

  1. If the same key exists in the legacy file, it copies the legacy value.
  2. Otherwise it applies a small set of mapping rules for renamed keys (for example LOCAL_BACKUP_PATH → BACKUP_PATH).
  3. If neither matches, it keeps the existing value in the base template/config.

Finally, any legacy keys not used by steps (1) or (2) are listed as “manual review” keys.

Automatic Ceph handling

During migration, ProxSave can automatically set BACKUP_CEPH_CONFIG=false when it can’t detect any Ceph configuration on the node (unless the legacy file already explicitly disabled it).

This is reported in both dry-run and apply output so you can override it if needed.

Safety and rollback

If the target config already exists, ProxSave creates a backup before overwriting it:

  • configs/backup.env.migration-backup.YYYYMMDD_HHMMSS

After writing, ProxSave reloads and validates the migrated config. If validation fails, it automatically rolls back to the previous file.

After migration (recommended steps)

  1. Review the generated backup.env (paths, retention, notifications, encryption settings).
  2. Run a dry-run to validate the configuration:
proxsave --dry-run
  1. Run the first real backup and verify the results/logs.