Project

varnisher

0.02
No commit activity in last 3 years
No release in over 3 years
There's a lot of open issues
Some tools that make working with the Varnish HTTP cache easier, including things like doing mass purges of entire domains.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 0.4.1
~> 5.0.6
~> 10.1.0
~> 1.13.0

Runtime

~> 6.0
~> 1.6
~> 1.3
 Project Readme

varnisher

Build Status Dependency Status

Administering Varnish is generally a breeze, but sometimes you want to do one of the few things that aren't painless out of the box. Hopefully, that's where this toolbox comes in.

Varnisher lets you do things like:

  • Purge a webpage and everything (e.g. images, JavaScript files, CSS files) referenced on that page
  • Spider an entire domain — useful for priming a cache
  • Purge an entire domain, including optionally re-spidering it afterwards to keep the cache warm

Full documentation is available on rdoc.info.

Installation

Varnisher can be installed using RubyGems:

gem install varnisher

Varnisher requires Ruby 1.9.3 or above.

Usage

NAME
varnisher

SYNOPSIS
varnisher (purge|spider) [options]+

DESCRIPTION
Varnisher is a set of tools for working with the Varnish HTTP cache.

PARAMETERS
--verbose, -v
	If given, Varnisher will be noisier about what it's up to.
--hostname=hostname, -H (0 ~> hostname=localhost)
	The hostname/IP address of your Varnish server.
--port=port, -p (0 ~> int(port=80))
	The port Varnish is listening on.
--help, -h

EXAMPLES
varnisher purge http://example.com
varnisher spider example.com
varnisher purge --reindex example.com

If you find yourself typing certain parameters every time you use the script, you can specify them in an RC file called .varnishrc in your home directory. The file format is YAML and the default options are, if you want to paste and override them:

verbose: false
hostname: localhost
port: 80
num-pages: -1
ignore-hashes: true
ignore-query-strings: false

Examples

Purging a page and all the resources on it

Quite often, it's necessary redevelop a page on a website in a way that involves changes not only to the page but also to CSS files, images, JavaScript files, etc. Purging pages in this instance can be a painful process, or at least one that requires a few ban commands in varnishadm. No longer!

Just enter:

$ varnisher purge http://www.example.com/path/to/page

...and /path/to/page, along with all its images, CSS files, JavaScript files, and other external accoutrements, will be purged from Varnish's cache.

As a bonus, this action is multithreaded, meaning even resource-heavy pages should purge quickly and evenly.

This action requires your VCL to have something like the following, which is fairly standard:

if (req.request == "PURGE") {
    if ( client.ip ~ auth ) {
        ban("obj.http.x-url == " + req.url + " && obj.http.x-host == " + req.http.host);
        error 200 "Purged.";
    }
}

(For an explanation of just what obj.http.x-url means, and why you should use it rather than req.url, see this page.)

Purging an entire domain

Provided your VCL has something akin to the following in it:

if ( req.request == "DOMAINPURGE" ) {
        if ( client.ip ~ auth ) {
                ban("obj.http.x-host == " + req.http.host);
                error 200 "Purged.";
        }
}

...then you should be able to quickly purge an entire domain's worth of pages and resources by simply issuing the command:

$ varnisher purge www.example.com

Repopulating the cache

If you've purged a whole domain, and particularly if your backend is slow, you might want to quickly repopulate the cache so that users never see your slow misses. Well, you can! Use the spider action:

$ varnisher spider www.example.com

spider accepts either a hostname or a URL as its starting point, and will only fetch pages on the same domain as its origin. You can limit the number of pages it will process using the -n parameter:

$ varnisher -n 500 spider www.example.com

If you'd like to combine purging and spidering, you can use the reindex option:

$ varnisher purge --reindex www.example.com

…which is functionally equivalent to:

$ varnisher purge www.example.com
$ varnisher spider www.example.com