Restore Modes

ProxSave provides a guided restore workflow for both Proxmox VE (PVE) and Proxmox Backup Server (PBS). The restore is category-based: each mode selects a predefined set of categories, and ProxSave only applies what is present in the chosen backup bundle.

Restores write back to the system root (/) and require root privileges.

How to run restore (TUI vs CLI)

TUI (interactive screens):

proxsave --restore

CLI (text prompts):

proxsave --restore --cli

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

For troubleshooting, you can increase verbosity:

proxsave --restore --cli --log-level debug

Restore modes (what changes between them)

Mode choices are the same in TUI and CLI. If ProxSave cannot analyze the bundle contents (for example due to a broken archive), it falls back to a full archive extraction workflow.

In this fallback flow, ProxSave asks you to confirm by typing RESTORE (or 0 to cancel) and then extracts the whole archive to / (still applying the /etc/pve safety rule described below).

FULL mode (full)

Restores every available category found in the bundle for the detected system type (PVE or PBS).

Use when you need a full node rebuild, disaster recovery, or after a fresh OS reinstall.

STORAGE/DATASTORE mode (storage)

Restores storage/datastore definitions plus the related job configuration, without touching general node access settings.

Use when storage definitions or backup jobs are missing/broken but the OS/network layer is fine.

Selected categories (depending on system type and what exists in the bundle):

PVE: pve_cluster, storage_pve, pve_jobs, zfs
PBS: pbs_config, datastore_pbs, pbs_jobs, zfs

SYSTEM BASE mode (base)

Restores essential OS-level configuration for reachability and services.

Use when the node is reachable but misconfigured (network/SSH/SSL/service units), and you want a conservative restore that does not touch storage definitions or cluster/PBS database state.

Selected categories:

network, ssl, ssh, services

CUSTOM mode (custom)

Lets you choose individual categories interactively.

TUI: you can go back from category selection to mode selection.
CLI: you can toggle categories by number, then continue.

Use when you want a very selective restore (for example only network + ssl).

Important safety behavior (PVE: /etc/pve)

ProxSave intentionally never writes to /etc/pve when restoring to /.

If the bundle contains /etc/pve data (category pve_config_export), it is treated as export-only and extracted to a separate export directory under your base directory (for example pve-config-export-YYYYMMDD-HHMMSS).

This applies to all restore paths, including the full-archive fallback: /etc/pve is always exported/skipped and never overwritten directly.

Special handling: PVE cluster database (SAFE vs RECOVERY)

If ProxSave detects a cluster backup (manifest ClusterMode=cluster) and the restore plan includes pve_cluster, it asks how to proceed:

SAFE: do not write /var/lib/pve-cluster/config.db; export cluster files only.
RECOVERY: restore the full cluster database (/var/lib/pve-cluster). Use only when the cluster is offline/isolated to avoid split-brain.

In SAFE mode, ProxSave can optionally help you apply selected exported configs via pvesh (for example VM/CT configs for the current node, storage.cfg, and datacenter.cfg).

In RECOVERY mode, ProxSave stops key PVE services and attempts to unmount /etc/pve before restoring the cluster database.

Restore workflow (high level)

Select the backup source (local / secondary / cloud).
Pick a bundle.
Decrypt if needed (AGE).
Compatibility check (may prompt to continue).
Analyze categories and select restore mode (or select categories in CUSTOM).
(PVE cluster) Choose SAFE vs RECOVERY if applicable.
Show the restore plan.
Confirm restore (type RESTORE, or abort).
Create a safety backup for categories writing to system paths.
Apply restore and export-only extraction.
Recreate storage/datastore directories when relevant.
Print follow-up actions (service checks, ZFS checks, reboot recommendation).

Safety backups and logs

Safety backup (rollback)

Before overwriting files for non-export categories, ProxSave creates a tarball safety backup under:

/tmp/proxsave/restore_backup_YYYYMMDD_HHMMSS.tar.gz
The latest location is also saved to /tmp/proxsave/restore_backup_location.txt

If needed, ProxSave prints a rollback hint like:

tar -xzf /tmp/proxsave/restore_backup_YYYYMMDD_HHMMSS.tar.gz -C /

Detailed restore log

During selective extraction, ProxSave writes a detailed log under /tmp/proxsave/restore_YYYYMMDD_HHMMSS.log and prints its path.

Mode comparison (conceptual)

Mode	Network / SSL / SSH	PVE Cluster DB (/var/lib/pve-cluster)	Storage / Datastore	Jobs	Services	Notes
FULL	✓	✓ (SAFE/RECOVERY prompt when applicable)	✓	✓	✓	Complete restore
STORAGE/DATASTORE	✗	PVE only (included via pve_cluster)	✓	✓	limited	Focus on storage + jobs
SYSTEM BASE	✓	✗	✗	✗	✓	OS/access layer only
CUSTOM	depends	depends	depends	depends	depends	You select categories