Centinel AnalyticaCentinel Analytica
PlatformsWeb Server

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-dev headers. 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 and extract the package

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 VCL
  • example.vcl: a minimal site VCL that includes it
  • src/: source for the libvmod_centinel VMOD, which decodes block pages
  • autogen.sh, configure.ac, Makefile.am: the autotools build files
Build and install the VMOD

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 install

make 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.

Run a TLS proxy to the validator

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 verified

The 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.crt
stunnel /etc/stunnel/centinel.conf
Configure centinel.vcl

Copy centinel.vcl next to your VCL (for example /etc/varnish/) and edit it:

  1. Point the validator backend at the TLS proxy (127.0.0.1:8443).
  2. Set your secret key in vcl_backend_fetch (set bereq.http.X-API-Key = "...";).
  3. 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.

Include it from your VCL

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, unchanged

Varnish 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.

Load it
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=128k

Or on a running instance:

varnishadm vcl.load centinel /etc/varnish/default.vcl && varnishadm vcl.use centinel

The 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:

  1. Bypasses static assets. The regex in centinel_validate matches the path only, so a query string or ; parameter cannot fake an extension. Varnish caches these as usual.
  2. Validates GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS. Other methods, such as PURGE and BAN, and ESI fragments go straight to your VCL.
  3. Buffers a request body up to 1 MB so it still reaches your origin after the validator hop. A larger body gets 413.
  4. Rejects a malformed Host header with 400, because the validator cannot parse the URL.
  5. Reads the decision from x-centinel-* response headers. centinel.b64decode() decodes the block or interstitial page.
  6. Applies the decision:
    • allow: the original request continues into your vcl_recv
    • block: 403 and the block page
    • redirect: the interstitial page
  7. Forwards the validator's first Set-Cookie and 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

SettingWhereDefault
Secret keyvcl_backend_fetch → X-API-Keynone, required
Origin backendyour VCL, declared before the includeyour app
Validator backendbackend validatorTLS proxy → validator
Trusted proxiesacl centinel_trusted_proxylocalhost
Protected pathscentinel_validate static-asset regexstatic assets bypass
Block/interstitial pagefrom 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

On this page