FAQ

Jeroen Vermeulen edited this page Dec 13, 2015 · 25 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.

Installation

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.

Usage

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/warm-cache.sh http://example.com/sitemap.xml

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.

Troubleshooting

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 MageSpeedTest.com) 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/3.13.5.0 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
754bca59-a8ed-4057-95fa-6d4c73d09e62
#

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'm seeing an empty cart after clicking "Add to cart"!

Please note this issue is resolved as of 0.6.3

This is due to an existing bug that occurs when new users click 'add to cart' on the first page they visit. If they land on another page first and then click 'add to cart' subsequently, the bug does not occur. As of version 0.6.3 this issue is resolved by allowing you to choose from one of two options to prevent this problem:

  1. The VCL tweak option disables Varnish on the first page load for all new users, allowing a valid session to be generated by Magento. This is the preferred option, but does degrades performance.
  2. An observer method that disables CRSF protection, which is not recommended as it can make a store vulnerable to cross-site scripting attacks.

Google is indexing my ESI URLs!

This typically will only happen if your production site is running with debugging options turned on (not recommended!) but if Google does somehow index these URLS, you can update your site's robots.txt file as described in this issue to prevent this from occurring.

Why are there "DUMMY CONTENT" html comments in my source code?

The "DUMMY CONTENT" comment tags were added as a workaround a specific Varnish problem originally discussed here. As such, if you decide to remove them you may experience intermittent issues with ESI.

I'm getting an error: "Inline-C not allowed" when Varnish is restarted

This may be due to configuration issues when using a distribution that uses systemd - see this issue for details.

I'm getting an error message like: "Panic message:#012Assert error in VEP_Init()"

This may be resolved by adding -p workspace_backend=64k to the Varnish startup parameters. See this issue for more details.

Upgrades

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 (-p feature=+esi_ignore_other_elements as of Varnish 4.0). How to add this option depends on your OS but for CentOS you would add it to DAEMON_OPTS in /etc/sysconfig/varnish.