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.

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.