WordPress.org

Plugin Directory

Test out the new Plugin Directory and let us know what you think.

Varnish HTTP Purge

Automatically purge Varnish Cache when content on your site is modified.

Please report all issues in the support forums

If you have code patches, pull requests are welcome.

How can I tell everything's working?

This can be difficult, since it's a silent plugin. That is you turn it on and walk away. The easiest way to tell would be view a page as a non-logged-in user. I recommend a private browsing window. Then, as a logged in user in another window, edit an existing post (make a small change). Refresh the view in your private window. If the change is there, then everything's working!

Does every WordPress plugin and theme work with Varnish?

No. Some of them have behavior that causes Varnish not to cache. While debugging that is outside the scope of this plugin, there is an "Is Varnish Working?" tool (see WP Admin -> Tools -> Varnish Status) that tries to detect most of the common issues and direct you to resolutions.

How can I debug my site?

From your WordPress Dashboard, go to Tools -> Varnish Status. There a page will auto-scan your main plugin page and report back any issues found. This includes any known problematic plugins.

What version of Varnish is supported?

This was built and tested on Varnish 3.x. While it is reported to work on 2.x and 4.x, it is only supported on v3 at this time.

Why doesn't every page flush when I make a new post?

The only pages that should purge are the post's page, the front page, categories, and tags. The reason why is a little philosophical.

When building out this plugin, there were a couple pathways on how best to handle purging caches and they boiled down to two: Decisions (the plugin purges what it purges when it purges) and Options (you decide what to purge, when and why). It's entirely possible to make this plugin purge everything, every time a 'trigger' happens, have it purge some things, or have it be so you can pick that purges.

