Layer 4 vs Layer 7 Load Balancing Explained with HAProxy

Understanding the OSI Model Foundation

Before diving into HAProxy configuration, it helps to understand where Layers 4 and 7 sit within the OSI (Open Systems Interconnection) model. The OSI model organizes network communication into seven distinct layers, from the physical wire at Layer 1 through the application logic at Layer 7. Load balancers operate at different layers depending on how deeply they inspect and route traffic. The deeper a load balancer inspects, the more routing intelligence it gains — but at the cost of additional processing overhead.

Layer 4, the Transport Layer, deals with TCP and UDP segments. A Layer 4 load balancer has visibility into source and destination IP addresses, TCP and UDP port numbers, and connection state — but nothing above that. It cannot read HTTP headers, inspect URL paths, parse cookies, or evaluate any application-specific data embedded in the payload.

Layer 7, the Application Layer, is where HTTP, HTTPS, DNS, SMTP, and other high-level protocols live. A Layer 7 load balancer fully parses the application payload. It can inspect HTTP headers, evaluate URL paths, read cookies, rewrite content, and make routing decisions based on the full context of each individual request rather than treating a connection as an opaque byte stream.

HAProxy supports both models through its mode directive. Setting mode tcp activates Layer 4 behavior; mode http activates full Layer 7 HTTP proxying. Understanding when to use each mode — and how to configure it correctly — is fundamental to building scalable, efficient, and maintainable infrastructure.

How Layer 4 Load Balancing Works in HAProxy

In Layer 4 mode (mode tcp), HAProxy operates on raw TCP connections. When a client connects to the HAProxy virtual IP, HAProxy selects a backend server using its configured load-balancing algorithm and then proxies all TCP bytes bidirectionally between the two endpoints for the lifetime of that connection. HAProxy does not read or interpret the application-layer payload at any point — it simply moves bytes from one file descriptor to another.

Because HAProxy never parses traffic contents, Layer 4 mode is extremely fast and CPU-efficient. There is no HTTP parsing, no per-request buffer allocation, and no ACL evaluation against headers or URLs. The trade-off is a complete loss of application-layer visibility — routing decisions can only be based on IP addresses, port numbers, and connection-level state such as the number of active sessions to each backend.

By default, backend servers see the HAProxy IP as the connection source rather than the real client address. This is addressed by enabling the PROXY protocol, which prepends a small structured header to each proxied TCP stream carrying the original client IP and port. Backend software must be explicitly configured to parse this header.

Common Layer 4 use cases include:

• Relational database clusters — MySQL on port 3306, PostgreSQL on port 5432, and similar engines with proprietary wire protocols
• LDAP and LDAPS directory services
• SMTP mail relay and MTA clustering
• Custom binary TCP protocols used by financial trading systems, game servers, or embedded devices
• Any workload where raw throughput and sub-millisecond added latency take priority over application routing intelligence

Layer 4 HAProxy Configuration Example

The following configuration places HAProxy at 10.10.10.10 as a TCP load balancer for a three-node PostgreSQL cluster listening on port 5432. The leastconn algorithm is used because database sessions are long-lived and vary in resource consumption; leastconn routes each new connection to the server with the fewest active sessions rather than cycling blindly through backends with round-robin.

global
    log /dev/log local0
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin
    maxconn 50000
    user infrarunbook-admin
    group infrarunbook-admin
    daemon

defaults
    mode tcp
    log global
    option tcplog
    option dontlognull
    timeout connect 5s
    timeout client  30s
    timeout server  30s

frontend pgsql_frontend
    bind 10.10.10.10:5432
    default_backend pgsql_backend

backend pgsql_backend
    balance leastconn
    option tcp-check
    server db-01 10.10.10.21:5432 check inter 3s rise 2 fall 3
    server db-02 10.10.10.22:5432 check inter 3s rise 2 fall 3
    server db-03 10.10.10.23:5432 check inter 3s rise 2 fall 3

