Decryption

ProxSave provides an interactive decryption workflow for AGE-encrypted backups.

It is meant for cases where you want to generate a decrypted bundle you can inspect or move elsewhere. If your goal is to restore configuration, use --restore instead: it can decrypt as part of the restore workflow.

Run decryption (TUI vs CLI)

TUI (interactive screens):

proxsave --decrypt

CLI (text prompts):

proxsave --decrypt --cli

For troubleshooting:

proxsave --decrypt --cli --log-level debug

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

What --decrypt does (output)

The decryption workflow produces a decrypted bundle (a .tar file) in your chosen destination directory.

• Default destination directory: BASE_DIR/decrypt (or ./decrypt if BASE_DIR is not set)
• Output filename: *.decrypted.bundle.tar

The decrypted bundle contains:

• the decrypted archive (for example hostname-backup-YYYYMMDD-HHMMSS.tar.xz)
• a regenerated metadata file (.metadata) with EncryptionMode=none
• a regenerated checksum file (.sha256) for the decrypted archive

ProxSave performs decryption in a temporary directory under /tmp/proxsave and only moves the final decrypted bundle into your destination directory.

Workflow overview

1) Select backup source

ProxSave lists backup sources based on your configuration (local/secondary paths and optional cloud/rclone remotes).

For cloud remotes, ProxSave reads bundle metadata via rclone cat and downloads the selected bundle to a temporary location before decrypting.

2) Select backup

--decrypt only lists backups marked as encrypted in their metadata (manifest EncryptionMode=age).

3) Provide decryption secret

In CLI mode, ProxSave prompts:

• Paste an AGE X25519 secret key (AGE-SECRET-KEY-…), or
• Enter the same passphrase used during ProxSave’s passphrase-based recipient setup.

Notes:

• Input is not echoed.
• 0 aborts the workflow.
• If the key/passphrase does not match the archive, ProxSave asks again.

4) Choose destination directory

ProxSave asks where to write the decrypted bundle. It will ask before overwriting existing files.

Extracting and inspecting the decrypted bundle

List bundle contents:

tar -tf backup.decrypted.bundle.tar

Extract the bundle:

mkdir -p /tmp/proxsave-decrypt-out
tar -xf backup.decrypted.bundle.tar -C /tmp/proxsave-decrypt-out

Then inspect/extract the decrypted archive:

tar -tf /tmp/proxsave-decrypt-out/hostname-backup-YYYYMMDD-HHMMSS.tar.xz
tar -xf /tmp/proxsave-decrypt-out/hostname-backup-YYYYMMDD-HHMMSS.tar.xz -C /tmp/extracted

If your tar does not auto-detect compression, use the matching flag (example: -J for .xz).

Decrypting with standard AGE tools

ProxSave uses the standard AGE file format, so X25519-key encrypted archives can be decrypted with age:

age --decrypt -i /path/to/key.txt backup.tar.xz.age > backup.tar.xz

Important limitation:

• ProxSave’s built-in decrypt workflow accepts only AGE X25519 secret keys and the ProxSave passphrase method. If you encrypted a backup using SSH recipients, use the age CLI with your SSH private key to decrypt it.

Troubleshooting

“Provided key or passphrase does not match this archive”

• Ensure you are using the correct AGE-SECRET-KEY-... line (X25519 identity), or the exact passphrase used during ProxSave recipient setup.
• If multiple recipients were configured, any matching identity is sufficient.

No encrypted backups found

• --decrypt only lists backups with EncryptionMode=age. Plain (non-encrypted) backups are intentionally excluded.

Cloud download failures

• Verify rclone is installed and the remote is reachable.
• Re-run with --log-level debug to see the failing rclone command output.