CacheFilter

The task of the CacheFilter is to keep local copies of frequently accessed documents and thus to reduce the time connected to the network. It performs a similar task as the browser cache, but does not cache content per client but per filter instance. This means that the CacheFilter should only be used for locations that emit static, insensitive content. The goal of the filter is to optimize access to this static content (for example image resources).

The cache filter considers HTTP headers sent by the content provider (Cache-Control HTTP header directive), but does not check possible caching <meta> tags in the HTML content. If the CacheFilter is used on user-specific resources and the content provider does not send a corresponding Cache-Control directive, co-browsing results. This means that one (authenticated) user will see content of another user's session.

The filter can cache to memory or to a file system. In either case, the filter caches no more than (MaxEntries * MaxEntrySize) bytes of data. When the document in the cache reaches the age configured by MaxLifeTime, it becomes invalid and is deleted from the cache.

In case of file system caching:

• The directory FileCache.Rootdirectory must already exist when starting nevisProxy, so that the CacheFilter can create directories in it.
• The parameter FileCache.CleanOnStartup controls whether the cache directory FileCache.Rootdirectory has to be deleted on server startup.

Classname

ch::nevis::isiweb4::filter::cache::CacheFilter

Library

libCacheFilters.so.1

Configuration

CacheType

Type: enum
Possible values: file, memory
Usage Constraints: required
Default: file

Determines the location of the cache, either memory or file system.

FileCache.CleanOnStartup

Type: boolean
Usage Constraints: optional
Default: true

If the server is restarted, the cache in the file system can be cleaned or not.

CacheQuery

Type: boolean
Usage Constraints: optional
Default: false

Set this parameter to true to indicate that GET requests with query parameters should be cached.

IgnoreRequest

Type: boolean
Usage Constraints: optional
Default: true

Request headers (for example Cache-Control: no-cache) can force a cache to override its cache and answer with the response from the original server. If IgnoreRequest is set to true, the cache ignores such request headers.

IgnoreResponse

Type: boolean
Usage Constraints: optional
Default: false

Response headers can indicate whether intermediate servers should cache the response. If IgnoreResponse is set to true, the response is cached. Some clients or content providers try to switch off caching even for mostly static content like images or style sheets. You can limit the load on your content providers by mapping a CacheFilter on your image locations with both Ignore* configurations set to true and a reasonable MaxLifeTime.

MaxEntries

Type: integer
Usage Constraints: optional, scaling
Default: 1000

Defines how many documents can be cached. The directory FileCache.RootDirectory has never more than MaxEntries files in it. The directory FileCache.RootDirectory has to have (MaxEntries * MaxEntrySize) bytes of empty disk space.

MaxEntrySize

Type: integer
Unit: bytes
Usage Constraints: optional, scaling
Default: 1000000

The maximum size of a document to be placed in the cache. Documents bigger than MaxEntrySize will never be cached. For the CacheType file, the cache directory requires MaxEntrySize * MaxEntries of free disk space.

MaxLifeTime

Type: integer
Unit: seconds
Usage Constraints: optional, scaling
Default: 3600

The maximum duration to cache a document. A document is never cached longer than MaxLifeTime, so updates on cached document will show after at least this time.

InheritMaxAge

Type: boolean
Usage Constraints: optional
Default: false

If set to true, we take the Cache-Control: max-age header from the backend to set the caching life time. If there is no Cache-Control: max-age, we fall back to the value set by MaxLifeTime.

MaxURILen

Type: integer
Usage Constraints: optional, advanced, min: 10, max: 1000
Default: 500

The URI is used as a key for a lookup table to find the requested page. The MaxURILen is used to calculate the memory size of the lookup table. Should not be changed.

FileCache.RootDirectory

Type: string
Usage Constraints: optional, basic
Default: <spooldir>/cache

The directory in which cache files are stored. The default directory is created when creating a new instance. When using a custom location, the directory must be created before starting nevisProxy. The directory must be readable and writable by the user starting nevisProxy, and it must be unique for every configured CacheFilter.

Note for nevisAdmin 4 users

The CacheFilter can be configured with a Generic Application Settings or a Generic Virtual Host Settings pattern. However the default FileCache.RootDirectory is not created automatically, thus one has to create a directory, or use an existing one.

There are two main options:

• If you have a single CacheFilter in your instance, you can use the /var/opt/nevisproxy/<instance>/run/ directory for the FileCache.RootDirectory, as it is automatically created.
• If you have several CacheFilters in your instance, or if you want to use a custom location for FileCache.RootDirectory, use a Generic Deployment pattern to create the necessary directories.

SuppressRequestHeader

Type: string
Usage Constraints: optional

A newline- or whitespace-separated list of HTTP request headers that will not be sent to the content provider. A typical example is If-Modified-Since.

CacheCookieRules

Type: string
Syntax: <PCRE RegExp for the Cookie name>:<PCRE RegExp for the Cookie value>:NOCACHE|CACHE[:LOG|SILENT] Usage Constraints: optional
Default: .*:.*:NOCACHE

The parameter is a newline separated list of rules of cookie caching. The NOCACHE|CACHE cache action part defines whether the cookie has to be cached, the LOG|SILENT log action part defines whether a log line should be traced for the action. The log action part is optional. The default is SILENT if NOCACHE is configured, and LOG if CACHE is configured.

Possible security breach

The CacheFilter is intended to be used only for static content. Serious security breaches can happen if a session cookie is cached and given to the subsequent user because she/he visits the same URL. However, under special circumstances you might want to cache some cookies like the language cookie.

Example of a CacheFilter using the file system to store cached files

<filter>
  <filter-name>SampleCacheFilter</filter-name>
  <filter-class>ch::nevis::isiweb4::filter::cache::CacheFilter</filter-class>
  <init-param>
    <param-name>FileCache.CleanOnStartup</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>IgnoreRequest</param-name>
    <param-value>true</param-value>
  </init-param>
  <init-param>
    <param-name>MaxLifeTime</param-name>
    <param-value>30</param-value>
  </init-param>
  <init-param>
    <param-name>FileCache.RootDirectory</param-name>
    <param-value>/var/opt/nevisproxy/default/cache</param-value>
  </init-param>
  <init-param>
    <param-name>MaxEntries</param-name>
    <param-value>100</param-value>
  </init-param>
  <init-param>
    <param-name>MaxEntrySize</param-name>
    <param-value>100000</param-value>
  </init-param>
  <init-param>
    <param-name>IgnoreResponse</param-name>
    <param-value>false</param-value>
  </init-param>
  <init-param>
    <param-name>IgnoreRequest</param-name>
    <param-value>false</param-value>
  </init-param>
  <init-param>
    <param-name>CacheQuery</param-name>
    <param-value>false</param-value>
  </init-param>
</filter>