Upgrading RP-PAM — Patch Updates (.rppkg)¶

Section: Operations | Article 40
Audience: System Administrators
Last Updated: 2026-04-06

Understanding Update Types¶

RP-PAM has two types of updates. This article covers patch updates (.rppkg). For major version upgrades, see Upgrading RP-PAM — Major Versions.

Update Type	Package Format	What Changes	Downtime	Frequency
Patch / Hotfix	`.rppkg`	Only changed components	Minimal to zero	As needed
Major Upgrade	MSI / deb / rpm	All binaries replaced	Full restart	Quarterly

Why .rppkg?¶

A .rppkg file is a signed package that contains only the components that changed. Instead of replacing the entire application, RP-PAM updates only the affected layers:

Layer	Example	Impact
Layer 5 — Portal UI	CSS fix, new dashboard widget	Zero downtime (hot-swap)
Layer 4 — Modules	AD module bug fix	Module restart only (seconds)
Layer 3 — Core Services	Vault service security patch	Brief service restart (~30 seconds)
Layer 2 — Database Layer	Query optimization	Brief service restart
Layer 1 — Platform Host	Runtime update	Full restart (~60 seconds)

Database schema changes (migrations) are always applied last, only after all component updates pass their smoke tests.

Key point: A .rppkg file works on all platforms — Windows, Linux, and Docker. The same package file applies everywhere. You do not need separate packages for different operating systems.

Before You Start¶

Back up your database (see Backup and Restore)
Verify the package — ensure you received it from Ravenphyre (check the download source)
Read the release notes — included with every .rppkg download
Schedule a maintenance window — most patches take under 2 minutes, but plan for 10 minutes

Applying a Patch — Using the Upgrade Tool (Recommended)¶

The rppam-upgrade tool handles the entire process with automatic rollback on failure.

Windows¶

# Navigate to the tools directory
cd "C:\Program Files\Ravenphyre\RP-PAM\tools"

# Apply the patch
.\rppam-upgrade.exe --package "C:\Downloads\update-1.0.1.rppkg"

Linux¶

sudo /opt/rppam/tools/rppam-upgrade --package /tmp/update-1.0.1.rppkg

What the Upgrade Tool Does¶

The tool executes a 9-step pipeline automatically:

[1/9] Pre-flight checks.............. OK
  - Verifies package signature
  - Checks disk space (needs 2 GB free)
  - Validates current schema version

[2/9] Creating database backup....... OK
  - Full database backup before any changes

[3/9] Backing up current binaries.... OK
  - Copies current installation for rollback

[4/9] Stopping RP-PAM service....... OK

[5/9] Installing new binaries........ OK
  - Layer-by-layer, bottom to top

[6/9] Running database migrations.... OK
  - Only if the package includes schema changes
  - Each migration validated before proceeding

[7/9] Starting RP-PAM service....... OK

[8/9] Running health check........... OK
  - Verifies the service is healthy after update

[9/9] Upgrade complete!

If Something Goes Wrong¶

The upgrade tool automatically rolls back if any step fails:

Failure Point	What Happens
Component smoke test fails	Backup binaries restored, service restarted with old version
Schema migration fails	Migration DOWN blocks run in reverse, binaries restored
Health check fails after update	Full rollback (schema + binaries), old version restored

You can also manually trigger a rollback:

Windows:

.\rppam-upgrade.exe --rollback

Linux:

sudo /opt/rppam/tools/rppam-upgrade --rollback

Applying a Patch — In HA Clusters¶

In a multi-node HA deployment, patches are applied as a rolling update — one node at a time, with zero cluster downtime.

Automatic Rolling Update (from the leader node)¶

The leader node coordinates the rolling update across all nodes:

Windows (on the leader node):

.\rppam-upgrade.exe --package "C:\Downloads\update-1.0.1.rppkg" --rolling

Linux (on the leader node):

sudo /opt/rppam/tools/rppam-upgrade --package /tmp/update-1.0.1.rppkg --rolling

The rolling update process:

Standby nodes updated first — each standby is drained, updated, smoke-tested, and rejoined
Primary (leader) updated last — after all standbys are healthy on the new version
A standby promotes to leader temporarily while the original leader is being updated
Zero cluster downtime — at least one node is always serving requests

Manual Node-by-Node Update¶

If you prefer to control the process manually:

Update Node 2 (standby): rppam-upgrade --package update.rppkg
Verify Node 2 is healthy: curl http://node2:7101/system/health/ping
Update Node 3 (standby): repeat
Update Node 1 (primary): the cluster automatically fails over to a standby during this step

Verifying the Update¶

After the update completes:

Check the version:

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

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

Check update history:

# Windows
Invoke-RestMethod http://localhost:7101/api/v1/admin/updates/status `
  -Headers @{ Authorization = "Bearer $adminJwt" }

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

Check logs for errors:

Windows:

Get-Content "C:\ProgramData\Ravenphyre\RP-PAM\Logs\rppam*.log" -Tail 20

Linux:

sudo journalctl -u rppam --since "10 minutes ago"

Troubleshooting¶

Problem	Solution
"Package signature invalid"	Re-download the package; the file may be corrupted
"Insufficient disk space"	Free up at least 2 GB on the RP-PAM drive
"Schema version mismatch"	You may have skipped a patch — apply patches in order
Rollback doesn't complete	Use `--rollback` manually; check backup directory exists
Service won't start after update	Check logs; try manual rollback: `rppam-upgrade --rollback`

Next Steps¶

Upgrading RP-PAM — Major Versions — For MSI/deb/rpm major upgrades
Backup and Restore — Ensure backups are current before patching