The router: the front door of every box

You are here: the router is the single public-facing process on a box. The hibernation activator (part 06) and the mesh (part 07) both live inside this same process, switched on by configuration.

What the router is and why it exists

A box hosts many chat space instances, plus a few supporting services. Each of those is its own process, and none of them listens on a public network port — every one of them listens on a unix socket, which is a special file (in this system, under /run/lchat/) that processes on the same machine can connect to like a network address. Unix sockets are invisible to the internet, which is the point: the only way traffic reaches an instance is through the router.

The router is started by systemd as the service lchat-router.service, and it is the same single lchat binary as everything else, started with the router subcommand. Its full start command, exactly as the systemd unit runs it, is:

/opt/lchat/lchat router --registry /data/registry.db --acme-cache /data/acme

The two arguments name the two files the router depends on: the registry (its routing table) and the certificate cache (its TLS material). The router has three jobs, taken in turn below:

1. TLS: obtain and present the right certificate for every hostname it serves.
2. Routing: map each request’s hostname to the right unix socket and forward the request.
3. Hosting the activator and the mesh: when configured, wake sleeping instances (part 06) and cooperate with peer boxes (part 07). This page covers the first two; the other two have their own pages.

The registry: the routing table on disk

The router’s routing table lives in a small SQLite database, by default /data/registry.db, called the registry throughout this guide. It has one table, routes, with one row per hostname the box serves. The columns you will care about as an operator:

You rarely edit the registry directly — the command-line tools (lchat add-instance, lchat remove, and so on) do it for you, and lchat instances prints it in a readable form. But it is useful to know that the whole routing state of a box is one ordinary SQLite file you can inspect:

sqlite3 "file:/data/registry.db?mode=ro" "SELECT host, kind, status, version, hibernate FROM routes"
chat-a.example.com|instance|ready|1b4bd808|0
chat-b.example.com|instance|ready|1b4bd808|1
home.example.com|service|ready||0

How the router learns about changes

The router keeps the routing table in memory (swapped atomically, so a reload never drops an in-flight connection) and re-reads the registry in two ways:

• On a reload signal. systemctl reload lchat-router sends the process a HUP signal, and the unit’s ExecReload line is exactly that. The provisioning commands (add-instance, remove, hibernate) trigger this themselves, so you rarely type it.
• On a two-second poll. The router also fingerprints the registry file every two seconds and reloads if it changed. This exists because a change made by another process (for example the control daemon) must be picked up even if nobody sends a signal.

TLS certificates: automatic, two ways

The router obtains its certificates from Let’s Encrypt automatically. There are two mechanisms, and they coexist:

Per-host certificates, issued on first contact

By default the router uses the ACME HTTP-01 method: when a browser first connects for a hostname the router has never served, the router asks Let’s Encrypt for a certificate for exactly that hostname, answers the validation request Let’s Encrypt makes to port 80, and receives a certificate within a few seconds. Certificates (and their private keys) are cached on disk in /data/acme/ — one file per host — so this happens once per host, not once per connection.

Crucially, the router will only request a certificate for a hostname that exists in the registry with a serveable status. This rule (the “host policy”) prevents strangers from pointing arbitrary DNS names at your box and burning through Let’s Encrypt’s rate limits on your behalf.

A wildcard certificate for a whole domain

Per-host issuance rides Let’s Encrypt’s rate limit of roughly fifty new certificates per registered domain per week — a hard ceiling on how fast new spaces can be created. So the router can additionally hold a wildcard certificate (*.example.com), obtained with the ACME DNS-01 method, which covers every direct subdomain at once. Enable it by setting two variables in the router’s environment file, /data/router.env, then restarting the router:

LCHAT_WILDCARD_DOMAINS=example.com
LCHAT_DNSIMPLE_TOKEN=<a DNSimple account API token that can edit the example.com zone>

With this set, the router re-checks the wildcard certificate at startup and every twelve hours, renewing when it is missing or within thirty days of expiry. Issuance works by publishing a temporary DNS record (_acme-challenge.example.com) through the DNSimple API, which is why the token is needed. The certificate persists in the same /data/acme/ cache as wildcard-example.com.pem. Hostnames on other domains, and the apex domain itself, keep using the per-host path — and if wildcard issuance ever fails, per-host issuance quietly keeps covering those hosts too, so a DNS-provider outage degrades gracefully instead of taking the box down.

What the router does on each port

These are the only two public TCP ports on a box. The firewall guidance in part 08 allows exactly 80, 443, and the WireGuard port (51820, UDP) inbound, and nothing else — SSH is not publicly reachable at all; operators reach it only through the WireGuard tunnel, and WireGuard itself does not answer unauthenticated packets, so to a port scanner the box shows nothing but the web. running today

How a request is routed, step by step

1. A request arrives for, say, https://chat-a.example.com/api/version. The router strips any port from the hostname and looks chat-a.example.com up in its in-memory copy of the registry.
2. If the host is unknown (no ready row), the router answers 404 — or, if LCHAT_FALLBACK_URL is set in /data/router.env, redirects to that URL instead. The fallback pairs well with wildcard DNS: a mistyped or retired subdomain lands on your marketing site rather than an error page.
3. If the host is a normal (systemd-managed) route, the router opens a connection to the row’s unix socket and forwards the request, preserving the original hostname so the instance knows who it is.
4. If the host is flagged for hibernation, the request is handed to the activator inside the router, which may need to wake the instance first — the whole story is part 06.
5. If the box is in a mesh and the placement rule says another box owns this host, the request is forwarded to that box instead — part 07.

Why deploys do not drop requests

When an instance restarts (during a deploy), there is a brief moment when the old process has exited and the new one has not yet bound its socket. During that gap, the router’s connection attempts fail — and the router responds by retrying the connection for up to thirteen seconds before giving up. Thirteen seconds comfortably exceeds an instance’s shutdown drain (ten seconds) plus startup, so in practice a request arriving mid-deploy just waits a beat and then succeeds. This retry window is a load-bearing detail: it is what makes “restart the instance” a zero-downtime operation without any blue-green complexity.

The router also quietly strips two internal headers from every request before forwarding it (X-Lchat-Sidecar and X-Lchat-Mesh-Forwarded), so no outside client can forge the markers that bot sidecars and mesh peers use.

Configuring the router

The router reads optional configuration from /data/router.env (a plain KEY=value file; the unit declares it with a leading -, meaning the file may be absent). Everything it understands:

Checking on the router

# Is it running, and since when?
systemctl status lchat-router

# What has it logged recently? (-f follows live)
journalctl -u lchat-router -n 100

# Does it serve a known host end to end? (checks TLS, routing, and the instance)
curl -s https://chat-a.example.com/api/version
{"version":"a41c9f2","build":"1b4bd808"}

Because the activator runs inside the router, a hibernating fleet’s wake/sleep log lines also appear in journalctl -u lchat-router — that journal is the single most informative log on the box. Part 08 catalogues the log lines worth knowing.