The “HAProxy in front of Varnish” topology is the boring, reliable answer for clients who need TLS termination, load balancing, and HTTP caching at the edge without buying a CDN. HAProxy handles the TLS handshake, certificate rotation, and load distribution; Varnish handles the cache; origin handles the application. This article is the install we run for clients in this exact shape — port layout, PROXY-protocol wiring, health checks, and the operational details.
How to verify
Inspect the listener layout and the upstream wiring on a deployed system.
ss -ltnp | grep -E ':(443|80|6081|8443)\b'
ps -fC haproxy
ps -fC varnishd
curl -sI -k https://localhost/ -H "Host: example.com" | grep -iE 'server|x-cache|via'
echo "show backend" | socat - /var/run/haproxy/admin.sock
varnishstat -1 -f MAIN.client_req -f MAIN.cache_hit -f MAIN.cache_miss
If HAProxy’s stats show its varnish backend as UP and Varnish reports requests, the stack is wired. If curl https://... succeeds but origin sees Varnish’s IP as the source, you have not configured PROXY protocol — Varnish sees HAProxy’s IP, origin sees Varnish’s IP, and the client IP is lost.
What’s happening
HAProxy terminates TLS on 443, optionally re-encrypts on the way out, and forwards plaintext HTTP to Varnish on a chosen port (6081 by default, or a Unix socket for lower latency). Varnish caches the response or fetches from origin. The PROXY protocol carries the client’s original IP from HAProxy to Varnish (and optionally to origin) so the application logs the real client.
Two listener layouts are common:
-
HAProxy 443 (TLS) -> Varnish 80 (HTTP) -> origin 8080. HAProxy is the only thing on 443; everything inside is HTTP. Simpler, but TLS is terminated entirely at the edge — internal hops are unencrypted.
-
HAProxy 443 (TLS) -> Varnish 80 (HTTP) -> HAProxy 8443 (re-encrypt) -> origin 443. The “TLS sandwich” — HAProxy terminates, hands plaintext to Varnish, then re-encrypts to origin. Useful when network policy requires encryption between nodes.
We default to the first. The “TLS sandwich” is the right answer when compliance or zero-trust networking demands it, not as a default.
The procedure
-
HAProxy frontend on 443 with TLS termination.
frontend fe_https bind :443 ssl crt /etc/haproxy/certs/app.example.com.pem alpn h2,http/1.1 bind :80 http-request redirect scheme https unless { ssl_fc } http-request set-header X-Forwarded-Proto https if { ssl_fc } http-request set-header X-Forwarded-Proto http unless { ssl_fc } default_backend be_varnish -
HAProxy backend points at Varnish with PROXY protocol.
backend be_varnish balance leastconn option httpchk GET /_health http-check expect status 200 server varnish1 127.0.0.1:8443 send-proxy check server varnish2 10.0.0.5:8443 send-proxy check backup -
Varnish accepts PROXY-protocol on a separate listener.
# In /etc/systemd/system/varnish.service.d/override.conf ExecStart=/usr/sbin/varnishd \ -j unix,user=vcache \ -F \ -a :80 \ -a localhost:8443,PROXY \ -T localhost:6082 \ -f /etc/varnish/default.vcl \ -s malloc,2g -
Varnish VCL forwards client IP from PROXY headers to origin.
sub vcl_recv { set req.http.X-Forwarded-For = client.ip; set req.http.X-Real-IP = client.ip; } sub vcl_backend_fetch { set bereq.http.X-Forwarded-For = bereq.http.X-Forwarded-For; } -
Validate the chain. Use a recognizable client IP for the test and check origin logs.
curl -sI -H "X-Test: chain" https://app.example.com/healthz tail -n 5 /var/log/origin/access.log | awk '{print $1, $7, $9}' # Expect the test client's IP, not 10.0.0.x of HAProxy/Varnish
Common pitfalls
- Forgetting
send-proxyon the HAProxy backend AND,PROXYon the Varnish listener — both must agree, otherwise Varnish parses the binary PROXY header as garbage HTTP and returns 503. - Mixing
send-proxyandsend-proxy-v2between HAProxy and Varnish — they speak the same family but the format differs; pick one explicitly. - TLS certificate rotation that swaps the file but does not signal HAProxy — use
kill -SIGUSR2or the runtime API to reload, do not restart. - Health-checking Varnish with a default URL that hits VCL and gets cached as a 200 forever — point the health check at a path that bypasses cache.
- Putting both HAProxy and Varnish on the same machine and not sizing them together — the kernel network stack and the Varnish cache compete for the same memory budget.
In the engagements we run, this stack is the workhorse edge for clients running self-hosted applications that need TLS, caching, and HA without buying a CDN. Stack Harbor’s managed operations practice is to own the certificate rotation, the VCL deploy pipeline, and the runbook for “when Varnish flaps.” See our HAProxy install article and the Varnish install article for the per-component installs that compose into this stack.