# Varnish

> Bot protection for Varnish Cache 6.0 LTS using a VCL config and a small helper VMOD.

Source: https://docs.centinelanalytica.com/platforms/web-server/varnish

## 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](https://docs.centinelanalytica.com/install/dashboard.md)
* 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

1. **Download and extract the package**

   Download [centinel-varnish.zip](https://docs.centinelanalytica.com/downloads/centinel-varnish.zip) and extract it:

   ```bash
   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

2. **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:

   ```bash
   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.

3. **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.

   **Reuse nginx/HAProxy (recommended)**

   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
   # 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 sidecar**

   [ghostunnel](https://github.com/ghostunnel/ghostunnel) is a maintained single-binary TLS proxy (Prometheus metrics, cert hot-reload, graceful restart):

   ```bash
   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 (legacy)**

   stunnel works too, though it used the most CPU of the options we measured:

   ```ini
   # /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
   ```

   ```bash
   stunnel /etc/stunnel/centinel.conf
   ```

4. **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](#client-ip-behind-a-proxy)).

   ```c
   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.

5. **Include it from your VCL**

   Add one line to your site VCL, after your backend declarations and before your own
   subroutines:

   ```c
   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`.

6. **Load it**

   ```bash
   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:

   ```bash
   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.

```c
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](https://docs.centinelanalytica.com/install/scripts.md) 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:

```bash
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
