#####EDIT: NB Ban is technically different from Purge. Banned objects remain in memory but banning is faster than purging. Read the Varnish 3 documentation here and here.
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 ban.
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"
Note that 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!
Read the Varnish 3 documentation here and here
Incidentally, 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!
Regarding naming: Yes, it's a terrible name IMO. But it does have some merit: It bans the cached object from being used - it does not actually remove the object. It's like sweeping dust under the rug. It's not technically cleaner, but it's practically gone. And following this analogy, eventually someone has to clean under the rug if you want to free up the space it's occupying.
The reason it seems like bad naming is because you are specifying URLs. So it looks like you are banning a URL when in fact Varnish doesn't care about what URL you are specifying - it's banning the object.
So... IMO, a more appropriate name would probably be "ban.object" or "stash" or something that doesn't seem so destructive.