Haproxy Knowledge Patch

HAProxy Knowledge Patch

Use this skill for HAProxy configuration, migration, routing, Runtime API, Lua, logging, TLS, QUIC, health-check, and operations work involving the behaviors documented here. Determine the deployed branch and patch level, then apply only guidance that matches it.

Reference index

Breaking changes and migration priorities

Make proxy and server names unique

Duplicate names across frontend, listen, backend, defaults, and log-forward families, and duplicate server names, warned in 3.1 and became breaking in 3.3. Rename collisions before moving to 3.3.

Preserve the old balancing policy explicitly

A backend without balance uses random rather than roundrobin in 3.3. Configure the former policy explicitly when distribution must remain the same:

backend application
    balance roundrobin

Account for abort-on-close

HTTP backends enable option abortonclose by default in 3.3, allowing work to stop before an abandoned request reaches a server. The option is also valid in a frontend.

Update compression configuration

Request and response compression use filter comp-req and filter comp-res in 3.4. The shared compression filter and direction setting are replaced, and compression-direction is deprecated.

backend application
    filter comp-res
    compression algo gzip
    compression type text/html text/plain application/json

Use filter-sequence when execution order must differ from declaration order. A declared filter omitted from the sequence is skipped.

Replace deprecated dispatch forms

Ahead of planned 3.5 removal, replace dispatch <address> with a regular server named dispatch at the same address. Give other legacy servers weight zero when that is necessary to preserve dispatch behavior.

backend legacy_dispatch
    server dispatch 192.0.2.10:8080

Replace transparent or option transparent with a zero-address server to preserve routing to the original TPROXY address:

backend original_destination
    server tproxy 0.0.0.0

Update renamed and retired directives

• Replace global tune.quic.frontend.* names with tune.quic.fe.* names.
• Replace global no-quic with tune.quic.listen on or tune.quic.listen off.
• Replace the global master-worker directive with command-line -W or -Ws.
• Treat backend dispatch and option transparent as deprecated.
• program sections and legacy C mailers were deprecated in 3.1 with removal scheduled for 3.3; Lua mailers are the supported replacement after removal.
• OpenTracing is deprecated and scheduled for removal in 3.5; OpenTelemetry is available as its add-on replacement.

Fix configuration validation failures

• An ACL can no longer specify multiple match types after -m; the configuration fails instead of silently using the final type.
• Ambiguous combinations such as path_beg -m reg warn.
• http-send-name-header cannot target connection, content-length, host, or transfer-encoding.
• Empty arguments warn in 3.2 and were scheduled to become errors in the next version. Use ${NAME[*]} for an intentionally empty environment expansion.

Security and correctness priorities

Protect the statistics administration interface

Stats administration remains documented as vulnerable to CSRF. Stats POST requests validate Origin, and stats admin operations honor stats scope, so scoped administration cannot reach excluded proxies.

Bound TLS 1.3 KeyUpdate work

Use tune.ssl.keyupdate-rate-limit to place an explicit rate bound on peer-triggered TLS 1.3 KeyUpdate processing.

Apply protocol abuse controls

• quic-initial rules can reject, accept, silently drop a datagram with dgram-drop, or send-retry during the QUIC handshake.
• tune.glitches.kill.cpu-usage gates threshold-based connection termination by CPU usage; its default 0 kills at the configured threshold regardless of load.
• HTTP/2 frame and RST_STREAM batch limits can constrain overload and reset attacks. Values from 1 through 10 for tune.h2.fe.max-rst-at-once mitigate RST attacks, though very low values can add interactive or gRPC latency.
• HTTP/1 glitch thresholds exist independently for frontend and backend multiplexers; graceful close begins at 75% of the threshold when threshold-based termination is enabled.

Expect stricter Protobuf conversion

Protobuf lookup rejects nested-path bypasses and deprecated group wire types. Inputs relying on either behavior fail conversion.

Routing and health quick reference

Create a backend at runtime

A runtime-created backend is unavailable for routing until published. Build it, enable its server and health, and publish it:

add backend test-backend from mydefaults mode http
add server test-backend/server1 127.0.0.1:3000 check
enable server test-backend/server1
enable health test-backend/server1
publish backend test-backend

For safe removal, place every server in maintenance, wait for srv-removable, delete the servers, unpublish the backend, wait for be-removable, and delete the backend.

Reuse health-check definitions

A named healthcheck section can contain a supported check type and its http-check or tcp-check actions. Select it from a server with the healthcheck argument.

Select retry behavior dynamically

set-retries works in tcp-request and http-request rules. Custom stream timeouts and maximum retries remain initialized correctly after backend selection.

http-request set-retries 0 if METH_POST

Use retry-on 421 when a misdirected request should be retried against a different capable backend server.

Enforce a backend connection ceiling

Add server argument strict-maxconn when maxconn must count open TCP connections rather than concurrent HTTP requests.

TLS and QUIC quick reference

Attach policy to a certificate

Use frontend ssl-f-use to reference a certificate in crt-store and attach certificate-specific TLS versions, ALPN, ciphers, or signature algorithms without an external crt-list.

Handle automatic backend SNI

HAProxy derives server-side SNI from the HTTP host header in 3.3. sni-auto and no-sni-auto control traffic behavior; check-sni-auto and no-check-sni-auto control health checks.

Distinguish experimental transports

• Backend HTTP/3 uses a quic4@ server address and requires expose-experimental-directives plus normal backend TLS verification.
• QMux carries QUIC frames over an ordered reliable byte stream and requires expose-experimental-directives with alpn h3 on the relevant TCP bind or server line.
• Encrypted Client Hello uses the experimental ech bind argument, and clients must retrieve its public key from DNS.

Observability and runtime quick reference

Log at transaction stages

log profile assigns destination-specific formats at accept, request, connect, response, close, error, or any. do-log emits additional logs during processing and can select a profile per invocation in 3.4.

http-request do-log profile syslog

Use focused supported tracing

Tracing is supported and controlled through the Runtime API. Sources include h1, h2, h3, quic, qmux, fcgi, spop, peers, check, ssl, and acme.

Preserve statistics only across reloads

Experimental shared-memory statistics require expose-experimental-directives, shm-stats-file, and unique guid values on participating frontends, backends, and servers. They survive reloads but not process restarts.

Applying the references

Open the reference matching the current task before changing configuration. Keep version-dependent syntax tied to its stated introduction or transition, especially for compression, QUIC naming, balancing defaults, deprecations, and experimental features.