Backups

The Backups page is your last line of defence against data loss, fat-finger drops, and disk failures. ProxPanel takes encrypted backups of the entire PostgreSQL database — subscribers, sessions, transactions, audit history, settings, the lot — plus uploaded assets (logo, login background, favicon). Backups are AES-256-GCM encrypted with a key derived from the license key, so even if someone exfiltrates a backup file they cannot read it without the license server’s cooperation.

The V2 backup format introduced in v1.0.208 embeds the source license key in the header so a backup made on Server A can be restored on Server B without you having to remember which license created it — the system fetches the right decryption key from the license server automatically.

How to get here

• Sidebar → Backups (database icon).
• Direct URL: /backups.

Admins by default. Resellers can be granted backups.view, backups.create, backups.restore, backups.delete independently — useful if you want a designated reseller to be able to take backups but not restore them.

Layout

Section	Purpose
Manual backup	One-click Create Backup Now.
Backup files	List of stored backups: filename, size, created_at, source license, validate, download, restore, delete.
Schedules	Cron-style schedules (daily/weekly/monthly), destinations, retention.
Restore from different server	Upload a backup taken elsewhere; the page auto-detects the source license and fetches the right key.

V1 vs V2 format

	V1	V2
Magic header	PROXPANEL_ENCRYPTED_BACKUP_V1\n	PROXPANEL_ENCRYPTED_BACKUP_V2\nLICENSE_KEY=PROXP-...\n
Encryption	AES-256-GCM	AES-256-GCM (unchanged)
Restore on same server	Yes	Yes
Restore on different server	Requires manually entering source license key	Auto-detected from header
Created by ProxPanel ≥ v1.0.208	No	Yes (default)

V2 is strictly an additive change — V1 backups still restore fine, you just have to type the source license key into the restore dialog. New backups are always V2.

Encryption details

encryptBackup:

1. Runs pg_dump to a temp SQL file.
2. Derives the AES-256 key from the license key via deriveEncryptionKey() — PBKDF2 with a fixed app salt (ProxPanel-AES256-Backup-2024).
3. Generates a fresh 12-byte GCM nonce per backup. The nonce is prepended to the ciphertext (standard AES-GCM convention).
4. Writes the magic header + ciphertext to the destination path with 0600 permissions.

The key is never written to disk. If the license server is unreachable for ~5 minutes during a backup attempt, the system falls back to the cached license key from memory; longer outages prevent fresh backups but do not affect already-stored ones.

Manual backup

Click Create Backup Now. The handler streams pg_dump, encrypts, and writes the result to /opt/proxpanel/backups/proisp_full_YYYYMMDD_HHMMSS.proisp.bak. A 30,000-subscriber database typically takes 30–60 seconds; you see a progress toast.

ValidateBackup confirms a backup is well-formed before you trust it:

1. Reads the magic header (V1 or V2).
2. Tries to decrypt the first 4 KB — if AES-GCM auth tag verification fails, the backup is corrupted or the key is wrong.
3. Confirms the decrypted stream starts with pg_dump headers.

Run Validate on any backup you intend to restore — better to find corruption now than during a real outage.

Scheduled backups

Schedules are configurable in the Schedules tab:

Field	Purpose
Name	Human-readable identifier.
Frequency	daily, weekly, monthly.
Day of week / day of month / time	When to run. Uses the panel’s configured timezone (tzdata mounted into the API container so Asia/Beirut etc. resolve).
Storage type	local, ftp, cloud.
Local path	If local.
FTP host/port/user/pass/path/passive/TLS	If ftp. Password stored encrypted; the UI masks it.
Retention	Keep last N backups per schedule; older ones are deleted automatically.

The scheduler runs every minute with a 2-minute window for cron matching, and same-day deduplication so a system restart in the middle of a backup minute doesn’t cause two backups.

Destinations

• Local — /opt/proxpanel/backups/ inside the container. Bind-mounted to /opt/proxpanel/backups/ on the host so you can copy files off via rsync if you want.
• FTP / FTPS — push the encrypted backup straight to an offsite FTP. Both plain FTP and FTPS (explicit TLS) are supported. Passive mode by default.
• Cloud — pushed to the license server’s tenant cloud storage. SaaS deployments use this by default so each tenant’s backups land in their own isolated bucket.

The encrypted file itself is byte-identical regardless of destination — the same backup can be downloaded from one destination and restored on a server in another data centre.

Restore

Restore:

1. Reads the file’s magic header. V2 → extracts the embedded LICENSE_KEY=.
2. If a Source License Key was supplied by the operator, that overrides the embedded one.
3. Calls the license server’s GET /api/v1/license/backup-password with the license key; receives the DB password used to encrypt this backup.
4. Decrypts to a temp SQL file. AES-GCM auth tag failure → bail with a clear error.
5. Stops the API, drops and recreates the database, restores the SQL, restarts the API.

If the license server is unreachable (e.g., during disaster recovery in an isolated network), you can still restore on the same server (uses local in-memory key). For cross-server restore you need license-server reachability.

Cross-server restore

The killer feature: download a backup from one server, upload to a different server (different license), click Restore. The system auto-detects everything.

The only gotcha for V1 backups: enter the source license key manually in the restore dialog. The UI hints at this with a green “auto-detected” message above the field — for V2 backups, the field can be left empty.

Note

Cross-server restore is the right move for: migrating between VPS providers, restoring after a server is destroyed, cloning production to staging, moving between data centres. It is not a license-bypass — both source and destination must have valid licenses, and the source license must still be active on the license server.

Validation before restore

Always click Validate before clicking Restore. Validation:

• Confirms the file is well-formed and the encryption key works.
• Costs ~1 second.
• Catches the 95% of failure modes (corrupted upload, wrong file, encryption mismatch) before they tear down your running database.

Common workflows

Take a one-off backup before a risky change

1. Click Create Backup Now.
2. Wait for the success toast. The new file appears at the top of the list.
3. Click Validate on it to confirm.
4. (Optional) Download to your laptop for off-site storage.
5. Now perform the risky change with confidence.

Set up a nightly off-site backup to FTP

1. Schedules → New Schedule.
2. Frequency = daily, time = 03:00.
3. Storage = ftp. Fill in your FTP host, credentials, target path. Tick passive mode and TLS if your FTP supports it.
4. Retention = 30 (keep the last 30 nightly backups).
5. Save. The first backup runs at the next 03:00; the FTP server gets the encrypted file each night.

Restore a backup on a fresh server after disaster

1. Stand up the new ProxPanel server with its own license activated.
2. Open Backups → Restore from different server.
3. Upload the V2 backup file. The page reads the header and shows the source license key it detected.
4. Click Validate to confirm decryption works against the source license.
5. Click Restore. The new server’s database is replaced with the source server’s snapshot. After ~1–2 minutes the panel is back up with all your data.

Permissions

Permission	What it gates
backups.view	Open the page and see the file list.
backups.create	Take manual backups.
backups.edit	Edit schedules.
backups.restore	Restore any backup.
backups.delete	Delete backup files.

Related pages

• Settings → Backups — global backup settings and retention defaults.
• Audit Logs — every backup, validate, restore, and delete is audited.
• Settings → License — backup encryption depends on the license key.
• Settings → Network — confirm the panel can reach the license server before scheduling backups.
• Reports — verify a restore worked by comparing report totals against the previous day.