10
Networking-and-TLS
gsadmin edited this page 2026-08-11 06:40:57 -04:00

Networking and TLS

ExecuteR does not terminate public TLS itself.

The state of the art is a dedicated edge that terminates TLS once, renews certificates automatically via ACME, and gives you layer-7 visibility. Any of these work well:

Edge Notes
Caddy Automatic HTTPS; single binary, runs on Windows or Linux
Nginx UI Web console with ACME renewal, also installs on Windows
HAProxy High-throughput L4/L7
Zoraxy All-in-one with a friendly UI

Routes to forward:

  • / → WebUI
  • /api/* → backend
  • /messaging/agent and /messaging/browser → NATS WebSocket

Preserve the WebSocket upgrade, and send X-Forwarded-For, -Proto, -Host and -Prefix.

Standalone vs split routing

The route table above is the split layout, where WebUI, the API and NATS run as separate services (the container deployment) — that is why the sample has three upstreams.

The standalone single binary is different. It is the WebUI + API plus a built-in WebSocket relay: it forwards /messaging/* to its local NATS over loopback itself. So point every route at the one backend port (9080 by default, https when TLS is on) — a single upstream — and leave NATS on loopback. Nothing forwards to NATS directly.

One caveat if you adapt the split sample for standalone: the /messaging/* routes speak WebSocket, so a split upstream targets the NATS WebSocket port (9222 / 19222), never the core protocol port 4222.

Exposing NATS directly (optional)

Only if you deliberately want the edge proxy to hit the NATS WebSocket itself — offloading the relay from the backend — set the NATS WebSocket bind to 0.0.0.0 (the server MSI's "WS bind" field, or setup --nats-bind). The core and monitor listeners always stay on loopback.

When you do that with self-signed TLS on, the WebSocket listener serves TLS using the server's own managed leaf (data/tls) — no separate NATS certificate to make or rotate. The sidecar reloads nats-server when the chain renews. Your edge proxy then treats that wss://…:9222 upstream exactly like the backend one: skip verification, or import the root + intermediate.

Ready-to-adapt single-file samples ship in the repository:

  • src/Infra/nginx — nginx-ui friendly site with edge rate limiting
  • src/Infra/caddy — automatic HTTPS via ACME, runs on Windows too
  • src/Infra/haproxy — stick-table rate limits and tunnel timeouts

Each carries the same shape: BEFORE-USE placeholders, forwarded headers, WebSocket handling, commented IP allow-lists, and the self-signed upstream variant.

Standing up Nginx UI — scripted as a Windows service, or in Docker on Linux — is covered step by step in Edge Proxy Install, along with the full nginx site for ExecuteR.

How the server learns its URL, scheme and port

The server sits behind your edge proxy. The connection it sees is the hop from the proxy, not the client's original request. Forwarded headers bridge that gap.

When a trusted proxy sets them, the server adopts the original request's details:

  • X-Forwarded-Proto → the scheme the client used (http or https). This is how the server knows the public side is HTTPS even though the proxy talks to it over plain http.
  • X-Forwarded-Host → the public hostname the client asked for. A port in this value is honored; otherwise the scheme's default applies.
  • X-Forwarded-For → the client's real IP, for logs and rate limiting.
  • X-Forwarded-Prefix → a path prefix, when the app is mounted under a sub-path.

From scheme and host the server builds its public base URL.

That URL is what goes into the Add-Device one-liner, the install commands, and the links shown to operators. So a device receives a URL that actually reaches the server — not the internal address the proxy happened to connect to.

Pinning the URL explicitly

Set PUBLIC_SERVER_URL to bake in the exact external URL — scheme, host and port.

It wins over the headers and over the request. Reach for it when the admin browses via an internal name the devices cannot reach, or when you just want the URL fixed regardless of how a request arrived.

Which proxies are trusted

Forwarded headers are honored only from a trusted source. Otherwise any client could spoof them.

  • Trusted by default from private address space: loopback, RFC1918 and CGNAT. A typical cloud or LAN proxy needs no configuration.
  • TRUSTED_PROXIES — comma/semicolon list of exact proxy IPs. Replaces the private-range defaults.
  • TRUSTED_NETWORKS — CIDR ranges such as 10.0.0.0/8. Also replaces the defaults.
  • TRUSTED_HOSTS — an allow-list of host names accepted from X-Forwarded-Host.
  • FORWARD_LIMIT — how many chained proxies to walk back. Default is 1; raise it only for proxy-behind-proxy.
  • TRUST_PROXY=0 — turn forwarded-header processing off entirely, for a directly exposed deployment.

Headers consumed: X-Forwarded-For, -Proto, -Host and -Prefix.

How this ties into TLS termination

Where TLS terminates follows the URL. That is what keeps deployment flexible:

  • Proxy with a real certificate in front — clients see the proxy's cert. X-Forwarded-Proto: https tells the server the public side is secure. The internal hop can be plain http or the self-signed listener.
  • No proxy, self-signed direct — the server serves HTTPS itself, and the base URL is its own https address.

The install command the server hands out reflects exactly this: when self-signed TLS is on it embeds the CA fingerprint (inside the bootstrap token) so the agent can pin whatever it fetches; with a real certificate in front the agent simply validates. See Agents below.

Self-Signed TLS (on by default)

The server encrypts its own listener by default.

It serves HTTPS with a chain it manages itself: root CA → intermediate → leaf. The chain is issued on first boot and auto-renewed — the leaf lasts a year, is re-issued 30 days early, and hot-swaps without a restart.

Opting out: TLS_SELF_SIGNED=0, setup --tls 0, or uncheck the box in the server MSI wizard.

What the reverse proxy should do

Two equally valid options. Pick per your organization's security standards.

  • Skip verification — nginx proxy_ssl_verify off, Caddy tls_insecure_skip_verify, HAProxy ssl verify none. This is not insecure. The hop is still fully encrypted; the self-signed roots simply are not distributed, so there is nothing to verify against.
  • Establish trust — import the root and intermediate into the proxy's trust store. fullchain.crt sits next to the PEMs for pinning. This adds a rotation duty: when the chain rotates at expiry, re-import the new roots.

Where the chain lives

  • Windows — the machine certificate stores, each link where it belongs: root in Trusted Root Certification Authorities, intermediate in Intermediate CAs, leaf in Personal. Browsers on the server itself trust it with no warning.
  • Windows, additionally — a PEM mirror under <data>/tls, refreshed on every renewal. A local Caddy or Nginx UI can bind or trust those files and stay current.
  • Linux / macOS — the PEM files are the primary store. TLS_CERT_DIR overrides the location.

Agents

Trust is automatic and anchored safely on first contact — the server decides, the agent follows, and there is no operator checkbox.

  • Connection-first. At enrollment the agent tries a normally-validated connection. If the certificate already validates — a real/edge cert, or a CA installed on a previous run — it installs nothing.
  • Self-signed, first contact. Only if validation fails does the agent fetch the CA from /api/enrollment/ca (accept-any) and pin it: the fetched root must match the fingerprint baked into the bootstrap token before it is installed. A mismatch — or a 404, or a token with no fingerprint — aborts, which closes the trust-on-first-use window. After that it validates normally.
  • A real certificate in front — /api/enrollment/ca returns 404, so the agent installs nothing and validates against the system trust store. Add that proxy later and nothing on the agent changes.
  • Staying current — a background service refreshes the CA over the agent's already-validated connection, so a root renewed in place (same key, re-issued certificate) or a new intermediate is picked up before the old cert expires, with no re-enrollment. A true root key rotation can't validate and is left for a fresh bootstrap token.

TlsSkipVerify remains a manual accept-any escape hatch. Full walk-through: Self-Signed TLS Trust Bootstrap; agent commands in Agent Deployment.