HAProxy maxconn hierarchy: global, frontend, backend, and per-server limits

HAProxy does not have one connection limit. It has four, enforced independently at the global, frontend, backend, and per-server levels. Any one of them can throttle traffic while the other three show headroom. This is why “global maxconn is at 30%” tells you almost nothing during an incident: the request path can be blocked at a per-server limit you never set, or queuing behind a backend constraint you did not know existed.

This is a reference for how each level works, its defaults, what happens when it is reached, and which stats fields expose it. It assumes you know the basic HAProxy request pipeline. If not, start with How HAProxy actually works in production.

What maxconn actually limits

A proxied request consumes two connections inside HAProxy: the client-side connection on the frontend and the server-side connection to the backend. Correspondingly, each proxied connection consumes roughly two file descriptors, plus FDs for listeners, the stats socket, log sockets, health checks, and peers. Every limit in the hierarchy is ultimately bounded by what the process can hold in file descriptors and memory.

Memory matters too. A fully buffered connection holds two buffers (request and response, each tune.bufsize, 16KB by default) plus roughly 20KB of connection metadata. Current HAProxy versions allocate buffers on demand, so idle connections cost less than this worst-case figure. Connection capacity is a three-way constraint: FDs, memory, and the configured maxconn values. The first one you run out of wins.

The four levels

The hierarchy is not a chain where one limit delegates to the next. Each level is an independent gate, and a request must pass all of them.