In the interests of design, we decided that the KISS principle was key. Since you can configure your Varnish to always purge all pages recursively (i.e. purging http://example.com/ would purge all pages below it), if that's a requirement, you can set it yourself. There are also other Varnish plugins that allow for more granular control (including W3 Total Cache), however this plugin will not be gaining a whole bunch of options to handle that.

Why doesn't my cache purge when I edit my theme?

Because the plugin only purges your content when you edit it. That means if you edit a page/post, or someone leaves a comment, it'll change. Otherwise, you have to purge the whole cache. The plugin will do this for you if you activate a new theme, but not when you edit your current theme's files.

If you use Jetpack's CSS editor, it will purge the whole cache for your site on save.

How do I manually purge the whole cache?

Click the 'Purge Varnish Cache' button on the "Right Now" Dashboard (see the screenshot if you can't find it).

There's also a "Purge Varnish" button on the admin toolbar.

I don't see a button!

If you're on a Multisite Network and you're on the primary site in the network, only the network admins can purge that site

On a subfolder network if you flush the site at example.com, then everything under that (like example.com/site1 and example.com/siten and everything else) would also get flushed. That means that a purge on the main site purges the entire network.

In order to mitigate the destructive nature of that power, only the network admins can purge everything on the main site of a subfolder network.

Why is nothing caching when I use PageSpeed?

PageSpeed likes to put in Caching headers to say not to cache. To fix this, you need to put this in your .htaccess section for PageSpeed: ModPagespeedModifyCachingHeaders off

If you're using nginx, it's pagespeed ModifyCachingHeaders off;

Can I use this with a proxy service like CloudFlare?

Yes, but you'll need to make some additional changes (see "Why aren't my changes showing when I use CloudFlare or another proxy?" below).

Why aren't my changes showing when I use CloudFlare or another proxy?

When you use CloudFlare or any other similar service, you've got a proxy in front of the Varnish proxy. In general this isn't a bad thing. The problem arises when the DNS shenanigans send the purge request to your domain name. When you've got an additional proxy like CloudFlare, you don't want the request to go to the proxy, you want it to go to Varnish server.

On single-site, you can edit this via the Tools -> Varnish Status page. On Multisite, you'll need to add the following to your wp-config.php file:

define('VHP_VARNISH_IP','123.45.67.89');

Replace "123.45.67.89" with the IP of your Varnish Server (not CloudFlare, Varnish). DO NOT put in http in this define.

If you want to use WP-CLI, you can set an option in the database. This will NOT take precedence over the define, it's just there to let hosts who are using something like wp-cli do this for you in an automated fashion:

wp option add vhp_varnish_ip 123.45.67.89

and

wp option update vhp_varnish_ip 123.45.67.890

How do I find my Varnish IP?

Your Varnish IP must be one of the IPs that Varnish is listening on. If you use multiple IPs, or if you've customized your ACLs, you'll need to pick on that doesn't conflict with your other settings. For example, if you have Varnish listening on a public and private IP, you'll want to pick the private. On the other hand, if you told Varnish to listen on 0.0.0.0 (i.e. "listen on every interface you can") you would need to check what IP you set your purge ACL to allow (commonly 127.0.0.1 aka localhost), and use that (i.e. 127.0.0.1).

If your webhost set up Varnish for you, you may need to ask them for the specifics if they don't have it documented. I've listed the ones I know about here, however you should still check with them if you're not sure.

  • DreamHost - If you're using DreamPress and Cloudflare, go into the Panel and click on the DNS settings for the domain. The entry for resolve-to.domain is your varnish server: `resolve-to.www A 208.97.157.172` -- If you're NOT using Cloudflare, you don't need it, but it's just your normal IP.

What if I have multiple varnish IPs?

Multiple IPs are not supported at this time.

I have a major issue with writing code I don't use, which means that since I'm only using one IP right now, I don't want to be on the ball for supporting multiple IPs. I don't even have a place to test it, which is just insane to attempt to code if you think about it. Yes, I could accept pull requests, but that means everyone's at some other person's discretion. So no, I won't be doing that at this time.

Why don't my gzip'd pages flush?

Make sure your Varnish VCL is configured correctly to purge all the right pages. This is normally an issue with Varnish 2, which is not supported by this plugin.

Why isn't the whole cache purge working?

The plugin sends a PURGE command of /.* and X-Purge-Method in the header with a value of regex. If your Varnish server doesn't doesn't understand the wildcard, you can configure it to check for the header.

How can I debug?

If WP_DEBUG is on and you're not seeing any errors, you'll have to jump into the command line.

To see every request made to varnish, use this:

varnishncsa -F "%m %U"

If you want to grab the last purge requests, it's this:

varnishlog -d -c -m RxRequest:PURGE

And this will show you if the WP button was used:

varnishlog -d -c -m RxURL:.*vhp_flush_all.*

In general, I leave the first command up and test the plugin.

A full Varnish flush looks like this:

PURGE /.*

And a new-post (or edited post) would look like this:

PURGE /category/uncategorized/
PURGE /author/ipstenu/
PURGE /author/ipstenu/feed/
PURGE /2015/08/test-post/
PURGE /feed/rdf/
PURGE /feed/rss/
PURGE /feed/
PURGE /feed/atom/
PURGE /comments/feed/
PURGE /2015/08/test-post/feed/
PURGE /

It's just a matter of poking at things from then on.

How do I configure my VCL?

This is a question beyond the support of plugin. I don't offer any Varnish Config help due to resources. I will say this, you absolutely must have PURGE set up in your VCL. This is still supported in Varnish v3, though may not be set up by default. Also, here are some links to other people who use this plugin and have made public their VCLs:

All of these VCLs work with this plugin.

Can I filter things to add special URLs?

Yes!

  • vhp_home_url - Change the home URL (default is home_url())
  • vhp_purge_urls - Add additional URLs to what will be purged
  • varnish_http_purge_events - Add a specific event to trigger a page purge
  • varnish_http_purge_events_full - Add a specific event to trigger a full site purge
  • varnish_http_purge_schema - Allows you to change the schema (default is http)

I strongly urge you to use the last one with caution. If you trigger a full site purge too often, you'll obviate the usefulness of caching!

I added in an event to purge on and it's not working

If you're using varnish_http_purge_events then you have to make sure your event spits out a post ID.

If you don't have a post ID and you still need this, add it to both varnish_http_purge_events_full and varnish_http_purge_events - but please use this with caution, otherwise you'll be purging everything all the time, and you're a terrible person.

Hey, don't you work at DreamHost? Is this Official or DreamHost only?

Yes I do, and yes and no. This plugin is installed by default for all DreamPress installs on DreamHost, and I maintain it for DreamHost, but it was not originally an official DH plugin which means I will continue to support all users to the best of my ability.

Requires: 4.0 or higher
Compatible up to: 4.7.3
Last Updated: 4 weeks ago
Active Installs: 40,000+

Ratings

4.5 out of 5 stars

Support

5 of 6 support threads in the last two months have been marked resolved.

Got something to say? Need help?

Compatibility

+
=
Not enough data

0 people say it works.
0 people say it's broken.

100,1,1 100,1,1 100,1,1 100,1,1
100,1,1
100,1,1
100,1,1
0,1,0
100,1,1
100,1,1
100,1,1 0,7,0
100,1,1
100,1,1
100,1,1
100,1,1 100,1,1
100,2,2 100,1,1 100,1,1
100,1,1
100,1,1 100,1,1
100,1,1 100,2,2
100,1,1 100,1,1
100,1,1
100,1,1
100,1,1
100,2,2
100,2,2
100,1,1
100,1,1 100,1,1
100,2,2
100,3,3
100,2,2
100,1,1
100,1,1
100,1,1