Upgrading RP-PAM — Major Versions¶

Section: Operations | Article 41
Audience: System Administrators
Last Updated: 2026-04-07

Understanding Major Upgrades¶

Major version upgrades replace the entire RP-PAM installation with a new version. Unlike .rppkg patch updates (which replace only changed components), a major upgrade installs new binaries, updates the database schema, and may introduce breaking changes.

Attribute	Patch (.rppkg)	Major Upgrade (MSI/deb/rpm)
Package format	`.rppkg`	`.msi` (Windows), `.deb` (Debian/Ubuntu), `.rpm` (RHEL/Fedora)
What changes	Only changed components	All binaries replaced
Schema migrations	Incremental	May include major schema changes
Downtime	Minimal to zero	Full restart required (5-15 minutes)
Rollback	Automatic	Manual (restore from backup)
Frequency	As needed	Quarterly

For patch updates, see Upgrading RP-PAM — Patch Updates (.rppkg).

Before You Start¶

1. Read the Release Notes¶

Every major release includes release notes that document: - Breaking changes and required configuration updates - New features and changed behaviors - Minimum supported database versions - Migration notes specific to this version

2. Back Up Everything¶

This is critical. Major upgrades cannot be automatically rolled back. You must have a working backup that includes the database, configuration, encryption keys, certificates, license, and module configurations.

Use the built-in backup tool to create a complete encrypted backup in one command:

Windows PowerShell:

.\rppam-backup.ps1 now

Linux:

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

This creates an AES-256-GCM encrypted .rppam-backup archive containing everything needed for a full rollback. See Backup and Restore for full details.

Verify the backup before proceeding. Run rppam-backup verify to confirm the archive is valid and decryptable. Do not proceed with the upgrade until you have confirmed a valid backup exists.

3. Check System Requirements¶

Review System Requirements for the new version. Major releases may increase minimum requirements for: - .NET runtime version - Database engine version - Operating system version - Disk space

4. Schedule Downtime¶

Plan for 10-15 minutes of downtime. Notify users in advance.

Upgrade Procedure — Windows¶

Step 1: Stop the RP-PAM Service¶

Stop-Service -Name "RpPam" -Force
Get-Service -Name "RpPam"   # Confirm status is "Stopped"

Step 2: Install the New Package¶

Run the MSI installer. It will detect the existing installation and perform an in-place upgrade.

# Interactive install (double-click the MSI or run):
msiexec /i "C:\Downloads\rppam-2.0.0-x64.msi"

# Silent install (for scripted upgrades):
msiexec /i "C:\Downloads\rppam-2.0.0-x64.msi" /qn /l*v "C:\Logs\rppam-upgrade.log"

The installer preserves your existing configuration in C:\ProgramData\Ravenphyre\RP-PAM\.

Step 3: Run Database Migrations¶

cd "C:\Program Files\Ravenphyre\RP-PAM\tools"
.\rppam-migrate.exe --apply

The migration tool will: - Display all pending migrations - Apply them in order - Report success or failure for each migration

Step 4: Start the Service¶

Start-Service -Name "RpPam"

Step 5: Verify¶

# Check service status
Get-Service -Name "RpPam"

# Check version
Invoke-RestMethod http://localhost:7101/system/health/ping

# Check for errors in recent logs
Get-Content "C:\ProgramData\Ravenphyre\RP-PAM\Logs\rppam*.log" -Tail 30

Upgrade Procedure — Linux (Debian/Ubuntu)¶

Step 1: Stop the RP-PAM Service¶

sudo systemctl stop rppam
sudo systemctl status rppam   # Confirm "inactive (dead)"

Step 2: Install the New Package¶

sudo dpkg -i /tmp/rppam-2.0.0-amd64.deb

If there are dependency issues:

sudo apt-get install -f

Step 3: Run Database Migrations¶

sudo /opt/rppam/tools/rppam-migrate --apply

Step 4: Start the Service¶

sudo systemctl start rppam

Step 5: Verify¶

# Check service status
sudo systemctl status rppam

# Check version
curl -s http://localhost:7101/system/health/ping | jq .

# Check for errors in recent logs
sudo journalctl -u rppam --since "10 minutes ago" --no-pager

Upgrade Procedure — Linux (RHEL/Fedora)¶

Step 1: Stop the RP-PAM Service¶

