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.

Verify the SHA-256 of the downloaded image:

sha256sum enforcegate-vX-2026.30.0-EA.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-2026.30.0-EA.ova.sig \
    --insecure-ignore-tlog \
    enforcegate-vX-2026.30.0-EA.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. These land in /opt/enforcegate/bundles/standalone/.env as ENGINE_LICENSE_SERIAL/USERNAME/PASSWORD.
  6. Engine Control API admin — username and password for the engine's Control API (what eghost / egctl and the captive portal authenticate against). Replaces the build-time default (admin / enforcegate-changeme).
  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. Host console passwords — passwords for the appliance's root and enforcegate host accounts. These are what you'll use to SSH into the appliance after deploy.

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 two distinct authentication surfaces. The wizard sets credentials for both during initial setup.

Engine Control API — what the eghost and egctl operator CLIs and the captive portal sidecar authenticate against:

  • Username: admin (overridable in the wizard's Engine Control API admin step)
  • Build-time default password: enforcegate-changeme — replaced by the value entered in the wizard. If the shipped default is still in place after setup, eghost status raises an audit warning.

Host SSH — for running eghost and host-level maintenance on the appliance:

  • Username: enforcegate
  • Password: set in the wizard's Host console passwords step. The appliance image ships with no SSH password — only authorised-keys access via ~/.ssh/authorized_keys is accepted until the wizard runs.

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 once the wizard reports success and the appliance has rebooted:

  1. SSH in as the enforcegate host user with the password set in the wizard's Host console passwords step:

    ssh enforcegate@<appliance-IP>

  2. Verify the stack is healthy from the host:

    [enforcegate@enforcegate-vx ~]$ eghost status

  3. Drop into the engine REPL to confirm the engine itself is up and the Control API is reachable. eghost cli prompts for the Engine Control API admin password from wizard step 6 — not the SSH password from step 11:

    [enforcegate@enforcegate-vx ~]$ eghost cli
Password: ********
host> show status
host> show version
host> exit

The two credential prompts in this flow correspond to the two distinct authentication surfaces documented under Access surfaces — SSH uses the enforcegate host account; eghost cli authenticates against the Engine Control API.

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.