Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP


Alex Headley edited this page · 13 revisions

Table of Contents

General Questions

What's with the name?

I like puns.

Is there a list of the changes in each release somewhere?

Yep, see the CHANGELOG. Note that changes for the next release are often added to the changelog before that release is ready to go out, so make sure you know what the latest actual release is.

Will Turpentine work with extension XYZ?

It depends, see the compatibility list, or open a ticket if you can't find it there.

Will Turpentine work in a shared hosting environment?

This depends on the specific environment but probably not. Turpentine requires management access to the Varnish daemon to apply it's generated configuration and most shared hosts are not going to allow this.

Why do I need to disable Magento's Full Page Cache (FPC) for Turpentine?

On a FPC cache hit, Magento runs very little PHP code. Instead it basically just spits out the cached page from disk (or memcached, redis, etc). With Turpentine, this is a problem because Turpentine normally adds some headers to tell Varnish what is and isn't OK to cache, and whether Varnish should do ESI processing on the response (for ESI included blocks). This results in the FPC caching a page with ESI injected blocks, but Varnish doesn't run the ESI processing on the page which effectively means those blocks are missing from the page. Additionally, it can result in Varnish caching pages it shouldn't, like the customer login page.


I installed Turpentine but I don't see the config section!

Refresh the Config, Layout, and Block HTML caches in System > Configuration

Ok, I see the config sections but I get a 404 when selecting them!

Turpentine adds some new permissions that don't get applied to your current session. Log out and log back in to fix.


How do I "warm" the cache?

You can use a crawler (I believe there are Magento extensions that will do this) on the site after adding the crawler's IP address to the Crawler IP Addresses or user agent to the Crawler User Agents setting.

UPDATE: There is now also a bash script in the repo under the util/ directory that will read URLs from your site's sitemap and use siege to hit each one (once). Run like so:

$ ./util/

I want to do some special stuff in the VCL, how do I avoid my changes being lost on an upgrade?

As of 0.4.0 you can put your customizations in app/code/community/Nexcessnet/Turpentine/misc/custom_include.vcl, and Turpentine will automatically include that file at the top of the generated VCL.

I'm using varnishncsa to generate logs and the ESI URLs are cut off, how do I get the full URL in the logs?

The URLs in Varnish's log entries are limited to 255 characters by default, you'll need to change the shm_reclen parameter. Doing this is distribution specific, but will probably involve editing /etc/init.d/varnishd or /etc/sysconfig/varnish.


I installed Turpentine but siege/ab/etc aren't showing a speed increase!

By default, Turpentine passes requests without frontend cookies through to Magento so they can get a new session. Most performance testing tools and crawlers don't support cookies, so all of their requests get passed through, negating the Varnish caching. If you want to benchmark your site, add the IP addresses you will be using the testing tools from to the Crawler IPs, then re-apply the Varnish Configuration to let requests from those IP addresses bypass the frontend cookie requirement.

UPDATE: As of version 0.1.6 Turpentine will (by default) detect some performance testing tools (siege, ab, and by their User-Agent so this is not necessarily applicable anymore. If you are using a tool that is not in the default list of Crawler User Agents then you can add it to have it detected. Note that the regex you add to the Crawler User Agents setting is matched against the entire User-Agent header, so to match curl with it's default user agent of curl/7.24.0 (x86_64-redhat-linux-gnu) libcurl/7.24.0 NSS/ zlib/1.2.5 libidn/1.24 libssh2/1.4.1 you can add something like curl/.*libcurl/.*.

I added the Varnish secret key but Turpentine still can't talk to Varnish!

The Varnish Authentication Key has to match what Varnish uses byte for byte. On some distro packages Varnish will use the contents of /etc/varnish/secret, which by default contains a UUID with a newline at the end. The newline must be added in the config option by using \n in it's place. For example:

# cat /etc/varnish/secret

Note that the prompt is on the next line, that means there is a newline at the end of the file, so the contents of the Varnish Authentication Key setting should look like 754bca59-a8ed-4057-95fa-6d4c73d09e62\n.

I'm getting a timeout error when trying to apply the VCL or flush the cache!

You probably added Varnish's listening port to the Server List option instead of the management port. The listening port is where Varnish listens for external requests (usually on port 80 or 8080), the management port is where Varnish listens for admin commands (usually on port 6082).

I'm getting a "ESI processing not enabled" error on some or all pages!

If you're using a version < 0.1.5 then you're probably running into the bug where Magento's block html cache caches the ESI template so that gets output instead of the block's actual content. You can either upgrade (recommended), or disable the Block HTML cache type on the Cache Management page.

Otherwise, make sure the Varnish Pages and Varnish ESI Blocks cache types are enabled, then hit the Apply Varnish Config and Flush Cache Storage buttons on the Cache Management page. If you still see it happening then it's probably a new bug, feel free to open a bug report.

What does the "Varnish data to write over length limit by x characters" error mean?

By default, Varnish limits CLI commands to 8192 characters. The generated VCL plus the command to use may exceed this limit (by the x amount).

To fix it, Varnish needs to be started with -p cli_buffer=16384. How to add this option depends on your OS but for CentOS you would add it to DAEMON_OPTS in /etc/sysconfig/varnish.

UPDATE: As of RELEASE-0.2.0 the generated VCL now has most white-space stripped which reduces the size down to ~5KB so this shouldn't be much of an issue anymore.

The pages in the admin added by another extension are being cached!

By default, the admin panel URLs have the form /admin/<something>/, some extensions don't put their URLs under the /admin/ namespace, and instead use something else, like /extension_admin/<something>/. Turpentine currently has no way of recognizing that those URLs are also part of the admin so they need to be added to the URL blacklist manually.


I upgraded the extension and all my settings got reset!

In the course of adding the ESI support Turpentine's settings were renamed (v0.1.0), which causes them to be reset to their default value. As the extension is still in beta I didn't feel it was worthwhile to try and preserve the old settings. This will hopefully be the only time this happens but no promises!

I upgraded and now I can't find the Varnish Management page in the admin!

This page was removed in version 0.1.4 in favor of more tightly integrating with Magento's built-in UI. Varnish page and ESI blocks cache can now be cleared in the same way as Magento's other cache types (via the Cache Management page), and saving settings after making changes to the Varnish Options or Caching Options will apply and save the Varnish configuration. The Varnish configuration can still be downloaded, see the "Download Varnish Config" button on the Cache Management page.

I upgraded to Turpentine 0.6+ and are the "Add to Cart" buttons look broken!

The addition of CSRF protection to some buttons in Magento CE 1.8+ and EE 1.13+ require a small change to Varnish's configuration to make it start with -p esi_syntax=0x2. How to add this option depends on your OS but for CentOS you would add it to DAEMON_OPTS in /etc/sysconfig/varnish.

Something went wrong with that request. Please try again.