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.

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.

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.

• 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).

• 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 www.originalfunsite.com
• 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 www.originalfunsite.com .

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

Next Step: Verify that Your Cache Settings are in Effect

To verify that caching is taking place, look for this line in your HTTP response header: X-Cache: HIT from www.originalfunsite.com

• If you see X-Cache: HIT, then yes, caching is occurring.
• If you see X-Cache: MISS, then this particular item was NOT cached.

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 http://www.originalfunsite.com/events ). In Chasseur, the maximum age is

Cache-Control: max-age=3600 X-Cache: HIT from www.originalfunsite.com

Optimize Cache Settings and Measure Caching Performance

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.

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.

Default-age=0 will cause EP to store cacheable items in the cache and always check to make sure if it is current before serving cached content to the browser. (This is the default and generally recommended). 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).

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|cache.host 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.

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 the 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.