The option tcp-check directive instructs HAProxy to verify each backend by completing a TCP three-way handshake. A server is marked healthy after two consecutive successful checks (rise 2) and taken offline after three consecutive failures (fall 3). The inter 3s parameter sets the health probe interval to three seconds, balancing detection speed against backend check load.

The option dontlognull directive suppresses log entries for connections that send no data — useful for silencing monitoring system probes that perform bare TCP connects without transmitting a payload. The option tcplog enables a TCP-specific log format that records source IP, destination port, connection duration, and bytes transferred, giving you meaningful visibility even without application-layer context.

How Layer 7 Load Balancing Works in HAProxy

In Layer 7 mode (mode http), HAProxy acts as a full HTTP reverse proxy. It terminates the client's TCP connection entirely, reads and fully parses the HTTP request line, headers, and optionally the body, makes a routing decision based on that application-layer information, and then opens its own separate TCP connection to the selected backend server to forward the request. This two-leg connection model — client-to-HAProxy, then HAProxy-to-backend — is what makes Layer 7 both powerful and slightly more resource-intensive than Layer 4.

Because HAProxy has complete visibility into the HTTP layer, it can implement sophisticated routing logic through Access Control Lists (ACLs). ACLs allow matching on virtually any HTTP attribute: the Host header for virtual hosting across multiple domains, path prefixes for microservice routing, specific cookie values for session affinity, request method for separating read and write traffic, or custom request headers injected by upstream gateways.

Layer 7 mode also enables HAProxy to serve as an SSL/TLS terminator. When a client connects on port 443, HAProxy decrypts the TLS session, inspects the plaintext HTTP request, applies routing rules, and forwards plain HTTP to backend servers on the internal network. This centralizes certificate management and offloads TLS processing from every individual application server in the fleet.

Key Layer 7 capabilities include:

• Path-based routing — send

  /api/

  requests to a dedicated API server pool,

  /static/

  to a CDN origin pool, and everything else to the primary application tier
• Virtual hosting — route based on the HTTP Host header to serve multiple domains from one HAProxy instance without separate processes
• Cookie-based session persistence — insert a server-tracking cookie so user sessions consistently land on the same backend throughout their duration
• SSL/TLS termination — decrypt HTTPS at the load balancer and communicate over plain HTTP on the trusted internal network
• Header manipulation — add X-Forwarded-For, strip internal debug headers, or rewrite Location headers on redirect responses
• HTTP health checks — verify that a backend returns a specific HTTP status code or response body string, not merely that it accepts a TCP connection
• Rate limiting — enforce per-IP or per-URL request rate limits using stick tables backed by in-memory counters

Layer 7 HAProxy Configuration Example

The following configuration illustrates a production-grade HTTP load balancer for solvethenetwork.com. SSL/TLS terminates at the HAProxy frontend on sw-infrarunbook-01. Traffic is distributed to three distinct backend pools based on URL path using ACL rules evaluated in order at the frontend.

global
    log /dev/log local0
    chroot /var/lib/haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin
    maxconn 100000
    user infrarunbook-admin
    group infrarunbook-admin
    daemon
    tune.ssl.default-dh-param 2048

defaults
    mode http
    log global
    option httplog
    option dontlognull
    option forwardfor
    option http-server-close
    timeout connect 5s
    timeout client  60s
    timeout server  60s
    timeout http-request 15s
    timeout http-keep-alive 5s
    errorfile 503 /etc/haproxy/errors/503.http

frontend https_frontend
    bind 10.10.10.10:80
    bind 10.10.10.10:443 ssl crt /etc/haproxy/certs/solvethenetwork.com.pem alpn h2,http/1.1
    http-request redirect scheme https unless { ssl_fc }

    acl is_api    path_beg /api/
    acl is_static path_beg /static/ /assets/

    use_backend api_backend    if is_api
    use_backend static_backend if is_static
    default_backend app_backend

