Caching with EP

Caching with EP

Caching with EP

To set up caching using Enfold Proxy(EP):

  1. Create an EP proxy definition to link your Plone site with IIS. Verify that it works.
  2. Select one of the Available caching products for plone. Install and enable it.
  3. Edit the cache settings for your proxy definition. (See Optimize Cache Settings and Measure Caching Performance ).
  4. Next Step: Verify that Your Cache Settings are in Effect

Caching increases Plone's performance significantly, so most deployments feature a caching solution of some kind. Enfold Proxy (EP) offers a caching solution which is easy to configure and track. They can't handle all requests -- personalized pages and dynamic content require Zope -- but when they can handle a request, they should.

Before trying caching, you should review the tutorial about how caching in Enfold Proxy works . This tutorial covers how to view HTTP headers and how to interpret them. Also, when testing cache settings, you should be familiar with these things:

  1. how to examine Enfold Proxy logs and how to set the log level to headers. (See Using logs to view headers).
  2. how to clear cache on your local browser.
  3. how to purge Enfold Proxy's cache. (See Purging Cache). Purging helps Enfold Proxy start over if you have misconfigured your cache settings.

Enfold Proxy lets you set up caching for each proxy definition (See Adding a Proxy Definition). Each proxy definition will store the files for caching in a separate directory (typically C:\Program Files\Enfold Proxy\cache). Except for object-based caching or XSLT caching , you can configure caching almost entirely through EP's configuration utility without needing to edit the eep.ini file.

If you configure your proxy definitions manually, the cache settings will be set directly in the [host] section corresponding to the individual proxy definition. All cache-related configuration options are prefixed with cache_.

This table of caching options contains a description of each option which you can configure through EP's configuration utility. To learn more about cache headers, see the Cache Headers reference guide.

Having problems? Check the troubleshooting checklist or the common tasks in Enfold Proxy or the FAQ.

What is a cacheable item?

First, let's cover the kind of web items that can and should be cached.

  • static content (images and JavaScript)
  • content for anonymous users. Items (such as Plone-generated HTML) can be cached with little danger.
  • selected content for logged in users.

Warning Incorrect configuration of caching has the potential for authenticated requests being cached (which is bad). Generally, the two Plone products discussed below have sensible policies about not caching authenticated requests. Nonetheless, if you are creating a customized CacheFu policy or using another caching product for Plone, it's a good idea to confirm that authenticated requests are not being cached. Also, it's a good idea to purge your cache or your proxy definition after you make a change to your cache settings on the Plone side.

First Step: Install and Activate a Caching Product

Before you can cache, you must install and activate a product in Plone specifically for caching. With this product you can configure and customize cache settings.

Install a Caching Product

