Backup and Restore¶

Section: Operations | Article 39
Audience: System Administrators
Last Updated: 2026-04-08

Overview¶

RP-PAM stores critical data in three locations: the database, the configuration file, and the encryption key material. All three must be backed up together to ensure a successful restore. A backup from one component without the others is useless — encrypted vault data cannot be decrypted without the matching encryption keys.

This article covers automated and manual backups, offsite storage, and full restore procedures for both single-node and HA deployments.

What to Back Up¶

Component	Location (Windows)	Location (Linux)	Why It Matters
Database	MSSQL instance or local `.bak`	PostgreSQL instance or `pg_dump`	All user data, vault entries (encrypted), audit logs, workflow state
Configuration	`C:\ProgramData\Ravenphyre\RP-PAM\rppam.config`	`/etc/rppam/rppam.config`	Node identity, connection strings, cluster settings, all feature configuration
Encryption keys (KEK)	`C:\ProgramData\Ravenphyre\RP-PAM\Keys\`	`/var/lib/rppam/keys/`	Key Encryption Keys that protect vault DEKs. Without these, vault credentials cannot be decrypted.
JWT signing key	`C:\ProgramData\Ravenphyre\RP-PAM\Keys\jwt-signing.key`	`/var/lib/rppam/keys/jwt-signing.key`	RSA private key for signing authentication tokens
TLS certificates	`C:\ProgramData\Ravenphyre\RP-PAM\Certs\`	`/var/lib/rppam/certs/`	Service certificates issued by Step-CA
License file	`C:\ProgramData\Ravenphyre\RP-PAM\license.jwt`	`/etc/rppam/license.jwt`	Your RP-PAM license token
Module configurations	`C:\ProgramData\Ravenphyre\RP-PAM\Modules\`	`/var/lib/rppam/modules/`	Module registration, per-module settings, custom module packages

Critical: The encryption keys directory (Keys/) is the most important backup target after the database. If you lose the KEK files and do not have a backup, all vault credentials are permanently unrecoverable.

The backup tool handles all of this automatically. When you run rppam-backup now, every component listed above is included in the encrypted archive. You do not need to back up these items individually.

Using the Backup Tool¶

RP-PAM includes a unified backup and restore tool that handles all components in a single operation. It produces a single AES-256-GCM encrypted .rppam-backup archive containing everything needed for a full restore.

Two ways to back up:

Backup & Restore GUI (Windows): Launch from the Start Menu → RP-PAM Backup & Restore. Visual interface with Backup Now, Restore, Schedule, History, Verify, and Storage Management tabs.
Command line (Windows PowerShell or Linux bash): Use the rppam-backup commands shown below. Ideal for automation and scripting.

Available Commands¶

Command	Description
`rppam-backup now`	Run a full backup immediately
`rppam-backup restore --file <path>`	Restore from an encrypted backup archive
`rppam-backup list`	Show backup history
`rppam-backup verify --file <path>`	Verify a backup archive's integrity without restoring
`rppam-backup schedule`	Create a scheduled automated backup

Running a Backup¶

Windows PowerShell:

# Full backup to the default backup directory
.\rppam-backup.ps1 now

# Full backup with offsite copy
.\rppam-backup.ps1 now -OffsitePath "\\fileserver\backups\rppam"

Linux:

# Full backup to the default backup directory
sudo /opt/rppam/tools/rppam-backup.sh now

# Full backup with offsite copy
sudo /opt/rppam/tools/rppam-backup.sh now --offsite /mnt/nas/rppam-backups

# Full backup with S3 offsite copy
sudo /opt/rppam/tools/rppam-backup.sh now --offsite s3://my-bucket/rppam-backups

What the Backup Tool Does¶

[1/7] Backing up database............. OK
  - Full database dump (MSSQL .bak or PostgreSQL pg_dump)

[2/7] Backing up configuration........ OK
  - rppam.config

[3/7] Backing up encryption keys...... OK
  - CEK export, KEK files

[4/7] Backing up JWT signing key...... OK
  - RSA private key for session tokens

[5/7] Backing up TLS certificates..... OK
  - Service certificates and CA trust store

[6/7] Backing up license.............. OK
  - License JWT file

[7/7] Backing up module configs....... OK
  - Module registration and configuration files

Encrypting backup archive (AES-256-GCM)...
Backup complete.
  File:     /var/lib/rppam/backups/rppam-backup-20260406-020015.rppam-backup
  Size:     247 MB
  Contains: Database, config, keys, certs, license, modules
  Retained: 7 most recent backups

Recovery Password¶

On the first backup, the tool generates a cryptographically strong recovery password and displays it in a prominent banner:

╔══════════════════════════════════════════════════════════════╗
║          BACKUP RECOVERY PASSWORD — SAVE THIS NOW          ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  Password:  aB3xK9mP2vL7nQ5wR8tY1uF4hJ6sD0g  ║
║                                                              ║
║  This password will NOT be shown again.                      ║
║  Store it in a password manager, print it, or write it down. ║
║  Without this password, backups CANNOT be restored.          ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

You must type YES to confirm you have saved the password before the backup proceeds. The password is never stored on the server — only a salted hash is kept for verification. All subsequent backups prompt you to enter the same password.

Store the recovery password separately from the backup files. If you store them together, anyone who obtains the backup can decrypt it. Use your organisation's password manager or a sealed envelope in a secure location.

Primary-Only Enforcement¶

The backup tool refuses to run on standby nodes. This prevents conflicting backups from different nodes and ensures the backup always contains the most current data from the leader.

If you attempt to run a backup on a standby node:

ERROR: This node (node2) is a standby. Backups must be taken from the primary node (node1).
       Connect to the primary node and run the backup from there.

In a local-sync deployment, the primary node always has the most recent committed data (all writes must reach quorum before the primary acknowledges them). Backing up from the primary guarantees you capture every committed transaction.

Scheduling Automatic Backups¶

The backup tool has a built-in scheduling command that creates the appropriate scheduled task (Windows) or cron job (Linux) for you.

Windows PowerShell:

# Schedule daily backups at 2:00 AM
.\rppam-backup.ps1 schedule -Daily -At "02:00"

# Schedule weekly backups on Sunday at 3:00 AM
.\rppam-backup.ps1 schedule -Weekly -At "Sun 03:00"

This creates a Windows Scheduled Task named "RP-PAM Automated Backup" that runs under the SYSTEM account. You can view or modify it in Task Scheduler.

Linux:

# Schedule daily backups at 2:00 AM
sudo /opt/rppam/tools/rppam-backup.sh schedule --daily --at 02:00

# Schedule weekly backups on Sunday at 3:00 AM
sudo /opt/rppam/tools/rppam-backup.sh schedule --weekly --at "Sun 03:00"

This creates a cron job for the root user. View it with sudo crontab -l.

Note: Scheduled backups use --force to skip the interactive leader check. Ensure the schedule is only active on the primary node, or that your HA cluster handles this through leader-gated scheduling.

Offsite Backup Configuration¶

The backup tool can automatically copy completed backups to an offsite location for disaster recovery.

Supported Offsite Destinations¶

Destination	Flag	Example
UNC path (Windows share)	`--offsite-path`	`\\fileserver\backups\rppam`
Amazon S3	`--offsite-s3`	`s3://my-bucket/rppam-backups/`
Local/NFS path	`--offsite-path`	`/mnt/nas/rppam-backups/`

