CheatPress

Varnish HTTP cache

Version 8.0 · source

Varnish, Postcard, light preview Light · Postcard 102 × 152 mm · PDF Varnish, Postcard, dark preview Dark · Postcard 102 × 152 mm · PDF Varnish, Postcard, ink saver preview Ink saver · Postcard 102 × 152 mm · PDF
Varnish, A5, light preview Light · A5 148 × 210 mm · PDF Varnish, A5, dark preview Dark · A5 148 × 210 mm · PDF Varnish, A5, ink saver preview Ink saver · A5 148 × 210 mm · PDF
Varnish, A4, light preview Light · A4 210 × 297 mm · PDF Varnish, A4, dark preview Dark · A4 210 × 297 mm · PDF Varnish, A4, ink saver preview Ink saver · A4 210 × 297 mm · PDF
Varnish, A4 landscape, light preview Light · A4 landscape 297 × 210 mm · PDF Varnish, A4 landscape, dark preview Dark · A4 landscape 297 × 210 mm · PDF Varnish, A4 landscape, ink saver preview Ink saver · A4 landscape 297 × 210 mm · PDF
Varnish, A3, light preview Light · A3 297 × 420 mm · PDF Varnish, A3, dark preview Dark · A3 297 × 420 mm · PDF Varnish, A3, ink saver preview Ink saver · A3 297 × 420 mm · PDF
Varnish, A3 landscape, light preview Light · A3 landscape 420 × 297 mm · PDF Varnish, A3 landscape, dark preview Dark · A3 landscape 420 × 297 mm · PDF Varnish, A3 landscape, ink saver preview Ink saver · A3 landscape 420 × 297 mm · PDF
Varnish, Letter, light preview Light · Letter 8.5 × 11 in · PDF Varnish, Letter, dark preview Dark · Letter 8.5 × 11 in · PDF Varnish, Letter, ink saver preview Ink saver · Letter 8.5 × 11 in · PDF
Varnish, Tabloid, light preview Light · Tabloid 11 × 17 in · PDF Varnish, Tabloid, dark preview Dark · Tabloid 11 × 17 in · PDF Varnish, Tabloid, ink saver preview Ink saver · Tabloid 11 × 17 in · PDF

Start here

varnishd -a :80 -f <file.vcl>
Start the cache
varnishadm vcl.load <name> <file>
Compile a VCL
varnishadm vcl.use <name>
Switch to it
varnishadm ban "<expr>"
Invalidate objects
varnishadm backend.list
Backend health
varnishstat -1
Counters once
varnishlog -g request
Grouped log
varnishtop -i ReqURL
Top URLs

Concepts

  1. Client HTTP request
  2. Cache hit: serve object
  3. Backend fetch, vcl_backend_response
  4. Client vcl_deliver

Run varnishd

varnishd -a :<port> -f <file.vcl>
Listen on a port with a VCL file
varnishd -a :<port> -b <host>:<port>
Quick start with a single backend
varnishd -T localhost:6082 -S <secretfile>
Open the management CLI
varnishd -s malloc,<size>
Cache in memory, e.g. malloc,1G
varnishd -V
Print the version

varnishadm

varnishadm
Interactive CLI to varnishd
varnishadm <command>
Run one CLI command
varnishadm -T <host>:<port> -S <secretfile>
Connect over the management port
varnishadm help
List all CLI commands
varnishadm status
Is the cache process running?

VCL management

varnishadm vcl.load <name> <file>
Compile and load a VCL
Loading does not activate it. A compile error leaves the running VCL untouched.
varnishadm vcl.use <name>
Make a loaded VCL active
varnishadm vcl.list
List VCLs, state and temperature
varnishadm vcl.show <name>
Print the VCL source
varnishadm vcl.discard <name>
Unload a VCL

Bans and purging

varnishadm ban req.url ~ "<regex>"
Invalidate by URL pattern
varnishadm ban req.http.host == "<host>" && req.url ~ "<regex>"
Combine conditions with &&
varnishadm ban.list
Show active bans
curl -X PURGE <url>
Purge one object via VCL
Needs a PURGE handler with return(purge) in vcl_recv, ideally ACL-protected.

Backends and health

varnishadm backend.list
List backends and health
varnishadm backend.list -p
Include probe details
varnishadm backend.set_health <backend> sick
Take a backend out of rotation
varnishadm backend.set_health <backend> auto
Return control to the probe

Parameters

varnishadm param.show
List parameters and values
varnishadm param.show changed
Only non-default parameters
varnishadm param.set <param> <value>
Change a parameter live

varnishstat

varnishstat
Live counters (curses)
varnishstat -1
Print all counters once
varnishstat -1 -f MAIN.cache_hit -f MAIN.cache_miss
Select counters (globs)
MAIN.cache_hit, MAIN.cache_miss
Compute the hit ratio

varnishlog

varnishlog
Log every transaction
varnishlog -g request
Group by client request tree
varnishlog -c
Client side only
varnishlog -b
Backend side only
varnishlog -q '<VSL query>'
Filter transactions
varnishlog -q 'ReqURL ~ "^/api"'
Match by URL
varnishlog -q 'RespStatus >= 500'
Only server errors

varnishtop and friends

varnishtop -i ReqURL
Most requested URLs
varnishncsa
Apache-style access log

VCL essentials

vcl 4.1;
Required first line
backend default { .host = "<host>"; .port = "<port>"; }
Declare a backend
sub vcl_recv { ... }
Request arrives; choose hash, pass, purge
return (pass);
Skip the cache for this request
sub vcl_backend_response { set beresp.ttl = 5m; }
Set cache lifetime
sub vcl_deliver { ... }
Edit the response to the client
set beresp.grace = 1h;
Serve stale while refetching
unset req.http.Cookie;
Drop cookies so pages cache
set resp.http.X-Cache = obj.hits > 0 ? "HIT" : "MISS";
Expose hit status
Common VCL variables
Variable Meaning
req.url request path and query
req.http.<h> request header
bereq.* request sent to backend
beresp.ttl object lifetime
obj.hits times served from cache
resp.http.<h> response header to client

Recipes

Deploy a new VCL with rollback
varnishadm vcl.load v2 /etc/varnish/v2.vclvarnishadm vcl.use v2# something wrong? roll back:varnishadm vcl.use v1varnishadm vcl.discard v2
Cache ratio at a glance
varnishstat -1 -f MAIN.cache_hit -f MAIN.cache_miss# live and updating:watch -n2 'varnishstat -1 -f MAIN.cache_hit -f MAIN.cache_miss'
Debug one URL end to end
varnishlog -g request -q 'ReqURL ~ "^/checkout"'# in another terminalcurl -sI http://localhost/checkout