Configuration

Many of the options should be self-explanatory but we'll walk through them for the sake of completeness. All of the configuration is done through Magento's standard Admin > System > Configuration menu, in the Varnish Options and Caching Options pages of the Turpentine section.

Note that saving changes to either of these sections will immediately apply the changes to the running Varnish config and save the VCL so manually hitting the Apply Varnish Configuration button on the Cache Management page should no longer be necessary.

Once you're done configuring, head over to the Usage page.

Varnish Options

General Options

• Apply VCL On Config Change: Enable or disable automatic generation and application of the new VCL on the Varnish Options or Caching Options sections
• Strip whitespace from VCL files: If enabled, extra whitespace will be removed from the generated VCL files, which helps avoid cli_buffer issues.
• Use VCL Fix: When Enable is selected, a VCL fix will be used to prevent session and formKey issues. If Disable is selected, an observer will be used. Please note that the observer method will disable CSRF protection.
• Enable Debug Info: Enable or disable debug information, including extra response headers. It is a major security risk to leave this option enabled on a live site. VCL Change
• Enable Block Logging: Enable or disable logging of block names that are potentially eligible for ESI injection. This is really only useful for debugging and for discovering the names of blocks when you want to add a new ESI cache policy and should be disabled otherwise as it has a performance penalty.
• Enable AJAX Flash Messages: Enable or disable the special handling of the flash messages blocks (messages and global_messages). You may need to disable this (and remove the related sections from the ESI layout) if you have another extension that alters the behaviour of the flash messages.
• Fix Product List Toolbar: Enable this to prevent caching the visitor's view preferences of the product list.
• Enable Site Crawler: Enable to allow Turpentine to automatically warm the cache on cache flushes
• Enable Crawler Debug: Enable debug info from the site crawler

Logging

• Use Custom Log File: Allows you to specify a custom log file name (no paths) that Turpentine will write log entries to instead of the default Magento log.

Servers

• Varnish Version: You can explicitly choose which version of Varnish VCL should be used (2.1, 3.0 or 4.0) or let the plugin figure it out automatically. Note that mixed major-version environments are not currently supported (i.e. one v2.1 server and one v3.0 server) but probably will be in the future (some of the code is there for this but not all of it).
• Server List: Specify the management interfaces of each Varnish server you're using as HOST:PORT pairs, one per line. Note that this is different from the Varnish backend and main Varnish listening interface.
• Varnish Authentication Key: Set the Varnish management interface auth key. This must match what Varnish uses byte for byte. Newlines can be encoded as \n.
• Config File Location: Set the location for the plugin to save generated VCLs to. {{root_dir}} is automatically replaced with Magento's base directory. It is not recommended that you set this to /etc/varnish/default.vcl as Magento will not likely have write access to that location (and probably shouldn't either). You should instead symlink /etc/varnish/default.vcl to the whatever you choose for this (or the default).
• Custom VCL File Location: Set the location for the custom VCL include file. The contents of this file will be included at the bottom of the generated VCL if it exists

Caching Options

Backend

• Load Balancing: This allows for load balancing between multiple backends.
• Backend Server List: Enter the IP address, including port for each back-end server - (only available if "No, use only one backend server" is NOT chosen)
• Backend Check URL: Enter a URL here that Varnish can use to probe a back-end to make sure it is available. Leave blank to disable probing. (Only available if "No, use only one backend server" is NOT chosen)
• Backend Server List for Admin: Specify backend servers to use specifically for admin requests. (Only available if "Yes, with separate settings for admin" is chosen)
• Backend Host: This should be the IP address your backend (web server) listens on for your site. The default of "127.0.0.1" may need to be changed depending on your specific configuration. (Only available if using one backend)
• Backend Port: This is the port for the backend, where Varnish will connect when it needs to get something from your site. While testing Varnish/this plugin you will usually want to leave this as port 80 (the standard HTTP port) so your site remains accessible even if something goes wrong with Varnish or the plugin. (Only available if using one backend)
• Frontend Timeout: This is how long Varnish will wait for Magento frontend requests to start responding before erroring out.
• Admin Timeout: This is how long Varnish will wait for Magento backend (admin) requests to start responding before erroring out.
• Crawler IP Addresses: A comma-separated list of IP addresses that should bypass Turpentine's frontend cookie requirement. Also useful for performance testing tools as they also typically don't support cookies. Note - if you are using something like Pound to terminate SSL before Varnish, setting this to the same IP could cause users to end up sharing the crawler session. See this issue for more discussion.
• Crawler User Agents: A comma-separated list of User-Agent regexs that should bypass Turpentine's frontend cookie requirement. Also useful for performance testing tools as they also typically don't support cookies. Includes Googlebot, ab (Apache Bench), siege, and MageSpeedTest.com by default.