(these are generic instructions for installing any Plone product).

  1. Choose which caching product you wish to use (see below).
  2. If necessary, download the product and place inside the Products directory of Plone/Enfold Server(typically C:\Program Files\Enfold Server\Products in Windows).
  3. Go to the Plone control panel (i.e., and select Add/Remove Products. You should see the name of your Product(s) on the Products available for install list.
  4. In the Plone control panel, look for a link under Add-on Product Configuration. One of these links should lead you to a configuration menu for the caching product you have chosen to install.
  5. From the product configuration options, make sure caching has been enabled/turned on.

Available Caching Products

Chasseur is a Plone product included with Enfold Server. It was designed for ease-of-use and simplicity. It is currently maintained and supported by Enfold. The main two settings are Normal (cache images, js, css for one hour) and Aggressive (cache js, css, images for one hour and also cache content for anonymous users for 1 hour).

  • Normal is generally risk-free and unlikely to cause problems, especially if image files are unlikely to change.
  • Aggressive is generally not recommended because it interferes with EP's ability to purge content. When that happens, an individual browser might use private cache instead of checking with EP/ES to make sure it has fresh content. (See Purging Content with Scripts).

CacheFu is an open source product with a wide variety of features. Actually, it consists of 4 separate products (CacheSetup, PageCacheManager, CMFSquidTool, and PolicyHTTPCacheManager) which are dropped into the Products directory. CacheFu offers a lot more granular control over caching. It lets you set policies and configure headings and cache rules for different content types in Plone. Check the cachefu documentation for details. Zest Software also has a good tutorial about setting up CacheFu at This Zest Software tutorial assumes you are using a Varnish proxy in Linux, but many of the concepts and strategies apply when using Enfold Proxy as well.

  • Important: you need to enable a caching policy for CacheFu to work in EP. On the first tab, you need to choose Enable CacheFu. Under Active Cache Policy, choose Default Cache Policy or choose another policy (You can create one from scratch or clone an existing one by going to the Policy tab). On the first tab, you will also need to choose a Proxy Cache Purge Configuration; choose No Purge (zope-only, or zope behind apache).
  • CacheFu will use cache headers different from Chasseur. But EP is able to process both of them; in fact, after you enable CacheFu, Chasseur will deactivate all cache profile previously enabled.
  • You can specify caching behavior in Plone by deciding which header to use when returning a particular Plone content type. To do that, go to the Rule tab, and select the content type you want. Each rule will let you specify a header for anonymous users and a rule for authenticated users. (Presumably, you'd want a reduced amount of caching for authenticated users).
  • The label for each header ("Do not Cache", "Cache in proxy-cache for 1 hour," "Cache-in-browser for 1 hour," etc) should be self-explanatory. Keep in mind that you can also edit properties for each header on the Headers tab.
  • at the time of this writing (January, 2009), a browser bug in Internet Explorer prevents sysadmin users from viewing/editing properties on the CachuFu Rules tab. (This bug does not affect users of Firefox). As a result, the hyperlinks on the CacheFu configuration page won't work properly; you may need to open these hyperlinks in a new browser tab or browser window.
  • CMFSquidTool is an open-source caching product supported by Enfold which lets you purge cache. (As long as you set your IP address in Caching Purge Sources -- see Purging Cache). However, you may find it easier to use Enfold Proxy to purge cached items for proxy definition(s).

Enable Cache in your Proxy Definition

By default, when you create a proxy definition in EP, caching is enabled. However, you might need to change your settings to suit your hardware.

See a description of each cache setting.

Enfold Proxy will keep a lot of "stale" cached files inside the cache directory corresponding to a specific proxy definition. These stale cache files will accumulate in the cache directory until it approaches the maximum cache size. That is actually a good thing. In Chasseur, for example, a lot of content is cached for one hour. After one hour (or even after five years), whenever the browser requests the same resource, EP will check with Plone and ask, "is this stale item still valid?" Plone will give one of two responses. Either:

  • Plone will reply, "it's still good." (In this case, EP will return the stale item to the browser and update its own records to indicate that this stale cache is now valid. This process is called, revalidating the cache). The HTTP headers to the user will say: X-Cache: HIT from
  • Plone will reply, "Nope. That's an outdated version." (In this case, Enfold Server or Plone will send the updated version to Enfold Proxy, which will pass it on to the browser and also replace the outdated version with the newer version). X-Cache: MISS from .

Enfold Proxy now has an easy button in its interface to purge cached items for proxy definition(s).

Next Step: Verify that Your Cache Settings are in Effect

The easiest way to verify your cache settings is to view the Enfold Proxy logs themselves. That allows you to see the responses from Plone and also prevents browser issues from misleading you. When viewing the Enfold Proxy logs, be sure to activate the new Headers log level which is easier to read than typical HTTP headers.

To verify that caching is taking place from the browser, look for this line in your HTTP response header: X-Cache: HIT from

  • If you see X-Cache: HIT, then yes, Enfold Proxy has sent you a cached version of this content item.
  • If you see X-Cache: MISS, then no, Enfold Proxy has sent you this content which was not in its cache.

Generally HIT's indicate successful caching.

Keep in mind that X-Cache: MISS is not always a bad thing. For example, if logged in as an administrator, many resources will not be cached on purpose. It's best to test as an anonymous web surfer (i.e., someone who is not logged in). If an item contains a modification, then a MISS reply is mandatory. Also, object-based caching (like XSLT caching )doesn't modify these headers, so EP can be properly caching XSLT pages and still be sending out X-Cache: MISS headers.

Careful: When testing, it's a good idea to use two different browsers. In Browser A (such as Internet Explorer), log in as Admin. In Browser B (i.e., Firefox), log in as anonymous or as a logged in user. It's also important to clear cache the right way and even to close the browser entirely (if you don't, the http headers you see won't be accurate). Consult the troubleshooting checklist for caching.

To see the HTTP headers directly, see Tools for Viewing Headers . You should probably pick two or three sample items to check for headers. Anything will do, but at least one should be a graphic and one should be a Zope page (such as ). In Chasseur, the maximum age is

Cache-Control: max-age=3600 X-Cache: HIT from

Optimize Cache Settings and Measure Caching Performance

(See also: Caching Goals and Strategies).

Many of your cache settings can be tweaked in whatever Plone product you are using to cache web items. The CacheFu Plone product, for example, offers a lot of fine-grained controls and the ability to create caching rules.

Note: if you suspect your cache settings are misconfigured, purging your cache can often eliminate the problem. (See Purging Cache).

But EP also offers some cache settings to tweak.

Here are some default settings for each proxy definition as set by Enfold Proxy:

  • Maximum Size of the Cache: 10 gigabytes for each proxy definition
  • Maximum number of items in the cache for each proxy definition: 50,000
  • Maximum size of an item which can be cached: 100K
  • Default-Age: 0

The main thing you can adjust here is storage amount and item size. The larger the storage amount you have, the more cacheable items EP can keep at once. Increasing maximum item size is recommended if your Plone server returns a lot of web items (which is not the same thing as "web pages") over 100K. If the maximum is increased to a very large size, this will also consume RAM on the machine with EP. Also, when you cache larger files, that will cause the maximum size of the cache to fill up more quickly. Theoretically, if your cache directory for your proxy definition is always at maximum and the hit percentage is declining, that could indicate you need to increase your maximum here.

If Plone includes max-age=0 in the headers, EP will store cachable items and always check to make sure if it is current before serving cached content to the browser. Even so, EP will not cache an item which is forbidden to be cached (according to Plone or whatever Plone Product is setting these commands). For more about how EP handles HTTP headers, see the Cache Headers Reference.

If you check Enfold Proxy's cache.log messages for your proxy definition (and set the log level to Information), you will see every minute or so some statistics about caching:

2008-02-18 10:31:45,250| originalfunsite|STATS|3500|2856|Cache statistics:
        gets: 88, hits: 65 (33 validated), misses: 23 (0 uncachable)
        hitrate: 73% (58% excluding validations)
        size: 1943668 bytes, 324 items

The most important number here is the 58% in parenthesis. It refers to requests that EP returned without forwarding it to Enfold Server or Plone (thus resulting in the most time-saving). The 73% number includes those occasions when the item was stale and EP needed to make a conditional request to Enfold Server/Plone. So 15% (i.e., 73-58) is the percentage of times when EP had to revalidate stale cache by checking with Enfold Server or Plone. These revalidation requests generally do not result in significant time savings, so for all practical purposes the only number you need to worry about is the number in parenthesis.

To improve this percentage, you would need to set cachefu to allow EP to serve cached items without validating them. In general this is done either by specifying a "max-age" or an expires date in the future (ensuring that the content item will never expire). You can increase the value of max-age to increase the amount of time necessary to pass before the browser will revalidate it.

For more information about how EP validates and caches things, see Caching Goals and Strategies.

Made a mistake? Purging Cached Content will prevent the person's browser from relying on a cached version of content on Enfold Proxy. Doing this is helpful for testing your cache settings.

Caching Error Pages

It is possible to configure Enfold Proxy to cache certain non-200 pages from Plone. This could be useful if you wish for Enfold Proxy to cache 404 "Not Found" pages or 301/302 redirect pages. Suppose for example a URL is to be permanently redirected to another page. By allowing Enfold Proxy to cache the 301 message, Enfold Proxy could handle this directly instead of having to check with Plone each time about it.

To enable this feature,

  1. Arrange for Plone to send a page with a cache header of 404/301/302. (You probably will need to do this programmatically in a Plone template or with a python script in Plone to make this happen). The cache headers should indicate that the page is cachable and how long the page is to be considered fresh. (Read more about cache headers).
  2. Open EP configuration tool.
  3. Select your proxy definition. Select the Advanced Caching tab.
  4. Check the box for Allow error pages to be cached.

Here are a few things to keep in mind.

  • You need to set a reasonable age for the item to be cached. Unless you do that, surfers might see cached error pages instead of the current content.
  • You can always purge the cache in the event of misconfiguration.

The cache directory

The proxy allows you to configure the directory where cached items are stored for a particular proxy definition.

  1. Open EP configuration tool
  2. Select your proxy definition. Select the Caching tab.
  3. Leave this blank if you want your cache directory to exist under the application directory. The directory will be created if it does not exist. If you wish to put your cache files elsewhere, you should copy the complete path to the directory here (e.g., C:\My Documents\proxy definition 1\cache).

Important: IIS must be restarted before a change to this option will take effect.

When you change the cache_directory, the old cache is not migrated to the new location (i.e., the old cache remains and a new empty cache is created at the new location.)

Migrating your cache to a different place:

  1. Stop IIS.
  2. Move the cache directory into a new location.
  3. Copy the absolute path into the Cache Directory field of your proxy definition. Press the Save button.
  4. restart IIS.

After you press Save, Enfold Proxy will make the cache directory writable by the user running Enfold Proxy.

IIS6 Considerations

For normal operation, the Enfold Proxy process requires access to the logs and cache directories. The Network Service account under IIS6 does not have this permission. Even if Enfold Proxy has no access to these directories it will still run as a proxy - although no logging information will be written, and it will not operate as a cache.

The Enfold Proxy configuration tool attempts to ensure that directory permissions are set appropriately, but depending on local policies, this may not be effective. It may be necessary to manually configure the IIS application pool or the permissions on the directories to enable these facilities.