DocsReferenceLimits & timeouts

Limits & timeouts

Every cap in this page is flag-overridable, but the defaults are chosen deliberately — each one guards against a specific failure mode, not a round number picked for its own sake.

HTTP server timeouts#

ReadHeaderTimeoutdurationdefault: 10s
Guards against slowloris-style clients that trickle headers in one byte at a time.
IdleTimeoutdurationdefault: 120s
Public keep-alive idle timeout. Guards against file-descriptor exhaustion from idle connections.
MaxHeaderBytesbytesdefault: 64 KiB
Guards against header bombs.
ResponseHeaderTimeoutdurationdefault: 30s
How long the edge waits for the local app to start responding before returning 504. Guards against a hung local app. Post-header response duration is unlimited by design — streaming downloads and SSE need that, and a client disconnect cancels the request context anyway.
Dial-to-agentdurationdefault: 5s
Budget for opening the yamux stream and writing its preamble. Times out to 502 if the session is wedged.
-client-idle-timeoutdurationdefault: 60s
How long one read of a request body, or one write of a response, may wait on the public client. A client that stops sending its upload gets 408; one that stops reading its response is disconnected. Either way its request slots are freed. The deadline applies only while a read or write is blocked, so long uploads, SSE streams and WebSockets that keep moving are unaffected.
-tcp-idle-timeoutdurationdefault: 30m
Closes a TCP tunnel connection that has carried no bytes in either direction for this long. A connection busy in only one direction, such as a download, stays open. Raise it, or enable keepalives such as SSH's ServerAliveInterval, for sessions that sit idle longer.

Body limits#

Declared body capbytesdefault: 256 MiB
Checked against Content-Length before the request is proxied at all — this is the real 413, and it covers every well-behaved client.
Streaming body capbytesdefault: 256 MiB
Enforced via MaxBytesReader for chunked or unknown-length bodies, surfaced as 413 from a custom ErrorHandler that type-checks *http.MaxBytesError.
-webhook-max-body-bytesbytesdefault: 1 MiB
Largest body the edge buffers to verify a webhook signature (capped by -max-body-bytes). Larger bodies get 413.
-webhook-buffer-bytesbytesdefault: 64 MiB
Total memory all in-flight webhook verifications may hold. The edge reserves a request's declared length (or the full per-request cap for chunked bodies) before reading it; when the budget is spent it answers 503 with Retry-After and counts ngstoned_rejected_webhook_buffer_total. Must be at least -webhook-max-body-bytes.

A chunked 413 may ship a partial body

The naive design — relying on MaxBytesReader alone — returns 502, not 413, because the trip surfaces as a request-body read error inside RoundTrip after headers and up to 256 MiB have already reached the agent. With both checks in place the chunked path still means the agent may have already forwarded a partial body to the local app before the edge cuts it off.

Rate limiting#

Per-IP rate limittoken bucketdefault: 20 req/s, burst 50
Backed by an LRU of 10k IPs. Exceeding it returns 429.
Auth attemptsratedefault: 5 / IP / minute
Applies to the control-plane authentication handshake on :4443.

Concurrency & the window budget#

Global in-flight semaphoreintdefault: 64
The total memory ceiling for the system — see the callout below.
Per-session concurrent streamsintdefault: 48
Its own semaphore, beneath the global one, so one tunnel can't monopolize the edge. Exceeding it returns 429.
-per-ip-inflightintdefault: 32
In-flight HTTP requests plus TCP tunnel connections one client address may hold at once, across every tunnel on the edge (IPv6 is grouped by /48, like the rate limiter). Without it, one client could take every per-session or global slot with slow or idle connections. Exceeding it returns 429, or closes the TCP connection.
yamux AcceptBacklogintdefault: 512
Deliberately set above both caps — see the callout below.
Peak tunnel bufferingbytesdefault: 64 MiB per side
64 concurrent streams × a 1 MiB yamux receive window each — the largest buffer in the system.

AcceptBacklog is not the concurrency cap

It's an easy and expensive misreading. AcceptBacklog is the depth of yamux's accept queue; when it's full, a new stream gets RST'd — a 502the client can't interpret, instead of the 429 the system intends. Concurrency is enforced by the per-session (48) and global (64) semaphores instead, with AcceptBacklog set comfortably above both (512) so it never becomes the binding constraint. The yamux receive window is itself a buffer — each open stream may hold up to its window of received-but-unread bytes on both machines, so concurrency × window is the number that matters, not either alone.

The upgrade budget#

A WebSocket upgrade or an SSE stream would otherwise hold one of the semaphores above for its entire life, starving ordinary HTTP requests behind it. The edge detects a long-lived response — 101 Switching Protocols, or a 200 whose Content-Type is text/event-stream — and moves it onto this separate budget, releasing its global and per-session in-flight slot back to the pool. See WebSockets & SSE for the full picture.

-upgrade-inflightintdefault: 256
Global concurrent upgraded (WebSocket/SSE) connection cap, across every tunnel on the edge.
-per-session-upgradeintdefault: 32
Per-session concurrent upgraded connection cap, beneath the global one.

A connection that can't be reclassified because either cap is exhausted is rejected outright with 503 Service Unavailable — it is not silently downgraded or left occupying a request slot — and ngstoned_rejected_upgrade_cap_total increments. ngstoned_active_upgrades is a live gauge of currently open upgraded connections.

Control-plane caps#

:4443 concurrent TLS handshakesintdefault: 16
Guards against an unauthenticated handshake flood.
:4443 unauthenticated sessionsintdefault: 32
Guards against slow-auth session hoarding. QUIC connections share both caps with TCP. An unauthenticated QUIC connection is closed no later than 5 s after admission and holds its slot until it is closed.
:4443 unauthenticated sessions per client addressintdefault: 4
Set with -unauth-per-addr; the default is a quarter of -handshake-concurrency, and never below 1. Counted per IPv4 address or per IPv6 /48 and shared by TCP, QUIC, WebSocket and forwarded control, where the address is the original client's. Stops one address from filling the handshake cap, though four addresses (or /48s) can still fill it. A refused client is turned away without any control reply: a TCP connection is closed, a QUIC connection is refused with CONNECTION_REFUSED, and a WebSocket upgrade gets 503 too many connections. Refusals are counted in ngstoned_rejected_unauth_per_addr_total. Many agents behind one NAT or one IPv6 /48 that start together can hit it.
QUIC handshake idle timeoutdurationdefault: 10s
Applies only with -quic. A QUIC handshake that stalls is dropped. The edge sends a QUIC Retry before it admits a connection, so the agent's first handshake reply arrives two round trips after it starts. The agent waits up to 10 s for it, and the whole handshake and authentication must fit in the 5 s pre-authentication budget after admission. A link with a round trip above about 4.5 s cannot connect over QUIC and should use TCP. Agents older than this release wait 5 s and are limited to about 2.5 s.
QUIC dial timeoutdurationdefault: 20s
Applies only with -quic. The agent's whole QUIC dial budget. With UDP blocked, a literal address fails after 10 s. A name with both an IPv4 and an IPv6 address tries IPv4 first and then IPv6, so it fails after up to 20 s. With more than two records the 20 s may run out after the first two.
QUIC max idle timeoutdurationdefault: 15s
Applies only with -quic. A peer that vanishes without a clean close is noticed within about this long.
QUIC keep-alivedurationdefault: 5s
Applies only with -quic. Keeps an idle connection open and lets a vanished peer be detected.