How to purge ('ban') an entire domain in Varnish Cache 3
Purge may be a more appropriate action for your use-case; although the examples in the gist below work, it's not necessarily the best way of doing this.
I thought I'd share this because it's taken me a couple of hours to work out and the documentation is not entirely clear.
First of all, the purge method used to be called
purge in Varnish 2.x but they renamed it to
ban in 3.0. Confusingly there is also a new command called
purge too! The new
purge command is much less sophisticated than
ban, as (AFAIK) it only purges exactly matched items, so basically one at a time.
If you do wish to use the new
purge you need to have some specific VCL in place. See here
in Varnish 2.x I would have used a cURL request:
curl -X PURGE www.mydomain.com
However in Varnish 3 this will only purge the homepage / default document itself from that domain.
In order to purge the whole domain we need to use
Purge whole domain from the command line
For me a common use-case is that after deploying an update to a website I want to purge the entire cache of it to ensure that users get the fresh content. For a fairly static site I might have Varnish's TTL set to 24 hours, so purging is critical if I want to prove to my client that I've actually done some work.
Bear in mind:
- Don't purge an entire site during high traffic load, unless your back-end server has got balls of steel. (
banlets you purge selectively too).
- You can't flush public or user caches, so this doesn't negate the need to increment filenames on any assets with long expiry times (and / or manage your public cache-control headers carefully).
####To get to the point
There are several ways to do this but the simplest way is via varnishadm, which you can go into and control manually, or run on the command line by passing the required command to it.
In my newest project I've simply added the following line to the end of my deploy script (which runs on the same server as Varnish, obv.):
sudo varnishadm "ban req.http.host ~ www.mydomain.com"
ban accepts a regex, so by modifying the expression you can create more specific bans. For example, to purge for all CSS files only:
sudo varnishadm "ban req.http.host ~ www.mydomain.com && req.url ~ .css"
That's it, I hope this helps someone out at some point.
* EDIT: clarified in the comment below. Thanks!
ban strikes me as a terrible name for the function. I'm sure there are logical technical reasons for the name, but to the user 'ban' implies some kind of permanent ban on the cached content specified. Practically, once something has been 'banned' a new cache will be created the next time a request is made for that content.
If anyone can clarify the reasoning behind the name please add a comment!