Normalization Options

• Normalize Encoding: Enable/disable request Accept-Encoding header normalization. Clients (browsers) can specify the type of content encoding they can accept in a large number of ways. Enabling this will simplify this header, increasing the Varnish cache hit rate. This feature applies largely to the gzip/deflate headers and normalizes browsers that send a gzip accept header (regardless of header ordering) into the same hash bucket (ditto for deflate).
• Normalize User-Agent: Enable/disable request User-Agent header normalization. Browser user-agents can vary even between installs on the same version and OS. Enabling this adds another header to the request (X-Varnish-User-Agent) containing a simplified version of the User-Agent header. This increases the Varnish hit-rate while still allowing the cache to vary by browser (including mobile browsers). Only use this if you need to deliever special pages for different browers. The "right way" is to leave this option off and let your CSS/JS deal with the browser differences on the client end. While enabling this can increase performance leaving it OFF is more performant if your design allows.
• Normalize Host: Enabling this setting makes Varnish rewrite the Host header of a request to a specific domain. This can be helpful to prevent duplicate entries in the cache (for http://example.com/somepage and http://www.example.com/somepage for example) by making the backend see all requests as coming to a specific domain. Note that this setting is likely to break many/most multi-store setups so it's use should be carefully considered.
• Normalize Host Target: If Normalize Host is enabled, this is the host to normalize requests to.
• Normalize Cookie Regex: Regular expression that if matched will force the cookie to use the domain set below.
• Normalized Cookie Target: If the regular expression specified above is matched, the cookie domain will be set to the domain specified here.

TTLs

All TTLs should be specified in seconds.

• Grace Period: Varnish will serve expired entries from the cache for this many seconds while it fetches a new object from the backend. This is also the hit_for_pass period for pages that Turpentine signals to not cache.
• Default TTL: This is the default TTL (Time To Live) for cached pages in seconds.
• URL-based TTLs: This setting lets you specify specific URL paths. It should be a list of PATTERN,TTL comma-separated pairs, one per line. Note that the URL paths are relative to the Magento root path and should not start with a / (slash). For example, to cache the home page for 20 seconds, the "About Us" page for 30 seconds, and all product pages for 40 seconds, you would do something like this:

$,20
about-us,30
products/.*,40

• Static File TTL: This is the TTL for static files (things like CSS, Javascript, and images). See the Static Asset Extensions setting.

URL-based Caching

• URL Blacklist: This is a list of URL patterns (relative to the Magento root, one per line) that Varnish should never cache. Note that the admin section and API are automatically included.
• Bypass Varnish if base URL is not found within a store?: If enabled, any request that does not start with a store URL will bypass Varnish.

Parameter-based Caching

• GET Parameters: This is a comma-separated list of GET request parameters (ex: var in http://www.example.com/somepage?var=foobar) that will prevent Varnish from caching a page.
• Ignore GET Parameters: This is a separated list of GET request parameters that will be ignored by Varnish.
• Transfer unmodified URL to Backend Server: By default the backend server gets a modified URL (without ignored GET parameters). As a result the ignored parameters can not be used by the backend server for uncachable requests, for example a redirect. By activating this option the backend server gets the the unmodified url, but the cache still uses the modified url for lookups.

Static Caching

• Force Static Asset Caching: Enabling this setting will make Varnish cache requests for static assets even after the cookie that disables caching has been set.
• Static Asset Extensions: A comma-separated list of file extensions (without the . (dot)) of files that should be considered static assets. Note that you can use regular expressions here.

Maintenance Mode

• Enable Maintenance Mode: When enabled, all traffic (except from IP addresses in developer client restrictions) will receive error page HTML specified in Custom HTML content of vcl synth (error) sub
• Custom HTML content of vcl synth (error) sub: Paste the full HTML of the error page to be displayed when in maintenance mode.