.\rppam-backup.ps1 now -OffsitePath "\\fileserver.corp.local\backups\rppam"

The backup tool copies the completed archive to the UNC path after the local backup succeeds. Ensure the computer account (or service account running RP-PAM) has write permissions to the UNC share.

Amazon S3¶

sudo /opt/rppam/tools/rppam-backup.sh now \
  --offsite s3://my-pam-backups/rppam/

The tool uses the AWS CLI (aws s3 cp) to upload the archive. Ensure the AWS CLI is installed and configured with credentials that have write access to the bucket. For production, use an IAM role instead of access keys when running on EC2.

Local / NFS Path¶

sudo /opt/rppam/tools/rppam-backup.sh now \
  --offsite /mnt/nas/rppam-backups/

Ensure the NFS mount is active and writable before running the backup.

Restore Procedure¶

Before You Start¶

Identify the backup to restore. Use the most recent healthy backup.
Locate the archive password. You will need the recovery password that was displayed when you ran your first backup. The tool will prompt you to enter it.
Ensure RP-PAM is stopped on the server where you are restoring.
For HA clusters: Restore on the primary node only. Standby nodes will re-sync automatically.

Step-by-Step Restore¶

The restore tool handles stopping the service, decrypting the archive, restoring all components, validating the schema, and restarting the service in one command.

Windows PowerShell:

# Full restore — restores everything (database, config, keys, certs, license, modules)
.\rppam-backup.ps1 restore -BackupFile "C:\Backups\rppam-backup-20260406-020015.rppam-backup"

# Restore only the database (leaves config and keys untouched)
.\rppam-backup.ps1 restore -BackupFile "C:\Backups\rppam-backup-20260406-020015.rppam-backup" -DatabaseOnly

# Restore only the configuration file
.\rppam-backup.ps1 restore -BackupFile "C:\Backups\rppam-backup-20260406-020015.rppam-backup" -ConfigOnly