backend app_backend
    balance roundrobin
    option httpchk
    http-check send meth GET uri /health ver HTTP/1.1 hdr Host sw-infrarunbook-01
    http-check expect status 200
    cookie SRVID insert indirect nocache
    server app-01 10.10.10.31:8080 check inter 5s rise 2 fall 3 cookie app01
    server app-02 10.10.10.32:8080 check inter 5s rise 2 fall 3 cookie app02
    server app-03 10.10.10.33:8080 check inter 5s rise 2 fall 3 cookie app03

backend api_backend
    balance leastconn
    option httpchk
    http-check send meth GET uri /api/health ver HTTP/1.1 hdr Host sw-infrarunbook-01
    http-check expect status 200
    http-request set-header X-Backend-Pool api
    server api-01 10.10.10.41:8081 check inter 5s rise 2 fall 3
    server api-02 10.10.10.42:8081 check inter 5s rise 2 fall 3

backend static_backend
    balance roundrobin
    option httpchk
    http-check send meth GET uri /health ver HTTP/1.1 hdr Host sw-infrarunbook-01
    http-check expect status 200
    server static-01 10.10.10.51:8082 check inter 10s rise 2 fall 3
    server static-02 10.10.10.52:8082 check inter 10s rise 2 fall 3

The option forwardfor directive adds an X-Forwarded-For header carrying the real client IP to every proxied request. Backend application servers read this header to log accurate client addresses and apply IP-based logic such as geolocation or abuse detection. This is the Layer 7 equivalent of PROXY protocol in TCP mode, with the advantage of being natively understood by virtually all web frameworks without additional server-side configuration.

The option http-server-close enables a hybrid keep-alive model: HAProxy maintains persistent HTTP keep-alive connections toward clients while closing each backend connection after the server sends its response. This frees backend connection slots quickly and prevents the backend pool from accumulating idle socket handles, improving overall backend efficiency under high concurrency.

Cookie-based session persistence is configured with the cookie SRVID insert indirect nocache directive in the app_backend block. On a client's first request, HAProxy injects a Set-Cookie: SRVID=app01 header into the backend's response. On all subsequent requests from that client carrying the SRVID cookie, HAProxy bypasses the round-robin algorithm and routes directly to app-01 for the duration of the session. The indirect flag strips the cookie from the request before it reaches the backend, keeping the persistence mechanism transparent to the application.

Health Checks: TCP vs HTTP

Health check capability is one of the most operationally significant differences between Layer 4 and Layer 7 modes, and it directly affects how confidently you can trust that traffic is only sent to genuinely healthy backends.

In TCP mode, the default check is a TCP connect test activated by option tcp-check. HAProxy opens a connection to the backend IP and port. If the TCP three-way handshake completes successfully, the server is marked healthy. This is fast and imposes minimal load, but it only confirms that the operating system is accepting connections on that port — not that the application itself is functional. A PostgreSQL instance that accepts connections but fails all queries due to a full tablespace, an out-of-memory condition, or a corrupted data directory will still pass a TCP health check indefinitely.

In HTTP mode, option httpchk enables genuine application-level health verification. HAProxy sends a real HTTP request to each backend and evaluates the response. With http-check expect status 200, a server is only marked healthy when it returns an HTTP 200 OK. For richer validation, http-check expect string can assert that a specific substring appears in the response body, confirming that a JSON readiness endpoint is returning meaningful data rather than an empty or error response.

backend app_backend_advanced
    option httpchk
    http-check send meth GET uri /readyz ver HTTP/1.1 hdr Host sw-infrarunbook-01
    http-check expect status 200
    http-check expect string status:ready
    server app-01 10.10.10.31:8080 check inter 10s rise 2 fall 3
    server app-02 10.10.10.32:8080 check inter 10s rise 2 fall 3

Chaining multiple http-check expect lines performs an AND evaluation — the backend must satisfy all conditions simultaneously to be marked healthy. This allows you to assert both a correct HTTP status code and meaningful response body content in a single health check pass, catching application errors that would be invisible to a TCP-only probe.

Performance Characteristics

