Upgrade¶

EnforceGate vX uses the same upgrade procedure for the virtual appliance and the Docker bundle: download the new release, verify it, and re-run sudo ./install.sh. The installer detects an existing deployment and switches to its upgrade path — no flags, no separate command.

Procedure¶

1. Download the new release from the Software Downloads Portal — the OVA for the virtual appliance, or the standalone bundle archive for Docker.
2. Verify the cosign signature against exosys-release.pub the same way you did at first install (see VMware or Docker for the exact command).
3. Unpack into a new directory next to the previous bundle — do not overwrite the old one until the upgrade is confirmed healthy.

4. Run the installer:

   sudo ./install.sh
   

5. The wizard detects the existing deployment on the host, prints a short summary (current version → target version, volumes that will be reused), and prompts for confirmation. Accept to start the upgrade.

The installer pulls or loads the new image, rolls the stack onto the new tags, and waits for the engine and sidecars to report healthy before returning.

Release artifact names¶

Every shipped artifact carries the edition in its filename, so a Pro build is never mistaken for a Business or Enterprise one. Downloads arrive as a single per-release directory:

<version>-<TIER>-<edition>/
├── enforcegate-standalone-<edition>-<version>-<TIER>.tar.zst       # Docker-host installer
├── enforcegate-vX-<edition>-<version>-<GD|EA|IR>.ova               # VM image (VMware / VirtualBox)
│                                        …also .qcow2 .vmdk .vhdx .ovf .mf
├── enforcegate-vX-<edition>-appliance.x86_64-<version>-<GD|EA|IR>.install.iso
├── <every file above>.sig                                          # per-file signature
├── SHA256SUMS · SHA512SUMS · exosys-release.pub · VERIFY.md
└── sbom.cyclonedx.json (+ .sig)

Manual upgrade — SCP + installer¶

When the release bundle is on a workstation rather than downloadable directly from the host (air-gapped deployment, restricted egress, or an operator who wants to control the transfer path themselves), the upgrade is a straightforward SCP + installer pattern. Works for both the appliance and the Docker bundle; the appliance needs one extra step to temporarily open its host SSH port so the SCP transfer can reach /tmp.

# (1) APPLIANCE ONLY — open host SSH (port 22) so scp can reach /tmp.
#     Run from the appliance management console: `ssh -p 2222
#     <operator>@<appliance>` → engine CLI → `start shell` → host root.
eghost console lockdown off

# (2) From your workstation, upload the release bundle plus its
#     verification material to the host. Set EDITION to the edition you
#     are licensed for — the filename must match it.
export EDITION=pro          # pro | business | enterprise
export VERSION=2026.52.0
export TIER=GD-prod

BUNDLE=enforcegate-standalone-${EDITION}-${VERSION}-${TIER}.tar.zst
scp "${BUNDLE}" "${BUNDLE}.sig" \
    exosys-release.pub SHA256SUMS SHA512SUMS VERIFY.md \
    enforcegate@<appliance-hostname-or-ip>:/tmp

# (3) On the host: unpack and run the installer. It detects the
#     existing deployment and switches to the upgrade path
#     automatically.
cd /tmp/
tar -xf enforcegate-standalone-${EDITION}-${VERSION}-${TIER}.tar.zst
cd enforcegate-installer/
./bin/enforcegate-installer

# (4) APPLIANCE ONLY — re-lock host SSH once the upgrade is complete.
eghost console lockdown on

Verify the release signature and the SHA-256 / SHA-512 manifests against VERIFY.md before running the installer — the installer does not re-verify the bundle it was launched from. See VMware — Image download or Docker — Verify for the exact cosign and sha*sum commands.

What is preserved¶

The upgrade reuses all operator state from the previous install:

• Configuration — engine.conf, squid-connector.conf, and any operator overrides applied via .env.
• License activation — the bound serial and the engine's license-bound state under /etc/enforcegate/license/.
• Policy history — committed policy versions and the audit trail (see policy rollback).
• Audit log — the EULA-acceptance hash chain and the SSL-inspection audit log.
• TLS material — the captive-portal leaf and (if bump mode is enabled) the bump CA.

State is preserved because the four named volumes (enforcegate-config, enforcegate-data, enforcegate-shared, enforcegate-tls) survive container removal. See persistence for the full volume model and the section-merge behaviour applied to config files.

Engine ↔ connector co-upgrade¶

The wire protocol between the engine and its Squid connector — Defendr — has its own version, distinct from the engine release. The engine and every connector that pairs with it must be on the same Defendr major.minor to establish a session. A mismatched pair is rejected at the engine's protocol-version check and the engine logs:

[error] Defendr protocol version mismatch: remote:0.X, local:0.Y

The connector then fails its session, Squid respawns it, and the cycle repeats until the versions line up.

For the standalone bundle this is automatic — one image artifact carries both the engine and the connector, so a sudo ./install.sh upgrade rolls them together. The co-upgrade requirement only matters in two shapes:

• Multi-image deployments where the engine and a connector run in separate containers from different image tags — upgrade both image tags as a unit.
• A standalone Squid on a separate host (reference setup) forwarding to a remote engine — the connector binary on the Squid host needs to roll alongside the engine on the EnforceGate host. The Defendr protocol bumped from v1 to v2 in 2026.28.0; deployments straddling that boundary will not connect.

If you need to stage the rollout, plan a brief connector outage during which the engine logs the mismatch line — it resolves the moment the connector catches up. Operator state on both sides survives.

Verifying the upgrade¶

After the installer returns, confirm the new version is running:

eghost version       # CLI + per-container image versions
eghost status        # engine + sidecar health
eghost              # one-screen deployment dashboard

The release field in eghost status should match the version you just deployed. If any component is still on the previous tag, the upgrade did not complete — check eghost logs and the troubleshooting guide.

Rolling back¶

If the new release behaves unexpectedly, re-run sudo ./install.sh from the previous bundle directory. The installer treats the older version as a target upgrade-path (downgrade) and rolls the stack back onto it. Operator state is preserved across the rollback just as it is across the upgrade.

For finer-grained recovery — restoring an earlier policy version without touching the image — see policy rollback.