# Restore only encryption keys and JWT signing key
.\rppam-backup.ps1 restore -BackupFile "C:\Backups\rppam-backup-20260406-020015.rppam-backup" -KeysOnly

Linux:

# Full restore
sudo /opt/rppam/tools/rppam-backup.sh restore \
  --file /var/lib/rppam/backups/rppam-backup-20260406-020015.rppam-backup

# Restore only the database
sudo /opt/rppam/tools/rppam-backup.sh restore \
  --file /var/lib/rppam/backups/rppam-backup-20260406-020015.rppam-backup \
  --database-only

# Restore only the configuration
sudo /opt/rppam/tools/rppam-backup.sh restore \
  --file /var/lib/rppam/backups/rppam-backup-20260406-020015.rppam-backup \
  --config-only

# Restore only encryption keys
sudo /opt/rppam/tools/rppam-backup.sh restore \
  --file /var/lib/rppam/backups/rppam-backup-20260406-020015.rppam-backup \
  --keys-only

The tool will prompt for your recovery password. It then performs these steps automatically:

[1/6] Stopping RP-PAM service........ OK
[2/6] Restoring database............. OK
  - MSSQL: RESTORE DATABASE ... WITH REPLACE
  - PostgreSQL: pg_restore
[3/6] Restoring configuration........ OK
  - rppam.config written to correct location
[4/6] Restoring encryption keys...... OK
  - CEK, KEK files, JWT signing key restored
[5/6] Restoring certs, license, modules.. OK
  - TLS certificates, license JWT, module configs
[6/6] Validating and starting........ OK
  - Schema validation via rppam-migrate
  - Service started and health checked

Restore complete.
  Standby nodes will catch up automatically via DatabaseSyncService.

Restore and Replicate (local-sync Mode)¶

If your HA cluster uses local-sync database mode, restoring a backup on the primary node does not automatically update the standby nodes' local databases. You must trigger a full re-sync.

Procedure¶

Restore on the primary node using the standard restore procedure above.

Stop all standby nodes:

Windows:

# On each standby node
Stop-Service RpPam

Linux:

# On each standby node
sudo systemctl stop rppam

Trigger a full re-sync from the primary:

Windows:

& "C:\Program Files\Ravenphyre\RP-PAM\tools\rppam-cluster.exe" resync `
  --from node1 `
  --to all `
  --full

Linux:

sudo /opt/rppam/tools/rppam-cluster resync \
  --from node1 \
  --to all \
  --full

Start standby nodes one at a time:

# On each standby node
sudo systemctl start rppam

Verify cluster health:

curl -s http://localhost:7101/system/health/cluster \
  -H "Authorization: Bearer $ADMIN_JWT" | jq .

All nodes should show "status": "healthy" and "quorumMet": true.

Important: Do not start standby nodes before the resync completes. Starting a standby with stale data while the primary has restored data can cause replication conflicts.

For external-shared mode, standby nodes automatically pick up the restored database because they connect to the same external database server. No resync step is needed.

After a Full Rebuild: License Rebinding¶

If you are restoring RP-PAM onto a new server (different hardware or VM) rather than the same server, the license must be rebound to the new machine. RP-PAM licenses are tied to a node fingerprint that includes hardware identifiers.

When Rebinding Is Required¶

Scenario	Rebinding Required?
Restore to the same server (same hardware)	No
Restore to a new VM on the same hypervisor	Yes
Restore to completely different hardware	Yes
Restore after OS reinstall on the same hardware	Usually no (hardware IDs unchanged)
Restore in a DR failover to a pre-registered DR node	No (DR node was already registered)

Rebinding Procedure¶

Step 1: Import your existing license on the new server

Windows:

& "C:\Program Files\Ravenphyre\RP-PAM\tools\rppam-setup.exe" import-license `
  --file "C:\ProgramData\Ravenphyre\RP-PAM\license.jwt"

Linux:

sudo /opt/rppam/tools/rppam-setup import-license \
  --file /etc/rppam/license.jwt

Step 2: Request a rebind from Ravenphyre

The import command will detect the fingerprint mismatch and display a rebind request code:

License fingerprint mismatch detected.
Current node fingerprint: ABCD-1234-EFGH-5678
Licensed fingerprint:     WXYZ-9876-IJKL-5432

Rebind request code: eyJhbGciOiJSUzI1NiIs...

Submit this code to Ravenphyre support or your license portal to receive an updated license.

Step 3: Submit the rebind request

Online: Contact support@ravenphyre.net with the rebind request code for license rebinding.
Offline / Air-gapped: Contact your Ravenphyre account representative with the rebind request code. They will issue an updated license file.