Layer 4 mode is fundamentally faster than Layer 7 because HAProxy does not need to parse application-layer data. In TCP mode, the load balancer splices bytes between two file descriptors without allocating request-scoped buffers, evaluating ACLs, or managing the HTTP state machine. On modern server hardware such as an 8-core system with 16 GB of RAM, HAProxy in TCP mode can handle millions of new connections per second with added latency measured in microseconds, not milliseconds.

Layer 7 introduces overhead that is measurable but rarely a production bottleneck. For each HTTP request, HAProxy must allocate a parse buffer (default 16 KB per side), read and parse the HTTP request line and all headers, evaluate frontend ACL rules in order, potentially manipulate headers, and manage two independent TCP connections. On the same hardware, HAProxy in HTTP mode routinely sustains 200,000 to 500,000 HTTP requests per second in benchmarks — a throughput ceiling that the vast majority of application backends cannot approach, meaning the load balancer itself is almost never the bottleneck.

For WebSocket connections in HTTP mode, HAProxy handles the initial HTTP Upgrade negotiation at Layer 7, applies ACL-based routing during the handshake phase, and then transitions the connection to a bidirectional TCP tunnel for the WebSocket data stream. This gives you Layer 7 routing intelligence for the connection setup and Layer 4 forwarding efficiency for the ongoing data transfer — the best of both modes in a single connection lifecycle.

Choosing Between Layer 4 and Layer 7

The practical decision comes down to two questions: what information do you need to make intelligent routing decisions, and what features must the load balancer provide beyond simple connection distribution?

Use Layer 4 (mode tcp) when:

• You are load balancing non-HTTP protocols — database connections, LDAP, SMTP, or proprietary binary protocols where HAProxy cannot parse the wire format
• Maximum throughput and minimal added latency are hard requirements
• SSL pass-through is required so that client certificates reach the backend servers intact and unmodified
• The protocol carries streaming binary data that must not be buffered or parsed at the proxy level
• Long-lived stateful TCP sessions need to persist without any proxy-level interference

Use Layer 7 (mode http) when:

• You are load balancing HTTP or HTTPS application traffic where routing decisions benefit from request context
• Content-based routing by URL path, Host header, query string, or custom header is required
• SSL/TLS should terminate at the load balancer rather than at each individual backend server
• Cookie-based or header-based session persistence is needed to support stateful application tiers
• Detailed HTTP-level access logging with method, URL, status code, and response time is required for observability
• Rate limiting, request rewriting, response header manipulation, or compression is needed at the proxy layer
• WebSocket connections need to be proxied with HTTP-level ACL routing on the upgrade handshake

Combining Both Modes in a Single HAProxy Instance

A production HAProxy deployment can simultaneously serve TCP and HTTP frontends from the same process. The defaults section sets a baseline mode, but individual frontend and backend blocks override it freely. The following example shows a single HAProxy instance on sw-infrarunbook-01 handling HTTPS application traffic in HTTP mode alongside a MySQL active-passive pair in TCP mode.

defaults
    mode http
    log global
    option httplog
    timeout connect 5s
    timeout client  60s
    timeout server  60s

frontend web_frontend
    bind 10.10.10.10:443 ssl crt /etc/haproxy/certs/solvethenetwork.com.pem alpn h2,http/1.1
    option forwardfor
    default_backend web_backend

backend web_backend
    balance roundrobin
    option httpchk
    http-check send meth GET uri /health ver HTTP/1.1 hdr Host sw-infrarunbook-01
    http-check expect status 200
    server web-01 10.10.10.31:8080 check inter 5s rise 2 fall 3
    server web-02 10.10.10.32:8080 check inter 5s rise 2 fall 3

frontend mysql_frontend
    bind 10.10.10.10:3306
    mode tcp
    default_backend mysql_backend

backend mysql_backend
    mode tcp
    balance leastconn
    option tcp-check
    server mysql-primary 10.10.10.61:3306 check inter 5s rise 2 fall 3
    server mysql-replica 10.10.10.62:3306 check inter 5s rise 2 fall 3 backup