flowchart TD
  G["Global maxconn
process-wide, show info: Maxconn"]
  F["Frontend maxconn
per frontend, stats: slim on FRONTEND rows"]
  B["Backend fullconn
per backend, stats: slim on BACKEND rows"]
  S["Server maxconn
per server line, stats: slim on SERVER rows"]
  G --> F --> B --> S
  S --> Q["Per-server / per-backend queue
qcur, qtime"]
  F -.-> R["Reject when at limit"]

Global maxconn

Set with maxconn in the global section. This is the per-process ceiling on concurrent connections. It is the only level most teams monitor, which is the core mistake this article exists to correct.

If you do not set it, HAProxy derives it at startup from the file descriptor limit. The rough rule of thumb is (ulimit-n - listeners - 1) / 2, reflecting the two-FD-per-connection cost. Newer versions compute the value from current FD limits and memory constraints rather than a single fixed formula, so do not trust arithmetic: read the actual enforced value from the runtime API.

# Actual enforced global limits
echo "show info" | socat unix-connect:/var/run/haproxy.sock stdio | grep -E "^(CurrConns|Maxconn|Maxsock|Ulimit-n):"

Maxconn is the enforced connection limit, Maxsock is HAProxy’s internally calculated FD ceiling, and CurrConns is the current connection count. The ratio CurrConns / Maxconn is the global saturation signal. Because Maxconn counts both sides of the proxy, effective proxying capacity is roughly Maxconn / 2 minus overhead.

One reload trap: old processes hold their own FDs while draining. During a reload storm, the new process can show a clean CurrConns while the system FD limit is consumed by zombies.

Frontend maxconn

Set with maxconn in a frontend (or listen) section. It caps concurrent connections on that frontend only. The default inherits the global limit, so multiple frontends silently share one ceiling unless you carve them up.

When a frontend hits its limit, new connections to that listener are refused or stall in the kernel accept queue while other frontends keep working. This shows up in stats as scur approaching slim on the FRONTEND row, with dcon/dses (denied connections/sessions) incrementing.

Frontend maxconn is the right tool for protecting one listener from another: a noisy internal health-check frontend, an admin interface, or a second-tier vhost should not consume slots needed by the production frontend.

Backend: fullconn, not maxconn

There is no maxconn keyword for backend sections. The stats page shows a “Sessions Limit” on BACKEND rows, and operators reasonably assume it is a hard cap on backend concurrency. It is not.

The value shown is fullconn, which defaults to 10% of the sum of the maxconns of all frontends that route to that backend. Its actual role is narrower: it is the reference point for dynamic server maxconn scaling when you use minconn on server lines. When backend concurrency is below fullconn, servers operate at minconn; as concurrency approaches fullconn, per-server limits scale up toward maxconn. If you do not use minconn, fullconn is largely informational. It does not reject or queue traffic by itself.

Do not read the BACKEND row’s slim as backend connection capacity. Backend-level admission control is the aggregate of the per-server limits, covered next.

Per-server maxconn

Set with maxconn on each server line. This is the limit that actually protects your application, and its default is 0: unlimited. If you never set it, HAProxy will send unbounded concurrency to a server that very much has bounds: a thread pool, a worker count, a connection limit of its own.

This is the most common maxconn misconfiguration. Global maxconn has headroom, the frontend is fine, but the application degrades silently because nothing stopped HAProxy from piling 5,000 concurrent requests onto a server tuned for 200. Set per-server maxconn at or below what the application can handle, and let HAProxy’s queue absorb the excess instead of the application’s internals.

Two subtleties:

• In HTTP mode, per-server maxconn limits concurrent in-flight requests, not TCP connections. With HTTP/2 multiplexing to the backend, many requests share one TCP connection, so the connection count to the server can be far lower than request concurrency. If you need a TCP-level cap, the server and default-server keyword strict-maxconn (available since HAProxy 3.2) forces the TCP interpretation; without it, maxconn counts in-flight requests while idle connections may push the total connection count above maxconn.
• With http-reuse in effect, scur on a SERVER row counts connections, not in-flight requests. A server showing scur = 10 may be carrying many more concurrent requests.

What happens when a limit is reached

The levels fail differently, and confusing them wastes incident time.

The key diagnostic asymmetry: global and frontend saturation reject at the edge, while per-server saturation queues. Queuing is backpressure, and it is usually the behavior you want, because the alternative is the application falling over. But a queue is only tolerable if it drains. Sustained qcur with rising qtime means offered load exceeds what the per-server limits allow through, and the queue grows until timeouts turn waiting into 503s. With the default maxqueue of 0 the queue is unbounded, so the failure mode is latency and eventual timeout, not immediate rejection.

One more interaction: when a server fails and HAProxy redistributes its traffic, the surviving servers’ scur climbs toward their slim. Per-server maxconn that was generous at full fleet size becomes the bottleneck during partial failure. Size per-server limits with the N-1 case in mind.

Defaults and platform traps

Unset global maxconn in containers. Because the global limit is derived from the FD limit, anything that inflates ulimit -n inflates the derived maxconn and the memory HAProxy pre-allocates for its FD table. Docker Engine 23 raised the default hard nofile limit to 1073741816; HAProxy versions before fd-hard-limit existed (2.6+) could try to allocate an FD table for a billion entries and crash at startup. If you run HAProxy in a container, set an explicit maxconn, and on 2.6+ consider fd-hard-limit to cap the FD table regardless of what the container runtime reports. Also remove any vestigial ulimit-n setting left over from old configs; it is strongly discouraged in current versions.

The displayed default moved. Older HAProxy builds showed a compiled-in default (2000 in some 1.x builds). Current builds auto-derive, so haproxy -vv no longer tells you the enforced number. show info does.

Unlimited per-server is a choice, not a neutral default. Default 0 means “trust the application.” For a service with a hard worker pool, that trust is misplaced. Set the limit, accept the queue, monitor the queue.

Signals to watch in production

Monitor all four levels, not just global. Ratios, not absolutes.

A useful sanity check during any latency incident: pull scur/slim for every SERVER row before looking at anything global. Per-server saturation with global headroom is the signature this hierarchy produces, and it is invisible if you only graph CurrConns.

How Netdata helps

• Netdata collects the HAProxy stats CSV per row type, so global, frontend, backend, and per-server scur/slim are charted independently. You can see a per-server limit pinned at 100% while the global curve sits at 30%, without running socat by hand.
• Per-server and per-backend queue depth (qcur) and queue time (qtime) are time series, which makes the difference between a self-draining spike and a growing backlog obvious.
• Correlating frontend hrsp_5xx against backend hrsp_5xx separates HAProxy-generated 503s (queue timeouts, no available server) from application errors, which is the fork in the road for maxconn incidents.
• Ratio-based alerts on scur/slim at each level catch saturation at whichever gate trips first, instead of a single global threshold that hides per-server bottlenecks.
• ConnRate vs SessRate and dcon/dses trended together expose edge rejections from global or frontend limits that never show up as queuing.

Related guides

• How HAProxy actually works in production: a mental model for operators
• HAProxy monitoring checklist: the signals every production proxy needs
• HAProxy monitoring maturity model: from survival to expert