`eghost`¶

eghost is the host-side operator CLI for EnforceGate vX. It is the single entry point recommended for every day-to-day operator action — from starting the stack to authoring policies, managing users, and generating support bundles. Under the hood it wraps docker compose for lifecycle and egctl / egpolicy for the engine-side operations.

The binary is installed at /usr/local/bin/eghost on both the virtual appliance (by the first-boot wizard) and on Docker bundle deployments (manually from the bundle's installer/bin/). Run without arguments to see a deployment dashboard:

eghost

Run eghost help for the verb list, or eghost <verb> --help for per-verb usage.

Lifecycle¶

Verb	Effect
`eghost up`	Start the stack (engine, captive portal, TLS terminator).
`eghost down`	Stop the stack. Volumes preserved.
`eghost restart [service]`	Restart everything, or one named service.
`eghost logs [service]`	Follow compose logs. Optionally scope to one service.
`eghost ps`	List the services and their state.

Status¶

Verb	Effect
`eghost`	One-screen deployment dashboard (no verb).
`eghost status`	Detailed engine and sidecar health, listener state, connector neighbours.
`eghost uptime`	Per-container uptime.
`eghost version`	CLI version plus the version of every running container's image.

Host-CLI ↔ stack version mismatch warning¶

eghost version prints a release: line (the version compiled into the host eghost binary) and a per-image-version line for every running container (read live from each container's OCI label). The two should match — but a docker compose pull && docker compose up -d swap upgrades the images while leaving the host binary on disk untouched, so release: can silently lag the actual running stack.

To make that visible, eghost version prints an explicit warning when its compiled release: disagrees with the version reported by the running enforcegate engine image, and points the operator at the resolution:

[enforcegate@enforcegate-vx ~]$ eghost version
release:    2026.51.0 (GD)
enforcegate (engine):    2026.52.0 (GD)
captive-portal:          2026.52.0 (GD)
tls-terminator:          2026.52.0 (GD)
enforcegate-toolbox:     2026.52.0 (GD)

! warning: eghost release (2026.51.0) lags the running stack (2026.52.0).
!          Re-run the appliance installer to refresh /usr/local/bin/eghost.

The warning is informational — every verb still works against the upgraded stack; the verbs have been forward-compatible across every shipped release. The fix is to re-run the installer (enforcegate-installer on the appliance, or ./install.sh for the Docker bundle), which writes a fresh /usr/local/bin/eghost matching the on-disk image tags.

Policy management¶

Verb	Effect
`eghost policy list`	List every `.policy` file in the rules directory.
`eghost policy show <name>`	Print a policy's content.
`eghost policy new [name]`	Create a new policy file in `$EDITOR`. Saves, compiles, and reloads automatically.
`eghost policy edit <name>`	Edit an existing policy. Saves, compiles, and reloads automatically.
`eghost policy remove <name>`	Delete a policy. Prompts for confirmation, then recompiles and reloads.

new, edit and remove invoke the underlying egpolicy compiler and the engine's reload path on save / confirm. The operator does not need a separate reload step.

The <name> argument can be:

the full filename (90-denyurlshort.policy),
the basename without extension (90-denyurlshort),
or a unique substring (denyurlshort) that matches exactly one file.

See policies for the file format.

User management¶

Verb	Effect
`eghost users list`	List Control-API user accounts.
`eghost users add <name>`	Create a new user. Prompts for password and privilege level.
`eghost users passwd <name>`	Change a user's password.
`eghost users remove <name>`	Delete a user. Refuses to self-remove.

See privilege model for the four levels.

Engine interaction¶

Verb	Effect
`eghost cli`	Drop into the interactive `egctl` REPL. Credentials are prompted host-side and forwarded.
`eghost engine shell`	Open `/bin/sh` inside the `enforcegate` engine container. New in 2026.42.0.
`eghost portal shell`	Open `/bin/sh` inside the `captive-portal` container. New in 2026.42.0.
`eghost tls shell`	Open `/bin/sh` inside the `tls-terminator` container. New in 2026.42.0.
`eghost shell [service]`	Deprecated. Use the per-namespace shells above (`eghost engine shell` / `portal shell` / `tls shell` / `toolbox shell`). Still works for one release with a deprecation notice; the rename disambiguates from the appliance console's in-CLI `shell`, which escapes out to the host.
`eghost api control test`	Probe the engine's Control API for liveness.
`eghost api license-activation test`	Probe the external Control Server for license-activation reachability.

Captive portal¶

Operator-facing surface for the captive-portal sidecar — see Captive portal for the routes, theming, and storage model.

Verb	Effect
`eghost portal aup edit`	Open the operator AUP Markdown in the host `$EDITOR` (seeded from a template on first edit). Saves, enables the feature, and recreates the captive-portal container so the new policy is served on the next `/aup` verdict. Verifies the portal stays up after the recreate; auto-reverts on crash. (new in 2026.36.0)
`eghost portal aup enable`	Enable the operator AUP rendering on the `/aup` verdict page without opening the editor. Reads from the previously-saved policy.
`eghost portal aup disable`	Disable the operator AUP rendering. The `/aup` route falls back to the built-in default; the saved policy is preserved.
`eghost portal aup show`	Print the current operator AUP Markdown to stdout.
`eghost portal aup status`	Report whether the operator AUP is enabled, the policy mtime, and the portal container's health.

Toolbox sidecar¶

Operator-facing surface for the optional enforcegate-toolbox sidecar — see Toolbox for the operator workflow and the volume / hardening model.

Verb	Effect
`eghost toolbox`	Default verb — equivalent to `eghost toolbox status`.
`eghost toolbox enable`	Flip `ENFORCEGATE_TOOLBOX_ENABLED=true` in `.env` and start the toolbox container.
`eghost toolbox disable`	Stop the toolbox container; volumes preserved.
`eghost toolbox status`	Container state plus a per-list summary (loaded / rejected / stale).
`eghost toolbox shell`	Interactive `bash` inside the toolbox container — line editing, history, and tab completion.
`eghost toolbox run <script>`	Invoke `scripts/<script>` once, attached to the current terminal.
`eghost toolbox logs [-f]`	Tail the container's logs (JSON-line ingestable into a SIEM).
`eghost toolbox cron list`	Show the current crontab.
`eghost toolbox cron edit`	Edit the crontab in `$EDITOR`.
`eghost toolbox edit <file>`	Edit any file under the toolbox volume (`/var/lib/enforcegate-toolbox`) with your host `$EDITOR`. Copy-out / edit / copy-in round-trip; works regardless of whether the image carries an in-container editor. Paths are confined to the volume. (new in 2026.36.0)
`eghost toolbox extend <pkg>…`	Add apt packages to the toolbox declaratively. Records your package list, builds a local overlay image (`enforcegate/toolbox:extended`) from the base, and points the toolbox at it — rootfs stays read-only at runtime; reproducible. `--status` / `--clear` / `--base <tag> --rebuild` round out the lifecycle. No in-container `apt-get install` — Python deps still use `pip install --user`. (new in 2026.36.0)
`eghost toolbox lists`	Enumerate currently loaded `*.list` files with last-update mtime.

Git-repo script delivery¶

Every repo subcommand accepts an optional -v / --verbose flag that also emits the machine-readable JSON event record (e.g. {"ts":…,"event":"repo-pull",…}). Without the flag, the verb prints only the human status line (✓ egguard: pulled → …) — operators driving these interactively get a clean shell, while operator scripts that want to ingest the events into a SIEM enable -v per call.

Verb	Effect
`eghost toolbox repo add <name> <url> [--branch B] [--entrypoint E] [--ssh-key K] [--ca C] [-v]`	Register and clone a repo into the toolbox's persistent volume. Multi-repo by name.
`eghost toolbox repo list`	List registered repos with their URL, branch, and last-pull timestamp.
`eghost toolbox repo show <name>`	One repo's URL / branch / HEAD / last pull.
`eghost toolbox repo pull <name>` \| `--all` `[-v]`	Fetch and hard-reset a repo (or every registered repo) to its upstream.
`eghost toolbox repo run <name> [--pull] [-v]`	Run the repo's configured entrypoint now; optionally pull first.
`eghost toolbox repo remove <name> [-v]`	Unregister and remove a repo from the toolbox's volume.

Credentials and trust material¶

Verb	Effect
`eghost toolbox keys import <name>`	Import an SSH deploy key — paste the key on stdin, end with Ctrl-D. The key is stored at `/var/lib/enforcegate-toolbox/.ssh/<name>` (mode `0600`).
`eghost toolbox ca import <name>`	Import a private / self-signed CA certificate (paste, Ctrl-D). Stored at `/var/lib/enforcegate-toolbox/ca/<name>.crt`. Referenced by name from `repo add --ca`.

Manual file drop¶

Verb	Effect
`eghost toolbox unpack <archive>`	Unpack a tarball or zip archive (previously dropped into the toolbox volume via `docker cp`) into the `scripts/` directory.

Appliance management console¶

Only available on the appliance VM and ISO images (Docker-tarball installs don't own the host firewall and skip this surface). Provides a dedicated SSH entry point on port 2222 — separate from the regular operator SSH on 22 — that drops straight into the engine CLI. From inside the engine CLI, typing start shell escapes to a host root shell via su - for maintenance tasks. New in 2026.42.0.

Verb	Effect
`eghost console status`	Show the live management-console port, the source-CIDR filter (if any), the host-SSH lockdown posture, and an `sshd -t` health check.
`eghost console source <cidr…>`	Restrict the management-console port to one or more source CIDRs (e.g. `10.1.3.0/24 192.0.2.0/28`). Renders a `firewalld` rich rule per CIDR and removes the wide-open port.
`eghost console source --open`	Drop the source-CIDR restriction (open the management-console port to all sources). Prints a warning.
`eghost console lockdown on\\|off`	Lock down standard host SSH (port `22`) so operators funnel through the audited 2222 management console — `on` removes the `ssh` service from the firewalld public zone; `off` re-opens it. The tty console (Ctrl+Alt+F2) is unaffected and stays as break-glass. New in 2026.43.1.
`eghost console apply`	Re-render the sshd drop-ins, firewall rules, SELinux port label, and pre-auth banner from the running `eghost` version. Use after an image upgrade to refresh the console wiring without re-imaging the appliance.

The installer's "Management access" step calls eghost console source and eghost console lockdown to set the initial CIDR restriction and host-SSH posture at deploy time; the verbs above are the day-2 path.

REPL host-shell escape: start shell

Inside the engine CLI, start shell is the keyword that escapes to a host root shell via su -. Earlier 2026.42.x previews used the bare shell keyword; the rename in 2026.43.1 (Iron Harrier) avoids a collision with the sh → show abbreviation. The exit-77 wrapper contract is unchanged — only the operator-facing keyword moved.

Appliance firewall¶

Appliance VM / ISO only (Docker-tarball hosts manage their own firewall). Gates the published product ports (3128 / 80 / 443) via Docker's DOCKER-USER chain — previously they answered on every interface including WAN because Docker forwards them ahead of firewalld's input filtering. New in 2026.47.5.

Verb	Effect
`eghost firewall apply`	Apply (or re-apply) the current gating configuration and install the boot re-apply unit so the gating survives reboots. Idempotent; the entry point for upgrading an existing appliance.
`eghost firewall status`	Show the live posture — configured client CIDRs, active role (`eg-lan` / `eg-wan` / `eg-mgmt`), DOCKER-USER rule count, LAN-SSH state, and whether the boot re-apply unit is enabled.
`eghost firewall clients <cidr…>`	Restrict the product ports to one or more source CIDRs (e.g. `10.1.3.0/24 192.0.2.0/28`). On a single-NIC host this is the only gate available.
`eghost firewall lan-ssh on\\|off`	Toggle host SSH on the LAN interface. Default is off (funnel operators through the port-2222 management console). `on` re-opens standard port-22 SSH.
`eghost firewall relax`	Troubleshooting escape hatch — ungate the product ports immediately (answers "is the firewall eating my traffic?"). Temporary: the next `firewall apply`, boot, or docker restart restores the gating. Persisted CIDRs / roles are untouched. The fail-closed INPUT floor stays up.
`eghost firewall persist on\\|off`	Explicit control over whether the DOCKER-USER gating is re-applied on every boot. `on` installs and enables the `enforcegate-firewall.service` unit; `off` disables it (pair to `firewall relax` for managing the firewall by hand). `status` reports the persistence state.

Traffic that never touches the gate

Container-to-container and container egress (Squid pulling upstream, the toolbox pulling URL lists) originates from the docker bridges (docker0 / br-eg0) and is exempt from the DOCKER-USER gate — the gate only concerns traffic entering the containers from outside. Without that exemption, gating would kill the product's own egress the moment it was applied.

Appliance OS upgrade¶

Appliance VM / ISO only. Steers the appliance OS's (openSUSE MicroOS) daily auto-upgrade — the OS upgrades itself into a snapshot every night and reboots into it during a maintenance window; the schedule is now operator-tunable. New in 2026.47.5.

Verb	Effect
`eghost os upgrade status`	Cadence, maintenance window, whether a snapshot is staged, whether a reboot is pending, and whether the upgrade cycle is paused.
`eghost os upgrade schedule <oncalendar> [--jitter]`	Set the check cadence. `<oncalendar>` is a systemd `OnCalendar` expression (e.g. `daily`, `Mon 03:00`, `--* 04:00`); `--jitter` adds up-to-N-minutes randomisation.
`eghost os upgrade window <HH:MM> <duration>`	Set the maintenance window during which a staged snapshot may reboot the appliance (e.g. `03:30 90m`). Outside the window a staged reboot waits.
`eghost os upgrade reboot-policy <auto\\|rebootmgr\\|instant\\|off>`	Pick how staged snapshots become live. `auto` (default) uses rebootmgr's window gating; `instant` reboots immediately when staged; `off` never reboots automatically.
`eghost os upgrade pause [--days N]`	Freeze the upgrade cycle during change-blackouts (release freezes, audits). `--days N` sets a hard end date; without it, paused until `resume`. `status` warns loudly while paused.
`eghost os upgrade resume`	Unpause the upgrade cycle.
`eghost os upgrade now [--reboot]`	Trigger a snapshot upgrade immediately. Without `--reboot`, the snapshot is staged and reboots at the next maintenance window; with `--reboot`, requests the window-gated reboot now (still subject to the reboot policy).
`eghost os upgrade reboot-now`	Reboot into the currently-staged snapshot immediately, bypassing the maintenance-window gate.

Reference and support¶

Verb	Effect
`eghost license`	Show the current license activation state (edition, expiry, connector counts). Equivalent to `egctl show-license` on the host side.
`eghost notices [service]`	Print third-party software notices for the named service (default: `enforcegate` standalone).
`eghost links`	Print the URLs operators commonly need (portal, dashboard, docs) plus reference commands.
`eghost support`	Print an inline diagnostic block — paste into a ticket if requested.
`eghost support bundle`	Write a redacted diagnostic tarball to `/tmp/enforcegate-diag-<timestamp>.tar.gz` for support tickets. See troubleshooting.

Environment¶

Variable	Effect
`ENFORCEGATE_NO_COLOR=1`	Disable ANSI colours in command output.

eghost¶