When overriding the mode from the defaults block, both the frontend and its corresponding backend must explicitly declare mode tcp. HAProxy emits a warning during configuration validation if a frontend and its backend have mismatched modes. In this configuration, mysql-replica is designated with the backup keyword — it receives no connections while mysql-primary is healthy, and automatically absorbs all traffic the moment the primary fails its health checks. This provides active-passive database failover at the load balancer layer without requiring application-level connection retry logic or external orchestration.

PROXY Protocol: Preserving Real Client IPs in TCP Mode

One persistent challenge with Layer 4 load balancing is that backend servers see the HAProxy IP as the client source address. This breaks IP-based logging, access control lists at the application level, and rate limiting logic that depends on the real client address. The PROXY protocol solves this by prepending a structured header to the beginning of the TCP stream that carries the original client IP, client port, destination IP, and destination port.

HAProxy supports sending PROXY protocol v1 (human-readable text) or v2 (compact binary) by appending send-proxy or send-proxy-v2 to backend server lines. The backend application must be configured to accept and parse this header before reading the rest of the stream.

backend pgsql_backend_proxy
    mode tcp
    balance leastconn
    option tcp-check
    server db-01 10.10.10.21:5432 check inter 3s rise 2 fall 3 send-proxy-v2
    server db-02 10.10.10.22:5432 check inter 3s rise 2 fall 3 send-proxy-v2
    server db-03 10.10.10.23:5432 check inter 3s rise 2 fall 3 send-proxy-v2

For PostgreSQL, PROXY protocol support is enabled via the proxy_protocol parameter in the listen stanza of pg_hba.conf. For NGINX in stream proxy mode, the proxy_protocol on directive activates parsing. Not all backend software supports PROXY protocol — check the documentation before enabling it. In HTTP mode, option forwardfor is universally supported by web frameworks and remains the preferred mechanism for passing client IP information to application servers.

Frequently Asked Questions

Q: What is the fundamental difference between Layer 4 and Layer 7 load balancing in HAProxy?

A: Layer 4 (mode tcp) operates on raw TCP connections without inspecting the application payload. HAProxy makes routing decisions based only on IP address, port, and connection state, then forwards bytes unchanged between client and server. Layer 7 (mode http) fully parses each HTTP request, making routing decisions based on headers, URL paths, cookies, and other application-layer attributes. Layer 4 is faster with lower overhead; Layer 7 is smarter and supports a far richer set of traffic management features.

Q: Which HAProxy mode should I use for HTTPS traffic?

A: Use mode http with SSL termination at the frontend bind line when you want content-based routing, HTTP health checks, cookie persistence, or header manipulation. HAProxy decrypts TLS and forwards plain HTTP to backends. Use mode tcp only when you need SSL pass-through — for example, when backend servers require client certificate authentication, or when end-to-end encryption must be maintained without the load balancer seeing plaintext request content.

Q: Can HAProxy run both TCP and HTTP frontends in the same configuration file?

A: Yes. Each frontend and backend block can declare its own mode, overriding the value inherited from the defaults section. A single HAProxy process running on sw-infrarunbook-01 can simultaneously handle HTTPS application traffic in mode http and database or mail frontends in mode tcp, each with their own timeout values, health check strategies, and load-balancing algorithms. The only requirement is that a frontend and its corresponding backend must use the same mode.

Q: Does HAProxy Layer 7 mode support WebSocket connections?

A: Yes, natively. When HAProxy in HTTP mode proxies a request that includes an Upgrade: websocket header, it forwards the upgrade handshake at Layer 7 — allowing ACL-based routing — and then transitions the established connection into a bidirectional TCP tunnel for the WebSocket data stream. No special backend configuration is needed beyond setting timeouts long enough to accommodate idle WebSocket connections without premature disconnection.

Q: How does cookie-based session persistence work in HAProxy Layer 7 mode?

