You think Varnish can cache responses by URL only? Not even close. Learn all different caching strategies available in Varnish, their benefits and consequences of usage. Learn how to and when to queue requests for the same endpoint, how to handle requests with conditional caching headers and how to have two levels of cache by tagging the responses.

1. In-depth caching in Varnish
Łukasz Lach
GOG.com Varnish Meetup, march 2019

2. Łukasz Lach
Software Architect
Docker Captain
Docker Certified Associate
Lecturer at the University of Warsaw
llach@llach.pl
2019

3. Try Varnish 6 in Docker!
$ docker run lukaszlach/varnish:6
Debug: Version: varnish-6.0.1 revision 8d54bec5330c293049ebf...
Debug: Platform: Linux,4.9.125-linuxkit,x86_64,-junix...
Debug: Child (17) Started
Info: Child (17) said Child starts

4. Varnish is a caching reverse proxy that can:
● pick a HTTP backend using one of available
load-balancing strategies
● pass the request to a backend and nothing more
● additionally cache the response if you sent
a valid caching header or used VCL for it
● serve a stalled response from cache while still updating it
in background with request coalescing
● serve a stalled response when backend servers are down

5. VCL is a programming language
● Varnish translates VCL into binary code which is then
executed when requests arrive
● VCL files are organized into subroutines
● if you do not call an action in your subroutine and it
reaches the end Varnish will execute a built-in VCL
● does not have any loops, jump statements, custom
variables, classes or functions

6. vcl_hash
vcl_pass
vcl_miss
vcl_hit
vcl_backend_fetch
vcl_backend_response
vcl_backend_error
vcl_deliver
hit-for-miss
hit-for-pass
vcl_recv
insert into cache

7. Default behaviour

8. vcl_recv # Called at the beginning of a request
1. pass every method except GET and HEAD
2. pass if request contains Cookie or Authorization header
3. hash

9. vcl_hash # Called to create a cache key for the request
1. add request URL to the cache key
2. add either the Host header or server IP to the cache key
3. lookup object in cache

10. vcl_hit # Called when a cache lookup is successful
1. serve the cached object if ttl is greater than 0 seconds
(a valid cache object)
2. serve the cached object if ttl+grace is greater than 0 seconds
(a stalled object in grace mode) and trigger a background fetch
3. miss

11. vcl_backend_response
# Called after the response headers have been successfully retrieved
1. deliver if response is uncacheable, create a hit-for-miss object
2. deliver and mark as hit-for-miss for 2 minutes if the response
● beresp.ttl is less than 0 seconds
● contains Set-Cookie header
● contains Surrogate-control header with no-store flag set
● does not contain Surrogate-control header but Cache-Control
has any of no-cache, no-store or private values set
● contains Vary header equal to *
3. deliver and store the object in cache

12. ttl
Before Varnish runs vcl_backend_response, the beresp.ttl variable has
already been set to a value.
beresp.ttl is initialized with the first value it finds among:
● The s-maxage variable in the Cache-Control response header
● The max-age variable in the Cache-Control response header
● The Expires response header
● The default_ttl parameter

13. Backend error ≠ HTTP error
When Varnish can not connect to the backend or if the request timed
out, this is considered a failed fetch and vcl_backend_error is
called.

14. Backend error ≠ HTTP error
When backend returns a 5xx or any other valid HTTP response, for
Varnish this is a successful fetch and vcl_backend_response is
called.
If this is a background fetch and the response is uncacheable, the
previously cached object is erased from the cache and may be replaced
with a hit-for-miss object.

15. Gracefully fallback to cache
Stop cache insertion and do not remove previously cached object from
cache when a backend fetch returns a 5xx error.
sub vcl_backend_response {
if (beresp.status >= 500 && bereq.is_bgfetch) {
return (abandon);
}
}
VCL

16. Not modified
If a cache object is being refreshed and backend returns a 304 response,
Varnish amends beresp before calling vcl_backend_response:
● If the gzip status changed, Content-Encoding is unset
and any Etag is weakened
● Any headers not present in the 304 response
are copied from the existing cache object
● The status gets set to 200

17. If you return (pass)
in vcl_recv Varnish never
has a chance to cache
the response and so will
never send 200 or 304
by itself for any request.
The same flow applies
to hit on a hit-for-pass
object.

18. If you return (hash)
in vcl_recv and Varnish
caches the response then
it can start sending 200
and 304 responses,
also when the cache
object is stalled.

19. Cached status codes
The following status codes are cached by default:
200: OK
203: Non-Authoritative Information
300: Multiple Choices
301: Moved Permanently
302: Moved Temporarily
304: Not modified
307: Temporary Redirect
410: Gone
404: Not Found

20. max-age=0 ≠ no-cache
max-age=0 tells caches (and clients) the response is stale from the
very beginning and so they should revalidate the response before using
a cached copy. They may be allowed to serve it as a stale content.
no-cache tells caches they must revalidate the response before using
a cached copy and will never serve it staled.

