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 [bytes]

• Usage Constraints: optional, scaling

• Default: 1000000

• The maximum size (in bytes) 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 [sec]
• 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

• Usage Constraints: optional

• Default: .*:.*:NOCACHE

• The parameter is a newline separated list of rules with the following syntax:
  <PCRE RegExp for the Cookie name>:<PCRE RegExp for the Cookie value>:NOCACHE|CACHE[:LOG|SILENT]

  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>