sudo systemctl stop rppam

Step 2: Install the New Package¶

sudo rpm -Uvh /tmp/rppam-2.0.0-x86_64.rpm

Or using dnf:

sudo dnf install /tmp/rppam-2.0.0-x86_64.rpm

Step 3: Run Database Migrations¶

sudo /opt/rppam/tools/rppam-migrate --apply

Step 4: Start the Service¶

sudo systemctl start rppam

Step 5: Verify¶

sudo systemctl status rppam
curl -s http://localhost:7101/system/health/ping | jq .
sudo journalctl -u rppam --since "10 minutes ago" --no-pager

Upgrade Procedure — Docker¶

For Docker deployments, pull the new image and recreate the container:

# Pull the new image
docker pull ravenphyre/rppam:2.0.0

# Stop and remove the current container
docker stop rppam && docker rm rppam

# Run migrations
docker run --rm \
  -v rppam-config:/etc/rppam \
  -v rppam-data:/var/lib/rppam \
  ravenphyre/rppam:2.0.0 rppam-migrate --apply

# Start the new container
docker run -d --name rppam \
  -p 7101:7101 \
  -v rppam-config:/etc/rppam \
  -v rppam-data:/var/lib/rppam \
  ravenphyre/rppam:2.0.0

# Verify
docker logs rppam --tail 20
curl -s http://localhost:7101/system/health/ping | jq .

HA Cluster Upgrades¶

For multi-node HA deployments, upgrade one node at a time to maintain availability:

Upgrade standby nodes first — stop, upgrade, migrate (only on the first node), start.
Verify each standby is healthy and has rejoined the cluster before proceeding.
Upgrade the primary (leader) last — the cluster will automatically fail over to a healthy standby.

Important: Run database migrations only once (on the first node you upgrade). The other nodes will detect the updated schema automatically.

Check cluster status after each node:

curl -s http://localhost:7101/api/v1/admin/cluster/status \
  -H "Authorization: Bearer $ADMIN_JWT" | jq .

Rollback¶

If the upgrade fails or introduces issues, restore from your pre-upgrade backup.

Windows Rollback¶

# Stop the service
Stop-Service -Name "RpPam" -Force

# Uninstall the new version
msiexec /x "C:\Downloads\rppam-2.0.0-x64.msi" /qn

# Install the previous version
msiexec /i "C:\Downloads\rppam-1.x.x-x64.msi" /qn

# Restore the database
Invoke-Sqlcmd -ServerInstance "localhost" -Query `
    "RESTORE DATABASE [RPPAM] FROM DISK = 'C:\Backups\RPPAM-pre-upgrade.bak' WITH REPLACE"

# Restore configuration
Copy-Item -Path "C:\Backups\rppam-pre-upgrade-*\*" `
    -Destination "C:\ProgramData\Ravenphyre\RP-PAM" -Recurse -Force

# Start the service
Start-Service -Name "RpPam"

Linux Rollback¶

# Stop the service
sudo systemctl stop rppam

# Reinstall the previous version (Debian/Ubuntu)
sudo dpkg -i /tmp/rppam-1.x.x-amd64.deb

# Restore the database (PostgreSQL)
sudo -u postgres psql -c "DROP DATABASE rppam;"
sudo -u postgres psql -c "CREATE DATABASE rppam;"
sudo -u postgres psql rppam < /tmp/rppam-db-backup-*.sql

# Restore configuration
sudo cp -r /tmp/rppam-config-backup-*/* /etc/rppam/

# Start the service
sudo systemctl start rppam

Troubleshooting¶

Problem	Cause	Solution
MSI installer fails with error 1603	Service still running or file lock	Stop the service and close any open log files
Migration fails with timeout	Large table requiring schema change	Increase migration timeout in `rppam.config`: `"migrationTimeoutSeconds": 600`
Service won't start after upgrade	Configuration format changed	Check release notes for config changes; compare with backup config
"Schema version mismatch"	Migrations did not run	Run `rppam-migrate --apply` manually
dpkg error: dependency problems	Missing system libraries	Run `sudo apt-get install -f` to resolve dependencies

Next Steps¶

Upgrading RP-PAM — Patch Updates (.rppkg) — For lighter patch updates
Backup and Restore — Ensure your backups are current
Log Collection and Submission — Collect logs if you need to contact support