Network & Firewall Access for Elchi
This page is the firewall checklist for the whole Elchi platform. It covers both sides of an installation:
- the platform servers (controller, control-plane, registry, MongoDB, metrics stack) — what they expose and what they must reach, and
- the edge hosts (machines running
elchi-client, its managed Envoy instances, and optionallyelchi-shield) — what they dial out to and the few things they expose.
Use it to size egress allow-lists, plan NAT/proxy rules, or harden a network policy. Everything below is derived from the running code paths in elchi-backend, elchi-client, elchi-shield, and the installers in elchi-archive — not aspirational.
Big picture — who talks to whom
┌──────────────────────── Platform server(s) ───────────────────────┐
│ │
Browser / operator ─────►:443 Front Envoy ──► nginx (UI) MongoDB :27017 │
│ │ └────► controller REST ClickHouse :9000 │
elchi-client (gRPC) ────►:443 │ x-target-cluster VictoriaMetrics / Grafana │
│ │ (set by registry ext_proc) │
Managed Envoy (xDS) ────►:443 ├───────────► control-plane(s) ◄─── registry (routing) │
Managed Envoy (ALS) ────►:443 └───────────► elchi-collector ──► ClickHouse │
│ │
DNS resolvers ──────────►:53 CoreDNS (GSLB, optional) │
└─────────────────────────────────────────────────────────────────────┘
Edge host: elchi-client ──gRPC──► platform :443 elchi-shield: loopback/UDS only,
elchi-client ──HTTPS─► archive.elchi.io optional egress → ClickHouse / OTel
The key design fact: in every production install path (bare-metal standalone, Docker Swarm, Helm), all client-facing traffic — browser UI, REST API, elchi-client command stream, Envoy xDS/ADS, and Envoy access-log streaming — enters through a single port on a front Envoy: TLS 443 on bare metal and Docker Swarm, the gateway NodePort (the install prints it) or your load balancer on Kubernetes. The registry's ext_proc filter inspects each request and sets an x-target-cluster header that routes it to the right internal process. You do not expose the controller, control-plane, or registry ports directly.
Inbound — platform servers
On Kubernetes (Helm chart)
The Helm chart has the same single front door, the gateway Envoy, exposed as a NodePort on every node:
- The http NodePort:
30000when it was free at install, otherwise the next free one (the install prints it;global.envoy.service.httpNodePortfixes it). Plain HTTP. Carries the UI, the REST API, theelchi-clientstream, Envoy xDS/ADS and the access-log streams. Allow it from operator networks and every edge-host subnet. - The https NodePort (
global.envoy.service.httpsNodePort, picked by Kubernetes unless you set it): the same routes over TLS.
With global.envoy.service.type=LoadBalancer the load balancer listens on 8080 (and 8443 for TLS) instead. Envoy admin (9901) is not exposed by the chart.
Single-node (standalone) install: one port
The bare-metal standalone installer opens exactly one port in the host firewall on a single-node install:
:443TCP — Front Envoy TLS listener. Carries the browser UI, REST API,elchi-clientgRPC command stream, Envoy xDS/ADS subscriptions, and Envoy access-log (ALS) streams. Allow from operator networks and every edge-host subnet.:53TCP + UDP — CoreDNS GSLB authoritative DNS. Only opened when the platform is installed with--gslb. Allow from your DNS resolvers.:19000TCP — Front Envoy's plain TCP proxy to ClickHouse, forelchi-shield's audit sink on the edge hosts (ClickHouse itself stays on loopback). Opened by the installer whenever ClickHouse is local; allow it from the edge-host subnets only if you use shield audit. Not TLS.
Everything else (controller, control-plane, registry, MongoDB, Grafana, VictoriaMetrics, ClickHouse, OTel, collector) binds loopback or stays firewall-blocked on a single node.
Multi-node (cluster) install: inter-node ports
When the standalone installer runs with 2+ nodes, these ports are additionally opened between cluster nodes only — they never need to be reachable from operators or edge hosts:
| Port | Proto | Purpose | When |
|---|---|---|---|
| 27017 | TCP | MongoDB replica set | 2+ nodes |
| 1870 | TCP | Registry gRPC (routing, ext_proc, HA peers) | 2+ nodes |
| 1960 | TCP | Controller gRPC (client command server) | 2+ nodes |
| 1980 | TCP | Controller REST API | 2+ nodes |
| 1990, 1991, … | TCP | Control-plane xDS — one port per installed Envoy version variant | 2+ nodes |
| 9000 | TCP | ClickHouse native protocol (collector → ClickHouse cross-node) | 2+ nodes, collector enabled |
| 9009 / 9181 / 9234 | TCP | ClickHouse interserver / Keeper client / Keeper Raft | 3+ nodes |
Docker Swarm deployments use the same logical ports and additionally require the standard Swarm mesh ports between nodes: 2377/tcp, 7946/tcp+udp, 4789/udp.
The processes have different built-in defaults, used as-is by the Helm charts inside the cluster network: controller REST :8099, controller gRPC :50051, control-plane xDS :18000, registry gRPC :9090, registry Prometheus metrics :9091 (hardcoded). The bare-metal installer remaps these to the 18xx/19xx range shown above. In both cases they are internal — the front Envoy on :443 is the only public entry point.
Internal-only ports (never open these)
For completeness — these bind on platform nodes but are loopback-only or intentionally firewall-blocked: front Envoy internal plaintext listener :8080, Envoy admin :9901, nginx UI :8081, Grafana :3000 (proxied at /grafana), VictoriaMetrics :8428, OTel Collector :4317/:4318, elchi-collector ALS :18090 + health :18091, ClickHouse HTTP :8123, registry metrics :9091, CoreDNS webhook :8053.
Inbound — edge hosts (elchi-client, Envoy, elchi-shield)
Edge hosts need almost nothing opened:
- Your Envoy data-plane listeners — whatever ports the services you publish through Envoy use (e.g. 80/443 for an edge proxy). These are defined by your listener configs, not by Elchi.
:179TCP (BGP) — only when the client is installed with--enable-bgp(FRR). Allow from/to your BGP peers.:8650UDP (HA heartbeat) — only on the two members of an HA pair, between their data and management addresses, both directions. The Elchi OS firewall opens it for the peer's addresses automatically. The standby also opens TCP connections to the active member's VIP listener ports to probe them — see Network requirements.
Everything else is local-only and needs no firewall rule:
elchi-clientitself listens on no TCP port at all — its controller connection is a single outbound gRPC stream.elchi-shieldserves Envoy over a Unix socket (/run/elchi-shield/extproc.sock, or loopback TCP) and exposes health/metrics/admin only on127.0.0.1:9001. Nothing needs to reach shield from off-box.- Envoy admin interfaces bind
127.0.0.1per instance.
Outbound — platform servers
Always required
The platform will not boot or stay healthy without these.
- MongoDB (27017 / SRV) — Primary state store, used by controller, control-plane, and registry (leader election).
mongodb+srv://<cluster>for Atlas (TLS) or your self-hosted host:port. On a standalone install MongoDB is local, so no egress rule is needed. - archive.elchi.io (HTTPS 443) — Envoy version metadata index (
/index.json) used to surface available versions in the UI and validate upgrade paths. - license-api.cloudnativeworks.com (HTTPS 443) — CNW License Server. Needed for activation; controllers also validate the license once at startup. Without it an activated license stays in force until its expiry date (the controller keeps the server's signed answer).
Internal (standalone install pulls these in locally)
- ClickHouse (native TCP 9000) — Controller reads shield audit events and traffic inventory; elchi-collector writes Envoy access logs. Local on standalone; a cross-node flow in clusters. Endpoints return 503 if
CLICKHOUSE_URIis unset. - GSLB nodes (HTTP 8053) — Controller pushes DNS record changes and queries health/records on the GSLB node instances (
X-Elchi-Secretheader). Only when GSLB is enabled.
Feature-gated
Open these only when the matching feature is enabled. None is needed for a vanilla install.
- Let's Encrypt ACME (HTTPS 443) —
acme-v02.api.letsencrypt.org(production) andacme-staging-v02.api.letsencrypt.org(staging). Google Trust Services (dv.acme-v02.api.pki.goog) whenca_provider: googleis selected. - DNS provider APIs (HTTPS 443) — For ACME DNS-01 challenges. Per provider:
api.cloudflare.com,api.godaddy.com,api.digitalocean.com,route53.amazonaws.com,lightsail.{region}.amazonaws.com, Google Cloud DNS APIs. Only the providers you actually attach need to be reachable. - OpenRouter API (HTTPS 443) —
openrouter.ai/api/v1for the AI Analyzer. Only contacted when an OpenRouter token is set per project. (All AI traffic goes through OpenRouter — no direct Anthropic/OpenAI egress.) - OpenStack APIs (HTTPS 443 / 5000) — Cloud provider integration (Keystone / Nova / Neutron). Only when a cloud is registered under
Settings → Clouds. - LDAP / LDAPS (389 / 636) — Optional external auth, when LDAP is enabled in
Settings → LDAP. - Syslog / SIEM (UDP, TCP, or TCP+TLS — your host:port) — Audit-log forwarding, when a syslog target is configured under
Settings → Audit Forwarding. - download.db-ip.com (HTTPS 443) — Free DB-IP Lite GeoIP database (city / ASN
.mmdb, ~80 MB) fetched on demand viaPOST /api/v3/setting/geoip/downloadfor shield's GeoIP features. Not needed if you upload a database file manually instead. - Kubernetes API (HTTPS 6443) — For the Discovery agent syncing endpoints back to the controller. The agent runs in-cluster, so this is normally an internal call rather than true egress.
- GSLB probe targets (HTTP / HTTPS / TCP) — When a GSLB record is created, the health checker continuously probes every IP/FQDN you list, on whatever port you configure. This is the largest egress surface — scope it by destination, not by port.
Install-time only
The installer downloads artifacts over HTTPS 443; after installation these are only needed again for upgrades:
github.com+api.github.com+codeload.github.com+raw.githubusercontent.com— Elchi binaries, UI bundle, Envoy, collector, CoreDNS/GSLB fromCloudNativeWorks/elchi-archivereleases; VictoriaMetrics and OTel Collector releases.- Distro package repos —
repo.mongodb.org+pgp.mongodb.com,apt.grafana.com/rpm.grafana.com,packages.clickhouse.com.
Outbound — edge hosts
What every machine running elchi-client must be able to reach:
- Elchi platform
:443(gRPC over TLS) — The one rule that matters. A single long-lived gRPC stream carries commands, heartbeat, stats, and bootstrap/config pushes; the managed Envoy instances open their xDS/ADS and access-log streams to the same address and port. - archive.elchi.io (HTTPS 443) — Downloads of Envoy binaries, SHA256-verified. Needed at install time and whenever a new Envoy version is deployed to the host.
- github.com / api.github.com (HTTPS 443) — Install-time only:
elchi-clientandelchi-shieldbinaries fromCloudNativeWorks/elchi-archivereleases (FRR packages too, if--enable-bgp). - Cloud metadata endpoints (HTTP 80, link-local) —
169.254.169.254andmetadata.google.internalfor cloud auto-detection. Local to the hypervisor; no firewall rule normally needed.
Optional, only when configured at shield install:
- ClickHouse (native TCP) —
elchi-shieldaudit-event sink (--shield-audit-dsn), batched and best-effort. Against the standalone install this is the platform's:19000proxy on any node (clickhouse://elchi:<password>@<node>:19000/elchi); against your own ClickHouse, its native port (9000 by default). - OTel Collector (OTLP gRPC 4317 / OTLP HTTP 4318) —
elchi-shieldmetrics push and/or audit-event alternative. On the standalone install the collector is also reachable through the front door:<node>:443(the/opentelemetryroute, TLS — the edge must trust the platform certificate). - JWKS endpoints (HTTPS) — Only if a shield JWT policy uses a remote
url:instead of a local key file; fetched at config load and refreshed in the background.
Quick reference — firewall snippets
Platform server (standalone, single node)
# Ingress
443/tcp from operators + edge-host subnets # UI, API, client gRPC, xDS, ALS
53/tcp+udp from DNS resolvers # only with --gslb
# Egress — always
archive.elchi.io:443 # version metadata + artifacts
license-api.cloudnativeworks.com:443 # license validation
github.com:443, api.github.com:443 # install/upgrade artifacts
# Egress — only if you issue certificates from Elchi
acme-v02.api.letsencrypt.org:443
acme-staging-v02.api.letsencrypt.org:443
api.cloudflare.com:443 # …plus only the DNS providers you attach
# Egress — only when the feature is on
openrouter.ai:443 # AI Analyzer
download.db-ip.com:443 # GeoIP database download (or upload manually)
<your-ldap-host>:636 # LDAP auth
<your-siem-host>:<port> # syslog forwarding
<gslb-node-ips>:8053 # GSLB node management
<gslb-probe-targets>:<any> # GSLB health probes
Edge host (elchi-client + Envoy + elchi-shield)
# Ingress
<your data-plane listener ports> # defined by your Envoy listeners
179/tcp from BGP peers # only with --enable-bgp
8650/udp from the HA peer (data + mgmt) # only on HA pair members
# Egress
<elchi-platform-address>:443 # client gRPC + Envoy xDS/ALS (the one that matters)
archive.elchi.io:443 # Envoy binaries
github.com:443, api.github.com:443 # install-time binaries
# Egress — only if shield telemetry is configured
<elchi-platform-address>:19000 # shield audit events (standalone install's ClickHouse proxy)
<clickhouse-host>:9000 # … or your own ClickHouse
<otel-collector>:4317 # shield metrics (OTLP/gRPC); or <elchi-platform-address>:443
Elchi's ACME integration runs DNS-01 challenges through the configured DNS provider API. You do not need to expose port 80 or 443 to the public internet for Let's Encrypt to issue or renew certificates. This makes Elchi safe to run entirely behind a VPN / private network.
Each GSLB record produces continuous outbound probes (HTTP, HTTPS, or TCP) against every IP you list, on whatever port you configured. If your egress policy is allow-listed, you must add every probe target. Plan ahead — there is no way to consolidate this list because the targets are user-defined.