Reverse proxy
A reverse proxy receives requests from clients and passes them to one or more application servers behind it, called upstreams. This page shows how to proxy a site or part of it, spread load across upstreams, detect failed upstreams, and secure and time-limit the connection to them.
Proxy a whole site to one application
server {
listen ":443"
listen ":80" redirect-https=#true
tls {
acme {
email "[email protected]"
}
}
}
site "app.example.com" {
route "/*" {
reverse-proxy {
upstream "http://127.0.0.1:8080"
}
}
}
This passes check --strict. MiraServe terminates TLS, applies the site's security checks and headers, and forwards each request to the application on port 8080 of the same machine.
The request path and query string are forwarded unchanged. If the upstream URL has a path, it is put in front: with upstream "http://127.0.0.1:8080/api", a request for /v1/users goes to /api/v1/users. Requests whose path contains . or .. segments, backslashes, NUL bytes or encoded forms of these are refused with 400 before they reach the upstream.
Several upstreams and load balancing
Repeat upstream for each backend, and choose how requests are spread with lb-policy:
site "example.com" {
root "/var/www/example"
route "/api/*" {
reverse-proxy {
upstream "https://10.0.1.30:8443" weight=3
upstream "https://10.0.1.31:8443"
lb-policy "least-conn"
health-check path="/healthz" interval="5s" timeout="2s" unhealthy-threshold=3
}
}
}
"round-robin"(default) takes upstreams in turn. An upstream withweight=3gets three turns for every one of an upstream with weight 1."least-conn"picks the upstream with the fewest requests in progress, scaled by weight."random"picks at random, scaled by weight.
Only upstreams currently considered healthy are chosen. If none is, the client gets 503 Service Unavailable.
Health checks
health-check makes MiraServe send GET to path on every upstream once per interval:
- A
2xxor3xxanswer withintimeoutcounts as healthy. Withouttimeout, the limit is half the interval, but at least 250 ms.timeoutmust be shorter thaninterval(E305). - After
unhealthy-thresholdfailures in a row (default 3), the upstream stops receiving traffic. One successful check brings it back. - With a health check configured, failed proxied requests also count: connection errors and timeouts on real traffic add to the same threshold.
Without health-check, upstreams are never taken out of rotation. A dead upstream then keeps receiving its share of requests, which fail with 502 or 504.
Streaming and Server-Sent Events
MiraServe forwards response data to the client as it arrives from the upstream; it does not wait for the whole response. This suits Server-Sent Events (SSE) and token-by-token output from language model APIs. For such routes, set streaming-flush "immediate":
site "ai.example.com" {
route "/v1/*" {
reverse-proxy {
upstream "http://127.0.0.1:8000"
streaming-flush "immediate"
}
}
}
In the current version, "immediate" and "buffered" forward data the same way; "immediate" additionally adds X-Accel-Buffering: no to the response so that other proxies and CDNs in the path do not hold the stream back.
A stream that sends nothing for longer than upstream-body-idle-timeout (default 60 seconds) is cut off. For long-lived event streams, have the application send a comment line (: keep-alive) more often than that, or raise the timeout.
WebSocket
WebSocket works on every reverse-proxy route without extra settings. MiraServe accepts the upgrade only on an HTTP/1.1 GET request with Upgrade: websocket, a Sec-WebSocket-Key and Sec-WebSocket-Version: 13. When the upstream answers 101 Switching Protocols, MiraServe connects the two sides directly.
- A WebSocket connection is closed after one hour, whatever its activity. This limit is fixed in the current version; clients should reconnect.
- An upstream that answers
101to a request that did not ask for an upgrade gets502instead.
Upstream TLS and mTLS
Use an https:// upstream URL to encrypt traffic to the backend. MiraServe then connects with TLS 1.3 only, prefers post-quantum key exchange, and checks the backend's certificate against the host name or IP address in the URL. By default it trusts the operating system's CA store. To trust your own internal CA instead, or to present a client certificate to the backend (mTLS), add upstream-tls:
site "example.com" {
route "/*" {
reverse-proxy {
upstream "https://backend.internal.example:8443"
upstream-tls {
ca-cert "/etc/miraserve/certs/internal-ca.pem"
client-cert "/etc/miraserve/certs/proxy-client.crt"
client-key "/etc/miraserve/certs/proxy-client.key"
}
}
}
}
- When
ca-certis set, only that bundle is trusted; the system CA store is not used for this route. client-certandclient-keymust be set together (E105).- A plain
http://upstream on a host that is not loopback produces warningW005, because the traffic crosses the network unencrypted.
Timeouts
The upstream timeouts are set once, in the timeouts block of server, and apply to every reverse proxy and MCP gateway route. There is no per-route override.
server {
listen ":443"
tls {
cert "/etc/miraserve/certs/example.com.crt"
key "/etc/miraserve/certs/example.com.key"
}
timeouts {
upstream-connect-timeout "5s"
upstream-response-timeout "120s"
upstream-body-idle-timeout "5m"
}
}
site "example.com" {
route "/*" {
reverse-proxy {
upstream "http://127.0.0.1:8080"
}
}
}
Directive (in server.timeouts) | Default | Meaning |
|---|---|---|
upstream-connect-timeout | "10s" | Time to open the TCP connection and finish the TLS handshake with the upstream. Maximum "120s". |
upstream-response-timeout | "60s" | Time to wait for the upstream's response headers after the request body has been sent, and the longest the upstream may stall while receiving the body. Maximum "3600s". |
upstream-body-idle-timeout | "60s" | Longest gap between two pieces of the response body. Maximum "3600s". |
A timeout returns 504 Gateway Timeout; a failed connection returns 502 Bad Gateway. Uploads are also limited by max-body-bytes in server.limits (default "10MiB", answered with 413) and by the client upload guards body-idle-timeout and min-body-rate-bps.
Headers MiraServe changes
On the request to the upstream:
Hostis set to the host and port of the upstream URL. The host the client asked for is sent inX-Forwarded-Host.X-Forwarded-Foris set to the client's IP address, replacing any value the client sent.X-Forwarded-Protois set tohttporhttps.- Client-supplied
X-Real-IP,ForwardedandX-Forwarded-Portare removed. - Hop-by-hop headers are removed:
Connection,Keep-Alive,Proxy-Connection,HTTP2-Settings,Proxy-Authenticate,Proxy-Authorization,TE(exceptTE: trailers, which gRPC needs),Trailer,Transfer-EncodingandUpgrade(except for WebSocket). Headers named inConnectionare removed too, except protected ones such asAuthorization,Cookieand the forwarding headers, which a client cannot strip this way. - All other headers, including
AuthorizationandCookie, are passed through.
On the response to the client, hop-by-hop headers and any Alt-Svc from the upstream are removed, and the site's security headers are applied: with "strict" they replace the upstream's values, with "standard" they fill in only missing ones. Error responses from the upstream are passed through as they are; only errors MiraServe produces itself (such as 502, 503 and 504) use the site's error pages.
Reference
Directive (in reverse-proxy) | Default | Meaning |
|---|---|---|
upstream "<url>" weight=<n> | required; weight=1 | Backend URL (http:// or https://). Repeat for more backends. Weight must be at least 1. |
lb-policy | "round-robin" | "round-robin", "least-conn" or "random". |
health-check | none | Properties path= (required, starts with /), interval= (required), timeout= (half the interval, at least 250 ms), unhealthy-threshold= (3). |
streaming-flush | "buffered" | "buffered" or "immediate". |
upstream-tls { … } | none | ca-cert, client-cert, client-key (PEM paths). |
Pitfalls
- The backend sees a different
Host. Applications that build links or check the host fromHostsee the upstream's address. Configure them to readX-Forwarded-HostandX-Forwarded-Proto. - MiraServe behind another proxy. MiraServe always replaces
X-Forwarded-Forwith the address of its direct peer. If a load balancer or CDN sits in front of MiraServe, the backend sees that device's address, not the visitor's. - HTTPS upstream by IP address. With
upstream "https://10.0.1.30:8443", the backend certificate must contain that IP address, or the connection fails with502. - TLS 1.2-only backends. Upstream connections use TLS 1.3 only. Older backends that cannot speak it fail with
502. - Silent event streams. SSE or long-polling responses that pause longer than
upstream-body-idle-timeoutare cut off. - No health check. Without one, a failed upstream keeps getting traffic.