Upgrade SSLNexus

The preferred production upgrade route is the same native package format used for installation: DEB on Debian/Ubuntu and RPM on RHEL-family systems. Do not replace the installed binaries manually.

1. Before The Upgrade

sudo ssl-nexus-admin preflight
sudo ssl-nexus-admin backup --output /secure/path/ssl-nexus-pre-upgrade.tar.gz

Preflight verifies the current PostgreSQL DSN, service health, Nginx and required runtime dependencies. Resolve every FAIL before starting the package transaction.

2. Use The Native Package Manager

# Debian / Ubuntu — immutable versioned package
sudo apt install ./ssl-nexus_<version>_amd64.deb

# RHEL / Rocky / AlmaLinux — immutable versioned package
sudo dnf upgrade ./ssl-nexus-<version>-1.x86_64.rpm

The public Downloads page uses stable latest aliases for convenience. The Versions page keeps immutable versioned filenames for reproducible upgrades and rollback records.

3. Package Cutover And Rollback

SSLNexus preserves a package-upgrade checkpoint under /var/backups/ssl-nexus/package-upgrades/. The package activation path provisions/validates PostgreSQL authentication, starts the packaged service, checks its exact version and health, validates Nginx, and runs production preflight. If activation fails and a valid checkpoint exists, the package scripts restore the previous runtime/state.

Do not remove the checkpoint until the new release has completed normal certificate, target and Authority operations.

4. Large MSP Estates

For estates approaching thousands of MSP organisations or millions of certificates, treat upgrade qualification as a performance exercise rather than extrapolating from a small installation.

• Run the new release against a representative copy/canary before the production window.
• Measure PostgreSQL backup duration, migration duration, restart-to-health time and the first scheduler cycle.
• Keep full-table backfills and large index creation out of the service cutover window. Release migrations should prefer resumable/background work and PostgreSQL concurrent index creation where applicable.
• Confirm adequate free storage for the existing database, a recovery snapshot and migration working space.
• After cutover, monitor database connections, scheduler latency, renewal queues and Authority refreshes before expanding the rollout.

A release should not be described as sub-second for a 5,000-account / 10,000,000-certificate estate until that exact migration and restart path has been measured at representative scale.

5. PostgreSQL Ident / Peer Authentication Failure

If startup reports Ident authentication failed, Peer authentication failed, or SQLSTATE 28000 for the SSLNexus application database, use the supported repair command instead of editing pg_hba.conf by hand:

sudo ssl-nexus-admin database repair-auth
sudo systemctl restart ssl-nexus.service
sudo ssl-nexus-admin preflight

The repair preserves the existing application password when available, places a narrow loopback SCRAM rule for the SSLNexus database ahead of broader distribution rules, reloads PostgreSQL, and verifies the same DSN used by the service. Package upgrades run the PostgreSQL provisioning/verification path before activating the new service.

6. Verify The Upgrade

sudo ssl-nexus-admin preflight
systemctl --no-pager --full status ssl-nexus.service
journalctl -u ssl-nexus.service -n 100 --no-pager

In the dashboard, open Operations and confirm the installed version, Authority connectivity and update status. Test at least one representative target path before closing the maintenance window.

7. Upgrade Notifications

Clients check the signed/trusted release manifest for newer versions. SSLNexus may also show an operator-controlled New SSLNexus Release banner from the Licence Authority. The banner is version-aware: a Client already running the announced semantic version or a newer one suppresses it automatically. Notifications never install packages automatically.

8. Release File Naming

The two names for a release contain identical package bytes. Never overwrite an immutable versioned filename; only the latest aliases move when a release is promoted. Release manifests follow the same contract: /releases/<version>.json is immutable and /releases/latest.json points at the promoted current release.