Varnish
Bot protection for Varnish Cache 6.0 LTS using a VCL config and a small helper VMOD.
Overview
Centinel integrates with Varnish through VCL. Protected requests are routed to the Centinel validator as a normal Varnish backend fetch, so Varnish's backend connection pool keeps the connection warm. The decision comes back in x-centinel-* response headers, so VCL never parses JSON. A small helper module (libvmod_centinel) base64-decodes the block or interstitial page for synth delivery and appends the validator's Set-Cookie without overwriting cookies from your origin. Blocked and challenged requests get a synthetic page. Allowed requests continue into your own VCL, so your backends, directors, and cache policy apply unchanged.
If the validator is unreachable, times out, or returns an error, requests fail open to your origin.
Backend TLS required
Open-source Varnish has no native backend TLS, and the validator is HTTPS. You must run a small local TLS proxy in front of validator.centinelanalytica.com and point the validator backend at it over plain HTTP on localhost. Reuse an nginx or HAProxy you already run, or add a ghostunnel sidecar; the install steps show both. Varnish Enterprise users can use a native TLS backend and skip the proxy. hitch won't work here: it only terminates inbound TLS and can't originate the outbound TLS this leg needs.
Prerequisites
- Secret key from your dashboard
- Varnish Cache 6.0 LTS (open source) or Varnish Enterprise 6, plus the matching
varnish-devheaders. Distro-stock Varnish 6.5 and 7.x are not supported: the VMOD is built with a strict ABI, so rebuild it after any Varnish upgrade. - Build tools:
autoconf,automake,libtool,pkg-config,python3-docutils - A local TLS proxy for the HTTPS validator (an existing nginx/HAProxy, or a ghostunnel sidecar)
- A configured origin backend
Install
Download centinel-varnish.zip and extract it:
curl -O https://docs.centinelanalytica.com/downloads/centinel-varnish.zip
unzip centinel-varnish.zip -d centinel-varnish/
cd centinel-varnish/The zip contains:
centinel.vcl: the Centinel VCL, which you include from your own VCLexample.vcl: a minimal site VCL that includes itsrc/: source for thelibvmod_centinelVMOD, which decodes block pagesautogen.sh,configure.ac,Makefile.am: the autotools build files
Debian and Ubuntu ship a newer Varnish and no varnish-dev package, so add the 6.0 LTS
repository and pin it. Without the pin, Debian 12 and Ubuntu 24.04 install their own
Varnish 7 and fail with varnish-dev : Depends: varnish (= 6.0.x). Then install the build
tools and build:
curl -s https://packagecloud.io/install/repositories/varnishcache/varnish60lts/script.deb.sh \
| sudo bash
printf 'Package: varnish varnish-dev\nPin: origin packagecloud.io\nPin-Priority: 1001\n' \
| sudo tee /etc/apt/preferences.d/varnish60lts
sudo apt-get install -y varnish varnish-dev \
build-essential automake autoconf libtool pkg-config python3-docutils
sh autogen.sh
./configure --disable-dependency-tracking
make
sudo make installmake install puts libvmod_centinel.so into Varnish's vmod directory.
Why --disable-dependency-tracking
The module includes the vmodtool-generated header, which doesn't exist when configure's dependency bootstrap runs. The flag defers that to the build step.
Open-source Varnish can't speak TLS to a backend, so a local proxy accepts plain HTTP on 127.0.0.1:8443 and originates TLS (with SNI) to the validator. All three options keep the validator connection warm under load; pick by what's already on the host.
If the host already runs nginx (or HAProxy), add a TLS-originating proxy. There's no extra daemon to run, and it used the least CPU and memory in our benchmark. The keepalive, proxy_ssl_session_reuse and Connection "" lines keep the upstream TLS connection warm. Don't drop proxy_ssl_verify or proxy_ssl_name: without them nginx sends the upstream group name as SNI and accepts any certificate, so anyone on the network path could pose as the validator and read your API key.
# nginx.conf
upstream centinel_validator { server validator.centinelanalytica.com:443; keepalive 16; }
server {
listen 127.0.0.1:8443;
location / {
proxy_pass https://centinel_validator;
proxy_ssl_protocols TLSv1.2 TLSv1.3; # nginx before 1.23.4 also offers TLS 1.0
proxy_ssl_server_name on; # SNI
proxy_ssl_name validator.centinelanalytica.com; # SNI defaults to the upstream name, not the host
proxy_ssl_verify on; # verify the validator's cert
proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
proxy_ssl_verify_depth 3;
proxy_ssl_session_reuse on;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host validator.centinelanalytica.com;
}
}HAProxy equivalent: a backend with server centinel validator.centinelanalytica.com:443 ssl sni str(validator.centinelanalytica.com) verify required ca-file /etc/ssl/certs/ca-certificates.crt plus http-reuse always.
ghostunnel is a maintained single-binary TLS proxy (Prometheus metrics, cert hot-reload, graceful restart):
ghostunnel client \
--listen 127.0.0.1:8443 \
--target validator.centinelanalytica.com:443 \
--disable-authentication # present no client cert; the server cert is still verifiedThe connection stays warm as long as Varnish keeps its (pooled) front-side connection open.
stunnel works too, though it used the most CPU of the options we measured:
# /etc/stunnel/centinel.conf
foreground = no
[centinel]
client = yes
accept = 127.0.0.1:8443
connect = validator.centinelanalytica.com:443
sni = validator.centinelanalytica.com
verifyChain = yes # sni alone does not verify the cert
checkHost = validator.centinelanalytica.com
CAfile = /etc/ssl/certs/ca-certificates.crtstunnel /etc/stunnel/centinel.confCopy centinel.vcl next to your VCL (for example /etc/varnish/) and edit it:
- Point the
validatorbackend at the TLS proxy (127.0.0.1:8443). - Set your secret key in
vcl_backend_fetch(set bereq.http.X-API-Key = "...";). - List the proxies in front of Varnish in
acl centinel_trusted_proxy(see Client IP behind a proxy).
backend validator {
.host = "127.0.0.1";
.port = "8443";
.max_connections = 200;
.connect_timeout = 3s;
.first_byte_timeout = 5s;
.between_bytes_timeout = 2s;
}Keep the three timeouts. Varnish defaults first_byte_timeout to 60s, so without them a hung
validator stalls each client request for a minute instead of failing open in five seconds.
Add one line to your site VCL, after your backend declarations and before your own subroutines:
vcl 4.1;
backend origin { .host = "127.0.0.1"; .port = "8080"; } # your first backend stays the default
include "centinel.vcl";
sub vcl_recv { ... } # your routing, directors and cache policy, unchangedVarnish runs same-named subroutines in include order, so Centinel validates the request
first and then hands the original request to your vcl_recv. No site VCL yet? Start from
the bundled example.vcl.
Declare your backends before the include. Varnish uses the first backend declared as the
default, and that must be your origin, not validator.
varnishd -f /etc/varnish/default.vcl -a :80 -s malloc,256m \
-p workspace_client=256k -p workspace_backend=256k \
-p http_resp_hdr_len=96k -p http_resp_size=128kOr on a running instance:
varnishadm vcl.load centinel /etc/varnish/default.vcl && varnishadm vcl.use centinelThe four -p values let a block page up to the validator's 64k cap through. With the
defaults, a page over about 23k fails the validator fetch and the request is allowed.
Configure
How it works
On every request, the VCL:
- Bypasses static assets. The regex in
centinel_validatematches the path only, so a query string or;parameter cannot fake an extension. Varnish caches these as usual. - Validates
GET,HEAD,POST,PUT,PATCH,DELETE, andOPTIONS. Other methods, such asPURGEandBAN, and ESI fragments go straight to your VCL. - Buffers a request body up to 1 MB so it still reaches your origin after the validator hop.
A larger body gets
413. - Rejects a malformed
Hostheader with400, because the validator cannot parse the URL. - Reads the decision from
x-centinel-*response headers.centinel.b64decode()decodes the block or interstitial page. - Applies the decision:
allow: the original request continues into yourvcl_recvblock: 403 and the block pageredirect: the interstitial page
- Forwards the validator's first
Set-Cookieand a fixed set of response headers (Content-Type,Cache-Control,X-Content-Type-Options,X-Frame-Options,Content-Security-Policy,Referrer-Policy).
The client's Cookie (other than _centinel) and Authorization headers are never sent to
the validator. Your origin still receives them.
Caching and the validator
Allowed requests follow your own cache policy, so cached pages stay cached and your origin sees no extra traffic. The validator is still called on every protected request, including cache hits, so a bot cannot read a cached page. Each allowed request costs one internal restart. Directors, multiple storage backends, ESI, and tiered Varnish setups work unchanged.
Client IP behind a proxy
Varnish takes the client address from the TCP connection. If a TLS terminator, load balancer,
or another Varnish sits in front, add its address to acl centinel_trusted_proxy in
centinel.vcl. For a trusted peer, the VCL reads the client IP from the last
X-Forwarded-For entry that peer added and honours X-Forwarded-Proto: https. For any other
peer, both headers are ignored, so a client cannot choose the IP the validator scores.
acl centinel_trusted_proxy {
"127.0.0.1";
"::1";
"10.0.0.0"/8; # your load balancers
}Pure VCL cannot modify a response body, so this integration does not inject the browser script. Add the script tag to your HTML yourself, or use Fastly Compute if you want it injected for you.
Configuration reference
| Setting | Where | Default |
|---|---|---|
| Secret key | vcl_backend_fetch → X-API-Key | none, required |
| Origin backend | your VCL, declared before the include | your app |
| Validator backend | backend validator | TLS proxy → validator |
| Trusted proxies | acl centinel_trusted_proxy | localhost |
| Protected paths | centinel_validate static-asset regex | static assets bypass |
| Block/interstitial page | from the validator (x-centinel-response-html-b64) | served via synth |
Keep-alive & tuning
Varnish pools the localhost hop to the proxy on its own (.max_connections on the validator backend). The proxy has to keep its upstream TLS connection open so the handshake happens once, not on every request. nginx does this with keepalive and proxy_ssl_session_reuse, HAProxy with http-reuse always. stunnel and ghostunnel stay warm as long as Varnish keeps its pooled connection to them.
On low-traffic sites, Varnish closes idle backend connections after backend_idle_timeout (60s by default). Raise it, for example -p backend_idle_timeout=300, so a quiet spell doesn't cost a fresh TLS handshake.
The block or interstitial page arrives in a response header (x-centinel-response-html-b64). Varnish caps a single header (http_resp_hdr_len, 8k by default) and all headers together (http_resp_size, 32k by default). If the page goes over either, the fetch fails and the request is let through, so keep the four -p values from the launch command. The validator never sends more than 64k of HTML; a bigger page is replaced with a short generic one.
Varnish keeps at most 64 headers per request (http_max_hdr). A request that comes close is refused instead of reaching the validator without its key. If real clients send more than about 40 headers, raise -p http_max_hdr.
The cookie attributes are fixed. The VCL forwards only the first cookie, as Path=/; HttpOnly; SameSite=Lax; Max-Age=86400, and adds Secure when the request came in over HTTPS. The validator's own attributes are dropped on this platform.
Verify
Confirm the VCL loaded, watch the validator hop, then send a request that should be denied:
varnishadm vcl.list
varnishlog -g request -q 'ReqURL eq "/validate"'
curl -s -o /dev/null -w '%{http_code}\n' -A 'python-requests/2.31' http://localhost/If the VMOD will not load, it was built against a different Varnish version; rebuild it. If
everything is allowed, check that the validator backend is healthy and that
http_resp_hdr_len is large enough for your block page, since an oversized header fails the fetch
and the request is let through.
Changelog
- v1.1.0 — Includable VCL, bypass fixes
- v1.0.1 — TLS proxy and keep-alive guidance
- v1.0.0 — Initial release