Skip to content

Virtual appliance

The EnforceGate vX virtual appliance is the recommended installation method for most environments: a single OVA that boots into an immutable host OS with Docker pre-installed and the EnforceGate standalone bundle pre-pulled. A guided installer walks the operator through the remaining configuration on first boot.

The appliance deploys on VMware ESXi, KVM (via virt-v2v or direct import), and Microsoft Hyper-V — the same OVA image works for all three.

Prerequisites

The appliance deploys on any of the following hypervisors:

  • VMware vSphere ESXi 8.0 or newer.
  • KVM with QEMU 7.0+ (use virt-v2v to convert the OVA, or import the bundled .qcow2 directly).
  • Microsoft Hyper-V Server 2019 or newer (use the bundled .vhdx file from the same release).

Resource defaults: 2 vCPU, 4 GiB RAM, 24 GiB disk — see requirements for tuning guidance.

Image download

Go to the Software Downloads Portal, select EnforceGate, then EnforceGate vX appliance and follow the link to download the latest OVA.

The VM image filename carries the edition and the release class — for example enforcegate-vX-pro-2026.52.0-GD.ova. Set these to match the file you downloaded:

export EDITION=pro          # pro | business | enterprise — must match your licence
export VERSION=2026.52.0
export CLASS=GD             # release class only: GD | EA | IR

VM images use the release class, not the full tier

The .ova / .qcow2 / .vmdk / .vhdx carry only GD / EA / IR, while the Docker installer tarball carries the full tier (GD-prod). See release artifact names.

Verify the SHA-256 of the downloaded image:

sha256sum enforcegate-vX-${EDITION}-${VERSION}-${CLASS}.ova

Ensure that the checksum matches the value published on the download page. Never trust checksums from third-party sources.

We also recommend verifying the cosign signature of the OVA against the Exosys release public key:

cosign verify-blob \
    --key exosys-release.pub \
    --signature enforcegate-vX-${EDITION}-${VERSION}-${CLASS}.ova.sig \
    --insecure-ignore-tlog \
    enforcegate-vX-${EDITION}-${VERSION}-${CLASS}.ova

exosys-release.pub is shipped alongside the OVA on the downloads portal and is also reproduced inside every released bundle at ./exosys-release.pub.

Virtual machine installation

To deploy the appliance from the OVA on VMware ESXi: log in to the ESXi Host Client, right-click the host and select Create / Register VM. Choose Deploy a virtual machine from an OVF or OVA file, click Next, then follow the wizard to upload the OVA, name the VM, select storage and network, and review before finishing.

Step-by-step guide (VMware ESXi)

  1. Log in to the ESXi Host Client. Access your ESXi host via its web client.
  2. Create the VM. Right-click the host in the inventory and select Create / Register VM.
  3. Select deployment type. Choose Deploy a virtual machine from an OVF or OVA file and click Next.
  4. Upload the OVA. Click the blue pane to browse, select the OVA file, and click Open.
  5. Name the VM. Enter a name for your new VM and click Next.
  6. Select storage. Choose the datastore for the VM's files and click Next.
  7. Configure network. Map the VM's network adapter to the correct network in your environment.
  8. Review and complete. Review the deployment settings on Ready to complete and click Finish.
  9. Post-deployment configuration. Once import completes, edit the VM to set CPU, memory, and other settings as needed (defaults are 2 vCPU / 4 GiB RAM / 24 GiB disk).

KVM / Hyper-V

For KVM, import the bundled .qcow2 file directly via virsh define and a domain XML referencing the disk, or convert via virt-v2v --in-place. For Hyper-V, import the bundled .vhdx file with the New-VM wizard. The first-boot configuration flow is identical to VMware once the VM is running.

Initial setup

Setup wizard