Step 4: Import the updated license

# Windows
& "C:\Program Files\Ravenphyre\RP-PAM\tools\rppam-setup.exe" import-license `
  --file "C:\Downloads\updated-license.jwt"

# Linux
sudo /opt/rppam/tools/rppam-setup import-license \
  --file /tmp/updated-license.jwt

Step 5: Restart RP-PAM

Restart-Service RpPam    # Windows

sudo systemctl restart rppam    # Linux

Backup Retention Best Practices¶

Environment	Local Retention	Offsite Retention	Backup Frequency
Small (single node)	7 days	30 days	Daily
Medium (2-node HA)	14 days	90 days	Daily
Large (3+ nodes)	14 days	90 days	Daily + hourly transaction log backups
Regulated (SOX, PCI)	30 days	365 days	Daily + hourly transaction log backups

Cleaning Up Old Local Backups¶

Windows:

# Delete local backups older than 14 days
Get-ChildItem "C:\Backups\*.rppam-backup" |
  Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-14) } |
  Remove-Item -Force

Linux:

# Delete local backups older than 14 days
find /var/backups/rppam/ -name "*.rppam-backup" -mtime +14 -delete

Verifying Backup Integrity¶

You can verify a backup without restoring it. The verify command decrypts the archive, checks the manifest, and reports on each component.

Windows:

.\rppam-backup.ps1 verify -BackupFile "C:\ProgramData\Ravenphyre\RP-PAM\Backups\rppam-backup-20260406-020015.rppam-backup"

Linux:

sudo /opt/rppam/tools/rppam-backup.sh verify \
  --file /var/lib/rppam/backups/rppam-backup-20260406-020015.rppam-backup

The tool prompts for your recovery password, then displays:

  Decryption: PASS
  Manifest:   PASS
    Date:     2026-04-06T02:00:15+00:00
    Host:     pam-node1
    Engine:   postgresql
    database: 1 file(s)
    config: 1 file(s)
    keys: 3 file(s)
    jwt: 1 file(s)
    certs: 2 file(s)
    license: 1 file(s)
    modules: 4 file(s)

Verification: PASS — backup is valid and decryptable.

Listing Backup History¶

Windows:

.\rppam-backup.ps1 list

Linux:

sudo /opt/rppam/tools/rppam-backup.sh list

Output:

FILENAME                                       SIZE       DATE
─────────────────────────────────────────────  ──────────  ────────────────────
rppam-backup-20260408-020015.rppam-backup       251.3 MB  2026-04-08 02:00:15
rppam-backup-20260407-020012.rppam-backup       249.8 MB  2026-04-07 02:00:12
rppam-backup-20260406-020015.rppam-backup       247.2 MB  2026-04-06 02:00:15

Total: 3 backups (retaining 7)

Recommendation: Run rppam-backup verify on your offsite copies monthly to confirm they are not corrupted.

Troubleshooting¶

Problem	Likely Cause	Solution
"This node is a standby"	Running backup on a non-primary node	Connect to the primary node and run the backup there
"Archive password incorrect"	Wrong password or corrupted file	Try the correct password; re-download from offsite if file is corrupted
"Database restore failed"	Database engine version mismatch	Ensure the target database engine is the same version or newer than the source
"KEK file missing from archive"	Backup was taken before KEK was generated	This backup cannot decrypt vault data; use a newer backup
"Fingerprint mismatch" after restore	Restoring onto different hardware	Follow the license rebinding procedure above
Standby nodes show stale data after restore	Local-sync mode requires manual resync	Run `rppam-cluster resync --full` from the primary

Next Steps¶

Upgrading RP-PAM (rppkg patches) — Apply patches after verifying your backup
HA Multi-Node Setup — Understand cluster topology for backup planning
Break-Glass Emergency Access — Emergency access if the restore process requires it

Backup and Restore¶

Overview¶

What to Back Up¶

Using the Backup Tool¶

Available Commands¶

Running a Backup¶

What the Backup Tool Does¶

Recovery Password¶

Primary-Only Enforcement¶

Scheduling Automatic Backups¶

Offsite Backup Configuration¶

Supported Offsite Destinations¶

UNC Path (Windows Network Share)¶

Amazon S3¶

Local / NFS Path¶

Restore Procedure¶

Before You Start¶

Step-by-Step Restore¶

Restore and Replicate (local-sync Mode)¶

Procedure¶

After a Full Rebuild: License Rebinding¶

When Rebinding Is Required¶

Rebinding Procedure¶

Backup Retention Best Practices¶

Cleaning Up Old Local Backups¶

Verifying Backup Integrity¶

Listing Backup History¶

Troubleshooting¶

Next Steps¶