21. Request coalescing
The benefit of a graced object in cache is that Varnish queues requests
for the same cache key triggering one background fetch, as long as it is
running all clients are served a stalled object.
So eventually setting ttl=0s and grace=1m enables request
coalescing for one minute while still constantly refreshing the cached
object from the backend.

22. The first request for the
resource creates a graced
object in the cache.
Further requests to this
resource are served
from cache and a
Background job is
triggered, one backend
fetch at a time.

23. The built-in VCL
Run varnishd -x builtin to view the built-in VCL.
$ docker run lukaszlach/varnish:6
varnishd -x builtin
/*-
* Copyright (c) 2006 Verdens Gang AS
* Copyright (c) 2006-2015 Varnish Software AS
...

24. Modifying the cache key

25. Modifying the cache key
The easiest way to create a separate cache object
for the same URL and Host is to call hash_data in
vcl_hash with a value we want to differentiate on.

26. hash_data
As vcl_hash is a client function so you can only use the req object.
sub vcl_hash {
hash_data(req.http.Any-Request-Header);
# unnecessary if, effect is the same as above
if (req.http.X-Country) {
hash_data(req.http.X-Country);
}
# having a default value makes more sense
if (req.http.X-Device) {
hash_data(req.http.X-Device);
} else {
hash_data("desktop");
}
}
VCL

27. Know the cache key
You can pass any value from VCL to varnishlog and varnishncsa, including
the cache key in an encoded format, individual parts of the key are not available.
sub vcl_deliver {
if (obj.hits > 0) {
std.log("cache_key:" + blob.encode(blob=req.hash, encoding=HEX));
}
}
$ varnishncsa -F '%r %{VCL_Log:cache_key}x'
GET /page1 1097cdf0f8af3b5daa2a22e85c7b7ada50bbd295efc7fcfb37c54eaebd832b43
GET /page2 49b6a5b0905ff6e20824cd2569f150ef694776c522a152674c1bd18c2ed51268
GET /page3 7f9ce7c3f05f8a34af3b5daa2a22e85ce345b750bd295efc7fcf23b47c55cebd
VCL

28. Varying the response

29. Varying the response
The Vary HTTP response header tells Varnish to create
a separate cache object for the same cache key by using
values of the request headers pointed by name.

30. Vary
Sending Vary: X-Country, X-Device response header from backend
results in /page being cached in number of copies equal
to all combinations of these two header values.
X-Country: us | X-Device: desktop
X-Country: us | X-Device: mobile
X-Country: pl | X-Device: desktop
X-Country: pl | X-Device: mobile
GET /page
4 variations of /page stored in cache

31. Finding the variation
All headers pointed by a Vary header must be present
in the req.http object before cache lookup
is triggered (return lookup) so that Varnish
knows exactly which object is to be served.

32. Difference from hash_data
Using Vary leaves you the possibility to PURGE an URL using
a single request to delete all variations of the cached object
because it does not change the cache key.
When using hash_data you need to pass all headers
and values used in vcl_hash, so eventually PURGE
all copies manually one by one using separate requests.

33. Vary once
Do not pass the Vary header to the client as this may create copies on
his side, but also expose internal header names.
# do not vary on the client side
sub vcl_deliver {
unset resp.http.Vary;
}
# do not vary in Varnish
sub vcl_backend_response {
unset beresp.http.Vary;
}
VCL

34. Tagging the response

35. vmod_key
Varnish module (vmod) that allows to tag
a response with several values.
Later on you can purge or softpurge all responses
containing defined tag using a single PURGE request.
http://bit.ly/vmod_xkey

36. Specifying response tags
Tags are specified in the xkey response header.
Multiple tags can be specified per header line with a space
separator or in multiple response headers.
xkey: tag/1 tag2 tag-3

37. The first two requests create
cache objects tagged with
several values.
Backend or any other
client allowed to PURGE
can now remove all
cache entries by
pointing only a tag.

38. Purging with cache in mind
Softpurge works like purge but keeps the grace and keep values
of a cached object.
● sets ttl to 0s
● allows to reply with 304 to conditional requests
● allows to serve stale content to clients if the backend is unavailable
● enables asynchronous and automatic backend fetching
to update object

39. Caching strategy Summary
Default behaviour Caches all GET requests with valid Cache-Control or fallbacks
to default TTL, respects conditional caching headers like ETag
and Last-Modified. Different URL or query string is needed for a
separate cache entry.
Modifying cache
key in vcl_hash
Easy way if you work with request header or values available in
VCL. Makes purging harder.
Using the Vary
header
Although, like in the above solution, you need to work with
request and VCL values, this solution allows to pass the
control on what to cache with which values to backend.
Tagging the
response
Easy and powerful, however it is Varnish-specific and requires
custom implementation on the backend side.

40. Thank you!
GOG.com Meetups
https://www.meetup.com/gogcom
Varnish Software
https://www.varnish-software.com