A: Configure the cookie directive in a backend block. With insert mode, HAProxy appends a Set-Cookie header to the backend's first response, tagging it with the server identifier defined in the server line's cookie parameter. On all subsequent requests from that client carrying the cookie, HAProxy reads the tag and routes directly to the corresponding server, bypassing the configured balancing algorithm. The indirect flag removes the cookie before the request reaches the backend, keeping the persistence mechanism invisible to the application.

Q: What is the performance overhead of Layer 7 compared to Layer 4 in HAProxy?

A: Layer 7 requires HTTP parsing, per-request buffer allocation, ACL evaluation, and two-leg connection management — all adding CPU and memory overhead relative to Layer 4's byte-forwarding model. In practice, HAProxy in HTTP mode handles hundreds of thousands of requests per second on modern hardware, which comfortably exceeds the throughput of typical application backends. The overhead is real but rarely the bottleneck. It only becomes a concern at extremely high sustained request rates or on hardware with very limited CPU resources.

Q: How do I preserve the real client IP address when using HAProxy in Layer 4 TCP mode?

A: Enable the PROXY protocol by adding send-proxy (v1 text format) or send-proxy-v2 (v2 binary format) to each server line in the backend block. HAProxy will prepend a PROXY protocol header to every outbound TCP connection carrying the original client IP and port. The backend application must be explicitly configured to parse this header — for example, the proxy_protocol listen parameter in PostgreSQL or the proxy_protocol on directive in NGINX stream blocks.

Q: What are the health check options available in TCP mode versus HTTP mode?

A: In TCP mode, option tcp-check performs a connect test — HAProxy opens a TCP connection and marks the server healthy if the handshake succeeds. You can extend this with TCP check sequences that send and receive specific byte strings, useful for verifying Redis with a PING command or checking a custom protocol greeting. In HTTP mode, option httpchk combined with http-check send and http-check expect sends a real HTTP request and asserts on the response status code or body content, providing genuine application-level health verification.

Q: When should I use leastconn instead of roundrobin in HAProxy?

A: Use leastconn when connections are long-lived or when request processing time varies significantly between requests. Database sessions, WebSocket connections, large file uploads, and streaming endpoints all benefit from leastconn because round-robin can pile new connections onto a backend that is already saturated with slow, long-running sessions while another backend sits comparatively idle. Use roundrobin for short-lived HTTP requests where each request takes roughly the same time to process — it has lower scheduling overhead and distributes load evenly when request durations are uniform.

Q: Can I route traffic to different backends based on the domain name in HAProxy Layer 7 mode?

A: Yes. Use an ACL matching the HTTP Host header. For example, acl is_api hdr(host) -i api.solvethenetwork.com followed by use_backend api_backend if is_api routes all requests to api.solvethenetwork.com to a dedicated backend pool. A single HAProxy frontend bound to one IP and port can act as a virtual host dispatcher for many domains simultaneously, routing each to an independent backend without requiring separate HAProxy processes or IP addresses per hostname.

Q: Does mode http work for non-HTTP protocols?

A: No. Mode http is strictly for HTTP/1.x and HTTP/2 (negotiated via ALPN on TLS connections). Attempting to use mode http with a non-HTTP protocol — a database wire protocol, SMTP, or a custom binary format — will result in HAProxy failing to parse the stream, generating parse errors in the logs, and closing connections prematurely. For any non-HTTP protocol, use mode tcp. For HTTP/3 over QUIC, HAProxy does not currently support QUIC natively; QUIC traffic must be handled upstream by a separate component.

Q: How do I troubleshoot Layer 7 routing problems in HAProxy?

A: Start by confirming that option httplog is active in your defaults or frontend block — HAProxy's HTTP log format records the request method, URL, response status, bytes transferred, backend name, and server name, which immediately shows whether traffic is reaching the intended backend. For ACL debugging, temporarily add http-request capture req.hdr(Host) len 64 and http-request capture path len 128 to the frontend to log the Host header and path values being evaluated against your ACLs. The HAProxy stats page, configured on a dedicated frontend listening on a management IP like 10.10.10.10 on port 8404, provides a real-time view of connection counts, health status, and server weights for every backend pool.