On first boot the appliance brings up the guided installer on the VM's console. It walks the operator through:

  1. Keyboard layout — picked first so the operator can type the rest of the wizard's fields in their native layout.
  2. Timezone — system timezone selection (defaults to UTC).
  3. Host network — DHCP or static IP, hostname, FQDN, DNS servers, optional default route.
  4. EULA — pages the End User License Agreement, Software License, and Warranty. Acceptance is required to continue and is recorded with a tamper-evident hash chain.
  5. License credentials — your license serial, account username, and password. Land in /opt/enforcegate/bundles/standalone/.env as ENGINE_LICENSE_SERIAL/USERNAME/PASSWORD. See Licensing.
  6. Operator account — a single username and password used for both the management-console SSH login (port 2222) and the engine Control-API superadmin. Replaces the build-time default (enforcegate / enforcegate-changeme). The name is configurable and renames both sides in lockstep — pick a lowercase POSIX username since it's a real host login.
  7. Organisation name — the legal entity name baked into the X.509 Subject DN of the engine's Defendr certificate and the SSL-bump CA. Once a bump CA has been issued under one O=, rotating the name is a fleet trust-store redistribution event — pick carefully.
  8. Captive portal hostname — FQDN clients reach the portal at (used as the CN/SAN on the portal's bump-CA-signed leaf cert). Defaults to localhost for smoke-tests; production deployments should set a real FQDN.
  9. SSL inspection mode — off (default), peek, or bump. Selecting bump requires confirming the binding acknowledgement (ENFORCEGATE_SSL_INSPECT_ACK=1) — see SSL inspection.
  10. Customize Options — opt-in components beyond the default enforcement appliance. The first item is the operator toolbox sidecar (enforcegate-toolbox) — a sandboxed container with bash, Python, and the standard EnforceGate CLI tooling pre-installed, designed for scheduled category-list refresh, ad-hoc URL / domain investigation, and operator scripting. Off by default; opting in writes ENFORCEGATE_TOOLBOX_ENABLED=true to the bundle's .env. The toolbox can also be enabled later via eghost toolbox enable. See Toolbox.
  11. Root password — password for the appliance's root host account, kept as break-glass. The operator account (from step 6) is what you'll normally use to SSH into the management console on port 2222.

The wizard writes everything to /opt/enforcegate/bundles/standalone/.env, installs the eghost operator CLI at /usr/local/bin/eghost, then enables a systemd autostart unit that runs eghost up at every host boot.

Access surfaces

The deployed appliance has one unified operator credential (from the wizard's Operator account step) that covers both authentication surfaces, plus a separate break-glass root password:

Operator account — same username and password for both:

  • The management-console SSH login on port 2222 — drops the operator straight into the engine CLI via SSO (see Appliance management console).
  • The engine Control API — what eghost / egctl and the captive portal sidecar authenticate against under the hood.

Default username enforcegate (was admin pre-2026.43.1; two-password setup was replaced by the unified credential in 2026.45.0). The name is configurable at install time and renames both sides in lockstep; enforcegate-host console set-operator <name> is the day-2 rename verb.

root — break-glass account for host-level recovery. Separate password set in the wizard's Root password step. Not used for day-to-day operation.

Regular host SSH (port 22) is locked down by default on the appliance to funnel operators through the audited console — see eghost console lockdown.

Re-running the wizard

To re-run the wizard after deploy (for example to change network configuration), SSH in and invoke the binary directly:

$ ssh enforcegate@<VM-IP>
[enforcegate@enforcegate-vx ~]$ enforcegate-installer
Welcome to the EnforceGate vX setup
[...]

Once setup completes the appliance reboots and the enforcegate compose stack starts automatically via the enforcegate.service systemd unit (ordered After=docker.service).

First login

The canonical first-login flow on the appliance uses the management console on port 2222 — SSH drops straight into the engine CLI with the unified operator credential from wizard step 6 (no second password prompt):

  1. SSH into the management console on port 2222:

    ssh -p 2222 enforcegate@<appliance-IP>

    The console SSO authenticates via kernel peer credentials and resolves the asserted operator to their AAA privilege level. First-time landing goes straight into the engine CLI.

  2. Verify the engine is healthy from the CLI prompt:

    host> show status
host> show version
host> exit

  3. If you need a host shell for maintenance tasks, type start shell from the engine CLI. The console escapes to a host root shell via su - (prompts for the root password from wizard step 11). Type exit or hit Ctrl-D to return.

Regular host SSH (port 22) is locked down by default on the appliance to funnel operators through the audited console — see eghost console lockdown to relax it if you need direct host-side access for scripting.

Day-2 operations

After first login, drive the appliance with the eghost CLI:

[enforcegate@enforcegate-vx ~]$ eghost                   # one-screen dashboard
[enforcegate@enforcegate-vx ~]$ eghost status            # detailed health
[enforcegate@enforcegate-vx ~]$ eghost version           # CLI + per-image versions
[enforcegate@enforcegate-vx ~]$ eghost logs              # follow compose logs
[enforcegate@enforcegate-vx ~]$ eghost ps                # list services
[enforcegate@enforcegate-vx ~]$ eghost restart           # restart the stack
[enforcegate@enforcegate-vx ~]$ eghost policy list       # list ACL policy files
[enforcegate@enforcegate-vx ~]$ eghost cli               # interactive engine CLI
[enforcegate@enforcegate-vx ~]$ eghost help              # full verb reference

eghost help is the canonical inventory of operator commands. See services and runtime for the lifecycle model and status for the health-check workflow.